Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: clarify event/domain scoping, lifecycle #248

Merged
merged 5 commits into from
Mar 1, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading