Shared rate limits and trusted proxies

Status: Accepted (2026-09-15) · Amends: ADR-0019, ADR-0031, ADR-0038

Context#

v1.0 must replace per-instance rate limits with limits shared across instances (roadmap). Today:

Constraints: PostgreSQL is the only required service (ADR-0014); core can't depend on pgx (ADR-0019); generated apps own their wiring and receive changes through aps upgrade (ADR-0050); tunables are runtime settings, secrets and infrastructure are environment variables (ADR-0031).

The maintainer decided (2026-09-15): when the database can't answer, fall back to per-instance limits; include trusted-proxy handling; make the sign-in limits runtime settings.

Why trusted proxies belong here: a shared per-IP limit behind a load balancer keys every user by the balancer's IP, so one person's retries would lock out everyone. Shared limits are unsafe without it.

Options#

Decision#

1. Core ratelimit: a small interface#

// Decision is the outcome of one request against a limit.
type Decision struct {
	Allowed    bool
	RetryAfter time.Duration // when not allowed
}

// A Taker decides whether a request for key may proceed. An error means the
// limiter couldn't decide; callers allow the request.
type Taker interface {
	Take(ctx context.Context, key string) (Decision, error)
}

• The in-memory *Limiter gains Take; Allow stays for compatibility and is documented as the in-memory shortcut.
• Middleware takes a Taker (a *Limiter still fits, so existing calls compile). An error allows the request: a store that can fail handles its own fallback (below).
• Core stays within its budget: no new dependency.

2. modules/ratelimitpg: the shared limiter#

A new module, like auditpg: core ratelimit, modules/postgres and pgx.

l, err := ratelimitpg.New(pool, "auth_login", ratelimit.Limit{PerSecond: 10.0 / 900, Burst: 10},
	ratelimitpg.WithLogger(logger))
d, err := l.Take(ctx, "ada@example.com")

3. Failing safe: per-instance fallback, and a local pre-check#

• Fallback (maintainer's decision): when the statement fails or times out, Take decides with an in-memory ratelimit.Limiter of the same limit, logs a warning at most once a minute per limiter, and counts ratelimit.fallbacks. Sign-in keeps working with today's per-instance protection during an outage.
• Local pre-check: before the database, each limiter checks an in-memory bucket with twice the burst. A client far over its limit is refused without a database write, so a flood of requests can't become a flood of writes. Normal clients never reach the local limit first.
• Take returns an error only for invalid use (an empty key); outages never surface as errors.

4. Trusted proxies#

5. Limits as runtime settings#

"Account exists" notices stay at one a minute: an anti-abuse rule for email, not a tunable. Settings are audited and apply to every instance through LISTEN/NOTIFY (ADR-0031).

6. Wiring#

• Full presets: every limiter above uses ratelimitpg; the auth use cases take a ratelimit.Taker per limit instead of building their own; the ratelimit_cleanup job is defined; APP_TRUSTED_PROXIES is read and the middleware installed; the four settings are declared.
• Minimal preset: in-memory limiters and trusted proxies (no database).
• aps upgrade adds the module, migration, job, setting declarations and wiring; .env.example documents APP_TRUSTED_PROXIES.

Observability#

• Spans from the pool's tracer on each decision (db.statement names the operation only).
• Counters in ratelimitpg through the OpenTelemetry metric API: ratelimit.decisions (attributes limiter, allowed), ratelimit.fallbacks (limiter, reason).
• GET /ops/system shows fallbacks since start per limiter.
• A denied request is logged at debug; audit keeps recording auth.login.failed with reason rate_limited as today.

Testing#

Why#

• GCRA keeps today's rate-and-burst behaviour exactly, with one row and one statement per decision.
• PostgreSQL is already required; an unlogged table makes it cheap enough for authentication paths.
• Falling back to per-instance limits keeps sign-in available and never removes protection entirely.
• The local pre-check stops the limiter from becoming a way to load the database.
• Trusted proxies make per-IP limits and audit addresses correct behind load balancers.

Trade-offs#

• A database round trip on every rate-limited request (authentication paths only), and a hot key serialises its own requests.
• A crash or failover resets budgets (unlogged table).
• During a database outage, limits are per instance again.
• Operators must list their proxies; a wrong APP_TRUSTED_PROXIES either ignores real client IPs or trusts spoofed ones (documented, and all-trusting ranges refused).
• One more module, table, job and four settings.

Consequences#

• ratelimit gains Taker, Decision, Limit and (*Limiter).Take (additions only); Middleware accepts a Taker.
• New module modules/ratelimitpg (pre-1.0, ADR-0015); httpx.TrustedProxies.
• Full apps: changed auth use-case config (limiters injected), new settings, job, migration and middleware; upgrade notes describe the behaviour change: limits now apply across all instances, so multi-instance deployments see stricter effective limits.
• Threat model: rate-limit rows (credential stuffing, 2FA guessing) gain shared enforcement; a new row for client IP spoofing through forwarded headers.
• ADR-0038's "rate limits are per instance" trade-off and "trusted-proxy client IP handling" follow-up are resolved.

Implementation notes (2026-09-15)#

• Core: ratelimit gains Limit (with Per(n, window) and Valid), Decision, Taker, ErrEmptyKey and (*Limiter).Take; Middleware takes a Taker, so existing calls with a *Limiter compile unchanged. httpx gains ParseTrustedProxies (CIDRs or single addresses; /0 refused with ErrTrustAll) and TrustedProxies. No new core dependency.
• modules/ratelimitpg: NewStore(pool, opts) and store.Limiter(name, limit func(ctx) ratelimit.Limit), so a limit backed by runtime settings applies to the next request. The in-memory pre-check and fallback are rebuilt when the limit changes.
• Storage differs from the decision above in one detail: the table has no expires_at. A bucket is full again exactly when tat has passed, so tat serves both the decision and DeleteExpired (indexed). One statement decides, and returns the snapshot's previous tat and the clock for the retry time, so a refused request costs one round trip too.
• Deferred: fallback counts in GET /ops/system. The OpenTelemetry counters ratelimit.decisions (limiter, allowed, source = database, local or fallback) and ratelimit.fallbacks (limiter, reason = timeout or error) and a warning at most once a minute per limiter cover operations for now.
• Apps: internal/app/rate_limits.go builds four limiters (auth_ip, auth_login, auth_mfa, auth_notice) on the app's pool; the auth use cases take LoginLimiter, MFALimiter and NoticeLimiter (in-memory defaults when nil, for tests and other wiring); the per-IP middleware uses the shared limiter; APP_TRUSTED_PROXIES in all three golden apps; settings auth.ip_requests_per_minute, auth.login_attempts, auth.login_window and auth.mfa_change_attempts in group rate_limits, reason required; the hourly ratelimit_cleanup job; the module's migration copied as 20260917000002_ratelimit_buckets.sql. The 2FA-change limit now has its own budget instead of sharing the sign-in limiter under an mfa: prefix.
• Performance: BenchmarkTake against the Docker PostgreSQL on a laptop: about 0.43 ms per decision, including the round trip.