feat!: internally maintain provider status

src/OpenFeature/Api.cs

@@ -6,6 +6,7 @@
 using System.Threading.Tasks;
 using Microsoft.Extensions.Logging;
 using OpenFeature.Constant;
+using OpenFeature.Error;
 using OpenFeature.Model;
 
 namespace OpenFeature
@@ -37,18 +38,17 @@ static Api() { }
  private Api() { }
 
  /// <summary>
- /// Sets the feature provider. In order to wait for the provider to be set, and initialization to complete,
+ /// Sets the default feature provider. In order to wait for the provider to be set, and initialization to complete,
  /// await the returned task.
  /// </summary>
  /// <remarks>The provider cannot be set to null. Attempting to set the provider to null has no effect.</remarks>
  /// <param name="featureProvider">Implementation of <see cref="FeatureProvider"/></param>
  public async Task SetProviderAsync(FeatureProvider featureProvider)
  {
  this._eventExecutor.RegisterDefaultFeatureProvider(featureProvider);
- await this._repository.SetProviderAsync(featureProvider, this.GetContext()).ConfigureAwait(false);
+ await this._repository.SetProviderAsync(featureProvider, this.GetContext(), AfterInitialization, AfterError).ConfigureAwait(false);
  }
 
-
  /// <summary>
  /// Sets the feature provider to given clientName. In order to wait for the provider to be set, and
  /// initialization to complete, await the returned task.
@@ -62,7 +62,7 @@ public async Task SetProviderAsync(string clientName, FeatureProvider featurePro
  throw new ArgumentNullException(nameof(clientName));
  }
  this._eventExecutor.RegisterClientFeatureProvider(clientName, featureProvider);
- await this._repository.SetProviderAsync(clientName, featureProvider, this.GetContext()).ConfigureAwait(false);
+ await this._repository.SetProviderAsync(clientName, featureProvider, this.GetContext(), AfterInitialization, AfterError).ConfigureAwait(false);
  }
 
  /// <summary>
@@ -121,7 +121,7 @@ public FeatureProvider GetProvider(string clientName)
  /// <returns><see cref="FeatureClient"/></returns>
  public FeatureClient GetClient(string? name = null, string? version = null, ILogger? logger = null,
  EvaluationContext? context = null) =>
- new FeatureClient(name, version, logger, context);
+ new FeatureClient(() => _repository.GetProvider(name), name, version, logger, context);
 
  /// <summary>
  /// Appends list of hooks to global hooks list
@@ -258,12 +258,46 @@ public void RemoveHandler(ProviderEventTypes type, EventHandlerDelegate handler)
  public void SetLogger(ILogger logger)
  {
  this._eventExecutor.SetLogger(logger);
+ this._repository.SetLogger(logger);
  }
 
  internal void AddClientHandler(string client, ProviderEventTypes eventType, EventHandlerDelegate handler)
  => this._eventExecutor.AddClientHandler(client, eventType, handler);
 
  internal void RemoveClientHandler(string client, ProviderEventTypes eventType, EventHandlerDelegate handler)
  => this._eventExecutor.RemoveClientHandler(client, eventType, handler);
+
+ /// <summary>
+ /// Update the provider state to READY and emit a READY event after successful init.
+ /// </summary>
+ private async Task AfterInitialization(FeatureProvider provider)
+ {
+ provider.Status = ProviderStatus.Ready;
+ var eventPayload = new ProviderEventPayload
+ {
+ Type = ProviderEventTypes.ProviderReady,
+ Message = "Provider initialization complete",
+ ProviderName = provider.GetMetadata().Name,
+ };
+
+ await this._eventExecutor.EventChannel.Writer.WriteAsync(new Event { Provider = provider, EventPayload = eventPayload }).ConfigureAwait(false);
+ }
+
+ /// <summary>
+ /// Update the provider state to ERROR and emit an ERROR after failed init.
+ /// </summary>
+ private async Task AfterError(FeatureProvider provider, Exception ex)
+
+ {
+ provider.Status = typeof(ProviderFatalException) == ex.GetType() ? ProviderStatus.Fatal : ProviderStatus.Error;
+ var eventPayload = new ProviderEventPayload
+ {
+ Type = ProviderEventTypes.ProviderError,
+ Message = $"Provider initialization error: {ex?.Message}",
+ ProviderName = provider.GetMetadata()?.Name,
+ };
+
+ await this._eventExecutor.EventChannel.Writer.WriteAsync(new Event { Provider = provider, EventPayload = eventPayload }).ConfigureAwait(false);
+ }
  }
 }

src/OpenFeature/Constant/ErrorType.cs

@@ -47,5 +47,10 @@ public enum ErrorType
  /// Context does not contain a targeting key and the provider requires one.
  /// </summary>
  [Description("TARGETING_KEY_MISSING")] TargetingKeyMissing,
+
+ /// <summary>
+ /// The provider has entered an irrecoverable error state.
+ /// </summary>
+ [Description("PROVIDER_FATAL")] ProviderFatal,
  }
 }

src/OpenFeature/Constant/ProviderStatus.cs

@@ -26,6 +26,11 @@ public enum ProviderStatus
  /// <summary>
  /// The provider is in an error state and unable to evaluate flags.
  /// </summary>
- [Description("ERROR")] Error
+ [Description("ERROR")] Error,
+
+ /// <summary>
+ /// The provider has entered an irrecoverable error state.
+ /// </summary>
+ [Description("FATAL")] Fatal,
  }
 }

src/OpenFeature/Error/ProviderFatalException.cs

@@ -0,0 +1,23 @@
+using System;
+using System.Diagnostics.CodeAnalysis;
+using OpenFeature.Constant;
+
+namespace OpenFeature.Error
+{
+ /// <summary> the
+ /// An exception that signals the provider has entered an irrecoverable error state.
+ /// </summary>
+ [ExcludeFromCodeCoverage]
+ public class ProviderFatalException : FeatureProviderException
+ {
+ /// <summary>
+ /// Initialize a new instance of the <see cref="ProviderFatalException"/> class
+ /// </summary>
+ /// <param name="message">Exception message</param>
+ /// <param name="innerException">Optional inner exception</param>
+ public ProviderFatalException(string? message = null, Exception? innerException = null)
+ : base(ErrorType.ProviderFatal, message, innerException)
+ {
+ }
+ }
+}

src/OpenFeature/Error/ProviderNotReadyException.cs

@@ -5,7 +5,7 @@
 namespace OpenFeature.Error
 {
  /// <summary>
- /// Provider has yet been initialized when evaluating a flag.
+ /// Provider has not yet been initialized when evaluating a flag.
  /// </summary>
  [ExcludeFromCodeCoverage]
  public class ProviderNotReadyException : FeatureProviderException

src/OpenFeature/EventExecutor.cs

@@ -184,7 +184,7 @@ private void EmitOnRegistration(FeatureProvider? provider, ProviderEventTypes ev
  {
  return;
  }
- var status = provider.GetStatus();
+ var status = provider.Status;
 
  var message = "";
  if (status == ProviderStatus.Ready && eventType == ProviderEventTypes.ProviderReady)
@@ -234,6 +234,7 @@ private async void ProcessFeatureProviderEventsAsync(object? providerRef)
  switch (item)
  {
  case ProviderEventPayload eventPayload:
+ this.UpdateProviderStatus(typedProviderRef, eventPayload);
  await this.EventChannel.Writer.WriteAsync(new Event { Provider = typedProviderRef, EventPayload = eventPayload }).ConfigureAwait(false);
  break;
  }
@@ -307,6 +308,24 @@ private async void ProcessEventAsync()
  }
  }
 
+ // map events to provider status as per spec: https://openfeature.dev/specification/sections/events/#requirement-535
+ private void UpdateProviderStatus(FeatureProvider provider, ProviderEventPayload eventPayload)
+ {
+ switch (eventPayload.Type)
+ {
+ case ProviderEventTypes.ProviderReady:
+ provider.Status = ProviderStatus.Ready;
+ break;
+ case ProviderEventTypes.ProviderStale:
+ provider.Status = ProviderStatus.Stale;
+ break;
+ case ProviderEventTypes.ProviderError:
+ provider.Status = eventPayload.ErrorType == ErrorType.ProviderFatal ? ProviderStatus.Fatal : ProviderStatus.Error;
+ break;
+ default: break;
+ }
+ }
+
  private void InvokeEventHandler(EventHandlerDelegate eventHandler, Event e)
  {
  try

src/OpenFeature/FeatureProvider.cs

@@ -1,10 +1,12 @@
 using System.Collections.Immutable;
+using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Channels;
 using System.Threading.Tasks;
 using OpenFeature.Constant;
 using OpenFeature.Model;
 
+[assembly: InternalsVisibleTo("DynamicProxyGenAssembly2")] // required to allow NSubstitute mocking of internal methods
 namespace OpenFeature
 {
  /// <summary>
@@ -94,35 +96,25 @@ public abstract Task<ResolutionDetails<Value>> ResolveStructureValueAsync(string
  EvaluationContext? context = null, CancellationToken cancellationToken = default);
 
  /// <summary>
- /// Get the status of the provider.
+ /// Internally-managed provider status.
+ /// The SDK uses this field to track the status of the provider.
+ /// Not visible outside OpenFeature assembly
  /// </summary>
- /// <returns>The current <see cref="ProviderStatus"/></returns>
- /// <remarks>
- /// If a provider does not override this method, then its status will be assumed to be
- /// <see cref="ProviderStatus.Ready"/>. If a provider implements this method, and supports initialization,
- /// then it should start in the <see cref="ProviderStatus.NotReady"/>status . If the status is
- /// <see cref="ProviderStatus.NotReady"/>, then the Api will call the <see cref="InitializeAsync" /> when the
- /// provider is set.
- /// </remarks>
- public virtual ProviderStatus GetStatus() => ProviderStatus.Ready;
+ internal virtual ProviderStatus Status { get; set; } = ProviderStatus.NotReady;
 
  /// <summary>
  /// <para>
  /// This method is called before a provider is used to evaluate flags. Providers can overwrite this method,
  /// if they have special initialization needed prior being called for flag evaluation.
+ /// When this method completes, the provider will be considered ready for use.
  /// </para>
  /// </summary>
  /// <param name="context"><see cref="EvaluationContext"/></param>
  /// <param name="cancellationToken">The <see cref="CancellationToken"/> to cancel any async side effects.</param>
  /// <returns>A task that completes when the initialization process is complete.</returns>
  /// <remarks>
  /// <para>
- /// A provider which supports initialization should override this method as well as
- /// <see cref="GetStatus"/>.
- /// </para>
- /// <para>
- /// The provider should return <see cref="ProviderStatus.Ready"/> or <see cref="ProviderStatus.Error"/> from
- /// the <see cref="GetStatus"/> method after initialization is complete.
+ /// Providers not implementing this method will be considered ready immediately.
  /// </para>
  /// </remarks>
  public virtual Task InitializeAsync(EvaluationContext context, CancellationToken cancellationToken = default)

src/OpenFeature/IFeatureClient.cs

@@ -1,6 +1,7 @@
 using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
+using OpenFeature.Constant;
 using OpenFeature.Model;
 
 namespace OpenFeature
@@ -53,6 +54,12 @@ public interface IFeatureClient : IEventBus
  /// <returns>Client metadata <see cref="ClientMetadata"/></returns>
  ClientMetadata GetMetadata();
 
+ /// <summary>
+ /// Returns the current status of the associated provider.
+ /// </summary>
+ /// <returns><see cref="ProviderStatus"/></returns>
+ ProviderStatus ProviderStatus { get; }
+
  /// <summary>
  /// Resolves a boolean feature flag
  /// </summary>

src/OpenFeature/Model/ProviderEvents.cs

@@ -28,6 +28,11 @@ public class ProviderEventPayload
  /// </summary>
  public string? Message { get; set; }
 
+ /// <summary>
+ /// Optional error associated with the event. 
+ /// </summary>
+ public ErrorType? ErrorType { get; set; }
+
  /// <summary>
  /// A List of flags that have been changed.
  /// </summary>

src/OpenFeature/OpenFeatureClient.cs

@@ -21,6 +21,7 @@ public sealed partial class FeatureClient : IFeatureClient
  private readonly ClientMetadata _metadata;
  private readonly ConcurrentStack<Hook> _hooks = new ConcurrentStack<Hook>();
  private readonly ILogger _logger;
+ private readonly Func<FeatureProvider> _providerAccessor;
  private EvaluationContext _evaluationContext;
 
  private readonly object _evaluationContextLock = new object();
@@ -48,6 +49,9 @@ public sealed partial class FeatureClient : IFeatureClient
  return (method(provider), provider);
  }
 
+ /// <inheritdoc />
+ public ProviderStatus ProviderStatus => this._providerAccessor.Invoke().Status;
+
  /// <inheritdoc />
  public EvaluationContext GetContext()
  {
@@ -69,16 +73,18 @@ public void SetContext(EvaluationContext? context)
  /// <summary>
  /// Initializes a new instance of the <see cref="FeatureClient"/> class.
  /// </summary>
+ /// <param name="providerAccessor">Function to retrieve current provider</param>
  /// <param name="name">Name of client <see cref="ClientMetadata"/></param>
  /// <param name="version">Version of client <see cref="ClientMetadata"/></param>
  /// <param name="logger">Logger used by client</param>
  /// <param name="context">Context given to this client</param>
  /// <exception cref="ArgumentNullException">Throws if any of the required parameters are null</exception>
- public FeatureClient(string? name, string? version, ILogger? logger = null, EvaluationContext? context = null)
+ internal FeatureClient(Func<FeatureProvider> providerAccessor, string? name, string? version, ILogger? logger = null, EvaluationContext? context = null)
  {
  this._metadata = new ClientMetadata(name, version);
  this._logger = logger ?? NullLogger<FeatureClient>.Instance;
  this._evaluationContext = context ?? EvaluationContext.Empty;
+ this._providerAccessor = providerAccessor;
  }
 
  /// <inheritdoc />
@@ -246,6 +252,16 @@ private async Task<FlagEvaluationDetails<T>> EvaluateFlagAsync<T>(
  {
  var contextFromHooks = await this.TriggerBeforeHooksAsync(allHooks, hookContext, options, cancellationToken).ConfigureAwait(false);
 
+ // short circuit evaluation entirely if provider is in a bad state
+ if (provider.Status == ProviderStatus.NotReady)
+ {
+ throw new ProviderNotReadyException("Provider has not yet completed initialization.");
+ }
+ else if (provider.Status == ProviderStatus.Fatal)
+ {
+ throw new ProviderFatalException("Provider is in an irrecoverable error state.");
+ }
+
  evaluation =
  (await resolveValueDelegate.Invoke(flagKey, defaultValue, contextFromHooks.EvaluationContext, cancellationToken).ConfigureAwait(false))
  .ToFlagEvaluationDetails();