From 82a5f73e2be0febc6e70e34e8356e2fab40cbe5a Mon Sep 17 00:00:00 2001 From: BillLynch Date: Fri, 21 Jul 2023 09:38:35 +0100 Subject: [PATCH 1/5] improvement: emit events on context changed Signed-off-by: BillLynch --- specification.json | 21 +++++++++++++++++++++ specification/sections/05-events.md | 18 ++++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/specification.json b/specification.json index ef8cda11..7bdeb76f 100644 --- a/specification.json +++ b/specification.json @@ -891,6 +891,27 @@ "content": "Handlers attached after the provider is already in the associated state, MUST run immediately.", "RFC 2119 keyword": "MUST", "children": [] + }, + { + "id": "Requirement 5.3.4", + "machine_id": "requirement_5_3_4", + "content": "When the provider's `on context changed` is called, `PROVIDER_STALE` handlers MUST run.", + "RFC 2119 keyword": "MUST", + "children": [] + }, + { + "id": "Requirement 5.3.5", + "machine_id": "requirement_5_3_5", + "content": "If the provider's `on context changed` function terminates successfully, `PROVIDER_READY` handlers MUST run.", + "RFC 2119 keyword": "MUST", + "children": [] + }, + { + "id": "Requirement 5.3.6", + "machine_id": "requirement_5_3_6", + "content": "If the provider's `on context changed` function terminates abnormally, `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..e5a9ab8f 100644 --- a/specification/sections/05-events.md +++ b/specification/sections/05-events.md @@ -144,3 +144,21 @@ 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). + +#### Requirement 5.3.4 + +> When the provider's `on context changed` is called, `PROVIDER_STALE` handlers **MUST** run. + +See: [provider events](#51-provider-events), [`provider event types`](../types.md#provider-events) + +#### Requirement 5.3.5 + +> If the provider's `on context changed` function terminates successfully, `PROVIDER_READY` handlers **MUST** run. + +See: [provider events](#51-provider-events), [`provider event types`](../types.md#provider-events) + +#### Requirement 5.3.6 + +> If the provider's `on context changed` function terminates abnormally, `PROVIDER_ERROR` handlers **MUST** run. + +See: [provider events](#51-provider-events), [`provider event types`](../types.md#provider-events) From 342af54b117dd42d0d640b9dd29c3e28abe5958c Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Fri, 8 Dec 2023 16:09:57 -0500 Subject: [PATCH 2/5] fixup: make STALE optional, diagram Signed-off-by: Todd Baert --- specification.json | 46 ++++++++++++++---------- specification/sections/05-events.md | 54 ++++++++++++++++++++++++----- specification/types.md | 15 ++++---- 3 files changed, 81 insertions(+), 34 deletions(-) diff --git a/specification.json b/specification.json index 7bdeb76f..d9f1302c 100644 --- a/specification.json +++ b/specification.json @@ -893,25 +893,33 @@ "children": [] }, { - "id": "Requirement 5.3.4", - "machine_id": "requirement_5_3_4", - "content": "When the provider's `on context changed` is called, `PROVIDER_STALE` handlers MUST run.", - "RFC 2119 keyword": "MUST", - "children": [] - }, - { - "id": "Requirement 5.3.5", - "machine_id": "requirement_5_3_5", - "content": "If the provider's `on context changed` function terminates successfully, `PROVIDER_READY` handlers MUST run.", - "RFC 2119 keyword": "MUST", - "children": [] - }, - { - "id": "Requirement 5.3.6", - "machine_id": "requirement_5_3_6", - "content": "If the provider's `on context changed` function terminates abnormally, `PROVIDER_ERROR` handlers MUST run.", - "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 e5a9ab8f..057eba31 100644 --- a/specification/sections/05-events.md +++ b/specification/sections/05-events.md @@ -145,20 +145,56 @@ If such handlers are attached after the provider underlying the client has alrea See [provider initialization](./02-providers.md#24-initialization), [setting a provider](./01-flag-evaluation.md#setting-a-provider). -#### Requirement 5.3.4 +### Event handlers and context reconciliation -> When the provider's `on context changed` is called, `PROVIDER_STALE` handlers **MUST** run. +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). +Optionally, some providers may transition to a the `STALE` state while their associated context is waiting to be reconciled, since this may involve asynchronous operations such as network calls. -See: [provider events](#51-provider-events), [`provider event types`](../types.md#provider-events) +```mermaid +--- +title: Provider context reconciliation +--- +stateDiagram-v2 + direction TB + READY --> READY:emit(PROVIDER_CONTEXT_CHANGED) + READY --> ERROR + ERROR --> 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. -#### Requirement 5.3.5 +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. -> If the provider's `on context changed` function terminates successfully, `PROVIDER_READY` handlers **MUST** run. +see: [provider event types](../types.md#provider-events), [provider events](#51-provider-events), context, [provider context reconciliation](02-providers.md#26-provider-context-reconciliation) -See: [provider events](#51-provider-events), [`provider event types`](../types.md#provider-events) +##### Conditional Requirement 5.3.4.3 -#### Requirement 5.3.6 +> If the provider's `on context changed` function terminates abnormally, associated `PROVIDER_ERROR` handlers **MUST** run. -> If the provider's `on context changed` function terminates abnormally, `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 events](#51-provider-events), [`provider event types`](../types.md#provider-events) +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 From 021bd33d1add96fbc2da45d5412a4aa45fe24f5b Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Fri, 8 Dec 2023 16:20:29 -0500 Subject: [PATCH 3/5] fixup: diagram Signed-off-by: Todd Baert --- specification/sections/05-events.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/sections/05-events.md b/specification/sections/05-events.md index 057eba31..2e02d113 100644 --- a/specification/sections/05-events.md +++ b/specification/sections/05-events.md @@ -158,8 +158,7 @@ title: Provider context reconciliation stateDiagram-v2 direction TB READY --> READY:emit(PROVIDER_CONTEXT_CHANGED) - READY --> ERROR - ERROR --> READY + ERROR --> READY:emit(PROVIDER_READY) READY --> STALE:emit(PROVIDER_STALE) STALE --> READY:emit(PROVIDER_CONTEXT_CHANGED) STALE --> ERROR:emit(PROVIDER_ERROR) From 16d4120db06b78474ab358bd393f41c32a2cf9fa Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Sat, 9 Dec 2023 10:33:30 -0500 Subject: [PATCH 4/5] fixup: more clarity Signed-off-by: Todd Baert --- specification/sections/05-events.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/sections/05-events.md b/specification/sections/05-events.md index 2e02d113..d66e041b 100644 --- a/specification/sections/05-events.md +++ b/specification/sections/05-events.md @@ -149,6 +149,7 @@ See [provider initialization](./02-providers.md#24-initialization), [setting a p 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 a the `STALE` state while their associated context is waiting to be reconciled, since this may involve asynchronous operations such as network calls. ```mermaid From 8222682d81295e183b4de511c5d8b9d2cc1cf9cf Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Mon, 11 Dec 2023 16:25:13 -0500 Subject: [PATCH 5/5] Update specification/sections/05-events.md Co-authored-by: Kavindu Dodanduwa Signed-off-by: Todd Baert --- specification/sections/05-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/sections/05-events.md b/specification/sections/05-events.md index d66e041b..48f693af 100644 --- a/specification/sections/05-events.md +++ b/specification/sections/05-events.md @@ -150,7 +150,7 @@ See [provider initialization](./02-providers.md#24-initialization), [setting a p 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 a the `STALE` state while their associated context is waiting to be reconciled, since this may involve asynchronous operations such as network calls. +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 ---