Skip to content

Commit

Permalink
chore: clarify event/domain scoping, lifecycle (#248)
Browse files Browse the repository at this point in the history
Adding some additional non-normative text to clarify a few things at the
prompt of @federicobond .

The meaning and justification should be self-evident, and if it's not I
did a bad job. 😅

---------

Signed-off-by: Todd Baert <todd.baert@dynatrace.com>
  • Loading branch information
toddbaert authored Mar 1, 2024
1 parent 57829b0 commit 37cf68b
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 2 deletions.
7 changes: 6 additions & 1 deletion specification/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -109,9 +110,13 @@ 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.
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

Expand Down
12 changes: 11 additions & 1 deletion specification/sections/05-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 37cf68b

Please sign in to comment.