Valkey 8.0 Cluster Routing, Multi-Threaded I/O, and Atomic Script Invariants

--- description: Valkey 8.0 Cluster Routing, Multi-Threaded I/O, and Atomic Script Invariants - Enforces strict cluster slot routing invariants, failover resilience, and deterministic cross-slot atomic script execution in Valkey 8.0. Prevents runtime CROSSSLOT errors, unbounded connection churn during master failovers, and latency regressions arising from uncoordinated multi-threaded I/O client configurations. globs: src/**/*.ts, src/**/*.js, lib/**/*.ts, config/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-failover-multithreaded-io-standard" --- # Valkey 8.0 Cluster Routing, Multi-Threaded I/O, and Atomic Script Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing un-tagged multi-key Lua scripts and naive failover loops causing CROSSSLOT panics and cluster storm disconnects. ## System Constraints You are a Principal Backend Systems Architect specializing in high-throughput caching and in-memory databases. Mandate strict adherence to Valkey 8.0 cluster topologies, hash tagging ({tenantId}) for transactional Lua execution, exponential-jittered MOVED/ASK redirect recovery, and pipelined I/O thread utilization. ## Strict Guidelines - Engineers MUST ALWAYS enforce uniform cluster hash tags (e.g., `{tenant:123}:entity`) on all multi-key operations and Lua/Function scripts to prevent runtime CROSSSLOT exceptions. - Engineers MUST NOT issue cross-slot commands (MGET, MSET, Lua scripts touching multiple un-tagged keys) across distinct cluster slots without client-side batching or hash-tag collation. - Clients MUST implement automated cluster topology refresh with exponential backoff and jitter upon encountering `MOVED` and `ASK` redirects, avoiding uncoordinated thundering herds during primary election. - Services MUST configure cluster-aware connection pooling aligned with Valkey 8.0's multi-threaded I/O (`io-threads`), maintaining discrete pooled sockets rather than blocking single-connection multiplexers under heavy concurrency. - Components NEVER execute blocking operations (e.g., KEYS, FLUSHALL without ASYNC, long-running unindexed EVAL scripts) that saturate the main execution thread and invalidate Valkey 8.0 I/O parallelization. ## Bad vs Good Implementations ### Cluster-Aware Atomic Rate Limiting Script Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The script uses separate keys ('rate:...' and 'audit:...') without hash tags, causing Valkey Cluster to route them to different hash slots (0-16383), immediately failing with a CROSSSLOT error. Furthermore, a standalone client is used instead of a cluster client equipped to handle MOVED/ASK redirects during node failover. ```typescript import Redis from 'ioredis'; // Anti-pattern: Missing cluster awareness, raw keys crossing slot boundaries, // and naive unhandled failover causing CROSSSLOT and unhandled MOVED errors. const client = new Redis('valkey://10.0.0.1:6379'); export async function checkRateLimit(tenantId: string, userId: string, limit: number): Promise<boolean> { 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], 'last_seen', ARGV[2]) return current <= tonumber(ARGV[3]) `; // BUG: KEYS[1] and KEYS[2] will hash to different cluster slots! // Throws: (error) CROSSSLOT Keys in request don't hash to the same slot const countKey = `rate:${tenantId}:${userId}:count`; const auditKey = `audit:${tenantId}:${userId}:meta`; return (await client.eval(script, 2, countKey, auditKey, 60, Date.now(), limit)) === 1; } ``` #### Production Standard (Correct) > **Standard**: Wraps the tenant identifier in a Valkey hash tag `{tenant:${tenantId}}`, forcing both keys to hash to the exact same cluster slot and preserving script atomicity without CROSSSLOT errors. The cluster client manages automatic slot discovery, node failovers, and reconnect backoffs with randomized jitter. ```typescript import { Cluster, RedisOptions } from 'ioredis'; const clusterNodes = [ { host: '10.0.0.1', port: 6379 }, { host: '10.0.0.2', port: 6379 }, { host: '10.0.0.3', port: 6379 } ]; // Production invariant: Topology refresh, retry backoff with jitter, and cluster slot mapping export const valkeyCluster = new Cluster(clusterNodes, { enableReadyCheck: true, scaleReads: 'slave', clusterRetryStrategy: (times: number) => { const delay = Math.min(100 * Math.pow(2, times), 2000); const jitter = Math.floor(Math.random() * 200); return delay + jitter; }, slotsRefreshTimeout: 2000, redisOptions: { connectTimeout: 5000, maxRetriesPerRequest: 3 } }); const RATE_LIMIT_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], 'last_seen', ARGV[2]) return current <= tonumber(ARGV[3]) `; export async function checkRateLimit(tenantId: string, userId: string, limit: number): Promise<boolean> { // Invariant: Enforce hash tags {...} to guarantee keys hash to the identical 16384 slot const slotHash = `{tenant:${tenantId}}`; const countKey = `${slotHash}:rate:${userId}:count`; const auditKey = `${slotHash}:audit:${userId}:meta`; const result = await valkeyCluster.eval( RATE_LIMIT_SCRIPT, 2, countKey, auditKey, 60, Date.now(), limit ); return result === 1; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Cluster Routing, Multi-Threaded I/O, and Atomic Script Invariants

Valkey 8.0 Cluster Routing, Multi-Threaded I/O, and Atomic Script Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces strict cluster slot routing invariants, failover resilience, and deterministic cross-slot atomic script execution in Valkey 8.0. Prevents runtime CROSSSLOT errors, unbounded connection churn during master failovers, and latency regressions arising from uncoordinated multi-threaded I/O client configurations. 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 failover loops causing CROSSSLOT panics and cluster storm disconnects. 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 failover loops causing CROSSSLOT panics and cluster storm disconnects.	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 uniform cluster hash tags (e.g., `{tenant

Engineers MUST ALWAYS enforce uniform cluster hash tags (e.g., `{tenant:123}:entity`) on all multi-key operations and Lua/Function scripts to prevent runtime CROSSSLOT exceptions.

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.