Skip to content

feat: emit events on context change (client-only) #200

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.

Sign up for GitHub

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

Merged
toddbaert merged 5 commits into from
Dec 13, 2023
Merged

feat: emit events on context change (client-only) #200

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
82a5f73
improvement: emit events on context changed
Billlynch Jul 21, 2023
342af54
fixup: make STALE optional, diagram
toddbaert Dec 8, 2023
021bd33
fixup: diagram
toddbaert Dec 8, 2023
16d4120
fixup: more clarity
toddbaert Dec 9, 2023
8222682
Update specification/sections/05-events.md
toddbaert Dec 11, 2023
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
Prev Previous commit
Next Next commit
fixup: make STALE optional, diagram 
Signed-off-by: Todd Baert <[email protected]>
  • Loading branch information
@toddbaert
toddbaert committed Dec 8, 2023
commit 342af54b117dd42d0d640b9dd29c3e28abe5958c
46 changes: 27 additions & 19 deletions specification.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -893,25 +893,33 @@
"children": []
},
{
"id": "Requirement 5.3.4",
"machine_id": "requirement_5_3_4",
"content": "When the provider's `on context changed` is called, `PROVIDER_STALE` handlers MUST run.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 5.3.5",
"machine_id": "requirement_5_3_5",
"content": "If the provider's `on context changed` function terminates successfully, `PROVIDER_READY` handlers MUST run.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 5.3.6",
"machine_id": "requirement_5_3_6",
"content": "If the provider's `on context changed` function terminates abnormally, `PROVIDER_ERROR` handlers MUST run.",
"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: 45 additions & 9 deletions specification/sections/05-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,20 +145,56 @@ If such handlers are attached after the provider underlying the client has alrea

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

#### Requirement 5.3.4
### Event handlers and context reconciliation

> When the provider's `on context changed` is called, `PROVIDER_STALE` handlers **MUST** run.
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).
Optionally, some providers may transition to a the `STALE` state while their associated context is waiting to be reconciled, since this may involve asynchronous operations such as network calls.
Comment thread
toddbaert marked this conversation as resolved.
Outdated
Comment thread
toddbaert marked this conversation as resolved.
Outdated

See: [provider events](#51-provider-events), [`provider event types`](../types.md#provider-events)
```mermaid
---
title: Provider context reconciliation
---
stateDiagram-v2
direction TB
READY --> READY:emit(PROVIDER_CONTEXT_CHANGED)
READY --> ERROR
ERROR --> 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.

#### Requirement 5.3.5
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.

> If the provider's `on context changed` function terminates successfully, `PROVIDER_READY` handlers **MUST** run.
see: [provider event types](../types.md#provider-events), [provider events](#51-provider-events), context, [provider context reconciliation](02-providers.md#26-provider-context-reconciliation)

See: [provider events](#51-provider-events), [`provider event types`](../types.md#provider-events)
##### Conditional Requirement 5.3.4.3

#### Requirement 5.3.6
> If the provider's `on context changed` function terminates abnormally, associated `PROVIDER_ERROR` handlers **MUST** run.

> If the provider's `on context changed` function terminates abnormally, `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 events](#51-provider-events), [`provider event types`](../types.md#provider-events)
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
View file
Open in desktop
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