Valkey 8.0 Threaded I/O Cluster Failover and Lua Hash-Tagging Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Executing un-hashed multi-key Lua scripts and lacking automated cluster slot refresh on MOVED/ASK redirects) 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 Failover and Lua Hash-Tagging Standard

--- description: Valkey 8.0 Threaded I/O Cluster Failover and Lua Hash-Tagging Standard - Enforces strict hash-tag slot pinning for multi-key Lua scripts and resilient cluster topology refresh handling during Valkey 8.0 failovers. Prevents CROSSSLOT evaluation runtime errors and thundering herd connection deadlocks caused by unhandled MOVED/ASK redirects in high-throughput multi-threaded I/O environments. 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-cluster-topology-lua-guardrails" --- # Valkey 8.0 Threaded I/O Cluster Failover and Lua Hash-Tagging Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing un-hashed multi-key Lua scripts and lacking automated cluster slot refresh on MOVED/ASK redirects ## System Constraints You are a Principal Backend Architect enforcing Valkey 8.0 cluster resilience and threaded I/O safety. Mandate strict hash-tag usage (`{...}`) for all multi-key operations and Lua evaluations to ensure slot co-locality. Enforce explicit handling of MOVED/ASK cluster redirects with dynamic slot cache refresh and exponential backoff. Reject bare single-node connections or static endpoint configurations in clustered topologies. ## Strict Guidelines - Engineers MUST ALWAYS enclose common grouping identifiers in hash tags (e.g., `{tenant:123}:orders`) when executing Lua scripts or multi-key operations across Valkey clusters to prevent CROSSSLOT failures. - Engineers MUST NOT execute Lua scripts that access dynamic, un-hashed keys passed only via ARGV or non-bracketed KEYS parameters. - Services MUST configure automated slot topology refresh strategies (periodic slot refresh and auto-refresh on MOVED cluster redirects) to gracefully survive primary node failovers under Valkey 8.0. - Code SHOULD configure client connection pool limits aligned with Valkey 8.0 `io-threads` capacity and avoid long-running, blocking Lua scripts that stall the single-threaded execution core. - Components NEVER execute raw single-node client commands directly against cluster seed nodes without enabling cluster-aware redirect handling. ## Bad vs Good Implementations ### Valkey Cluster Client Configuration and Lua Script Hash-Tagging #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Connecting to a cluster seed node via standard standalone Redis/Valkey client will fail upon failover because it lacks MOVED/ASK redirect handling and slot refresh mechanics. Furthermore, passing two distinct, un-hashed keys (`user:from:bal` and `user:to:bal`) will hash to different slots, throwing a CROSSSLOT error. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Direct single-node connection unaware of cluster failovers, // and multi-key Lua script with non-bracketed keys causing CROSSSLOT errors. export const valkeyClient = new Redis('valkey://cluster-seed.internal:6379'); export async function transferCredits(fromUser: string, toUser: string, amount: number) { const script = ` local fromBal = tonumber(redis.call('get', KEYS[1]) or 0) if fromBal < tonumber(ARGV[1]) then return -1 end redis.call('decrby', KEYS[1], ARGV[1]) redis.call('incrby', KEYS[2], ARGV[1]) return 1 `; // Runtime error: CROSSSLOT Keys in request don't hash to the same slot return await valkeyClient.eval(script, 2, `user:${fromUser}:bal`, `user:${toUser}:bal`, amount); } ``` #### Production Standard (Correct) > **Standard**: Uses a native Cluster client with dynamic slot table refreshes (`slotsRefreshInterval`, `slotsRefreshTimeout`) to seamlessly survive failovers when multi-threaded I/O redirects `MOVED`/`ASK`. Hash tags (`{org:${orgId}}`) guarantee both keys map to the identical cluster hash slot, ensuring atomic Lua script execution. ```typescript import { Cluster } from 'ioredis'; // PRODUCTION FIX: Configured Valkey Cluster with auto-refresh on failover export const valkeyCluster = new Cluster( [{ host: 'valkey-seed-01.internal', port: 6379 }, { host: 'valkey-seed-02.internal', port: 6379 }], { enableReadyCheck: true, slotsRefreshTimeout: 2000, slotsRefreshInterval: 30000, // Background slot table sync clusterRetryStrategy: (times) => Math.min(100 * Math.pow(2, times), 2000), redisOptions: { connectTimeout: 5000, lazyConnect: true, } } ); export async function transferOrgCredits(orgId: string, fromUser: string, toUser: string, amount: number) { // Invariant: Keys bound to the same slot using Valkey hash tag syntax: {orgId} const fromKey = `{org:${orgId}}:user:${fromUser}:bal`; const toKey = `{org:${orgId}}:user:${toUser}:bal`; const script = ` local fromBal = tonumber(redis.call('get', KEYS[1]) or 0) if fromBal < tonumber(ARGV[1]) then return -1 end redis.call('decrby', KEYS[1], ARGV[1]) redis.call('incrby', KEYS[2], ARGV[1]) return 1 `; return await valkeyCluster.eval(script, 2, fromKey, toKey, amount); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Threaded I/O Cluster Failover and Lua Hash-Tagging Standard

Valkey 8.0 Threaded I/O Cluster Failover and Lua Hash-Tagging Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict hash-tag slot pinning for multi-key Lua scripts and resilient cluster topology refresh handling during Valkey 8.0 failovers. Prevents CROSSSLOT evaluation runtime errors and thundering herd connection deadlocks caused by unhandled MOVED/ASK redirects in high-throughput multi-threaded I/O environments. 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 Lua scripts and lacking automated cluster slot refresh on MOVED/ASK redirects 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 Lua scripts and lacking automated cluster slot refresh on MOVED/ASK redirects	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 grouping identifiers in hash tags (e.g., `{tenant

Engineers MUST ALWAYS enclose common grouping identifiers in hash tags (e.g., `{tenant:123}:orders`) when executing Lua scripts or multi-key operations across Valkey clusters to prevent CROSSSLOT failures.

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.