cache-redis-patterns

Files (7)

• SKILL.md
• DOC_LINKS.md · references/
• ENGINE_ALTERNATIVES.md · references/
• EXAMPLES.md · references/
• MESSAGING_COMMANDS.md · references/
• RATE_LIMITING_LUA.md · references/
• REDIS_PATTERNS_GUIDE.md · references/

SKILL.md (first lines)

## Routing

Choose the smallest workflow that matches the request. Load a reference only when its topic is needed; otherwise use this root guide. Treat the workflow as a heuristic while preserving safety, protocol, schema, destructive-action, and artifact invariants. Provider/API facts remain where intrinsic to the named integration; executor or model choice does not change the contract.

# Caching and Coordination Patterns

Production playbook for caching strategies, data structure selection, rate limiting, distributed locks, messaging, and cluster operations. This skill teaches **patterns first** (cache-aside, write-through, stampede protection, distributed locking) and uses Redis as the primary implementation reference, with alternatives noted throughout.

## Scope

- Adding caching to reduce latency/cost on hot paths.
- Implementing rate limiting, request shaping, or quotas.
- Using Redis for session storage, leaderboards, or real-time counters.
- Coordinating distributed work (locks, leader election).
- Building real-time messaging or event streaming.

## Inputs to collect (ask only if missing / blocking)

- Redis deployment: managed (ElastiCache, Memorystore, Upstash, Redis Cloud) vs self-hosted.
- Redis version and available modules (RedisJSON, RedisSearch, etc.).
- Consistency requirements: how stale can cached data be?
- Keyspace constraints: multi-tenant, per-environment prefixes.
- Expected QPS, payload sizes, and memory budget.

## Step 1 -- Caching patterns

### Cache-aside (lazy loading)

See references/EXAMPLES.md, Example 1, for this implementation path.

- Most common pattern. Application manages cache explicitly.
- Risk: cache miss storm on cold start or mass invalidation.
- Mitigation: warm cache on deploy; use jittered TTLs.

### Write-through

See references/EXAMPLES.md, Example 2, for this implementation path.

- Guarantees cache consistency with DB.
- Higher write latency (cache + DB in write path).
- Good for read-heavy workloads with strong consistency needs.

### Write-behind (write-back)

See references/EXAMPLES.md, Example 3, for this implementation path.

- Lowest write latency. Risk of data loss if Redis crashes before flush.
- Requires reliable flush mechanism (Redis Streams or external queue).
- Good for counters, analytics, non-critical state.

### Read-through

See references/EXAMPLES.md, Example 4, for this implementation path.

- Cache manages its own data loading (application does not manage cache explicitly).
- Requires a cache loader/provider function or library support.
- Simplifies application code; cache handles miss logic.

### Refresh-ahead (proactive)

See references/EXAMPLES.md, Example 5, for this implementation path.

- Eliminates cache miss latency for predictable keys.
- Implement with sorted set of expiry times + background worker.

### Layered caching (near-cache)

See references/EXAMPLES.md, Example 6, for this implementation path.

- Sub-millisecond reads from L1; L2 as shared fallback.
- Use for extremely hot paths (session lookups, feature flags, config).
- Invalidation via Redis Pub/Sub ensures L1 caches stay coherent across instances.

#### Server-assisted near-cache (RESP3 CLIENT TRACKING)

Prefer **server-assisted client-side caching** over a Pub/Sub-driven L1 when the client and library support RESP3 -- Redis pushes invalidation messages itself, so the L1 is reliably invalidated (unlike RESP2/keyspace-notification near-caches) and hot reads skip the network round trip entirely (up to ~45x faster reads).

See references/EXAMPLES.md, Example 7, for this implementation path.

- **Default tracking** uses server-side memory to remember keys; **BCAST** scales to many keys by prefix with no per-key server cost.
- For connection pools, use the **redirect** option to push invalidations to a second (pub/sub) connection (`CLIENT TRACKING ON REDIRECT <client-id>`), since the data connections are shared.
- Client support: redis-py, Lettuce, Redisson, StackExchange.Redis (and others). Complements the L1/Pub-Sub layered pattern above rather than replacing the cross-instance coherence story.
- Detail and a Python sketch: see [references/REDIS_PATTERNS_GUIDE.md](references/REDIS_PATTERNS_GUIDE.md) section 8.
- Reference: https://redis.io/docs/latest/develop/reference/client-side-caching/

## Step 2 -- Data structure selection

| Structure | Use case | Key operations |
|-----------|----------|----------------|
| **String** | Simple K/V, counters, flags | `SET`, `GET`, `INCR`, `SETNX` |
| **Hash** | Object storage, partial updates | `HSET`, `HGET`, `HMGET`, `HINCRBY` |
| **List** | Queues, recent items, activity feeds | `LPUSH`, `RPOP`, `LRANGE`, `LTRIM` |
| **Set** | Tags, unique membership, intersections | `SADD`, `SISMEMBER`, `SINTER`, `SUNION` |
| **Sorted Set** | Leaderboards, priority queues, time-series | `ZADD`, `ZRANGE`, `ZRANGEBYSCORE`, `ZRANK` |
| **Stream** | Event log, reliable messaging, consumer groups | `XADD`, `XREAD`, `XREADGROUP`, `XACK` |
| **JSON** (RedisJSON) | Complex nested documents | `JSON.SET`, `JSON.GET`, `JSON.ARRAPPEND` |
| **Vector Set** (Redis 8+, beta/preview) | Semantic search, embeddings, similarity | `VADD`, `VSIM`, `VREM` |

### Redis 8.x new commands

- **HGETEX / HSETEX** (Redis 8.0+): get/set hash fields with per-field TTL -- simplifies session and cache patterns.
- **MSETEX** (Redis 8.4+): set multiple keys with TTL in a single atomic operation.
- **Atomic compare-and-set**: `SET` command now supports CAS for lock-free concurrency patterns.
- **XACKDEL**: acknowledge and delete stream entries atomically.
- **Vector sets** (Redis 8+, beta/preview -- verify GA status at https://redis.io/docs/): native vector embeddings for semantic search.

### Choosing between Hash and JSON

- **Hash**: flat key-value pairs; native Redis; no module needed. Use HGETEX/HSETEX (Redis 8+) for per-field expiry.
- **JSON**: nested objects, arrays, atomic path updates; built into Redis 8+ (no separate module needed).
- Rule: use Hash for simple objects; JSON for nested structures.

### Memory-efficiency levers (the biggest low-effort cost reducer)

Encoding choice often shrinks cluster sizing more than any pattern change -- collections kept under their **listpack** thresholds use ~5-10x less memory than the `hashtable`/`skiplist` encodings.

- Keep collections under the listpack limits: `hash-max-listpack-entries` 512 / `hash-max-listpack-value` 64 (and the `zset-`, `list-`, `set-max-listpack-*` / `set-max-intset-entries` equivalents). Crossing a threshold permanently converts the key to the heavier encoding.
- **Bucket many small String keys into Hashes** (e.g. ~1000 fields per hash) to amortize the ~per-key overhead -- a large win when you have millions of tiny keys.
- Tune for your workload: raising thresholds (e.g. to 1024) trades CPU for lower memory; lowering them trades memory for CPU.

From rafaelob/aiLine, Apache-2.0.

More from rafaelob/aiLine