From fe7c0b3cb55c624ce4c033dbb4533081e9bf7422 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Thu, 8 Sep 2022 12:04:11 -0400 Subject: [PATCH 1/3] Adding details on context and merging Signed-off-by: Todd Baert --- .../concepts/03-evaluation-context.mdx | 61 ++++++++++++++++--- 1 file changed, 53 insertions(+), 8 deletions(-) diff --git a/docs/reference/concepts/03-evaluation-context.mdx b/docs/reference/concepts/03-evaluation-context.mdx index 25702aab..0145eda5 100644 --- a/docs/reference/concepts/03-evaluation-context.mdx +++ b/docs/reference/concepts/03-evaluation-context.mdx @@ -8,21 +8,26 @@ import TabItem from '@theme/TabItem'; # Evaluation Context -The _evaluation context_ is a container for arbitrary contextual data that can be used as a basis for dynamic evaluation. Static data such as the host or an identifier for the application can be configured globally. Dynamic evaluation context, such as the IP address of the client in a web application, can be implicitly propagated or explicitly passed to during flag evaluation, and can be merged with static values. +The [_evaluation context_](/docs/specification/glossary#evaluation-context) is a container for arbitrary contextual data that can be used as a basis for dynamic evaluation. Static data such as the host or an identifier for the application can be configured globally. Dynamic evaluation context, such as the IP address of the client in a web application, can be implicitly propagated or explicitly passed to during flag evaluation, and can be merged with static values. ## Providing Evaluation Context - - -Values relevant for flag evaluation can be included in the evaluation context. +Values relevant for flag evaluation can be included in the evaluation context at multiple points: globally (on the top level API), on the client, and at the point of flag evaluation (invocation). ```ts +// add a value to the global context +OpenFeature.context = { myGlobalKey: 'myGlobalValue' } + +// add a value to the client context +const client = OpenFeature.getClient(); +client.context = { myClientKey: 'myClientValue' } + // add a value to the invocation context const context: EvaluationContext = { - myKey: 'myValue', + myInvocationKey: 'myInvocationValue', }; const boolValue = await client.getBooleanValue('boolFlag', false, context); ``` @@ -31,9 +36,17 @@ const boolValue = await client.getBooleanValue('boolFlag', false, context); ```java +// add a value to the global context +OpenFeatureAPI api = OpenFeatureAPI.getInstance(); +api.setEvaluationContext(new EvaluationContext().add("myGlobalKey", "myGlobalValue")); + +// add a value to the client context +Client client = api.getClient(); +client.setEvaluationContext(new EvaluationContext().add("myClientKey", "myClientValue")); + // add a value to the invocation context EvaluationContext context = new EvaluationContext(); -context.addStringAttribute("myKey", "myValue") +context.addStringAttribute("myInvocationKey", "myInvocationValue") Boolean boolValue = client.getBooleanValue("boolFlag", false, context); ``` @@ -41,9 +54,17 @@ Boolean boolValue = client.getBooleanValue("boolFlag", false, context); ```csharp +// add a value to the global context +OpenFeature api = OpenFeature.Instance; +api.SetContext(new EvaluationContext().Add("myGlobalKey", "myGlobalValue")); + +// add a value to the client context +FeatureClient client = api.GetClient(); +api.SetContext(new EvaluationContext().Add("myClientKey", "myClientValue")); + // add a value to the invocation context var context = new EvaluationContext(); -context.Add("myKey", "myValue"); +context.Add("myInvocationKey", "myInvocationValue"); var boolValue = await client.GetBooleanValue("boolFlag", false, context); ``` @@ -51,10 +72,26 @@ var boolValue = await client.GetBooleanValue("boolFlag", false, context); ```go + +// add a value to the global context +SetEvaluationContext(EvaluationContext{ + Attributes: map[string]interface{}{ + "myGlobalKey": "myGlobalValue", + }, +}) + +// add a value to the client context +client := NewClient("my-app") +client.SetEvaluationContext(EvaluationContext{ + Attributes: map[string]interface{}{ + "myClientKey": "myClientValue", + }, +}) + // add a value to the invocation context ctx := openfeature.EvaluationContext{ Attributes: map[string]interface{}{ - "myKey": "myValue", + "myInvocationKey": "myInvocationValue", }, } boolValue, err := client.BooleanValue("boolFlag", false, ctx, openfeature.EvaluationOptions{}) @@ -63,6 +100,14 @@ boolValue, err := client.BooleanValue("boolFlag", false, ctx, openfeature.Evalua +### Context merging + +At the point of flag evaluation, the evaluation context is merged, and duplicate values are overwritten as defined in the [specification](/docs/specification/sections/evaluation-context#merging-context). + +### Circular structures in Evaluation Context + +Many providers serialize the evaluation context as part of their operation. Be careful not to include Circular structures in the evaluation context to avoid serialization issues. + ## Targeting Key Many feature flag management systems require an identifier for the subject of flag evaluation. For many feature flag systems this is required in order to perform fractional evaluation or percentage-based rollouts deterministically. In the case of web applications or mobile apps, the subject is frequently an end user, but in other cases it could be a service or client application. The `evaluation context` includes an optional `targeting key` field for this purpose. The targeting key should contain a string uniquely identifying the subject (i.e.: a UUID, a hash of some user attribute such as an email, or a the hostname of an application or service). Some providers may require this field to be set to function correctly. From fbb35a6a4e64aec1dba2ae494c3aa7c8759a6eed Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Thu, 8 Sep 2022 12:32:07 -0400 Subject: [PATCH 2/3] fix capitalization Signed-off-by: Todd Baert --- docs/reference/concepts/03-evaluation-context.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/concepts/03-evaluation-context.mdx b/docs/reference/concepts/03-evaluation-context.mdx index 0145eda5..9835395b 100644 --- a/docs/reference/concepts/03-evaluation-context.mdx +++ b/docs/reference/concepts/03-evaluation-context.mdx @@ -106,7 +106,7 @@ At the point of flag evaluation, the evaluation context is merged, and duplicate ### Circular structures in Evaluation Context -Many providers serialize the evaluation context as part of their operation. Be careful not to include Circular structures in the evaluation context to avoid serialization issues. +Many providers serialize the evaluation context as part of their operation. Be careful not to include circular structures in the evaluation context to avoid serialization issues. ## Targeting Key From e74351ca8c09b5d2c4a95d965adf5dd3b5c14280 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Thu, 8 Sep 2022 13:04:08 -0400 Subject: [PATCH 3/3] Add provider links Signed-off-by: Todd Baert --- docs/reference/concepts/03-evaluation-context.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/concepts/03-evaluation-context.mdx b/docs/reference/concepts/03-evaluation-context.mdx index 9835395b..f265f7e5 100644 --- a/docs/reference/concepts/03-evaluation-context.mdx +++ b/docs/reference/concepts/03-evaluation-context.mdx @@ -110,8 +110,8 @@ Many providers serialize the evaluation context as part of their operation. Be c ## Targeting Key -Many feature flag management systems require an identifier for the subject of flag evaluation. For many feature flag systems this is required in order to perform fractional evaluation or percentage-based rollouts deterministically. In the case of web applications or mobile apps, the subject is frequently an end user, but in other cases it could be a service or client application. The `evaluation context` includes an optional `targeting key` field for this purpose. The targeting key should contain a string uniquely identifying the subject (i.e.: a UUID, a hash of some user attribute such as an email, or a the hostname of an application or service). Some providers may require this field to be set to function correctly. +Many feature flag management systems require an identifier for the subject of flag evaluation. For many feature flag systems this is required in order to perform fractional evaluation or percentage-based rollouts deterministically. In the case of web applications or mobile apps, the subject is frequently an end user, but in other cases it could be a service or client application. The `evaluation context` includes an optional `targeting key` field for this purpose. The targeting key should contain a string uniquely identifying the subject (i.e.: a UUID, a hash of some user attribute such as an email, or a the hostname of an application or service). Some [providers](/docs/reference/concepts/provider) may require this field to be set to function correctly. ## Personally Identifiable Information (PII) Considerations -Be thoughtful in your inclusion of personal data in the `evaluation context`. Such data is useful for targeting and dynamic evaluation, but you should consider how the provider in use may handle or persist this data. Hooks (specifically hooks implementing the _before_ stage) can be useful to restrict, filter or anonymize data in the `evaluation context`. +Be thoughtful in your inclusion of personal data in the `evaluation context`. Such data is useful for targeting and dynamic evaluation, but you should consider how the [provider](/docs/reference/concepts/provider) in use may handle or persist this data. Hooks (specifically hooks implementing the _before_ stage) can be useful to restrict, filter or anonymize data in the `evaluation context`.