audit, advisories and doctors/setup work

src/__Libraries/StellaOps.FeatureFlags/IFeatureFlagProvider.cs

@@ -0,0 +1,99 @@
+namespace StellaOps.FeatureFlags;
+
+/// <summary>
+/// Provider that supplies feature flag values from a specific source.
+/// Providers are ordered by priority in the composite service.
+/// </summary>
+public interface IFeatureFlagProvider
+{
+    /// <summary>
+    /// Unique name identifying this provider.
+    /// </summary>
+    string Name { get; }
+
+    /// <summary>
+    /// Priority order (lower = higher priority, checked first).
+    /// </summary>
+    int Priority { get; }
+
+    /// <summary>
+    /// Whether this provider supports watching for changes.
+    /// </summary>
+    bool SupportsWatch { get; }
+
+    /// <summary>
+    /// Tries to get the value of a feature flag.
+    /// </summary>
+    /// <param name="flagKey">The feature flag key.</param>
+    /// <param name="context">Evaluation context for targeting.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The flag result, or null if this provider doesn't have the flag.</returns>
+    Task<FeatureFlagResult?> TryGetFlagAsync(
+        string flagKey,
+        FeatureFlagEvaluationContext context,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Lists all feature flags known to this provider.
+    /// </summary>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>All flag definitions from this provider.</returns>
+    Task<IReadOnlyList<FeatureFlagDefinition>> ListFlagsAsync(CancellationToken ct = default);
+
+    /// <summary>
+    /// Watches for changes to feature flags.
+    /// Only called if SupportsWatch is true.
+    /// </summary>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Stream of change events.</returns>
+    IAsyncEnumerable<FeatureFlagChangedEvent> WatchAsync(CancellationToken ct = default);
+}
+
+/// <summary>
+/// Base class for feature flag providers with common functionality.
+/// </summary>
+public abstract class FeatureFlagProviderBase : IFeatureFlagProvider
+{
+    /// <inheritdoc />
+    public abstract string Name { get; }
+
+    /// <inheritdoc />
+    public virtual int Priority => 100;
+
+    /// <inheritdoc />
+    public virtual bool SupportsWatch => false;
+
+    /// <inheritdoc />
+    public abstract Task<FeatureFlagResult?> TryGetFlagAsync(
+        string flagKey,
+        FeatureFlagEvaluationContext context,
+        CancellationToken ct = default);
+
+    /// <inheritdoc />
+    public virtual Task<IReadOnlyList<FeatureFlagDefinition>> ListFlagsAsync(
+        CancellationToken ct = default)
+    {
+        return Task.FromResult<IReadOnlyList<FeatureFlagDefinition>>([]);
+    }
+
+    /// <inheritdoc />
+    public virtual async IAsyncEnumerable<FeatureFlagChangedEvent> WatchAsync(
+        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken ct = default)
+    {
+        // Default implementation does nothing
+        await Task.CompletedTask;
+        yield break;
+    }
+
+    /// <summary>
+    /// Creates a successful flag result.
+    /// </summary>
+    protected FeatureFlagResult CreateResult(
+        string key,
+        bool enabled,
+        object? variant = null,
+        string? reason = null)
+    {
+        return new FeatureFlagResult(key, enabled, variant, reason, Name);
+    }
+}