diff --git a/specification.json b/specification.json index ef8cda11..d9f1302c 100644 --- a/specification.json +++ b/specification.json @@ -891,6 +891,35 @@ "content": "Handlers attached after the provider is already in the associated state, MUST run immediately.", "RFC 2119 keyword": "MUST", "children": [] + }, + { + "id": "Condition 5.3.4", + "machine_id": "condition_5_3_4", + "content": "The implementation uses the static-context paradigm.", + "RFC 2119 keyword": null, + "children": [ + { + "id": "Conditional Requirement 5.3.4.1", + "machine_id": "conditional_requirement_5_3_4_1", + "content": "When the provider's `on context changed` is called, the provider MAY emit the `PROVIDER_STALE` event, and transition to the `STALE` state.", + "RFC 2119 keyword": "MAY", + "children": [] + }, + { + "id": "Conditional Requirement 5.3.4.2", + "machine_id": "conditional_requirement_5_3_4_2", + "content": "If the provider's `on context changed` function terminates normally, associated `PROVIDER_CONTEXT_CHANGED` handlers MUST run.", + "RFC 2119 keyword": "MUST", + "children": [] + }, + { + "id": "Conditional Requirement 5.3.4.3", + "machine_id": "conditional_requirement_5_3_4_3", + "content": "If the provider's `on context changed` function terminates abnormally, associated `PROVIDER_ERROR` handlers MUST run.", + "RFC 2119 keyword": "MUST", + "children": [] + } + ] } ] } \ No newline at end of file diff --git a/specification/sections/05-events.md b/specification/sections/05-events.md index 1db44724..48f693af 100644 --- a/specification/sections/05-events.md +++ b/specification/sections/05-events.md @@ -144,3 +144,57 @@ For instance, _application authors_ may attach readiness handlers to be confiden If such handlers are attached after the provider underlying the client has already been initialized, they should run immediately. See [provider initialization](./02-providers.md#24-initialization), [setting a provider](./01-flag-evaluation.md#setting-a-provider). + +### Event handlers and context reconciliation + +Providers built to conform to the static context paradigm feature an additional `PROVIDER_CONTEXT_CHANGED` event, which is used to signal that the global context has been changed, and flags should be re-evaluated. +This can be particularly useful for triggering UI repaints in multiple components when one component updates the [evaluation context](./03-evaluation-context.md). +SDK implementations automatically fire the the `PROVIDER_CONTEXT_CHANGED` events if the `on context changed` handler terminates normally (and `PROVIDER_ERROR` events otherwise). +Optionally, some providers may transition to the `STALE` state while their associated context is waiting to be reconciled, since this may involve asynchronous operations such as network calls. + +```mermaid +--- +title: Provider context reconciliation +--- +stateDiagram-v2 + direction TB + READY --> READY:emit(PROVIDER_CONTEXT_CHANGED) + ERROR --> READY:emit(PROVIDER_READY) + READY --> STALE:emit(PROVIDER_STALE) + STALE --> READY:emit(PROVIDER_CONTEXT_CHANGED) + STALE --> ERROR:emit(PROVIDER_ERROR) +``` + +#### Condition 5.3.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) + +##### Conditional Requirement 5.3.4.1 + +> When the provider's `on context changed` is called, the provider **MAY** emit the `PROVIDER_STALE` event, and transition to the `STALE` state. + +Some providers cache evaluated flags, and re-evaluate them when the context is changed. +In these cases, the provider may signal its cache is invalid with the `PROVIDER_STALE` event and the `STALE` provider state. + +see: [provider event types](../types.md#provider-events), [provider events](#51-provider-events), context, [provider context reconciliation](02-providers.md#26-provider-context-reconciliation) + +##### Conditional Requirement 5.3.4.2 + +> If the provider's `on context changed` function terminates normally, associated `PROVIDER_CONTEXT_CHANGED` handlers **MUST** run. + +The implementation must run any `PROVIDER_CONTEXT_CHANGED` handlers associated with the provider after the provider has reconciled its state and returned from the `on context changed` function. +The `PROVIDER_CONTEXT_CHANGED` is not emitted from the provider itself; the SDK implementation must run the `PROVIDER_CONTEXT_CHANGED` handlers if the `on context changed` function terminates normally. + +see: [provider event types](../types.md#provider-events), [provider events](#51-provider-events), context, [provider context reconciliation](02-providers.md#26-provider-context-reconciliation) + +##### Conditional Requirement 5.3.4.3 + +> If the provider's `on context changed` function terminates abnormally, associated `PROVIDER_ERROR` handlers **MUST** run. + +The `PROVIDER_ERROR` is not emitted from the provider itself; the SDK implementation must run the `PROVIDER_ERROR` handlers if the `on context changed` throws or otherwise signals an error. + +see: [provider event types](../types.md#provider-events), [provider events](#51-provider-events), context, [provider context reconciliation](02-providers.md#26-provider-context-reconciliation) \ No newline at end of file diff --git a/specification/types.md b/specification/types.md index a53dacae..054f8d30 100644 --- a/specification/types.md +++ b/specification/types.md @@ -139,12 +139,15 @@ It supports definition of arbitrary properties, with keys of type `string`, and An enumeration of provider events. -| Event | Explanation | -| ------------------------------ | --------------------------------------------------------------------------------------------------- | -| PROVIDER_READY | The provider is ready to perform flag evaluations. | -| PROVIDER_ERROR | The provider signalled an error. | -| PROVIDER_CONFIGURATION_CHANGED | A change was made to the backend flag configuration. | -| PROVIDER_STALE | The provider's cached state is no longer valid and may not be up-to-date with the source of truth. | +| Event | Explanation | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------ | +| PROVIDER_READY | The provider is ready to perform flag evaluations. | +| PROVIDER_ERROR | The provider signalled an error. | +| PROVIDER_CONFIGURATION_CHANGED | A change was made to the backend flag configuration. | +| PROVIDER_STALE | The provider's cached state is no longer valid and may not be up-to-date with the source of truth. | +| PROVIDER_CONTEXT_CHANGED* | The context associated with the provider has changed, and the provider has reconciled it's associated state. | + +\* [static context (client-side) paradigm](./glossary.md#static-context-paradigm) only ### Handler Functions