StellaOps.Messaging.RateLimiting.InMemory

In-process rate limiter backend for StellaOps.Messaging.RateLimiting (for testing and development)

PackageStellaOps.Messaging.RateLimiting.InMemory
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.InMemory5

StellaOps.Messaging.RateLimiting.InMemory namespace

TypeKindDescription
InMemoryRateLimitRegistryclassThe in-process rate limit state: one RateLimitBucketper limiter key, holding one window per policy.
InMemoryRateLimiterclassIn-memory implementation of IRateLimiter.
InMemoryRateLimiterFactoryclassFactory for creating in-memory rate limiter instances.
InMemoryRateLimiterServiceCollectionExtensionsclassRegisters the in-process rate limiter.
RateLimitBucketclassFixed-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

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.

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

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

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

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

Returns

Whether the permit was counted, and the effective window with its count afterwards.