@kelpie/server 0.1.0

package/src/modules/webhooks/repository.ts

@@ -0,0 +1,244 @@
+import type { WebhookDeliveryStatus, WebhookEvent, WebhookStatus } from '@kelpie/schemas'
+import { and, arrayContains, desc, eq, inArray, lt, ne } from 'drizzle-orm'
+import type { SQL } from 'drizzle-orm'
+
+import { keysetCondition, orderByWindow, timestampSort } from '../../lib/pagination.ts'
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import { webhookDeliveries, webhooks } from './schema.ts'
+
+export type WebhookRecord = typeof webhooks.$inferSelect
+export type WebhookColumns = typeof webhooks.$inferInsert
+export type DeliveryRecord = typeof webhookDeliveries.$inferSelect
+export type DeliveryColumns = typeof webhookDeliveries.$inferInsert
+
+export const WEBHOOK_SORTS: SortableFields<WebhookRecord> = {
+  created_at: timestampSort(webhooks.createdAt, (webhook) => webhook.createdAt),
+  updated_at: timestampSort(webhooks.updatedAt, (webhook) => webhook.updatedAt),
+}
+
+export const DEFAULT_WEBHOOK_SORT = '-created_at'
+
+export const DELIVERY_SORTS: SortableFields<DeliveryRecord> = {
+  created_at: timestampSort(webhookDeliveries.createdAt, (delivery) => delivery.createdAt),
+}
+
+/** Newest first: a delivery log is read to find out what just happened. */
+export const DEFAULT_DELIVERY_SORT = '-created_at'
+
+export interface WebhookFilters {
+  readonly status?: WebhookStatus | undefined
+}
+
+export interface DeliveryFilters {
+  readonly status?: WebhookDeliveryStatus | undefined
+}
+
+/** The last settled delivery for one webhook, as the list view reports it. */
+export interface LastDelivery {
+  readonly at: Date
+  readonly status: WebhookDeliveryStatus
+}
+
+function conditionsFor(workspaceId: string, filters: WebhookFilters): (SQL | undefined)[] {
+  return [
+    eq(webhooks.workspaceId, workspaceId),
+    filters.status === undefined ? undefined : eq(webhooks.status, filters.status),
+  ]
+}
+
+export function listWebhooks(
+  db: Queryable,
+  workspaceId: string,
+  filters: WebhookFilters,
+  window: ListWindow<WebhookRecord>,
+): Promise<WebhookRecord[]> {
+  return db
+    .select()
+    .from(webhooks)
+    .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, webhooks.id)))
+    .orderBy(...orderByWindow(window, webhooks.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findWebhook(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<WebhookRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(webhooks)
+    .where(and(eq(webhooks.workspaceId, workspaceId), eq(webhooks.id, id)))
+    .limit(1)
+
+  return found
+}
+
+/**
+ * The registrations one event should reach.
+ *
+ * `paused` is excluded and `failing` is not: pausing is the customer saying
+ * stop, while failing is a report on the endpoint. A failing webhook keeps
+ * being tried, which is the only way it can return to `active` by itself.
+ */
+export function listSubscribed(
+  db: Queryable,
+  workspaceId: string,
+  event: WebhookEvent,
+): Promise<WebhookRecord[]> {
+  return db
+    .select()
+    .from(webhooks)
+    .where(
+      and(
+        eq(webhooks.workspaceId, workspaceId),
+        ne(webhooks.status, 'paused'),
+        arrayContains(webhooks.events, [event]),
+      ),
+    )
+}
+
+/**
+ * The most recent settled delivery per webhook, for the `last_delivery_*` fields.
+ *
+ * Derived rather than stored. `schema.md` gives `webhooks` no delivery columns,
+ * and a denormalised copy of the log's newest row is a second source of truth
+ * that can only ever drift from it.
+ *
+ * @param webhookIds At most one page of ids, so the `in` list is bounded by the
+ *   same ceiling `?limit=` is.
+ */
+export async function findLastDeliveries(
+  db: Queryable,
+  webhookIds: readonly string[],
+): Promise<ReadonlyMap<string, LastDelivery>> {
+  if (webhookIds.length === 0) {
+    return new Map()
+  }
+
+  const rows = await db
+    .selectDistinctOn([webhookDeliveries.webhookId], {
+      webhookId: webhookDeliveries.webhookId,
+      createdAt: webhookDeliveries.createdAt,
+      status: webhookDeliveries.status,
+    })
+    .from(webhookDeliveries)
+    .where(inArray(webhookDeliveries.webhookId, [...webhookIds]))
+    // The id breaks a tie: several deliveries of one event land in the same
+    // millisecond, and ULIDs order by creation within one.
+    .orderBy(webhookDeliveries.webhookId, desc(webhookDeliveries.createdAt), desc(webhookDeliveries.id))
+
+  return new Map(rows.map((row) => [row.webhookId, { at: row.createdAt, status: row.status }]))
+}
+
+export async function insertWebhook(db: Queryable, values: WebhookColumns): Promise<WebhookRecord> {
+  const [created] = await db.insert(webhooks).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting webhook ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateWebhook(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<WebhookColumns>,
+): Promise<WebhookRecord | undefined> {
+  const [updated] = await db
+    .update(webhooks)
+    .set(changes)
+    .where(and(eq(webhooks.workspaceId, workspaceId), eq(webhooks.id, id)))
+    .returning()
+
+  return updated
+}
+
+/**
+ * Moves a webhook between `active` and `failing` after a delivery settles.
+ *
+ * Deliberately does not touch `updated_at`. That column answers "when did
+ * somebody last change this registration", and a customer compares it against
+ * `last_delivery_at` to see whether their fix took effect. The engine moving it
+ * would destroy that comparison.
+ */
+export async function setWebhookStatus(
+  db: Queryable,
+  id: string,
+  status: WebhookStatus,
+): Promise<void> {
+  await db.update(webhooks).set({ status }).where(eq(webhooks.id, id))
+}
+
+export async function deleteWebhook(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(webhooks)
+    .where(and(eq(webhooks.workspaceId, workspaceId), eq(webhooks.id, id)))
+    .returning({ id: webhooks.id })
+
+  return deleted.length
+}
+
+export async function insertDelivery(
+  db: Queryable,
+  values: DeliveryColumns,
+): Promise<DeliveryRecord> {
+  const [created] = await db.insert(webhookDeliveries).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting webhook delivery ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+/**
+ * Deletes this webhook's log rows older than the cutoff.
+ *
+ * Scoped to one webhook rather than the workspace so the delete walks
+ * `webhook_deliveries_webhook_idx` — the workspace column has no index here,
+ * and the engine calls this on every recorded delivery.
+ *
+ * @returns How many rows went, for the engine's log line.
+ */
+export async function deleteExpiredDeliveries(
+  db: Queryable,
+  webhookId: string,
+  before: Date,
+): Promise<number> {
+  const deleted = await db
+    .delete(webhookDeliveries)
+    .where(and(eq(webhookDeliveries.webhookId, webhookId), lt(webhookDeliveries.createdAt, before)))
+    .returning({ id: webhookDeliveries.id })
+
+  return deleted.length
+}
+
+export function listDeliveries(
+  db: Queryable,
+  workspaceId: string,
+  webhookId: string,
+  filters: DeliveryFilters,
+  window: ListWindow<DeliveryRecord>,
+): Promise<DeliveryRecord[]> {
+  return db
+    .select()
+    .from(webhookDeliveries)
+    .where(
+      and(
+        eq(webhookDeliveries.workspaceId, workspaceId),
+        eq(webhookDeliveries.webhookId, webhookId),
+        filters.status === undefined ? undefined : eq(webhookDeliveries.status, filters.status),
+        keysetCondition(window, webhookDeliveries.id),
+      ),
+    )
+    .orderBy(...orderByWindow(window, webhookDeliveries.id))
+    .limit(window.fetchLimit)
+}

package/src/modules/webhooks/routes.ts

@@ -0,0 +1,240 @@
+import {
+  WEBHOOK_DELIVERY_STATUSES,
+  WEBHOOK_EVENTS,
+  WEBHOOK_SETTABLE_STATUSES,
+  WEBHOOK_STATUSES,
+} from '@kelpie/schemas'
+import type { WebhookDeliveryStatus, WebhookStatus } from '@kelpie/schemas'
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { AppError, toErrorDetails } from '../../lib/errors.ts'
+import { pageBody, readJsonBody, readListParameters } from '../../lib/http.ts'
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import type { CreatedWebhookView, DeliveryView, WebhooksService, WebhookView } from './service.ts'
+import { urlProblem } from './url.ts'
+
+/**
+ * Wire shapes for `/v1/webhooks`.
+ *
+ * Bodies are strict: `api.md` makes an unknown field a 422 rather than
+ * something dropped in silence.
+ */
+
+const urlField = z.string().refine((value) => urlProblem(value) === undefined, {
+  error: (issue) => urlProblem(String(issue.input))?.message ?? 'Invalid URL',
+})
+
+/**
+ * At least one event, and no repeats.
+ *
+ * A registration subscribed to nothing is a row that can never fire, and a
+ * repeated name would deliver the same event twice to the same endpoint. Both
+ * are almost certainly a mistake in the caller rather than an intent.
+ */
+const eventsField = z
+  .array(z.enum(WEBHOOK_EVENTS))
+  .min(1, { error: 'Subscribe to at least one event' })
+  .refine((events) => new Set(events).size === events.length, {
+    error: 'Each event may be listed once',
+  })
+
+export const createBody = z.strictObject({
+  url: urlField,
+  events: eventsField,
+})
+
+/**
+ * `status` takes `active` and `paused` only. `failing` is what the delivery
+ * engine reports about the endpoint, so accepting it here would let a caller
+ * assert something only a delivery attempt can establish.
+ */
+export const updateBody = z
+  .strictObject({
+    url: urlField,
+    events: eventsField,
+    status: z.enum(WEBHOOK_SETTABLE_STATUSES),
+  })
+  .partial()
+
+/**
+ * Rotation takes no fields in the common case, so the body is optional and
+ * `overlap` defaults to off. Strict like every other body: a misspelled field
+ * is a `422` rather than a rotation that silently took effect at once.
+ */
+export const rotateBody = z.strictObject({ overlap: z.boolean().optional() })
+
+export interface WebhooksRoutesDependencies extends CredentialDependencies {
+  readonly service: WebhooksService
+}
+
+/**
+ * Reads a body that may be absent entirely.
+ *
+ * `POST …/rotate_secret` with nothing in it is the ordinary request, and
+ * `readJsonBody` answers `400` for an empty body. Local to this module rather
+ * than in `lib/http.ts` because it has one caller; it moves there when a second
+ * endpoint wants it.
+ */
+async function readOptionalJsonBody<T>(context: Context, schema: z.ZodType<T>): Promise<T> {
+  const text = await context.req.text()
+  let raw: unknown = {}
+
+  if (text.trim().length > 0) {
+    try {
+      raw = JSON.parse(text)
+    } catch {
+      throw new AppError('bad_request', 'Body must be valid JSON')
+    }
+  }
+
+  const parsed = schema.safeParse(raw)
+
+  if (!parsed.success) {
+    throw AppError.validationFailed('Request body is invalid', toErrorDetails(parsed.error.issues))
+  }
+
+  return parsed.data
+}
+
+export function webhookResponse(webhook: WebhookView): Record<string, unknown> {
+  return {
+    id: webhook.id,
+    url: webhook.url,
+    events: webhook.events,
+    secret_prefix: webhook.secretPrefix,
+    status: webhook.status,
+    last_delivery_at: webhook.lastDeliveryAt === null ? null : webhook.lastDeliveryAt.toISOString(),
+    last_delivery_status: webhook.lastDeliveryStatus,
+    created_at: webhook.createdAt.toISOString(),
+    updated_at: webhook.updatedAt.toISOString(),
+  }
+}
+
+export function createdWebhookResponse(webhook: CreatedWebhookView): Record<string, unknown> {
+  return { ...webhookResponse(webhook), secret: webhook.secret }
+}
+
+export function deliveryResponse(delivery: DeliveryView): Record<string, unknown> {
+  return {
+    id: delivery.id,
+    webhook_id: delivery.webhookId,
+    event: delivery.event,
+    payload: delivery.payload,
+    status: delivery.status,
+    attempts: delivery.attempts,
+    delivered_at: delivery.deliveredAt === null ? null : delivery.deliveredAt.toISOString(),
+    created_at: delivery.createdAt.toISOString(),
+  }
+}
+
+/**
+ * Reads a `?status=` filter against a fixed list.
+ *
+ * @throws AppError 422 for a value that is not a status. Answering it with an
+ *   empty list would read as "none in that state" rather than "no such state".
+ */
+function readStatusFilter<Status extends string>(
+  context: Context,
+  statuses: readonly [Status, ...Status[]],
+): Status | undefined {
+  const raw = context.req.query('status')
+
+  if (raw === undefined) {
+    return undefined
+  }
+
+  const parsed = z.enum(statuses).safeParse(raw)
+
+  if (!parsed.success) {
+    throw AppError.validationFailed('That is not a status', [
+      { field: 'status', message: `Use one of: ${statuses.join(', ')}` },
+    ])
+  }
+
+  return parsed.data
+}
+
+export function mountWebhooksRoutes(router: Hono, dependencies: WebhooksRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/webhooks', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      { status: readStatusFilter<WebhookStatus>(context, WEBHOOK_STATUSES) },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, webhookResponse))
+  })
+
+  /** The response carries `secret`. No later request can retrieve it. */
+  router.post('/webhooks', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const webhook = await dependencies.service.create(await requireActor(context), {
+      url: body.url,
+      events: body.events,
+    })
+
+    return context.json(createdWebhookResponse(webhook), 201)
+  })
+
+  router.get('/webhooks/:id', async (context) => {
+    const webhook = await dependencies.service.get(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(webhookResponse(webhook))
+  })
+
+  router.patch('/webhooks/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const webhook = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      body,
+    )
+
+    return context.json(webhookResponse(webhook))
+  })
+
+  /**
+   * Replaces the signing secret, answering with the new one exactly once. Same
+   * contract `POST /v1/webhooks` has, and the registration keeps its id, its
+   * subscriptions and its delivery log.
+   */
+  router.post('/webhooks/:id/rotate_secret', async (context) => {
+    const body = await readOptionalJsonBody(context, rotateBody)
+    const webhook = await dependencies.service.rotateSecret(
+      await requireActor(context),
+      context.req.param('id'),
+      { overlap: body.overlap ?? false },
+    )
+
+    return context.json(createdWebhookResponse(webhook))
+  })
+
+  router.delete('/webhooks/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+
+  /**
+   * The delivery log for one webhook. Nested, like a form's submissions: a
+   * delivery only means anything against the registration that produced it.
+   */
+  router.get('/webhooks/:id/deliveries', async (context) => {
+    const page = await dependencies.service.listDeliveries(
+      await requireActor(context),
+      context.req.param('id'),
+      { status: readStatusFilter<WebhookDeliveryStatus>(context, WEBHOOK_DELIVERY_STATUSES) },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, deliveryResponse))
+  })
+}

package/src/modules/webhooks/schema.ts

@@ -0,0 +1,78 @@
+import {
+  WEBHOOK_DELIVERY_STATUSES,
+  WEBHOOK_EVENTS,
+  WEBHOOK_STATUSES,
+} from '@kelpie/schemas'
+import type { WebhookDeliveryStatus, WebhookEvent, WebhookStatus } from '@kelpie/schemas'
+import { index, integer, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
+
+import { checkOneOf, createdAt, moment, primaryId, updatedAt } from '../../lib/columns.ts'
+import { workspaces } from '../workspace/schema.ts'
+
+export { WEBHOOK_DELIVERY_STATUSES, WEBHOOK_EVENTS, WEBHOOK_STATUSES }
+export type { WebhookDeliveryStatus, WebhookEvent, WebhookStatus }
+
+/** Outbound HTTP deliveries driven by the internal event bus. */
+export const webhooks = pgTable(
+  'webhooks',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    url: text('url').notNull(),
+    events: text('events').array().$type<WebhookEvent[]>().notNull().default([]),
+    /**
+     * The signing secret, sealed by `lib/secrets.ts`.
+     *
+     * Not a hash, unlike every other secret in the schema, because `api.md`
+     * signs each delivery *with* this secret and the receiver holds the
+     * plaintext we showed them once. A hash could never produce a signature
+     * anything off the shelf can verify.
+     */
+    secretEncrypted: text('secret_encrypted').notNull(),
+    secretPrefix: text('secret_prefix').notNull(),
+    /**
+     * The secret this one replaced, kept only while a rotation overlaps.
+     *
+     * Set when a customer rotates and asks for an overlap window, so a delivery
+     * carries a signature under both secrets and an endpoint that has not been
+     * redeployed yet still verifies. Null the rest of the time, which is every
+     * webhook that has never rotated and every rotation taken immediately.
+     */
+    previousSecretEncrypted: text('previous_secret_encrypted'),
+    /** When the value above stops being signed with. Null together with it. */
+    previousSecretExpiresAt: moment('previous_secret_expires_at'),
+    status: text('status').$type<WebhookStatus>().notNull().default('active'),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    index('webhooks_workspace_idx').on(table.workspaceId),
+    checkOneOf('webhooks_status_check', table.status, WEBHOOK_STATUSES),
+  ],
+)
+
+/** Append-only delivery log, pruned by retention rather than updated. */
+export const webhookDeliveries = pgTable(
+  'webhook_deliveries',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    webhookId: text('webhook_id')
+      .notNull()
+      .references(() => webhooks.id, { onDelete: 'cascade' }),
+    event: text('event').$type<WebhookEvent>().notNull(),
+    payload: jsonb('payload').$type<Record<string, unknown>>().notNull(),
+    status: text('status').$type<WebhookDeliveryStatus>().notNull(),
+    attempts: integer('attempts').notNull().default(0),
+    deliveredAt: moment('delivered_at'),
+    createdAt: createdAt(),
+  },
+  (table) => [
+    index('webhook_deliveries_webhook_idx').on(table.webhookId),
+    checkOneOf('webhook_deliveries_status_check', table.status, WEBHOOK_DELIVERY_STATUSES),
+  ],
+)