From 8e31a2cb7bd8ec9b81486c0334be522a0f68aef9 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Wed, 28 Feb 2024 14:34:23 -0500 Subject: [PATCH 1/4] chore: clarify event/domain scoping, lifecycle Signed-off-by: Todd Baert --- specification/glossary.md | 6 ++++++ specification/sections/05-events.md | 12 +++++++++++- 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/specification/glossary.md b/specification/glossary.md index 5f759fae..c4f1eb3a 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -28,6 +28,7 @@ This document defines some terms that are used across this specification. - [Evaluation API](#evaluation-api) - [Flag Management System](#flag-management-system) - [Provider](#provider) + - [Provider Lifecycle](#provider-lifecycle) - [Domain](#domain) - [Integration](#integration) - [Evaluation Context](#evaluation-context) @@ -109,9 +110,14 @@ A source-of-truth for flag values and rules. Flag management systems may include An SDK-compliant implementation which resolves flag values from a particular flag management system, allowing the use of the [Evaluation API](./sections/01-flag-evaluation.md#13-flag-evaluation) as an abstraction for the system in question. +### Provider Lifecycle + +The possible states and transitions of a provider over the course of its usage, as defined by the [provider interface](./sections/02-providers.md). + ### Domain An identifier which logically binds clients with providers, allowing for multiple providers to be used simultaneously within a single application. +Domain binding is dynamic; it may change over the course of an application lifetime (ie: a client associated to the default provider via an unbound domain will be bound to a new provider if a provider is subsequently assigned to that domain). ### Integration diff --git a/specification/sections/05-events.md b/specification/sections/05-events.md index 16243d8c..ddf52b0b 100644 --- a/specification/sections/05-events.md +++ b/specification/sections/05-events.md @@ -22,6 +22,11 @@ graph C -->|run handlers| CH(Client event handlers) ``` +The `domain` of a provider constitutes a logical scope for events. +Clients associated to a particular provider through a `domain` run event handlers only when that provider emits events, or one of its lifecycle functions terminates. + +see: [domain](../glossary.md#domain) + ### 5.1. Provider events #### Requirement 5.1.1 @@ -44,13 +49,17 @@ see: [provider event types](../types.md#provider-events), [`event details`](../t > When a `provider` signals the occurrence of a particular `event`, the associated `client` and `API` event handlers **MUST** run. +Client event handlers respect the dynamic binding of clients to providers via `domains`. +Client event handlers run when a lifecycle function terminates on the associated provider, or the associated provider emits an event. + see: [provider event types](./../types.md#provider-events) and [event handlers](#52-event-handlers). #### Requirement 5.1.3 > When a `provider` signals the occurrence of a particular `event`, event handlers on clients which are not associated with that provider **MUST NOT** run. -Providers bound to a `domain` constitute their own "events scope". +Client event handlers respect the dynamic binding of clients to providers via `domains`. +Client event handlers do not run when a lifecycle function terminates on an unassociated provider, or an unassociated provider emits an event. see [setting a provider](./01-flag-evaluation.md#setting-a-provider), [domain](../glossary.md#domain) for details. @@ -130,6 +139,7 @@ This means that the order of provider configuration and event handler addition i ### Event handlers and initialization Though providers themselves need not implement events, the `flag evaluation API` uses events to convey relevant state changes during configuration and initialization. +Implementations automatically emit `PROVIDER_READY` or `PROVIDER_ERROR` events depending on the outcome of the `initialize` function, if the provider has implemented one (if none is implemented, `PROVIDER_READY` runs unconditionally). _Application authors_ and _application integrators_ use these events to wait for proper initialization of the provider and to do basic monitoring and error handling. #### Requirement 5.3.1 From 7464f3e8bb224e0f5687a9430a5e8cb9b1a5b98a Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Wed, 28 Feb 2024 14:38:52 -0500 Subject: [PATCH 2/4] fixup: markdown toc Signed-off-by: Todd Baert --- specification/glossary.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/glossary.md b/specification/glossary.md index c4f1eb3a..e7a2f016 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -116,8 +116,7 @@ The possible states and transitions of a provider over the course of its usage, ### Domain -An identifier which logically binds clients with providers, allowing for multiple providers to be used simultaneously within a single application. -Domain binding is dynamic; it may change over the course of an application lifetime (ie: a client associated to the default provider via an unbound domain will be bound to a new provider if a provider is subsequently assigned to that domain). +An identifier which logically binds clients with providers, allowing for multiple providers to be used simultaneously within a single application. Domain binding is dynamic; it may change over the course of an application lifetime (ie: a client associated to the default provider via an unbound domain will be bound to a new provider if a provider is subsequently assigned to that domain). ### Integration From 4ef5f5cbbb94d5695396a77365645e514ede4835 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Wed, 28 Feb 2024 15:20:27 -0500 Subject: [PATCH 3/4] Update specification/glossary.md Signed-off-by: Todd Baert --- specification/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/glossary.md b/specification/glossary.md index e7a2f016..d5187460 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -116,7 +116,7 @@ The possible states and transitions of a provider over the course of its usage, ### Domain -An identifier which logically binds clients with providers, allowing for multiple providers to be used simultaneously within a single application. Domain binding is dynamic; it may change over the course of an application lifetime (ie: a client associated to the default provider via an unbound domain will be bound to a new provider if a provider is subsequently assigned to that domain). +An identifier which logically binds clients with providers, allowing for multiple providers to be used simultaneously within a single application. Domain binding is dynamic; it may change over the course of an application's lifetime (ie: a client associated to the default provider via an unbound domain will be bound to a new provider if a provider is subsequently assigned to that domain). ### Integration From 40aa4d5f1fcccf9c39c26d10c3d2b097cdfce42a Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Wed, 28 Feb 2024 15:23:22 -0500 Subject: [PATCH 4/4] add comma 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 ddf52b0b..e62234cb 100644 --- a/specification/sections/05-events.md +++ b/specification/sections/05-events.md @@ -23,7 +23,7 @@ graph ``` The `domain` of a provider constitutes a logical scope for events. -Clients associated to a particular provider through a `domain` run event handlers only when that provider emits events, or one of its lifecycle functions terminates. +Clients associated to a particular provider through a `domain`, run event handlers only when that provider emits events, or one of its lifecycle functions terminates. see: [domain](../glossary.md#domain)