@sixb/core 0.0.1

package/src/webhooks/registry.ts

@@ -0,0 +1,127 @@
+import type { ConnectorDefinition } 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.`
+      )
+    }
+
+    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 = routes.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
+
+      routes.set(route, registeredWebhook)
+      registered.push(registeredWebhook)
+    }
+  }
+
+  return {
+    webhooks: registered,
+  }
+}
+
+export function webhookRoute(connectorId: string, webhookId: string): string {
+  return `/api/webhooks/${connectorId}/${webhookId}`
+}
+
+function assertValidWebhook(
+  connectorId: string,
+  webhook: unknown
+): asserts webhook is WebhookDefinition {
+  if (!isRecord(webhook)) {
+    throw new WebhookValidationError(`[Sixb] Connector '${connectorId}' has an invalid webhook.`)
+  }
+
+  if (webhook.kind !== "webhook") {
+    throw new WebhookValidationError(
+      `[Sixb] Connector '${connectorId}' webhook must be created with defineWebhook(...).`
+    )
+  }
+
+  if (typeof webhook.id !== "string" || !webhook.id.trim()) {
+    throw new WebhookValidationError(
+      `[Sixb] Connector '${connectorId}' webhook id must not be empty.`
+    )
+  }
+
+  if (webhook.method !== "POST") {
+    throw new WebhookValidationError(
+      `[Sixb] Webhook '${connectorId}/${webhook.id}' must use method POST.`
+    )
+  }
+
+  if (!isRecord(webhook.body)) {
+    throw new WebhookValidationError(
+      `[Sixb] Webhook '${connectorId}/${webhook.id}' body is required.`
+    )
+  }
+
+  if (
+    webhook.body.format !== "json" &&
+    webhook.body.format !== "text" &&
+    webhook.body.format !== "raw"
+  ) {
+    throw new WebhookValidationError(
+      `[Sixb] Webhook '${connectorId}/${webhook.id}' body format must be json, text, or raw.`
+    )
+  }
+
+  if (typeof webhook.body.parse !== "function") {
+    throw new WebhookValidationError(
+      `[Sixb] Webhook '${connectorId}/${webhook.id}' body parser must provide parse(value).`
+    )
+  }
+
+  if (webhook.verify !== undefined && typeof webhook.verify !== "function") {
+    throw new WebhookValidationError(
+      `[Sixb] Webhook '${connectorId}/${webhook.id}' verify must be a function.`
+    )
+  }
+
+  if (webhook.idempotencyKey !== undefined && typeof webhook.idempotencyKey !== "function") {
+    throw new WebhookValidationError(
+      `[Sixb] Webhook '${connectorId}/${webhook.id}' idempotencyKey must be a function.`
+    )
+  }
+
+  if (typeof webhook.handle !== "function") {
+    throw new WebhookValidationError(
+      `[Sixb] Webhook '${connectorId}/${webhook.id}' handle must be a function.`
+    )
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/webhooks/types.ts

@@ -0,0 +1,98 @@
+import type { ConnectorDefinition } from "../connectors/types"
+import type { Logger } from "../logging"
+import type { OntologySource, Sixb } from "../runtime"
+
+export type WebhookBodyFormat = "json" | "text" | "raw"
+
+/**
+ * Runtime parser used by `.json(schema)`.
+ *
+ * The parser receives already-decoded JSON as `unknown` and must validate,
+ * normalize, and return the body shape that handlers can safely use.
+ */
+export interface WebhookBodySchema<TBody> {
+  parse(value: unknown): TBody
+}
+
+/** Internal body parser stored on the finalized webhook definition. */
+export interface WebhookBodyParser<TBody> {
+  readonly format: WebhookBodyFormat
+  parse(value: unknown): TBody
+}
+
+/**
+ * Connector-scoped inbound webhook definition.
+ *
+ * Definitions are inert metadata. The server owns route registration and
+ * dispatch, while connector authors own verification, parsing, and handling.
+ */
+export interface WebhookDefinition<TBody = unknown, TClient = unknown> {
+  readonly kind: "webhook"
+  readonly id: string
+  readonly method: "POST"
+  readonly body: WebhookBodyParser<TBody>
+  /** Stable provider delivery id used to skip duplicate or concurrent deliveries. */
+  readonly idempotencyKey?: WebhookIdempotencyKeyResolver<TBody>
+  /** Runs before body parsing and receives raw bytes for signature checks. */
+  verify?(ctx: WebhookVerifyContext): Promise<void> | void
+  handle(
+    ctx: WebhookHandlerContext<TBody, TClient>
+  ): Promise<WebhookHandlerResult> | WebhookHandlerResult
+}
+
+export interface WebhookMetadata {
+  readonly id: string
+  readonly method: "POST"
+  readonly route: string
+  readonly bodyFormat: WebhookBodyFormat
+}
+
+export interface WebhookVerifyContext {
+  readonly sixb: Sixb<readonly OntologySource[]>
+  readonly logger: Logger
+  readonly connector: ConnectorDefinition
+  readonly webhook: WebhookMetadata
+  readonly request: Request
+  readonly rawBody: Uint8Array
+}
+
+export interface WebhookHandlerContext<TBody, TClient> extends WebhookVerifyContext {
+  readonly body: TBody
+  /** Lazily resolve the connector client only when the handler needs it. */
+  client(): Promise<TClient>
+}
+
+export interface WebhookIdempotencyContext<TBody> extends WebhookVerifyContext {
+  readonly body: TBody
+}
+
+type BivariantCallback<TArgs extends readonly unknown[], TReturn> = {
+  bivarianceHack(...args: TArgs): TReturn
+}["bivarianceHack"]
+
+export type WebhookIdempotencyKeyResolver<TBody> = BivariantCallback<
+  [ctx: WebhookIdempotencyContext<TBody>],
+  Promise<string | null | undefined> | string | null | undefined
+>
+
+/**
+ * Optional handler response. When omitted, dispatch returns `202 Accepted`.
+ */
+export interface WebhookResponse {
+  readonly status?: number
+  readonly headers?: HeadersInit
+  readonly body?: unknown
+}
+
+// biome-ignore lint/suspicious/noConfusingVoidType: webhook handlers intentionally support no-return callbacks.
+export type WebhookHandlerResult = WebhookResponse | void
+
+export interface RegisteredWebhook<
+  TBody = unknown,
+  TClient = unknown,
+  TConnector extends ConnectorDefinition = ConnectorDefinition,
+> {
+  readonly connector: TConnector
+  readonly webhook: WebhookDefinition<TBody, TClient>
+  readonly route: string
+}

package/src/webhooks/unverified.ts

@@ -0,0 +1,82 @@
+/**
+ * How a webhook is allowed to treat the credential its provider sends.
+ *
+ * A union, so no value carries neither branch. `resolveWebhookVerification` covers the path
+ * where the credential arrives as `TCredential | undefined` from the environment, which no type
+ * can narrow. Generic because a credential is not always a signing secret: PandaDoc resolves a
+ * shared key, Pipedrive compares a username and password.
+ */
+export type WebhookVerification<TCredential = string> =
+  | { readonly credential: TCredential; readonly allowUnverified?: never }
+  | {
+      readonly credential?: never
+      /**
+       * Accept deliveries this webhook cannot verify. Without a credential the route accepts
+       * requests from anyone who can reach it, so it has to be asked for.
+       */
+      readonly allowUnverified: true
+    }
+
+/**
+ * How to name a webhook, and its options, in a message about its verification.
+ *
+ * The options are part of the subject because a connector has two entry points with different
+ * names for the same thing: a message fixed to one sends half the callers to an option their
+ * API does not have.
+ */
+export interface WebhookVerificationSubject {
+  /** The connector, as it appears in its own message prefix — `SixbGitHub`, `SixbMercury`. */
+  readonly connector: string
+  /** What this webhook checks when a credential is configured, as a noun phrase. */
+  readonly verifies: string
+  /** The option carrying the credential, written as the caller would type it. */
+  readonly credentialOption: string
+  /** The option that accepts unverified deliveries, written as the caller would type it. */
+  readonly allowOption: string
+}
+
+export class UnverifiedWebhookError extends Error {
+  readonly name = "UnverifiedWebhookError"
+}
+
+/**
+ * Narrows a credential that may be absent into a {@link WebhookVerification}, or refuses.
+ *
+ * Returns the union so a caller spreads the result into the builder instead of deciding again.
+ * Refusing is the point: a missing credential used to mean `.verify()` returned early and the
+ * route accepted anything that reached it. Throwing here fails `createSixb()` instead, so the
+ * API role never starts open.
+ */
+export function resolveWebhookVerification<TCredential>(
+  subject: WebhookVerificationSubject,
+  options: { readonly credential?: TCredential; readonly allowUnverified?: boolean }
+): WebhookVerification<TCredential> {
+  if (options.credential) return { credential: options.credential }
+
+  if (!options.allowUnverified) {
+    throw new UnverifiedWebhookError(
+      `[${subject.connector}] This webhook has no credential, so ${subject.verifies} cannot be ` +
+        `checked and the route would accept unverified requests from anyone who can reach it. ` +
+        `Set ${subject.credentialOption}, or pass ${subject.allowOption} to accept that.`
+    )
+  }
+
+  return { allowUnverified: true }
+}
+
+/**
+ * Announces a webhook whose author chose to accept unverified deliveries. Called where the
+ * webhook is defined, not inside `verify()`: once per boot is a fact, once per request is noise.
+ */
+export function warnUnverifiedWebhook<TCredential>(
+  subject: WebhookVerificationSubject,
+  verification: WebhookVerification<TCredential>
+): void {
+  if (verification.credential) return
+
+  console.warn(
+    `[${subject.connector}] ${subject.allowOption}, so ${subject.verifies} is not checked ` +
+      `and this route accepts unverified requests from anyone who can reach it. ` +
+      `Set ${subject.credentialOption} before exposing it.`
+  )
+}

package/src/workers/errors.ts

@@ -0,0 +1,25 @@
+/**
+ * Thrown by worker primitives when an operation is interrupted by `stop()`.
+ *
+ * `name` is `"AbortError"` so it interoperates with the DOM `AbortSignal`
+ * convention used across the codebase.
+ */
+export class WorkerAbortError extends Error {
+  readonly name = "AbortError"
+}
+
+/** Raised after a worker exhausts its bounded restart budget. */
+export class WorkerUnhealthyError extends Error {
+  readonly name = "WorkerUnhealthyError"
+
+  constructor(
+    readonly workerName: string,
+    readonly restartCount: number,
+    options?: ErrorOptions
+  ) {
+    super(
+      `[SixbWorker] ${workerName} is unhealthy after ${restartCount} restart attempt(s).`,
+      options
+    )
+  }
+}

package/src/workers/index.ts

@@ -0,0 +1,6 @@
+export { WorkerAbortError, WorkerUnhealthyError } from "./errors"
+export type { QueueDelivery, QueueDeliveryState, QueueSettlementResult } from "./queue-delivery"
+export { QueueDeliveryLeaseLostError } from "./queue-delivery"
+export type { QueueWorkerConfig, QueueWorkerFailureDecision } from "./queue-worker"
+export { isAbortError, QueueWorker } from "./queue-worker"
+export { Worker } from "./worker"

package/src/workers/queue-delivery.ts

@@ -0,0 +1,309 @@
+import type { ClaimedQueueJob, Queue, QueueJob, QueueJobError } from "../queues"
+import { WorkerAbortError } from "./errors"
+
+export type QueueDeliveryState = "active" | "lost" | "settled"
+
+/**
+ * Outcome of a settlement call. `"lost"` means the queue job was **not** acknowledged because
+ * ownership was already gone — the job may be redelivered. Settlement never throws for a lost
+ * lease; exceptions are reserved for queue calls that themselves fail (outcome then unknown).
+ */
+export type QueueSettlementResult = "settled" | "lost"
+
+export interface QueueDelivery<TJob extends QueueJob> {
+  readonly claimed: ClaimedQueueJob<TJob>
+  readonly signal: AbortSignal
+  readonly state: QueueDeliveryState
+  /** Expiration from the latest queue-confirmed claim or renewal. */
+  readonly leaseExpiresAt: string
+
+  /** 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>
+  close(): Promise<void>
+}
+
+export interface CreateQueueDeliveryOptions<TJob extends QueueJob> {
+  readonly queue: Queue<TJob>
+  readonly claimed: ClaimedQueueJob<TJob>
+  readonly leaseMs: number
+  readonly signal: AbortSignal
+  readonly onLeaseLost?: () => void
+  readonly onRenewalError?: (error: unknown) => void
+}
+
+const MIN_RENEWAL_INTERVAL_MS = 1
+
+export class QueueDeliveryLeaseLostError extends WorkerAbortError {}
+
+type RenewalAttempt<TJob extends QueueJob> =
+  | { readonly kind: "renewed"; readonly claimed: ClaimedQueueJob<TJob> | null }
+  | { readonly kind: "failed"; readonly error: unknown }
+  | { 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> {
+  return new ManagedQueueDelivery(options)
+}
+
+class ManagedQueueDelivery<TJob extends QueueJob> implements QueueDelivery<TJob> {
+  readonly claimed: ClaimedQueueJob<TJob>
+  readonly signal: AbortSignal
+
+  private readonly queue: Queue<TJob>
+  private readonly leaseMs: number
+  private readonly renewLease: Queue<TJob>["renewLease"]
+  private readonly onLeaseLost: (() => void) | undefined
+  private readonly onRenewalError: ((error: unknown) => void) | undefined
+  private readonly lossController = new AbortController()
+  private readonly stopController = new AbortController()
+  private readonly renewalIntervalMs: number
+  private readonly renewalLoop: Promise<void>
+  private readonly leaseRenewedListeners = new Set<(claimed: ClaimedQueueJob<TJob>) => void>()
+  private currentState: QueueDeliveryState = "active"
+  private currentLeaseExpiresAt: string
+  private leaseExpiresAtTimestamp: number
+  private renewalErrorReported = false
+  private closing: Promise<void> | null = null
+  private settling = false
+
+  constructor(options: CreateQueueDeliveryOptions<TJob>) {
+    this.queue = options.queue
+    this.claimed = options.claimed
+    this.leaseMs = options.leaseMs
+    this.renewLease = options.queue.renewLease?.bind(options.queue)
+    this.onLeaseLost = options.onLeaseLost
+    this.onRenewalError = options.onRenewalError
+    this.currentLeaseExpiresAt = options.claimed.leaseExpiresAt
+    this.leaseExpiresAtTimestamp = parseLeaseExpiration(options.claimed.leaseExpiresAt)
+    this.renewalIntervalMs = Math.max(MIN_RENEWAL_INTERVAL_MS, Math.floor(options.leaseMs / 3))
+    this.signal = AbortSignal.any([options.signal, this.lossController.signal])
+    this.renewalLoop = this.runRenewalLoop()
+  }
+
+  get state(): QueueDeliveryState {
+    return this.currentState
+  }
+
+  get leaseExpiresAt(): string {
+    return this.currentLeaseExpiresAt
+  }
+
+  onLeaseRenewed(listener: (claimed: ClaimedQueueJob<TJob>) => void): () => void {
+    this.leaseRenewedListeners.add(listener)
+    return () => this.leaseRenewedListeners.delete(listener)
+  }
+
+  complete(): Promise<QueueSettlementResult> {
+    return this.settle(() =>
+      this.queue.complete({
+        projectId: this.claimed.job.projectId,
+        jobId: this.claimed.job.id,
+        leaseId: this.claimed.leaseId,
+      })
+    )
+  }
+
+  retry(
+    input: { readonly availableAt?: string; readonly error?: QueueJobError } = {}
+  ): 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> {
+    return this.settle(() =>
+      this.queue.fail({
+        projectId: this.claimed.job.projectId,
+        jobId: this.claimed.job.id,
+        leaseId: this.claimed.leaseId,
+        error,
+      })
+    )
+  }
+
+  close(): Promise<void> {
+    if (this.closing) return this.closing
+    this.closing = this.stopRenewal()
+    return this.closing
+  }
+
+  private async settle(operation: () => Promise<void>): Promise<QueueSettlementResult> {
+    if (this.currentState !== "active") {
+      return this.currentState === "settled" ? "settled" : "lost"
+    }
+    if (this.settling) {
+      throw new Error(`[SixbQueueWorker] Queue job '${this.claimed.job.id}' is already settling.`)
+    }
+
+    this.settling = true
+    try {
+      await this.stopRenewal()
+      if (!(await this.confirmSettlementLease())) return "lost"
+      await operation()
+      this.currentState = "settled"
+      return "settled"
+    } finally {
+      this.settling = false
+    }
+  }
+
+  private async confirmSettlementLease(): Promise<boolean> {
+    if (this.currentState !== "active") return false
+    if (Date.now() >= this.leaseExpiresAtTimestamp) {
+      this.markLost()
+      return false
+    }
+    if (!this.renewLease) return true
+
+    const attempt = await this.attemptRenewal()
+    if (attempt.kind === "renewed") {
+      if (!attempt.claimed) {
+        this.markLost()
+        return false
+      }
+      this.recordRenewal(attempt.claimed)
+      return true
+    }
+    if (attempt.kind === "failed") {
+      this.reportRenewalError(attempt.error)
+    }
+    if (attempt.kind === "expired" || Date.now() >= this.leaseExpiresAtTimestamp) {
+      this.markLost()
+      return false
+    }
+    return true
+  }
+
+  private async runRenewalLoop(): Promise<void> {
+    while (this.currentState === "active" && !this.stopController.signal.aborted) {
+      const remainingMs = this.leaseExpiresAtTimestamp - Date.now()
+      if (remainingMs <= 0) {
+        this.markLost()
+        return
+      }
+
+      const delayMs = this.renewLease ? Math.min(this.renewalIntervalMs, remainingMs) : remainingMs
+      await sleep(delayMs, this.stopController.signal).catch(() => {})
+      if (this.stopController.signal.aborted || this.currentState !== "active") return
+      if (Date.now() >= this.leaseExpiresAtTimestamp) {
+        this.markLost()
+        return
+      }
+      if (!this.renewLease) continue
+
+      const attempt = await this.attemptRenewal()
+      if (attempt.kind === "expired") {
+        this.markLost()
+        return
+      }
+      if (attempt.kind === "failed") {
+        this.reportRenewalError(attempt.error)
+        continue
+      }
+      if (!attempt.claimed) {
+        this.markLost()
+        return
+      }
+      this.recordRenewal(attempt.claimed)
+    }
+  }
+
+  private attemptRenewal(): Promise<RenewalAttempt<TJob>> {
+    if (!this.renewLease || Date.now() >= this.leaseExpiresAtTimestamp) {
+      return Promise.resolve({ kind: "expired" })
+    }
+
+    const remainingMs = Math.max(1, this.leaseExpiresAtTimestamp - Date.now())
+    return new Promise((resolve) => {
+      let finished = false
+      const finish = (attempt: RenewalAttempt<TJob>): void => {
+        if (finished) return
+        finished = true
+        clearTimeout(timer)
+        resolve(attempt)
+      }
+      const timer = setTimeout(() => finish({ kind: "expired" }), remainingMs)
+
+      this.renewLease?.({
+        projectId: this.claimed.job.projectId,
+        jobId: this.claimed.job.id,
+        leaseId: this.claimed.leaseId,
+        leaseMs: this.leaseMs,
+      }).then(
+        (claimed) => finish({ kind: "renewed", claimed }),
+        (error) => finish({ kind: "failed", error })
+      )
+    })
+  }
+
+  private recordRenewal(claimed: ClaimedQueueJob<TJob>): void {
+    this.currentLeaseExpiresAt = claimed.leaseExpiresAt
+    this.leaseExpiresAtTimestamp = parseLeaseExpiration(claimed.leaseExpiresAt)
+    this.renewalErrorReported = false
+    for (const listener of this.leaseRenewedListeners) {
+      try {
+        listener(claimed)
+      } catch (error) {
+        this.onRenewalError?.(error)
+      }
+    }
+  }
+
+  private reportRenewalError(error: unknown): void {
+    if (this.renewalErrorReported) return
+    this.renewalErrorReported = true
+    this.onRenewalError?.(error)
+  }
+
+  private markLost(): void {
+    if (this.currentState !== "active") return
+    this.currentState = "lost"
+    this.lossController.abort(
+      new QueueDeliveryLeaseLostError(
+        `[SixbQueueWorker] Queue job '${this.claimed.job.id}' lost its lease.`
+      )
+    )
+    this.onLeaseLost?.()
+  }
+
+  private async stopRenewal(): Promise<void> {
+    this.stopController.abort()
+    await this.renewalLoop.catch(() => {})
+  }
+}
+
+function parseLeaseExpiration(value: string): number {
+  const timestamp = Date.parse(value)
+  if (!Number.isFinite(timestamp)) {
+    throw new Error(`[SixbQueueWorker] Invalid queue lease expiration '${value}'.`)
+  }
+  return timestamp
+}
+
+async function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(finish, ms)
+    function finish(): void {
+      clearTimeout(timer)
+      signal.removeEventListener("abort", finish)
+      resolve()
+    }
+    signal.addEventListener("abort", finish, { once: true })
+  })
+}