StellaOps.Messaging.RateLimiting

Rate limiting for services behind a Router gateway: the limiter contract, the fixed-window rules and the limiter factory.

PackageStellaOps.Messaging.RateLimiting
ComponentRouter
LicenceBUSL-1.1 (Router licence)
Package kindLibrary
Target frameworknet10.0

To add the package to a project, see Installing Stella Ops packages.

Namespaces

NamespaceTypes
StellaOps.Messaging.RateLimiting8

StellaOps.Messaging.RateLimiting namespace

TypeKindDescription
IRateLimiterinterfaceTransport-agnostic rate limiter interface.
IRateLimiterFactoryinterfaceFactory for creating rate limiter instances.
RateLimitPolicyrecordDefines a rate limit policy: at most RateLimitPolicy.MaxPermitspermits per key in each fixed, epoch-aligned window of length RateLimitPolicy.Window(see RateLimiterContract).
RateLimitResultstructResult of a rate limit acquisition attempt.
RateLimitStatusstructCurrent status of a rate limit key.
RateLimitWindowstructOne fixed rate limit window, in Unix milliseconds.
RateLimitWindowStatestructA key’s effective window and the permits counted in it.
RateLimiterContractclassThe rules every IRateLimiterbackend (Valkey, PostgreSQL, in-memory) applies, so that one RateLimitPolicygives the same decisions on each of them.

IRateLimiter interface

public interface IRateLimiter

Transport-agnostic rate limiter interface. Every backend applies the same fixed-window algorithm (windows aligned to the Unix epoch); check and increment are atomic, and a denied attempt does not consume a permit. Keys are case-sensitive. A key keeps one window per policy, so one limiter can apply several policies (for example per minute and per day) to the same key. The shared rules are defined by RateLimiterContract.

ProviderName property

string ProviderName { get; }

Gets the provider name for diagnostics (e.g., “valkey”, “postgres”, “inmemory”).

GetStatusAsync(string, RateLimitPolicy, CancellationToken) method

ValueTask<RateLimitStatus> GetStatusAsync(string key, RateLimitPolicy policy, CancellationToken cancellationToken = default)

Gets current usage for a key under policy without consuming a permit.

Parameters

Returns

The current rate limit status.

ResetAsync(string, CancellationToken) method

ValueTask<bool> ResetAsync(string key, CancellationToken cancellationToken = default)

Resets the rate limit counters for a key under every policy.

Parameters

Returns

True if the key had permits counted, under any policy, in a window that had not ended, and was reset.

TryAcquireAsync(string, RateLimitPolicy, CancellationToken) method

ValueTask<RateLimitResult> TryAcquireAsync(string key, RateLimitPolicy policy, CancellationToken cancellationToken = default)

Attempts to acquire a permit from the rate limiter under policy. When the key’s current window for that policy is full the attempt is denied, nothing is counted, and RateLimitResult.RetryAfteris the time until that window ends. The key’s windows for other policies are not changed: a caller that applies two policies calls once per policy.

Parameters

Returns

The result of the rate limit check.

IRateLimiterFactory interface

public interface IRateLimiterFactory

Factory for creating rate limiter instances.

ProviderName property

string ProviderName { get; }

Gets the provider name for this factory.

Create(string) method

IRateLimiter Create(string name)

Creates a rate limiter with the specified name.

Parameters

Returns

A configured rate limiter instance.

Exceptions

RateLimitPolicy record

public sealed record RateLimitPolicy

Defines a rate limit policy: at most RateLimitPolicy.MaxPermitspermits per key in each fixed, epoch-aligned window of length RateLimitPolicy.Window(see RateLimiterContract).

Parameters

Exceptions

RateLimitPolicy(int, TimeSpan) constructor

public RateLimitPolicy(int MaxPermits, TimeSpan Window)

Defines a rate limit policy: at most RateLimitPolicy.MaxPermitspermits per key in each fixed, epoch-aligned window of length RateLimitPolicy.Window(see RateLimiterContract).

Parameters

Exceptions

MaxPermits property

public int MaxPermits { get; init; }

Maximum number of permits allowed within one window.

Window property

public TimeSpan Window { get; init; }

The window length.

PerHour(int) method

public static RateLimitPolicy PerHour(int maxPermits)

Creates a per-hour rate limit policy.

PerMinute(int) method

public static RateLimitPolicy PerMinute(int maxPermits)

Creates a per-minute rate limit policy.

PerSecond(int) method

public static RateLimitPolicy PerSecond(int maxPermits)

Creates a per-second rate limit policy.

RateLimitResult struct

public readonly struct RateLimitResult

Result of a rate limit acquisition attempt.

CurrentCount property

public int CurrentCount { get; init; }

Gets the current count of permits used in the window.

IsAllowed property

public bool IsAllowed { get; init; }

Gets whether the permit was acquired (request allowed).

RemainingPermits property

public int RemainingPermits { get; init; }

Gets the number of remaining permits in the window.

RetryAfter property

public TimeSpan? RetryAfter { get; init; }

Gets the suggested time to wait before retrying (when denied).

Allowed(int, int) method

public static RateLimitResult Allowed(int currentCount, int remainingPermits)

Creates a result indicating the permit was acquired.

Denied(int, TimeSpan) method

public static RateLimitResult Denied(int currentCount, TimeSpan retryAfter)

Creates a result indicating the request was denied.

RateLimitStatus struct

public readonly struct RateLimitStatus

Current status of a rate limit key.

CurrentCount property

public int CurrentCount { get; init; }

Gets the current count of permits used in the window.

Exists property

public bool Exists { get; init; }

Gets whether the key exists (has any usage).

RemainingPermits property

public int RemainingPermits { get; init; }

Gets the number of remaining permits in the window.

WindowRemaining property

public TimeSpan WindowRemaining { get; init; }

Gets the time remaining until the window resets.

Empty(int) method

public static RateLimitStatus Empty(int maxPermits)

Creates a status for a key with no usage.

WithUsage(int, int, TimeSpan) method

public static RateLimitStatus WithUsage(int currentCount, int remainingPermits, TimeSpan windowRemaining)

Creates a status for an existing key.

RateLimitWindow struct

public readonly struct RateLimitWindow : IEquatable<RateLimitWindow>

One fixed rate limit window, in Unix milliseconds.

Parameters

RateLimitWindow(long, long) constructor

public RateLimitWindow(long StartMs, long LengthMs)

One fixed rate limit window, in Unix milliseconds.

Parameters

EndMs property

public long EndMs { get; }

Window end (exclusive), in Unix milliseconds.

LengthMs property

public long LengthMs { get; init; }

Window length.

StartMs property

public long StartMs { get; init; }

Window start (inclusive).

RemainingAt(DateTimeOffset) method

public TimeSpan RemainingAt(DateTimeOffset now)

Time from now until the window ends; zero once it has ended.

RateLimitWindowState struct

public readonly struct RateLimitWindowState : IEquatable<RateLimitWindowState>

A key’s effective window and the permits counted in it.

Parameters

RateLimitWindowState(RateLimitWindow, int) constructor

public RateLimitWindowState(RateLimitWindow Window, int Count)

A key’s effective window and the permits counted in it.

Parameters

Count property

public int Count { get; init; }

Permits counted in Window.

Window property

public RateLimitWindow Window { get; init; }

The effective window.

RateLimiterContract class

public static class RateLimiterContract

The rules every IRateLimiterbackend (Valkey, PostgreSQL, in-memory) applies, so that one RateLimitPolicygives the same decisions on each of them.

Remarks

Algorithm: a fixed window aligned to the Unix epoch. For a window of W milliseconds, a call at Unix time t (milliseconds) belongs to the window that starts at floor(t / W) * W. A key may take at most RateLimitPolicy.MaxPermitspermits in one window. Check and increment are one atomic step in every backend.

A denied attempt does not consume a permit: the count stays at the limit until the window ends.

A key’s stored window never moves backwards. A caller whose clock lags behind a window another caller has already opened is counted in that newer window, so clock skew between hosts cannot reopen permits.

A key keeps one window per policy. Its state under one policy (RateLimitPolicy.MaxPermitsand RateLimitPolicy.Window, named by RateLimiterContract.PolicyIdentity(RateLimitPolicy)) is independent of its state under any other policy, so one limiter can apply a per-minute and a per-day policy to the same key. Equal policies share one window. IRateLimiter.ResetAsync(string, CancellationToken)clears the key under every policy.

MaxKeyLength constant

public const int MaxKeyLength = 512

Longest accepted rate limit key, in UTF-16 code units. Keeps a PostgreSQL key within one index entry.

MaxNameLength constant

public const int MaxNameLength = 40

Longest accepted limiter name. Keeps every derived PostgreSQL identifier within 63 bytes.

MaxWindow field

public static readonly TimeSpan MaxWindow

Longest accepted window.

MinWindow field

public static readonly TimeSpan MinWindow

Shortest accepted window.

CreateResult(bool, RateLimitWindowState, RateLimitPolicy, DateTimeOffset) method

public static RateLimitResult CreateResult(bool allowed, RateLimitWindowState state, RateLimitPolicy policy, DateTimeOffset now)

Builds the result of an acquisition attempt in the shape every backend returns.

Parameters

CreateStatus(RateLimitWindowState, RateLimitPolicy, DateTimeOffset) method

public static RateLimitStatus CreateStatus(RateLimitWindowState state, RateLimitPolicy policy, DateTimeOffset now)

Builds the status of a key in the shape every backend returns.

Parameters

GetWindow(RateLimitPolicy, DateTimeOffset) method

public static RateLimitWindow GetWindow(RateLimitPolicy policy, DateTimeOffset now)

Gets the epoch-aligned window that now falls in for policy.

PolicyIdentity(RateLimitPolicy) method

public static string PolicyIdentity(RateLimitPolicy policy)

Names the state a key keeps for policy: <max permits>/<window in milliseconds>ms, for example 10/60000ms. A key keeps one window per identity.

ResolveStoredWindow(RateLimitWindow, long?, long?, int) method

public static RateLimitWindowState ResolveStoredWindow(RateLimitWindow current, long? storedStartMs, long? storedLengthMs, int storedCount)

Resolves stored key state against the caller’s current window. The stored window is kept when it has the same length and does not start before the current one (the window never moves backwards); otherwise the current window applies with no permits counted.

Parameters

Returns

The effective window and the permits already counted in it.

ValidateKey(string) method

public static void ValidateKey(string key)

Validates a rate limit key: not null, not empty, at most RateLimiterContract.MaxKeyLengthcharacters.

Parameters

Exceptions

ValidateName(string) method

public static string ValidateName(string name)

Validates a limiter name before any backend uses it in a key prefix or a table name. A name is 1 to RateLimiterContract.MaxNameLengthcharacters from a-z, 0-9 and _, starting with a letter.

Parameters

Returns

The validated name, unchanged.

Exceptions