Add Dependency Injection code to Hosting package

Signed-off-by: Kyle Julian <[email protected]>

Author: kylejuliandev

src/OpenFeature.Hosting/DependencyInjection/Diagnostics/FeatureCodes.cs

@@ -0,0 +1,38 @@
+namespace OpenFeature.DependencyInjection.Diagnostics;
+
+/// <summary>
+/// Contains identifiers for experimental features and diagnostics in the OpenFeature framework.
+/// </summary>
+/// <remarks>
+/// <c>Experimental</c> - This class includes identifiers that allow developers to track and conditionally enable
+/// experimental features. Each identifier follows a structured code format to indicate the feature domain,
+/// maturity level, and unique identifier. Note that experimental features are subject to change or removal 
+/// in future releases.
+/// <para>
+/// <strong>Basic Information</strong><br/>
+/// These identifiers conform to OpenFeature’s Diagnostics Specifications, allowing developers to recognize 
+/// and manage experimental features effectively.
+/// </para>
+/// </remarks>
+/// <example>
+/// <code>
+/// Code Structure:
+///     - "OF" - Represents the OpenFeature library.
+///     - "DI" - Indicates the Dependency Injection domain.
+///     - "001" - Unique identifier for a specific feature.
+/// </code>
+/// </example>
+internal static class FeatureCodes
+{
+    /// <summary>
+    /// Identifier for the experimental Dependency Injection features within the OpenFeature framework.
+    /// </summary>
+    /// <remarks>
+    /// <c>OFDI001</c> identifier marks experimental features in the Dependency Injection (DI) domain.
+    /// 
+    /// Usage:
+    /// Developers can use this identifier to conditionally enable or test experimental DI features.
+    /// It is part of the OpenFeature diagnostics system to help track experimental functionality.
+    /// </remarks>
+    public const string NewDi = "OFDI001";
+}

src/OpenFeature.Hosting/DependencyInjection/Guard.cs

@@ -0,0 +1,20 @@
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+
+namespace OpenFeature.DependencyInjection;
+
+[DebuggerStepThrough]
+internal static class Guard
+{
+    public static void ThrowIfNull(object? argument, [CallerArgumentExpression(nameof(argument))] string? paramName = null)
+    {
+        if (argument is null)
+            throw new ArgumentNullException(paramName);
+    }
+
+    public static void ThrowIfNullOrWhiteSpace(string? argument, [CallerArgumentExpression(nameof(argument))] string? paramName = null)
+    {
+        if (string.IsNullOrWhiteSpace(argument))
+            throw new ArgumentNullException(paramName);
+    }
+}

src/OpenFeature.Hosting/DependencyInjection/IFeatureLifecycleManager.cs

@@ -0,0 +1,24 @@
+namespace OpenFeature.DependencyInjection;
+
+/// <summary>
+/// Defines the contract for managing the lifecycle of a feature api.
+/// </summary>
+public interface IFeatureLifecycleManager
+{
+    /// <summary>
+    /// Ensures that the feature provider is properly initialized and ready to be used.
+    /// This method should handle all necessary checks, configuration, and setup required to prepare the feature provider.
+    /// </summary>
+    /// <param name="cancellationToken">Propagates notification that operations should be canceled.</param>
+    /// <returns>A Task representing the asynchronous operation of initializing the feature provider.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the feature provider is not registered or is in an invalid state.</exception>
+    ValueTask EnsureInitializedAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gracefully shuts down the feature api, ensuring all resources are properly disposed of and any persistent state is saved.
+    /// This method should handle all necessary cleanup and shutdown operations for the feature provider.
+    /// </summary>
+    /// <param name="cancellationToken">Propagates notification that operations should be canceled.</param>
+    /// <returns>A Task representing the asynchronous operation of shutting down the feature provider.</returns>
+    ValueTask ShutdownAsync(CancellationToken cancellationToken = default);
+}

src/OpenFeature.Hosting/DependencyInjection/Internal/EventHandlerDelegateWrapper.cs

@@ -0,0 +1,8 @@
+using OpenFeature.Constant;
+using OpenFeature.Model;
+
+namespace OpenFeature.DependencyInjection.Internal;
+
+internal record EventHandlerDelegateWrapper(
+    ProviderEventTypes ProviderEventType,
+    EventHandlerDelegate EventHandlerDelegate);

src/OpenFeature.Hosting/DependencyInjection/Internal/FeatureLifecycleManager.cs

@@ -0,0 +1,66 @@
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace OpenFeature.DependencyInjection.Internal;
+
+internal sealed partial class FeatureLifecycleManager : IFeatureLifecycleManager
+{
+    private readonly Api _featureApi;
+    private readonly IServiceProvider _serviceProvider;
+    private readonly ILogger<FeatureLifecycleManager> _logger;
+
+    public FeatureLifecycleManager(Api featureApi, IServiceProvider serviceProvider, ILogger<FeatureLifecycleManager> logger)
+    {
+        _featureApi = featureApi;
+        _serviceProvider = serviceProvider;
+        _logger = logger;
+    }
+
+    /// <inheritdoc />
+    public async ValueTask EnsureInitializedAsync(CancellationToken cancellationToken = default)
+    {
+        this.LogStartingInitializationOfFeatureProvider();
+
+        var options = _serviceProvider.GetRequiredService<IOptions<OpenFeatureOptions>>().Value;
+        if (options.HasDefaultProvider)
+        {
+            var featureProvider = _serviceProvider.GetRequiredService<FeatureProvider>();
+            await _featureApi.SetProviderAsync(featureProvider).ConfigureAwait(false);
+        }
+
+        foreach (var name in options.ProviderNames)
+        {
+            var featureProvider = _serviceProvider.GetRequiredKeyedService<FeatureProvider>(name);
+            await _featureApi.SetProviderAsync(name, featureProvider).ConfigureAwait(false);
+        }
+
+        var hooks = new List<Hook>();
+        foreach (var hookName in options.HookNames)
+        {
+            var hook = _serviceProvider.GetRequiredKeyedService<Hook>(hookName);
+            hooks.Add(hook);
+        }
+
+        _featureApi.AddHooks(hooks);
+
+        var handlers = _serviceProvider.GetServices<EventHandlerDelegateWrapper>();
+        foreach (var handler in handlers)
+        {
+            _featureApi.AddHandler(handler.ProviderEventType, handler.EventHandlerDelegate);
+        }
+    }
+
+    /// <inheritdoc />
+    public async ValueTask ShutdownAsync(CancellationToken cancellationToken = default)
+    {
+        this.LogShuttingDownFeatureProvider();
+        await _featureApi.ShutdownAsync().ConfigureAwait(false);
+    }
+
+    [LoggerMessage(200, LogLevel.Information, "Starting initialization of the feature provider")]
+    partial void LogStartingInitializationOfFeatureProvider();
+
+    [LoggerMessage(200, LogLevel.Information, "Shutting down the feature provider")]
+    partial void LogShuttingDownFeatureProvider();
+}

src/OpenFeature.Hosting/DependencyInjection/MultiTarget/CallerArgumentExpressionAttribute.cs

@@ -0,0 +1,23 @@
+// @formatter:off
+// ReSharper disable All
+#if NETCOREAPP3_0_OR_GREATER
+// https://github.com/dotnet/runtime/issues/96197
+[assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(System.Runtime.CompilerServices.CallerArgumentExpressionAttribute))]
+#else
+#pragma warning disable
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace System.Runtime.CompilerServices;
+
+[AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false, Inherited = false)]
+internal sealed class CallerArgumentExpressionAttribute : Attribute
+{
+    public CallerArgumentExpressionAttribute(string parameterName)
+    {
+        ParameterName = parameterName;
+    }
+
+    public string ParameterName { get; }
+}
+#endif

src/OpenFeature.Hosting/DependencyInjection/MultiTarget/IsExternalInit.cs

@@ -0,0 +1,21 @@
+// @formatter:off
+// ReSharper disable All
+#if NET5_0_OR_GREATER
+// https://github.com/dotnet/runtime/issues/96197
+[assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(System.Runtime.CompilerServices.IsExternalInit))]
+#else
+#pragma warning disable
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.ComponentModel;
+
+namespace System.Runtime.CompilerServices;
+
+/// <summary>
+/// Reserved to be used by the compiler for tracking metadata.
+/// This class should not be used by developers in source code.
+/// </summary>
+[EditorBrowsable(EditorBrowsableState.Never)]
+static class IsExternalInit { }
+#endif

src/OpenFeature.Hosting/DependencyInjection/OpenFeatureBuilder.cs

@@ -0,0 +1,60 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace OpenFeature.DependencyInjection;
+
+/// <summary>
+/// Describes a <see cref="OpenFeatureBuilder"/> backed by an <see cref="IServiceCollection"/>.
+/// </summary>
+/// <param name="services">The services being configured.</param>
+public class OpenFeatureBuilder(IServiceCollection services)
+{
+    /// <summary> The services being configured. </summary>
+    public IServiceCollection Services { get; } = services;
+
+    /// <summary>
+    /// Indicates whether the evaluation context has been configured.
+    /// This property is used to determine if specific configurations or services
+    /// should be initialized based on the presence of an evaluation context.
+    /// </summary>
+    public bool IsContextConfigured { get; internal set; }
+
+    /// <summary>
+    /// Indicates whether the policy has been configured.
+    /// </summary>
+    public bool IsPolicyConfigured { get; internal set; }
+
+    /// <summary>
+    /// Gets a value indicating whether a default provider has been registered.
+    /// </summary>
+    public bool HasDefaultProvider { get; internal set; }
+
+    /// <summary>
+    /// Gets the count of domain-bound providers that have been registered.
+    /// This count does not include the default provider.
+    /// </summary>
+    public int DomainBoundProviderRegistrationCount { get; internal set; }
+
+    /// <summary>
+    /// Validates the current configuration, ensuring that a policy is set when multiple providers are registered
+    /// or when a default provider is registered alongside another provider.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown if multiple providers are registered without a policy, or if both a default provider 
+    /// and an additional provider are registered without a policy configuration.
+    /// </exception>
+    public void Validate()
+    {
+        if (!IsPolicyConfigured)
+        {
+            if (DomainBoundProviderRegistrationCount > 1)
+            {
+                throw new InvalidOperationException("Multiple providers have been registered, but no policy has been configured.");
+            }
+
+            if (HasDefaultProvider && DomainBoundProviderRegistrationCount == 1)
+            {
+                throw new InvalidOperationException("A default provider and an additional provider have been registered without a policy configuration.");
+            }
+        }
+    }
+}