@elytracms/forms 0.0.0-stage → 0.0.95

package/src/convex/index.ts

@@ -0,0 +1,340 @@
+import { internalActionGeneric, makeFunctionReference } from 'convex/server'
+import { v } from 'convex/values'
+import type { GenericId } from 'convex/values'
+import { createUuidIdFactory } from '@elytracms/core/determinism'
+import { INGEST_MAX_UPLOAD_BYTES, INGEST_UPLOAD_TTL_MS } from '@elytracms/core/ingest'
+import type { IngestHandlerResult } from '@elytracms/core/ingest'
+import { resolveRecordQuery } from '@elytracms/core/persistence'
+import type { RecordWireRow } from '@elytracms/core/persistence'
+import { internalMutation, internalQuery, mutation } from '@elytracms/studio/convex/functions'
+import type { MutationCtx } from '@elytracms/studio/convex/functions'
+import { requireCapability } from '@elytracms/studio/convex/guard'
+import {
+  claimIngestUpload,
+  ingestHandler,
+  ingestHandlerArgs,
+  ingestUploadRecordKind,
+  parseIngestPayload,
+  recordIngestUpload,
+} from '@elytracms/studio/convex/ingest'
+import {
+  defineRecordFunctions,
+  findRecordDoc,
+  listRecordWire,
+  saveRecord,
+} from '@elytracms/studio/convex/record-functions'
+import { submissionRecordKind } from '../shared/kind'
+import type { DeliveryEntry, DeliveryState, SubmissionField, SubmissionFile } from '../shared/kind'
+import { FORMS_UPLOAD_CONTENT_TYPES, readSubmissionPayload } from '../shared/submission'
+import {
+  FORMS_DELIVERY_URL_ENV,
+  applyDeliveryOutcome,
+  attemptFormDelivery,
+  deliveredRecipients,
+  deliveryOutcomeSchema,
+} from '../shared/delivery'
+import type { FormDeliveryRequest } from '../shared/delivery'
+
+/**
+ * `@elytracms/forms/convex` — the deployment half of the forms addon (EC-613). The project
+ * reaches it with ONE re-export file, named by the kind's `module`:
+ *
+ * ```ts
+ * // studio/convex/forms.ts
+ * export * from '@elytracms/forms/convex'
+ * ```
+ *
+ * …and registers the receiver's handler in its one `http.ts` line:
+ *
+ * ```ts
+ * import { formsIngest } from '@elytracms/forms/convex'
+ * export default defineStudioHttp({ auth, ingest: { submission: formsIngest } })
+ * ```
+ *
+ * What it holds:
+ *
+ * - **the kind's functions** — `get` / `list` (the record store's, EC-616), `save` (the
+ *   record store's write, plus: a write that moves a row INTO `pending` schedules its
+ *   delivery — the editor's "retry"), `remove` (the row AND its stored files);
+ * - **`ingest`** — the receiver's `submission` handler (EC-617): an `upload` is accepted
+ *   under the forms upload policy and its intent recorded; a `submission` is read
+ *   (`readSubmissionPayload`), its uploads claimed, the row written and its delivery
+ *   scheduled. A claim that fails refuses the submission and deletes the files already
+ *   claimed for it — no claimed bytes ever sit without a row;
+ * - **`deliver`** — the scheduled action per row: it asks the site's delivery route to send
+ *   (`attemptFormDelivery`) and `recordDelivery` logs the answer per recipient and schedules
+ *   the next attempt (`applyDeliveryOutcome`);
+ * - **`unclaimedUploads`** — internal: the upload intents past their life that no submission
+ *   claimed (their bytes cannot be located — EC-617's residue — so they are listed, not swept).
+ *
+ * Environment: `ELYTRA_INGEST_SECRET` (the ingest pair, EC-617) and
+ * `ELYTRA_FORMS_DELIVERY_URL` (the site's delivery route, e.g. `https://example.com/api/forms`).
+ */
+
+const kind = submissionRecordKind
+
+/** The functions of this module, addressed by the kind's module (`forms:deliver`). */
+const fn = (name: string) => `${kind.module}:${name}` as const
+const deliverRef = makeFunctionReference<'action', { submissionId: string; attempt: number }>(fn('deliver'))
+const deliveryInputRef = makeFunctionReference<'query', { submissionId: string }, DeliveryInput | null>(fn('deliveryInput'))
+const recordDeliveryRef = makeFunctionReference<'mutation', { submissionId: string; attempt: number; outcome: unknown }>(
+  fn('recordDelivery'),
+)
+
+/** The receiver's handler, for the project's `http.ts`: `defineStudioHttp({ auth, ingest: { submission: formsIngest } })`. */
+export const formsIngest = ingestHandler(fn('ingest'))
+
+/** The forms upload policy (the receiver's 10 MiB cap; documents and raster images only). */
+const UPLOAD_POLICY = { maxBytes: INGEST_MAX_UPLOAD_BYTES, contentTypes: FORMS_UPLOAD_CONTENT_TYPES }
+
+function env(name: string): string | undefined {
+  const value = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.[name]?.trim()
+  return value ? value : undefined
+}
+
+async function scheduleDelivery(ctx: MutationCtx, submissionId: string, attempt: number, delayMs: number): Promise<void> {
+  await ctx.scheduler.runAfter(delayMs, deliverRef, { submissionId, attempt })
+}
+
+// --- The kind's functions ------------------------------------------------------------------
+
+const records = defineRecordFunctions(kind)
+
+/** One submission by id (the record store's `get`). */
+export const get = records.get
+/** The project's submissions, filtered by `form` / `status` and time (the record store's `list`). */
+export const list = records.list
+
+const columnArgs = Object.fromEntries(
+  [...Object.keys(kind.fields), 'meta'].map((column) => [column, v.optional(v.any())]),
+)
+
+/**
+ * The record store's write (EC-577: absent keeps, `null` clears, a value sets), and one rule
+ * of the forms addon: a write that moves a row INTO `pending` schedules its delivery — how an
+ * editor retries a failed one. The inbox writes only the editor's columns it changed, so a
+ * save never carries a stale copy of the delivery the action is writing.
+ */
+export const save = mutation({
+  args: { [kind.idKey]: v.string(), ...columnArgs, createdAt: v.string(), updatedAt: v.string() },
+  handler: async (ctx, args: Record<string, unknown>) => {
+    await requireCapability(ctx, kind.access.write)
+    const { [kind.idKey]: submissionId, createdAt, updatedAt, ...write } = args
+    const id = submissionId as string
+    const before = await findRecordDoc(ctx, kind, id)
+    const row = await saveRecord(ctx, kind, id, write, { createdAt: createdAt as string, updatedAt: updatedAt as string })
+    if (row['deliveryState'] === 'pending' && before?.data['deliveryState'] !== 'pending') {
+      await scheduleDelivery(ctx, id, 1, 0)
+    }
+    return row
+  },
+})
+
+/** Delete a submission AND the files it claimed (no bytes outlive their row). */
+export const remove = mutation({
+  args: { [kind.idKey]: v.string() },
+  handler: async (ctx, args: Record<string, unknown>) => {
+    await requireCapability(ctx, kind.access.write)
+    const doc = await findRecordDoc(ctx, kind, args[kind.idKey] as string)
+    if (!doc) return
+    await deleteFiles(ctx, (doc.data['files'] as SubmissionFile[] | undefined) ?? [])
+    await ctx.db.delete(doc._id)
+  },
+})
+
+async function deleteFiles(ctx: MutationCtx, files: readonly { storageId: string }[]): Promise<void> {
+  for (const file of files) {
+    const id = file.storageId as GenericId<'_storage'>
+    if (await ctx.db.system.get(id).catch(() => null)) await ctx.storage.delete(id)
+  }
+}
+
+// --- The receiver's handler ------------------------------------------------------------------
+
+let mintSubmissionUuid: (() => string) | undefined
+
+/** The file names a payload field lists (the `./next` helpers send each file's name as the field's value). */
+function fileNames(payload: readonly SubmissionField[], field: string): string[] {
+  const value = payload.find((entry) => entry.name === field)?.value
+  if (typeof value === 'string') return [value]
+  return Array.isArray(value) ? value : []
+}
+
+/** The receiver's `submission` handler (and the `upload`s a submission claims) — see the module header. */
+export const ingest = internalMutation({
+  args: ingestHandlerArgs,
+  handler: async (ctx, { payload, receivedAt }): Promise<IngestHandlerResult> => {
+    const body = parseIngestPayload(payload)
+    if (body.kind === 'upload') return recordIngestUpload(ctx, body, receivedAt, UPLOAD_POLICY)
+    if (body.kind !== 'submission') {
+      return { ok: false, status: 422, message: 'The forms addon takes submissions and their uploads only.' }
+    }
+    const read = readSubmissionPayload(body, { hasFiles: (body.uploads?.length ?? 0) > 0 })
+    if (!read.ok) return { ok: false, status: read.status, message: read.message, issues: read.issues }
+
+    // Claim every upload; on the first refusal, delete what this submission already claimed.
+    const files: SubmissionFile[] = []
+    const namesUsed = new Map<string, number>()
+    for (const claim of body.uploads ?? []) {
+      const claimed = await claimIngestUpload(ctx, claim, body.target, receivedAt)
+      if (!claimed.ok) {
+        await deleteFiles(ctx, files)
+        return claimed
+      }
+      const index = namesUsed.get(claimed.field) ?? 0
+      namesUsed.set(claimed.field, index + 1)
+      const name = fileNames(read.columns.payload, claimed.field)[index]
+      const url = await ctx.storage.getUrl(claimed.storageId as GenericId<'_storage'>)
+      files.push({
+        field: claimed.field,
+        ...(name ? { name } : {}),
+        storageId: claimed.storageId,
+        contentType: claimed.contentType,
+        size: claimed.size,
+        ...(url ? { url } : {}),
+      })
+    }
+
+    // EC-578: the one id factory (UUID v4) — never a clock or a counter.
+    mintSubmissionUuid ??= createUuidIdFactory()
+    const id = `${kind.idPrefix}_${mintSubmissionUuid()}`
+    const spam = read.columns.spam !== 'clean'
+    const deliveryState: DeliveryState = spam ? 'skipped' : 'pending'
+    await saveRecord(
+      ctx,
+      kind,
+      id,
+      {
+        ...read.columns,
+        ...(files.length > 0 ? { files } : {}),
+        status: spam ? 'spam' : 'new',
+        deliveryState,
+        submittedAt: receivedAt,
+      },
+      { createdAt: receivedAt, updatedAt: receivedAt },
+    )
+    if (deliveryState === 'pending') await scheduleDelivery(ctx, id, 1, 0)
+    // A filled honeypot is answered like any other submission: a bot learns nothing.
+    return { ok: true, id }
+  },
+})
+
+// --- Delivery --------------------------------------------------------------------------------
+
+/** What the delivery action reads of a row. */
+export interface DeliveryInput {
+  form: string
+  payload: SubmissionField[]
+  files: { field: string; name?: string; contentType: string; size: number; url: string }[]
+  sourceUrl?: string
+  submittedAt: string
+  deliveryState: DeliveryState
+  delivered: string[]
+}
+
+/** The delivery action's read of one row (internal). */
+export const deliveryInput = internalQuery({
+  args: { submissionId: v.string() },
+  handler: async (ctx, { submissionId }): Promise<DeliveryInput | null> => {
+    const doc = await findRecordDoc(ctx, kind, submissionId)
+    if (!doc) return null
+    const data = doc.data as Record<string, unknown>
+    const files = ((data['files'] as SubmissionFile[] | undefined) ?? []).flatMap((file) =>
+      file.url
+        ? [{ field: file.field, ...(file.name ? { name: file.name } : {}), contentType: file.contentType, size: file.size, url: file.url }]
+        : [],
+    )
+    return {
+      form: data['form'] as string,
+      payload: data['payload'] as SubmissionField[],
+      files,
+      ...(typeof data['sourceUrl'] === 'string' ? { sourceUrl: data['sourceUrl'] } : {}),
+      submittedAt: data['submittedAt'] as string,
+      deliveryState: data['deliveryState'] as DeliveryState,
+      delivered: deliveredRecipients((data['deliveryLog'] as DeliveryEntry[] | undefined) ?? []),
+    }
+  },
+})
+
+/**
+ * One delivery attempt for one row — scheduled by `ingest`, by a retry, and by itself after a
+ * retryable failure. A row that is no longer `pending` (an editor intervened) is left alone.
+ */
+export const deliver = internalActionGeneric({
+  args: { submissionId: v.string(), attempt: v.number() },
+  handler: async (ctx, { submissionId, attempt }) => {
+    const input = await ctx.runQuery(deliveryInputRef, { submissionId })
+    if (!input || input.deliveryState !== 'pending') return { attempted: false as const }
+    const request: FormDeliveryRequest = {
+      kind: 'formDelivery',
+      submissionId,
+      form: input.form,
+      payload: input.payload,
+      files: input.files,
+      ...(input.sourceUrl ? { sourceUrl: input.sourceUrl } : {}),
+      submittedAt: input.submittedAt,
+      attempt,
+      delivered: input.delivered,
+    }
+    const outcome = await attemptFormDelivery({
+      request,
+      url: env(FORMS_DELIVERY_URL_ENV),
+      secret: env('ELYTRA_INGEST_SECRET'),
+    })
+    await ctx.runMutation(recordDeliveryRef, { submissionId, attempt, outcome })
+    return { attempted: true as const, outcome: outcome.kind }
+  },
+})
+
+/** Log one attempt's outcome on its row and schedule the next attempt (internal). */
+export const recordDelivery = internalMutation({
+  args: { submissionId: v.string(), attempt: v.number(), outcome: v.any() },
+  handler: async (ctx, { submissionId, attempt, outcome }) => {
+    const doc = await findRecordDoc(ctx, kind, submissionId)
+    if (!doc || doc.data['deliveryState'] !== 'pending') return
+    const log = (doc.data['deliveryLog'] as DeliveryEntry[] | undefined) ?? []
+    const now = new Date().toISOString()
+    const step = applyDeliveryOutcome(
+      { log, attempt, now, delivered: deliveredRecipients(log) },
+      deliveryOutcomeSchema.parse(outcome),
+    )
+    await saveRecord(
+      ctx,
+      kind,
+      submissionId,
+      { deliveryState: step.deliveryState, deliveryLog: step.deliveryLog },
+      { createdAt: doc.createdAt, updatedAt: now },
+    )
+    if (step.retryInMs !== undefined) await scheduleDelivery(ctx, submissionId, attempt + 1, step.retryInMs)
+  },
+})
+
+// --- Orphaned uploads ------------------------------------------------------------------------
+
+/**
+ * The upload intents past their life that no submission claimed (internal — run it from the
+ * dashboard or `npx convex run forms:unclaimedUploads`). Their bytes cannot be located: Convex
+ * returns a stored file's id to the uploader only (EC-617's documented residue), so they are
+ * listed here, never swept.
+ */
+export const unclaimedUploads = internalQuery({
+  args: {},
+  handler: async (ctx) => {
+    const before = new Date(Date.now() - INGEST_UPLOAD_TTL_MS).toISOString()
+    const rows: RecordWireRow[] = await listRecordWire(
+      ctx,
+      ingestUploadRecordKind,
+      resolveRecordQuery(ingestUploadRecordKind, { where: { state: 'issued' }, before }),
+    )
+    return {
+      count: rows.length,
+      declaredBytes: rows.reduce((sum, row) => sum + Number(row['size'] ?? 0), 0),
+      uploads: rows.map((row) => ({
+        uploadId: String(row[ingestUploadRecordKind.idKey]),
+        form: String(row['target']),
+        field: String(row['field']),
+        issuedAt: String(row['issuedAt']),
+      })),
+    }
+  },
+})

package/src/shared/delivery.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest'
+import {
+  DELIVERY_MAX_ATTEMPTS,
+  applyDeliveryOutcome,
+  attemptFormDelivery,
+  deliveredRecipients,
+  formDeliveryRequestSchema,
+  verifyFormDeliverySignature,
+} from './delivery'
+import type { DeliveryOutcome, FormDeliveryRequest } from './delivery'
+import { FORMS_DELIVERY_SIGNATURE_HEADER } from './delivery'
+import type { DeliveryEntry } from './kind'
+
+/** EC-613 — the delivery state machine (pure) and the deployment's one attempt (injected transport). */
+
+const NOW = '2026-10-26T12:00:00.000Z'
+const step = (outcome: DeliveryOutcome, attempt = 1, log: DeliveryEntry[] = []) =>
+  applyDeliveryOutcome({ log, attempt, now: NOW, delivered: deliveredRecipients(log) }, outcome)
+
+describe('applyDeliveryOutcome', () => {
+  it('every recipient reached → sent, one log line each, nothing scheduled', () => {
+    const result = step({ kind: 'results', results: [{ to: 'a@x.test', ok: true, id: 'm1' }, { to: 'b@x.test', ok: true }] })
+    expect(result).toEqual({
+      deliveryState: 'sent',
+      deliveryLog: [
+        { at: NOW, attempt: 1, to: 'a@x.test', ok: true, id: 'm1' },
+        { at: NOW, attempt: 1, to: 'b@x.test', ok: true },
+      ],
+    })
+  })
+
+  it('a failed recipient is retried after the backoff; the one reached is never re-sent', () => {
+    const first = step({ kind: 'results', results: [{ to: 'a@x.test', ok: true }, { to: 'b@x.test', ok: false, error: 'mailbox full' }] })
+    expect(first.deliveryState).toBe('pending')
+    expect(first.retryInMs).toBe(60_000)
+    expect(first.deliveryLog[1]).toMatchObject({ to: 'b@x.test', ok: false, error: 'mailbox full', retryAt: '2026-10-26T12:01:00.000Z' })
+    expect(deliveredRecipients(first.deliveryLog)).toEqual(['a@x.test'])
+    // Attempt 2 reaches b — the row is sent.
+    const second = step({ kind: 'results', results: [{ to: 'b@x.test', ok: true }] }, 2, first.deliveryLog)
+    expect(second.deliveryState).toBe('sent')
+  })
+
+  it('the last attempt ends the run: partial when someone was reached, failed when nobody was', () => {
+    const partialLog: DeliveryEntry[] = [{ at: NOW, attempt: 1, to: 'a@x.test', ok: true }]
+    const failedRecipient: DeliveryOutcome = { kind: 'results', results: [{ to: 'b@x.test', ok: false, error: 'refused' }] }
+    expect(step(failedRecipient, DELIVERY_MAX_ATTEMPTS, partialLog)).toMatchObject({ deliveryState: 'partial' })
+    expect(step(failedRecipient, DELIVERY_MAX_ATTEMPTS)).toMatchObject({ deliveryState: 'failed' })
+    expect(step(failedRecipient, DELIVERY_MAX_ATTEMPTS).retryInMs).toBeUndefined()
+  })
+
+  it('an unreachable site and a 5xx/429 are retried; a 4xx and an unset route fail at once', () => {
+    expect(step({ kind: 'unreachable', message: 'ECONNREFUSED' })).toMatchObject({ deliveryState: 'pending', retryInMs: 60_000 })
+    expect(step({ kind: 'refused', status: 503, message: 'down' }, 2)).toMatchObject({ deliveryState: 'pending', retryInMs: 600_000 })
+    expect(step({ kind: 'refused', status: 429, message: 'slow down' })).toMatchObject({ deliveryState: 'pending' })
+    expect(step({ kind: 'refused', status: 404, message: 'No form “x”.' })).toEqual({
+      deliveryState: 'failed',
+      deliveryLog: [{ at: NOW, attempt: 1, ok: false, error: 'HTTP 404: No form “x”.' }],
+    })
+    expect(step({ kind: 'unconfigured', message: 'ELYTRA_FORMS_DELIVERY_URL is not set' })).toMatchObject({ deliveryState: 'failed' })
+  })
+
+  it('a form with no recipients is skipped (an inbox-only form), with a note', () => {
+    expect(step({ kind: 'results', results: [] })).toEqual({
+      deliveryState: 'skipped',
+      deliveryLog: [{ at: NOW, attempt: 1, ok: true, note: 'no recipients' }],
+    })
+  })
+})
+
+describe('attemptFormDelivery — the deployment’s request to the site', () => {
+  const request: FormDeliveryRequest = {
+    kind: 'formDelivery',
+    submissionId: 'submission_1',
+    form: 'contact',
+    payload: [{ name: 'email', value: 'ada@example.test' }],
+    files: [],
+    submittedAt: NOW,
+    attempt: 1,
+    delivered: [],
+  }
+
+  it('signs the request with the ingest secret; the site verifies it (control: another secret does not)', async () => {
+    let seen: { body: string; signature: string | null } | undefined
+    const fetchImpl = (async (_url: string, init: RequestInit) => {
+      seen = { body: String(init.body), signature: new Headers(init.headers).get(FORMS_DELIVERY_SIGNATURE_HEADER) }
+      return Response.json({ results: [{ to: 'shop@example.test', ok: true }] })
+    }) as unknown as typeof fetch
+    const outcome = await attemptFormDelivery({ request, url: 'https://site.test/api/forms', secret: 's3cret', fetchImpl })
+    expect(outcome).toEqual({ kind: 'results', results: [{ to: 'shop@example.test', ok: true }] })
+    expect(formDeliveryRequestSchema.parse(JSON.parse(seen!.body))).toEqual(request)
+    expect(await verifyFormDeliverySignature(seen!.body, seen!.signature, 's3cret')).toBe(true)
+    expect(await verifyFormDeliverySignature(seen!.body, seen!.signature, 'other')).toBe(false)
+  })
+
+  it('unset route or secret → unconfigured, and nothing is sent', async () => {
+    let calls = 0
+    const fetchImpl = (async () => {
+      calls += 1
+      return Response.json({ results: [] })
+    }) as unknown as typeof fetch
+    expect((await attemptFormDelivery({ request, url: undefined, secret: 's', fetchImpl })).kind).toBe('unconfigured')
+    expect((await attemptFormDelivery({ request, url: 'https://site.test', secret: undefined, fetchImpl })).kind).toBe('unconfigured')
+    expect(calls).toBe(0)
+  })
+
+  it('maps the site’s answers: 401 names the secret pair, 4xx keeps its error, a bad 200 body and a network error are failures', async () => {
+    const answer = (response: Response | Error) =>
+      (async () => {
+        if (response instanceof Error) throw response
+        return response
+      }) as unknown as typeof fetch
+    const attempt = (fetchImpl: typeof fetch) => attemptFormDelivery({ request, url: 'https://site.test', secret: 's', fetchImpl })
+    expect(await attempt(answer(new Response('', { status: 401 })))).toMatchObject({ kind: 'refused', status: 401, message: expect.stringMatching(/INGEST_SECRET/) })
+    expect(await attempt(answer(Response.json({ error: 'No form “contact”.' }, { status: 404 })))).toEqual({
+      kind: 'refused',
+      status: 404,
+      message: 'No form “contact”.',
+    })
+    expect(await attempt(answer(Response.json({ nope: true })))).toMatchObject({ kind: 'refused', status: 502 })
+    expect(await attempt(answer(new Error('ECONNREFUSED')))).toMatchObject({ kind: 'unreachable', message: expect.stringMatching(/ECONNREFUSED/) })
+  })
+})