Skip to main content

Crate runlimit_postgres

Crate runlimit_postgres 

Source
Expand description

Replica-safe PostgreSQL storage for Runlimit fixed-window policies.

PostgresLimiter implements the same anchored fixed-window model as the in-memory backend: the first admitted check starts a window, and subsequent checks share that window until it expires. PostgreSQL’s clock is the sole time authority, so callers on different hosts do not need synchronized clocks. Atomic batches use set-based lock, preflight, and update phases, so their number of SQL phases does not grow with the batch size. Single checks use the same separate logical-key, counter-row, and capacity-shard lock phases so every statement that tests row absence starts after the logical key lock has been acquired. PostgresLimiter implements runlimit_core::Limiter for async generic adapters. The optional serde feature enables validated PostgresConfig loading and the corresponding runlimit-core policy and response metadata.

§Installation

Call PostgresLimiter::migrate before serving traffic. It can share SQLx’s _sqlx_migrations table with application migrations only when every participating Migrator configures Migrator::set_ignore_missing to true. A strict application migrator will reject Runlimit’s migration versions as unknown. The first migration creates runlimit_fixed_windows in the connection’s default schema.

MIGRATOR is the raw bundled migrator with SQLx’s strict defaults. It is intended for an exclusively managed migration history and connection. It does not add PostgresLimiter::migrate’s protection against returning a possibly session-locked connection to a pool after an error or cancellation. Applications that retain a strict host migrator should vendor the bundled Runlimit SQL as application-owned migrations, in order, using CREATE_RUNLIMIT_FIXED_WINDOWS_SQL and SET_RUNLIMIT_FIXED_WINDOWS_FILLFACTOR_SQL followed by BOUND_RUNLIMIT_FIXED_WINDOW_CARDINALITY_SQL instead of invoking either Runlimit migrator against the shared history.

§Storage capacity

Every counter belongs to one of CAPACITY_SHARD_COUNT persistent shards. The migration-maintained ledger enforces HARD_MAX_ROWS_PER_SHARD even for older replicas, while PostgresConfig::maximum_rows_per_shard lets current replicas fail closed at a lower operational bound. A full shard denies only new storage keys; existing rows remain usable and active rows are never evicted. Expiry alone does not release a row. Capacity becomes reusable only after PostgresLimiter::cleanup_expired commits its deletion.

§Failure semantics

Pre-commit database failures and pre-commit timeouts mean the transaction did not commit. A CheckError::CommitOutcomeUnknown or CheckError::CommitTimedOut error means PostgreSQL may have committed even though the client did not receive confirmation. CheckError::CommittedResponseInvariant means the commit was confirmed but its response was unusable. Fail closed in all three cases, and do not blindly retry a check that may already have consumed quota. Once the database has produced a denial, an explicit rollback failure or deadline cannot replace that valid decision; the connection is discarded so closing it rolls back the non-mutating denied transaction. Dropping a check or cleanup future prevents the backend from reporting its outcome; if cancellation races with commit, callers must likewise treat the outcome as unknown. Prefer this backend’s configured acquisition and operation budgets to a shorter outer timeout.

The advisory-lock v1 domain and derivation are a cross-replica protocol. They must not be changed in place: replicas from a rolling deployment must calculate identical lock IDs for the same persistent counter. PostgreSQL’s advisory-lock namespace is shared by every application in the same database. An unrelated or deliberately held matching bigint lock therefore blocks the affected Runlimit key until the operation deadline; use a trusted database boundary and restrict advisory-lock privileges for unrelated roles. The persisted capacity-shard derivation is likewise a cross-replica protocol: it XORs the leading bytes of the policy fingerprint and opaque subject key. Changing the derivation or shard count requires a new storage protocol and migration.

§Integration tests

The database tests are opt-in:

RUNLIMIT_POSTGRES_TEST_DATABASE_URL=postgresql:///runlimit_test \
cargo test -p runlimit-postgres --test postgres -- --ignored

Structs§

PostgresConfig
Runtime bounds for PostgreSQL admission work.
PostgresLimiter
A replica-safe rate limiter backed by a PostgreSQL pool.

Enums§

CheckError
Failure from a quota check.
MaintenanceError
Failure from bounded expired-window cleanup.
PostgresConfigError
Invalid PostgreSQL backend configuration.

Constants§

BOUND_RUNLIMIT_FIXED_WINDOW_CARDINALITY_SQL
SQL for the additive 20260726000000_bound_runlimit_fixed_window_cardinality migration.
CAPACITY_SHARD_COUNT
Number of stable capacity shards used by PostgreSQL storage.
CREATE_RUNLIMIT_FIXED_WINDOWS_SQL
SQL for the immutable 20260723000000_create_runlimit_fixed_windows migration.
HARD_MAX_ROWS_PER_SHARD
Database-enforced maximum number of fixed-window rows in one capacity shard.
SET_RUNLIMIT_FIXED_WINDOWS_FILLFACTOR_SQL
SQL for the additive 20260725000000_set_runlimit_fixed_windows_fillfactor migration.

Statics§

MIGRATOR
Raw bundled migrations required by PostgresLimiter.