feat!: add static/dynamic context (#171)

Signed-off-by: Todd Baert <[email protected]>
Co-authored-by: Skye Gill <[email protected]>
Co-authored-by: Justin Abrahms <[email protected]>
Co-authored-by: Pete Hodgson <[email protected]>
Co-authored-by: Jonathan Norris <[email protected]>
Co-authored-by: Kavindu Dodanduwa <[email protected]>

Author: 6 people

specification.json

@@ -22,6 +22,8 @@ This document defines some terms that are used across this specification.
   - [Library Author](#library-author)
 - [Common](#common)
   - [Feature Flag SDK](#feature-flag-sdk)
+  - [Client-Side SDK](#client-side-sdk)
+  - [Server-Side SDK](#server-side-sdk)
   - [Feature Flag API](#feature-flag-api)
   - [Evaluation API](#evaluation-api)
   - [Flag Management System](#flag-management-system)
@@ -39,6 +41,9 @@ This document defines some terms that are used across this specification.
   - [Targeting Key](#targeting-key)
   - [Fractional Evaluation](#fractional-evaluation)
   - [Rule](#rule)
+- [SDK Paradigms](#sdk-paradigms)
+  - [Dynamic-Context Paradigm](#dynamic-context-paradigm)
+  - [Static-Context Paradigm](#static-context-paradigm)
 
 <!-- tocstop -->
 
@@ -76,6 +81,14 @@ The maintainer of a shared library which is a dependency of many applications or
 
 The libraries used by the Application Author to implement feature flags in their application or service. The interfaces defined in these libraries adhere to the Feature Flag API.
 
+### Client-Side SDK
+
+An SDK which is built for usage in client applications (e.g. single-page web applications), and typically uses the [static-context paradigm](#static-context-paradigm).
+
+### Server-Side SDK
+
+An SDK which is built for usage in server applications (e.g. REST services), and typically uses the [dynamic-context paradigm](#dynamic-context-paradigm).
+
 ### Feature Flag API
 
 The interfaces and abstractions used by authors (Application, Integration, Provider).
@@ -163,3 +176,25 @@ Pseudorandomly resolve flag values using a context property, such as a targeting
 ### Rule
 
 A rule is some criteria that's used to determine which variant a particular context should be mapped to.
+
+## SDK Paradigms
+
+Feature flag frameworks have SDKs which operate in two distinct paradigms: those designed for use with a single user client application (e.g. mobile phones, single-page web apps), and those designed for multi-user applications, such as web server applications. Some parts of the OpenFeature specification diverge depending on the paradigm.
+
+### Dynamic-Context Paradigm
+
+Server-side applications typically perform flag evaluations on behalf of many users, with each request or event being associated with a particular user or client. For this reason, server frameworks typically operate similarly to this:
+
+- the application is initialized with some static context (geography, service name, hostname, etc)
+- with each request or event, relevant dynamic context (for example, user session data, unique user identifiers) is provided to flag evaluations
+
+### Static-Context Paradigm
+
+In contrast to server-side or other service-type applications, client side applications typically operate in the context of a single user. Most feature flagging libraries for these applications have been designed with this in mind. Frequently, client/web libraries operate similarly to this:
+
+- an initialization occurs, which fetches evaluated flags in bulk for a given context (user)
+- the evaluated flags are cached in the library
+- flag evaluations take place against this cache, without a need to provide context (context was already used to evaluate flags in bulk)
+- libraries provide a mechanism to update context (e.g. if a user logs in), meaning cached evaluations are no longer valid and must be re-evaluated, frequently involving a network request or I/O operation
+
+Not all client libraries work this way, but generally, libraries that accept dynamic context per evaluation can build providers which conform to this model with relative ease, while the reverse is not true.

specification/glossary.md

@@ -130,7 +130,13 @@ client.getMetadata().getName(); // "my-client"
 
 [![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
-#### Requirement 1.3.1
+#### Condition 1.3.1
+
+> The implementation uses the dynamic-context paradigm.
+
+see: [dynamic-context paradigm](../glossary.md#dynamic-context-paradigm)
+
+##### Conditional Requirement 1.3.1.1
 
 > The `client` **MUST** provide methods for typed flag evaluation, including boolean, numeric, string, and structure, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), `evaluation context` (optional), and `evaluation options` (optional), which returns the flag value.
 
@@ -152,10 +158,37 @@ See [evaluation context](./03-evaluation-context.md) for details.
 
 #### Condition 1.3.2
 
-> The implementation language differentiates between floating-point numbers and integers.
+[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+
+> The implementation uses the static-context paradigm.
+
+see: [static-context paradigm](../glossary.md#static-context-paradigm)
 
 ##### Conditional Requirement 1.3.2.1
 
+> The `client` **MUST** provide methods for typed flag evaluation, including boolean, numeric, string, and structure, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), and `evaluation options` (optional), which returns the flag value.
+
+```typescript
+// example boolean flag evaluation
+boolean myBool =  client.getBooleanValue('bool-flag', false);
+
+// example overloaded string flag evaluation with optional params
+string myString = client.getStringValue('string-flag', 'N/A', options);
+
+// example number flag evaluation
+number myNumber = client.getNumberValue('number-flag', 75);
+
+// example overloaded structure flag evaluation with optional params
+MyStruct myStruct = client.getObjectValue<MyStruct>('structured-flag', { text: 'N/A', percentage: 75 }, options);
+```
+
+
+#### Condition 1.3.3
+
+> The implementation language differentiates between floating-point numbers and integers.
+
+##### Conditional Requirement 1.3.3.1
+
 > The client **SHOULD** provide functions for floating-point numbers and integers, consistent with language idioms.
 
 ```java
@@ -166,15 +199,21 @@ long getFloatValue(String flag, long defaultValue);
 
 See [types](../types.md) for details.
 
-#### Requirement 1.3.3
+#### Requirement 1.3.4
 
 > The `client` **SHOULD** guarantee the returned value of any typed flag evaluation method is of the expected type. If the value returned by the underlying provider implementation does not match the expected type, it's to be considered abnormal execution, and the supplied `default value` should be returned.
 
 ### 1.4. Detailed Flag Evaluation
 
 [![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
-#### Requirement 1.4.1
+#### Condition 1.4.1
+
+> The implementation uses the dynamic-context paradigm.
+
+see: [dynamic-context paradigm](../glossary.md#dynamic-context-paradigm)
+
+##### Conditional Requirement 1.4.1.1
 
 > The `client` **MUST** provide methods for detailed flag value evaluation with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), `evaluation context` (optional), and `evaluation options` (optional), which returns an `evaluation details` structure.
 
@@ -193,69 +232,96 @@ FlagEvaluationDetails<MyStruct> myStructDetails = client.getObjectDetails<MyStru
 
 ```
 
-#### Requirement 1.4.2
+#### Condition 1.4.2
+
+[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+
+> The implementation uses the static-context paradigm.
+
+see: [static-context paradigm](../glossary.md#static-context-paradigm)
+
+##### Conditional Requirement 1.4.2.1
+
+> The `client` **MUST** provide methods for detailed flag value evaluation with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), and `evaluation options` (optional), which returns an `evaluation details` structure.
+
+```typescript
+// example detailed boolean flag evaluation
+FlagEvaluationDetails<boolean> myBoolDetails = client.getBooleanDetails('bool-flag', false);
+
+// example detailed string flag evaluation
+FlagEvaluationDetails<string> myStringDetails = client.getStringDetails('string-flag', 'N/A', options);
+
+// example detailed number flag evaluation
+FlagEvaluationDetails<number> myNumberDetails = client.getNumberDetails('number-flag', 75);
+
+// example detailed structure flag evaluation
+FlagEvaluationDetails<MyStruct> myStructDetails = client.getObjectDetails<MyStruct>('structured-flag', { text: 'N/A', percentage: 75 }, options);
+
+```
+
+#### Requirement 1.4.3
 
 > The `evaluation details` structure's `value` field **MUST** contain the evaluated flag value.
 
-#### Condition 1.4.3
+#### Condition 1.4.4
 
 > The language supports generics (or an equivalent feature).
 
-##### Conditional Requirement 1.4.3.1
+##### Conditional Requirement 1.4.4.1
 
 > The `evaluation details` structure **SHOULD** accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field.
 
-#### Requirement 1.4.4
+#### Requirement 1.4.5
 
 > The `evaluation details` structure's `flag key` field **MUST** contain the `flag key` argument passed to the detailed flag evaluation method.
 
-#### Requirement 1.4.5
+#### Requirement 1.4.6
 
 > In cases of normal execution, the `evaluation details` structure's `variant` field **MUST** contain the value of the `variant` field in the `flag resolution` structure returned by the configured `provider`, if the field is set.
 
-#### Requirement 1.4.6
+#### Requirement 1.4.7
 
 > In cases of normal execution, the `evaluation details` structure's `reason` field **MUST** contain the value of the `reason` field in the `flag resolution` structure returned by the configured `provider`, if the field is set.
 
-#### Requirement 1.4.7
+#### Requirement 1.4.8
 
 > In cases of abnormal execution, the `evaluation details` structure's `error code` field **MUST** contain an `error code`.
 
 See [error code](../types.md#error-code) for details.
 
-#### Requirement 1.4.8
+#### Requirement 1.4.9
 
 > In cases of abnormal execution (network failure, unhandled error, etc) the `reason` field in the `evaluation details` **SHOULD** indicate an error.
 
-#### Requirement 1.4.9
+#### Requirement 1.4.10
 
 > Methods, functions, or operations on the client **MUST NOT** throw exceptions, or otherwise abnormally terminate. Flag evaluation calls must always return the `default value` in the event of abnormal execution. Exceptions include functions or methods for the purposes for configuration or setup.
 
 Configuration code includes code to set the provider, instantiate providers, and configure the global API object.
 
-#### Requirement 1.4.10
+#### Requirement 1.4.11
 
 > In the case of abnormal execution, the client **SHOULD** log an informative error message.
 
 Implementations may define a standard logging interface that can be supplied as an optional argument to the client creation function, which may wrap standard logging functionality of the implementation language.
 
-#### Requirement 1.4.11
+#### Requirement 1.4.12
 
 > The `client` **SHOULD** provide asynchronous or non-blocking mechanisms for flag evaluation.
 
 It's recommended to provide non-blocking mechanisms for flag evaluation, particularly in languages or environments wherein there's a single thread of execution.
 
-#### Requirement 1.4.12
+#### Requirement 1.4.13
 
 > In cases of abnormal execution, the `evaluation details` structure's `error message` field **MAY** contain a string containing additional details about the nature of the error.
 
-#### Requirement 1.4.13
+#### Requirement 1.4.14
 
 > If the `flag metadata` field in the `flag resolution` structure returned by the configured `provider` is set, the `evaluation details` structure's `flag metadata` field **MUST** contain that value. Otherwise, it **MUST** contain an empty record.
 
 This `flag metadata` field is intended as a mechanism for providers to surface additional information about a feature flag (or its evaluation) beyond what is defined within the OpenFeature spec itself. The primary consumer of this information is a provider-specific hook.
 
-#### Condition 1.4.14
+#### Condition 1.4.15
 
 > The implementation language supports a mechanism for marking data as immutable.
 

specification/sections/01-flag-evaluation.md

@@ -77,7 +77,7 @@ The value of the variant field might only be meaningful in the context of the fl
 
 #### Requirement 2.2.5
 
-> The `provider` **SHOULD** populate the `resolution details` structure's `reason` field with `"STATIC"`, `"DEFAULT",` `"TARGETING_MATCH"`, `"SPLIT"`, `"CACHED"`, `"DISABLED"`, `"UNKNOWN"`, `"ERROR"` or some other string indicating the semantic reason for the returned flag value.
+> The `provider` **SHOULD** populate the `resolution details` structure's `reason` field with `"STATIC"`, `"DEFAULT",` `"TARGETING_MATCH"`, `"SPLIT"`, `"CACHED"`, `"DISABLED"`, `"UNKNOWN"`, `"STALE"`, `"ERROR"` or some other string indicating the semantic reason for the returned flag value.
 
 As indicated in the definition of the [`resolution details`](../types.md#resolution-details) structure, the `reason` should be a string. This allows providers to reflect accurately why a flag was resolved to a particular value.
 
@@ -245,6 +245,30 @@ class MyProvider implements Provider, AutoDisposable {
   void dispose() {
     // close connections, terminate threads or timers, etc...
   }
+```
+
+### 2.6. Provider context reconciliation
+
+[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+
+Static-context focused providers may need a mechanism to understand when their cache of evaluated flags must be invalidated or updated. An `on context changed` handler can be defined which performs whatever operations are needed to reconcile the evaluated flags with the new context.
+
+#### Requirement 2.6.1
+
+> The provider **MAY** define an `on context changed` handler, which takes an argument for the previous context and the newly set context, in order to respond to an evaluation context change.
+
+Especially in static-context implementations, providers and underlying SDKs may maintain state for a particular context.
+The `on context changed` handler provides a mechanism to update this state, often by re-evaluating flags in bulk with respect to the new context.
+
+```java
+// MyProvider implementation of the onContextChanged function defined in Provider
+class MyProvider implements Provider {
+  //...
+
+  onContextChanged(EvaluationContext oldContext, EvaluationContext newContext): void {
+    // update context-sensitive cached flags, or otherwise react to the change in the global context 
+  }
+
   //...
 }
 ```

specification/sections/02-providers.md

@@ -44,13 +44,39 @@ The key uniquely identifies a field in the `evaluation context` and it should be
 
 ### 3.2 Context levels and merging
 
-#### Requirement 3.2.1
+#### Condition 3.2.1
+
+> The implementation uses the dynamic-context paradigm.
+
+see: [dynamic-context paradigm](../glossary.md#dynamic-context-paradigm)
+
+##### Conditional Requirement 3.2.1.1
 
 > The API, Client and invocation **MUST** have a method for supplying `evaluation context`.
 
 API (global) `evaluation context` can be used to supply static data to flag evaluation, such as an application identifier, compute region, or hostname. Client and invocation `evaluation context` are ideal for dynamic data, such as end-user attributes.
 
-#### Requirement 3.2.2
+#### Condition 3.2.2
+
+[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+
+> The implementation uses the static-context paradigm.
+
+see: [static-context paradigm](../glossary.md#static-context-paradigm)
+
+##### Conditional Requirement 3.2.2.1
+
+> The API **MUST** have a method for setting the global `evaluation context`.
+
+API (global) `evaluation context` can be used to supply data to flag evaluation, such as (but not limited to) user name, email, or user organization membership changes.
+
+##### Conditional Requirement 3.2.2.2
+
+> The Client and invocation **MUST NOT** have a method for supplying `evaluation context`.
+
+In the static-context paradigm, context is global. The client and invocation cannot supply evaluation context. 
+
+#### Requirement 3.2.3
 
 > Evaluation context **MUST** be merged in the order: API (global; lowest precedence) -> client -> invocation -> before hooks (highest precedence), with duplicate values being overwritten.
 
@@ -66,3 +92,17 @@ flowchart LR
   client --> invocation
   invocation --> hook
 ```
+
+#### Condition 3.2.4
+
+[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+
+> The implementation uses the static-context paradigm.
+
+see: [static-context paradigm](../glossary.md#static-context-paradigm)
+
+##### Requirement 3.2.4.1
+
+> When the global `evaluation context` is set, the `on context changed` handler **MUST** run.
+
+The SDK implementation must run the `on context changed` handler on the registered provider whenever the global `evaluation context` is mutated.