diff --git a/docs/reference/flag-definitions.md b/docs/reference/flag-definitions.md index 9f5ce2502..b667ce167 100644 --- a/docs/reference/flag-definitions.md +++ b/docs/reference/flag-definitions.md @@ -146,7 +146,7 @@ Example of an invalid configuration: `targeting` is an **optional** property. A targeting rule **must** be valid JSON. -Flagd uses a modified version of [JSON Logic](https://jsonlogic.com/), as well as some custom pre-processing, to evaluate these rules. +Flagd uses a modified version of [JsonLogic](https://jsonlogic.com/), as well as some custom pre-processing, to evaluate these rules. The output of the targeting rule **must** match the name of one of the variants defined above. If an invalid or null value is returned by the targeting rule, the `defaultVariant` value is used. If no targeting rules are defined, the response reason will always be `STATIC`, this allows for the flag values to be cached, this behavior is described [here](specifications/rpc-providers.md#caching). @@ -173,7 +173,7 @@ The evaluation context can be accessed in targeting rules using the `var` operat | Retrieve property from the evaluation context or use a default | `#!json { "var": ["email", "noreply@example.com"] }` | | Retrieve a nested property from the evaluation context | `#!json { "var": "user.email" }` | -> For more information, see the `var` section in the [JSON Logic documentation](https://jsonlogic.com/operations.html#var). +> For more information, see the `var` section in the [JsonLogic documentation](https://jsonlogic.com/operations.html#var). #### Conditions @@ -217,10 +217,19 @@ They are purpose built extensions to JsonLogic in order to support common featur | Function | Description | Example | | ---------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `fractional` (_available v0.6.4+_) | Deterministic, pseudorandom fractional distribution | Logic: `#!json { "fractional" : [ { "var": "email" }, [ "red" , 50], [ "green" , 50 ] ] }`
Result: Pseudo randomly `red` or `green` based on the evaluation context property `email`.

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"] }`
Result: `true`

Logic: `#!json { "starts_with" : [ "10.0.0.1", "192.168"] }`
Result: `false`
Additional documentation can be found [here](./custom-operations/string-comparison-operation.md) | -| `ends_with` | Attribute ends with the specified value | Logic: `#!json { "ends_with" : [ "noreply@example.com", "@example.com"] }`
Result: `true`

Logic: `#!json { ends_with" : [ "noreply@example.com", "@test.com"] }`
Result: `false`
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"]}`
Result: `true`

Additional documentation can be found [here](./custom-operations/semver-operation.md) | +| `fractional` (_available v0.6.4+_) | Deterministic, pseudorandom fractional distribution | Logic: `#!json { "fractional" : [ { "var": "email" }, [ "red" , 50], [ "green" , 50 ] ] }`
Result: Pseudo randomly `red` or `green` based on the evaluation context property `email`.

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"] }`
Result: `true`

Logic: `#!json { "starts_with" : [ "10.0.0.1", "192.168"] }`
Result: `false`
Additional documentation can be found [here](./custom-operations/string-comparison-operation.md). | +| `ends_with` | Attribute ends with the specified value | Logic: `#!json { "ends_with" : [ "noreply@example.com", "@example.com"] }`
Result: `true`

Logic: `#!json { ends_with" : [ "noreply@example.com", "@test.com"] }`
Result: `false`
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"]}`
Result: `true`

Additional documentation can be found [here](./custom-operations/semver-operation.md). | + +#### $flagd properties in the evaluation context + +Flagd adds the following properties to the evaluation context that can be used in the targeting rules. + +| Property | Description | From version | +|----------|-------------|--------------| +| `$flagd.flagKey` | the identifier for the flag being evaluated | v0.6.4 | +| `$flagd.timestamp`| a unix timestamp (in seconds) of the time of evaluation | v0.6.7 | ## Shared evaluators diff --git a/docs/reference/specifications/in-process-providers.md b/docs/reference/specifications/in-process-providers.md index 4e3aa45e4..4992657c9 100755 --- a/docs/reference/specifications/in-process-providers.md +++ b/docs/reference/specifications/in-process-providers.md @@ -68,6 +68,7 @@ Note that for the in-process provider only the `sync` package will be relevant, An in-process flagd provider should provide the feature set offered by [JsonLogic](https://jsonlogic.com) to evaluate flag resolution requests for a given context. If available, the JsonLogic library for the chosen technology should be used. +Additionally, it should also provide the custom JsonLogic evaluators and `$flagd` properties in the evaluation context described below. ### Custom JsonLogic evaluators @@ -94,6 +95,16 @@ This evaluator selects a variant based on whether the specified property within starts/ends with a certain string. For more specific implementation guidelines, please refer to [this document](./custom-operations/string-comparison-operation-spec.md). +### $flagd properties in the evaluation context + +An in-process flagd provider should also add the following properties to the JsonLogic evaluation context so that users can use them in their targeting rules. +Conflicting properties in the context will be overwritten by the values below. + +| Property | Description | +|----------|-------------| +| `$flagd.flagKey` | the identifier for the flag being evaluated | +| `$flagd.timestamp`| a unix timestamp (in seconds) of the time of evaluation | + ## Provider construction (**using Go as an example**)