From 776ee1f3966354e0a674bb77e24a1e486be005fc Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Fri, 6 Dec 2024 10:46:14 -0500 Subject: [PATCH] feat!: add evaluation details to finally hook (#280) Signed-off-by: Michael Beemer --- specification.json | 8 ++++---- specification/sections/04-hooks.md | 23 ++++++++++++++--------- 2 files changed, 18 insertions(+), 13 deletions(-) diff --git a/specification.json b/specification.json index 62147570..8f68095b 100644 --- a/specification.json +++ b/specification.json @@ -692,7 +692,7 @@ { "id": "Requirement 4.1.2", "machine_id": "requirement_4_1_2", - "content": "The `hook context` SHOULD provide: access to the `client metadata` and the `provider metadata` fields.", + "content": "The `hook context` SHOULD provide access to the `client metadata` and the `provider metadata` fields.", "RFC 2119 keyword": "SHOULD", "children": [] }, @@ -721,7 +721,7 @@ { "id": "Requirement 4.2.1", "machine_id": "requirement_4_2_1", - "content": "`hook hints` MUST be a structure supports definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number | datetime | structure`..", + "content": "`hook hints` MUST be a structure supports definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number | datetime | structure`.", "RFC 2119 keyword": "MUST", "children": [] }, @@ -808,7 +808,7 @@ { "id": "Requirement 4.3.6", "machine_id": "requirement_4_3_6", - "content": "The `after` stage MUST run after flag resolution occurs. It accepts a `hook context` (required), `flag evaluation details` (required) and `hook hints` (optional). It has no return value.", + "content": "The `after` stage MUST run after flag resolution occurs. It accepts a `hook context` (required), `evaluation details` (required) and `hook hints` (optional). It has no return value.", "RFC 2119 keyword": "MUST", "children": [] }, @@ -822,7 +822,7 @@ { "id": "Requirement 4.3.8", "machine_id": "requirement_4_3_8", - "content": "The `finally` hook MUST run after the `before`, `after`, and `error` stages. It accepts a `hook context` (required) and `hook hints` (optional). There is no return value.", + "content": "The `finally` hook MUST run after the `before`, `after`, and `error` stages. It accepts a `hook context` (required), `evaluation details` (required) and `hook hints` (optional). It has no return value.", "RFC 2119 keyword": "MUST", "children": [] }, diff --git a/specification/sections/04-hooks.md b/specification/sections/04-hooks.md index af7bbaa6..e8157807 100644 --- a/specification/sections/04-hooks.md +++ b/specification/sections/04-hooks.md @@ -14,8 +14,8 @@ Hooks add their logic at any of four specific stages of flag evaluation: - `before`, immediately before flag evaluation - `after`, immediately after successful flag evaluation -- `error`, immediately after an unsuccessful during flag evaluation -- `finally` unconditionally after flag evaluation +- `error`, immediately after an unsuccessful flag evaluation +- `finally`, unconditionally after flag evaluation ```mermaid flowchart LR @@ -27,11 +27,14 @@ flowchart LR E -..-> F ``` -Hooks can be configured to run globally (impacting all flag evaluations), per client, or per flag evaluation invocation. Some example use-cases for hook include adding additional data to the [evaluation context](./03-evaluation-context.md), performing validation on the received flag value, providing data to telemetric tools, and logging errors. +Hooks can be configured to run globally (impacting all flag evaluations), per client, or per flag evaluation invocation. Some example use cases for a hook include adding additional data to the [evaluation context](./03-evaluation-context.md), performing validation on the received flag value, providing data to telemetric tools, and logging errors. ### Definitions -**Hook**: Application author/integrator-supplied logic that is called by the OpenFeature framework at a specific stage. **Stage**: An explicit portion of the flag evaluation lifecycle. e.g. `before` being "before the [resolution](../glossary.md#resolving-flag-values) is run. **Invocation**: A single call to evaluate a flag. `client.getBooleanValue(..)` is an invocation. **API**: The global API singleton. +**Hook**: Application author/integrator-supplied logic that is called by the OpenFeature framework at a specific stage. +**Stage**: An explicit portion of the flag evaluation lifecycle. e.g. `before` being "before" the [resolution](../glossary.md#resolving-flag-values) is run. +**Invocation**: A single call to evaluate a flag. `client.getBooleanValue(..)` is an invocation. +**API**: The global API singleton. ### 4.1. Hook context @@ -43,7 +46,7 @@ Hook context exists to provide hooks with information about the invocation. #### Requirement 4.1.2 -> The `hook context` **SHOULD** provide: access to the `client metadata` and the `provider metadata` fields. +> The `hook context` **SHOULD** provide access to the `client metadata` and the `provider metadata` fields. #### Requirement 4.1.3 @@ -63,7 +66,7 @@ see: [dynamic-context paradigm](../glossary.md#dynamic-context-paradigm) #### Requirement 4.2.1 -> `hook hints` **MUST** be a structure supports definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number | datetime | structure`.. +> `hook hints` **MUST** be a structure supports definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number | datetime | structure`. #### Condition 4.2.2 @@ -129,7 +132,7 @@ Evaluation context merge order is defined in [Context levels and merging](./03-e #### Requirement 4.3.6 -> The `after` stage **MUST** run after flag resolution occurs. It accepts a `hook context` (required), `flag evaluation details` (required) and `hook hints` (optional). It has no return value. +> The `after` stage **MUST** run after flag resolution occurs. It accepts a `hook context` (required), `evaluation details` (required) and `hook hints` (optional). It has no return value. #### Requirement 4.3.7 @@ -137,7 +140,9 @@ Evaluation context merge order is defined in [Context levels and merging](./03-e #### Requirement 4.3.8 -> The `finally` hook **MUST** run after the `before`, `after`, and `error` stages. It accepts a `hook context` (required) and `hook hints` (optional). There is no return value. +> The `finally` hook **MUST** run after the `before`, `after`, and `error` stages. It accepts a `hook context` (required), `evaluation details` (required) and `hook hints` (optional). It has no return value. + +The evaluation details passed to the `finally` stage matches the evaluation details returned to the application author. #### Condition 4.3.9 @@ -179,7 +184,7 @@ client.getValue('my-flag', 'defaultValue', new Hook3()); > If a `finally` hook abnormally terminates, evaluation **MUST** proceed, including the execution of any remaining `finally` hooks. -In languages with try/catch semantics, this means that exceptions thrown in `finally` hooks should be caught, and not propagated up the call stack. +In languages with try/catch semantics, this means that exceptions thrown in `finally` hooks should be caught and not propagated up the call stack. #### Requirement 4.4.4