StellaOps.Messaging.RateLimiting.Valkey

Valkey/Redis rate limiter backend for StellaOps.Messaging.RateLimiting

PackageStellaOps.Messaging.RateLimiting.Valkey
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.RateLimiting.Valkey3

StellaOps.Messaging.RateLimiting.Valkey namespace

TypeKindDescription
ValkeyRateLimiterclassValkey/Redis implementation of IRateLimiter.
ValkeyRateLimiterFactoryclassFactory for creating Valkey rate limiter instances.
ValkeyRateLimiterServiceCollectionExtensionsclassRegisters 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

Exceptions

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

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

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

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

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

Returns

A configured rate limiter instance.

Exceptions

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

Returns

The service collection.