DistributedRateLimiter 1.0.3

DistributedRateLimiter

Distributed rate limiting for .NET backed by your existing database. No Redis, no message broker, no extra infrastructure.

Works in HTTP pipelines and background services — any code that calls an external API or shared resource can enforce a rate limit that's consistent across every running instance.

How it works

Each rate limit check is handled atomically in your existing database, so all running instances share the same state automatically — no in-memory counters that diverge across pods.

Instance A                          Instance B
│                                   │
│  POST /orders                     │  POST /orders
│  → CheckAsync("user:42", policy)  │  → CheckAsync("user:42", policy)
│  → INSERT ... ON CONFLICT         │  → INSERT ... ON CONFLICT
│    DO UPDATE SET count + 1        │    DO UPDATE SET count + 1
│  ← count = 1  ✓ allowed           │  ← count = 2  ✓ allowed
│                                   │
│  POST /orders (101st request)     │
│  → CheckAsync("user:42", policy)  │
│  ← count = 101  ✗ 429             │

The database row is the single source of truth. No synchronisation needed between instances.

Algorithms

Projects

Quick start

1. Install packages

dotnet add package DistributedRateLimiter
dotnet add package DistributedRateLimiter.Providers.Postgres

2. Register with the host

using DistributedRateLimiter;
using DistributedRateLimiter.Core.Model;
using DistributedRateLimiter.Providers.Postgres;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbRateLimiter(
    new PostgresRateLimitStore(connectionString, tableName: "__rate_limits"),
    opts => opts.AddPolicy(new RateLimitPolicy
    {
        Name      = "api",
        Algorithm = RateLimitAlgorithm.SlidingWindow,
        Limit     = 100,
        Window    = TimeSpan.FromMinutes(1)
    }));

var app = builder.Build();

3. Add the middleware

// Limit by authenticated user, falling back to IP
app.UseDbRateLimiter(
    keySelector: ctx => ctx.User.Identity?.Name
                     ?? ctx.Connection.RemoteIpAddress?.ToString()
                     ?? "anon",
    policyName: "api");

app.MapControllers();
app.Run();

That's it. Every request now increments a shared counter in your database. When a key exceeds the limit the middleware returns 429 Too Many Requests with standard rate limit headers.

Response headers

Multiple policies

Register as many policies as you need — each is identified by name:

builder.Services.AddDbRateLimiter(
    new PostgresRateLimitStore(connectionString, "__rate_limits"),
    opts =>
    {
        opts.AddPolicy(new RateLimitPolicy
        {
            Name      = "authenticated",
            Algorithm = RateLimitAlgorithm.SlidingWindow,
            Limit     = 1000,
            Window    = TimeSpan.FromMinutes(1)
        });

        opts.AddPolicy(new RateLimitPolicy
        {
            Name      = "anonymous",
            Algorithm = RateLimitAlgorithm.SlidingWindow,
            Limit     = 20,
            Window    = TimeSpan.FromMinutes(1)
        });

        opts.AddPolicy(new RateLimitPolicy
        {
            Name                = "webhooks",
            Algorithm           = RateLimitAlgorithm.TokenBucket,
            BucketCapacity      = 500,
            RefillRatePerSecond = 50
        });
    });

app.UseDbRateLimiter(
    keySelector: ctx => ctx.User.Identity?.Name
                     ?? ctx.Connection.RemoteIpAddress?.ToString()
                     ?? "anon",
    policyNameSelector: ctx => ctx.User.Identity?.IsAuthenticated == true
        ? "authenticated"
        : "anonymous");

Using in background services

IDbRateLimiter lives in DistributedRateLimiter.Core and has no HTTP dependency — inject it anywhere.

Register the policy at startup alongside your other policies:

builder.Services.AddDbRateLimiter(
    new PostgresRateLimitStore(connectionString, "__rate_limits"),
    opts =>
    {
        opts.AddPolicy(new RateLimitPolicy { Name = "api", /* ... */ });

        opts.AddPolicy(new RateLimitPolicy
        {
            Name                = "payment-gateway",
            Algorithm           = RateLimitAlgorithm.TokenBucket,
            BucketCapacity      = 100,
            RefillRatePerSecond = 100
        });
    });

Then inject IDbRateLimiter and call it by name:

using DistributedRateLimiter.Core.Interface;

public class OrderProcessingWorker : BackgroundService
{
    private readonly IDbRateLimiter _limiter;
    private readonly IOrderRepository _orders;
    private readonly IPaymentGateway _payments;

    public OrderProcessingWorker(
        IDbRateLimiter limiter,
        IOrderRepository orders,
        IPaymentGateway payments)
    {
        _limiter = limiter;
        _orders = orders;
        _payments = payments;
    }

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            var orders = await _orders.GetPendingAsync(ct);

            foreach (var order in orders)
            {
                // Enforce the payment gateway's per-merchant API quota
                // consistently across all running instances of this worker
                var result = await _limiter.CheckAsync(
                    key:        $"payment-gateway:{order.MerchantId}",
                    policyName: "payment-gateway",
                    ct);

                if (!result.Allowed)
                {
                    await Task.Delay(result.RetryAfter, ct);
                    continue;
                }

                await _payments.ChargeAsync(order, ct);
            }

            await Task.Delay(TimeSpan.FromSeconds(5), ct);
        }
    }
}

This is where a database-backed limiter has a meaningful advantage over in-memory alternatives — if you run 5 instances of this worker, an in-memory limiter allows 5× the intended quota. The shared database counter enforces the real limit regardless of instance count.

Cleanup

Rate limit rows accumulate over time. Register the built-in cleanup worker to purge them on a schedule:

// Default: purge rows older than 2 hours, run every 30 minutes
builder.Services.AddDbRateLimiterCleanup();

// Custom intervals
builder.Services.AddDbRateLimiterCleanup(opts =>
{
    opts.MaxAge   = TimeSpan.FromHours(1);   // set to at least your longest window
    opts.Interval = TimeSpan.FromMinutes(10);
});

RateLimitCleanupOptions lives in DistributedRateLimiter.Core.Model:

The worker starts with a 30-second delay on boot so it doesn't fire immediately on every instance restart, and any exception during cleanup is caught and logged — it retries on the next interval rather than crashing.

Algorithms in depth

SlidingWindow

Buckets requests by key and second — all requests arriving within the same second increment a single shared row, then a rolling SUM counts all rows within the window. Provides true sliding enforcement — a burst of 100 requests is measured against the exact 60-second window ending now, not against a clock-aligned boundary. Concurrent requests within the same second are serialised by the database's row-level lock on the upsert, so no application-level advisory lock is needed.

new RateLimitPolicy
{
    Name      = "api",
    Algorithm = RateLimitAlgorithm.SlidingWindow,
    Limit     = 100,
    Window    = TimeSpan.FromMinutes(1)
}

FixedWindow

Simpler and cheaper than sliding window — one row per key, reset at each window boundary. Allows a burst of up to 2 × Limit at a boundary (the last requests of one window plus the first of the next).

new RateLimitPolicy
{
    Name      = "api",
    Algorithm = RateLimitAlgorithm.FixedWindow,
    Limit     = 100,
    Window    = TimeSpan.FromMinutes(1)
}

FixedWindow supports any positive whole-number-of-seconds window on all providers. Buckets are aligned to the Unix epoch, so a 10-second window produces buckets at 00:00:00, 00:00:10, 00:00:20, etc.

TokenBucket

Maintains a token count per key. Each request consumes one token. Tokens refill continuously at RefillRatePerSecond up to BucketCapacity. Allows short bursts while enforcing a long-run average rate.

new RateLimitPolicy
{
    Name                = "api",
    Algorithm           = RateLimitAlgorithm.TokenBucket,
    BucketCapacity      = 200,   // burst up to 200
    RefillRatePerSecond = 10     // steady-state: 10 req/s
}

Database providers

PostgreSQL

using DistributedRateLimiter.Providers.Postgres;

new PostgresRateLimitStore(connectionString, tableName: "__rate_limits")

EnsureSchemaAsync creates the table if it does not exist:

CREATE TABLE IF NOT EXISTS __rate_limits (
    key          TEXT        NOT NULL,
    window_start TIMESTAMPTZ NOT NULL,
    count        INT         NOT NULL DEFAULT 0,
    tokens       FLOAT       NULL,
    last_refill  TIMESTAMPTZ NULL,
    PRIMARY KEY (key, window_start)
);

FixedWindow and TokenBucket use a single atomic round-trip via INSERT ... ON CONFLICT DO UPDATE ... RETURNING. SlidingWindow uses a transaction with two statements — an upsert into a second-level bucket row and a rolling SUM count query. The ON CONFLICT DO UPDATE row-level lock serialises concurrent same-second requests, so no advisory lock is needed.

Required features:

No extensions or special server configuration required. Minimum: PostgreSQL 9.5. PostgreSQL 12+ recommended.

Theoretical throughput (single app instance, pool of 100 connections, formula: pool ÷ (latency × round-trips)):

Round-trip breakdown:

• FixedWindow / TokenBucket — 1 round-trip (INSERT ... ON CONFLICT DO UPDATE ... RETURNING)
• SlidingWindow — 4 round-trips (BEGIN + upsert + count query + COMMIT)

With multiple app instances, total connections across all instances must stay below PostgreSQL's max_connections (default 100 on most managed services). Use PgBouncer in transaction mode to scale past this limit.

Package: Npgsql 8.x+. Targets net8.0, net9.0, net10.0.

SQL Server

using DistributedRateLimiter.Providers.MsSql;

new MsSqlRateLimitStore(connectionString, tableName: "__rate_limits")

EnsureSchemaAsync creates the table if it does not exist:

IF OBJECT_ID(N'[__rate_limits]', N'U') IS NULL
CREATE TABLE [__rate_limits] (
    key          NVARCHAR(512)  NOT NULL,
    window_start DATETIMEOFFSET NOT NULL,
    count        INT            NOT NULL DEFAULT 0,
    tokens       FLOAT          NULL,
    last_refill  DATETIMEOFFSET NULL,
    PRIMARY KEY (key, window_start)
);

Uses MERGE ... WITH (HOLDLOCK) for atomic upserts.

Required features:

Minimum: SQL Server 2008 for FixedWindow and SlidingWindow. SQL Server 2022+ is required for the TokenBucket algorithm due to the GREATEST() function.

Theoretical throughput (single app instance, pool of 100 connections, formula: pool ÷ (latency × round-trips)):

Round-trip breakdown:

• FixedWindow / TokenBucket — 1 round-trip (MERGE ... OUTPUT in a single batch)
• SlidingWindow — 3 round-trips (BEGIN TX + MERGE; SELECT batch + COMMIT)

SQL Server's default max pool size is 100 per connection string; increase via Max Pool Size=N in the connection string.

Package: Microsoft.Data.SqlClient 6.x. Targets net8.0, net9.0, net10.0.

MySQL / MariaDB

using DistributedRateLimiter.Providers.MySql;

new MySqlRateLimitStore(connectionString, tableName: "__rate_limits")

EnsureSchemaAsync creates the table if it does not exist:

CREATE TABLE IF NOT EXISTS `__rate_limits` (
    `key`          VARCHAR(512) NOT NULL,
    `window_start` DATETIME(6)  NOT NULL,
    `count`        INT          NOT NULL DEFAULT 0,
    `tokens`       DOUBLE       NULL,
    `last_refill`  DATETIME(6)  NULL,
    PRIMARY KEY (`key`, `window_start`)
);

MySQL/MariaDB does not support RETURNING on upserts so FixedWindow and TokenBucket cost 2 round-trips instead of 1. SlidingWindow uses a multi-statement batch (INSERT ... ON DUPLICATE KEY UPDATE + SELECT) inside a READ COMMITTED transaction — InnoDB row-level locking on the upsert serialises concurrent same-second requests without an advisory lock.

Required features:

Minimum: MySQL 5.6+ or MariaDB 5.3+. InnoDB is required for SlidingWindow; MyISAM is not supported. Multi-statement queries and READ COMMITTED isolation are supported by MySqlConnector with no additional connection string options.

Theoretical throughput (single app instance, pool of 100 connections, formula: pool ÷ (latency × round-trips)):

Round-trip breakdown:

• FixedWindow / TokenBucket — 2 round-trips (upsert + select, MySQL does not support RETURNING)
• SlidingWindow — 3 round-trips (BEGIN TX + INSERT; SELECT batch + COMMIT)

Tune pool size via Max Pool Size=N in the connection string.

Package: MySqlConnector 2.x. Targets net8.0, net9.0, net10.0.

Custom provider

Implement IRateLimitStore from DistributedRateLimiter.Core:

using DistributedRateLimiter.Core.Interface;
using DistributedRateLimiter.Core.Model;

public sealed class MyCustomStore : IRateLimitStore
{
    public Task EnsureSchemaAsync(CancellationToken ct = default) { ... }

    public Task<RateLimitResult> SlidingWindowAsync(
        string key, int limit, TimeSpan window, CancellationToken ct = default) { ... }

    public Task<RateLimitResult> FixedWindowAsync(
        string key, int limit, TimeSpan window, CancellationToken ct = default) { ... }

    public Task<RateLimitResult> TokenBucketAsync(
        string key, int capacity, double refillRatePerSecond, CancellationToken ct = default) { ... }

    public Task PurgeExpiredAsync(TimeSpan maxAge, CancellationToken ct = default) { ... }
}

Pass it directly to AddDbRateLimiter:

builder.Services.AddDbRateLimiter(new MyCustomStore(), opts => { ... });

Configuration reference

RateLimitPolicy

RateLimitCleanupOptions

When to use this vs Redis

A database-backed rate limiter is a good fit when:

• Your stack does not already include Redis
• You need distributed enforcement across instances without adding infrastructure
• You are already on a supported database for other purposes

Throughput guide for a single hot key (cloud, same region):

For most real-world rate limit keys (per-user, per-IP, per-tenant) traffic rarely exceeds a few hundred requests per second on any single key, so all three algorithms are a practical fit. SlidingWindow becomes the bottleneck only when a single key is genuinely a hot path — in that case, switch to FixedWindow or TokenBucket, or use Redis.

Consider Redis when:

• A single key routinely receives thousands of requests per second and you need SlidingWindow semantics
• You need sub-millisecond enforcement latency
• You are already running Redis for caching or pub/sub