Skip to content

Redis Service

Purpose: High-performance cache for policy lookups and rate limiting Audience: Backend Engineers, DevOps Source of Truth: TRUTH_MAP.md

Last Updated: February 1, 2026

Purpose

Redis provides sub-millisecond caching for: - Policy evaluation results - Rate limit counters - Session data - Temporary execution state

Key Feature: Enables <2ms policy lookups by caching evaluation results.

Configuration

Variable Required Default Description
REDIS_URL Yes - Full connection URL
REDIS_ADDR No localhost:6379 Host:port (legacy)
REDIS_PASSWORD No - Auth password
REDIS_DB No 0 Database number

Connection URL Format

redis://[:password@]host:port[/db]
rediss://[:password@]host:port[/db]  # TLS

Connection

Environment Connection
Local (Docker) redis://localhost:6379
Railway (Production) redis.railway.internal:6379
Production Use REDIS_URL from Doppler/Railway secrets

Health Check

# Ping
redis-cli -u "$REDIS_URL" ping
# Expected: PONG

# Info
redis-cli -u "$REDIS_URL" info server | head -5

# Memory usage
redis-cli -u "$REDIS_URL" info memory | grep used_memory_human

Key Namespace

Pattern Purpose TTL
tenant:{id}:policy:{hash} Policy evaluation cache 5 min
tenant:{id}:ratelimit:{key} Rate limit counters 1 min
tenant:{id}:session:{id} Session state 24 hr
envelope:{id}:state Execution state 1 hr

Cache Patterns

Policy Evaluation Cache

Key: tenant:abc123:policy:sha256(policy_json)
Value: {"result": "ALLOW", "evaluated_at": "..."}
TTL: 300 seconds

Rate Limiting

Key: tenant:abc123:ratelimit:user:xyz:minute
Value: 45 (counter)
TTL: 60 seconds

Failure Modes

Failure Impact Detection Recovery
Connection lost Cache miss, slower responses Health check Reconnect, graceful degradation
Memory exhaustion Evictions, data loss Memory metrics Increase memory limit
Slow commands Latency spike Slow log Optimize queries

Graceful Degradation: If Redis is unavailable, Fulcrum falls back to database queries (slower but functional).

Monitoring

# Monitor commands in real-time
redis-cli -u "$REDIS_URL" monitor

# Slow log
redis-cli -u "$REDIS_URL" slowlog get 10

# Memory stats
redis-cli -u "$REDIS_URL" memory stats

Security

  • Network: Redis should NOT be exposed publicly
  • Auth: Always use password in production
  • TLS: Use rediss:// URL for encrypted connections
  • Commands: Consider disabling dangerous commands (FLUSHALL, DEBUG)

Back to Runbooks | Documentation