Valkey 8.0 Multi-Threaded I/O, Slot Redirection, and Lua Atomicity Standard

--- description: Valkey 8.0 Multi-Threaded I/O, Slot Redirection, and Lua Atomicity Standard - Enforces strict cluster-aware client configuration, hash-tag slot alignment, and non-blocking command execution for Valkey 8.0 deployments. Guarantees zero-downtime cluster topology transitions during failovers while preventing CROSSSLOT errors and event-loop thread starvation under asynchronous threaded I/O workloads. globs: src/**/*.ts, src/**/*.mts, src/lib/cache/**/*.{ts,js}, src/infrastructure/redis/**/*.{ts,js}, src/infrastructure/valkey/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-threaded-io-production-standard" --- # Valkey 8.0 Multi-Threaded I/O, Slot Redirection, and Lua Atomicity Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Dynamic Key Generation in Lua Scripts and Static Cluster Topologies Causing CROSSSLOT Exceptions and Dropped Failover Traffic ## System Constraints You are a Principal Backend Infrastructure Architect enforcing Valkey 8.0 production standards. You mandate explicit hash-tag slot routing, robust topology refresh mechanics for cluster failover (MOVED/ASK), non-blocking script design for threaded I/O engines, and deterministic key registration in Lua/Valkey Functions. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate co-located multi-key operations within curly brace hash tags (e.g., `{tenant:123}:session`, `{tenant:123}:profile`) to guarantee single-slot mapping across Valkey cluster nodes. - Engineers MUST configure Valkey client connection pools with automated cluster topology refresh on `MOVED` and `CLUSTERDOWN` errors, setting a bounded `slotsRefreshTimeout` to prevent stale node routing during replica promotion. - Code MUST NEVER compute or construct target cache keys dynamically inside Lua scripts or Valkey Functions; all accessed keys MUST be explicitly passed via the `KEYS` array to satisfy cluster routing validation. - Engineers MUST NOT execute long-running (>5ms) Lua scripts or blocking commands (`KEYS *`, non-indexed aggregate scans) because Valkey 8.0's threaded I/O multiplexes socket reads/writes while the command execution engine remains single-threaded. - Clients MUST handle `ASK` redirects by executing an `ASYNC ASKING` command on the destination node connection prior to retrying the command, while persisting existing slot assignments until a `MOVED` redirection is received. - Services MUST enable cluster read-from-replica scaling using `READONLY` mode only for idempotent, eventual-consistency-tolerant operations, ensuring failover detection resets replica read pools immediately. ## Bad vs Good Implementations ### Valkey Cluster Client Initialization and Atomic Multi-Key Lua Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The cluster client lacks slot-refresh triggers upon node failover, causing connection dropouts during primary promotion. Furthermore, the Lua script generates keys internally without explicit declaration in KEYS, which bypasses cluster routing verification and triggers a fatal CROSSSLOT error when keys reside on different hash slots. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Static cluster configuration without topology refresh, // and dynamically constructed keys in Lua causing CROSSSLOT and failover stalls. export const valkeyClient = new Redis.Cluster(['valkey-node-1:6379'], { scaleReads: 'all', // Missing auto-refresh on topology changes }); export async function transferTokensBad( fromUser: string, toUser: string, amount: number ): Promise<boolean> { const script = ` -- Fails in cluster mode: dynamically constructed keys bypass router local fromBal = tonumber(redis.call('GET', 'user:' .. ARGV[1] .. ':bal') or 0) if fromBal < tonumber(ARGV[3]) then return 0 end redis.call('DECRBY', 'user:' .. ARGV[1] .. ':bal', ARGV[3]) redis.call('INCRBY', 'user:' .. ARGV[2] .. ':bal', ARGV[3]) return 1 `; // Throws CROSSSLOT Keys in request don't hash to the same slot return Boolean(await valkeyClient.eval(script, 0, fromUser, toUser, amount)); } ``` #### Production Standard (Correct) > **Standard**: The production implementation configures aggressive cluster topology refreshing upon failover (`slotsRefreshTimeout`, exponential backoff) and leverages client auto-pipelining to exploit Valkey 8.0's multi-threaded I/O. Keys are co-located to the identical cluster slot using hash tags (`{tenant:...}`) and explicitly declared via `KEYS`, preventing CROSSSLOT errors. ```typescript import Redis, { Cluster, ClusterNode } from 'ioredis'; // PRODUCTION STANDARD: Auto-refreshing topology with bounded retry, hash-tags, and explicit KEYS const nodes: ClusterNode[] = [ { host: process.env.VALKEY_HOST_1 ?? 'valkey-01', port: 6379 }, { host: process.env.VALKEY_HOST_2 ?? 'valkey-02', port: 6379 }, ]; export const valkeyCluster = new Cluster(nodes, { dnsLookup: (address, callback) => callback(null, address, 4), enableReadyCheck: true, slotsRefreshTimeout: 2000, // Automatically refresh topology when a node fails over or slots migrate autoResubscribe: true, scaleReads: 'slave', clusterRetryStrategy(times: number) { return Math.min(100 * Math.pow(2, times), 2000); }, redisOptions: { connectTimeout: 5000, commandTimeout: 3000, enableAutoPipelining: true, // Optimizes Valkey 8.0 threaded I/O pipelines }, }); const TRANSFER_SCRIPT = ` local from_bal = tonumber(redis.call('GET', KEYS[1]) or '0') local amount = tonumber(ARGV[1]) if from_bal < amount then return 0 end redis.call('DECRBY', KEYS[1], amount) redis.call('INCRBY', KEYS[2], amount) return 1 `; export async function transferTokensGood( tenantId: string, fromUserId: string, toUserId: string, amount: number ): Promise<boolean> { // Invariant: Multi-key operations MUST share a hash-tag to map to the identical cluster slot const fromKey = `{tenant:${tenantId}}:user:${fromUserId}:bal`; const toKey = `{tenant:${tenantId}}:user:${toUserId}:bal`; const result = await valkeyCluster.eval( TRANSFER_SCRIPT, 2, fromKey, toKey, amount.toString() ); return result === 1; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Multi-Threaded I/O, Slot Redirection, and Lua Atomicity Standard

Valkey 8.0 Multi-Threaded I/O, Slot Redirection, and Lua Atomicity Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict cluster-aware client configuration, hash-tag slot alignment, and non-blocking command execution for Valkey 8.0 deployments. Guarantees zero-downtime cluster topology transitions during failovers while preventing CROSSSLOT errors and event-loop thread starvation under asynchronous threaded I/O workloads. 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: Dynamic Key Generation in Lua Scripts and Static Cluster Topologies Causing CROSSSLOT Exceptions and Dropped Failover Traffic 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	Dynamic Key Generation in Lua Scripts and Static Cluster Topologies Causing CROSSSLOT Exceptions and Dropped Failover Traffic	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 encapsulate co-located multi-key operations within curly brace hash tags (e.g., `{tenant

Engineers MUST ALWAYS encapsulate co-located multi-key operations within curly brace hash tags (e.g., `{tenant:123}:session`, `{tenant:123}:profile`) to guarantee single-slot mapping across Valkey cluster nodes.

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.