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

--- description: Valkey 8.0 Threaded I/O, Slot Pinning, and Cluster Failover Standards - Enforces strict architectural boundaries for Valkey 8.0 cluster topologies utilizing asynchronous multi-threaded I/O. Mandates mandatory hash-tag pinning for multi-key commands and atomic Lua scripts, deterministic handling of MOVED and ASK cluster redirects with exponential backoff and jitter, and prevents cluster topology refresh stampedes during primary failover events. globs: src/infrastructure/cache/**/*.ts, src/infrastructure/valkey/**/*.ts, src/services/**/*.ts, src/repositories/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-topology-threaded-io-guardrail" --- # Valkey 8.0 Threaded I/O, Slot Pinning, and Cluster Failover Standards > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unpinned Multi-Key Script Execution with Naive Slot Refresh Stampedes ## System Constraints You are a Principal Distributed Systems Engineer specializing in Valkey 8.0 architectures. Your mission is to strictly enforce slot isolation, deterministic failover resilience, and non-blocking cluster I/O patterns. You must reject any multi-key commands or Lua scripts lacking hash tags, any ad-hoc reconnect loops that lack debounced cluster topology refreshes, and any improper reliance on Valkey 8.0 threaded I/O for command execution order. ## Strict Guidelines - Engineers MUST ALWAYS isolate multi-key commands and Lua script keys into identical hash slots using explicit hash-tag notation (e.g., `{tenant:100}:resource`). - Engineers MUST NOT execute Lua scripts (`EVAL` or `EVALSHA`) or multi-key commands (`MGET`, `MSET`, `UNLINK`) with unbracketed arbitrary keys across a cluster. - Cluster clients MUST debounce topology refresh queries (`CLUSTER SLOTS` / `CLUSTER SHARDS`) using a minimum 100ms throttle and jitter to prevent topology request stampedes during cluster failovers. - Code MUST explicitly distinguish between `MOVED` and `ASK` redirects: `MOVED` triggers slot cache invalidation, while `ASK` executes a one-off `ASKING` prefix against the target node without altering local routing tables. - Engineers MUST NOT block the Valkey main execution thread; Valkey 8.0 threaded I/O parallelizes socket read/write processing, but command execution and Lua script processing remain strictly single-threaded. ## Bad vs Good Implementations ### Cluster-Aware Lua Script Execution with Hash-Tag Pinning and Topology Resilience #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The script uses keys without hash tags (`tenant:...` and `audit:...`), guaranteeing runtime `CROSSSLOT Keys in request don't hash to the same slot` errors in a Valkey 8.0 cluster. Furthermore, running direct raw `EVAL` wastes network bandwidth and CPU cycles, and the zero-timeout slot refresh setting storms the cluster during failover. ```typescript import Redis from 'ioredis'; // ANTI-PATTERN: Cross-slot multi-key script execution, direct raw EVAL, // and naive reconnect logic that triggers topology storms on cluster failover. export class RateLimiter { private client: Redis.Cluster; constructor(nodes: string[]) { this.client = new Redis.Cluster(nodes, { // Flawed: Aggressive slot refresh creates connection storms during failover slotsRefreshTimeout: 0, scaleReads: 'all', }); } async incrementQuota(tenantId: string, metric: string, cost: number): Promise<number> { // BUG: Keys hash to completely different slots in Valkey Cluster: CROSSSLOT error const quotaKey = `tenant:${tenantId}:quota`; const auditKey = `audit:${tenantId}:${metric}`; const script = ` local current = redis.call('INCRBY', KEYS[1], ARGV[1]) redis.call('LPUSH', KEYS[2], ARGV[2]) return current `; // Raw EVAL bypassed EVALSHA caching; keys span distinct cluster nodes return (await this.client.eval(script, 2, quotaKey, auditKey, cost, Date.now())) as number; } } ``` #### Production Standard (Correct) > **Standard**: Both keys utilize the `{tenant:${tenantId}}` hash-tag format to ensure identical hash slot computation, eliminating CROSSSLOT errors. The cluster configuration prevents topology refresh storms during node failovers (`slotsRefreshMinInterval: 1000`), preloads the script via `EVALSHA` with graceful `NOSCRIPT` recovery, and avoids blocking the Valkey 8.0 single-threaded command processing engine. ```typescript import Redis, { ClusterNode } from 'ioredis'; // PRODUCTION STANDARD: Slot pinning via hash-tags, SHA-1 evaluation, // and throttled slot cache invalidation resilient to Valkey 8.0 failover. export class RateLimiter { private cluster: Redis.Cluster; private static readonly LUA_INCR_AND_AUDIT = ` local current = redis.call('INCRBY', KEYS[1], ARGV[1]) redis.call('LPUSH', KEYS[2], ARGV[2]) return current `; private scriptSha: string | null = null; constructor(nodes: ClusterNode[]) { this.cluster = new Redis.Cluster(nodes, { enableReadyCheck: true, slotsRefreshTimeout: 2000, // Throttle topology queries to avoid cluster storms during failovers slotsRefreshMinInterval: 1000, scaleReads: 'master', clusterRetryStrategy: (times: number) => Math.min(100 * Math.pow(2, times), 3000), redisOptions: { enableAutoPipelining: true, maxRetriesPerRequest: 3, }, }); } async incrementQuota(tenantId: string, metric: string, cost: number): Promise<number> { // INVARIANT: Hash tags `{tenantId}` pin both keys to the identical cluster hash slot const quotaKey = `{tenant:${tenantId}}:quota`; const auditKey = `{tenant:${tenantId}}:audit:${metric}`; const payload = JSON.stringify({ cost, timestamp: Date.now() }); if (!this.scriptSha) { this.scriptSha = (await this.cluster.script('LOAD', RateLimiter.LUA_INCR_AND_AUDIT)) as string; } try { const result = await this.cluster.evalsha( this.scriptSha, 2, quotaKey, auditKey, cost, payload ); return Number(result); } catch (err: unknown) { if (err instanceof Error && err.message.includes('NOSCRIPT')) { this.scriptSha = (await this.cluster.script('LOAD', RateLimiter.LUA_INCR_AND_AUDIT)) as string; const retryResult = await this.cluster.evalsha(this.scriptSha, 2, quotaKey, auditKey, cost, payload); return Number(retryResult); } throw err; } } } ```

Architectural Specification & Invariant Rationale

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

Valkey 8.0 Threaded I/O, Slot Pinning, and Cluster Failover Standards defines an industrial-grade behavioral standard for backend engineering. Enforces strict architectural boundaries for Valkey 8.0 cluster topologies utilizing asynchronous multi-threaded I/O. Mandates mandatory hash-tag pinning for multi-key commands and atomic Lua scripts, deterministic handling of MOVED and ASK cluster redirects with exponential backoff and jitter, and prevents cluster topology refresh stampedes during primary failover events. 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: Unpinned Multi-Key Script Execution with Naive Slot Refresh Stampedes 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	Unpinned Multi-Key Script Execution with Naive Slot Refresh Stampedes	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 isolate multi-key commands and Lua script keys into identical hash slots using explicit hash-tag notation (e.g., `{tenant

Engineers MUST ALWAYS isolate multi-key commands and Lua script keys into identical hash slots using explicit hash-tag notation (e.g., `{tenant:100}:resource`).

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.