StellaOps.Messaging.RateLimiting.Postgres
PostgreSQL rate limiter backend for StellaOps.Messaging.RateLimiting
| Package | StellaOps.Messaging.RateLimiting.Postgres |
| 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.Postgres | 3 |
StellaOps.Messaging.RateLimiting.Postgres namespace
| Type | Kind | Description |
|---|---|---|
PostgresRateLimiter | class | PostgreSQL implementation of IRateLimiter. |
PostgresRateLimiterFactory | class | Factory for creating PostgreSQL rate limiter instances. |
PostgresRateLimiterServiceCollectionExtensions | class | Registers the PostgreSQL rate limiter. |
PostgresRateLimiter class
public sealed class PostgresRateLimiter : IRateLimiter
PostgreSQL implementation of IRateLimiter. Fixed window aligned to the Unix epoch (RateLimiterContract). Each key has one row per policy; one INSERT ... ON CONFLICT DO UPDATE ... WHERE statement checks and increments it atomically, and a denied attempt updates nothing. The table rate_limit_<name> is created at run time; the limiter name is validated by RateLimiterContract.ValidateName(string)before it reaches SQL.
PostgresRateLimiter(PostgresConnectionFactory, string, ILogger<PostgresRateLimiter>, TimeProvider) constructor
public PostgresRateLimiter(PostgresConnectionFactory connectionFactory, string name, ILogger<PostgresRateLimiter>? logger = null, TimeProvider? timeProvider = null)
Creates a named limiter whose counters are kept in PostgreSQL.
Parameters
connectionFactory: Opens the PostgreSQL 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.
PostgresRateLimiterFactory class
public sealed class PostgresRateLimiterFactory : IRateLimiterFactory
Factory for creating PostgreSQL rate limiter instances.
PostgresRateLimiterFactory(PostgresConnectionFactory, ILoggerFactory, TimeProvider) constructor
public PostgresRateLimiterFactory(PostgresConnectionFactory connectionFactory, ILoggerFactory? loggerFactory = null, TimeProvider? timeProvider = null)
Creates the factory of PostgreSQL limiters.
Parameters
connectionFactory: Opens the PostgreSQL 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.
PostgresRateLimiterServiceCollectionExtensions class
public static class PostgresRateLimiterServiceCollectionExtensions
Registers the PostgreSQL rate limiter.
AddPostgresRateLimiter(IServiceCollection) extension method
public static IServiceCollection AddPostgresRateLimiter(this IServiceCollection services)
Registers PostgresRateLimiterFactoryas the IRateLimiterFactory. The limiter uses the PostgresConnectionFactory (connection and schema) that the PostgreSQL Messaging transport registers, so register that transport too.
Parameters
services: The service collection.
Returns
The service collection.
