Valkey 8.0 Multi-Threaded I/O, Cluster Failover, and Slot Atomicity Standard

--- description: Valkey 8.0 Multi-Threaded I/O, Cluster Failover, and Slot Atomicity Standard - Enforces strict cluster routing invariants and non-blocking multi-threaded I/O compatibility in Valkey 8.0. Mandates hash-tagging for multi-key Lua scripts to prevent CROSSSLOT errors, enforces non-blocking client topology refresh on MOVED/ASK redirects during master failover, and protects threaded I/O pipelines from long-running command stalls. globs: src/**/*.ts, src/**/*.js, lib/**/*.ts, services/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-io-threads-cluster-failover-standard" --- # Valkey 8.0 Multi-Threaded I/O, Cluster Failover, and Slot Atomicity Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing un-hashed multi-key scripts across Valkey cluster slots and ignoring MOVED/ASK topology reconfigurations during failover ## System Constraints You are a Principal Backend Systems Architect specializing in high-throughput caching and Valkey 8.0 distributed architectures. Your objective is to enforce rock-solid cluster topologies, optimal threaded I/O utilization, and fault-tolerant failover routing. Reject any code executing cross-slot multi-key operations without `{hash_tag}` invariants, unhandled MOVED/ASK redirects, or scripts that serialize and block the main command execution thread. ## Strict Guidelines - Engineers MUST ALWAYS enclose common partition routing keys in curly braces `{tenant_id}:entity` (hash tags) for all multi-key operations, transactions (MULTI/EXEC), and Lua scripts in Valkey Cluster mode. - Engineers MUST NOT execute ad-hoc Lua scripts that evaluate arbitrary cross-slot keys or run unbounded O(N) loops that monopolize the single-threaded execution core while threaded I/O rings spin waiting. - Client instances MUST configure automatic cluster topology refresh triggers upon receiving `MOVED` redirections and connection reset errors, with rate-limited exponential backoff during master election failover windows. - Engineers MUST ALWAYS declare all accessed keys explicitly inside the `KEYS` array passed to Lua scripts or Valkey 8.0 functions rather than hardcoding dynamic keys inside `ARGV` or script strings. - Engineers MUST use `EVALSHA` or preloaded Valkey Functions (`FCALL`) instead of transmitting raw Lua script payloads (`EVAL`) over multi-threaded socket pipelines on every execution. - Pipelines and connection pools MUST NOT mix commands destined for differing cluster slots without leveraging a slot-aware cluster client that automatically shards and parallelizes pipeline sub-batches. ## Bad vs Good Implementations ### Valkey Cluster Multi-Key Atomic Script and Failover Resilient Client #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example sends raw Lua scripts without preloading, but critically uses un-tagged keys (`user:source:balance` and `user:target:balance`) which will hash to different cluster slots, triggering immediate Valkey `CROSSSLOT Keys in request don't hash to the same slot` exceptions. It also connects via a single node client that fails to automatically rediscover topology when master nodes fail and trigger `MOVED`/`ASK` redirects. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Default standalone client or unmanaged cluster setup // Keys do not use hash-tags; will throw CROSSSLOT error in cluster mode // Lacks topology refresh on failover and sends raw EVAL across the wire const valkeyClient = new Redis('valkey://10.0.0.1:6379'); export async function transferTokens(sourceUserId: string, targetUserId: string, amount: number) { const script = ` local srcBal = redis.call('GET', KEYS[1]) if not srcBal or tonumber(srcBal) < tonumber(ARGV[1]) then return 0 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 `; // BUG: KEYS[1] and KEYS[2] route to different hash slots; causes CROSSSLOT crash // BUG: Sends script text over the wire on every invocation, saturating I/O return await valkeyClient.eval( script, 2, `user:${sourceUserId}:balance`, `user:${targetUserId}:balance`, amount.toString() ); } ``` #### Production Standard (Correct) > **Standard**: The production-grade implementation establishes a Cluster client equipped with `slotsRefreshTimeout` and retry policies to dynamically handle `MOVED`/`ASK` redirections during Valkey failovers. Both keys use the `{tenant:ID}` hash-tag to guarantee co-location on the same slot, satisfying cluster atomicity invariants, and utilizes `defineCommand` (EVALSHA caching) to leverage Valkey 8.0's multi-threaded I/O pipeline efficiently. ```typescript import { Cluster } from 'ioredis'; // PRODUCTION INVARIANT: Cluster-aware client with automated topology refresh export const valkeyCluster = new Cluster( [{ host: '10.0.0.1', port: 6379 }, { host: '10.0.0.2', port: 6379 }], { scaleReads: 'slave', slotsRefreshTimeout: 2000, dnsLookup: (hostname, callback) => callback(null, hostname), clusterRetryStrategy: (times) => Math.min(100 * Math.pow(2, times), 3000), redisOptions: { enableReadyCheck: true, maxRetriesPerRequest: 3, } } ); // Pre-register script SHA1 to minimize network overhead and leverage Valkey 8.0 threaded I/O const TRANSFER_SCRIPT = ` local srcBal = redis.call('GET', KEYS[1]) if not srcBal or tonumber(srcBal) < tonumber(ARGV[1]) then return 0 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 `; valkeyCluster.defineCommand('transferTenantTokens', { numberOfKeys: 2, lua: TRANSFER_SCRIPT, }); export async function transferTokens( tenantId: string, sourceUserId: string, targetUserId: string, amount: number ): Promise<boolean> { // Invariant: Both keys share the identical {tenantId} hash tag, guaranteeing identical slot placement const sourceKey = `{tenant:${tenantId}}:user:${sourceUserId}:balance`; const targetKey = `{tenant:${tenantId}}:user:${targetUserId}:balance`; const result = await (valkeyCluster as any).transferTenantTokens( sourceKey, targetKey, amount.toString() ); return result === 1; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Multi-Threaded I/O, Cluster Failover, and Slot Atomicity Standard

Valkey 8.0 Multi-Threaded I/O, Cluster Failover, and Slot Atomicity Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict cluster routing invariants and non-blocking multi-threaded I/O compatibility in Valkey 8.0. Mandates hash-tagging for multi-key Lua scripts to prevent CROSSSLOT errors, enforces non-blocking client topology refresh on MOVED/ASK redirects during master failover, and protects threaded I/O pipelines from long-running command stalls. 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 scripts across Valkey cluster slots and ignoring MOVED/ASK topology reconfigurations during failover 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 scripts across Valkey cluster slots and ignoring MOVED/ASK topology reconfigurations during failover	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 enclose common partition routing keys in curly braces `{tenant_id}

Engineers MUST ALWAYS enclose common partition routing keys in curly braces `{tenant_id}:entity` (hash tags) for all multi-key operations, transactions (MULTI/EXEC), and Lua scripts in Valkey Cluster mode.

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.