1.4 KiB
Shared fixed-window throttling
Core exposes govoplan_core.core.throttling for security-sensitive endpoints
that need bounded fixed-window counters. Subjects are SHA-256 hashed before they
become store keys. A configured Redis instance provides atomic counters shared
across API workers. Development and temporary Redis outages use a bounded
process-local fallback. Production-like startup rejects an enabled login
throttle without REDIS_URL unless
GOVOPLAN_ALLOW_PROCESS_LOCAL_LOGIN_THROTTLE=true explicitly acknowledges the
single-process limitation. When Redis fails at runtime, local attempts are still
mirrored so losing the distributed store does not reset the active worker's
protection window.
Callers define one or more ThrottleDimension values with a controlled
namespace, a subject and a positive limit. They must call check before an
expensive verifier, record after a failed attempt, and may reset the relevant
dimension after successful verification. A blocked decision includes a
retry_after_seconds value suitable for an HTTP Retry-After header.
The first consumer is Scheduling's anonymous participation password challenge.
Its namespace is poll-participation-password; its subject combines tenant,
scheduling request and Poll's non-secret invitation-token fingerprint. Access's
login throttle predates this primitive and should be migrated onto it in a
separate compatibility-preserving slice.