stemedb/applications/aphoria/dogfood/cachewrap/docs/sources/redis-spec.md

Redis Protocol Specification - Key Excerpts for Cache Client

Authority Tier: Tier 1 (Standards) Source: https://redis.io/docs/reference/protocol-spec/ + https://redis.io/commands/ Relevance: Defines canonical behavior for TTL, eviction, key formats, and command semantics

---

TTL and Expiration (SETEX, EXPIRE, EXPIREAT commands)

User fills in: Fetch Redis command documentation for SETEX, EXPIRE, EXPIREAT

Look for language like:

• "SETEX key seconds value - Set key to hold string value with TTL of seconds"
• "Keys are evicted when their TTL expires"
• "If no expiration is set, keys persist indefinitely"

Key Claims:

• cache/ttl :: required = true

  • Consequence: Missing TTL causes memory leak - cached values never expire, unbounded growth

• cache/ttl :: minimum = 1

  • Consequence: TTL=0 means immediate expiration - cached value unusable

• cache/expiration_strategy :: values = ["passive", "active"]

  • Consequence: Wrong strategy affects memory vs CPU tradeoff

---

Eviction Policies (MAXMEMORY-POLICY)

User fills in: Fetch Redis documentation for maxmemory-policy configuration

Look for:

• LRU (Least Recently Used)
• LFU (Least Frequently Used)
• Random eviction
• No eviction (return errors when memory full)

Key Claims:

• cache/eviction_policy :: required = true

  • Consequence: No eviction policy means undefined behavior when cache full (errors or random eviction)

• cache/eviction_policy :: recommended = "LRU"

  • Consequence: Wrong policy (e.g., random) degrades hit rates

• cache/max_size :: required = true

  • Consequence: Unbounded cache size causes OOM under sustained load

---

Key Format and Validation

User fills in: Fetch Redis documentation on key restrictions

Look for:

• Maximum key length (512 MB but practically much smaller)
• Forbidden characters (control characters, null bytes)
• Key naming best practices

Key Claims:

• cache/key_validation :: required = true

  • Consequence: Unvalidated keys enable injection attacks (control characters, escape sequences)

• cache/key_length :: maximum = 1024

  • Consequence: Excessively long keys waste memory and degrade performance

---

Connection Semantics

User fills in: Fetch Redis documentation on connection handling, pipelining, pooling

Look for:

• Connection persistence recommendations
• Pipelining for performance
• Connection pool sizing

Key Claims:

• cache/connection_pooling :: required = true

  • Consequence: No pooling means new connection per request - resource exhaustion

• cache/connection_timeout :: minimum = 1

  • Consequence: timeout=0 causes indefinite blocking on connection failures

---

Extraction Guide

1. Fetch documentation:

   # Navigate to Redis official docs
   open https://redis.io/docs/
   

2. Search for key sections:

   • Commands: SETEX, EXPIRE, GET, SET
   • Configuration: maxmemory-policy, timeout
   • Best practices: Key design, connection management

3. Extract MUST/SHOULD patterns:

   • Look for normative language (MUST, SHOULD, SHALL)
   • Document consequences from "Common Pitfalls" sections
   • Note performance implications

4. Map to concept paths:

   • cache/ttl
   • cache/eviction_policy
   • cache/key_validation
   • cache/connection_pooling

5. Add to claims with provenance:

   • Provenance: "Redis Protocol Specification v7.0 - SETEX command"
   • Link to specific command or config doc