Redis Distributed Lock & Cache Invalidation Standard

--- description: Redis Distributed Lock & Cache Invalidation Standard - Production Redis conventions: safe distributed locking with Redlock or Lua release scripts, TTL on all keys to prevent memory leaks, and pipeline/transaction batching. globs: **/*cache*, **/*redis* alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/redis-distributed-patterns" --- # Redis Distributed Lock & Cache Invalidation Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: AI sets keys without TTL, uses non-atomic GET then SET for locks, or causes cache stampedes. ## System Constraints You are a distributed caching architect. Every key written to Redis must have an explicit TTL. Never implement locks with naive GET/SET; use SET NX PX with a unique identifier and release via Lua script to prevent unlocking another worker's expired lock. ## Strict Guidelines - Always attach an expiration (EX/PX) to SET commands to prevent permanent key leaks. - Distributed locks must use `SET key uuid NX PX 5000` and unlock with a Lua script comparing the uuid. - Batch multiple read/write operations using Redis Pipeline or MGET/MSET to eliminate network roundtrips. ## Bad vs Good Implementations ### Safe Distributed Lock Release with Lua Script #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If execution took longer than TTL, deleting the key deletes another process's newly acquired lock. ```typescript // Anti-pattern: Naive unlock causing accidental lock theft async function releaseLock(key: string) { await redis.del(key); // DANGEROUS! If our lock expired, we just deleted another worker's lock! } ``` #### Production Standard (Correct) > **Standard**: Atomic Lua script ensures we only delete the lock if the token matches our worker's ownership. ```typescript // Production Standard: Atomic release verifying lock owner token const UNLOCK_LUA = ` if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end `; export async function releaseLock(key: string, lockToken: string) { await redis.eval(UNLOCK_LUA, 1, key, lockToken); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Redis Distributed Lock & Cache Invalidation Standard

Redis Distributed Lock & Cache Invalidation Standard defines an industrial-grade behavioral standard for backend engineering. Production Redis conventions: safe distributed locking with Redlock or Lua release scripts, TTL on all keys to prevent memory leaks, and pipeline/transaction batching. 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: AI sets keys without TTL, uses non-atomic GET then SET for locks, or causes cache 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	AI sets keys without TTL, uses non-atomic GET then SET for locks, or causes cache 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:

Always attach an expiration (EX/PX) to SET commands to prevent permanent key leaks.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Distributed locks must use `SET key uuid NX PX 5000` and unlock with a Lua script comparing the uuid.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Batch multiple read/write operations using Redis Pipeline or MGET/MSET to eliminate network roundtrips.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Redis Distributed Lock & Cache Invalidation Standard critical for AI coding assistants?

Production Redis conventions: safe distributed locking with Redlock or Lua release scripts, TTL on all keys to prevent memory leaks, and pipeline/transaction batching. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (AI sets keys without TTL, uses non-atomic GET then SET for locks, or causes cache stampedes.) 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.