@sixb/core 0.1.1 → 0.1.3

package/src/testing/sync-execution.ts

@@ -0,0 +1,61 @@
+import type { TrustedPrimitiveRef } from "../execution"
+import type { QueueSyncRunInput, Storage, SyncRunRecord } from "../storage"
+import type { ExecutionStorage } from "../storage/executions"
+
+/** Create the durable execution required by a Sync-run storage fixture. */
+export async function createTestSyncExecution(
+  executions: ExecutionStorage,
+  input: {
+    readonly projectId: string
+    readonly syncId: string
+    readonly runId: string
+    readonly executionId?: string
+  }
+): Promise<string> {
+  const executionId = input.executionId ?? `test_sync_execution:${input.runId}`
+  const existing = await executions.getById({ projectId: input.projectId, id: executionId })
+  if (existing) return executionId
+
+  const primitive: TrustedPrimitiveRef = {
+    kind: "sync",
+    id: input.syncId,
+    runId: input.runId,
+  }
+  await executions.create({
+    id: executionId,
+    projectId: input.projectId,
+    executor: { type: "primitive", kind: primitive.kind, runId: primitive.runId },
+    source: { type: "event", eventId: `test_event:${input.runId}` },
+    correlationId: `test_correlation:${input.runId}`,
+    authorizationRef: { type: "trustedPrimitive", primitive },
+  })
+  return executionId
+}
+
+/** Queue a Sync run with the valid durable execution fixture required by every provider. */
+export async function queueTestSyncRun(
+  storage: Pick<Storage, "syncRuns" | "executions">,
+  input: Omit<QueueSyncRunInput, "executionId">
+): Promise<SyncRunRecord> {
+  if (!storage.syncRuns) throw new Error("Sync run storage is not configured for this test.")
+  const executionId = await createTestSyncExecution(storage.executions, {
+    projectId: input.projectId,
+    syncId: input.syncId,
+    runId: input.id,
+  })
+  return storage.syncRuns.queue({ ...input, executionId })
+}
+
+/** Start a Sync run after creating its durable execution and queued state. */
+export async function startTestSyncRun(
+  storage: Pick<Storage, "syncRuns" | "executions">,
+  input: Omit<QueueSyncRunInput, "executionId" | "queuedAt"> & { readonly startedAt?: Date }
+): Promise<SyncRunRecord> {
+  const { startedAt, ...queuedRun } = input
+  await queueTestSyncRun(storage, { ...queuedRun, queuedAt: startedAt })
+  return storage.syncRuns!.start({
+    id: input.id,
+    projectId: input.projectId,
+    startedAt,
+  })
+}

package/src/testing/webhook-execution.ts

@@ -0,0 +1,47 @@
+import type { TrustedPrimitiveRef } from "../execution"
+import type { StartWebhookRunInput, Storage, WebhookRunRecord } from "../storage"
+import type { ExecutionStorage } from "../storage/executions"
+
+/** Create the durable execution required by a Webhook-run storage fixture. */
+export async function createTestWebhookExecution(
+  executions: ExecutionStorage,
+  input: {
+    readonly projectId: string
+    readonly route: string
+    readonly runId: string
+    readonly executionId?: string
+  }
+): Promise<string> {
+  const executionId = input.executionId ?? `test_webhook_execution:${input.runId}`
+  const existing = await executions.getById({ projectId: input.projectId, id: executionId })
+  if (existing) return executionId
+
+  const primitive: TrustedPrimitiveRef = {
+    kind: "webhook",
+    id: input.route,
+    runId: input.runId,
+  }
+  await executions.create({
+    id: executionId,
+    projectId: input.projectId,
+    executor: { type: "primitive", kind: primitive.kind, runId: primitive.runId },
+    source: { type: "webhook", deliveryId: input.runId },
+    correlationId: `test_correlation:${input.runId}`,
+    authorizationRef: { type: "trustedPrimitive", primitive },
+  })
+  return executionId
+}
+
+/** Start a Webhook run with the valid durable execution fixture required by every provider. */
+export async function startTestWebhookRun(
+  storage: Pick<Storage, "webhookRuns" | "executions">,
+  input: Omit<StartWebhookRunInput, "executionId">
+): Promise<WebhookRunRecord> {
+  if (!storage.webhookRuns) throw new Error("Webhook run storage is not configured for this test.")
+  const executionId = await createTestWebhookExecution(storage.executions, {
+    projectId: input.projectId,
+    route: input.route,
+    runId: input.id,
+  })
+  return storage.webhookRuns.start({ ...input, executionId })
+}

package/src/testing/webhook-run-storage-contract.ts

@@ -0,0 +1,240 @@
+import { describe, expect, test } from "bun:test"
+import type { SixbFailure } from "../errors/types"
+import type { CreateExecutionInput, Storage } from "../storage"
+import type { WebhookRunFailureCode } from "../storage/webhook-runs"
+import { startTestWebhookRun } from "./webhook-execution"
+
+export type WebhookRunStorageContractStorage = Storage & {
+  readonly webhookRuns: NonNullable<Storage["webhookRuns"]>
+}
+
+export interface WebhookRunStorageContractSuiteOptions<
+  TStorage extends WebhookRunStorageContractStorage = WebhookRunStorageContractStorage,
+> {
+  readonly createStorage: () => TStorage | Promise<TStorage>
+  readonly cleanup?: (storage: TStorage) => void | Promise<void>
+}
+
+const projectId = "webhook-contract"
+const route = "/api/webhooks/github/events"
+const bodySha256 = "0".repeat(64)
+const finishedAt = new Date("2026-06-01T12:01:00.000Z")
+const retryableFailure = {
+  code: "webhook.delivery_failed",
+  message: "Webhook delivery failed.",
+  retryable: true,
+  at: finishedAt.toISOString(),
+  details: { connectorId: "github", webhookId: "events", runId: "delivery-retry" },
+} as const satisfies SixbFailure<WebhookRunFailureCode>
+const rejectedFailure = {
+  code: "webhook.delivery_rejected",
+  message: "Webhook delivery was rejected.",
+  retryable: false,
+  at: finishedAt.toISOString(),
+} as const satisfies SixbFailure<WebhookRunFailureCode>
+
+/** Runs the durable Webhook delivery contract against one complete storage provider. */
+export function runWebhookRunStorageContractSuite<
+  TStorage extends WebhookRunStorageContractStorage,
+>(label: string, options: WebhookRunStorageContractSuiteOptions<TStorage>): void {
+  const withStorage = async (body: (storage: TStorage) => Promise<void>): Promise<void> => {
+    const storage = await options.createStorage()
+    try {
+      await body(storage)
+    } finally {
+      await options.cleanup?.(storage)
+    }
+  }
+
+  describe(label, () => {
+    test("round-trips the immutable execution and delivery identity", async () => {
+      await withStorage(async (storage) => {
+        const run = await startTestWebhookRun(storage, runInput("delivery-1", "provider-1"))
+        expect(run).toMatchObject({
+          id: "delivery-1",
+          projectId,
+          executionId: "test_webhook_execution:delivery-1",
+          connectorId: "github",
+          webhookId: "events",
+          status: "running",
+          route,
+          requestBodyBytes: 12,
+          requestBodySha256: bodySha256,
+          idempotencyKey: "provider-1",
+        })
+        await expect(
+          storage.webhookRuns.getByDelivery({
+            projectId,
+            connectorId: "github",
+            webhookId: "events",
+            idempotencyKey: "provider-1",
+          })
+        ).resolves.toEqual(run)
+      })
+    })
+
+    test("rejects missing or mismatched execution authority", async () => {
+      await withStorage(async (storage) => {
+        const missing = runInput("missing-execution")
+        await expect(
+          storage.webhookRuns.start({ ...missing, executionId: "missing" })
+        ).rejects.toMatchObject({ code: "invalid_execution" })
+
+        await storage.executions.create(disabledRequestExecution("wrong-execution"))
+        await expect(
+          storage.webhookRuns.start({ ...missing, executionId: "wrong-execution" })
+        ).rejects.toMatchObject({ code: "invalid_execution" })
+      })
+    })
+
+    test("enforces one run per provider delivery key", async () => {
+      await withStorage(async (storage) => {
+        await startTestWebhookRun(storage, runInput("delivery-first", "provider-shared"))
+        await expect(
+          startTestWebhookRun(storage, runInput("delivery-second", "provider-shared"))
+        ).rejects.toMatchObject({ code: "duplicate_run" })
+      })
+    })
+
+    test("restarts only retryable failures without changing execution identity", async () => {
+      await withStorage(async (storage) => {
+        const started = await startTestWebhookRun(
+          storage,
+          runInput("delivery-retry", "provider-retry")
+        )
+        await storage.webhookRuns.finish({
+          projectId,
+          id: started.id,
+          status: "failed",
+          finishedAt,
+          responseStatus: 503,
+          error: retryableFailure,
+        })
+        const restarted = await storage.webhookRuns.restart({ projectId, id: started.id })
+        expect(restarted).toMatchObject({
+          id: started.id,
+          executionId: started.executionId,
+          status: "running",
+        })
+        expect(restarted.finishedAt).toBeUndefined()
+        expect(restarted.responseStatus).toBeUndefined()
+        expect(restarted.error).toBeUndefined()
+
+        await storage.webhookRuns.finish({
+          projectId,
+          id: started.id,
+          status: "succeeded",
+          responseStatus: 202,
+        })
+        await expect(
+          storage.webhookRuns.restart({ projectId, id: started.id })
+        ).rejects.toMatchObject({ code: "invalid_transition" })
+      })
+    })
+
+    test("does not reopen a terminal client rejection", async () => {
+      await withStorage(async (storage) => {
+        const run = await startTestWebhookRun(storage, runInput("delivery-rejected"))
+        await storage.webhookRuns.finish({
+          projectId,
+          id: run.id,
+          status: "failed",
+          finishedAt,
+          responseStatus: 422,
+          error: rejectedFailure,
+        })
+        await expect(storage.webhookRuns.restart({ projectId, id: run.id })).rejects.toMatchObject({
+          code: "invalid_transition",
+        })
+      })
+    })
+
+    test("persists a validated, detached failure through get and list", async () => {
+      await withStorage(async (storage) => {
+        const run = await startTestWebhookRun(storage, runInput("failed-run", "failed-key"))
+        const failedRunFailure = {
+          ...retryableFailure,
+          details: { ...retryableFailure.details, runId: run.id },
+        }
+        const mutableFailure = {
+          code: "webhook.delivery_failed" as const,
+          message: String(failedRunFailure.message),
+          retryable: true as const,
+          at: failedRunFailure.at,
+          details: {
+            connectorId: String(failedRunFailure.details.connectorId),
+            webhookId: String(failedRunFailure.details.webhookId),
+            runId: String(failedRunFailure.details.runId),
+          },
+        }
+        const finished = await storage.webhookRuns.finish({
+          projectId,
+          id: run.id,
+          status: "failed",
+          finishedAt,
+          responseStatus: 503,
+          error: mutableFailure,
+        })
+
+        mutableFailure.details.runId = "mutated-after-write"
+        expect(finished.error).toEqual(failedRunFailure)
+        await expect(storage.webhookRuns.getById({ projectId, id: run.id })).resolves.toMatchObject(
+          {
+            error: failedRunFailure,
+          }
+        )
+        await expect(
+          storage.webhookRuns.list({
+            projectId,
+            statuses: ["failed"],
+            idempotencyKey: "failed-key",
+          })
+        ).resolves.toMatchObject({ runs: [{ id: run.id, error: failedRunFailure }], total: 1 })
+      })
+    })
+
+    test("rejects failures outside the Webhook run contract without finishing", async () => {
+      await withStorage(async (storage) => {
+        const run = await startTestWebhookRun(storage, runInput("invalid-failure"))
+        await expect(
+          storage.webhookRuns.finish({
+            projectId,
+            id: run.id,
+            status: "failed",
+            finishedAt,
+            error: { ...retryableFailure, code: "runtime.cancelled" } as never,
+          })
+        ).rejects.toThrow("code is not allowed by this failure contract")
+        const unchanged = await storage.webhookRuns.getById({ projectId, id: run.id })
+        expect(unchanged?.status).toBe("running")
+        expect(unchanged?.error).toBeUndefined()
+      })
+    })
+  })
+}
+
+function runInput(id: string, idempotencyKey?: string) {
+  return {
+    id,
+    projectId,
+    connectorId: "github",
+    webhookId: "events",
+    method: "POST",
+    route,
+    requestBodyBytes: 12,
+    requestBodySha256: bodySha256,
+    ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+    startedAt: new Date("2026-06-01T12:00:00.000Z"),
+  }
+}
+
+function disabledRequestExecution(id: string): CreateExecutionInput {
+  return {
+    id,
+    projectId,
+    executor: { type: "request", requestId: id },
+    source: { type: "http", requestId: id },
+    correlationId: `correlation:${id}`,
+    authorizationRef: { type: "disabled" },
+  }
+}

package/src/testing/workflow-execution.ts

@@ -0,0 +1,77 @@
+import type { AuthorizablePrincipal, TrustedPrimitiveRef } from "../execution"
+import type { ExecutionStorage } from "../storage/executions"
+
+/** Create the durable execution chain required by a workflow-run storage fixture. */
+export async function createTestWorkflowExecution(
+  executions: ExecutionStorage,
+  input: {
+    readonly projectId: string
+    readonly workflowId: string
+    readonly runId: string
+    readonly executionId?: string
+    readonly requestedBy?: AuthorizablePrincipal
+  }
+): Promise<string> {
+  const parentExecutionId = `test_request_execution:${input.runId}`
+  const executionId = input.executionId ?? `test_workflow_execution:${input.runId}`
+  const primitive: TrustedPrimitiveRef = {
+    kind: "workflow",
+    id: input.workflowId,
+    runId: input.runId,
+  }
+
+  await executions.create({
+    id: parentExecutionId,
+    projectId: input.projectId,
+    executor: { type: "request", requestId: `test_request:${input.runId}` },
+    source: { type: "http", requestId: `test_request:${input.runId}` },
+    ...(input.requestedBy === undefined ? {} : { requestedBy: structuredClone(input.requestedBy) }),
+    correlationId: `test_correlation:${input.runId}`,
+    authorizationRef:
+      input.requestedBy === undefined
+        ? { type: "disabled" }
+        : { type: "principal", principal: structuredClone(input.requestedBy) },
+  })
+  await executions.create({
+    id: executionId,
+    projectId: input.projectId,
+    executor: { type: "primitive", kind: primitive.kind, runId: primitive.runId },
+    source: { type: "execution", executionId: parentExecutionId },
+    ...(input.requestedBy === undefined ? {} : { requestedBy: structuredClone(input.requestedBy) }),
+    correlationId: `test_correlation:${input.runId}`,
+    authorizationRef: { type: "trustedPrimitive", primitive },
+  })
+
+  return executionId
+}
+
+/** Create a root workflow execution as produced by an automatic trigger. */
+export async function createTestAutomaticWorkflowExecution(
+  executions: ExecutionStorage,
+  input: {
+    readonly projectId: string
+    readonly workflowId: string
+    readonly runId: string
+    readonly executionId?: string
+    readonly source?: { readonly type: "schedule" | "event"; readonly eventId: string }
+    readonly correlationId?: string
+  }
+): Promise<string> {
+  const executionId = input.executionId ?? `test_workflow_execution:${input.runId}`
+  const primitive: TrustedPrimitiveRef = {
+    kind: "workflow",
+    id: input.workflowId,
+    runId: input.runId,
+  }
+
+  await executions.create({
+    id: executionId,
+    projectId: input.projectId,
+    executor: { type: "primitive", kind: primitive.kind, runId: primitive.runId },
+    source: input.source ?? { type: "event", eventId: `test_event:${input.runId}` },
+    correlationId: input.correlationId ?? `test_correlation:${input.runId}`,
+    authorizationRef: { type: "trustedPrimitive", primitive },
+  })
+
+  return executionId
+}

package/src/webhooks/index.ts

@@ -2,7 +2,8 @@ export { defineWebhook } from "./builders"
 export type { WebhookConnectorClient } from "./connector"
 export { webhookConnector } from "./connector"
 export { WebhookValidationError } from "./errors"
-export { registerWebhooks, webhookRoute } from "./registry"
+export type { WebhookCatalog, WebhookRegistryOptions } from "./registry"
+export { WebhookRegistry, webhookRoute } from "./registry"
 export type {
   RegisteredWebhook,
   WebhookBodyFormat,

package/src/webhooks/internal.ts

@@ -0,0 +1,5 @@
+export {
+  type AdmitWebhookRunInput,
+  type AdmitWebhookRunResult,
+  admitWebhookRun,
+} from "./run-admission"

package/src/webhooks/registry.ts

@@ -1,53 +1,77 @@
-import type { ConnectorDefinition } from "../connectors/types"
+import { type ConnectorDefinition, isStaticConnectorDefinition } from "../connectors/types"
 import { WebhookValidationError } from "./errors"
 import type { RegisteredWebhook, WebhookDefinition } from "./types"
 
-export function registerWebhooks(connectors: readonly ConnectorDefinition[]): {
-  readonly webhooks: readonly RegisteredWebhook[]
-} {
-  const registered: RegisteredWebhook[] = []
-  const routes = new Map<string, RegisteredWebhook>()
-
-  for (const connector of connectors) {
-    const webhooks = connector.adapter.webhooks ?? []
-    if (!Array.isArray(webhooks)) {
-      throw new WebhookValidationError(
-        `[Sixb] Connector '${connector.id}' webhooks must be an array when provided.`
-      )
-    }
+/** Read-only access to connector webhooks registered by a host. */
+export interface WebhookCatalog {
+  list(): readonly RegisteredWebhook[]
+  getByRoute(route: string): RegisteredWebhook | null
+  getById(connectorId: string, webhookId: string): RegisteredWebhook | null
+}
+
+export interface WebhookRegistryOptions {
+  readonly connectors: readonly ConnectorDefinition[]
+}
+
+export class WebhookRegistry implements WebhookCatalog {
+  private readonly webhooks: readonly RegisteredWebhook[]
+  private readonly byRoute = new Map<string, RegisteredWebhook>()
 
-    const ids = new Set<string>()
-    for (const webhook of webhooks) {
-      assertValidWebhook(connector.id, webhook)
+  constructor(options: WebhookRegistryOptions) {
+    const registered: RegisteredWebhook[] = []
 
-      if (ids.has(webhook.id)) {
+    for (const connector of options.connectors) {
+      if (!isStaticConnectorDefinition(connector)) continue
+      const webhooks = connector.adapter.webhooks ?? []
+      if (!Array.isArray(webhooks)) {
         throw new WebhookValidationError(
-          `[Sixb] Duplicate webhook id '${webhook.id}' for connector '${connector.id}'.`
+          `[Sixb] Connector '${connector.id}' webhooks must be an array when provided.`
         )
       }
-      ids.add(webhook.id)
 
-      const route = webhookRoute(connector.id, webhook.id)
-      const duplicate = routes.get(route)
-      if (duplicate) {
-        throw new WebhookValidationError(
-          `[Sixb] Duplicate webhook route '${route}' for connectors '${duplicate.connector.id}' and '${connector.id}'.`
-        )
+      const ids = new Set<string>()
+      for (const webhook of webhooks) {
+        assertValidWebhook(connector.id, webhook)
+
+        if (ids.has(webhook.id)) {
+          throw new WebhookValidationError(
+            `[Sixb] Duplicate webhook id '${webhook.id}' for connector '${connector.id}'.`
+          )
+        }
+        ids.add(webhook.id)
+
+        const route = webhookRoute(connector.id, webhook.id)
+        const duplicate = this.byRoute.get(route)
+        if (duplicate) {
+          throw new WebhookValidationError(
+            `[Sixb] Duplicate webhook route '${route}' for connectors '${duplicate.connector.id}' and '${connector.id}'.`
+          )
+        }
+
+        const registeredWebhook = {
+          connector,
+          webhook,
+          route,
+        } satisfies RegisteredWebhook
+
+        this.byRoute.set(route, registeredWebhook)
+        registered.push(registeredWebhook)
       }
+    }
+
+    this.webhooks = Object.freeze(registered)
+  }
 
-      const registeredWebhook = {
-        connector,
-        webhook,
-        route,
-      } satisfies RegisteredWebhook
+  list(): readonly RegisteredWebhook[] {
+    return this.webhooks
+  }
 
-      routes.set(route, registeredWebhook)
-      registered.push(registeredWebhook)
-    }
+  getByRoute(route: string): RegisteredWebhook | null {
+    return this.byRoute.get(route) ?? null
   }
 
-  return {
-    webhooks: registered,
+  getById(connectorId: string, webhookId: string): RegisteredWebhook | null {
+    return this.getByRoute(webhookRoute(connectorId, webhookId))
   }
 }