Mandatory Idempotency Keys for Mutating React 19 Server Actions

--- description: Mandatory Idempotency Keys for Mutating React 19 Server Actions - Enforces network-resilient mutations across React 19 Server Actions by requiring client-generated, cryptographically unique idempotency tokens bound to submission state. Under high-latency or unstable mobile network transitions, automatic or user-driven retries must guarantee strict exactly-once execution semantics at the persistence layer. Without this guardrail, duplicate executions corrupt state, duplicate financial transactions, and create unrecoverable orphaned records. globs: app/**/*.{ts,tsx}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-server-actions-idempotency-key-guardrail" --- # Mandatory Idempotency Keys for Mutating React 19 Server Actions > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded Server Action Invocations Allowing Duplicate Execution Under Mobile Network Retries ## System Constraints You are a Principal Software Architect enforcing production-grade resilience standards on React 19 Server Actions. You must reject any mutating Server Action that lacks deterministic idempotency handling. Ensure that all transactional workflows initiated via forms, useActionState, or startTransition pass a client-persisted idempotency key and verify it atomically at the server boundary before executing side effects. ## Strict Guidelines - Engineers MUST ALWAYS generate an idempotency key (e.g., UUIDv4 or crypto.randomUUID()) on the client during form initialization or per logical user intent, preserving it across transient render cycles until successful completion. - Engineers MUST pass the idempotency key as a hidden form input or explicit argument into any mutating Server Action ('use server'). - Services MUST atomically acquire or check the idempotency key in a centralized transactional store (e.g., Redis SETNX or SQL unique constraint lock) before executing any state-mutating side effects. - Engineers MUST NOT regenerate the idempotency key during automatic network retries, component re-renders, or re-executions caused by hydration mismatches. - Services MUST cache and return the original successful response if a request containing an already-processed idempotency key is received. - Components NEVER rely solely on client-side button disabling (`disabled={pending}`) to prevent duplicate transactional submissions, as network dropped-ACK events bypass client state locks. ## Bad vs Good Implementations ### React 19 Server Action with Idempotency Key Pipeline #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When a client experiences mobile packet drop after the server finishes DB creation but before the HTTP response reaches the device, React/browser retries or user double-clicks submit a second mutation, resulting in duplicate order creation and multiple payment authorizations. ```typescript // BAD: Naked server action execution vulnerable to duplicate records on network retry 'use server'; import { db } from '@/lib/db'; export async function processOrderAction(prevState: unknown, formData: FormData) { const sku = formData.get('sku') as string; const quantity = Number(formData.get('quantity')); // DANGER: Re-submitting on flaky 3G/LTE mobile connections causes duplicate orders/charges const order = await db.orders.create({ data: { sku, quantity, status: 'PENDING' } }); await db.payments.charge({ orderId: order.id }); return { success: true, orderId: order.id }; } ``` #### Production Standard (Correct) > **Standard**: A client-supplied idempotency key is evaluated using an atomic distributed lock and response cache. Duplicate submissions receive either the cached canonical response or an in-flight status, guaranteeing exactly-once transactional semantics. ```typescript // GOOD: Production-grade idempotency enforcement with atomic lock and response caching 'use server'; import { db } from '@/lib/db'; import { redis } from '@/lib/redis'; interface ActionResponse { success: boolean; orderId?: string; error?: string; } export async function processOrderAction( prevState: ActionResponse | null, formData: FormData ): Promise<ActionResponse> { const idempotencyKey = formData.get('idempotencyKey') as string; const sku = formData.get('sku') as string; const quantity = Number(formData.get('quantity')); if (!idempotencyKey || typeof idempotencyKey !== 'string') { throw new Error('MISSING_IDEMPOTENCY_KEY: Refusing to process non-deterministic mutation.'); } const lockKey = `idempotency:${idempotencyKey}`; // Acquire lock for 120 seconds using SETNX semantics const acquired = await redis.set(lockKey, 'IN_FLIGHT', { nx: true, ex: 120 }); if (!acquired) { const cachedResult = await redis.get<ActionResponse>(`${lockKey}:result`); if (cachedResult) { return cachedResult; } return { success: false, error: 'Transaction is currently processing. Please wait.' }; } try { const order = await db.$transaction(async (tx) => { return tx.orders.create({ data: { sku, quantity, idempotencyKey, status: 'CONFIRMED' } }); }); const result: ActionResponse = { success: true, orderId: order.id }; await redis.set(`${lockKey}:result`, JSON.stringify(result), { ex: 86400 }); return result; } catch (err) { await redis.del(lockKey); throw err; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory Idempotency Keys for Mutating React 19 Server Actions

Mandatory Idempotency Keys for Mutating React 19 Server Actions defines an industrial-grade behavioral standard for frontend engineering. Enforces network-resilient mutations across React 19 Server Actions by requiring client-generated, cryptographically unique idempotency tokens bound to submission state. Under high-latency or unstable mobile network transitions, automatic or user-driven retries must guarantee strict exactly-once execution semantics at the persistence layer. Without this guardrail, duplicate executions corrupt state, duplicate financial transactions, and create unrecoverable orphaned records. 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: Unbounded Server Action Invocations Allowing Duplicate Execution Under Mobile Network 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	Unbounded Server Action Invocations Allowing Duplicate Execution Under Mobile Network 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 an idempotency key (e.g., UUIDv4 or crypto.randomUUID()) on the client during form initialization or per logical user intent, preserving it across transient render cycles until successful completion.

Engineers MUST ALWAYS generate an idempotency key (e.g., UUIDv4 or crypto.randomUUID()) on the client during form initialization or per logical user intent, preserving it across transient render cycles until successful completion.

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.