用幂等键和事务发件箱，彻底避免 Next.js 表单重复提交

'use client'

import { useRef, useState } from 'react'

export function LeadForm({ formId }: { formId: string }) {
  const activeKey = useRef<string | null>(null)
  const [submitting, setSubmitting] = useState(false)

  async function submit(payload: Record<string, unknown>) {
    const key = activeKey.current ?? crypto.randomUUID()
    activeKey.current = key
    setSubmitting(true)

    try {
      const response = await fetch(`/api/forms/${formId}/submit`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Idempotency-Key': key,
        },
        body: JSON.stringify(payload),
      })

      if (response.status === 409) {
        activeKey.current = null
        throw new Error('This submission was retried with different data.')
      }

      if (!response.ok) {
        throw new Error('Submission failed')
      }

      const receipt = await response.json()
      activeKey.current = null
      return receipt
    } finally {
      setSubmitting(false)
    }
  }

  // Render form fields and pass `submitting` to the submit button.
  return null
}

CREATE EXTENSION IF NOT EXISTS pgcrypto;

CREATE TABLE form_submissions (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  form_id uuid NOT NULL,
  schema_version integer NOT NULL,
  idempotency_key text NOT NULL,
  request_hash text NOT NULL,
  payload jsonb NOT NULL,
  status text NOT NULL DEFAULT 'accepted',
  response_json jsonb,
  created_at timestamptz NOT NULL DEFAULT now(),
  UNIQUE (form_id, idempotency_key)
);

CREATE TABLE integration_events (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  submission_id uuid NOT NULL REFERENCES form_submissions(id),
  integration_id uuid NOT NULL,
  delivery_key text NOT NULL UNIQUE,
  status text NOT NULL DEFAULT 'pending',
  attempt_count integer NOT NULL DEFAULT 0,
  next_attempt_at timestamptz NOT NULL DEFAULT now(),
  lease_expires_at timestamptz,
  last_error_code text,
  UNIQUE (submission_id, integration_id)
);

import { createHash } from 'node:crypto'

function canonicalJson(value: unknown): string {
  if (Array.isArray(value)) {
    return `[${value.map(canonicalJson).join(',')}]`
  }

  if (value && typeof value === 'object') {
    const entries = Object.entries(value as Record<string, unknown>)
      .sort(([a], [b]) => a.localeCompare(b))
      .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)

    return `{${entries.join(',')}}`
  }

  return JSON.stringify(value)
}

export function fingerprintSubmission(input: {
  formId: string
  schemaVersion: number
  payload: Record<string, unknown>
}) {
  return createHash('sha256')
    .update(canonicalJson(input))
    .digest('hex')
}

import type { Pool } from 'pg'

export async function acceptSubmission(db: Pool, input: {
  formId: string
  schemaVersion: number
  key: string
  requestHash: string
  payload: Record<string, unknown>
  integrationIds: string[]
}) {
  const client = await db.connect()

  try {
    await client.query('BEGIN')

    const inserted = await client.query(
      `INSERT INTO form_submissions
        (form_id, schema_version, idempotency_key, request_hash, payload)
       VALUES ($1, $2, $3, $4, $5::jsonb)
       ON CONFLICT (form_id, idempotency_key) DO NOTHING
       RETURNING id`,
      [
        input.formId,
        input.schemaVersion,
        input.key,
        input.requestHash,
        JSON.stringify(input.payload),
      ],
    )

    if (inserted.rowCount === 0) {
      const existing = await client.query(
        `SELECT id, request_hash, response_json
         FROM form_submissions
         WHERE form_id = $1 AND idempotency_key = $2`,
        [input.formId, input.key],
      )

      const row = existing.rows[0]
      if (!row || row.request_hash !== input.requestHash) {
        const error = new Error('Idempotency conflict')
        ;(error as Error & { status?: number }).status = 409
        throw error
      }

      await client.query('COMMIT')
      return { ...row.response_json, replayed: true }
    }

    const submissionId = inserted.rows[0].id
    const receipt = { submissionId, accepted: true }

    for (const integrationId of input.integrationIds) {
      const deliveryKey = `${submissionId}:${integrationId}`
      await client.query(
        `INSERT INTO integration_events
          (submission_id, integration_id, delivery_key)
         VALUES ($1, $2, $3)
         ON CONFLICT (submission_id, integration_id) DO NOTHING`,
        [submissionId, integrationId, deliveryKey],
      )
    }

    await client.query(
      `UPDATE form_submissions
       SET response_json = $2::jsonb
       WHERE id = $1`,
      [submissionId, JSON.stringify(receipt)],
    )

    await client.query('COMMIT')
    return { ...receipt, replayed: false }
  } catch (error) {
    await client.query('ROLLBACK')
    throw error
  } finally {
    client.release()
  }
}

WITH candidate AS (
  SELECT id
  FROM integration_events
  WHERE (
    status IN ('pending', 'retryable')
    AND next_attempt_at <= now()
  ) OR (
    status = 'processing'
    AND lease_expires_at < now()
  )
  ORDER BY next_attempt_at
  FOR UPDATE SKIP LOCKED
  LIMIT 1
)
UPDATE integration_events AS event
SET status = 'processing',
    attempt_count = attempt_count + 1,
    lease_expires_at = now() + interval '2 minutes'
FROM candidate
WHERE event.id = candidate.id
RETURNING event.*;

it('accepts concurrent retries only once', async () => {
  const key = crypto.randomUUID()

  const attempts = await Promise.all(
    Array.from({ length: 10 }, () =>
      submitForm({
        formId,
        key,
        payload: validLead,
      }),
    ),
  )

  expect(new Set(attempts.map(item => item.submissionId)).size).toBe(1)
  expect(await countSubmissions({ formId, key })).toBe(1)
  expect(
    await countEventsForSubmission(attempts[0].submissionId),
  ).toBe(enabledIntegrations.length)
})

it('rejects the same key with different data', async () => {
  const key = crypto.randomUUID()

  await submitForm({ formId, key, payload: validLead })

  await expect(
    submitForm({
      formId,
      key,
      payload: { ...validLead, email: 'other@example.com' },
    }),
  ).rejects.toMatchObject({ status: 409 })
})