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.
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, includingPROVIDER_READY
,PROVIDER_ERROR
,PROVIDER_CONFIGURATION_CHANGED
andPROVIDER_STALE
, with aprovider 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 particularevent
, the associatedclient
andAPI
event handlers MUST run.
see: provider event types and event handlers.
Requirement 5.1.3
When a
provider
signals the occurrence of a particularevent
, 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 theprovider event details
'serror 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 associatinghandler functions
with a particularprovider 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 associatinghandler functions
with a particularprovider 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 theclient 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.
Requirement 5.2.4
The
handler function
MUST accept aevent details
parameter.
see: event details
Requirement 5.2.5
If a
handler function
terminates abnormally, otherhandler functions
MUST run.
Requirement 5.2.6
Event handlers MUST persist across
provider
changes.
If a provider is changed, existing 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
andclient
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
PROVIDER_READY
handlers attached after the provider is already in a ready state MUST run immediately.