redis-cache-strategy

name: redis-cache-strategy description: > Redis caching strategy designer and reviewer. ALWAYS use when designing, reviewing, or troubleshooting Redis caching layers — cache pattern selection (cache-aside, write-through, write-behind), TTL strategy, cache stampede/penetration/avalanche prevention, hot key handling, cache-DB consistency, distributed locking, key naming, and degradation design. Use even for "just add a cache" requests — cache invalidation is one of the two hard problems in computer science, and a naive implementation creates subtle consistency bugs that surface only under load.

Redis Cache Strategy Review

Quick Reference

§1 Scope

In scope — Redis caching strategy for production backend services:

• Cache pattern selection (cache-aside, write-through, write-behind, dual-write debounce)
• Key naming conventions and namespace design
• TTL strategy (expiration, jitter, eviction policy alignment)
• Cache failure modes (stampede/penetration/avalanche) and defenses
• Hot key detection and mitigation (singleflight, local cache, sharding)
• Cache-DB consistency design and staleness SLA
• Distributed locking patterns (SETNX, Redlock, lock timeout)
• Cache warmup and cold-start strategies
• Degradation design (cache-down fallback)

Out of scope — delegate to dedicated skills:

• Redis cluster topology, persistence (RDB/AOF), replication config → redis-best-practise
• Application code changes → go-code-reviewer or language-specific reviewer
• Security hardening, ACL, TLS → redis-best-practise

§2 Mandatory Gates

Execute gates sequentially. Each gate has a STOP condition.

Gate 1: Context Collection

STOP: Cannot determine what the cache is caching (no data source, no access pattern). Clarify before proceeding.

PROCEED: At least data source, cache role, and consistency requirement are known or assumed.

Gate 2: Scope Classification

STOP: Request is not cache-related (e.g., Redis Streams pipeline, pub/sub messaging). Redirect to redis-best-practise.

PROCEED: Caching intent confirmed.

Gate 3: Risk Classification

STOP: Any UNSAFE item without fallback design.

PROCEED: Every cache component has risk level and mitigation.

Gate 4: Output Completeness

Before delivering output, verify all §9 Output Contract sections present. §9.9 Uncovered Risks must never be empty.

§3 Depth Selection

Force Standard or higher when any signal appears: write-behind or write-through pattern, distributed lock, multi-service shared cache, consistency SLA < 5s, cache as authoritative store for any data, hot key with >10K QPS.

§4 Degradation Modes

When context is incomplete, degrade gracefully — never fabricate assumptions about consistency requirements.

Hard rule: Never claim a caching strategy is "consistent" without defining the staleness window. In Degraded/Minimal mode, flag "consistency SLA undefined" in §9.9.

§5 Cache Strategy Checklist

Execute every item. Mark PASS / WARN / FAIL with evidence.

5.1 Pattern Selection

1. Cache pattern identified and justified — which pattern (cache-aside / write-through / write-behind / dual-write debounce) is used and why? The pattern must match the read:write ratio and consistency requirement. When uncertain → load references/cache-patterns.md.

2. Source of truth explicitly defined — is the database or the cache the authoritative source? Ambiguity here is the #1 cause of data inconsistency bugs. Rule: the database is almost always the source of truth; the cache is a derived, disposable copy.

3. Invalidation strategy defined — how and when is stale cache data removed? Options: TTL-based expiration, explicit invalidation on write, event-driven invalidation (CDC/pub-sub). At least one must be active.

5.2 Key Design & TTL

4. Key naming follows namespace convention — {service}:{entity}:{id} or {tenant}:{domain}:{version}:{id}. Keys must be deterministic, greppable, and avoid collisions. No bare numeric IDs.

5. TTL is set with jitter — every cached key must have a TTL. Add random jitter (±10-20%) to prevent synchronized expiration (cache avalanche). No immortal keys unless explicitly justified.

6. Key and value size bounded — keys < 1KB, values < 10KB as default guidance. Large values should use Hash fields or compression. Check with redis-cli --bigkeys.

7. Eviction policy matches access pattern — allkeys-lru for general caching, volatile-lru for mixed TTL/permanent keys, allkeys-lfu for frequency-based (Redis 4.0+). Mismatched policy causes unpredictable evictions.

5.3 Failure Mode Defense

8. Stampede (thundering herd) protection — when a hot key expires, hundreds of concurrent requests hit the database simultaneously. Defense: singleflight/mutex pattern (only one goroutine/thread fetches, others wait), or stale-while-revalidate.

9. Penetration protection — requests for non-existent IDs bypass cache and always hit DB. Defense: cache null/empty results with short TTL (30-60s), or bloom filter at cache layer.

10. Avalanche protection — mass key expiration at same time overwhelms DB. Defense: TTL jitter (item 5), multi-level cache (L1 local + L2 Redis), circuit breaker on DB calls.

11. Hot key mitigation — single key receiving disproportionate traffic. Defense: local in-process cache (L1), key sharding (key:{hash%N}), or read replicas. Detect with redis-cli --hotkeys (Redis 4.0+ LFU mode).

5.4 Consistency & Operations

12. Staleness window quantified — define in seconds/minutes how stale cached data can be. This is a business decision, not a technical default. Document it and monitor actual staleness.

13. Distributed lock bounded — if using Redis locks (SETNX + EX), ensure: (a) lock has TTL to prevent deadlock, (b) lock value is unique token for safe release, (c) release uses Lua CAS to prevent releasing someone else's lock. Consider whether the lock actually needs to be distributed.

14. Cache-down degradation path — what happens when Redis is unreachable? Options: serve stale from local cache, bypass to DB directly (with rate limiting), return degraded response. "Service crashes" is not an acceptable answer.

§6 Pattern Selection (Standard + Deep)

Quick decision guide — for full patterns load references/cache-patterns.md.

Cache warmup strategies (for cold start)

• Lazy warmup: first request populates cache (accept initial latency spike)
• Eager warmup: pre-populate on deploy via batch scan of hot entities
• Gradual warmup: route increasing traffic percentage through cache layer (canary)

§7 Anti-Examples

AE-1: Immortal cache key — no TTL set

// WRONG: key lives forever; stale data never expires
rdb.Set(ctx, "user:123", userData, 0)  // 0 = no expiration
// RIGHT: always set TTL with jitter
ttl := 30*time.Minute + time.Duration(rand.Intn(300))*time.Second
rdb.Set(ctx, "user:123", userData, ttl)

AE-2: Write-behind without durable queue

// WRONG: write to Redis, async goroutine writes DB — if process crashes, data lost
rdb.Set(ctx, key, value, ttl)
go func() { db.Save(value) }()  // fire-and-forget = data loss risk
// RIGHT: use durable queue (Kafka, Redis Stream with ACK) between cache and DB

AE-3: Cache-aside without stampede protection

// WRONG: 1000 concurrent requests all miss cache, all query DB simultaneously
val, err := rdb.Get(ctx, key).Result()
if err == redis.Nil {
    val = db.Query(id)        // 1000 goroutines hit DB at once
    rdb.Set(ctx, key, val, ttl)
}
// RIGHT: use singleflight to deduplicate concurrent cache fills
val, err, _ = sfGroup.Do(key, func() (interface{}, error) {
    return db.Query(id)
})

AE-4: KEYS command for batch invalidation

// WRONG: KEYS blocks Redis for the entire scan — O(N) on all keys
keys, _ := rdb.Keys(ctx, "user:*").Result()
rdb.Del(ctx, keys...)
// RIGHT: use SCAN with bounded cursor iteration, or structured invalidation

AE-5: Distributed lock without TTL or safe release

// WRONG: lock has no TTL — if holder crashes, lock is held forever (deadlock)
rdb.SetNX(ctx, "lock:order:123", "1", 0)
// Also WRONG: releasing without checking ownership
rdb.Del(ctx, "lock:order:123")  // may delete someone else's lock
// RIGHT: TTL + unique token + Lua CAS release
token := uuid.New().String()
rdb.SetNX(ctx, "lock:order:123", token, 10*time.Second)
// Release with Lua: if redis.call('get',KEYS[1])==ARGV[1] then return redis.call('del',KEYS[1]) end

AE-6: Cache issue reported as business logic bug

-- WRONG: "Bug: user sees old profile after update"
-- This is a cache staleness issue, not a logic bug. Check invalidation strategy.
-- RIGHT: report as "Cache consistency: stale read after write — invalidation delay"

Extended anti-examples (AE-7 through AE-13) in references/cache-anti-examples.md.

§8 Cache Strategy Scorecard

Critical — any FAIL means overall FAIL

• Cache-DB consistency strategy explicitly defined (not "write both and hope")
• TTL set on all cached keys with jitter (no immortal keys without justification)
• Cache-down degradation path exists (Redis unavailable ≠ service down)

Standard — 4 of 5 must pass

• Cache pattern matches business scenario (not blindly cache-aside for everything)
• Stampede protection for hot keys (singleflight / mutex / stale-while-revalidate)
• Penetration protection (null-value caching or bloom filter)
• Key naming follows {namespace}:{entity}:{id} convention
• Distributed locks have TTL and safe CAS release

Hygiene — 3 of 4 must pass

• Cache hit rate monitoring configured
• Eviction policy matches data access pattern (LRU/LFU/volatile)
• Key and value sizes within bounds (<1KB key, <10KB value)
• Warmup strategy defined for cold start / deployment

Verdict: X/12; Critical: Y/3; Standard: Z/5; Hygiene: W/4. PASS requires: Critical 3/3 AND Standard ≥4/5 AND Hygiene ≥3/4.

§9 Output Contract

Every cache strategy review MUST produce these sections. Write "N/A — [reason]" if inapplicable.

### 9.1 Context Gate
| Item | Value | Source |

### 9.2 Depth & Mode
[Lite/Standard/Deep] × [review/design/troubleshoot] — [rationale]

### 9.3 Risk Assessment
| Component | Pattern | Risk | Notes |

### 9.4 Strategy Design (Standard/Deep; "N/A — Lite" for Lite)
- Pattern selection + justification
- Consistency model + staleness SLA
- Failure mode defenses

### 9.5 Implementation (key schema, TTL config, code patterns)

### 9.6 Validation Plan
- Cache hit rate target
- Staleness measurement
- Failure injection tests (Redis down, hot key, mass expiry)

### 9.7 Degradation Plan (what happens when cache fails)

### 9.8 Monitoring & Alerts
- Hit rate, latency, eviction rate, big key detection

### 9.9 Uncovered Risks (MANDATORY — never empty)
| Area | Reason | Impact | Follow-up |

Volume rules:

• FAIL findings: always fully detailed with fix
• WARN findings: up to 10; overflow to §9.9
• PASS: summary only
• §9.9 minimum: document all assumptions (especially consistency SLA if undefined)

Scorecard summary (append after §9.9):

Scorecard: X/12 — Critical Y/3, Standard Z/5, Hygiene W/4 — PASS/FAIL
Data basis: [full context | degraded | minimal | planning]

§10 Reference Loading Guide