Valkey 8.0 Threaded I/O Slot Pinning & Failover Invariants

--- description: Valkey 8.0 Threaded I/O Slot Pinning & Failover Invariants - Enforces strict hash-tag slot pinning for multi-key operations and Lua scripts while mandating automated MOVED/ASK redirect recovery in Valkey 8.0. Prevents CROSSSLOT exceptions, uncoordinated failover split-brains, and main-thread execution starvation across threaded I/O engine topologies. globs: src/**/*.ts, src/**/*.service.ts, src/infra/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-cluster-failover-threaded-io-guardrails" --- # Valkey 8.0 Threaded I/O Slot Pinning & Failover Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unpinned Multi-Key Script Execution and Naive Non-Cluster Client Failover Routing ## System Constraints You are a Principal Engineer enforcing Valkey 8.0 Threaded I/O & Cluster Failover standards. Mandate slot pinning invariants via hash tags, deterministic Lua key declarations via KEYS arrays, and resilient retry topologies for MOVED and ASK cluster redirects. ## Strict Guidelines - Engineers MUST ALWAYS use hash tags (e.g., `{tenant:123}:entity`) for all multi-key operations, transactions, and Lua scripts to pin keys to a single Valkey 8.0 hash slot. - Engineers MUST NOT reference or derive key names dynamically inside Lua scripts via ARGV or string concatenation; all accessed keys MUST be passed through the explicit `KEYS` array to allow client-side cluster routing and engine slot verification. - Engineers MUST configure cluster-aware clients with explicit redirect limits, exponential backoff, and topology auto-refresh triggers upon receiving `MOVED` or `ASK` responses during failover events. - Lua scripts MUST NOT perform long-running CPU loops or unbound key scans; while Valkey 8.0 offloads network I/O across threads, command and script execution remains single-threaded per engine and will stall all concurrent I/O threads. - Cluster clients MUST explicitly handle readonly routing by issuing `READONLY` to replicas and falling back to the newly promoted primary immediately upon cluster topology updates. ## Bad vs Good Implementations ### Atomic Multi-Key Counter Update in Valkey 8.0 Cluster #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The client lacks cluster topology awareness, fails to handle MOVED/ASK redirects during failover, passes keys via ARGV preventing Valkey from inspecting slots, and uses keys without hash tags which causes runtime CROSSSLOT errors. ```typescript import { Redis } from 'ioredis'; // ANTI-PATTERN: Standalone client used against cluster, unpinned keys cause CROSSSLOT, // and key is dynamically derived inside Lua script, bypassing slot routing. const client = new Redis('valkey://10.0.0.1:6379'); export async function incrementCounters(tenantId: string, metricA: string, metricB: string) { const script = ` local keyA = ARGV[1] .. ':metric:' .. ARGV[2] local keyB = ARGV[1] .. ':metric:' .. ARGV[3] redis.call('INCRBY', keyA, 1) redis.call('INCRBY', keyB, 1) return {redis.call('GET', keyA), redis.call('GET', keyB)} `; // Fails with CROSSSLOT in Valkey Cluster and breaks cluster-aware pipelining return await client.eval(script, 0, tenantId, metricA, metricB); } ``` #### Production Standard (Correct) > **Standard**: Uses a properly configured Valkey Cluster client that handles node topology changes during failover, binds multi-key operations to the same hash slot via `{tenant:...}` hash tags, and exposes all target keys via the KEYS array for correct slot mapping. ```typescript import { Cluster } from 'ioredis'; // PRODUCTION FIX: Cluster-aware client with failover retries, slot-pinned hash tags, // and all keys explicitly passed in the KEYS array. const cluster = new Cluster(['valkey://10.0.0.1:6379', 'valkey://10.0.0.2:6379'], { clusterRetryStrategy: (times) => Math.min(100 * Math.pow(2, times), 2000), slotsRefreshTimeout: 2000, enableReadyCheck: true, scaleReads: 'slave', }); const INCREMENT_METRICS_LUA = ` redis.call('INCRBY', KEYS[1], 1) redis.call('INCRBY', KEYS[2], 1) return {redis.call('GET', KEYS[1]), redis.call('GET', KEYS[2])} `; export async function incrementCounters(tenantId: string, metricA: string, metricB: string): Promise<[string, string]> { // Hash tag '{' + tenantId + '}' guarantees both keys map to the exact same hash slot const keyA = `{tenant:${tenantId}}:metric:${metricA}`; const keyB = `{tenant:${tenantId}}:metric:${metricB}`; const result = await cluster.eval( INCREMENT_METRICS_LUA, 2, keyA, keyB ) as [string, string]; return result; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O Slot Pinning & Failover Invariants

Valkey 8.0 Threaded I/O Slot Pinning & Failover Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces strict hash-tag slot pinning for multi-key operations and Lua scripts while mandating automated MOVED/ASK redirect recovery in Valkey 8.0. Prevents CROSSSLOT exceptions, uncoordinated failover split-brains, and main-thread execution starvation across threaded I/O engine topologies. 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: Unpinned Multi-Key Script Execution and Naive Non-Cluster Client Failover Routing 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	Unpinned Multi-Key Script Execution and Naive Non-Cluster Client Failover Routing	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 use hash tags (e.g., `{tenant

Engineers MUST ALWAYS use hash tags (e.g., `{tenant:123}:entity`) for all multi-key operations, transactions, and Lua scripts to pin keys to a single Valkey 8.0 hash slot.

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.