feat: add support for eventing

README.md

@@ -167,6 +167,43 @@ client.AddHooks(new ExampleClientHook());
 var value = await client.GetBooleanValue("boolFlag", false, context, new FlagEvaluationOptions(new ExampleInvocationHook()));
 ```
 
+### Eventing
+
+Events allow you to react to state changes in the provider or underlying flag management system, such as flag definition changes,
+provider readiness, or error conditions.
+Initialization events (`PROVIDER_READY` on success, `PROVIDER_ERROR` on failure) are dispatched for every provider.
+Some providers support additional events, such as `PROVIDER_CONFIGURATION_CHANGED`.
+
+Please refer to the documentation of the provider you're using to see what events are supported.
+
+Example usage of an Event handler:
+
+```csharp
+public static void EventHandler(ProviderEventPayload eventDetails)
+{
+    Console.WriteLine(eventDetails.Type);
+}
+```
+
+```csharp
+EventHandlerDelegate callback = EventHandler;
+// add an implementation of the EventHandlerDelegate for the PROVIDER_READY event
+Api.Instance.AddHandler(ProviderEventTypes.ProviderReady, callback);
+```
+
+It is also possible to register an event handler for a specific client, as in the following example:
+
+```csharp
+EventHandlerDelegate callback = EventHandler;
+
+var myClient = Api.Instance.GetClient("my-client");
+
+var provider = new ExampleProvider();
+await Api.Instance.SetProvider(myClient.GetMetadata().Name, provider);
+
+myClient.AddHandler(ProviderEventTypes.ProviderReady, callback);
+```
+
 ### Logging
 
 The .NET SDK uses Microsoft.Extensions.Logging. See the [manual](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line) for complete documentation.

src/OpenFeature/Api.cs

@@ -4,6 +4,7 @@
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.Logging;
+using OpenFeature.Constant;
 using OpenFeature.Model;
 
 namespace OpenFeature
@@ -13,7 +14,7 @@ namespace OpenFeature
     /// In the absence of a provider the evaluation API uses the "No-op provider", which simply returns the supplied default flag value.
     /// </summary>
     /// <seealso href="https://github.com/open-feature/spec/blob/v0.5.2/specification/sections/01-flag-evaluation.md#1-flag-evaluation-api"/>
-    public sealed class Api
+    public sealed class Api : IEventBus
     {
         private EvaluationContext _evaluationContext = EvaluationContext.Empty;
         private readonly ProviderRepository _repository = new ProviderRepository();
@@ -22,6 +23,8 @@ public sealed class Api
         /// The reader/writer locks are not disposed because the singleton instance should never be disposed.
         private readonly ReaderWriterLockSlim _evaluationContextLock = new ReaderWriterLockSlim();
 
+        internal readonly EventExecutor EventExecutor = new EventExecutor();
+
 
         /// <summary>
         /// Singleton instance of Api
@@ -42,6 +45,7 @@ private Api() { }
         /// <param name="featureProvider">Implementation of <see cref="FeatureProvider"/></param>
         public async Task SetProvider(FeatureProvider featureProvider)
         {
+            this.EventExecutor.RegisterDefaultFeatureProvider(featureProvider);
             await this._repository.SetProvider(featureProvider, this.GetContext()).ConfigureAwait(false);
         }
 
@@ -54,6 +58,7 @@ public async Task SetProvider(FeatureProvider featureProvider)
         /// <param name="featureProvider">Implementation of <see cref="FeatureProvider"/></param>
         public async Task SetProvider(string clientName, FeatureProvider featureProvider)
         {
+            this.EventExecutor.RegisterClientFeatureProvider(clientName, featureProvider);
             await this._repository.SetProvider(clientName, featureProvider, this.GetContext()).ConfigureAwait(false);
         }
 
@@ -202,5 +207,17 @@ public async Task Shutdown()
         {
             await this._repository.Shutdown().ConfigureAwait(false);
         }
+
+        /// <inheritdoc />
+        public void AddHandler(ProviderEventTypes type, EventHandlerDelegate handler)
+        {
+            this.EventExecutor.AddApiLevelHandler(type, handler);
+        }
+
+        /// <inheritdoc />
+        public void RemoveHandler(ProviderEventTypes type, EventHandlerDelegate handler)
+        {
+            this.EventExecutor.RemoveApiLevelHandler(type, handler);
+        }
     }
 }

src/OpenFeature/Constant/EventType.cs

@@ -0,0 +1,25 @@
+namespace OpenFeature.Constant
+{
+    /// <summary>
+    /// The ProviderEventTypes enum represents the available event types of a provider.
+    /// </summary>
+    public enum ProviderEventTypes
+    {
+        /// <summary>
+        /// ProviderReady should be emitted by a provider upon completing its initialisation.
+        /// </summary>
+        ProviderReady,
+        /// <summary>
+        /// ProviderError should be emitted by a provider upon encountering an error.
+        /// </summary>
+        ProviderError,
+        /// <summary>
+        /// ProviderConfigurationChanged should be emitted by a provider when a flag configuration has been changed.
+        /// </summary>
+        ProviderConfigurationChanged,
+        /// <summary>
+        /// ProviderStale should be emitted by a provider when it goes into the stale state.
+        /// </summary>
+        ProviderStale
+    }
+}