StellaOps.Messaging.RateLimiting.InMemory
In-process rate limiter backend for StellaOps.Messaging.RateLimiting (for testing and development)
| Package | StellaOps.Messaging.RateLimiting.InMemory |
| 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.InMemory | 5 |
StellaOps.Messaging.RateLimiting.InMemory namespace
| Type | Kind | Description |
|---|---|---|
InMemoryRateLimitRegistry | class | The in-process rate limit state: one RateLimitBucketper limiter key, holding one window per policy. |
InMemoryRateLimiter | class | In-memory implementation of IRateLimiter. |
InMemoryRateLimiterFactory | class | Factory for creating in-memory rate limiter instances. |
InMemoryRateLimiterServiceCollectionExtensions | class | Registers the in-process rate limiter. |
RateLimitBucket | class | Fixed-window state of one in-memory rate limit key: one window per policy, identified by its RateLimitPolicy.MaxPermitsand window length (the algorithm is defined by RateLimiterContract). |
InMemoryRateLimitRegistry class
public sealed class InMemoryRateLimitRegistry
The in-process rate limit state: one RateLimitBucketper limiter key, holding one window per policy. One registry is shared by every limiter its InMemoryRateLimiterFactorycreates, so limiters with the same name share their counts. Counts are not shared between processes.
InMemoryRateLimitRegistry() constructor
public InMemoryRateLimitRegistry()
Creates an instance of InMemoryRateLimitRegistry.
GetOrCreateRateLimitBucket(string) method
public RateLimitBucket GetOrCreateRateLimitBucket(string key)
Gets or creates a rate limit bucket for the specified key.
RemoveRateLimitBucket(string) method
public RateLimitBucket? RemoveRateLimitBucket(string key)
Removes a rate limit bucket.
Returns
The removed bucket, or null when the key had none.
TryGetRateLimitBucket(string) method
public RateLimitBucket? TryGetRateLimitBucket(string key)
Gets the rate limit bucket for the specified key without creating one.
InMemoryRateLimiter class
public sealed class InMemoryRateLimiter : IRateLimiter
In-memory implementation of IRateLimiter. Fixed window aligned to the Unix epoch (RateLimiterContract), one window per key and policy; each key’s check and increment run under that key’s bucket lock, and a denied attempt does not consume a permit.
InMemoryRateLimiter(InMemoryRateLimitRegistry, string, TimeProvider) constructor
public InMemoryRateLimiter(InMemoryRateLimitRegistry registry, string name, TimeProvider? timeProvider = null)
Creates a named limiter over the process-local counters of a registry.
Parameters
registry: Holds the counters.name: The limiter name.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.
InMemoryRateLimiterFactory class
public sealed class InMemoryRateLimiterFactory : IRateLimiterFactory
Factory for creating in-memory rate limiter instances.
InMemoryRateLimiterFactory(InMemoryRateLimitRegistry, TimeProvider) constructor
public InMemoryRateLimiterFactory(InMemoryRateLimitRegistry registry, TimeProvider? timeProvider = null)
Creates the factory of in-memory limiters.
Parameters
registry: Holds the counters of every limiter.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.
InMemoryRateLimiterServiceCollectionExtensions class
public static class InMemoryRateLimiterServiceCollectionExtensions
Registers the in-process rate limiter.
AddInMemoryRateLimiter(IServiceCollection) extension method
public static IServiceCollection AddInMemoryRateLimiter(this IServiceCollection services)
Registers InMemoryRateLimiterFactoryas the IRateLimiterFactory, with one InMemoryRateLimitRegistryfor the process. Needs no Messaging transport.
Parameters
services: The service collection.
Returns
The service collection.
RateLimitBucket class
public sealed class RateLimitBucket
Fixed-window state of one in-memory rate limit key: one window per policy, identified by its RateLimitPolicy.MaxPermitsand window length (the algorithm is defined by RateLimiterContract). Every operation holds the bucket lock, so check and increment are one atomic step.
RateLimitBucket() constructor
public RateLimitBucket()
Creates an instance of RateLimitBucket.
HasLiveWindow(long) method
public bool HasLiveWindow(long nowMs)
Whether the bucket counted permits, under any policy, in a window that has not ended at nowMs.
Read(RateLimitWindow, int) method
public RateLimitWindowState Read(RateLimitWindow current, int maxPermits)
Reads the key’s effective window and count for the policy (maxPermits, current length) without counting a permit.
TryAcquire(RateLimitWindow, int) method
public (bool Allowed, RateLimitWindowState State) TryAcquire(RateLimitWindow current, int maxPermits)
Counts one permit in the key’s effective window for the policy (maxPermits, current length) unless that window already holds maxPermits permits. A denied attempt changes nothing; the windows of other policies are not read or changed.
Parameters
current: The caller’s window.maxPermits: The policy’s permit limit.
Returns
Whether the permit was counted, and the effective window with its count afterwards.
