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

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Executing unpinned multi-key Lua scripts across cluster slots while mishandling MOVED/ASK redirects and failover state transitions.) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

--- description: Valkey 8.0 Multi-Threaded I/O, Cluster Slot Redirects, and Hash-Tag Script Atomicity - Enforces strict hash-tag slot pinning for atomic multi-key Lua/Functions and resilient MOVED/ASK cluster redirection handling in Valkey 8.0. Prevents CROSSSLOT runtime exceptions, connection thrashing during automated failovers, and false concurrency assumptions under multi-threaded I/O. globs: src/**/*.ts, src/**/*.js, src/**/*.py, src/**/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-threaded-io-failover-standard" --- # Valkey 8.0 Multi-Threaded I/O, Cluster Slot Redirects, and Hash-Tag Script Atomicity > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing unpinned multi-key Lua scripts across cluster slots while mishandling MOVED/ASK redirects and failover state transitions. ## System Constraints You are a Principal Backend Systems Architect enforcing rigorous production standards for Valkey 8.0 deployments. Mandate strict adherence to cluster-aware key hashing, failover handling (MOVED vs ASK), and understanding the boundary between Valkey 8.0 multi-threaded I/O and serialized command execution. ## Strict Guidelines - Engineers MUST ALWAYS enclose common routing identifiers in hash tags (e.g., `{tenant:123}:session` and `{tenant:123}:profile`) for any multi-key command, transaction (MULTI/EXEC), or Lua/Valkey Function to guarantee co-location in the same cluster slot (0-16383). - Engineers MUST differentiate between MOVED and ASK redirection: MOVED requires updating the client slot topology cache immediately; ASK requires an ephemeral ASKING preamble command sent to the target node without altering the global slot map. - Engineers MUST configure exponential backoff with full jitter and a max retry ceiling during cluster failover states to prevent thundering herd reconnection storms during replica promotion. - Code MUST NOT rely on Valkey 8.0 multi-threaded I/O (`io-threads` and `io-threads-do-reads`) for parallelizing command execution logic; I/O threads strictly parallelize socket reads, protocol parsing, and response writes while the core command execution engine remains strictly single-threaded and sequentially consistent. - Services MUST execute multi-key scripts via EVALSHA or FCALL with explicit key count declarations matching only tagged co-located keys, and reject dynamic runtime key derivation inside the Lua body. ## Bad vs Good Implementations ### Cluster-Aware Lua Scripting & Failover-Resilient Client Setup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The keys `user:${fromUser}:bal` and `user:${toUser}:bal` lack hash tags, which causes Valkey Cluster to map them to different hash slots and throw a CROSSSLOT error. Furthermore, using a standalone client against a cluster endpoint fails to handle MOVED/ASK redirects during node failover, causing unhandled connection crashes. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Standalone client used on cluster, missing hash tags causing CROSSSLOT, // and unhandled cluster redirection during primary node failover. export const client = new Redis('redis://valkey-cluster-node-1:6379'); export async function transferTokens(fromUser: string, toUser: string, amount: number) { // FAILS in Valkey Cluster: fromUser and toUser likely hash to different slots (CROSSSLOT error) const luaScript = ` local fromBal = tonumber(redis.call('get', KEYS[1]) or 0) if fromBal < tonumber(ARGV[1]) then return 0 end redis.call('decrby', KEYS[1], ARGV[1]) redis.call('incrby', KEYS[2], ARGV[1]) return 1 `; // No cluster retry policy or redirect tracking configured return await client.eval(luaScript, 2, `user:${fromUser}:bal`, `user:${toUser}:bal`, amount); } ``` #### Production Standard (Correct) > **Standard**: Keys use the `{domain:${scopeId}}` hash tag to ensure slot co-location, preventing CROSSSLOT errors during atomic script execution. The `Cluster` client configuration explicitly manages slot maps, applies bounded exponential backoff with jitter during failover elections, and accurately delegates MOVED/ASK redirection. ```typescript import { Cluster, ClusterOptions } from 'ioredis'; // PRODUCTION INVARIANT: Cluster-aware client with automated slot refreshing, // failover retry backoff, and ASKING redirect management. const clusterOptions: ClusterOptions = { clusterRetryStrategy: (times: number) => { // Bounded exponential backoff with jitter for cluster failover recovery const delay = Math.min(100 * Math.pow(2, times), 3000); const jitter = Math.floor(Math.random() * 200); return delay + jitter; }, enableReadyCheck: true, maxRedirections: 16, slotsRefreshTimeout: 2000, scaleReads: 'slave' }; export const cluster = new Cluster( [ { host: 'valkey-cluster-node-1', port: 6379 }, { host: 'valkey-cluster-node-2', port: 6379 }, { host: 'valkey-cluster-node-3', port: 6379 } ], clusterOptions ); // Explicitly scope operations to a single tenant or shard domain using Valkey hash tags: {...} export async function transferTokensWithinDomain(scopeId: string, fromAccount: string, toAccount: string, amount: number): Promise<boolean> { const script = ` local fromBal = tonumber(redis.call('GET', KEYS[1]) or 0) local deduct = tonumber(ARGV[1]) if fromBal < deduct then return 0 end redis.call('DECRBY', KEYS[1], deduct) redis.call('INCRBY', KEYS[2], deduct) return 1 `; // Hash tag ensures both keys resolve to the exact same cluster hash slot const fromKey = `{domain:${scopeId}}:account:${fromAccount}:bal`; const toKey = `{domain:${scopeId}}:account:${toAccount}:bal`; const result = await cluster.eval(script, 2, fromKey, toKey, amount.toString()); return result === 1; } ```

Architectural Specification & Invariant Rationale

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

Valkey 8.0 Multi-Threaded I/O, Cluster Slot Redirects, and Hash-Tag Script Atomicity defines an industrial-grade behavioral standard for backend engineering. Enforces strict hash-tag slot pinning for atomic multi-key Lua/Functions and resilient MOVED/ASK cluster redirection handling in Valkey 8.0. Prevents CROSSSLOT runtime exceptions, connection thrashing during automated failovers, and false concurrency assumptions under multi-threaded I/O. 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 unpinned multi-key Lua scripts across cluster slots while mishandling MOVED/ASK redirects and failover state transitions. 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 unpinned multi-key Lua scripts across cluster slots while mishandling MOVED/ASK redirects and failover state transitions.	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 routing identifiers in hash tags (e.g., `{tenant

Engineers MUST ALWAYS enclose common routing identifiers in hash tags (e.g., `{tenant:123}:session` and `{tenant:123}:profile`) for any multi-key command, transaction (MULTI/EXEC), or Lua/Valkey Function to guarantee co-location in the same cluster slot (0-16383).

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.