5. Events

Overview

Events allow consumers (application integrator, application author, integration author) to react to state changes in the provider or underlying flag management system, such as flag definition changes, provider readiness, or error conditions. A provider may emit events or run a callback indicating that it received a certain event, optionally providing data associated with that event. Handlers registered on the client or the global API are then invoked with this data.

The data that providers supply in event payloads may include a list of flag keys changed, error messages, and possibly updated flag values.

graph P(Provider) -->|emit event| A[API] A -->|run handlers| AH("API (global) event handlers") A --> C[Client] C -->|run handlers| CH(Client event handlers)

5.1. Provider events

Requirement 5.1.1

The provider MAY define a mechanism for signaling the occurrence of one of a set of events, including PROVIDER_READY, PROVIDER_ERROR, PROVIDER_CONFIGURATION_CHANGED and PROVIDER_STALE, with a provider event details payload.

If available, native event-emitter or observable/observer language constructs can be used.

see: provider event types, event details.

Requirement 5.1.2

When a provider signals the occurrence of a particular event, the associated client and API event handlers MUST run.

see: provider event types and 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 named client constitute their own "events scope".

see: setting a provider

Requirement 5.1.4

PROVIDER_ERROR events SHOULD populate the provider event details's error message field.

The error message field should contain an informative message as to the nature of the error.

See event metadata

5.2. Event handlers

Requirement 5.2.1

The client MUST provide a function for associating handler functions with a particular provider event type.

  // run the myClientOnReadyHandler function when the PROVIDER_READY event is fired
  client.addHandler(ProviderEvents.Ready, myClientOnReadyHandler);

see: provider events, provider event types

Requirement 5.2.2

The API MUST provide a function for associating handler functions with a particular provider event type.

  // run the myGlobalErrorHandler function when the PROVIDER_READY event is fired
  OpenFeature.addHandler(ProviderEvents.Error, myGlobalErrorHandler);

see: provider events, provider event types

Requirement 5.2.3

The event details MUST contain the provider name associated with the event.

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, creating clients.

Requirement 5.2.4

The handler function MUST accept a event details parameter.

see: event details

Requirement 5.2.5

If a handler function terminates abnormally, other handler functions MUST run.

Requirement 5.2.6

Event handlers MUST persist across provider changes.

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

The API and client MUST provide a function allowing the removal of event handlers.

  // remove an existing handler for a PROVIDER_CONFIGURATION_CHANGED event
  client.removeHandler(ProviderEvents.ConfigurationChanged, myClientOnChangedHandler);

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

If the provider's initialize function terminates normally, PROVIDER_READY handlers MUST run.

See provider initialization and setting a provider.

Requirement 5.3.2

If the provider's initialize function terminates abnormally, PROVIDER_ERROR handlers MUST run.

A failed initialization could represent an unrecoverable error, such as bad credentials or a missing file. If a failed initialization could also represent a transient error. A provider which maintains a persistent connection to a remote flag management system may attempt to reconnect, and emit PROVIDER_READY after a failed initialization.

See provider initialization and setting a provider.

Requirement 5.3.3

Handlers attached after the provider is already in the associated state, MUST run immediately.

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, setting a provider.