Valkey 8.0 Threaded I/O Topology, Cluster Hash Tags, and Script Atomicity Guardrails

--- description: Valkey 8.0 Threaded I/O Topology, Cluster Hash Tags, and Script Atomicity Guardrails - Enforces strict cluster slot routing invariants and non-blocking command safety under Valkey 8.0's multi-threaded I/O engine. Prevents CROSSSLOT evaluation exceptions during master failovers, eliminates split-brain script executions, and mandates hash-tagging alongside exponential backoff slot refreshes. globs: src/infrastructure/cache/**/*.ts, src/services/cache/**/*.ts, src/lib/valkey/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-cluster-io-failover-production-standard" --- # Valkey 8.0 Threaded I/O Topology, Cluster Hash Tags, and Script Atomicity Guardrails > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing Cross-Slot Lua Scripts and Unbounded Cluster Reconnection Storms during Master Failover ## System Constraints You are a Principal Systems Architect enforcing Valkey 8.0 Threaded I/O and Cluster Failover invariants. Valkey 8.0 dispatches network parsing and serialization across parallel worker threads while preserving single-threaded execution state. You must guarantee that all multi-key operations, transactions, and Lua scripts explicitly constrain key spaces using RFC 6874-compliant hash tags `{...}`. You must enforce client-side slot redirect handling (MOVED/ASK) with jittered exponential backoff to protect cluster failover routing tables. ## Strict Guidelines - Engineers MUST ALWAYS enforce hash tagging `{tag}` on all keys touched within multi-key operations (MGET, MSET) or Lua/Functions scripts to guarantee single-slot co-location. - Engineers MUST NOT execute ad-hoc Lua scripts that dynamically synthesize cross-slot key references inside the engine or omit KEYS array declarations. - Code SHOULD configure Valkey cluster client drivers with explicit `natMap`, `slotsRefreshTimeout`, and bounded backoff retry loops to prevent I/O thread pipeline starvation during `CLUSTERDOWN` or `MOVED` bursts. - Services MUST route read replicas with explicit `READONLY` context negotiation and handle `ASK` redirects via one-off target socket dispatches without mutating client-side cluster slot maps. - Components NEVER execute blocking operations (e.g., long-running blocking Lua loops or unindexed `KEYS`) that saturate worker threads or stall failover heartbeats (`CLUSTER NODES`). ## Bad vs Good Implementations ### Valkey 8.0 Cluster-Safe Lua Script Execution & Failover Handling #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In a Valkey/Redis Cluster, keys hashing to different slots cannot be atomically updated within a single EVAL script. During cluster failover or slot migration, this execution fails hard. The cluster client configuration also lacks retry backoff, slot refresh controls, and ASK/MOVED safety constraints, creating client-side connection storms during failover. ```typescript import Redis, { Cluster } from 'ioredis'; const cluster = new Cluster([ { host: '10.0.0.1', port: 6379 }, { host: '10.0.0.2', port: 6379 }, ]); // ANTI-PATTERN: Keys span different hash slots causing CROSSSLOT errors in cluster mode. // Dynamic keys in Lua violate slot distribution, and retries hammer the cluster blindly. export async function transferCredits(fromUser: string, toUser: string, amount: number) { const script = ` local balance = redis.call('GET', KEYS[1]) if tonumber(balance) >= tonumber(ARGV[1]) then redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 end return 0 `; // Throws CROSSSLOT Keys in request don't hash to the same slot return await cluster.eval(script, 2, `user:${fromUser}:bal`, `user:${toUser}:bal`, amount); } ``` #### Production Standard (Correct) > **Standard**: Hash tags `{tenant:...}` force both keys into the identical slot (CRC16 mod 16384), satisfying Valkey 8.0 cluster atomicity invariants. The client cluster options configure exponential backoff with jitter and resilient slot refresh timeouts, preventing reconnect storms during automatic master failover. ```typescript import { Cluster, ClusterOptions } from 'ioredis'; const clusterOptions: ClusterOptions = { enableReadyCheck: true, scaleReads: 'slave', maxRedirections: 16, retryDelayOnFailover: 100, retryDelayOnClusterDown: 250, slotsRefreshTimeout: 2000, clusterRetryStrategy: (times: number) => { const delay = Math.min(100 * Math.pow(2, times), 3000); const jitter = Math.floor(Math.random() * 200); return delay + jitter; }, }; export const valkeyCluster = new Cluster( [ { host: '10.0.0.1', port: 6379 }, { host: '10.0.0.2', port: 6379 }, ], clusterOptions ); // PRODUCTION INVARIANT: Use hash tags `{tenantId}` to pin co-located slot boundaries. // All keys are declared in KEYS, preventing CROSSSLOT violations in Valkey 8.0 cluster engine. export async function transferTenantCredits( tenantId: string, fromUser: string, toUser: string, amount: number ): Promise<boolean> { const script = ` local senderKey = KEYS[1] local recipientKey = KEYS[2] local transferAmount = tonumber(ARGV[1]) local currentBal = tonumber(redis.call('GET', senderKey) or '0') if currentBal >= transferAmount then redis.call('DECRBY', senderKey, transferAmount) redis.call('INCRBY', recipientKey, transferAmount) return 1 end return 0 `; // Guaranteed same slot via hash tag: {tenant:123} const senderKey = `{tenant:${tenantId}}:user:${fromUser}:bal`; const recipientKey = `{tenant:${tenantId}}:user:${toUser}:bal`; const result = await valkeyCluster.eval( script, 2, senderKey, recipientKey, amount.toString() ); return result === 1; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O Topology, Cluster Hash Tags, and Script Atomicity Guardrails

Valkey 8.0 Threaded I/O Topology, Cluster Hash Tags, and Script Atomicity Guardrails defines an industrial-grade behavioral standard for backend engineering. Enforces strict cluster slot routing invariants and non-blocking command safety under Valkey 8.0's multi-threaded I/O engine. Prevents CROSSSLOT evaluation exceptions during master failovers, eliminates split-brain script executions, and mandates hash-tagging alongside exponential backoff slot refreshes. 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 Cross-Slot Lua Scripts and Unbounded Cluster Reconnection Storms during Master Failover 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 Cross-Slot Lua Scripts and Unbounded Cluster Reconnection Storms during Master Failover	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 `{tag}` on all keys touched within multi-key operations (MGET, MSET) or Lua/Functions scripts to guarantee single-slot co-location.

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.