fix: various clarifications (#193)

* loosen shutdown requirements to support things like go ctx
* clarify how to handle init/shutdown of providers bound to multiple names
* clarify that authors can await the READY event during init

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

specification.json

@@ -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": []
         },

specification/sections/01-flag-evaluation.md

@@ -39,15 +39,18 @@ See [provider](./02-providers.md) for details.
 
 > The `provider mutator` function **MUST** invoke the `initialize` function on the newly registered provider before using it to resolve flag values.
 
+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
 
 >  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 +277,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)

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.
+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.