Valkey 8.0 Cluster Topology, Cross-Slot Atomicity, and Threaded I/O Invariants

--- description: Valkey 8.0 Cluster Topology, Cross-Slot Atomicity, and Threaded I/O Invariants - Enforces strict hash-tag slot alignment for multi-key commands and Lua functions in Valkey 8.0 clusters, prevents event loop starvation under Threaded I/O configurations, and guarantees robust dynamic slot cache invalidation during cluster failovers. globs: src/**/*.ts, src/**/*.js, src/infrastructure/**/*.ts, lib/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-threaded-io-cluster-failover-guardrail" --- # Valkey 8.0 Cluster Topology, Cross-Slot Atomicity, and Threaded I/O Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unhashed multi-key Lua executions causing CROSSSLOT errors and unhandled MOVED/ASK redirect thrashing during failover ## System Constraints You are a Principal Engineer enforcing Valkey 8.0 Threaded I/O & Cluster Failover standards. Mandate invariant multi-key hash tagging, automatic cluster topology refreshes on MOVED/ASK redirects, and zero-blocking command semantics on the primary execution thread. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate multi-key commands, pipeline batches, and Lua script keys with matching hash tags (e.g., `{tenant:123}:orders`, `{tenant:123}:metrics`) to guarantee identical cluster slot routing. - Engineers MUST NOT assume Valkey 8.0 Threaded I/O executes commands across multiple threads; I/O threads only handle network read/write parsing, leaving command execution single-threaded. - Code SHOULD configure Valkey cluster clients with automated slot refresh hooks triggered by MOVED and ASK redirection limits, preventing infinite redirection cascades. - Services MUST implement exponential backoff with jitter on CLUSTERDOWN or read-only replica failover transitions to avoid thundering herd storms on newly promoted primaries. - Components NEVER execute long-running (O(N)) blocking Lua scripts or KEYS commands that stall the main execution loop and exhaust Valkey threaded I/O ring buffers. ## Bad vs Good Implementations ### Valkey 8.0 Cluster Client Setup and Hash-Tagged Lua Script Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The client lacks dynamic cluster topology refresh configurations on failovers (MOVED/ASK errors), and the Lua script references two arbitrary keys that hash to different master slots, causing execution failure in a clustered Valkey 8.0 deployment. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Standalone client used against cluster or cluster without topology refresh, // and multi-key Lua script with non-aligned hash slots causing CROSSSLOT runtime errors. export const valkeyCluster = new Redis.Cluster([ { host: 'valkey-node-1.internal', port: 6379 } ]); export async function updateSessionCounters(userId: string, tenantId: string) { const script = ` local u = redis.call('INCR', KEYS[1]) local t = redis.call('INCR', KEYS[2]) return {u, t} `; // BUG: Keys hash to distinct cluster slots: throws CROSSSLOT error return await valkeyCluster.eval(script, 2, `user:${userId}:hits`, `tenant:${tenantId}:hits`); } ``` #### Production Standard (Correct) > **Standard**: Keys utilize `{tenant:${tenantId}}` hash tags to ensure they resolve to the exact same hash slot (0-16383), and the cluster client is configured with slot refresh timeouts and exponential retry strategies to seamlessly handle primary-replica failovers. ```typescript import { Cluster, ClusterNode } from 'ioredis'; const clusterNodes: ClusterNode[] = [ { host: 'valkey-node-1.internal', port: 6379 }, { host: 'valkey-node-2.internal', port: 6379 } ]; // PRODUCTION FIX: Configured for dynamic topology refresh during failovers export const valkeyCluster = new Cluster(clusterNodes, { dnsLookup: (address, callback) => callback(null, address), slotsRefreshTimeout: 2000, enableReadyCheck: true, scaleReads: 'slave', clusterRetryStrategy: (times) => Math.min(100 * Math.pow(2, times), 2000), redisOptions: { maxRetriesPerRequest: 3, connectTimeout: 5000 } }); export async function updateSessionCounters(userId: string, tenantId: string) { // PRODUCTION FIX: Hash tags ensure both keys route to the exact same cluster slot const hashTag = `{tenant:${tenantId}}`; const userKey = `${hashTag}:user:${userId}:hits`; const tenantKey = `${hashTag}:aggregate:hits`; const script = ` local u = redis.call('INCR', KEYS[1]) local t = redis.call('INCR', KEYS[2]) return {u, t} `; return await valkeyCluster.eval(script, 2, userKey, tenantKey); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Cluster Topology, Cross-Slot Atomicity, and Threaded I/O Invariants

Valkey 8.0 Cluster Topology, Cross-Slot Atomicity, and Threaded I/O Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces strict hash-tag slot alignment for multi-key commands and Lua functions in Valkey 8.0 clusters, prevents event loop starvation under Threaded I/O configurations, and guarantees robust dynamic slot cache invalidation during cluster failovers. 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: Unhashed multi-key Lua executions causing CROSSSLOT errors and unhandled MOVED/ASK redirect thrashing 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	Unhashed multi-key Lua executions causing CROSSSLOT errors and unhandled MOVED/ASK redirect thrashing 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 encapsulate multi-key commands, pipeline batches, and Lua script keys with matching hash tags (e.g., `{tenant

Engineers MUST ALWAYS encapsulate multi-key commands, pipeline batches, and Lua script keys with matching hash tags (e.g., `{tenant:123}:orders`, `{tenant:123}:metrics`) to guarantee identical cluster slot routing.

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.