feat: STALE state, run handlers for current state immediately, provid…

…er name (#196)

Signed-off-by: Todd Baert <todd.baert@dynatrace.com>
Co-authored-by: Justin Abrahms <justin@abrah.ms>

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": []
         }

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
 

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).

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