@sixb/core 0.1.1 → 0.1.3

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

package/src/workers/queue-worker.ts

@@ -1,4 +1,6 @@
-import type { ClaimedQueueJob, Queue, QueueJob, QueueJobError } from "../queues"
+import { captureSixbFailure } from "../errors/internal"
+import type { SixbErrorCode, SixbFailure } from "../errors/types"
+import type { ClaimedQueueJob, Queue, QueueJob } from "../queues"
 import { WorkerAbortError } from "./errors"
 import {
   createQueueDelivery,
@@ -7,41 +9,73 @@ import {
 } from "./queue-delivery"
 import { Worker } from "./worker"
 
-export interface QueueWorkerConfig<TJob extends QueueJob> {
+type QueueWorkerFailureCodes = readonly [
+  "internal.unexpected",
+  "runtime.cancelled",
+  ...SixbErrorCode[],
+]
+
+export interface QueueWorkerConfig<
+  TJob extends QueueJob,
+  TFailureCodes extends QueueWorkerFailureCodes,
+> {
   readonly projectId: string
-  readonly queue: Queue<TJob>
+  readonly queue: Queue<TJob, TFailureCodes[number]>
+  /** Runtime counterpart of this lane's precise terminal-failure union. */
+  readonly failureCodes: TFailureCodes
   readonly workerId: string
   readonly leaseMs?: number
   readonly claimLimit?: number
   readonly idlePollMs?: number
 }
 
-export interface QueueWorkerFailureDecision {
-  readonly kind: "retry" | "fail"
-  readonly availableAt?: string
-}
+/**
+ * Queue settlement selected after execution stops.
+ *
+ * A worker must name its allowed failure-code union before it can supply an already-persisted
+ * failure. Workers that only choose retry vs fail need no generic annotation.
+ */
+export type QueueWorkerFailureDecision<TFailureCode extends SixbErrorCode = never> =
+  | {
+      readonly kind: "retry"
+      readonly availableAt?: string
+    }
+  | {
+      readonly kind: "fail"
+      /** Exact durable run failure, when execution already persisted one. */
+      readonly failure?: SixbFailure<TFailureCode>
+    }
 
 const DEFAULT_LEASE_MS = 15 * 60_000
 const DEFAULT_CLAIM_LIMIT = 1
 const DEFAULT_IDLE_POLL_MS = 1_000
 const MAX_CONSECUTIVE_CLAIM_FAILURES = 5
 
-export abstract class QueueWorker<TJob extends QueueJob> extends Worker {
-  protected readonly config: Required<QueueWorkerConfig<TJob>>
+export abstract class QueueWorker<
+  TJob extends QueueJob,
+  TFailureCodes extends QueueWorkerFailureCodes,
+> extends Worker {
+  protected readonly config: Required<QueueWorkerConfig<TJob, TFailureCodes>>
   private consecutiveClaimFailures = 0
 
-  constructor(config: QueueWorkerConfig<TJob>) {
+  constructor(config: QueueWorkerConfig<TJob, TFailureCodes>) {
     super()
     this.config = {
       projectId: config.projectId,
       queue: config.queue,
+      failureCodes: config.failureCodes,
       workerId: config.workerId,
       leaseMs: config.leaseMs ?? DEFAULT_LEASE_MS,
-      claimLimit: config.claimLimit ?? DEFAULT_CLAIM_LIMIT,
+      claimLimit: normalizeClaimLimit(config.claimLimit),
       idlePollMs: config.idlePollMs ?? DEFAULT_IDLE_POLL_MS,
     }
   }
 
+  /** Maximum jobs this worker process claims and executes at once. */
+  get concurrency(): number {
+    return this.config.claimLimit
+  }
+
   protected async run(signal: AbortSignal): Promise<void> {
     const inFlight = new Set<Promise<void>>()
     let runError: unknown = null
@@ -80,20 +114,24 @@ export abstract class QueueWorker<TJob extends QueueJob> extends Worker {
   protected abstract execute(
     claimed: ClaimedQueueJob<TJob>,
     signal: AbortSignal,
-    delivery: QueueDelivery<TJob>
+    delivery: QueueDelivery<TJob, TFailureCodes[number]>
   ): Promise<void>
 
   protected onExecutionError(
     _claimed: ClaimedQueueJob<TJob>,
     _error: unknown
-  ): Promise<QueueWorkerFailureDecision> | QueueWorkerFailureDecision {
+  ):
+    | Promise<QueueWorkerFailureDecision<TFailureCodes[number]>>
+    | QueueWorkerFailureDecision<TFailureCodes[number]> {
     return { kind: "fail" }
   }
 
   protected onAbortError(
     _claimed: ClaimedQueueJob<TJob>,
     _error: unknown
-  ): Promise<QueueWorkerFailureDecision> | QueueWorkerFailureDecision {
+  ):
+    | Promise<QueueWorkerFailureDecision<TFailureCodes[number]>>
+    | QueueWorkerFailureDecision<TFailureCodes[number]> {
     // Shutdown should normally release work for another process. Workers with non-idempotent
     // partial commits can override this and fail the job instead.
     return { kind: "retry" }
@@ -171,7 +209,7 @@ export abstract class QueueWorker<TJob extends QueueJob> extends Worker {
       if (signal.aborted || isAbortError(error)) {
         try {
           const decision = await this.onAbortError(claimed, error)
-          await this.applyFailureDecision(delivery, decision, error)
+          await this.applyFailureDecision(delivery, decision, error, "runtime.cancelled")
         } catch {
           // Shutdown is already in progress. The unacknowledged job becomes visible after its lease.
         }
@@ -180,7 +218,7 @@ export abstract class QueueWorker<TJob extends QueueJob> extends Worker {
 
       try {
         const decision = await this.onExecutionError(claimed, error)
-        await this.applyFailureDecision(delivery, decision, error)
+        await this.applyFailureDecision(delivery, decision, error, "internal.unexpected")
       } catch (settlementError) {
         logQueueOperationError("apply failure decision to", claimed, settlementError)
       }
@@ -190,24 +228,36 @@ export abstract class QueueWorker<TJob extends QueueJob> extends Worker {
   }
 
   private async applyFailureDecision(
-    delivery: QueueDelivery<TJob>,
-    decision: QueueWorkerFailureDecision,
-    error: unknown
+    delivery: QueueDelivery<TJob, TFailureCodes[number]>,
+    decision: QueueWorkerFailureDecision<TFailureCodes[number]>,
+    error: unknown,
+    defaultCode: "internal.unexpected" | "runtime.cancelled"
   ): Promise<void> {
     if (decision.kind === "retry") {
-      await delivery.retry({
-        availableAt: decision.availableAt,
-        error: toQueueJobError(error),
-      })
+      await delivery.retry({ availableAt: decision.availableAt })
       return
     }
 
-    await delivery.fail(toQueueJobError(error))
+    const failure =
+      decision.failure ??
+      captureSixbFailure(error, {
+        allowedCodes: this.config.failureCodes,
+        defaultCode,
+      })
+    await delivery.fail(failure)
+  }
+}
+
+function normalizeClaimLimit(value: number | undefined): number {
+  const claimLimit = value ?? DEFAULT_CLAIM_LIMIT
+  if (!Number.isSafeInteger(claimLimit) || claimLimit < 1) {
+    throw new Error("[SixbQueueWorker] Worker concurrency must be a positive safe integer.")
   }
+  return claimLimit
 }
 
-async function settleOrLog<TJob extends QueueJob>(
-  delivery: QueueDelivery<TJob>,
+async function settleOrLog<TJob extends QueueJob, TFailureCode extends SixbErrorCode>(
+  delivery: QueueDelivery<TJob, TFailureCode>,
   operation: string,
   settle: () => Promise<QueueSettlementResult>
 ): Promise<void> {
@@ -226,13 +276,6 @@ function logQueueOperationError(operation: string, claimed: ClaimedQueueJob, err
   )
 }
 
-function toQueueJobError(error: unknown): QueueJobError {
-  if (error instanceof Error) {
-    return { name: error.name, message: error.message }
-  }
-  return { message: String(error) }
-}
-
 /** True for a standard abort (`AbortController`/`AbortSignal.timeout`) error. */
 export function isAbortError(error: unknown): boolean {
   return error instanceof Error && error.name === "AbortError"