Skip to content

Commit

Permalink
chore: various doc fixes (#942)
Browse files Browse the repository at this point in the history 
* fixes some links
* adds bit about required version for `fractional`
* adds bit about multiple fs events, symlinks
* adds blurb about HTTP2 being blocked in some environments

Fixes: #894
Fixes: #479
Fixes: #362

---------

Signed-off-by: Todd Baert <[email protected]>
Co-authored-by: Michael Beemer <[email protected]>
  • Loading branch information
@toddbaert @beeme1mr
toddbaert and beeme1mr authored Sep 28, 2023
1 parent 745c29f commit 6d9aecd
Show file tree
Hide file tree
Showing 3 changed files with 36 additions and 13 deletions.
2 changes: 1 addition & 1 deletion docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ With flagd you can:
* aggregate flag definitions from multiple sources

It doesn't include a UI, management console or a persistence layer.
It's configurable entirely via a POSIX-style CLI.
It's configurable entirely via a [POSIX-style CLI](./reference/flagd-cli/flagd.md).
Thanks to it's minimalism, it's _extremely flexible_; you can leverage flagd as a sidecar alongside your application, an engine running in your application process, or as a central service evaluating thousands of flags per second.

## How do I deploy flagd?
Expand Down
24 changes: 12 additions & 12 deletions docs/reference/flag-definitions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -163,8 +163,8 @@ For example, when accessing flagd via HTTP, the POST body may look like this:

The evaluation context can be accessed in targeting rules using the `var` operation followed the evaluation context property name.

| Description | Example |
| -------------------------------------------------------------- | --------------------------------------------- |
| Description | Example |
| -------------------------------------------------------------- | ---------------------------------------------------- |
| Retrieve property from the evaluation context | `#!json { "var": "email" }` |
| Retrieve property from the evaluation context or use a default | `#!json { "var": ["email", "[email protected]"] }` |
| Retrieve a nested property from the evaluation context | `#!json { "var": "user.email" }` |
Expand All @@ -175,8 +175,8 @@ The evaluation context can be accessed in targeting rules using the `var` operat

Conditions can be used to control the logical flow and grouping of targeting rules.

| Conditional | Example |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Conditional | Example |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| If | Logic: `#!json {"if" : [ true, "yes", "no" ]}`<br>Result: `"yes"`<br><br>Logic: `#!json {"if" : [ false, "yes", "no" ]}`<br>Result: `"no"` |
| If else | Logic: `#!json {"if" : [ false, "yes", false, "no", "maybe" ]}`<br>Result: `"maybe"`<br><br>Logic: `#!json {"if" : [ false, "yes", false, "no", false, "maybe", "who knows" ]}`<br>Result: `"who knows"` |
| Or | Logic: `#!json {"or" : [ true, false ]}`<br>Result: `true`<br><br>Logic: `#!json {"or" : [ false, false ]}`<br>Result: `false` |
Expand All @@ -187,8 +187,8 @@ Conditions can be used to control the logical flow and grouping of targeting rul
Operations are used to take action on, or compare properties retrieved from the context.
These are provided out-of-the-box by JsonLogic.

| Operator | Description | Context type | Example |
| ---------------------- | -------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operator | Description | Context type | Example |
| ---------------------- | -------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Equals | Attribute equals the specified value, with type coercion. | any | Logic: `#!json { "==" : [1, 1] }`<br>Result: `true`<br><br>Logic: `#!json { "==" : [1, "1"] }`<br>Result: `true` |
| Strict equals | Attribute equals the specified value, with strict comparison. | any | Logic: `#!json { "===" : [1, 1] }`<br>Result: `true`<br><br>Logic: `#!json { "===" : [1, "1"] }`<br>Result: `false` |
| Not equals | Attribute doesn't equal the specified value, with type coercion. | any | Logic: `#!json { "!=" : [1, 2] }`<br>Result: `true`<br><br>Logic: `#!json { "!=" : [1, "1"] }`<br>Result: `false` |
Expand All @@ -211,12 +211,12 @@ These are provided out-of-the-box by JsonLogic.
These are custom operations specific to flagd and flagd providers.
They are purpose built extensions to JsonLogic in order to support common feature flag use cases.

| Function | Description | Example |
| ------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fractional` | Deterministic, pseudorandom fractional distribution | Logic: `#!json { "fractional" : [ { "var": "email" }, [ "red" , 50], [ "green" , 50 ] ] }` <br>Result: Pseudo randomly `red` or `green` based on the evaluation context property `email`.<br><br>Additional documentation can be found [here](./custom-operations/fractional.md) |
| `starts_with` | Attribute starts with the specified value | Logic: `#!json { "starts_with" : [ "192.168.0.1", "192.168"] }`<br>Result: `true`<br><br>Logic: `#!json { "starts_with" : [ "10.0.0.1", "192.168"] }`<br>Result: `false`<br>Additional documentation can be found [here](./custom-operations/string-comparision.md) |
| `ends_with` | Attribute ends with the specified value | Logic: `#!json { "ends_with" : [ "[email protected]", "@example.com"] }`<br>Result: `true`<br><br>Logic: `#!json { ends_with" : [ "[email protected]", "@test.com"] }`<br>Result: `false`<br>Additional documentation can be found [here](./custom-operations/string-comparision.md) |
| `sem_ver` | Attribute matches a semantic versioning condition | Logic: `#!json {"sem_ver": ["1.1.2", ">=", "1.0.0"]}`<br>Result: `true`<br><br>Additional documentation can be found [here](./custom-operations/semver-comparison.md) |
| Function | Description | Example |
| ---------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fractional` (_available v0.6.4+_) | Deterministic, pseudorandom fractional distribution | Logic: `#!json { "fractional" : [ { "var": "email" }, [ "red" , 50], [ "green" , 50 ] ] }` <br>Result: Pseudo randomly `red` or `green` based on the evaluation context property `email`.<br><br>Additional documentation can be found [here](./custom-operations/fractional-operation.md) |
| `starts_with` | Attribute starts with the specified value | Logic: `#!json { "starts_with" : [ "192.168.0.1", "192.168"] }`<br>Result: `true`<br><br>Logic: `#!json { "starts_with" : [ "10.0.0.1", "192.168"] }`<br>Result: `false`<br>Additional documentation can be found [here](./custom-operations/string-comparison-operation.md) |
| `ends_with` | Attribute ends with the specified value | Logic: `#!json { "ends_with" : [ "[email protected]", "@example.com"] }`<br>Result: `true`<br><br>Logic: `#!json { ends_with" : [ "[email protected]", "@test.com"] }`<br>Result: `false`<br>Additional documentation can be found [here](./custom-operations/string-comparison-operation.md) |
| `sem_ver` | Attribute matches a semantic versioning condition | Logic: `#!json {"sem_ver": ["1.1.2", ">=", "1.0.0"]}`<br>Result: `true`<br><br>Additional documentation can be found [here](./custom-operations/semver-operation.md) |

## Shared evaluators

Expand Down
23 changes: 23 additions & 0 deletions docs/troubleshooting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,3 +44,26 @@ Result:
```sh
{"value":1.23,"reason":"DEFAULT","variant":"one"}
```

---

## Extra/Duplicate Events in File Syncs

When using the file sync, you may notice more events than you'd expect.
This is attributable to nuances in text editors and the OS/filesystem.
Most editors will cause a few filesystem events on a save, for instance, not just one as you might expect.
Additionally, most filesystem operations are not atomic and also will result in multiple events.
Generally speaking, updating a symbolic link will result in only a single event, and may even be atomic on your filesystem/OS.
In fact, this is how Kubernetes handles changes to mounted ConfigMaps (OpenFeature Operator takes advantage of this fact in it's `file` mode).
**It's recommended if you're using the file sync in production, you use a symbolic link for the watched file, and update its contents by changing its target.**

---

## Received unexpected EOS on empty DATA frame from server

This error message indicates that HTTP2 requests are being blocked (gRPC runs over HTTP2).
You may need to explicitly allow HTTP2 or gRPC in your platform if you're using the [sync gRPC service](./reference/specifications/protos.md#syncv1sync_serviceproto).

!!! note

HTTP2 _is not_ strictly for the flag [evaluation gRPC service](./reference/specifications/protos.md#schemav1schemaproto), which is exposed both as a gRPC service and a RESTful HTTP/1.1 service, thanks to the [connect protocol](https://connectrpc.com/docs/protocol/).

0 comments on commit 6d9aecd

Please sign in to comment.