Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Resilience

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Executing Cross-Slot Multi-Key Lua Scripts and Naive Client Topologies During Failover) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Resilience

--- description: Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Resilience - Valkey 8.0 scales network ingestion via threaded I/O while preserving single-threaded execution for commands and Lua scripts. Multi-key operations and script invocations across clustered nodes must strictly pin keys to identical slots via explicit hash tags, avoid blocking the main event loop, and configure client-side topology updates to gracefully handle MOVED/ASK redirects and automated master failovers without connection dropping or transaction corruption. globs: src/**/*.ts, src/**/*.js, src/cache/**/*.ts, src/infrastructure/valkey/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-threaded-io-cluster-failover-production-standard" --- # Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Resilience > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing Cross-Slot Multi-Key Lua Scripts and Naive Client Topologies During Failover ## System Constraints You are a Principal Backend Architect enforcing strict Valkey 8.0 cluster standards. Mandate explicit hash tagging on all multi-key operations, enforce asynchronous slot topology discovery during failovers, prevent main-thread event loop blocking caused by long-running Lua scripts, and guarantee strict handling of MOVED, ASK, and CLUSTERDOWN responses. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate multi-key routing partitions using curly brace hash tags (e.g., `{tenant:123}:user` and `{tenant:123}:orders`) to guarantee all keys map to the same 16384 cluster hash slot. - Engineers MUST NOT execute Lua scripts or Valkey functions that touch non-hash-tagged keys across disparate slots, which causes immediate CROSSSLOT errors and corrupts atomic multi-operations. - Clients MUST configure automatic cluster topology refresh intervals and proactive MOVED/ASK slot redirection handling to tolerate node failovers without dropping in-flight traffic. - Engineers MUST leverage read-only script evaluation (EVAL_RO or FCALL_RO) for analytics and read aggregations to permit offloading execution to replica nodes when read scaling is enabled. - Code MUST NEVER execute blocking commands (e.g., KEYS, unbounded HGETALL, blocking Lua loops) that monopolize Valkey's single execution thread and bottleneck the multi-threaded I/O pipeline. ## Bad vs Good Implementations ### Cluster Slot Pinning & Failover Resilient Client Architecture #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The client lacks automated slot refresh policies to recover from cluster failovers (triggering CLUSTERDOWN errors). Furthermore, the Lua script accesses two distinct keys (`user:${senderId}:balance` and `user:${receiverId}:balance`) without hash tags, causing a CROSSSLOT exception because clustered Valkey partitions keys randomly across 16384 slots unless explicitly pinned. ```typescript import { Cluster } from 'ioredis'; // ANTI-PATTERN: Default static nodes without topology tracking, unpartitioned multi-key keys const cluster = new Cluster([ { host: '10.0.0.1', port: 6379 }, { host: '10.0.0.2', port: 6379 } ]); export async function transferBalance(senderId: string, receiverId: string, amount: number) { // FAILS in Cluster mode: senderId and receiverId map to different slots (CROSSSLOT error) const script = ` local sender = redis.call('GET', KEYS[1]) if not sender or tonumber(sender) < tonumber(ARGV[1]) then return 0 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 `; return cluster.eval(script, 2, `user:${senderId}:balance`, `user:${receiverId}:balance`, amount); } ``` #### Production Standard (Correct) > **Standard**: Hash tags `{tenant:${tenantId}}` ensure both keys compute to the exact same hash slot (0-16383), ensuring legal atomic script execution in a Valkey cluster. The cluster client configuration handles MOVED/ASK redirects and cluster failovers seamlessly via `slotsRefreshInterval` and exponential retry delays. ```typescript import { Cluster, ClusterOptions } from 'ioredis'; // PRODUCTION INVARIANT: Resilient topology updates with exponential backoff and slot caching const clusterOptions: ClusterOptions = { slotsRefreshInterval: 5000, // Proactively update topology before failover completion slotsRefreshTimeout: 2000, maxRedirections: 16, retryDelayOnFailover: 100, retryDelayOnClusterDown: 250, scaleReads: 'slave', clusterRetryStrategy: (times: number) => Math.min(100 * Math.pow(2, times), 2000), enableReadyCheck: true }; export const valkeyCluster = new Cluster([ { host: process.env.VALKEY_SEED_HOST || '10.0.0.1', port: 6379 } ], clusterOptions); export async function transferBalanceWithinTenant( tenantId: string, senderId: string, receiverId: string, amount: number ): Promise<number> { // Pin both keys to the identical slot using hash-tag syntax: {tenantId} const senderKey = `{tenant:${tenantId}}:user:${senderId}:balance`; const receiverKey = `{tenant:${tenantId}}:user:${receiverId}:balance`; const script = ` local bal = redis.call('GET', KEYS[1]) if not bal or tonumber(bal) < tonumber(ARGV[1]) then return 0 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 1 `; // Atomic execution within single slot; threaded I/O handles network serialization const result = await valkeyCluster.eval(script, 2, senderKey, receiverKey, amount); return Number(result); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Resilience

Valkey 8.0 Threaded I/O, Cluster Slot Pinning, and Failover Resilience defines an industrial-grade behavioral standard for backend engineering. Valkey 8.0 scales network ingestion via threaded I/O while preserving single-threaded execution for commands and Lua scripts. Multi-key operations and script invocations across clustered nodes must strictly pin keys to identical slots via explicit hash tags, avoid blocking the main event loop, and configure client-side topology updates to gracefully handle MOVED/ASK redirects and automated master failovers without connection dropping or transaction corruption. 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 Cross-Slot Multi-Key Lua Scripts and Naive Client Topologies 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 Cross-Slot Multi-Key Lua Scripts and Naive Client Topologies 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 routing partitions using curly brace hash tags (e.g., `{tenant

Engineers MUST ALWAYS encapsulate multi-key routing partitions using curly brace hash tags (e.g., `{tenant:123}:user` and `{tenant:123}:orders`) to guarantee all keys map to the same 16384 cluster hash 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.