@sixb/core 0.1.1 → 0.1.2

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))
   }
 }
 

package/src/webhooks/run-admission.ts

@@ -0,0 +1,172 @@
+import { randomUUID } from "node:crypto"
+import { createPrimitiveExecutionRecord } from "../execution/durable"
+import type { ExecutionRecord, Storage, WebhookRunRecord } from "../storage"
+import {
+  canRetryWebhookRun,
+  ExecutionStorageError,
+  isStorageSerializationFailure,
+  WebhookRunError,
+} from "../storage"
+
+const MAX_ADMISSION_ATTEMPTS = 3
+
+export interface AdmitWebhookRunInput {
+  readonly projectId: string
+  readonly storage: Storage
+  readonly runId: string
+  readonly connectorId: string
+  readonly webhookId: string
+  readonly method: string
+  readonly route: string
+  readonly requestBodyBytes: number
+  readonly requestBodySha256: string
+  readonly idempotencyKey?: string
+}
+
+export type AdmitWebhookRunResult =
+  | {
+      readonly status: "admitted"
+      readonly run: WebhookRunRecord
+      readonly execution: ExecutionRecord
+      readonly retried: boolean
+    }
+  | {
+      readonly status: "duplicate" | "in_progress"
+      readonly run: WebhookRunRecord
+    }
+
+/** Persist or reclaim one verified Webhook delivery before its protected handler executes. */
+export async function admitWebhookRun(input: AdmitWebhookRunInput): Promise<AdmitWebhookRunResult> {
+  assertAdmissionInput(input)
+  let attempt = 0
+
+  // Concurrent deliveries may both observe no run before one transaction commits. Retry only
+  // serialization and uniqueness races so the loser can reload the winning run; every other error
+  // fails immediately, and repeated contention remains bounded by MAX_ADMISSION_ATTEMPTS.
+  while (true) {
+    attempt += 1
+    try {
+      return await input.storage.transaction((tx) => admitWebhookRunTransaction(tx, input), {
+        isolation: "serializable",
+      })
+    } catch (error) {
+      if (attempt >= MAX_ADMISSION_ATTEMPTS || !isConcurrentAdmissionConflict(error)) {
+        throw error
+      }
+    }
+  }
+}
+
+async function admitWebhookRunTransaction(
+  storage: Storage,
+  input: AdmitWebhookRunInput
+): Promise<AdmitWebhookRunResult> {
+  const runs = requireWebhookRunStorage(storage)
+  const existing = input.idempotencyKey
+    ? await runs.getByDelivery({
+        projectId: input.projectId,
+        connectorId: input.connectorId,
+        webhookId: input.webhookId,
+        idempotencyKey: input.idempotencyKey,
+      })
+    : null
+
+  if (existing) {
+    assertSameDelivery(existing, input)
+    if (existing.status === "running") return { status: "in_progress", run: existing }
+    if (!canRetryWebhookRun(existing)) return { status: "duplicate", run: existing }
+
+    const execution = await requireWebhookExecution(storage, existing)
+    const run = await runs.restart({
+      projectId: input.projectId,
+      id: existing.id,
+    })
+    return { status: "admitted", run, execution, retried: true }
+  }
+
+  const executionInput = createPrimitiveExecutionRecord({
+    id: `exec_${randomUUID()}`,
+    primitive: { kind: "webhook", id: input.route, runId: input.runId },
+    origin: {
+      type: "automatic",
+      projectId: input.projectId,
+      source: { type: "webhook", deliveryId: input.runId },
+      correlationId: input.runId,
+    },
+  })
+  const execution = await storage.executions.create(executionInput)
+  const run = await runs.start({
+    id: input.runId,
+    projectId: input.projectId,
+    executionId: execution.id,
+    connectorId: input.connectorId,
+    webhookId: input.webhookId,
+    method: input.method,
+    route: input.route,
+    requestBodyBytes: input.requestBodyBytes,
+    requestBodySha256: input.requestBodySha256,
+    idempotencyKey: input.idempotencyKey,
+  })
+  return { status: "admitted", run, execution, retried: false }
+}
+
+function assertSameDelivery(existing: WebhookRunRecord, input: AdmitWebhookRunInput): void {
+  if (
+    existing.connectorId !== input.connectorId ||
+    existing.webhookId !== input.webhookId ||
+    existing.method !== input.method ||
+    existing.route !== input.route ||
+    existing.requestBodyBytes !== input.requestBodyBytes ||
+    existing.requestBodySha256 !== input.requestBodySha256
+  ) {
+    throw new WebhookRunError(
+      `[Sixb] Webhook delivery '${input.idempotencyKey}' conflicts with run '${existing.id}'.`,
+      "delivery_conflict"
+    )
+  }
+}
+
+async function requireWebhookExecution(
+  storage: Storage,
+  run: WebhookRunRecord
+): Promise<ExecutionRecord> {
+  const execution = await storage.executions.getById({
+    projectId: run.projectId,
+    id: run.executionId,
+  })
+  if (!execution) {
+    throw new WebhookRunError(
+      `[Sixb] Execution '${run.executionId}' for Webhook run '${run.id}' was not found.`,
+      "invalid_execution"
+    )
+  }
+  return execution
+}
+
+function requireWebhookRunStorage(storage: Storage): NonNullable<Storage["webhookRuns"]> {
+  if (!storage.webhookRuns) {
+    throw new WebhookRunError("[Sixb] Webhook run storage is not configured.")
+  }
+  return storage.webhookRuns
+}
+
+function assertAdmissionInput(input: AdmitWebhookRunInput): void {
+  if (input.idempotencyKey !== undefined && !input.idempotencyKey.trim()) {
+    throw new WebhookRunError("[Sixb] Webhook idempotency key must not be empty.")
+  }
+  if (!Number.isSafeInteger(input.requestBodyBytes) || input.requestBodyBytes < 0) {
+    throw new WebhookRunError("[Sixb] Webhook request body bytes must be a non-negative integer.")
+  }
+  if (!/^[a-f0-9]{64}$/.test(input.requestBodySha256)) {
+    throw new WebhookRunError("[Sixb] Webhook request body SHA-256 must be lowercase hexadecimal.")
+  }
+}
+
+function isConcurrentAdmissionConflict(error: unknown): boolean {
+  return (
+    isStorageSerializationFailure(error) ||
+    (error instanceof ExecutionStorageError && error.code === "duplicate_execution") ||
+    (error instanceof WebhookRunError &&
+      (error.code === "duplicate_run" || error.code === "invalid_transition"))
+  )
+}

package/src/webhooks/types.ts

@@ -1,4 +1,4 @@
-import type { ConnectorDefinition } from "../connectors/types"
+import type { StaticConnectorDefinition } from "../connectors/types"
 import type { Logger } from "../logging"
 import type { OntologySource, Sixb } from "../runtime"
 
@@ -47,21 +47,24 @@ export interface WebhookMetadata {
   readonly bodyFormat: WebhookBodyFormat
 }
 
+/** Pre-admission input. It intentionally has no execution SDK or run-scoped logger. */
 export interface WebhookVerifyContext {
-  readonly sixb: Sixb<readonly OntologySource[]>
-  readonly logger: Logger
-  readonly connector: ConnectorDefinition
+  readonly connector: StaticConnectorDefinition
   readonly webhook: WebhookMetadata
   readonly request: Request
   readonly rawBody: Uint8Array
 }
 
+/** Handler input bound to the durable Webhook run admitted for this delivery. */
 export interface WebhookHandlerContext<TBody, TClient> extends WebhookVerifyContext {
+  readonly sixb: Sixb<readonly OntologySource[]>
+  readonly logger: Logger
   readonly body: TBody
   /** Lazily resolve the connector client only when the handler needs it. */
   client(): Promise<TClient>
 }
 
+/** Pre-admission delivery identity input. It cannot perform protected domain work. */
 export interface WebhookIdempotencyContext<TBody> extends WebhookVerifyContext {
   readonly body: TBody
 }
@@ -90,7 +93,7 @@ export type WebhookHandlerResult = WebhookResponse | void
 export interface RegisteredWebhook<
   TBody = unknown,
   TClient = unknown,
-  TConnector extends ConnectorDefinition = ConnectorDefinition,
+  TConnector extends StaticConnectorDefinition = StaticConnectorDefinition,
 > {
   readonly connector: TConnector
   readonly webhook: WebhookDefinition<TBody, TClient>

package/src/workers/queue-delivery.ts

@@ -1,4 +1,5 @@
-import type { ClaimedQueueJob, Queue, QueueJob, QueueJobError } from "../queues"
+import type { SixbErrorCode } from "../errors/types"
+import type { ClaimedQueueJob, Queue, QueueJob, QueueJobFailure } from "../queues"
 import { WorkerAbortError } from "./errors"
 
 export type QueueDeliveryState = "active" | "lost" | "settled"
@@ -10,7 +11,10 @@ export type QueueDeliveryState = "active" | "lost" | "settled"
  */
 export type QueueSettlementResult = "settled" | "lost"
 
-export interface QueueDelivery<TJob extends QueueJob> {
+export interface QueueDelivery<
+  TJob extends QueueJob,
+  TFailureCode extends SixbErrorCode = SixbErrorCode,
+> {
   readonly claimed: ClaimedQueueJob<TJob>
   readonly signal: AbortSignal
   readonly state: QueueDeliveryState
@@ -20,16 +24,16 @@ export interface QueueDelivery<TJob extends QueueJob> {
   /** Observe successful queue renewals. The listener is not called for failed renewals. */
   onLeaseRenewed(listener: (claimed: ClaimedQueueJob<TJob>) => void): () => void
   complete(): Promise<QueueSettlementResult>
-  retry(input?: {
-    readonly availableAt?: string
-    readonly error?: QueueJobError
-  }): Promise<QueueSettlementResult>
-  fail(error: QueueJobError): Promise<QueueSettlementResult>
+  retry(input?: { readonly availableAt?: string }): Promise<QueueSettlementResult>
+  fail(failure: QueueJobFailure<TFailureCode>): Promise<QueueSettlementResult>
   close(): Promise<void>
 }
 
-export interface CreateQueueDeliveryOptions<TJob extends QueueJob> {
-  readonly queue: Queue<TJob>
+export interface CreateQueueDeliveryOptions<
+  TJob extends QueueJob,
+  TFailureCode extends SixbErrorCode,
+> {
+  readonly queue: Queue<TJob, TFailureCode>
   readonly claimed: ClaimedQueueJob<TJob>
   readonly leaseMs: number
   readonly signal: AbortSignal
@@ -47,19 +51,21 @@ type RenewalAttempt<TJob extends QueueJob> =
   | { readonly kind: "expired" }
 
 /** Owns lease renewal, loss detection, and settlement for one claimed queue job. */
-export function createQueueDelivery<TJob extends QueueJob>(
-  options: CreateQueueDeliveryOptions<TJob>
-): QueueDelivery<TJob> {
+export function createQueueDelivery<TJob extends QueueJob, TFailureCode extends SixbErrorCode>(
+  options: CreateQueueDeliveryOptions<TJob, TFailureCode>
+): QueueDelivery<TJob, TFailureCode> {
   return new ManagedQueueDelivery(options)
 }
 
-class ManagedQueueDelivery<TJob extends QueueJob> implements QueueDelivery<TJob> {
+class ManagedQueueDelivery<TJob extends QueueJob, TFailureCode extends SixbErrorCode>
+  implements QueueDelivery<TJob, TFailureCode>
+{
   readonly claimed: ClaimedQueueJob<TJob>
   readonly signal: AbortSignal
 
-  private readonly queue: Queue<TJob>
+  private readonly queue: Queue<TJob, TFailureCode>
   private readonly leaseMs: number
-  private readonly renewLease: Queue<TJob>["renewLease"]
+  private readonly renewLease: Queue<TJob, TFailureCode>["renewLease"]
   private readonly onLeaseLost: (() => void) | undefined
   private readonly onRenewalError: ((error: unknown) => void) | undefined
   private readonly lossController = new AbortController()
@@ -74,7 +80,7 @@ class ManagedQueueDelivery<TJob extends QueueJob> implements QueueDelivery<TJob>
   private closing: Promise<void> | null = null
   private settling = false
 
-  constructor(options: CreateQueueDeliveryOptions<TJob>) {
+  constructor(options: CreateQueueDeliveryOptions<TJob, TFailureCode>) {
     this.queue = options.queue
     this.claimed = options.claimed
     this.leaseMs = options.leaseMs
@@ -111,27 +117,24 @@ class ManagedQueueDelivery<TJob extends QueueJob> implements QueueDelivery<TJob>
     )
   }
 
-  retry(
-    input: { readonly availableAt?: string; readonly error?: QueueJobError } = {}
-  ): Promise<QueueSettlementResult> {
+  retry(input: { readonly availableAt?: string } = {}): Promise<QueueSettlementResult> {
     return this.settle(() =>
       this.queue.retry({
         projectId: this.claimed.job.projectId,
         jobId: this.claimed.job.id,
         leaseId: this.claimed.leaseId,
         availableAt: input.availableAt,
-        error: input.error,
       })
     )
   }
 
-  fail(error: QueueJobError): Promise<QueueSettlementResult> {
+  fail(failure: QueueJobFailure<TFailureCode>): Promise<QueueSettlementResult> {
     return this.settle(() =>
       this.queue.fail({
         projectId: this.claimed.job.projectId,
         jobId: this.claimed.job.id,
         leaseId: this.claimed.leaseId,
-        error,
+        failure,
       })
     )
   }