React 19 Server Actions Idempotency Key & Replay Quarantine Guardrail

--- description: React 19 Server Actions Idempotency Key & Replay Quarantine Guardrail - Enforces mandatory cryptographic client-generated idempotency tokens and atomic server-side mutation deduplication across React 19 Server Actions. Guarantees that network retries, optimistic re-triggers, and flaky transport reconciliations execute mutations exactly once while returning cached determinism for replayed requests. Quarantines concurrent re-entrancy and prevents phantom duplicate resource creation in distributed backends. globs: app/**/*.{ts,tsx}, src/**/*.{ts,tsx}, actions/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react19-server-actions-idempotency-key-quarantine" --- # React 19 Server Actions Idempotency Key & Replay Quarantine Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Executing naked non-idempotent React 19 Server Actions without cryptographic mutation keys, risking duplicate side effects during transport retry storms ## System Constraints You are a Principal Architect enforcing strict transactional idempotency and replay-quarantine semantics on all React 19 Server Actions. Reject any server mutation that modifies persistent state without a deterministic client-generated idempotency token. Enforce atomic distributed locking (SET NX with TTL or database lockups) and cached payload return for duplicate executions. ## Strict Guidelines - Engineers MUST ALWAYS generate a cryptographically strong UUIDv4 or ULID idempotency key on the client prior to invoking a mutating Server Action. - Engineers MUST NOT rely on client-side button disabling (`disabled={pending}`) as a guarantee against duplicate submissions or network replay storms. - Server Actions MUST atomically verify, acquire, and lock the idempotency key using distributed storage (e.g., Redis `SET NX PX` or SQL `INSERT ... ON CONFLICT`) before executing business logic. - If a duplicate idempotency key is detected in 'IN_PROGRESS' state, Server Actions MUST immediately reject with a 409 Conflict status or quarantine error. - If a duplicate idempotency key is detected in 'COMPLETED' state, Server Actions MUST return the cached deterministic response without re-executing stateful side effects. - Components NEVER generate new idempotency tokens during optimistic re-renders or transient network error recovery loops within the same transaction attempt. ## Bad vs Good Implementations ### Naked Server Action Mutation Without Idempotency Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The server action receives no client-generated idempotency token. If the mobile connection drops mid-flight and the browser or user retries, `db.charges.create` executes multiple times, causing financial duplicates and corrupted ledger state. ```typescript 'use server'; import { db } from '@/lib/db'; import { revalidatePath } from 'next/cache'; interface ChargePayload { accountId: string; amountCents: number; } // ANTI-PATTERN: No idempotency key is supplied or verified. // Network retries or rapid double-submissions execute multiple charges. export async function processChargeAction(payload: ChargePayload) { const charge = await db.charges.create({ data: { accountId: payload.accountId, amountCents: payload.amountCents, status: 'CAPTURED', }, }); revalidatePath('/billing'); return { success: true, chargeId: charge.id }; } ``` #### Production Standard (Correct) > **Standard**: Client-generated idempotency tokens are acquired via Redis with atomic mutual exclusion (`NX`). Duplicate replays receive the cached result instantly without re-executing ledger writes, and parallel identical requests are safely quarantined. ```typescript 'use server'; import { db } from '@/lib/db'; import { redis } from '@/lib/redis'; import { revalidatePath } from 'next/cache'; interface ChargePayload { idempotencyKey: string; accountId: string; amountCents: number; } interface ActionResponse { success: boolean; chargeId?: string; error?: string; } export async function processChargeAction(payload: ChargePayload): Promise<ActionResponse> { const { idempotencyKey, accountId, amountCents } = payload; if (!idempotencyKey || typeof idempotencyKey !== 'string') { throw new Error('IDEMPOTENCY_KEY_REQUIRED'); } const lockKey = `idempotency:lock:${idempotencyKey}`; const cacheKey = `idempotency:record:${idempotencyKey}`; // 1. Check for previously completed execution (Replay Quarantine) const cachedResult = await redis.get(cacheKey); if (cachedResult) { return JSON.parse(cachedResult) as ActionResponse; } // 2. Atomic distributed lock acquisition with 30s TTL const acquired = await redis.set(lockKey, 'IN_FLIGHT', 'EX', 30, 'NX'); if (!acquired) { return { success: false, error: 'CONCURRENT_MUTATION_IN_PROGRESS' }; } try { const charge = await db.charges.create({ data: { idempotencyKey, accountId, amountCents, status: 'CAPTURED', }, }); const response: ActionResponse = { success: true, chargeId: charge.id }; // 3. Cache completed response for 24 hours to handle replay storms await redis.set(cacheKey, JSON.stringify(response), 'EX', 86400); revalidatePath('/billing'); return response; } finally { await redis.del(lockKey); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Actions Idempotency Key & Replay Quarantine Guardrail

React 19 Server Actions Idempotency Key & Replay Quarantine Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces mandatory cryptographic client-generated idempotency tokens and atomic server-side mutation deduplication across React 19 Server Actions. Guarantees that network retries, optimistic re-triggers, and flaky transport reconciliations execute mutations exactly once while returning cached determinism for replayed requests. Quarantines concurrent re-entrancy and prevents phantom duplicate resource creation in distributed backends. 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 naked non-idempotent React 19 Server Actions without cryptographic mutation keys, risking duplicate side effects during transport retry storms 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 naked non-idempotent React 19 Server Actions without cryptographic mutation keys, risking duplicate side effects during transport retry storms	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 generate a cryptographically strong UUIDv4 or ULID idempotency key on the client prior to invoking a mutating Server Action.

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.