Valkey 8.0 Threaded I/O Topology, Hash Tags, and Failover Guardrails

--- description: Valkey 8.0 Threaded I/O Topology, Hash Tags, and Failover Guardrails - Enforces strict key hash-tagging for multi-key operations and atomic Lua scripts, alongside cluster-aware client configuration for Valkey 8.0 threaded I/O deployments. Prevents CROSSSLOT runtime exceptions, pipeline stalls, unhandled MOVED/ASK redirect storms, and connection pool exhaustion during master failovers. globs: src/**/*.ts, src/**/*.js, lib/**/*.ts, config/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-failover-io-threading" --- # Valkey 8.0 Threaded I/O Topology, Hash Tags, and Failover Guardrails > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing un-tagged multi-key Lua scripts via non-clustered clients without backoff-resilient MOVED/ASK redirection handling. ## System Constraints You are a Principal Backend Architect enforcing Valkey 8.0 invariants. Valkey 8.0 parallelizes socket read/write operations via threaded I/O, but executes commands and Lua scripts on the primary engine thread. You must strictly mandate key hash-tagging for multi-key atomicity, topology-aware cluster clients, and automated recovery from MOVED/ASK redirects and cluster failovers. ## Strict Guidelines - Engineers MUST ALWAYS use hash tags (e.g., `{tenant:101}:counter` and `{tenant:101}:metadata`) for any multi-key commands, transactions, or Lua scripts targeting a Valkey cluster to guarantee keys map to the exact same hash slot (0-16383). - Engineers MUST instantiate cluster-aware client drivers configured with automatic cluster slot discovery, refresh policies on MOVED redirects, and exponential backoff jitter on failover. - Engineers MUST NOT execute ad-hoc, unbounded Lua scripts or multi-key operations with distinct hash roots; doing so triggers fatal `CROSSSLOT Keys in request don't hash to the same slot` errors. - Code MUST explicitly separate cluster read-replica traffic (`scaleReads: 'slave'`) from write traffic when offloading I/O in read-heavy architectures, while honoring replica lag tolerances. - Pipelines MUST NOT span cross-slot operations without client-side slot grouping; cluster-aware clients must partition commands by node before pipelining to avoid head-of-line blocking under threaded I/O. - Lua scripts MUST declare all target keys via the `KEYS` array argument rather than hardcoding or dynamically computing key names in the script body, preserving engine slot validation and replication safety. ## Bad vs Good Implementations ### Cluster Token Bucket Rate Limiter with Hash-Tagged Keys and Clustered Client #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The client lacks cluster topology configuration and fails to handle MOVED/ASK redirection during failover. The Lua script accesses multiple keys without hash tags (`{...}`) and computes key names dynamically, which causes immediate CROSSSLOT runtime rejections in a Valkey cluster. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Standard non-cluster client connected to a cluster node // Keys do not share a hash tag, causing CROSSSLOT errors in Lua const client = new Redis('redis://valkey-cluster-node-1:6379'); export async function consumeRateLimit(userId: string, cost: number): Promise<boolean> { const script = ` local tokens = redis.call('GET', 'user:' .. KEYS[1] .. ':tokens') local lastUpdate = redis.call('GET', 'user:' .. KEYS[1] .. ':ts') -- Un-tagged separate keys fail in Valkey Cluster redis.call('SET', 'audit:user:' .. KEYS[1], 'checked') return 1 `; // Runtime error: CROSSSLOT Keys in request don't hash to the same slot return await client.eval(script, 2, userId, `audit:user:${userId}`); } ``` #### Production Standard (Correct) > **Standard**: All accessed keys share the exact same hash tag `{user:id}`, ensuring deterministic placement on the same hash slot and safe atomic execution. The client is explicitly cluster-aware with retry jitter and slot auto-refresh during node failover. ```typescript import { Cluster } from 'ioredis'; // PRODUCTION FIX: Clustered client with automatic slot refresh and redirect handling export const valkeyCluster = new Cluster([ { host: 'valkey-cluster-node-1', port: 6379 }, { host: 'valkey-cluster-node-2', port: 6379 } ], { enableReadyCheck: true, slotsRefreshTimeout: 2000, scaleReads: 'all', clusterRetryStrategy(times: number) { // Exponential backoff with jitter to survive master failover const delay = Math.min(100 * Math.pow(2, times), 3000); return delay + Math.floor(Math.random() * 200); } }); const RATE_LIMIT_LUA = ` local keyTokens = KEYS[1] local keyAudit = KEYS[2] local cost = tonumber(ARGV[1]) local currentTokens = tonumber(redis.call('GET', keyTokens) or '100') if currentTokens >= cost then redis.call('DECRBY', keyTokens, cost) redis.call('SET', keyAudit, ARGV[2], 'EX', 60) return 1 end return 0 `; export async function consumeRateLimit(userId: string, cost: number): Promise<boolean> { // Invariant: Hash tag {...} forces all keys to the exact same cluster hash slot const tokenKey = `{user:${userId}}:tokens`; const auditKey = `{user:${userId}}:audit`; const result = await valkeyCluster.eval( RATE_LIMIT_LUA, 2, tokenKey, auditKey, cost.toString(), Date.now().toString() ); return result === 1; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O Topology, Hash Tags, and Failover Guardrails

Valkey 8.0 Threaded I/O Topology, Hash Tags, and Failover Guardrails defines an industrial-grade behavioral standard for backend engineering. Enforces strict key hash-tagging for multi-key operations and atomic Lua scripts, alongside cluster-aware client configuration for Valkey 8.0 threaded I/O deployments. Prevents CROSSSLOT runtime exceptions, pipeline stalls, unhandled MOVED/ASK redirect storms, and connection pool exhaustion during master failovers. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Executing un-tagged multi-key Lua scripts via non-clustered clients without backoff-resilient MOVED/ASK redirection handling. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Executing un-tagged multi-key Lua scripts via non-clustered clients without backoff-resilient MOVED/ASK redirection handling.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS use hash tags (e.g., `{tenant

Engineers MUST ALWAYS use hash tags (e.g., `{tenant:101}:counter` and `{tenant:101}:metadata`) for any multi-key commands, transactions, or Lua scripts targeting a Valkey cluster to guarantee keys map to the exact same hash slot (0-16383).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.