React 19 Server Action Idempotency-Key Deduplication Guardrail

--- description: React 19 Server Action Idempotency-Key Deduplication Guardrail - Enforces deterministic client-side generation and server-side atomic validation of idempotency keys across all mutating React 19 Server Actions. Guarantees that concurrent submissions, network retry storms, and transient timeout replay loops cannot cause duplicate side effects or non-reentrant state corruptions. Mandates atomic distributed lock/reservation primitives prior to executing durable business mutations. globs: src/actions/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}, src/features/**/actions/**/*.{ts,tsx}, src/lib/mutations/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-server-action-idempotency-deduplication" --- # React 19 Server Action Idempotency-Key Deduplication Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Blind Execution of Non-Idempotent React 19 Server Actions on Optimistic Retries ## System Constraints You are a Principal Software Architect enforcing production-grade concurrency invariants on React 19 Server Actions. You must prevent duplicate writes, non-reentrant state corruption, and race conditions during network retries by requiring client-instantiated idempotency keys, atomic distributed reservation checks (e.g., Redis SET NX or DB unique constraints), and deterministic mutation response caching. ## Strict Guidelines - Engineers MUST ALWAYS generate a cryptographically unique `idempotencyKey` (UUIDv4/NanoID) on the client per logical user intent before triggering a Server Action, passing it through form state or explicit action arguments. - Engineers MUST NOT create or re-generate idempotency keys inside the Server Action scope, as subsequent network-level retries will receive distinct keys and defeat deduplication. - Engineers MUST ALWAYS wrap the Server Action mutation logic with an atomic reservation check (e.g., Redis `SET key value NX PX` or an INSERT with `ON CONFLICT DO NOTHING`) prior to executing external side effects (e.g., Stripe, database writes). - Services MUST return cached responses or handle in-flight locks gracefully when an idempotency key collision is detected, returning a deterministic result rather than re-executing business logic. - Components MUST retain the stable `idempotencyKey` across optimistic updates and `useActionState` retries, ensuring that automated form re-submissions or transient error replays target the same server mutation identifier. ## Bad vs Good Implementations ### Naive Server Action Execution vs. Atomic Idempotency-Guarded Action #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The action accepts a raw payload without a client-originated idempotency key. A retry storm, duplicate form submission, or network drop between server response and client receipt causes duplicate order records and double charging. ```typescript 'use server'; import { db } from '@/lib/db'; import { orders } from '@/lib/schema'; interface CheckoutPayload { itemId: string; quantity: number; userId: string; } // ANTI-PATTERN: No idempotency key validation. A double-click, unstable connection, // or automated retry will trigger multiple debits and duplicate order rows. export async function checkoutAction(payload: CheckoutPayload) { const user = await db.query.users.findFirst({ where: (u, { eq }) => eq(u.id, payload.userId) }); if (!user || user.balance < 100) { throw new Error('Insufficient funds'); } // Non-atomic read-then-write; network retry executes this multiple times const [order] = await db.insert(orders).values({ userId: payload.userId, itemId: payload.itemId, quantity: payload.quantity, createdAt: new Date(), }).returning(); return { success: true, orderId: order.id }; } ``` #### Production Standard (Correct) > **Standard**: The client passes a UUIDv4 `idempotencyKey`. The action atomically reserves this key via Redis NX semantics before initiating the transaction. Concurrent replays are blocked, while post-completion retries return the cached result deterministically without side effects. ```typescript 'use server'; import { db } from '@/lib/db'; import { orders } from '@/lib/schema'; import { redis } from '@/lib/redis'; import { z } from 'zod'; const CheckoutSchema = z.object({ idempotencyKey: z.string().uuid(), itemId: z.string().min(1), quantity: z.number().int().positive(), userId: z.string().min(1), }); export type CheckoutInput = z.infer<typeof CheckoutSchema>; export async function checkoutAction(rawInput: CheckoutInput) { const input = CheckoutSchema.parse(rawInput); const lockKey = `idempotency:checkout:${input.userId}:${input.idempotencyKey}`; // Atomic distributed reservation lock with 120s TTL const acquired = await redis.set(lockKey, 'IN_FLIGHT', 'EX', 120, 'NX'); if (!acquired) { const cachedResult = await redis.get(lockKey); if (cachedResult && cachedResult !== 'IN_FLIGHT') { // Deterministic replay of completed mutation return JSON.parse(cachedResult) as { success: boolean; orderId: string }; } throw new Error('Mutation already in-flight. Please wait.'); } try { const [order] = await db.insert(orders).values({ userId: input.userId, itemId: input.itemId, quantity: input.quantity, idempotencyKey: input.idempotencyKey, createdAt: new Date(), }).returning(); const response = { success: true, orderId: order.id }; // Cache completed result for deterministic replay across retry window await redis.set(lockKey, JSON.stringify(response), 'EX', 86400); return response; } catch (error) { // Release reservation lock on unrecoverable failure to permit client retries await redis.del(lockKey); throw error; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Action Idempotency-Key Deduplication Guardrail

React 19 Server Action Idempotency-Key Deduplication Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic client-side generation and server-side atomic validation of idempotency keys across all mutating React 19 Server Actions. Guarantees that concurrent submissions, network retry storms, and transient timeout replay loops cannot cause duplicate side effects or non-reentrant state corruptions. Mandates atomic distributed lock/reservation primitives prior to executing durable business mutations. 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: Blind Execution of Non-Idempotent React 19 Server Actions on Optimistic Retries 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	Blind Execution of Non-Idempotent React 19 Server Actions on Optimistic Retries	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 unique `idempotencyKey` (UUIDv4/NanoID) on the client per logical user intent before triggering a Server Action, passing it through form state or explicit action arguments.

Engineers MUST ALWAYS generate a cryptographically unique `idempotencyKey` (UUIDv4/NanoID) on the client per logical user intent before triggering a Server Action, passing it through form state or explicit action arguments.

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.