Valkey 8.0 Threaded I/O Topology, Slot Routing & Lua Atomicity Standard

--- description: Valkey 8.0 Threaded I/O Topology, Slot Routing & Lua Atomicity Standard - Enforces strict hash-tag slot locality for multi-key commands and Lua scripts across Valkey 8.0 clusters. Mandates resilient handling of MOVED and ASK redirection topologies during automatic node failovers and configures non-blocking cluster connection pools to prevent event-loop thread starvation under asynchronous threaded I/O workloads. globs: src/**/*.ts, src/**/*.js, lib/**/*.ts, app/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-cluster-failover-threaded-io-guardrail" --- # Valkey 8.0 Threaded I/O Topology, Slot Routing & Lua Atomicity Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing untagged cross-slot multi-key Lua scripts and naive reconnect loops on MOVED/ASK cluster failovers ## System Constraints You are a Principal Software Architect enforcing production invariants for Valkey 8.0 clusters utilizing multi-threaded I/O and dynamic cluster failover. All multi-key operations, transactions, and Lua scripts must strictly align with slot hash tags. Cluster clients must transparently handle MOVED and ASK redirections with bounded retry backoffs and automatic slot table re-mapping. Code must never block the client loop or trigger unpinned CROSSSLOT operations. ## Strict Guidelines - Engineers MUST ALWAYS enclose common entity identifiers in hash tags (e.g., `{tenant:123}:session`, `{tenant:123}:profile`) for any multi-key commands, transactions, or Lua scripts to ensure identical slot hashing across Valkey shards. - Engineers MUST NOT execute Lua scripts or transactions across keys that do not share the exact same hash tag, preventing fatal CROSSSLOT runtime errors during slot migration. - Cluster clients MUST be configured with dynamic slot table refreshing (`enableReadyCheck: true`, explicit `slotsRefreshTimeout`, and cluster topology retry limits) to seamlessly handle master-replica failovers and CLUSTERDOWN transients. - Code MUST NEVER catch MOVED or ASK errors manually via generic retry catches; cluster drivers MUST be allowed to intercept ASK redirects by automatically sending the `ASKING` command before dispatching to the target node. - Engineers MUST ensure client connection pool sizes and socket pipelining conform to Valkey 8.0 threaded I/O concurrency limits, avoiding client-side socket saturation while Valkey handles asynchronous multi-threaded reads/writes. - Lua scripts MUST be pre-loaded via `SCRIPT LOAD` and executed using `EVALSHA`, with strict fallback to `EVAL` only when `NOSCRIPT` is received across newly promoted failover replicas. ## Bad vs Good Implementations ### Cross-Slot Lua Execution and Unhandled Failover Retries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The keys do not share a hash tag, causing fatal CROSSSLOT runtime errors in Valkey Cluster. Furthermore, using a standalone client and manually parsing MOVED exceptions leads to unbound connection leaks, fails to handle ASKING protocol invariants during resharding, and breaks connection reuse optimized for Valkey 8.0 threaded I/O. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Standalone client connected to cluster node without topology refresh const client = new Redis({ host: 'valkey-node-1.internal', port: 6379 }); export async function transferTokens(sourceUser: string, targetUser: string, amount: number) { // Anti-pattern: Untagged keys will map to different cluster slots, causing CROSSSLOT failures const luaScript = ` local src = redis.call('GET', KEYS[1]) if tonumber(src) >= tonumber(ARGV[1]) then redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 end return 0 `; try { return await client.eval( luaScript, 2, `user:${sourceUser}:balance`, // Slot A `user:${targetUser}:balance`, // Slot B (CROSSSLOT error!) amount ); } catch (err: any) { // Anti-pattern: Manual primitive retry on MOVED causes cascading connection storms if (err.message.includes('MOVED')) { const [_, slot, targetNode] = err.message.split(' '); const [host, port] = targetNode.split(':'); const directNode = new Redis({ host, port: Number(port) }); return await directNode.eval(luaScript, 2, `user:${sourceUser}:balance`, `user:${targetUser}:balance`, amount); } throw err; } } ``` #### Production Standard (Correct) > **Standard**: Hash tags `{tenant:${tenantId}}` guarantee that both keys resolve to the exact same hash slot (0-16383), maintaining transactional atomicity inside Valkey. Utilizing a properly configured `Cluster` instance ensures automated slot mapping, MOVED/ASK redirect resolution, and resilient failover reconnects without leaking sockets. ```typescript import { Cluster, ClusterNode, ClusterOptions } from 'ioredis'; const clusterNodes: ClusterNode[] = [ { host: 'valkey-cluster-01.internal', port: 6379 }, { host: 'valkey-cluster-02.internal', port: 6379 }, { host: 'valkey-cluster-03.internal', port: 6379 }, ]; const clusterOptions: ClusterOptions = { enableReadyCheck: true, maxRedirections: 16, slotsRefreshTimeout: 2000, scaleReads: 'master', redisOptions: { connectTimeout: 5000, keepAlive: 10000, }, }; export const valkeyCluster = new Cluster(clusterNodes, clusterOptions); const TRANSFER_SCRIPT = ` local src = redis.call('GET', KEYS[1]) if not src or tonumber(src) < 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 transferTenantTokens( tenantId: string, sourceUser: string, targetUser: string, amount: number ): Promise<boolean> { // Invariant: Keys bound to the same slot using consistent hash tag {tenantId} const sourceKey = `{tenant:${tenantId}}:user:${sourceUser}:balance`; const targetKey = `{tenant:${tenantId}}:user:${targetUser}:balance`; // Cluster driver transparently handles slot resolution, MOVED, and ASKING redirects const result = await valkeyCluster.eval( TRANSFER_SCRIPT, 2, sourceKey, targetKey, amount.toString() ); return result === 1; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O Topology, Slot Routing & Lua Atomicity Standard

Valkey 8.0 Threaded I/O Topology, Slot Routing & Lua Atomicity Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict hash-tag slot locality for multi-key commands and Lua scripts across Valkey 8.0 clusters. Mandates resilient handling of MOVED and ASK redirection topologies during automatic node failovers and configures non-blocking cluster connection pools to prevent 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: Executing untagged cross-slot multi-key Lua scripts and naive reconnect loops on MOVED/ASK cluster failovers 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 cross-slot multi-key Lua scripts and naive reconnect loops on MOVED/ASK cluster failovers	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 enclose common entity identifiers in hash tags (e.g., `{tenant

Engineers MUST ALWAYS enclose common entity identifiers in hash tags (e.g., `{tenant:123}:session`, `{tenant:123}:profile`) for any multi-key commands, transactions, or Lua scripts to ensure identical slot hashing across Valkey shards.

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.