feat: Add multi-provider support

[askpt]

This PR

This pull request introduces the experimental "Multi-Provider" feature to the OpenFeature library, enabling simultaneous use of multiple feature flag providers with configurable evaluation strategies. The changes include updates to documentation, new classes and methods to support multi-provider functionality, and a sample implementation in AspNetCore. Below is a summary of the most important changes grouped by theme.

Documentation Updates:

• Added "Multi-Provider" to the feature list in README.md, marking it as experimental.
• Included a detailed section in README.md explaining the usage, evaluation strategies, modes, and limitations of the Multi-Provider feature.

Sample Implementation:

• Updated samples/AspNetCore/Program.cs to demonstrate Multi-Provider usage, including flag evaluation and error handling. [1] [2]

Core Multi-Provider Functionality:

• Introduced the MultiProvider class in src/OpenFeature/Providers/MultiProvider/MultiProvider.cs, implementing support for multiple providers, evaluation strategies, initialization, and shutdown logic.
• Added the ProviderEntry class to represent individual providers in the Multi-Provider configuration.

Supporting Models and Extensions:

• Created ProviderStatus and RegisteredProvider models to track provider states and metadata. [1] [2]
• Added ProviderExtensions to handle evaluation logic for individual providers.

Related Issues

Fixes #487

Notes

I didn't do proper testing for Hooks and Events. This PR is already quite big, and I would appreciate some feedback on the overall design.

Follow-up Tasks

• Add Hooks and Events support for Multi-Provider.
• Add Dependency Injection support.

How to test

Open the samples app and enjoy!

[codecov]

Codecov Report

❌ Patch coverage is 95.70707% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.60%. Comparing base (2547a57) to head (6685f01).

Files with missing lines	Patch %	Lines
...enFeature/Providers/MultiProvider/MultiProvider.cs	95.67%	5 Missing and 3 partials ⚠️
...MultiProvider/Strategies/BaseEvaluationStrategy.cs	85.36%	2 Missing and 4 partials ⚠️
...ture/Providers/MultiProvider/ProviderExtensions.cs	92.00%	0 Missing and 2 partials ⚠️
...er/Strategies/Models/StrategyPerProviderContext.cs	88.88%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #488      +/-   ##
==========================================
+ Coverage   88.45%   89.60%   +1.15%     
==========================================
  Files          50       64      +14     
  Lines        2096     2492     +396     
  Branches      245      295      +50     
==========================================
+ Hits         1854     2233     +379     
- Misses        191      199       +8     
- Partials       51       60       +9     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sergheevxo]

Do you have any idea when this will be implemented in the NuGet package?

[askpt]

Do you have any idea when this will be implemented in the NuGet package?

@sergheevxo I am actively working on #338, and this feature is next on my list.

[arttonoyan]

Apologies for the premature approval - I need to take a closer look at the changes before this can move forward. I’ll complete my review in the next couple of days

[weyert]

Is this thread safe?

[arttonoyan]

InitializeAsync and ShutdownAsync iterate through _registeredProviders and update each provider’s status concurrently. Each RegisteredProvider instance’s Status property is mutated inside Task.WhenAll without synchronization

Updating shared mutable state in parallel can lead to data races if the Status property is not thread‑safe. Either update statuses sequentially, protect them with synchronization (e.g., locks) or redesign RegisteredProvider to be immutable and return a new instance with the updated status.

---

To ensure we don’t run into issues here, I would suggest consider adding an integration test that validates the concurrent status updates behave correctly. This will help verify thread-safety and prevent potential data races.

[arttonoyan]

@askpt this was interesting to me so I played around with it a bit.
I’m sharing what I wrote so we don’t lose the code - feel free to improve it and reuse if it’s helpful!

Also, just an idea: it might be useful to add an internal GetRegisteredProviders() method in MultiProvider to make testing easier. Maybe even a public one if it makes sense longer term.

Here’s the test code I came up with:

[Fact]
public async Task MultiProvider_ConcurrentInitializationAndShutdown_ShouldMaintainConsistentProviderStatus()
{
    // Arrange
    const int providerCount = 20;
    var random = new Random();
    var providerEntries = new List<ProviderEntry>();

    for (int i = 0; i < providerCount; i++)
    {
        var provider = Substitute.For<FeatureProvider>();

        provider.InitializeAsync(Arg.Any<EvaluationContext>(), Arg.Any<CancellationToken>())
                .Returns(Task.CompletedTask);

        provider.ShutdownAsync(Arg.Any<CancellationToken>())
                .Returns(Task.CompletedTask);

        provider.GetMetadata()
                .Returns(new Metadata(name: $"provider-{i}"));

        providerEntries.Add(new ProviderEntry(provider));
    }

    var multiProvider = new MultiProvider(providerEntries);

    // Act: simulate concurrent initialization and shutdown with one task each
    var initTasks = Enumerable.Range(0, 1).Select(_ =>
        Task.Run(() => multiProvider.InitializeAsync(Arg.Any<EvaluationContext>(), CancellationToken.None)));

    var shutdownTasks = Enumerable.Range(0, 1).Select(_ =>
        Task.Run(() => multiProvider.ShutdownAsync(CancellationToken.None)));

    await Task.WhenAll(initTasks.Concat(shutdownTasks));

    // Assert: ensure that each provider ends in a valid lifecycle state
    var statuses = GetRegisteredStatuses().ToList();

    Assert.All(statuses, status =>
    {
        Assert.True(
            status is Constant.ProviderStatus.Ready or Constant.ProviderStatus.NotReady,
            $"Unexpected provider status: {status}");
    });

    // Local helper: uses reflection to access the private '_registeredProviders' field 
    // and retrieve the current status of each registered provider.
    // Consider replacing this with an internal or public method if testing becomes more frequent.
    IEnumerable<Constant.ProviderStatus> GetRegisteredStatuses()
    {
        var field = typeof(MultiProvider).GetField("_registeredProviders", BindingFlags.NonPublic | BindingFlags.Instance);
        if (field?.GetValue(multiProvider) is not IEnumerable<object> list)
            throw new InvalidOperationException("Could not retrieve registered providers via reflection.");

        foreach (var p in list)
        {
            var statusProperty = p.GetType().GetProperty("Status", BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance);
            if (statusProperty == null)
                throw new InvalidOperationException($"'Status' property not found on type {p.GetType().Name}.");

            if (statusProperty.GetValue(p) is not Constant.ProviderStatus status)
                throw new InvalidOperationException("Unable to read status property value.");

            yield return status;
        }
    }
}  

[askpt]

Fixed with: 4df6c76

Please let me know if I overdid the implementation of a thread safety for the initialisation and shutdown. I added a lock to the ChildProviderStatus and a semaphore for the lifecycle methods.

[weyert]

Do we want to use ex.ToString()?

[arttonoyan]

InitializeAsync and ShutdownAsync iterate through _registeredProviders and update each provider’s status concurrently. Each RegisteredProvider instance’s Status property is mutated inside Task.WhenAll without synchronization

Updating shared mutable state in parallel can lead to data races if the Status property is not thread‑safe. Either update statuses sequentially, protect them with synchronization (e.g., locks) or redesign RegisteredProvider to be immutable and return a new instance with the updated status.

---

To ensure we don’t run into issues here, I would suggest consider adding an integration test that validates the concurrent status updates behave correctly. This will help verify thread-safety and prevent potential data races.