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.

§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 version as unknown. The 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 an application-owned migration instead of invoking either Runlimit migrator against the shared history.

§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. 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 deadline 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.

§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.

Statics§

MIGRATOR
Raw bundled migrations required by PostgresLimiter.