Valkey 8.0 Cluster Slot Pinning, Lua Hash-Tagging, and Failover Resiliency

--- description: Valkey 8.0 Cluster Slot Pinning, Lua Hash-Tagging, and Failover Resiliency - Mandates strict hash slot pinning via curly-brace hash tags for all multi-key operations and atomic Lua scripts in Valkey 8.0 Cluster deployments. Enforces production-grade cluster failover routing, requiring explicit topology refresh limits, exponential backoff on MOVED redirects, and ASKING preambles for slot migration to prevent failover cascading outages. globs: src/cache/**/*.{ts,js}, src/infrastructure/valkey/**/*.{ts,js}, src/services/**/*.{ts,js}, src/lib/redis/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-threaded-io-resilience" --- # Valkey 8.0 Cluster Slot Pinning, Lua Hash-Tagging, and Failover Resiliency > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing unpinned multi-key Lua scripts causing CROSSSLOT exceptions and unhandled cluster redirection cascades during replica promotion. ## System Constraints You are a Principal Backend Engineer enforcing Valkey 8.0 clustering invariants, threaded I/O optimizations, and failover survivability. Valkey 8.0 multi-threaded socket I/O boosts throughput, but the cluster data plane enforces single-slot atomicity per transaction and script. You must prevent CROSSSLOT errors by mandating hash tags, ensure cluster client topology caches refresh correctly on MOVED/ASK errors, and prohibit unbuffered pipeline saturation. ## Strict Guidelines - Engineers MUST ALWAYS enforce curly brace hash tags (e.g., `{tenant:123}:session`) on all keys touched within the same Lua script or MULTI/EXEC pipeline to guarantee placement in identical Valkey 8.0 cluster slots (0–16383). - Engineers MUST NOT execute multi-key commands across disparate or non-tagged keys (e.g., `MGET key1 key2`), as Valkey Cluster nodes strictly reject cross-slot commands with a `CROSSSLOT Keys in request don't hash to the same slot` error. - Code MUST configure Valkey/Redis cluster client instances with automated topology refresh triggers (`slotsRefreshInterval`, slot refresh on `MOVED` redirects, and circuit-breaking during master failover). - Services MUST differentiate between `MOVED` (permanent redirect triggering routing table invalidation) and `ASK` (transient slot migration redirect requiring an `ASKING` preamble before the target command). - Components NEVER execute unbounded blocking commands (`BLPOP`, `BRPOP`, `BZPOPMIN`) over multi-threaded I/O pools without dedicated isolated connections, as connection stalls can monopolize socket read/write buffers. ## Bad vs Good Implementations ### Cross-Slot Lua Execution and Fragile Client Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The script uses separate key prefixes without hash tags, causing the keys to hash into distinct cluster slots. Valkey Cluster strictly rejects this with a CROSSSLOT error. Additionally, the cluster client lacks failover topology refresh settings, causing connection failures and redirect loops if the master node goes down. ```typescript import Redis, { Cluster } from 'ioredis'; // ANTI-PATTERN: Default cluster options without topology refresh policies, // and executing an atomic Lua script across keys without slot hash tags. export const valkeyCluster = new Cluster([ { host: '10.0.0.1', port: 6379 } ]); export async function deductCreditsBad( userId: string, cost: number ): Promise<boolean> { // In Valkey Cluster, 'user:credits:100' and 'user:audit:100' hash to different slots! // This throws: ReplyError: CROSSSLOT Keys in request don't hash to the same slot const luaScript = ` local credits = tonumber(redis.call('get', KEYS[1]) or '0') if credits >= tonumber(ARGV[1]) then redis.call('decrby', KEYS[1], ARGV[1]) redis.call('rpush', KEYS[2], 'debited_' .. ARGV[1]) return 1 end return 0 `; const result = await valkeyCluster.eval( luaScript, 2, `user:credits:${userId}`, `user:audit:${userId}`, cost.toString() ); return result === 1; } ``` #### Production Standard (Correct) > **Standard**: Hash tags `{user:${userId}}` guarantee that both keys hash to the identical slot (0–16383), maintaining atomic Lua execution in a distributed cluster. The cluster client is fortified with failover backoffs and slot refresh policies, seamlessly handling master-to-replica failover. ```typescript import { Cluster, ClusterOptions } from 'ioredis'; // PRODUCTION FIX: Configured for Valkey 8.0 cluster failovers and slot pinning. const clusterOptions: ClusterOptions = { slotsRefreshInterval: 5000, // Refresh cluster topology every 5s slotsRefreshTimeout: 2000, enableReadyCheck: true, maxRedirections: 16, retryDelayOnFailover: 100, retryDelayOnClusterDown: 250, scaleReads: 'slave', // Leverage Valkey read replicas safely redisOptions: { connectTimeout: 5000, keepAlive: 30000, enableAutoPipelining: true // Utilizes Valkey 8.0 threaded I/O throughput } }; export const valkeyCluster = new Cluster( [ { host: '10.0.0.1', port: 6379 }, { host: '10.0.0.2', port: 6379 } ], clusterOptions ); export async function deductCreditsGood( userId: string, cost: number ): Promise<boolean> { // INVARIANT: Use hash tags '{...}' to force both keys into the identical slot. const balanceKey = `{user:${userId}}:credits`; const auditKey = `{user:${userId}}:audit`; const luaScript = ` local credits = tonumber(redis.call('get', KEYS[1]) or '0') if credits >= tonumber(ARGV[1]) then redis.call('decrby', KEYS[1], ARGV[1]) redis.call('rpush', KEYS[2], 'debited_' .. ARGV[1]) return 1 end return 0 `; const result = await valkeyCluster.eval( luaScript, 2, balanceKey, auditKey, cost.toString() ); return result === 1; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Cluster Slot Pinning, Lua Hash-Tagging, and Failover Resiliency

Valkey 8.0 Cluster Slot Pinning, Lua Hash-Tagging, and Failover Resiliency defines an industrial-grade behavioral standard for backend engineering. Mandates strict hash slot pinning via curly-brace hash tags for all multi-key operations and atomic Lua scripts in Valkey 8.0 Cluster deployments. Enforces production-grade cluster failover routing, requiring explicit topology refresh limits, exponential backoff on MOVED redirects, and ASKING preambles for slot migration to prevent failover cascading outages. 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 unpinned multi-key Lua scripts causing CROSSSLOT exceptions and unhandled cluster redirection cascades during replica promotion. 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 unpinned multi-key Lua scripts causing CROSSSLOT exceptions and unhandled cluster redirection cascades during replica promotion.	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 enforce curly brace hash tags (e.g., `{tenant

Engineers MUST ALWAYS enforce curly brace hash tags (e.g., `{tenant:123}:session`) on all keys touched within the same Lua script or MULTI/EXEC pipeline to guarantee placement in identical Valkey 8.0 cluster slots (0–16383).

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.