Redis backend & failure modes

Redis is the shared state layer for things that need to be globally consistent across every instance of your app. Configuration stays in process memory. Behavioral knowledge stays in process memory. Only the cross-instance state goes to Redis.

What lives in Redis - and what doesn't

Rule of thumb: if two replicas need the same answer, it's in Redis. Same on every instance because they all booted from the same code.

Three key categories under redis_prefix

Every key fastapi-guard writes lives under the configured prefix (default "guard_core:").

Rate limits - ZSET. One sorted set per IP (and per IP+endpoint when route-scoped). Members are request IDs, scores are Unix timestamps. Window enforced via score-range removal on each check.

Ban list - STRING. One key per banned IP. Value is metadata; presence of the key + its TTL is what matters. TTL is set to auto_ban_duration on insert.

Agent buffer - JSON (optional). Buffer for events the agent couldn't deliver to the core API. Serialized blobs under agent_events:* and agent_metrics:*. TTL 3600s. Off by default; opt-in for delivery durability.

Naming - what you'll see in redis-cli

Set redis_prefix in SecurityConfig to namespace keys (e.g., when sharing a Redis with another app).

TTL strategy - sliding window vs fixed expiry

Rate limits - sliding window via ZSET scores. On each check: drop members with scores older than (now − window), then count the remaining members. The window IS the score range. No key-level TTL needed for correctness.

ZADD now {req_id}
ZREMRANGEBYSCORE 0 (now-window)
ZCARD

Bans & buffers - fixed expiry on the key. Set the key, set the TTL, walk away. Redis evicts it when it expires. Bans use auto_ban_duration. Agent buffer entries use 3600s.

SETEX banned_ips:{ip} auto_ban_duration ...

Consequence: rate-limit ZSETs self-prune on read; ban keys self-expire on time. Neither needs a sweeper process.

Ban check - two-tier, hot cache + Redis as truth

Every request checks the ban list. A round-trip to Redis per request is too expensive, so an in-memory cache sits in front.

1. Request arrives - middleware extracts the client IP.
2. In-memory cache check - bounded size, TTL per entry. If the IP is here, decision returns immediately.
3. Redis check on miss - source of truth across instances.
4. Cache populate - if Redis returns a ban, populate the in-memory cache so the next request is hot.

Failure modes - what each check does on Redis error

redis_fail_open - Redis outages as an availability decision

Checked before fail_secure, and only for Redis errors: when a check raises a GuardRedisError and redis_fail_open=True, that check is skipped and the request proceeds, while every non-Redis check failure still honors fail_secure. The default is False, so out of the box fail_secure remains the single decision point for all failures, Redis outages included. Flip it only if you've decided a Redis outage is an availability problem rather than a security one.

Rate limiting is the exception on both flags: it catches Redis errors itself and falls back to the in-memory counter, so neither redis_fail_open nor fail_secure ever sees them.

Connection resilience knobs

There is still no application-level reconnect loop - retries and timeouts are delegated to the Redis client - but since guard-core 3.5.0 they are explicitly configurable:

Retries use exponential backoff and fire only on transient connection/timeout errors. Keep both socket timeouts bounded - setting either to None means a partitioned, black-holed Redis blocks every request that needs it, indefinitely.

Operational - two things to get right in production

Shared Redis - all instances, one Redis, one prefix. Rate limits and bans are global state. If two replicas talk to different Redis instances, or the same one with different redis_prefix values, they keep separate ban lists. Symptom: "different replicas ban different IPs." Fix: confirm DSN and prefix match across all instances.

Persistence - AOF or RDB, not in-memory only. Bans are TTL'd Redis keys. If Redis restarts without persistence, every active ban is gone, and dashboards that look healthy will silently un-ban everyone. Run Redis with AOF (appendonly yes) for production.

Troubleshooting