Skip to content

Commit

Permalink
feat: emit events on context change (client-only) (#200)
Browse files Browse the repository at this point in the history
Signed-off-by: BillLynch <llynch.bill@gmail.com>
Co-authored-by: Todd Baert <todd.baert@dynatrace.com>
Co-authored-by: Kavindu Dodanduwa <Kavindu-Dodan@users.noreply.github.com>
  • Loading branch information
3 people authored Dec 13, 2023
1 parent 5ed6c0c commit 262da8f
Show file tree
Hide file tree
Showing 3 changed files with 92 additions and 6 deletions.
29 changes: 29 additions & 0 deletions specification.json
Original file line number Diff line number Diff line change
Expand Up @@ -891,6 +891,35 @@
"content": "Handlers attached after the provider is already in the associated state, MUST run immediately.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 5.3.4",
"machine_id": "condition_5_3_4",
"content": "The implementation uses the static-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 5.3.4.1",
"machine_id": "conditional_requirement_5_3_4_1",
"content": "When the provider's `on context changed` is called, the provider MAY emit the `PROVIDER_STALE` event, and transition to the `STALE` state.",
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Conditional Requirement 5.3.4.2",
"machine_id": "conditional_requirement_5_3_4_2",
"content": "If the provider's `on context changed` function terminates normally, associated `PROVIDER_CONTEXT_CHANGED` handlers MUST run.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Conditional Requirement 5.3.4.3",
"machine_id": "conditional_requirement_5_3_4_3",
"content": "If the provider's `on context changed` function terminates abnormally, associated `PROVIDER_ERROR` handlers MUST run.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
}
]
}
54 changes: 54 additions & 0 deletions specification/sections/05-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,3 +144,57 @@ For instance, _application authors_ may attach readiness handlers to be confiden
If such handlers are attached after the provider underlying the client has already been initialized, they should run immediately.

See [provider initialization](./02-providers.md#24-initialization), [setting a provider](./01-flag-evaluation.md#setting-a-provider).

### Event handlers and context reconciliation

Providers built to conform to the static context paradigm feature an additional `PROVIDER_CONTEXT_CHANGED` event, which is used to signal that the global context has been changed, and flags should be re-evaluated.
This can be particularly useful for triggering UI repaints in multiple components when one component updates the [evaluation context](./03-evaluation-context.md).
SDK implementations automatically fire the the `PROVIDER_CONTEXT_CHANGED` events if the `on context changed` handler terminates normally (and `PROVIDER_ERROR` events otherwise).
Optionally, some providers may transition to the `STALE` state while their associated context is waiting to be reconciled, since this may involve asynchronous operations such as network calls.

```mermaid
---
title: Provider context reconciliation
---
stateDiagram-v2
direction TB
READY --> READY:emit(PROVIDER_CONTEXT_CHANGED)
ERROR --> READY:emit(PROVIDER_READY)
READY --> STALE:emit(PROVIDER_STALE)
STALE --> READY:emit(PROVIDER_CONTEXT_CHANGED)
STALE --> ERROR:emit(PROVIDER_ERROR)
```

#### Condition 5.3.4

[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)

> The implementation uses the static-context paradigm.
see: [static-context paradigm](../glossary.md#static-context-paradigm)

##### Conditional Requirement 5.3.4.1

> When the provider's `on context changed` is called, the provider **MAY** emit the `PROVIDER_STALE` event, and transition to the `STALE` state.
Some providers cache evaluated flags, and re-evaluate them when the context is changed.
In these cases, the provider may signal its cache is invalid with the `PROVIDER_STALE` event and the `STALE` provider state.

see: [provider event types](../types.md#provider-events), [provider events](#51-provider-events), context, [provider context reconciliation](02-providers.md#26-provider-context-reconciliation)

##### Conditional Requirement 5.3.4.2

> If the provider's `on context changed` function terminates normally, associated `PROVIDER_CONTEXT_CHANGED` handlers **MUST** run.
The implementation must run any `PROVIDER_CONTEXT_CHANGED` handlers associated with the provider after the provider has reconciled its state and returned from the `on context changed` function.
The `PROVIDER_CONTEXT_CHANGED` is not emitted from the provider itself; the SDK implementation must run the `PROVIDER_CONTEXT_CHANGED` handlers if the `on context changed` function terminates normally.

see: [provider event types](../types.md#provider-events), [provider events](#51-provider-events), context, [provider context reconciliation](02-providers.md#26-provider-context-reconciliation)

##### Conditional Requirement 5.3.4.3

> If the provider's `on context changed` function terminates abnormally, associated `PROVIDER_ERROR` handlers **MUST** run.
The `PROVIDER_ERROR` is not emitted from the provider itself; the SDK implementation must run the `PROVIDER_ERROR` handlers if the `on context changed` throws or otherwise signals an error.

see: [provider event types](../types.md#provider-events), [provider events](#51-provider-events), context, [provider context reconciliation](02-providers.md#26-provider-context-reconciliation)
15 changes: 9 additions & 6 deletions specification/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,12 +139,15 @@ It supports definition of arbitrary properties, with keys of type `string`, and

An enumeration of provider events.

| Event | Explanation |
| ------------------------------ | --------------------------------------------------------------------------------------------------- |
| PROVIDER_READY | The provider is ready to perform flag evaluations. |
| PROVIDER_ERROR | The provider signalled an error. |
| PROVIDER_CONFIGURATION_CHANGED | A change was made to the backend flag configuration. |
| PROVIDER_STALE | The provider's cached state is no longer valid and may not be up-to-date with the source of truth. |
| Event | Explanation |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| PROVIDER_READY | The provider is ready to perform flag evaluations. |
| PROVIDER_ERROR | The provider signalled an error. |
| PROVIDER_CONFIGURATION_CHANGED | A change was made to the backend flag configuration. |
| PROVIDER_STALE | The provider's cached state is no longer valid and may not be up-to-date with the source of truth. |
| PROVIDER_CONTEXT_CHANGED* | The context associated with the provider has changed, and the provider has reconciled it's associated state. |

\* [static context (client-side) paradigm](./glossary.md#static-context-paradigm) only

### Handler Functions

Expand Down

0 comments on commit 262da8f

Please sign in to comment.