Valkey 8.0 Threaded I/O Slot Hash-Tagging and Failover Invariants

--- description: Valkey 8.0 Threaded I/O Slot Hash-Tagging and Failover Invariants - Enforces strict hash-tag slot alignment for multi-key operations and atomic Lua scripts in Valkey 8.0 cluster mode. Prevents CROSSSLOT errors, main-thread starvation under threaded I/O, and connection drops during unhandled MOVED/ASK failover redirects. 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-threaded-io-cluster-failover-invariant" --- # Valkey 8.0 Threaded I/O Slot Hash-Tagging and Failover Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing un-hashed cross-slot Lua scripts and failing to handle cluster slot topology refreshes during failovers ## System Constraints You are a Principal Engineer enforcing Valkey 8.0 Threaded I/O & Cluster Failover standards. Valkey 8.0 optimizes network I/O across worker threads, but the command execution engine remains single-threaded. Multi-key operations, atomic Lua scripts, and client cluster drivers must guarantee single-slot co-locality via hash tags {...}, pass all accessed keys strictly in the KEYS array, and configure robust topology refreshes for MOVED/ASK redirects during master-replica failovers. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate shared routing keys within hash tags (e.g., `{tenant:123}:session`, `{tenant:123}:profile`) for any multi-key transaction, MGET, MSET, or Lua script to guarantee co-location in the exact same 16384 slot. - Engineers MUST pass all cluster keys accessed by a Lua script explicitly inside the `KEYS` argument array; components MUST NOT construct or interpolate key strings inside the Lua script or pass keys via `ARGV`. - Code SHOULD configure Valkey cluster clients with automated slot topology discovery, setting explicit `slotsRefreshTimeout`, `slotsRefreshInterval`, and max retry counts on `MOVED`, `ASK`, and `CLUSTERDOWN` events. - Services MUST NOT execute unbounded Lua scripts, blocking calls (e.g., `BLPOP` without timeouts), or `KEYS *` commands; multi-threaded I/O in Valkey 8.0 handles socket I/O concurrently but script execution blocks the entire slot master thread. - Components NEVER execute raw single-node client commands across a cluster deployment; a cluster-aware driver with slot redirection routing MUST be used. ## Bad vs Good Implementations ### Valkey Cluster Hash-Tagged Lua Execution and Failover Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Connecting with a single-node client causes uncaught MOVED/ASK exceptions during failovers. Generating key names inside the Lua script breaks Valkey's slot-checking proxy, and missing hash tags causes CROSSSLOT errors when keys map to different hash slots across the cluster. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Standalone client connected to single node in a cluster, // un-hashed multi-key Lua script with keys generated inside the script, // and no slot redirection handling. export class RateLimiterService { private client: Redis; constructor() { this.client = new Redis('redis://valkey-node-01:6379'); } async increment(userId: string, action: string): Promise<number> { // Fails with CROSSSLOT in Valkey Cluster because keys hash to different slots // Keys are passed in ARGV and dynamically formed inside Lua const script = ` local countKey = 'user:' .. ARGV[1] .. ':count' local logKey = 'user:' .. ARGV[1] .. ':action:' .. ARGV[2] local current = redis.call('INCR', countKey) redis.call('LPUSH', logKey, ARGV[3]) return current `; return (await this.client.eval(script, 0, userId, action, Date.now().toString())) as number; } } ``` #### Production Standard (Correct) > **Standard**: Uses a cluster-aware driver with topology auto-refresh and backoff during failovers. Multi-key keys use `{user:ID}` hash tags to guarantee identical slot mapping (0-16383), and all keys are declared in the KEYS parameter for pre-execution slot validation. ```typescript import { Cluster, ClusterNode } from 'ioredis'; // PRODUCTION INVARIANT: Cluster-aware client with topology discovery, // automatic failover retries, and strict hash-tag co-location passed via KEYS. export class RateLimiterService { private cluster: Cluster; constructor(nodes: ClusterNode[]) { this.cluster = new Cluster(nodes, { scaleReads: 'all', slotsRefreshTimeout: 2000, slotsRefreshInterval: 30000, retryDelayOnFailover: 100, retryDelayOnClusterDown: 200, maxRedirections: 16, redisOptions: { enableAutoPipelining: true, connectTimeout: 5000 } }); } async increment(userId: string, action: string): Promise<number> { // Both keys share the {user:ID} hash tag, guaranteeing identical slot placement const countKey = `{user:${userId}}:count`; const logKey = `{user:${userId}}:action:${action}`; const timestamp = Date.now().toString(); const script = ` local current = redis.call('INCR', KEYS[1]) redis.call('LPUSH', KEYS[2], ARGV[1]) return current `; // Valkey cluster verifies KEYS[1] and KEYS[2] route to the same slot before executing return (await this.cluster.eval(script, 2, countKey, logKey, timestamp)) as number; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O Slot Hash-Tagging and Failover Invariants

Valkey 8.0 Threaded I/O Slot Hash-Tagging and Failover Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces strict hash-tag slot alignment for multi-key operations and atomic Lua scripts in Valkey 8.0 cluster mode. Prevents CROSSSLOT errors, main-thread starvation under threaded I/O, and connection drops during unhandled MOVED/ASK failover redirects. 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 cross-slot Lua scripts and failing to handle cluster slot topology refreshes during 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-hashed cross-slot Lua scripts and failing to handle cluster slot topology refreshes during 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 encapsulate shared routing keys within hash tags (e.g., `{tenant

Engineers MUST ALWAYS encapsulate shared routing keys within hash tags (e.g., `{tenant:123}:session`, `{tenant:123}:profile`) for any multi-key transaction, MGET, MSET, or Lua script to guarantee co-location in the exact same 16384 slot.

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.