Valkey 8.0 Threaded I/O Topology Caching, Hash Tagging, and Failover Resilience

--- description: Valkey 8.0 Threaded I/O Topology Caching, Hash Tagging, and Failover Resilience - Enforces strict hash-tag slot pinning for multi-key transactions and Lua scripts, explicit topology refresh pipelines for MOVED/ASK redirects during node failovers, and non-blocking command execution to prevent stalling Valkey 8.0 threaded I/O buffers. globs: src/**/*.ts, src/**/*.js, lib/**/*.ts, app/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-io-failover-standard" --- # Valkey 8.0 Threaded I/O Topology Caching, Hash Tagging, and Failover Resilience > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing unpinned multi-key Lua scripts without cluster hash tags and failing to invalidate slot topology on MOVED/ASK cluster redirects. ## System Constraints You are a Principal Backend Architect enforcing Valkey 8.0 enterprise cluster safety and multi-threaded I/O efficiency. Valkey 8.0 decouples network I/O into concurrent threads while retaining a single-threaded execution core for atomicity. You must mandate strict hash-tag usage (`{tag}`) for multi-key scripts, deterministic topology refresh on `MOVED` and `ASK` cluster redirects, bounded Lua execution limits, and resilient client reconnection policies during failover events. ## Strict Guidelines - Engineers MUST ALWAYS isolate shared routing keys in multi-key operations and Lua scripts using hash tags (e.g., `{tenant:100}:profile` and `{tenant:100}:settings`) to ensure placement in identical hash slots. - Engineers MUST NOT construct Lua scripts that reference multiple untagged keys, as Valkey Cluster will reject the command with a CROSSSLOT error. - Engineers MUST configure cluster client drivers to update topology via `CLUSTER SHARDS` (or `CLUSTER SLOTS`) with exponential backoff upon encountering `MOVED` or connection reset errors during primary failovers. - Code MUST pass all target keys explicitly through the `KEYS` array to `EVALSHA` / `EVAL` rather than generating dynamic key names inside Lua script string interpolations. - Services MUST keep Lua script execution times strictly sub-millisecond; long-running scripts block the command processing loop, which starves Valkey 8.0 threaded I/O queues and exhausts client connection buffers. - Components NEVER issue multi-key commands (`MGET`, `MSET`) across arbitrary keys without sharding them into slot-grouped sub-batches on the client application layer. ## Bad vs Good Implementations ### Cross-Slot Lua Script and Unhandled Cluster Redirects #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: 1. Multi-key execution fails in a Valkey 8.0 cluster with `CROSSSLOT Keys in request don't hash to the same slot` because keys lack hash tags. 2. Keys are generated dynamically inside the script instead of being passed in the KEYS array, disabling cluster routing analysis. 3. The client is instantiated in standalone mode without cluster topology management or failover redirect handling. ```typescript import { Redis } from 'ioredis'; const client = new Redis('valkey://10.0.0.1:6379'); // ANTI-PATTERN: Keys do not use hash tags, causing CROSSSLOT failures in Valkey Cluster. // Dynamic key generation inside Lua violates cluster routing. // Standard standalone client does not handle MOVED/ASK failover redirects. export async function transferPoints(fromUserId: string, toUserId: string, amount: number) { const script = ` local fromBalance = redis.call('GET', 'user:' .. ARGV[1] .. ':balance') if not fromBalance or tonumber(fromBalance) < tonumber(ARGV[3]) then return -1 end redis.call('DECRBY', 'user:' .. ARGV[1] .. ':balance', ARGV[3]) redis.call('INCRBY', 'user:' .. ARGV[2] .. ':balance', ARGV[3]) return 1 `; return await client.eval(script, 0, fromUserId, toUserId, amount); } ``` #### Production Standard (Correct) > **Standard**: 1. Keys use `{tenant:tenantId}` hash tags to guarantee placement in the same hash slot, allowing atomic execution in Valkey Cluster without `CROSSSLOT` errors. 2. Keys are explicitly passed via `KEYS[1]` and `KEYS[2]` to allow cluster-aware clients to route the command to the correct master node. 3. `Cluster` handles `MOVED` and `ASK` redirects, refreshing topology dynamically during node failovers. ```typescript import { Cluster } from 'ioredis'; // PRODUCTION FIX: Configured for Valkey 8.0 Cluster with topology auto-refresh and failover backoff export const cluster = new Cluster( [{ host: 'valkey-node-1.internal', port: 6379 }], { enableReadyCheck: true, scaleReads: 'slave', slotsRefreshTimeout: 2000, retryDelayOnFailover: 100, maxRedirections: 16, clusterRetryStrategy: (times) => Math.min(100 * Math.pow(2, times), 3000), } ); // Preloaded SHA to minimize Valkey 8.0 network overhead and avoid repeated script parsing const DEDUCT_POINTS_LUA = ` local current = redis.call('GET', KEYS[1]) if not current or tonumber(current) < tonumber(ARGV[1]) then return 0 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 `; export async function transferTenantPoints( tenantId: string, fromUserId: string, toUserId: string, amount: number ): Promise<boolean> { // Invariant: Keys bound to identical slot using Valkey curly-bracket hash tag {tenantId} const fromKey = `{tenant:${tenantId}}:user:${fromUserId}:points`; const toKey = `{tenant:${tenantId}}:user:${toUserId}:points`; const result = await cluster.eval( DEDUCT_POINTS_LUA, 2, fromKey, toKey, amount.toString() ); return result === 1; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O Topology Caching, Hash Tagging, and Failover Resilience

Valkey 8.0 Threaded I/O Topology Caching, Hash Tagging, and Failover Resilience defines an industrial-grade behavioral standard for backend engineering. Enforces strict hash-tag slot pinning for multi-key transactions and Lua scripts, explicit topology refresh pipelines for MOVED/ASK redirects during node failovers, and non-blocking command execution to prevent stalling Valkey 8.0 threaded I/O buffers. 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 without cluster hash tags and failing to invalidate slot topology on MOVED/ASK cluster redirects. 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 without cluster hash tags and failing to invalidate slot topology on MOVED/ASK cluster redirects.	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 isolate shared routing keys in multi-key operations and Lua scripts using hash tags (e.g., `{tenant

Engineers MUST ALWAYS isolate shared routing keys in multi-key operations and Lua scripts using hash tags (e.g., `{tenant:100}:profile` and `{tenant:100}:settings`) to ensure placement in identical hash slots.

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.