React 19 Server Actions Idempotency & Replay Shield Standard

--- description: React 19 Server Actions Idempotency & Replay Shield Standard - Enforces deterministic client-generated idempotency keys and atomic server-side deduplication for mutating React 19 Server Actions. Eliminates duplicate transactions and race conditions during network retries while preventing optimistic UI desynchronization. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-server-actions-idempotency-replay-shield-production-standard" --- # React 19 Server Actions Idempotency & Replay Shield Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Blind Server Action Invocations and Transient Idempotency Generating Duplicate Side Effects on Network Retries ## System Constraints You are a Principal Software Architect enforcing production-grade idempotency and optimistic UI invariants in React 19 Server Actions. Mandate client-side deterministic idempotency token generation paired with atomic server-side deduplication (using distributed locks or transactional key-value stores). Forbid direct invocation of non-idempotent server actions from mutating form handlers or hooks. Enforce strict synchronization between React 19's useActionState, useOptimistic, and verified idempotency lifecycle states. ## Strict Guidelines - Engineers MUST ALWAYS generate a cryptographically unique idempotency key on the client per user intent (e.g., button click / draft creation) prior to invoking a mutating Server Action. - Engineers MUST NOT generate idempotency keys inside the Server Action itself, as retries will generate separate keys and trigger duplicate side effects. - Engineers MUST store and verify idempotency tokens atomically in an external cache or database (e.g., Redis SETNX or PostgreSQL INSERT ON CONFLICT) with status tracking ('PROCESSING', 'COMPLETED', 'FAILED'). - Services MUST return the original cached response if an idempotency key with status 'COMPLETED' is replayed, without re-executing downstream business logic. - Components MUST NOT clear or roll back optimistic UI states until the Server Action definitively completes or returns a terminal non-retriable failure. - Engineers MUST pass the idempotency key as an immutable hidden form field or as an explicit parameter in server action bindings. - Components NEVER bind naked mutating actions to form actions without handling the in-flight pending state provided by useActionState. ## Bad vs Good Implementations ### Non-Idempotent Server Action with Unshielded Retries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The server action has no idempotency protection. If a user double-clicks or an unreliable connection retries the request, processPayment runs multiple times, causing duplicate financial transactions and corrupting state. ```typescript // BAD: No idempotency key provided by client. Network retries execute duplicate charges. // app/actions/checkout.ts 'use server'; import { db } from '@/lib/db'; import { paymentGateway } from '@/lib/payment'; export async function processPayment(prevState: any, formData: FormData) { const orderId = formData.get('orderId') as string; const amount = Number(formData.get('amount')); // Flaw: Network timeouts will cause React/browser retries to re-charge the customer const charge = await paymentGateway.charge({ orderId, amount }); await db.orders.update({ where: { id: orderId }, data: { status: 'PAID', chargeId: charge.id } }); return { success: true, chargeId: charge.id }; } // app/checkout/page.tsx 'use client'; import { useActionState, useOptimistic } from 'react'; import { processPayment } from '@/app/actions/checkout'; export function CheckoutForm({ order }: { order: { id: string; total: number } }) { const [state, formAction, isPending] = useActionState(processPayment, null); const [optimisticPaid, setOptimisticPaid] = useOptimistic(false, () => true); return ( <form action={async (formData) => { setOptimisticPaid(true); await formAction(formData); // Network retry causes catastrophic double mutation }}> <input type="hidden" name="orderId" value={order.id} /> <input type="hidden" name="amount" value={order.total} /> <button type="submit" disabled={isPending}> {optimisticPaid ? 'Processing Payment...' : 'Pay Now'} </button> </form> ); } ``` #### Production Standard (Correct) > **Standard**: A client-generated idempotency key is maintained across retries. The server uses Redis atomic SETNX to guard execution. Retried requests either safely receive the in-flight status or the cached successful response without executing duplicate payments. ```typescript // GOOD: Client-initiated deterministic idempotency key and atomic distributed locking. // app/actions/checkout.ts 'use server'; import { redis } from '@/lib/redis'; import { db } from '@/lib/db'; import { paymentGateway } from '@/lib/payment'; interface ActionResponse { success: boolean; chargeId?: string; error?: string; } export async function processPaymentWithShield( prevState: ActionResponse | null, formData: FormData ): Promise<ActionResponse> { const idempotencyKey = formData.get('idempotencyKey') as string; const orderId = formData.get('orderId') as string; const amount = Number(formData.get('amount')); if (!idempotencyKey) { return { success: false, error: 'MISSING_IDEMPOTENCY_KEY' }; } // Atomic lock & replay check: Lock duration 120s const lockKey = `idempotency:${idempotencyKey}`; const acquire = await redis.set(lockKey, JSON.stringify({ status: 'PROCESSING' }), 'EX', 120, 'NX'); if (!acquire) { const existing = await redis.get(lockKey); if (existing) { const cached = JSON.parse(existing); if (cached.status === 'PROCESSING') { return { success: false, error: 'CONCURRENT_REQUEST_IN_FLIGHT' }; } // Return memoized response without re-executing payment return cached.result; } return { success: false, error: 'ACQUISITION_FAILED' }; } try { const charge = await paymentGateway.charge({ orderId, amount, idempotencyKey }); await db.orders.update({ where: { id: orderId }, data: { status: 'PAID', chargeId: charge.id } }); const response: ActionResponse = { success: true, chargeId: charge.id }; await redis.set(lockKey, JSON.stringify({ status: 'COMPLETED', result: response }), 'EX', 86400); return response; } catch (err: any) { await redis.del(lockKey); return { success: false, error: err.message || 'PAYMENT_FAILED' }; } } // app/checkout/page.tsx 'use client'; import { useActionState, useOptimistic, useState } from 'react'; import { processPaymentWithShield } from '@/app/actions/checkout'; export function CheckoutForm({ order }: { order: { id: string; total: number } }) { // Deterministic key maintained per attempt/session const [idempotencyKey] = useState(() => crypto.randomUUID()); const [state, formAction, isPending] = useActionState(processPaymentWithShield, null); const [optimisticState, setOptimisticState] = useOptimistic( { isPaid: false, isPending: false }, (current) => ({ ...current, isPending: true }) ); return ( <form action={async (formData: FormData) => { setOptimisticState({ isPaid: false, isPending: true }); await formAction(formData); }} > <input type="hidden" name="idempotencyKey" value={idempotencyKey} /> <input type="hidden" name="orderId" value={order.id} /> <input type="hidden" name="amount" value={order.total} /> {state?.error && <p className="text-red-500" role="alert">{state.error}</p>} <button type="submit" disabled={isPending || optimisticState.isPending}> {isPending || optimisticState.isPending ? 'Processing...' : 'Pay Now'} </button> </form> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Actions Idempotency & Replay Shield Standard

React 19 Server Actions Idempotency & Replay Shield Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic client-generated idempotency keys and atomic server-side deduplication for mutating React 19 Server Actions. Eliminates duplicate transactions and race conditions during network retries while preventing optimistic UI desynchronization. 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 Server Action Invocations and Transient Idempotency Generating Duplicate Side Effects on 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	Blind Server Action Invocations and Transient Idempotency Generating Duplicate Side Effects on 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 a cryptographically unique idempotency key on the client per user intent (e.g., button click / draft creation) 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.