ThrottleChannel.Redis 1.0.0

ThrottleChannel

TL;DR

Channel-driven rate gate with capacity tokens, zero-loss cancellation, deterministic shutdown, and optional Redis-backed distributed coordination.

Features

• Channel-based backpressure: unbounded data channel with separate capacity counter prevents accidental drops.
• Precise pacing: monotonic Stopwatch scheduling guarantees ≤ configured RPS without timer drift.
• Immediate cancellation: canceled waiters free capacity instantly and never clog the queue.
• Deterministic shutdown: DisposeAsync drains the channel, flags waiters, and surfaces OperationCanceledException.
• Observability baked in: queue depth, cancellations, and wait durations exposed through RateGateMetricsSnapshot.
• Redis adapter: ThrottleChannel.Redis ships a fixed-window distributed permit acquirer using standard ConnectionMultiplexer patterns.

Installation

dotnet add package ThrottleChannel
# optional distributed integration
dotnet add package ThrottleChannel.Redis

Target frameworks: net8.0, netstandard2.1.

Quick Start

using System.Diagnostics.Metrics;
using ThrottleChannel.RateGate;

using var meter = new Meter("ThrottleChannel.RateGate", "1.0.0");
await using var gate = new FixedRpsGate(
    rps: 1,
    capacity: 1024,
    meter: meter);

foreach (var request in requests)
{
    await gate.WaitAsync(request.CancellationToken);
    await ProcessAsync(request);
}

var metrics = gate.Metrics;
Console.WriteLine($"Granted: {metrics.TotalGranted}, cancelled: {metrics.TotalCancelled}");

ASP.NET Core with Redis coordination

using Microsoft.Extensions.DependencyInjection;
using ThrottleChannel.Distributed;
using ThrottleChannel.RateGate;
using ThrottleChannel.Redis;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddThrottleChannelRedis(
    configuration: builder.Configuration.GetConnectionString("redis")!,
    configure: options =>
    {
        options.Key = "throttle:orders";
        options.PermitsPerWindow = 1;
    });

builder.Services.AddSingleton<FixedRpsGate>(sp =>
{
    var acquirer = sp.GetRequiredService<IDistributedPermitAcquirer>();
    return new FixedRpsGate(rps: 1, capacity: 1024, distributedAcquirer: acquirer);
});
builder.Services.AddSingleton<IRateGate>(sp => sp.GetRequiredService<FixedRpsGate>());

var app = builder.Build();

app.MapPost("/checkout", async (IRateGate gate, CancellationToken ct) =>
{
    await gate.WaitAsync(ct);
    return Results.Ok();
});

app.Run();

FixedRpsGate is registered as a singleton, so the DI container disposes it gracefully on shutdown.

Observability & Aspire

• Pass a Meter instance (or configure FixedRpsGateFactory with one) to enable automatic publishing through RateGateMetricsPublisher. Metrics are emitted on the ThrottleChannel.RateGate meter.

• The tests/ThrottleChannel.ServiceDefaults project wires OpenTelemetry exporters. When OTEL_EXPORTER_OTLP_ENDPOINT is set (for example, http://localhost:4317 exposed by the Aspire dashboard), metrics and traces flow to that endpoint.

• Run the local Aspire orchestrator to see live telemetry and distributed coordination:

  dotnet run --project tests/ThrottleChannel.AppHost/ThrottleChannel.AppHost.csproj
  

  The orchestrator provisions Redis, boots the integration worker, and links the OpenTelemetry pipeline to the Aspire dashboard.

Cancellation semantics

• WaitAsync throws OperationCanceledException when the caller supplies a canceled token.
• Tokens canceled while queued release capacity immediately and complete with OperationCanceledException.
• Shutdown (DisposeAsync) cancels every pending waiter, keeping channel and semaphore in a consistent state.

Why Channel + capacity tokens

Benchmarks

Scenario: 1k permit acquisitions per run, 1 or 10 rps configuration, averaged over 5 iterations. Baseline is legacy linked-list queue + locks (simulated in benchmarks project).

Run locally:

cd benchmarks/ThrottleChannel.Benchmarks
dotnet run -c Release

Benchmarks require restoring NuGet packages. In restricted CI environments provide an offline cache or enable network access.

Redis-backed tests

Redis integration suites rely on Docker via Testcontainers; the tests spin up a disposable Redis container and skip only if the local Docker daemon is unavailable. Make sure Docker Desktop/Colima/Podman is running before executing:

dotnet test ThrottleChannel.sln

CI/CD

• ci.yml — restore, build, test (with coverage), pack artifacts on every push/PR.
• release.yml — publish signed packages to NuGet when tagging v*.*.* (requires NUGET_API_KEY).

Repository layout

• src/ThrottleChannel — core channel-based gate.
• src/ThrottleChannel.Redis — Redis permit acquirer + DI helpers.
• tests/ThrottleChannel.Tests — xUnit coverage for cancellation, capacity, pacing, shutdown.
• tests/ThrottleChannel.TestSupport — Redis Testcontainers helpers and conditional attributes.
• tests/ThrottleChannel.ServiceDefaults — shared resilience + OpenTelemetry defaults for Aspire-integrated services.
• benchmarks/ThrottleChannel.Benchmarks — BenchmarkDotNet comparisons.
• samples/BasicConsole — console demo with multiple producers under 1 RPS gate.
• tests/ThrottleChannel.AppHost — Aspire orchestrator for integration scenarios.
• tests/ThrottleChannel.IntegrationWorker — background load generator used in Aspire orchestration.

Roadmap

See AGENTS.md for the full backlog: token bucket, per-key limits, sliding window, concurrency caps, telemetry hooks, NativeAOT.