StellaOps.Messaging.RateLimiting.Valkey
Valkey/Redis rate limiter backend for StellaOps.Messaging.RateLimiting
| Package | StellaOps.Messaging.RateLimiting.Valkey |
| 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.Valkey | 3 |
StellaOps.Messaging.RateLimiting.Valkey namespace
| Type | Kind | Description |
|---|---|---|
ValkeyRateLimiter | class | Valkey/Redis implementation of IRateLimiter. |
ValkeyRateLimiterFactory | class | Factory for creating Valkey rate limiter instances. |
ValkeyRateLimiterServiceCollectionExtensions | class | Registers the Valkey rate limiter. |
ValkeyRateLimiter class
public sealed class ValkeyRateLimiter : IRateLimiter
Valkey/Redis implementation of IRateLimiter. Fixed window aligned to the Unix epoch (RateLimiterContract). Each key is one hash (ratelimit:<name>:<key>) with three fields per policy, named after RateLimiterContract.PolicyIdentity(RateLimitPolicy): ws:<policy> window start, wl:<policy> window length and c:<policy> count (for example c:10/60000ms); one Lua script checks and increments one policy’s fields atomically, and a denied attempt writes nothing. Window arithmetic uses the caller’s clock; the key’s TTL, the longest one any policy needs, only bounds how long an ended window is kept.
ValkeyRateLimiter(ValkeyConnectionFactory, string, ILogger<ValkeyRateLimiter>, TimeProvider) constructor
public ValkeyRateLimiter(ValkeyConnectionFactory connectionFactory, string name, ILogger<ValkeyRateLimiter>? logger = null, TimeProvider? timeProvider = null)
Creates a named limiter whose counters are kept in Valkey.
Parameters
connectionFactory: Opens the Valkey connections.name: The limiter name.logger: Receives the diagnostics; none when not set.timeProvider: The clock; the system clock when not set.
Exceptions
ArgumentException:namebreaksRateLimiterContract.ValidateName(string).
ProviderName property
public string ProviderName { get; }
Gets the provider name for diagnostics (e.g., “valkey”, “postgres”, “inmemory”).
GetStatusAsync(string, RateLimitPolicy, CancellationToken) method
public 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
public 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
public 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.
ValkeyRateLimiterFactory class
public sealed class ValkeyRateLimiterFactory : IRateLimiterFactory
Factory for creating Valkey rate limiter instances.
ValkeyRateLimiterFactory(ValkeyConnectionFactory, ILoggerFactory, TimeProvider) constructor
public ValkeyRateLimiterFactory(ValkeyConnectionFactory connectionFactory, ILoggerFactory? loggerFactory = null, TimeProvider? timeProvider = null)
Creates the factory of Valkey limiters.
Parameters
connectionFactory: Opens the Valkey connections.loggerFactory: Creates the limiter loggers; none when not set.timeProvider: The clock; the system clock when not set.
ProviderName property
public string ProviderName { get; }
Gets the provider name for this factory.
Create(string) method
public 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.
ValkeyRateLimiterServiceCollectionExtensions class
public static class ValkeyRateLimiterServiceCollectionExtensions
Registers the Valkey rate limiter.
AddValkeyRateLimiter(IServiceCollection) extension method
public static IServiceCollection AddValkeyRateLimiter(this IServiceCollection services)
Registers ValkeyRateLimiterFactoryas the IRateLimiterFactory. The limiter uses the ValkeyConnectionFactory that the Valkey Messaging transport registers, so register that transport too.
Parameters
services: The service collection.
Returns
The service collection.
