Feat: add Redis governance query candidate selection

Author: rian-be

src/Redis/Storage/Candidates/Execution/RedisMutationRequestCandidateExecutor.cs

@@ -0,0 +1,41 @@
+using ModularityKit.Mutator.Governance.Redis.Storage.Candidates.Models;
+using ModularityKit.Mutator.Governance.Redis.Storage.Identifiers.Loading;
+
+namespace ModularityKit.Mutator.Governance.Redis.Storage.Candidates.Execution;
+
+/// <summary>
+/// Executes candidate id lookup plans against Redis set data.
+/// </summary>
+internal sealed class RedisMutationRequestCandidateExecutor(RedisMutationRequestIdSetReader idSetReader)
+{
+    private readonly RedisMutationRequestIdSetReader _idSetReader = idSetReader ?? throw new ArgumentNullException(nameof(idSetReader));
+
+    /// <summary>
+    /// Executes a candidate plan and returns the resulting request identifiers.
+    /// </summary>
+    /// <param name="plan">The candidate plan to execute.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The resolved request identifiers.</returns>
+    public async Task<IReadOnlyList<string>> ExecuteAsync(RedisMutationRequestCandidatePlan plan, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(plan);
+
+        return plan.Operation switch
+        {
+            RedisMutationRequestCandidateOperation.ExplicitIds => plan.ExplicitRequestIds ?? [],
+            RedisMutationRequestCandidateOperation.SingleSet => await LoadSingleSetAsync(plan, cancellationToken).ConfigureAwait(false),
+            RedisMutationRequestCandidateOperation.Union => await LoadUnionAsync(plan, cancellationToken).ConfigureAwait(false),
+            RedisMutationRequestCandidateOperation.Intersection => await LoadIntersectionAsync(plan, cancellationToken).ConfigureAwait(false),
+            _ => throw new InvalidOperationException($"Unsupported candidate operation '{plan.Operation}'.")
+        };
+    }
+
+    private Task<IReadOnlyList<string>> LoadSingleSetAsync(RedisMutationRequestCandidatePlan plan, CancellationToken cancellationToken) =>
+        _idSetReader.LoadIdsAsync(plan.Keys[0], cancellationToken);
+
+    private Task<IReadOnlyList<string>> LoadUnionAsync(RedisMutationRequestCandidatePlan plan, CancellationToken cancellationToken) => 
+        _idSetReader.LoadUnionedIdsAsync(plan.Keys, cancellationToken);
+
+    private Task<IReadOnlyList<string>> LoadIntersectionAsync(RedisMutationRequestCandidatePlan plan, CancellationToken cancellationToken) =>
+        _idSetReader.LoadIntersectedIdsAsync(plan.Keys[0], plan.Keys[1], cancellationToken);
+}

src/Redis/Storage/Candidates/Models/RedisMutationRequestCandidateOperation.cs

@@ -0,0 +1,27 @@
+namespace ModularityKit.Mutator.Governance.Redis.Storage.Candidates.Models;
+
+/// <summary>
+/// Defines how Redis request id candidates should be loaded for queries.
+/// </summary>
+internal enum RedisMutationRequestCandidateOperation
+{
+    /// <summary>
+    /// Uses an already known explicit list of request identifiers.
+    /// </summary>
+    ExplicitIds = 0,
+
+    /// <summary>
+    /// Loads identifiers from a single Redis set.
+    /// </summary>
+    SingleSet = 1,
+
+    /// <summary>
+    /// Loads identifiers from the union of multiple Redis sets.
+    /// </summary>
+    Union = 2,
+
+    /// <summary>
+    /// Loads identifiers from the intersection of multiple Redis sets.
+    /// </summary>
+    Intersection = 3
+}

src/Redis/Storage/Candidates/Models/RedisMutationRequestCandidatePlan.cs

@@ -0,0 +1,14 @@
+using StackExchange.Redis;
+
+namespace ModularityKit.Mutator.Governance.Redis.Storage.Candidates.Models;
+
+/// <summary>
+/// Represents a planned Redis candidate-id lookup operation.
+/// </summary>
+/// <param name="Operation">The candidate lookup operation to execute.</param>
+/// <param name="Keys">The Redis keys participating in the operation.</param>
+/// <param name="ExplicitRequestIds">The explicit request identifiers when no Redis set lookup is required.</param>
+internal sealed record RedisMutationRequestCandidatePlan(
+    RedisMutationRequestCandidateOperation Operation,
+    IReadOnlyList<RedisKey> Keys,
+    IReadOnlyList<string>? ExplicitRequestIds = null);

src/Redis/Storage/Candidates/Planning/RedisMutationRequestCandidatePlanBuilder.cs

@@ -0,0 +1,103 @@
+using ModularityKit.Mutator.Governance.Abstractions.Lifecycle.Model;
+using ModularityKit.Mutator.Governance.Abstractions.Queries.Model;
+using ModularityKit.Mutator.Governance.Redis.Keys;
+using ModularityKit.Mutator.Governance.Redis.Storage.Candidates.Models;
+using StackExchange.Redis;
+
+namespace ModularityKit.Mutator.Governance.Redis.Storage.Candidates.Planning;
+
+/// <summary>
+/// Builds candidate-id lookup plans for Redis-backed request queries.
+/// </summary>
+internal sealed class RedisMutationRequestCandidatePlanBuilder(RedisMutationRequestKeyspace keyspace)
+{
+    private readonly RedisMutationRequestKeyspace _keyspace = keyspace ?? throw new ArgumentNullException(nameof(keyspace));
+
+    /// <summary>
+    /// Builds a plan that loads all known request identifiers.
+    /// </summary>
+    /// <returns>The candidate plan.</returns>
+    public RedisMutationRequestCandidatePlan BuildAllRequestsPlan()
+        => Single(_keyspace.RequestIds());
+
+    /// <summary>
+    /// Builds a plan that loads request identifiers for a specific state.
+    /// </summary>
+    /// <param name="stateId">The state identifier.</param>
+    /// <returns>The candidate plan.</returns>
+    public RedisMutationRequestCandidatePlan BuildByStateIdPlan(string stateId)
+        => Single(_keyspace.RequestsByStateId(stateId));
+
+    /// <summary>
+    /// Builds a plan that loads pending request identifiers, optionally narrowed by pending reason.
+    /// </summary>
+    /// <param name="reason">The optional pending reason.</param>
+    /// <returns>The candidate plan.</returns>
+    public RedisMutationRequestCandidatePlan BuildPendingPlan(PendingMutationReason? reason)
+        => Single(GetPendingKey(reason));
+
+    /// <summary>
+    /// Builds a plan that loads pending request identifiers for a specific state.
+    /// </summary>
+    /// <param name="stateId">The state identifier.</param>
+    /// <param name="reason">The optional pending reason.</param>
+    /// <returns>The candidate plan.</returns>
+    public RedisMutationRequestCandidatePlan BuildPendingByStateIdPlan(string stateId, PendingMutationReason? reason)
+        => Intersect(_keyspace.RequestsByStateId(stateId), GetPendingKey(reason));
+
+    /// <summary>
+    /// Builds a best-effort Redis candidate plan for the supplied request query.
+    /// </summary>
+    /// <param name="query">The request query to analyze.</param>
+    /// <returns>The candidate plan.</returns>
+    public RedisMutationRequestCandidatePlan BuildQueryPlan(MutationRequestQuery query)
+    {
+        ArgumentNullException.ThrowIfNull(query);
+
+        if (query.RequestIds.Count > 0)
+            return Explicit(query.RequestIds);
+
+        if (query.PendingReasons.Count > 0)
+            return Union(query.PendingReasons.Select(_keyspace.PendingRequestIds));
+
+        if (query.Statuses.Count > 0)
+        {
+            var pendingOnly = query.Statuses.All(status => status == MutationRequestStatus.Pending);
+            return pendingOnly
+                ? BuildPendingPlan(reason: null)
+                : Union(query.Statuses.Select(_keyspace.RequestsByStatus));
+        }
+
+        if (query.StateIds.Count > 0)
+            return Union(query.StateIds.Select(_keyspace.RequestsByStateId));
+
+        return BuildAllRequestsPlan();
+    }
+
+    private RedisMutationRequestCandidatePlan Explicit(IEnumerable<string> requestIds)
+        => new(RedisMutationRequestCandidateOperation.ExplicitIds, Keys: [],
+            ExplicitRequestIds: requestIds
+                .Where(requestId => !string.IsNullOrWhiteSpace(requestId))
+                .Distinct(StringComparer.Ordinal)
+                .ToArray());
+
+    private RedisMutationRequestCandidatePlan Single(RedisKey key)
+        => new(RedisMutationRequestCandidateOperation.SingleSet, Keys: [key]);
+
+    private RedisMutationRequestCandidatePlan Union(IEnumerable<RedisKey> keys)
+    {
+        var materialized = keys.Distinct().ToArray();
+        if (materialized.Length == 1)
+            return Single(materialized[0]);
+
+        return new RedisMutationRequestCandidatePlan(
+            RedisMutationRequestCandidateOperation.Union,
+            materialized);
+    }
+
+    private RedisMutationRequestCandidatePlan Intersect(RedisKey left, RedisKey right)
+        => new(RedisMutationRequestCandidateOperation.Intersection, [left, right]);
+
+    private RedisKey GetPendingKey(PendingMutationReason? reason)
+        => reason.HasValue ? _keyspace.PendingRequestIds(reason.Value) : _keyspace.PendingRequestIds();
+}

src/Redis/Storage/Candidates/RedisMutationRequestQueryCandidateSelector.cs

@@ -0,0 +1,69 @@
+using ModularityKit.Mutator.Governance.Abstractions.Lifecycle.Model;
+using ModularityKit.Mutator.Governance.Abstractions.Queries.Model;
+using ModularityKit.Mutator.Governance.Redis.Storage.Candidates.Execution;
+using ModularityKit.Mutator.Governance.Redis.Storage.Candidates.Models;
+using ModularityKit.Mutator.Governance.Redis.Storage.Candidates.Planning;
+
+namespace ModularityKit.Mutator.Governance.Redis.Storage.Candidates;
+
+/// <summary>
+/// Selects Redis request-id candidates for higher-level request queries.
+/// </summary>
+internal sealed class RedisMutationRequestQueryCandidateSelector(
+    RedisMutationRequestCandidatePlanBuilder planBuilder,
+    RedisMutationRequestCandidateExecutor candidateExecutor)
+{
+    private readonly RedisMutationRequestCandidatePlanBuilder _planBuilder =
+        planBuilder ?? throw new ArgumentNullException(nameof(planBuilder));
+   
+    private readonly RedisMutationRequestCandidateExecutor _candidateExecutor =
+        candidateExecutor ?? throw new ArgumentNullException(nameof(candidateExecutor));
+
+    /// <summary>
+    /// Loads all known request identifiers.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The resolved request identifiers.</returns>
+    public Task<IReadOnlyList<string>> LoadAllRequestIdsAsync(CancellationToken cancellationToken) =>
+        LoadAsync(_planBuilder.BuildAllRequestsPlan(), cancellationToken);
+
+    /// <summary>
+    /// Loads request identifiers for a specific state.
+    /// </summary>
+    /// <param name="stateId">The state identifier.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The resolved request identifiers.</returns>
+    public Task<IReadOnlyList<string>> LoadByStateIdAsync(string stateId, CancellationToken cancellationToken) =>
+        LoadAsync(_planBuilder.BuildByStateIdPlan(stateId), cancellationToken);
+
+    /// <summary>
+    /// Loads pending request identifiers, optionally narrowed by reason.
+    /// </summary>
+    /// <param name="reason">The optional pending reason.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The resolved request identifiers.</returns>
+    public Task<IReadOnlyList<string>> LoadPendingAsync(PendingMutationReason? reason, CancellationToken cancellationToken) =>
+        LoadAsync(_planBuilder.BuildPendingPlan(reason), cancellationToken);
+
+    /// <summary>
+    /// Loads pending request identifiers for a specific state.
+    /// </summary>
+    /// <param name="stateId">The state identifier.</param>
+    /// <param name="reason">The optional pending reason.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The resolved request identifiers.</returns>
+    public Task<IReadOnlyList<string>> LoadPendingByStateIdAsync(string stateId, PendingMutationReason? reason, CancellationToken cancellationToken) =>
+        LoadAsync(_planBuilder.BuildPendingByStateIdPlan(stateId, reason), cancellationToken);
+
+    /// <summary>
+    /// Loads request identifiers for a general request query using Redis-side candidate narrowing.
+    /// </summary>
+    /// <param name="query">The query to analyze.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The resolved request identifiers.</returns>
+    public Task<IReadOnlyList<string>> LoadQueryCandidatesAsync(MutationRequestQuery query, CancellationToken cancellationToken) =>
+        LoadAsync(_planBuilder.BuildQueryPlan(query), cancellationToken);
+
+    private Task<IReadOnlyList<string>> LoadAsync(RedisMutationRequestCandidatePlan plan, CancellationToken cancellationToken) =>
+        _candidateExecutor.ExecuteAsync(plan, cancellationToken);
+}