Valkey 8.0 Threaded I/O, Cluster Routing, and Script Atomicity Guardrails

--- description: Valkey 8.0 Threaded I/O, Cluster Routing, and Script Atomicity Guardrails - Enforces strict cluster-topology handling, deterministic hash-tag slot affinity for transactional scripts, and resilient backoff redirection protocols for Valkey 8.0 multi-threaded deployments. Prevents CROSSSLOT evaluation exceptions, slot discovery thundering herds during failovers, and socket contention during threaded I/O execution. globs: src/infrastructure/cache/**/*.{ts,js,py,go}, src/lib/valkey/**/*.{ts,js,py,go}, src/modules/cache/**/*.{ts,js,py,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-threaded-io-cluster-failover-standard" --- # Valkey 8.0 Threaded I/O, Cluster Routing, and Script Atomicity Guardrails > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Un-tagged multi-key Lua scripting and unhandled MOVED/ASK redirect storms during node failover. ## System Constraints You are a Principal Engineer enforcing Valkey 8.0 Threaded I/O & Cluster Failover architectures. Valkey 8.0 uses asynchronous I/O threads for socket reads and writes while retaining single-threaded core execution semantics. You must mandate: 1) Explicit hash-tagging `{...}` on all multi-key operations and Lua scripts to ensure all keys hash to identical cluster slots (CRC16 % 16384); 2) Cluster client configurations that handle MOVED, ASK, and CLUSTERDOWN responses with bounded exponential backoff and topological table refreshes; 3) Zero cross-slot pipeline executions in atomic blocks; 4) Proper separation of KEYS and ARGV in Lua scripts and Valkey functions. ## Strict Guidelines - Engineers MUST ALWAYS enforce hash tags (e.g., `{tenant:100}:balance` and `{tenant:100}:orders`) for all multi-key transactions, MGET/MSET operations, and Lua scripts in clustered environments. - Engineers MUST NOT execute Lua scripts or functions where keys do not map to the same slot, or where keys are dynamically constructed inside the Lua script without passing them through the KEYS array. - Code SHOULD configure Valkey Cluster clients with automatic cluster topology refresh intervals, exponential jittered retry mechanisms for MOVED/ASK redirects, and bounded offline queue sizes to prevent memory exhaustion during primary failover. - Services MUST gracefully distinguish between transient redirection errors (`ASK`, `TRYAGAIN`) and permanent slot reassignments (`MOVED`), triggering immediate topology cache refreshes only on persistent failures to avoid thundering herd requests to the cluster bus. - Components NEVER execute blocking operations (e.g., `BLPOP`, long-running Lua scripts) on threads designated for high-throughput threaded I/O pipelines without circuit-breaking safeguards. ## Bad vs Good Implementations ### Cluster-Safe Hash-Tagged Lua Scripting and Resilient Cluster Client #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The keys 'user:from:balance' and 'user:to:balance' lack hash tags, which causes a fatal 'CROSSSLOT Keys in request don't hash to the same slot' error when nodes in the cluster manage different slots. Additionally, using a non-cluster client fails to handle MOVED/ASK redirects during node failover. ```typescript import { Redis } from 'ioredis'; // ANTI-PATTERN: Client unconfigured for cluster failover; keys lack hash tags, // causing non-deterministic CROSSSLOT errors in Valkey Cluster. const client = new Redis('valkey://10.0.0.1:6379'); export async function transferBalance( fromUser: string, toUser: string, amount: number ): Promise<boolean> { // FAILS in Valkey Cluster: fromUser and toUser map to different CRC16 slots const script = ` local sender = redis.call('GET', KEYS[1]) if not sender or tonumber(sender) < tonumber(ARGV[1]) then return 0 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 `; // Unhandled MOVED/ASK redirect or CROSSSLOT will crash the execution const result = await client.eval( script, 2, `user:${fromUser}:balance`, `user:${toUser}:balance`, amount ); return result === 1; } ``` #### Production Standard (Correct) > **Standard**: The good pattern enforces `{tenant:ID}` hash-tagging so that both keys hash to the same cluster slot (CRC16 % 16384), satisfying Valkey's single-node script execution invariant. The cluster client is initialized with topological refresh timeouts, bounded retries, and offline queue disabling to safeguard multi-threaded I/O pipelines from thundering herd failures during failover. ```typescript import { Cluster, ClusterOptions } from 'iovalkey'; const clusterConfig: ClusterOptions = { clusterRetryStrategy: (times: number) => Math.min(100 * Math.pow(2, times), 2000), enableOfflineQueue: false, maxRedirections: 16, slotsRefreshTimeout: 2000, scaleReads: 'master', }; export const valkeyCluster = new Cluster( [ { host: '10.0.0.1', port: 6379 }, { host: '10.0.0.2', port: 6379 }, { host: '10.0.0.3', port: 6379 } ], clusterConfig ); // LUA script guarantees slot affinity via explicit hash tags `{tenantId}` const ATOMIC_TRANSFER_SCRIPT = ` local sender = redis.call('GET', KEYS[1]) if not sender or tonumber(sender) < tonumber(ARGV[1]) then return 0 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 `; export async function transferBalanceWithinTenant( tenantId: string, fromUser: string, toUser: string, amount: number ): Promise<boolean> { // Use Hash Tags to guarantee both keys map to the exact same cluster slot const senderKey = `{tenant:${tenantId}}:user:${fromUser}:balance`; const recipientKey = `{tenant:${tenantId}}:user:${toUser}:balance`; try { const result = await valkeyCluster.eval( ATOMIC_TRANSFER_SCRIPT, 2, senderKey, recipientKey, amount.toString() ); return result === 1; } catch (error: any) { if (error?.message?.includes('CLUSTERDOWN')) { throw new Error('Valkey cluster failover in progress; retry via idempotency layer'); } throw error; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O, Cluster Routing, and Script Atomicity Guardrails

Valkey 8.0 Threaded I/O, Cluster Routing, and Script Atomicity Guardrails defines an industrial-grade behavioral standard for backend engineering. Enforces strict cluster-topology handling, deterministic hash-tag slot affinity for transactional scripts, and resilient backoff redirection protocols for Valkey 8.0 multi-threaded deployments. Prevents CROSSSLOT evaluation exceptions, slot discovery thundering herds during failovers, and socket contention during threaded I/O execution. 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-tagged multi-key Lua scripting and unhandled MOVED/ASK redirect storms during node failover. 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-tagged multi-key Lua scripting and unhandled MOVED/ASK redirect storms during node failover.	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 enforce hash tags (e.g., `{tenant

Engineers MUST ALWAYS enforce hash tags (e.g., `{tenant:100}:balance` and `{tenant:100}:orders`) for all multi-key transactions, MGET/MSET operations, and Lua scripts in clustered environments.

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.