Architecture

Brume is a single Rust binary that fronts three stores: Postgres for durable configuration, a dedicated Redis for rate-limit counters, and an in-process cache for hot lookups. This page describes how a check flows through that stack and what we never store.

The request path

A rate-limit check touches four layers:

1. Auth. The API key is verified against the auth cache (backed by Postgres). The key's project, tier, and scopes are resolved before any handler runs.
2. Rule resolution. The rule for the namespace is read from the in-process TTL cache. Postgres is never touched per request; rule mutations invalidate the cache.
3. Daily budget. On limit only, the project's daily check ceiling is checked against Redis before the rule evaluation, so a client cannot run unlimited denials.
4. Atomic evaluation. The check runs as one Lua script against the dedicated Redis: blocklist lookup, override resolution, quota check, and the algorithm's counter update happen in a single atomic operation. No race windows, no double-counting.

The verdict and X-RateLimit-* headers come back in the same response.

The stores

Keeping Postgres out of the hot path is deliberate: configuration changes are rare, checks are frequent, and the two should never contend.

Fail-open

If the rate-limit Redis is unreachable, the evaluation fails open: the gateway returns success: true with degraded: true and the X-Brume-RateLimit-Degraded header. Availability wins over correctness, and the degradation is visible rather than silent. The SDK offers the same tradeoff for timeouts and network errors via timeout.fallback and onError.

What we never store

• No request payloads. A check carries a namespace, an identifier, and a cost. There is no body to log, so there is no payload store.
• No identifier history beyond counters. Counters are ephemeral Redis state with window-bound lifetimes; they are not an audit trail of who did what.
• API keys are hashed at rest. The plaintext exists only at creation time.

Deployment shape

One binary, one config, one bill. The gateway runs behind a reverse proxy with TLS termination; upgrades are zero-downtime systemd restarts. See Deployment for the operational model and Runbook: Redis Failover for the failure path.