From 8e8c3447962949f5ed6a83002b68460243305b32 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Tue, 15 Aug 2023 10:53:01 -0400 Subject: [PATCH] feat: STALE state, run handlers for current state immediately, provider name (#196) Signed-off-by: Todd Baert Co-authored-by: Justin Abrahms --- specification.json | 4 ++-- specification/sections/01-flag-evaluation.md | 21 +++++++++++++------- specification/sections/05-events.md | 21 +++++++++++++------- specification/types.md | 13 ++++++------ 4 files changed, 37 insertions(+), 22 deletions(-) diff --git a/specification.json b/specification.json index d051c13d..2f4bd63c 100644 --- a/specification.json +++ b/specification.json @@ -796,7 +796,7 @@ { "id": "Requirement 5.2.3", "machine_id": "requirement_5_2_3", - "content": "The `event details` MUST contain the `client name` associated with the event.", + "content": "The `event details` MUST contain the `provider name` associated with the event.", "RFC 2119 keyword": "MUST", "children": [] }, @@ -845,7 +845,7 @@ { "id": "Requirement 5.3.3", "machine_id": "requirement_5_3_3", - "content": "`PROVIDER_READY` handlers attached after the provider is already in a ready state MUST run immediately.", + "content": "Handlers attached after the provider is already in the associated state, MUST run immediately.", "RFC 2119 keyword": "MUST", "children": [] } diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 8889636e..8ca43450 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -31,9 +31,9 @@ It's important that multiple instances of the `API` not be active, so that state OpenFeature.setProvider(new MyProvider()); ``` -This provider is used if there is not a more specific client name binding. (see later requirements). +This provider is used if a client is not bound to a specific provider through its name. -See [provider](./02-providers.md) for details. +See [provider](./02-providers.md), [creating clients](#creating-clients). #### Requirement 1.1.2.2 @@ -62,6 +62,10 @@ see: [shutdown](./02-providers.md#25-shutdown), [setting a provider](#setting-a- OpenFeature.setProvider("client-name", new MyProvider()); ``` +Named clients can be associated with a particular provider by supplying a matching name when the provider is set. + +See [creating clients](#creating-clients). + #### Requirement 1.1.4 > The `API` **MUST** provide a function to add `hooks` which accepts one or more API-conformant `hooks`, and appends them to the collection of any previously added hooks. When new hooks are added, previously added hooks are not removed. @@ -84,20 +88,23 @@ OpenFeature.getProviderMetadata(); See [provider](./02-providers.md) for details. +### Creating clients + #### Requirement 1.1.6 > The `API` **MUST** provide a function for creating a `client` which accepts the following options: > > - name (optional): A logical string identifier for the client. -```typescript +```java // example client creation and retrieval -OpenFeature.getClient({ - name: "my-openfeature-client", -}); +OpenFeature.getClient("my-named-client"); ``` -The name is a logical identifier for the client. +The name is a logical identifier for the client which may be associated with a particular provider by the application integrator. +If a client name is not bound to a particular provider, the client is associated with the default provider. + +See [setting a provider](#setting-a-provider) for details. #### Requirement 1.1.7 diff --git a/specification/sections/05-events.md b/specification/sections/05-events.md index da192bea..1db44724 100644 --- a/specification/sections/05-events.md +++ b/specification/sections/05-events.md @@ -1,5 +1,5 @@ --- -title: Events Extensions +title: Events description: Specification defining event semantics toc_max_heading_level: 4 --- @@ -80,10 +80,12 @@ see: [provider events](#51-provider-events), [`provider event types`](../types.m #### Requirement 5.2.3 -> The `event details` **MUST** contain the `client name` associated with the event. +> The `event details` **MUST** contain the `provider name` associated with the event. -The `client name` indicates the client/provider pair with which the event is associated. -This is especially relevant for event handlers which are attached to the `API`, not a particular client. +The `provider name` indicates the provider from which the event originated. +This is especially relevant for global event handlers used for general monitoring, such as alerting on provider errors. + +See [setting a provider](./01-flag-evaluation.md#setting-a-provider), [creating clients](./01-flag-evaluation.md#creating-clients). #### Requirement 5.2.4 @@ -99,7 +101,7 @@ see: [`event details`](../types.md#event-details) > Event handlers **MUST** persist across `provider` changes. -If a provider is changed, existing event handlers will still fire. +If the underlying provider is changed, existing client and API event handlers will still fire. This means that the order of provider configuration and event handler addition is independent. #### Requirement 5.2.7 @@ -134,6 +136,11 @@ See [provider initialization](./02-providers.md#24-initialization) and [setting #### Requirement 5.3.3 -> `PROVIDER_READY` handlers attached after the provider is already in a ready state **MUST** run immediately. +> Handlers attached after the provider is already in the associated state, **MUST** run immediately. -See [provider initialization](./02-providers.md#24-initialization) and [setting a provider](./01-flag-evaluation.md#setting-a-provider). +Handlers may be attached at any point in the application lifecycle. +Handlers should run immediately if the provider is already in the associated state. +For instance, _application authors_ may attach readiness handlers to be confident that system is ready to evaluate flags. +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). diff --git a/specification/types.md b/specification/types.md index a509cfd1..068806c7 100644 --- a/specification/types.md +++ b/specification/types.md @@ -99,11 +99,12 @@ This structure is populated by a provider for use by an [Application Author](./g An enumeration of possible provider states. -| Status | Explanation | -| --------- | ------------------------------------------------------------------------------- | -| NOT_READY | The provider has not been initialized. | -| READY | The provider has been initialized, and is able to reliably resolve flag values. | -| ERROR | The provider is initialized but is not able to reliably resolve flag values. | +| Status | Explanation | +| --------- | --------------------------------------------------------------------------------------------------- | +| NOT_READY | The provider has not been initialized. | +| READY | The provider has been initialized, and is able to reliably resolve flag values. | +| ERROR | The provider is initialized but is not able to reliably resolve flag values. | +| STALE | The provider's cached state is no longer valid and may not be up-to-date with the source of truth. | ### Provider Event Details @@ -136,7 +137,7 @@ An enumeration of provider events. | 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 not longer valid and may not be up-to-date with the source of truth. | +| PROVIDER_STALE | The provider's cached state is no longer valid and may not be up-to-date with the source of truth. | ### Handler Functions