Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Architecture

--- description: Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Architecture - Enforces strict cluster hash-tag pinning for multi-key operations and Lua scripts to prevent CROSSSLOT errors during Valkey 8.0 cluster failovers and resharding. Mandates resilient client topology caching, automated MOVED/ASK redirect recovery, and connection pooling calibrated to Valkey 8.0 threaded I/O throughput capabilities. 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-topology-slot-atomicity-standard" --- # Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Architecture > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing un-hashed multi-key Lua scripts and naive failover handling causing CROSSSLOT exceptions and cluster split-brain reads ## System Constraints You are a Principal Backend Architect specializing in high-throughput distributed caching with Valkey 8.0. Your role is to enforce zero-downtime cluster invariants: mandate that all multi-key transactions and Lua scripts enforce hash tag pinning `{slot_key}` to map to identical cluster hash slots (0-16383); verify that cluster clients handle MOVED and ASK redirects with exponential backoff and slot table invalidation during failover; and ensure client pool sizing respects Valkey 8.0's multi-threaded I/O model without overwhelming worker event loops. ## Strict Guidelines - Engineers MUST ALWAYS enforce hash tag syntax `{partition_key}` on all compound keys accessed within the same transaction (`MULTI`/`EXEC`), pipeline, or Lua script. - Engineers MUST NOT issue multi-key commands (`MGET`, `MSET`, `DEL`, `RENAME`) across divergent keys without verified hash-tag slot alignment. - Code SHOULD configure cluster clients with explicit topology auto-refresh triggers on `MOVED` redirects and periodic interval checks to survive replica failover promotions. - Services MUST route write traffic exclusively to cluster primary nodes and route replica reads only when connection sessions issue the `READONLY` command. - Components NEVER execute long-running blocking Lua scripts that stall the Valkey main execution thread, regardless of the number of enabled `io-threads`. ## Bad vs Good Implementations ### Cluster-Aware Lua Scripting & Failover-Safe Client Initialization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The Lua script executes against multi-slot keys without hash tags, causing Valkey 8.0 to throw a `CROSSSLOT Keys in request don't hash to the same slot` error. Furthermore, the cluster client lacks reconnection backoff, max redirect thresholds, and automated slot topology refresh logic during primary failover. ```typescript import { Cluster } from 'ioredis'; // Anti-pattern: Missing cluster failover policies and using un-hashed keys in Lua export const valkeyCluster = new Cluster([ { host: 'valkey-node-1', port: 6379 } ]); export async function transferBalance(senderId: string, receiverId: string, amount: number) { // FAILS in Valkey Cluster: keys hash to different slots -> CROSSSLOT error const luaScript = ` local senderBal = tonumber(redis.call('GET', KEYS[1]) or 0) if senderBal >= tonumber(ARGV[1]) then redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 end return 0 `; return valkeyCluster.eval( luaScript, 2, `user:${senderId}:balance`, // Slot X `user:${receiverId}:balance`, // Slot Y (Different slot! Throws CROSSSLOT error) amount.toString() ); } ``` #### Production Standard (Correct) > **Standard**: Enforces slot pinning via `{tenant:id}` hash tags, guaranteeing that all keys reside in the same Valkey 8.0 cluster slot and preserving script atomicity. The cluster client is configured with exponential failover backoff, slot refresh on `MOVED` redirects, and TCP connection parameters optimized for Valkey 8.0 threaded socket handling. ```typescript import { Cluster, ClusterOptions } from 'ioredis'; const clusterConfig: ClusterOptions = { enableReadyCheck: true, // Auto-refresh cluster slot table upon encountering node failover MOVED redirects scaleReads: 'slave', maxRedirections: 16, retryDelayOnFailover: 100, retryDelayOnClusterDown: 250, slotsRefreshTimeout: 2000, clusterRetryStrategy: (times: number) => { const delay = Math.min(times * 100, 3000); return delay; }, redisOptions: { connectTimeout: 5000, keepAlive: 30000, noDelay: true // Leverages Valkey 8.0 threaded I/O batch pipeline efficiency } }; export const valkeyCluster = new Cluster( [ { host: 'valkey-node-1', port: 6379 }, { host: 'valkey-node-2', port: 6379 }, { host: 'valkey-node-3', port: 6379 } ], clusterConfig ); export async function updateTenantLedger( tenantId: string, accountId: string, delta: number ): Promise<number> { // Invariant: Pin keys to identical slot using '{tenantId}' hash-tag const ledgerKey = `{tenant:${tenantId}}:account:${accountId}:balance`; const auditKey = `{tenant:${tenantId}}:audit_log`; const atomicLedgerUpdateLua = ` local current = tonumber(redis.call('GET', KEYS[1]) or '0') local nextVal = current + tonumber(ARGV[1]) redis.call('SET', KEYS[1], tostring(nextVal)) redis.call('RPUSH', KEYS[2], cjson.encode({ account = ARGV[2], delta = ARGV[1], ts = ARGV[3] })) return nextVal `; const now = Date.now().toString(); return (await valkeyCluster.eval( atomicLedgerUpdateLua, 2, ledgerKey, auditKey, delta.toString(), accountId, now )) as number; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Architecture

Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Architecture defines an industrial-grade behavioral standard for backend engineering. Enforces strict cluster hash-tag pinning for multi-key operations and Lua scripts to prevent CROSSSLOT errors during Valkey 8.0 cluster failovers and resharding. Mandates resilient client topology caching, automated MOVED/ASK redirect recovery, and connection pooling calibrated to Valkey 8.0 threaded I/O throughput capabilities. 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 un-hashed multi-key Lua scripts and naive failover handling causing CROSSSLOT exceptions and cluster split-brain reads 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 un-hashed multi-key Lua scripts and naive failover handling causing CROSSSLOT exceptions and cluster split-brain reads	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 tag syntax `{partition_key}` on all compound keys accessed within the same transaction (`MULTI`/`EXEC`), pipeline, or Lua script.

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.