StellaOps.Messaging.RateLimiting.Postgres

PostgreSQL rate limiter backend for StellaOps.Messaging.RateLimiting

PackageStellaOps.Messaging.RateLimiting.Postgres
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.Postgres3

StellaOps.Messaging.RateLimiting.Postgres namespace

TypeKindDescription
PostgresRateLimiterclassPostgreSQL implementation of IRateLimiter.
PostgresRateLimiterFactoryclassFactory for creating PostgreSQL rate limiter instances.
PostgresRateLimiterServiceCollectionExtensionsclassRegisters 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

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.

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

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

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

Returns

The service collection.