Redis Distributed State

Why Redis?

By default, AgentWatch stores rate limit counters, circuit breaker state, and response cache in memory. This works well for single-node deployments, but when you scale AgentWatch horizontally behind a load balancer, each node has its own independent counters — a user could send N × nodes requests before hitting the rate limit, and a circuit breaker opened on one node would not protect the others.

Redis solves this by providing a single shared state store that all gateway nodes read and write to atomically.

What Redis Enables

Capability	Without Redis	With Redis
Rate limiting	Per-node (multiply by node count)	Cluster-wide, accurate counts
Circuit breaker	Independent per node	Shared — one open circuit stops all nodes
Response caching	Per-node (cache misses from other nodes)	Shared — any node can serve a cached response
Horizontal scaling	Limited	Full active-active scaling behind a load balancer

Atomic operations: Rate limit increments and checks use Redis Lua scripts, which execute atomically — eliminating race conditions when multiple nodes process requests simultaneously.

Graceful Fallback

If Redis becomes unavailable (connection refused, timeout, etc.), AgentWatch automatically falls back to in-memory state. Rate limits and circuit breakers continue to function on a per-node basis until Redis is restored. No requests are dropped and no errors are surfaced to clients due to Redis outages.

Configuration

In config/database.json (or via environment variables):

{
  "redis": {
    "enabled": true,
    "url": "redis://redis.internal:6379",
    "password": "your-redis-password",
    "db": 0,
    "keyPrefix": "agentwatch:",
    "tls": true
  }
}

Field	Description
enabled	Set to true to activate Redis state sharing
url	Redis connection URL (redis:// or rediss:// for TLS)
password	Redis AUTH password (omit if not set)
db	Redis database index (0–15)
keyPrefix	Prefix for all AgentWatch keys — allows sharing a Redis instance with other services
tls	Enable TLS for encrypted connection (use rediss:// URL with this)

When to Use Redis

Deployment	Redis Needed?
Single-node (development, small teams)	No
Multiple nodes behind load balancer	Yes — required for accurate rate limiting
High-availability active-active	Yes
Kubernetes with multiple replicas	Yes

---