React 19 Server Action Idempotency Key Guardrail

--- description: React 19 Server Action Idempotency Key Guardrail - Enforces deterministic deduplication of state mutations across React 19 Server Actions interacting with optimistic UI transitions. Unmanaged optimistic rollbacks and automatic form resubmissions cause duplicate side-effects (e.g., double billing, duplicate records) across asynchronous network boundaries. All mutating Server Actions MUST require and validate client-generated UUIDv7 or cryptographic idempotency keys cached in a distributed transactional store. 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-action-idempotency-key-guardrail" --- # React 19 Server Action Idempotency Key Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Executing non-idempotent Server Actions inside useActionState or useOptimistic without persistent transaction keys ## System Constraints You are a Principal Software Architect enforcing production reliability across React 19 Server Action boundaries. You strictly reject any Server Action performing transactional side-effects (payments, state transitions, mutations) that lacks a cryptographically sound or monotonic client-issued idempotency key. You ensure optimistic mutations via useOptimistic or useActionState maintain consistent client-side keys during retries and that the server enforces atomic deduplication via distributed lock/cache backends. ## Strict Guidelines - Engineers MUST ALWAYS pass an explicit, immutable client-generated idempotency key (such as UUIDv7) into mutating React 19 Server Actions. - Engineers MUST NOT generate new idempotency keys during automatic action retries or within pure render cycles. - Components MUST generate and bind the idempotency key outside the action transition handler or store it in component state until the action settles. - Server Actions MUST atomically verify and claim the idempotency key in an external cache (e.g., Redis via SET NX EX) or database transaction prior to executing downstream side-effects. - Server Actions MUST return the cached result payload when encountering a duplicate key instead of throwing a generic uncaught error or re-executing business logic. ## Bad vs Good Implementations ### Idempotent Server Action Handling with Client-Bound UUIDv7 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Network timeouts or aggressive user resubmissions via optimistic forms will execute duplicate financial transactions. The Server Action relies entirely on implicit HTTP invocation state without idempotency control. ```typescript // 'use server' export async function processOrderAction(formData: FormData) { // VULNERABLE: Invocation triggered by useActionState / useOptimistic retry // executes multiple non-deduplicated charges and database writes const amount = Number(formData.get('amount')); const charge = await paymentGateway.charge({ amount }); await db.orders.create({ data: { chargeId: charge.id, amount } }); return { success: true, chargeId: charge.id }; } ``` #### Production Standard (Correct) > **Standard**: The Server Action requires a verified idempotency key, acquires an atomic distributed lock via Redis before invoking external gateways, caches the terminal response for safe retries, and properly clears locks on recoverable execution failures. ```typescript // 'use server' import { redis } from '@/lib/redis'; import { z } from 'zod'; const ActionSchema = z.object({ amount: z.number().positive(), idempotencyKey: z.string().uuid() }); export async function processOrderAction(formData: FormData) { const parsed = ActionSchema.safeParse({ amount: Number(formData.get('amount')), idempotencyKey: formData.get('idempotencyKey') }); if (!parsed.success) { return { success: false, error: 'INVALID_PAYLOAD' }; } const { amount, idempotencyKey } = parsed.data; const lockKey = `idempotency:order:${idempotencyKey}`; // Atomic check-and-set with 120s TTL const acquired = await redis.set(lockKey, 'PROCESSING', { nx: true, ex: 120 }); if (!acquired) { const existingResult = await redis.get(lockKey); if (existingResult && existingResult !== 'PROCESSING') { return JSON.parse(existingResult); } return { success: false, error: 'OPERATION_IN_FLIGHT' }; } try { const charge = await paymentGateway.charge({ amount, idempotencyKey }); const order = await db.orders.create({ data: { chargeId: charge.id, amount, idempotencyKey } }); const payload = { success: true, orderId: order.id }; await redis.set(lockKey, JSON.stringify(payload), { ex: 86400 }); return payload; } catch (err) { await redis.del(lockKey); throw err; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Action Idempotency Key Guardrail

React 19 Server Action Idempotency Key Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic deduplication of state mutations across React 19 Server Actions interacting with optimistic UI transitions. Unmanaged optimistic rollbacks and automatic form resubmissions cause duplicate side-effects (e.g., double billing, duplicate records) across asynchronous network boundaries. All mutating Server Actions MUST require and validate client-generated UUIDv7 or cryptographic idempotency keys cached in a distributed transactional store. 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 non-idempotent Server Actions inside useActionState or useOptimistic without persistent transaction keys 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 non-idempotent Server Actions inside useActionState or useOptimistic without persistent transaction keys	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 pass an explicit, immutable client-generated idempotency key (such as UUIDv7) into mutating React 19 Server Actions.

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.