Valkey 8.0 Cluster Topology Routing, Hash Tagging, and Threaded I/O Guardrails

--- description: Valkey 8.0 Cluster Topology Routing, Hash Tagging, and Threaded I/O Guardrails - Enforces strict hash tag partition alignment ({tag}) for atomic Lua scripts and multi-key operations in Valkey 8.0 clusters, alongside deterministic cluster redirect handling (MOVED/ASK) with exponential backoff. Precludes CROSSSLOT exceptions, uncoordinated failover reconnect loops, and unbuffered pipeline degradation in threaded I/O environments. globs: src/**/*.ts, src/**/*.js, lib/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-threaded-io-failover" --- # Valkey 8.0 Cluster Topology Routing, Hash Tagging, and Threaded I/O Guardrails > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing un-tagged multi-key Lua scripts and naive reconnect handling during Valkey cluster failovers. ## System Constraints You are a Principal Engineer enforcing Valkey 8.0 Threaded I/O & Cluster Failover standards. Mandate strict hash slot isolation with hash tags for all atomic operations and robust cluster redirect handling. ## Strict Guidelines - Engineers MUST ALWAYS wrap multi-key parameters and Lua script keys in hash tags (e.g., `{tenant:123}:session`) to guarantee co-location in the same cluster slot (0-16383). - Engineers MUST NOT execute multi-key commands (MGET, MSET, EVAL, FCALL) across distinct hash slots without client-side scatter-gather or explicit key partitioning. - Code SHOULD configure Valkey cluster client drivers with dynamic topology refresh intervals and bounded exponential backoff to handle MOVED and ASK redirects during node failovers. - Services MUST enable offline queuing during failover slot migration windows rather than immediately dropping in-flight pipeline commands. - Components NEVER assume multi-threaded I/O alters command execution atomicity; Valkey 8.0 executes commands sequentially in the main thread while parallelizing socket read/write operations. ## Bad vs Good Implementations ### Valkey Cluster Multi-Key Lua Execution & Failover Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The script uses separate key prefixes (`rate:...` and `profile:...`) without hash tags, causing Valkey Cluster to route them to different hash slots and throw a runtime CROSSSLOT error. Additionally, the cluster client lacks failover backoff, slot refresh strategies, and connection throttling during failovers. ```typescript import { Cluster } from 'ioredis'; // ANTI-PATTERN: Default naive cluster config without failover handling const valkey = new Cluster(['10.0.0.1:6379', '10.0.0.2:6379']); export async function updateRateLimit(userId: string, action: string) { // FAILS in Valkey Cluster: keys map to disparate slots -> CROSSSLOT Keys error const script = ` local current = redis.call('INCR', KEYS[1]) if current == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end redis.call('HSET', KEYS[2], 'lastAction', ARGV[2]) return current `; const key1 = `rate:${userId}:${action}`; const key2 = `profile:${userId}`; return await valkey.eval(script, 2, key1, key2, 60, Date.now()); } ``` #### Production Standard (Correct) > **Standard**: Encapsulating the routing identity within `{user:${userId}}` guarantees both keys map to identical hash slots, preserving atomic Lua execution. The cluster client is hardened with exponential backoff, auto-pipelining for Valkey 8.0 threaded I/O, and proactive slot refresh during cluster node failover. ```typescript import { Cluster } from 'ioredis'; // PRODUCTION FIX: Configured for Valkey 8.0 cluster failovers and threaded I/O pipelines const valkey = new Cluster( [{ host: '10.0.0.1', port: 6379 }, { host: '10.0.0.2', port: 6379 }], { enableOfflineQueue: true, slotsRefreshTimeout: 5000, retryDelayOnFailover: 100, maxRedirections: 5, clusterRetryStrategy: (times) => { const delay = Math.min(100 * Math.pow(2, times), 2000); return delay + Math.floor(Math.random() * 50); // Jittered backoff }, redisOptions: { enableAutoPipelining: true // Optimal for Valkey 8.0 threaded I/O } } ); export async function updateRateLimit(userId: string, action: string): Promise<number> { // Invariant: Keys bound to identical hash slot via explicit '{tag}' const script = ` local current = redis.call('INCR', KEYS[1]) if current == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end redis.call('HSET', KEYS[2], 'lastAction', ARGV[2]) return current `; const slotTag = `{user:${userId}}`; const key1 = `${slotTag}:rate:${action}`; const key2 = `${slotTag}:profile`; return (await valkey.eval(script, 2, key1, key2, 60, Date.now().toString())) as number; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Cluster Topology Routing, Hash Tagging, and Threaded I/O Guardrails

Valkey 8.0 Cluster Topology Routing, Hash Tagging, and Threaded I/O Guardrails defines an industrial-grade behavioral standard for backend engineering. Enforces strict hash tag partition alignment ({tag}) for atomic Lua scripts and multi-key operations in Valkey 8.0 clusters, alongside deterministic cluster redirect handling (MOVED/ASK) with exponential backoff. Precludes CROSSSLOT exceptions, uncoordinated failover reconnect loops, and unbuffered pipeline degradation in threaded I/O environments. 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-tagged multi-key Lua scripts and naive reconnect handling during Valkey cluster failovers. 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-tagged multi-key Lua scripts and naive reconnect handling during Valkey cluster failovers.	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 wrap multi-key parameters and Lua script keys in hash tags (e.g., `{tenant

Engineers MUST ALWAYS wrap multi-key parameters and Lua script keys in hash tags (e.g., `{tenant:123}:session`) 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.