Valkey 8.0 Threaded I/O, Cluster Slot Redirects, and Hash-Tag Script Atomicity

--- description: Valkey 8.0 Threaded I/O, Cluster Slot Redirects, and Hash-Tag Script Atomicity - Valkey 8.0 leverages an asymmetric multi-threaded I/O engine while retaining single-threaded core execution. In a clustered topology, all multi-key operations and Lua scripts must strictly isolate keys to a single hash slot via curly-brace hash tags, and client instances must implement dynamic topology refresh listeners to handle MOVED and ASK slot redirects transparently during failovers without socket pool exhaustion. globs: src/infrastructure/cache/**/*.{ts,js,py,go}, src/modules/**/cache/**/*.{ts,js,py,go}, src/lib/valkey/**/*.{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-threa-935" --- # Valkey 8.0 Threaded I/O, Cluster Slot Redirects, and Hash-Tag Script Atomicity > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing untagged multi-key Lua scripts and naive connection routing leading to CROSSSLOT errors and cluster failover blackouts. ## System Constraints You are a Principal Backend Architect enforcing strict Valkey 8.0 operational and architectural invariants. Valkey 8.0 distributes socket reading, parsing, and serialization across auxiliary I/O threads while maintaining command execution atomicity. You must mandate strict hash-tag enforcement ({hash_tag}) for all multi-key operations and atomic scripts to prevent CROSSSLOT failures across the 16,384 cluster slots. You must ensure client configurations react gracefully to cluster failovers by handling MOVED/ASK redirects, activating dynamic cluster topology refreshes via CLUSTER SHARDS, and preventing blocking operations from stalling the main execution engine. ## Strict Guidelines - Engineers MUST ALWAYS enforce hash tagging ({hash_tag}) around the co-locating key component in all multi-key operations, pipelines, and Lua scripts executed in Valkey Cluster. - Engineers MUST NOT execute Lua scripts or transactions across keys that resolve to disparate hash slots; every key passed into EVAL/EVALSHA or transactional MULTI/EXEC must share the identical {hash_tag}. - Clients MUST configure automatic topology refresh triggers (e.g., enableReadyCheck, natMap, and refresh on MOVED/ASK errors) with exponential backoff to handle node promotions during cluster failovers without thread starvation. - Code SHOULD preload Lua scripts via SCRIPT LOAD and execute via EVALSHA with dynamic fallback to EVAL on NOSCRIPT, rather than repeatedly transmitting raw script bodies across threaded I/O buffers. - Engineers MUST NOT execute long-running computational loops or blocking non-deterministic commands inside Valkey Lua scripts, as the main execution core remains single-threaded despite Valkey 8.0 threaded socket I/O. - Cluster clients MUST distinguish between transient ASK redirects (requiring ASKING followed by a one-off query to the target node) and permanent MOVED redirects (requiring immediate routing table invalidation and slot cache refresh). ## Bad vs Good Implementations ### Cross-Slot Lua Execution and Unhandled Failover Routing vs. Hash-Tagged Resilient Cluster Client #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The script uses separate keys ('user:sender:balance' and 'user:recipient:balance') without a unified hash tag. When these keys map to different slots among the 16,384 cluster partitions, Valkey rejects the execution with a CROSSSLOT error. Furthermore, the cluster client lacks failover retry strategies, slot refresh throttles, and automated topology discovery upon encountering MOVED/ASK responses. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Standalone client used in cluster or cluster client without // slot refresh mechanics, plus cross-slot multi-key Lua script. export class CacheService { private client: Redis.Cluster; constructor() { // Anti-pattern: No topology refresh on failover, static node assumptions this.client = new Redis.Cluster(['valkey-node-1:6379']); } async transferTokens(senderId: string, recipientId: string, amount: number): Promise<boolean> { // Anti-pattern: Multi-key script without hash tags ({...}). // Will intermittently throw 'CROSSSLOT Keys in request don\'t hash to the same slot' // in a clustered Valkey environment. const luaScript = ` local balance = tonumber(redis.call('get', KEYS[1]) or '0') if balance >= tonumber(ARGV[1]) then redis.call('decrby', KEYS[1], ARGV[1]) redis.call('incrby', KEYS[2], ARGV[1]) return 1 end return 0 `; const result = await this.client.eval( luaScript, 2, `user:${senderId}:balance`, `user:${recipientId}:balance`, amount ); return result === 1; } } ``` #### Production Standard (Correct) > **Standard**: The good implementation explicitly uses curly-brace hash tags '{shard:tenantOrShardId}' around both keys to force placement into identical hash slots, preserving script atomicity in Valkey 8.0 cluster mode. It configures cluster failover retry policies, slot refresh timeouts, and auto-pipelining to maximize the throughput of Valkey 8.0's multi-threaded I/O. ```typescript import { Cluster, ClusterOptions } from 'ioredis'; export class ResilientValkeyClusterService { private cluster: Cluster; // Pre-calculated SHA1 cache for EVALSHA private static readonly TRANSFER_SCRIPT = ` local senderBalance = tonumber(redis.call('GET', KEYS[1]) or '0') local transferAmount = tonumber(ARGV[1]) if senderBalance >= transferAmount then redis.call('DECRBY', KEYS[1], transferAmount) redis.call('INCRBY', KEYS[2], transferAmount) return 1 end return 0 `; private transferScriptSha: string | null = null; constructor(seedNodes: Array<{ host: string; port: number }>) { const options: ClusterOptions = { clusterRetryStrategy: (times) => Math.min(100 * Math.pow(2, times), 3000), enableReadyCheck: true, // Dynamic failover and topology updates on MOVED/ASK thresholds slotsRefreshTimeout: 2000, autoPipelining: true, redisOptions: { enableAutoPipelining: true, connectTimeout: 5000 } }; this.cluster = new Cluster(seedNodes, options); } async transferTokens( tenantOrShardId: string, senderId: string, recipientId: string, amount: number ): Promise<boolean> { // INVARIANT: Hash tags {...} guarantee both keys map to the exact same hash slot. const senderKey = `{shard:${tenantOrShardId}}:user:${senderId}:balance`; const recipientKey = `{shard:${tenantOrShardId}}:user:${recipientId}:balance`; try { const result = await this.cluster.eval( ResilientValkeyClusterService.TRANSFER_SCRIPT, 2, senderKey, recipientKey, amount.toString() ); return result === 1; } catch (error: unknown) { if (error instanceof Error && error.message.includes('MOVED')) { // Trigger an immediate non-blocking refresh of cluster slots on topology shift this.cluster.refreshSlotsCache(); } throw error; } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O, Cluster Slot Redirects, and Hash-Tag Script Atomicity

Valkey 8.0 Threaded I/O, Cluster Slot Redirects, and Hash-Tag Script Atomicity defines an industrial-grade behavioral standard for backend engineering. Valkey 8.0 leverages an asymmetric multi-threaded I/O engine while retaining single-threaded core execution. In a clustered topology, all multi-key operations and Lua scripts must strictly isolate keys to a single hash slot via curly-brace hash tags, and client instances must implement dynamic topology refresh listeners to handle MOVED and ASK slot redirects transparently during failovers without socket pool exhaustion. 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 untagged multi-key Lua scripts and naive connection routing leading to CROSSSLOT errors and cluster failover blackouts. 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 untagged multi-key Lua scripts and naive connection routing leading to CROSSSLOT errors and cluster failover blackouts.	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 tagging ({hash_tag}) around the co-locating key component in all multi-key operations, pipelines, and Lua scripts executed in Valkey Cluster.

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.