Valkey 8.0 Threaded I/O, Slot Redirect Handling, and Hash-Tagged Lua Atomicity

--- description: Valkey 8.0 Threaded I/O, Slot Redirect Handling, and Hash-Tagged Lua Atomicity - Enforces strict architectural invariants for Valkey 8.0 cluster topologies, preventing CROSSSLOT errors, main-thread event loop starvation under threaded I/O, and unhandled MOVED/ASK redirects during cluster node failovers. Mandates explicit curly brace hash tagging on all multi-key operations and atomic scripts, accompanied by topology-aware cluster client configurations. globs: src/**/*.ts, src/**/*.js, lib/**/*.ts, services/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-io-atomicity-guardrail" --- # Valkey 8.0 Threaded I/O, Slot Redirect Handling, and Hash-Tagged Lua Atomicity > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing Multi-Key Lua Scripts Without Hash Tags and Relying on Non-Cluster Clients During Failovers ## System Constraints You are a Principal Software Architect enforcing production invariants for Valkey 8.0 in clustered environments. Valkey 8.0 offloads socket reads and writes across multiple I/O threads, but the command execution engine remains single-threaded. You must strictly forbid cross-slot multi-key operations without explicit hash tags, enforce proper cluster client failover resilience (handling MOVED and ASK redirections), and prevent blocking operations inside Lua scripts that stall Valkey's single execution thread. ## Strict Guidelines - Engineers MUST ALWAYS enforce curly brace hash tags `{...}` on multi-key commands, pipelines, and Lua scripts to ensure all target keys hash to the identical 16384 cluster slot (CRC16(tag) % 16384). - Engineers MUST NOT execute Lua scripts or Valkey functions that perform non-deterministic multi-key lookups without passing all referenced keys in the explicit KEYS array. - Services MUST initialize a cluster-aware client (e.g., Valkey-Glide or Cluster-configured ioredis) with automated slot discovery, redirection handling (MOVED/ASK), and exponential backoff retry policies. - Code MUST NEVER execute blocking commands (e.g., BLPOP, long KEYS scans, or O(N) operations on unbounded collections) inside Lua scripts, as threaded I/O does NOT parallelize command execution. - Engineers MUST pre-load and invoke Lua scripts using EVALSHA rather than raw EVAL to minimize network I/O overhead and payload decoding costs across client threads. ## Bad vs Good Implementations ### Cluster-Aware Lua Execution with Hash Tags and Failover Retries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Connecting via a standalone Redis/Valkey client fails to handle MOVED/ASK redirects during node failover. Furthermore, `user:${senderId}:balance` and `user:${recipientId}:balance` hash to different cluster slots, causing Valkey to abort execution with a CROSSSLOT error. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Using a standalone client in a clustered Valkey setup, // un-tagged keys in multi-key Lua scripts causing CROSSSLOT failures, // and raw EVAL with no topology refresh during failovers. const valkey = new Redis('valkey://10.0.0.1:6379'); export async function transferBalance(senderId: string, recipientId: string, amount: number) { const script = ` local senderBal = tonumber(redis.call('GET', KEYS[1]) or '0') if senderBal < tonumber(ARGV[1]) then return 0 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 `; // BUG: KEYS[1] and KEYS[2] will hash to different slots -> CROSSSLOT error in cluster mode return valkey.eval(script, 2, `user:${senderId}:balance`, `user:${recipientId}:balance`, amount); } ``` #### Production Standard (Correct) > **Standard**: The good implementation uses `Cluster` with automatic topology discovery and exponential backoff retry. It guarantees single-slot affinity by using `{tenant:${tenantId}}` as a hash tag on all keys involved in the Lua script, and utilizes `evalsha` with a `NOSCRIPT` fallback to optimize threaded I/O decoding performance. ```typescript import { Cluster, RedisOptions } from 'ioredis'; // PRODUCTION STANDARD: Explicit cluster client with slot refresh, failover resilience, // SHA-preloaded Lua script, and strict partition hash tags `{tenantId}` to guarantee single-slot atomicity. const clusterNodes = [ { host: '10.0.0.1', port: 6379 }, { host: '10.0.0.2', port: 6379 }, { host: '10.0.0.3', port: 6379 } ]; export const valkeyCluster = new Cluster(clusterNodes, { enableReadyCheck: true, scaleReads: 'slave', slotsRefreshTimeout: 2000, clusterRetryStrategy: (times) => Math.min(100 * Math.pow(2, times), 3000), redisOptions: { connectTimeout: 5000, maxRetriesPerRequest: 3 } }); const TRANSFER_SCRIPT = ` local sender = redis.call('GET', KEYS[1]) local current = tonumber(sender or '0') local delta = tonumber(ARGV[1]) if current < delta then return 0 end redis.call('DECRBY', KEYS[1], delta) redis.call('INCRBY', KEYS[2], delta) return 1 `; let scriptSha: string | null = null; export async function transferTenantBalance( tenantId: string, senderId: string, recipientId: string, amount: number ): Promise<boolean> { // Invariant: Both keys share {tenantId} hash tag, guaranteeing identical cluster slot const senderKey = `{tenant:${tenantId}}:user:${senderId}:balance`; const recipientKey = `{tenant:${tenantId}}:user:${recipientId}:balance`; if (!scriptSha) { scriptSha = await valkeyCluster.script('LOAD', TRANSFER_SCRIPT) as string; } try { const result = await valkeyCluster.evalsha(scriptSha, 2, senderKey, recipientKey, amount); return result === 1; } catch (err: any) { if (err.message && err.message.includes('NOSCRIPT')) { scriptSha = await valkeyCluster.script('LOAD', TRANSFER_SCRIPT) as string; const retryResult = await valkeyCluster.evalsha(scriptSha, 2, senderKey, recipientKey, amount); return retryResult === 1; } throw err; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O, Slot Redirect Handling, and Hash-Tagged Lua Atomicity

Valkey 8.0 Threaded I/O, Slot Redirect Handling, and Hash-Tagged Lua Atomicity defines an industrial-grade behavioral standard for backend engineering. Enforces strict architectural invariants for Valkey 8.0 cluster topologies, preventing CROSSSLOT errors, main-thread event loop starvation under threaded I/O, and unhandled MOVED/ASK redirects during cluster node failovers. Mandates explicit curly brace hash tagging on all multi-key operations and atomic scripts, accompanied by topology-aware cluster client configurations. 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 Multi-Key Lua Scripts Without Hash Tags and Relying on Non-Cluster Clients During 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 Multi-Key Lua Scripts Without Hash Tags and Relying on Non-Cluster Clients During 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 enforce curly brace hash tags `{...}` on multi-key commands, pipelines, and Lua scripts to ensure all target keys hash to the identical 16384 cluster slot (CRC16(tag) % 16384).

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.