feat: Add events to the multi provider

src/OpenFeature.Providers.MultiProvider/MultiProvider.cs

@@ -28,7 +28,11 @@ public sealed class MultiProvider : FeatureProvider, IAsyncDisposable
     private ProviderStatus _providerStatus = ProviderStatus.NotReady;
     // 0 = Not disposed, 1 = Disposed
     // This is to handle the dispose pattern correctly with the async initialization and shutdown methods
-    private volatile int _disposed = 0;
+    private volatile int _disposed;
+
+    // Event handling infrastructure
+    private readonly Dictionary<FeatureProvider, Task> _eventListeningTasks = [];
+    private readonly CancellationTokenSource _eventProcessingCancellation = new();
 
     /// <summary>
     /// Initializes a new instance of the <see cref="MultiProvider"/> class with the specified provider entries and evaluation strategy.
@@ -53,6 +57,9 @@ public MultiProvider(IEnumerable<ProviderEntry> providerEntries, BaseEvaluationS
 
         // Create aggregate metadata
         this._metadata = new Metadata(MultiProviderConstants.ProviderName);
+
+        // Start listening to events from all registered providers
+        this.StartListeningToProviderEvents();
     }
 
     /// <inheritdoc/>
@@ -78,7 +85,6 @@ public override Task<ResolutionDetails<string>> ResolveStringValueAsync(string f
     public override Task<ResolutionDetails<Value>> ResolveStructureValueAsync(string flagKey, Value defaultValue, EvaluationContext? context = null, CancellationToken cancellationToken = default) =>
         this.EvaluateAsync(flagKey, defaultValue, context, cancellationToken);
 
-
     /// <inheritdoc/>
     public override async Task InitializeAsync(EvaluationContext context, CancellationToken cancellationToken = default)
     {
@@ -118,13 +124,31 @@ public override async Task InitializeAsync(EvaluationContext context, Cancellati
                 var exceptions = failures.Select(f => f.Error!).ToList();
                 var failedProviders = failures.Select(f => f.ProviderName).ToList();
                 this._providerStatus = ProviderStatus.Fatal;
+
+                // Emit error event
+                await this.EmitEvent(new ProviderEventPayload
+                {
+                    ProviderName = this._metadata.Name,
+                    Type = ProviderEventTypes.ProviderError,
+                    Message = $"Failed to initialize providers: {string.Join(", ", failedProviders)}",
+                    ErrorType = ErrorType.ProviderFatal
+                }, cancellationToken).ConfigureAwait(false);
+
                 throw new AggregateException(
                     $"Failed to initialize providers: {string.Join(", ", failedProviders)}",
                     exceptions);
             }
             else
             {
                 this._providerStatus = ProviderStatus.Ready;
+
+                // Emit ready event
+                await this.EmitEvent(new ProviderEventPayload
+                {
+                    ProviderName = this._metadata.Name,
+                    Type = ProviderEventTypes.ProviderReady,
+                    Message = "MultiProvider successfully initialized"
+                }, cancellationToken).ConfigureAwait(false);
             }
         }
         finally
@@ -154,16 +178,51 @@ private async Task<ResolutionDetails<T>> EvaluateAsync<T>(string key, T defaultV
             throw new ObjectDisposedException(nameof(MultiProvider));
         }
 
-        var strategyContext = new StrategyEvaluationContext<T>(key);
-        var resolutions = this._evaluationStrategy.RunMode switch
+        try
         {
-            RunMode.Parallel => await this.ParallelEvaluationAsync(key, defaultValue, evaluationContext, cancellationToken).ConfigureAwait(false),
-            RunMode.Sequential => await this.SequentialEvaluationAsync(key, defaultValue, evaluationContext, cancellationToken).ConfigureAwait(false),
-            _ => throw new NotSupportedException($"Unsupported run mode: {this._evaluationStrategy.RunMode}")
-        };
+            var strategyContext = new StrategyEvaluationContext<T>(key);
+            var resolutions = this._evaluationStrategy.RunMode switch
+            {
+                RunMode.Parallel => await this
+                    .ParallelEvaluationAsync(key, defaultValue, evaluationContext, cancellationToken)
+                    .ConfigureAwait(false),
+                RunMode.Sequential => await this
+                    .SequentialEvaluationAsync(key, defaultValue, evaluationContext, cancellationToken)
+                    .ConfigureAwait(false),
+                _ => throw new NotSupportedException($"Unsupported run mode: {this._evaluationStrategy.RunMode}")
+            };
+
+            var finalResult = this._evaluationStrategy.DetermineFinalResult(strategyContext, key, defaultValue,
+                evaluationContext, resolutions);
+            return finalResult.Details;
+        }
+        catch (NotSupportedException ex)
+        {
+            // Emit error event for unsupported run mode
+            await this.EmitEvent(new ProviderEventPayload
+            {
+                ProviderName = this._metadata.Name,
+                Type = ProviderEventTypes.ProviderError,
+                Message = $"Error evaluating flag '{key}' with run mode {this._evaluationStrategy.RunMode}",
+                ErrorType = ErrorType.ProviderFatal
+            }, cancellationToken).ConfigureAwait(false);
 
-        var finalResult = this._evaluationStrategy.DetermineFinalResult(strategyContext, key, defaultValue, evaluationContext, resolutions);
-        return finalResult.Details;
+            return new ResolutionDetails<T>(key, defaultValue, ErrorType.ProviderFatal, Reason.Error, errorMessage: ex.Message);
+        }
+        catch (Exception ex)
+        {
+            // Emit error event for evaluation failures
+            await this.EmitEvent(new ProviderEventPayload
+            {
+                ProviderName = this._metadata.Name,
+                Type = ProviderEventTypes.ProviderError,
+                Message = $"Error evaluating flag '{key}': {ex.Message}",
+                ErrorType = ErrorType.General,
+                FlagsChanged = [key]
+            }, cancellationToken).ConfigureAwait(false);
+
+            return new ResolutionDetails<T>(key, defaultValue, ErrorType.General, Reason.Error, errorMessage: ex.Message);
+        }
     }
 
     private async Task<List<ProviderResolutionResult<T>>> SequentialEvaluationAsync<T>(string key, T defaultValue, EvaluationContext? evaluationContext, CancellationToken cancellationToken)
@@ -220,6 +279,162 @@ private async Task<List<ProviderResolutionResult<T>>> ParallelEvaluationAsync<T>
         return resolutions;
     }
 
+    private void StartListeningToProviderEvents()
+    {
+        foreach (var registeredProvider in this._registeredProviders)
+        {
+            this._eventListeningTasks[registeredProvider.Provider] = this.ProcessProviderEventsAsync(registeredProvider);
+        }
+    }
+
+    private async Task ProcessProviderEventsAsync(RegisteredProvider registeredProvider)
+    {
+        var eventChannel = registeredProvider.Provider.GetEventChannel();
+        var cancellationToken = this._eventProcessingCancellation.Token;
+
+        while (await eventChannel.Reader.WaitToReadAsync(cancellationToken).ConfigureAwait(false))
+        {
+            while (eventChannel.Reader.TryRead(out var item))
+            {
+                if (cancellationToken.IsCancellationRequested)
+                {
+                    return;
+                }
+
+                if (item is not Event { EventPayload: { } eventPayload })
+                {
+                    continue;
+                }
+
+                await this.HandleProviderEventAsync(registeredProvider, eventPayload, cancellationToken).ConfigureAwait(false);
+            }
+        }
+    }
+
+    private async Task HandleProviderEventAsync(RegisteredProvider registeredProvider, ProviderEventPayload eventPayload, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            // Handle PROVIDER_CONFIGURATION_CHANGED events specially - these are always re-emitted
+            if (eventPayload.Type == ProviderEventTypes.ProviderConfigurationChanged)
+            {
+                await this.EmitEvent(new ProviderEventPayload
+                {
+                    ProviderName = $"{this._metadata.Name}/{registeredProvider.Name}",
+                    Type = eventPayload.Type,
+                    Message = eventPayload.Message ?? $"Configuration changed in provider {registeredProvider.Name}",
+                    FlagsChanged = eventPayload.FlagsChanged,
+                    EventMetadata = eventPayload.EventMetadata
+                }, cancellationToken).ConfigureAwait(false);
+                return;
+            }
+
+            // For status-changing events, update provider status and check if MultiProvider status should change
+            UpdateProviderStatusFromEvent(registeredProvider, eventPayload);
+
+            // Check if MultiProvider status has changed due to this provider's status change
+            var providerStatuses = this._registeredProviders.Select(rp => rp.Status).ToList();
+            var newMultiProviderStatus = DetermineAggregateStatus(providerStatuses);
+
+            // Only emit event if MultiProvider status actually changed
+            if (newMultiProviderStatus != this._providerStatus)
+            {
+                var previousStatus = this._providerStatus;
+                this._providerStatus = newMultiProviderStatus;
+
+                var eventType = newMultiProviderStatus switch
+                {
+                    ProviderStatus.Ready => ProviderEventTypes.ProviderReady,
+                    ProviderStatus.Error or ProviderStatus.Fatal => ProviderEventTypes.ProviderError,
+                    ProviderStatus.Stale => ProviderEventTypes.ProviderStale,
+                    _ => (ProviderEventTypes?)null
+                };
+
+                if (eventType.HasValue)
+                {
+                    await this.EmitEvent(new ProviderEventPayload
+                    {
+                        ProviderName = this._metadata.Name,
+                        Type = eventType.Value,
+                        Message = $"MultiProvider status changed from {previousStatus} to {newMultiProviderStatus} due to provider {registeredProvider.Name}",
+                        ErrorType = newMultiProviderStatus == ProviderStatus.Fatal ? ErrorType.ProviderFatal : eventPayload.ErrorType,
+                        FlagsChanged = eventPayload.FlagsChanged,
+                        EventMetadata = eventPayload.EventMetadata
+                    }, cancellationToken).ConfigureAwait(false);
+                }
+            }
+        }
+        catch (Exception ex)
+        {
+            // If there's an error processing the event, emit an error event
+            await this.EmitEvent(new ProviderEventPayload
+            {
+                ProviderName = this._metadata.Name,
+                Type = ProviderEventTypes.ProviderError,
+                Message = $"Error processing event from provider {registeredProvider.Name}: {ex.Message}",
+                ErrorType = ErrorType.General
+            }, cancellationToken).ConfigureAwait(false);
+        }
+    }
+
+    private static void UpdateProviderStatusFromEvent(RegisteredProvider registeredProvider, ProviderEventPayload eventPayload)
+    {
+        var newStatus = eventPayload.Type switch
+        {
+            ProviderEventTypes.ProviderReady => ProviderStatus.Ready,
+            ProviderEventTypes.ProviderError => eventPayload.ErrorType == ErrorType.ProviderFatal
+                ? ProviderStatus.Fatal
+                : ProviderStatus.Error,
+            ProviderEventTypes.ProviderStale => ProviderStatus.Stale,
+            _ => registeredProvider.Status // No status change for PROVIDER_CONFIGURATION_CHANGED
+        };
+
+        if (newStatus != registeredProvider.Status)
+        {
+            registeredProvider.SetStatus(newStatus);
+        }
+    }
+
+    private async Task EmitEvent(ProviderEventPayload eventPayload, CancellationToken cancellationToken)
+    {
+        try
+        {
+            await this.EventChannel.Writer.WriteAsync(eventPayload, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception)
+        {
+            // If we can't write to the event channel (e.g., it's closed), ignore the error
+        }
+    }
+
+    private static ProviderStatus DetermineAggregateStatus(List<ProviderStatus> providerStatuses)
+    {
+        // Check in precedence order as per specification
+        if (providerStatuses.Any(status => status == ProviderStatus.Fatal))
+        {
+            return ProviderStatus.Fatal;
+        }
+
+        if (providerStatuses.Any(status => status == ProviderStatus.NotReady))
+        {
+            return ProviderStatus.NotReady;
+        }
+
+        if (providerStatuses.Any(status => status == ProviderStatus.Error))
+        {
+            return ProviderStatus.Error;
+        }
+
+        if (providerStatuses.Any(status => status == ProviderStatus.Stale))
+        {
+            return ProviderStatus.Stale;
+        }
+
+        return providerStatuses.All(status => status == ProviderStatus.Ready) ? ProviderStatus.Ready :
+            // Default to NotReady if we have mixed statuses not covered above
+            ProviderStatus.NotReady;
+    }
+
     private static ReadOnlyCollection<RegisteredProvider> RegisterProviders(IEnumerable<ProviderEntry> providerEntries)
     {
         var entries = providerEntries.ToList();
@@ -280,15 +495,36 @@ public async ValueTask DisposeAsync()
         {
             this._initializationSemaphore.Dispose();
             this._shutdownSemaphore.Dispose();
+            this._eventProcessingCancellation.Dispose();
+        }
+    }
+
+    private async Task ShutdownEventProcessingAsync()
+    {
+        // Cancel event processing
+        this._eventProcessingCancellation.Cancel();
+
+        // Wait for all event listening tasks to complete, ignoring cancellation exceptions
+        if (this._eventListeningTasks.Count != 0)
+        {
+            try
+            {
+                await Task.WhenAll(this._eventListeningTasks.Values).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException)
+            {
+                // Expected when shutting down
+            }
         }
     }
 
     private async Task InternalShutdownAsync(CancellationToken cancellationToken)
     {
+        await this.ShutdownEventProcessingAsync().ConfigureAwait(false);
         await this._shutdownSemaphore.WaitAsync(cancellationToken).ConfigureAwait(false);
         try
         {
-            // We should be able to shutdown the provider when it is in Ready or Fatal status.
+            // We should be able to shut down the provider when it is in Ready or Fatal status.
             if ((this._providerStatus != ProviderStatus.Ready && this._providerStatus != ProviderStatus.Fatal) || this._disposed == 1)
             {
                 return;

src/OpenFeature.Providers.MultiProvider/README.md

@@ -181,6 +181,69 @@ await multiProvider.ShutdownAsync();
 await multiProvider.DisposeAsync();
 ```
 
+## Events
+
+The MultiProvider supports OpenFeature events and provides specification-compliant event handling. It follows the [OpenFeature Multi-Provider specification](https://openfeature.dev/specification/appendix-a#status-and-event-handling) for event handling behavior.
+
+### Event Handling Example
+
+```csharp
+using OpenFeature;
+using OpenFeature.Providers.MultiProvider;
+
+// Create the MultiProvider with multiple providers
+var providerEntries = new[]
+{
+    new ProviderEntry(new ProviderA(), "provider-a"),
+    new ProviderEntry(new ProviderB(), "provider-b")
+};
+var multiProvider = new MultiProvider(providerEntries);
+
+// Subscribe to MultiProvider events
+Api.Instance.AddHandler(ProviderEventTypes.ProviderReady, (eventDetails) =>
+{
+    Console.WriteLine($"MultiProvider is ready: {eventDetails?.ProviderName}");
+});
+
+Api.Instance.AddHandler(ProviderEventTypes.ProviderStale, (eventDetails) =>
+{
+    Console.WriteLine($"MultiProvider became stale: {eventDetails?.Message}");
+});
+
+Api.Instance.AddHandler(ProviderEventTypes.ProviderConfigurationChanged, (eventDetails) =>
+{
+    Console.WriteLine($"Configuration changed - Flags: {string.Join(", ", eventDetails?.FlagsChanged ?? [])}");
+});
+
+Api.Instance.AddHandler(ProviderEventTypes.ProviderError, (eventDetails) =>
+{
+    Console.WriteLine($"MultiProvider error: {eventDetails?.Message}");
+});
+
+// Set the provider - this will initialize all underlying providers
+// and emit PROVIDER_READY when all are successfully initialized
+await Api.Instance.SetProviderAsync(multiProvider);
+
+// Later, if an underlying provider becomes stale and changes MultiProvider status:
+// Only then will a PROVIDER_STALE event be emitted from MultiProvider
+```
+
+### Event Lifecycle
+
+1. **During Initialization**:
+
+    - MultiProvider emits `PROVIDER_READY` when all underlying providers initialize successfully
+    - MultiProvider emits `PROVIDER_ERROR` if any providers fail to initialize (causing aggregate status to become ERROR/FATAL)
+
+2. **Runtime Status Changes**:
+
+    - Status-changing events from underlying providers are captured internally
+    - MultiProvider only emits events when its aggregate status changes due to these internal events
+    - Example: If MultiProvider is READY and one provider becomes STALE, MultiProvider emits `PROVIDER_STALE`
+
+3. **Configuration Changes**:
+    - `PROVIDER_CONFIGURATION_CHANGED` events from underlying providers are always re-emitted
+
 ## Requirements
 
 - .NET 8+