Valkey 8.0 Multi-Threaded I/O, Hash-Tag Clustered Routing, and Failover Resilience

--- description: Valkey 8.0 Multi-Threaded I/O, Hash-Tag Clustered Routing, and Failover Resilience - Enforces strict hash-tag slot affinity for all multi-key operations and Lua scripts in Valkey 8.0 clusters, preventing CROSSSLOT errors during node re-sharding. Mandates explicit MOVED and ASK redirect exponential-backoff handling and proscribes CPU-intensive or long-running blocking operations that stall Valkey 8.0 threaded I/O pipelines. globs: src/**/*.{ts,js,mjs,cjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-slot-redirect-script-atomicity" --- # Valkey 8.0 Multi-Threaded I/O, Hash-Tag Clustered Routing, and Failover Resilience > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Un-hashed Cross-Slot Lua Execution and Unhandled Failover Redirect Storms ## System Constraints You are a Principal Software Architect enforcing Valkey 8.0 Threaded I/O and Cluster Failover invariants. Valkey 8.0 optimizes network I/O across threads, but core execution remains single-threaded per shard, and multi-key atomicity requires strict hash-slot co-location via hash tags '{...}'. You must enforce hashtag-isolated keys for all multi-key scripts/transactions, reject cross-slot executions, mandate cluster client redirect handling (MOVED/ASK) with jittered backoff during master-replica failovers, and eliminate long-running Lua scripts that starve the multi-threaded event loop. ## Strict Guidelines - Engineers MUST ALWAYS wrap multi-key parameters in curly braces '{...}' (hash tags) to guarantee identical hash slot assignment (CRC16 mod 16384) across keys evaluated in transactions or Lua scripts. - Engineers MUST NOT execute Lua scripts, MGET, MSET, or transactions across multiple keys lacking common hash tags in Valkey Cluster mode. - Code MUST explicitly configure cluster clients with auto-topology refresh enabled on MOVED/ASK redirects and cluster state changes, capped with exponential jittered backoff to survive master failover elections. - Services MUST keep Lua scripts non-blocking and idempotent, bounded strictly under 5 milliseconds to prevent stalling the main engine thread and clogging Valkey 8.0 threaded I/O ring buffers. - Components NEVER execute multi-key writes using EVAL/EVALSHA when any key is dynamically computed inside Lua without being declared in the KEYS array. ## Bad vs Good Implementations ### Cross-Slot Lua Script vs Hash-Tagged Cluster Failover-Resilient Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In Valkey Cluster, each shard owns distinct hash slots (0-16383). Calling EVAL on keys with differing CRC16 slot hashes throws a fatal CROSSSLOT exception. Additionally, an ad-hoc cluster client instantiation without topology refresh triggers connection drops during master failover. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Standalone multi-key Lua execution without hash tags // Causes CROSSSLOT errors in cluster mode and lacks failover redirect handling export async function transferCreditsBad(senderId: string, recipientId: string, amount: number) { const client = new Redis.Cluster([{ host: 'valkey-node-1', port: 6379 }]); const script = ` local sender = redis.call('GET', KEYS[1]) if not sender or tonumber(sender) < tonumber(ARGV[1]) then return -1 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 0 `; // BUG: Keys map to different slots (e.g., CRC16('user:101') != CRC16('user:202')) // Will fail with: "CROSSSLOT Keys in request don't hash to the same slot" return await client.eval(script, 2, `user:${senderId}:balance`, `user:${recipientId}:balance`, amount); } ``` #### Production Standard (Correct) > **Standard**: By enclosing the routing boundary in hash tags ('{org:...}'), both keys yield the exact same CRC16 hash slot, safely executing atomically on a single Valkey 8.0 cluster shard. The cluster client configuration handles MOVED/ASK redirects and cluster failovers with bounded jittered backoff. ```typescript import { Cluster, ClusterNode } from 'ioredis'; const clusterNodes: ClusterNode[] = [ { host: process.env.VALKEY_HOST || '127.0.0.1', port: Number(process.env.VALKEY_PORT) || 6379 } ]; // Resilient cluster configuration: auto-refreshes slot table on MOVED/ASK export const valkeyCluster = new Cluster(clusterNodes, { enableReadyCheck: true, scaleReads: 'master', clusterRetryStrategy(times: number) { // Bounded exponential backoff with jitter during failover elections return Math.min(100 * Math.pow(2, times) + Math.random() * 50, 3000); }, slotsRefreshTimeout: 2000, redisOptions: { connectTimeout: 5000, maxRetriesPerRequest: 3 } }); const TRANSFER_SCRIPT = ` local sender = redis.call('GET', KEYS[1]) if not sender or tonumber(sender) < tonumber(ARGV[1]) then return -1 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 0 `; export async function transferCreditsGood(organizationId: string, senderId: string, recipientId: string, amount: number): Promise<number> { // Hash tag '{org:...}' forces both keys to the identical slot (CRC16 calculated ONLY on contents within {}) const senderKey = `{org:${organizationId}}:user:${senderId}:balance`; const recipientKey = `{org:${organizationId}}:user:${recipientId}:balance`; const result = await valkeyCluster.eval( TRANSFER_SCRIPT, 2, senderKey, recipientKey, amount.toString() ); return Number(result); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Multi-Threaded I/O, Hash-Tag Clustered Routing, and Failover Resilience

Valkey 8.0 Multi-Threaded I/O, Hash-Tag Clustered Routing, and Failover Resilience defines an industrial-grade behavioral standard for backend engineering. Enforces strict hash-tag slot affinity for all multi-key operations and Lua scripts in Valkey 8.0 clusters, preventing CROSSSLOT errors during node re-sharding. Mandates explicit MOVED and ASK redirect exponential-backoff handling and proscribes CPU-intensive or long-running blocking operations that stall Valkey 8.0 threaded I/O pipelines. 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: Un-hashed Cross-Slot Lua Execution and Unhandled Failover Redirect Storms 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	Un-hashed Cross-Slot Lua Execution and Unhandled Failover Redirect Storms	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 wrap multi-key parameters in curly braces '{...}' (hash tags) to guarantee identical hash slot assignment (CRC16 mod 16384) across keys evaluated in transactions or Lua scripts.

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.