StellaOps.Messaging.RateLimiting
Rate limiting for services behind a Router gateway: the limiter contract, the fixed-window rules and the limiter factory.
| Package | StellaOps.Messaging.RateLimiting |
| Component | Router |
| Licence | BUSL-1.1 (Router licence) |
| Package kind | Library |
| Target framework | net10.0 |
To add the package to a project, see Installing Stella Ops packages.
Namespaces
| Namespace | Types |
|---|---|
StellaOps.Messaging.RateLimiting | 8 |
StellaOps.Messaging.RateLimiting namespace
| Type | Kind | Description |
|---|---|---|
IRateLimiter | interface | Transport-agnostic rate limiter interface. |
IRateLimiterFactory | interface | Factory for creating rate limiter instances. |
RateLimitPolicy | record | Defines a rate limit policy: at most RateLimitPolicy.MaxPermitspermits per key in each fixed, epoch-aligned window of length RateLimitPolicy.Window(see RateLimiterContract). |
RateLimitResult | struct | Result of a rate limit acquisition attempt. |
RateLimitStatus | struct | Current status of a rate limit key. |
RateLimitWindow | struct | One fixed rate limit window, in Unix milliseconds. |
RateLimitWindowState | struct | A key’s effective window and the permits counted in it. |
RateLimiterContract | class | The 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
key: The rate limit key.policy: The rate limit policy.cancellationToken: Cancellation token.
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
key: The rate limit key.cancellationToken: Cancellation token.
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
key: The rate limit key (e.g., user ID, IP address, resource identifier): 1 toRateLimiterContract.MaxKeyLengthcharacters, compared case-sensitively.policy: The rate limit policy defining max permits and window.cancellationToken: Cancellation token.
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
name: The rate limiter name (used as key prefix, and in PostgreSQL as part of the table name): 1 toRateLimiterContract.MaxNameLengthcharacters froma-z,0-9and_, starting with a letter. Checked byRateLimiterContract.ValidateName(string).
Returns
A configured rate limiter instance.
Exceptions
ArgumentException: The name breaks the rule.
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
MaxPermits: Maximum number of permits allowed within one window; at least 1.Window: The window length: a whole number of milliseconds fromRateLimiterContract.MinWindow(1 second) toRateLimiterContract.MaxWindow(366 days).
Exceptions
ArgumentOutOfRangeException: A value is outside its range, at construction or in awithexpression.
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
MaxPermits: Maximum number of permits allowed within one window; at least 1.Window: The window length: a whole number of milliseconds fromRateLimiterContract.MinWindow(1 second) toRateLimiterContract.MaxWindow(366 days).
Exceptions
ArgumentOutOfRangeException: A value is outside its range, at construction or in awithexpression.
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
StartMs: Window start (inclusive).LengthMs: Window length.
RateLimitWindow(long, long) constructor
public RateLimitWindow(long StartMs, long LengthMs)
One fixed rate limit window, in Unix milliseconds.
Parameters
StartMs: Window start (inclusive).LengthMs: Window length.
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
Window: The effective window.Count: Permits counted inWindow.
RateLimitWindowState(RateLimitWindow, int) constructor
public RateLimitWindowState(RateLimitWindow Window, int Count)
A key’s effective window and the permits counted in it.
Parameters
Window: The effective window.Count: Permits counted inWindow.
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
allowed: Whether a permit was counted.state: The effective window and its count after the attempt.policy: The policy applied.now: The caller’s time.
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
state: The effective window and its count.policy: The policy applied.now: The caller’s time.
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
current: The caller’s window fromRateLimiterContract.GetWindow(RateLimitPolicy, DateTimeOffset).storedStartMs: The stored window start, or null when the key has no state.storedLengthMs: The stored window length, or null when the key has no state.storedCount: The stored permit count.
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
key: The rate limit key.
Exceptions
ArgumentNullException: The key is null.ArgumentException: The key is empty or too long.
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
name: The limiter name.
Returns
The validated name, unchanged.
Exceptions
ArgumentNullException: The name is null.ArgumentException: The name breaks the rule.
