From 268e45628d14ddf74038088823a5a691e075de28 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Wed, 31 May 2023 13:36:58 -0400 Subject: [PATCH 1/3] fix: various clarifications * loosen shutdown requirements to support things like go ctx * clarify how to handle init/shutdown of providers bound to multiple names * clarify init function should terminate before provider used Signed-off-by: Todd Baert --- specification.json | 6 +++--- specification/sections/01-flag-evaluation.md | 12 +++++++----- specification/sections/02-providers.md | 8 ++++---- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/specification.json b/specification.json index 937273aa..773eb6c0 100644 --- a/specification.json +++ b/specification.json @@ -17,7 +17,7 @@ { "id": "Requirement 1.1.2.2", "machine_id": "requirement_1_1_2_2", - "content": "The `provider mutator` function MUST invoke the `initialize` function on the newly registered provider before using it to resolve flag values.", + "content": "The `provider mutator` function MUST await the termination `initialize` function on the newly registered provider before using it to resolve flag values.", "RFC 2119 keyword": "MUST", "children": [] }, @@ -230,7 +230,7 @@ { "id": "Requirement 1.6.1", "machine_id": "requirement_1_6_1", - "content": "The API MUST define a `shutdown` function which, when called, must call the respective `shutdown` function on the active provider.", + "content": "The API MUST define a mechanism to propagate a shutdown request to active providers.", "RFC 2119 keyword": "MUST", "children": [] }, @@ -386,7 +386,7 @@ { "id": "Requirement 2.5.1", "machine_id": "requirement_2_5_1", - "content": "The provider MAY define a `shutdown` function to perform whatever cleanup is necessary for the implementation.", + "content": "The provider MAY define a mechanism to gracefully shutdown and dispose of resources.", "RFC 2119 keyword": "MAY", "children": [] }, diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 8b592207..9af52ab2 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -37,9 +37,10 @@ See [provider](./02-providers.md) for details. #### Requirement 1.1.2.2 -> The `provider mutator` function **MUST** invoke the `initialize` function on the newly registered provider before using it to resolve flag values. +> The `provider mutator` function **MUST** await the termination `initialize` function on the newly registered provider before using it to resolve flag values. The `provider's` readiness can state can be determined from its `status` member/accessor. +Provider instances which are already active (because they have been bound to other `names` or otherwise) need not be initialized again. See [provider initialization](./02-providers.md#24-initialization). @@ -47,7 +48,8 @@ See [provider initialization](./02-providers.md#24-initialization). > The `provider mutator` function **MUST** invoke the `shutdown` function on the previously registered provider once it's no longer being used to resolve flag values. -Setting a new provider means the previous provider is no longer in use, and should therefore be disposed of using its `shutdown` function. +When a provider is no longer in use, it should be disposed of using its `shutdown` mechanism. +Provider instances which are bound to multiple names won't be shut down until the last binding is removed. see: [shutdown](./02-providers.md#25-shutdown), [setting a provider](#setting-a-provider) @@ -274,9 +276,9 @@ See [hooks](./04-hooks.md) for details. #### Requirement 1.6.1 -> The API **MUST** define a `shutdown` function which, when called, must call the respective `shutdown` function on the active provider. +> The API **MUST** define a mechanism to propagate a shutdown request to active providers. -The precise name of this function is not prescribed by this specification, but should be defined be the SDK. -Relevant language idioms should be considered when choosing the name for this function, in accordance with the resource-disposal semantics of the language in question. +The global API object might expose a `shutdown` function, which will call the respective `shutdown` function on the registered providers. +Alternatively, implementations might leverage language idioms such as auto-disposable interfaces or some means of cancellation signal propagation to allow for graceful shutdown. see: [`shutdown`](./02-providers.md#25-shutdown) diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index da562118..08f75620 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -236,7 +236,8 @@ see: [error codes](https://openfeature.dev/specification/types#error-code) #### Requirement 2.5.1 -> The provider **MAY** define a `shutdown` function to perform whatever cleanup is necessary for the implementation. +> The provider **MAY** define a mechanism to gracefully shutdown and dispose of resources. + ```java // MyProvider implementation of the dispose function defined in Provider class MyProvider implements Provider, AutoDisposable { @@ -249,6 +250,5 @@ class MyProvider implements Provider, AutoDisposable { ``` Providers may maintain remote connections, timers, threads or other constructs that need to be appropriately disposed of. -Provider authors may implement the `shutdown` function to perform relevant clean-up actions. -The precise name of this function is not prescribed by this specification, but should be defined be the SDK. -Relevant language idioms should be considered when choosing the name for this function, in accordance with the resource-disposal semantics of the language in question. \ No newline at end of file +Provider authors may implement a `shutdown` function to perform relevant clean-up actions. +Alternatively, implementations might leverage language idioms such as auto-disposable interfaces or some means of cancellation signal propagation to allow for graceful shutdown. \ No newline at end of file From 9f7e36ebb24796702c3d8efa5024e70301a0007f Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Wed, 31 May 2023 14:26:33 -0400 Subject: [PATCH 2/3] fixup: "of the" Signed-off-by: Todd Baert --- specification.json | 2 +- specification/sections/01-flag-evaluation.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification.json b/specification.json index 773eb6c0..88ec4eba 100644 --- a/specification.json +++ b/specification.json @@ -17,7 +17,7 @@ { "id": "Requirement 1.1.2.2", "machine_id": "requirement_1_1_2_2", - "content": "The `provider mutator` function MUST await the termination `initialize` function on the newly registered provider before using it to resolve flag values.", + "content": "The `provider mutator` function MUST await the termination of the `initialize` function on the newly registered provider before using it to resolve flag values.", "RFC 2119 keyword": "MUST", "children": [] }, diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 9af52ab2..c9dc1504 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -37,7 +37,7 @@ See [provider](./02-providers.md) for details. #### Requirement 1.1.2.2 -> The `provider mutator` function **MUST** await the termination `initialize` function on the newly registered provider before using it to resolve flag values. +> The `provider mutator` function **MUST** await the termination of the `initialize` function on the newly registered provider before using it to resolve flag values. The `provider's` readiness can state can be determined from its `status` member/accessor. Provider instances which are already active (because they have been bound to other `names` or otherwise) need not be initialized again. From 9f5a08468eb413ca42677e4a83ba4f5076ffc2e7 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Fri, 2 Jun 2023 09:43:05 -0400 Subject: [PATCH 3/3] fixup: revert await init change Signed-off-by: Todd Baert --- specification.json | 2 +- specification/sections/01-flag-evaluation.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/specification.json b/specification.json index 88ec4eba..505644cf 100644 --- a/specification.json +++ b/specification.json @@ -17,7 +17,7 @@ { "id": "Requirement 1.1.2.2", "machine_id": "requirement_1_1_2_2", - "content": "The `provider mutator` function MUST await the termination of the `initialize` function on the newly registered provider before using it to resolve flag values.", + "content": "The `provider mutator` function MUST invoke the `initialize` function on the newly registered provider before using it to resolve flag values.", "RFC 2119 keyword": "MUST", "children": [] }, diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index c9dc1504..5e5a3492 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -37,12 +37,13 @@ See [provider](./02-providers.md) for details. #### Requirement 1.1.2.2 -> The `provider mutator` function **MUST** await the termination of the `initialize` function on the newly registered provider before using it to resolve flag values. +> The `provider mutator` function **MUST** invoke the `initialize` function on the newly registered provider before using it to resolve flag values. -The `provider's` readiness can state can be determined from its `status` member/accessor. +Application authors can await the newly set `provider's` readiness using the `PROVIDER_READY` event. Provider instances which are already active (because they have been bound to other `names` or otherwise) need not be initialized again. +The `provider's` readiness can state can be determined from its `status` member/accessor. -See [provider initialization](./02-providers.md#24-initialization). +See [event handlers and initialization](./05-events.md#event-handlers-and-initialization), [provider initialization](./02-providers.md#24-initialization). #### Requirement 1.1.2.3