@objectstack/plugin-webhooks 7.5.0 → 7.6.0

package/dist/index.d.ts

@@ -1,12 +1,19 @@
 import { Plugin, PluginContext } from '@objectstack/core';
-import { IDataEngine, IRealtimeService, IClusterService } from '@objectstack/spec/contracts';
-import { I as IWebhookOutbox, a as AckResult, W as WebhookDelivery, E as EnqueueInput, C as ClaimOptions, D as DeliveryStatus } from './outbox-CIn7LSyB.js';
-export { A as AckFailure, b as AckSuccess, R as RedeliverError } from './outbox-CIn7LSyB.js';
+import { IDataEngine, IRealtimeService } from '@objectstack/spec/contracts';
+import { EnqueueHttpInput } from '@objectstack/service-messaging';
+export { SysWebhook } from './schema.js';
+import '@objectstack/spec/data';
 
+/**
+ * Enqueue callback into the shared `service-messaging` HTTP outbox (ADR-0018 M3).
+ * The plugin supplies one bound to `messaging.enqueueHttp(...)`; webhooks no
+ * longer own a delivery outbox/dispatcher — they share the generic substrate.
+ */
+type HttpEnqueueFn = (input: EnqueueHttpInput) => Promise<string>;
 /**
  * Optional logger interface (subset of console / kernel logger).
  */
-interface OptionalLogger$1 {
+interface OptionalLogger {
     info?(msg: string, meta?: unknown): void;
     warn?(msg: string, meta?: unknown): void;
     debug?(msg: string, meta?: unknown): void;
@@ -39,7 +46,7 @@ interface AutoEnqueuerOptions {
      * the subscription-change event is missed. Default 60s.
      */
     refreshIntervalMs?: number;
-    logger?: OptionalLogger$1;
+    logger?: OptionalLogger;
 }
 /**
  * Bridge between `IRealtimeService` (`data.record.*` events emitted by
@@ -82,7 +89,7 @@ interface AutoEnqueuerOptions {
 declare class AutoEnqueuer {
     private readonly engine;
     private readonly realtime;
-    private readonly outbox;
+    private readonly enqueue;
     private readonly subscriptions;
     private readonly subscriptionsObject;
     private readonly refreshIntervalMs;
@@ -92,7 +99,7 @@ declare class AutoEnqueuer {
     private refreshTimer;
     private running;
     private refreshing;
-    constructor(engine: IDataEngine, realtime: IRealtimeService, outbox: IWebhookOutbox, opts?: AutoEnqueuerOptions);
+    constructor(engine: IDataEngine, realtime: IRealtimeService, enqueue: HttpEnqueueFn, opts?: AutoEnqueuerOptions);
     /**
      * Load the subscription cache and start listening for events.
      */
@@ -118,287 +125,41 @@ declare class AutoEnqueuer {
     snapshot(): ReadonlyMap<string, ReadonlyArray<CachedSubscription>>;
 }
 
-/**
- * Default per-request timeout. Receivers SHOULD respond within ~30s; we
- * cap aggressively to free dispatcher slots.
- */
-declare const DEFAULT_TIMEOUT_MS = 15000;
-type FetchImpl = (input: string, init: {
-    method: string;
-    headers: Record<string, string>;
-    body: string;
-    signal: AbortSignal;
-}) => Promise<{
-    ok: boolean;
-    status: number;
-    text(): Promise<string>;
-}>;
-/** Single HTTP attempt classified to an `AckResult` shape (without nextRetryAt). */
-type AttemptOutcome = {
-    success: true;
-    httpStatus: number;
-    responseBody?: string;
-    durationMs: number;
-} | {
-    success: false;
-    retriable: boolean;
-    httpStatus?: number;
-    responseBody?: string;
-    error?: string;
-    durationMs: number;
-};
-/**
- * Send one HTTP attempt for the delivery. Pure (no DB writes) so the
- * dispatcher owns retry-schedule + ack logic.
- *
- *   - 2xx                       → success
- *   - 4xx (except 408/429)      → permanent failure (retriable = false → goes to `dead`)
- *   - 408, 429, 5xx, transport  → retriable
- */
-declare function sendOnce(delivery: WebhookDelivery, fetchImpl: FetchImpl): Promise<AttemptOutcome>;
-/**
- * Stripe-style retry schedule. Returns the next `nextRetryAt` ms (relative
- * to `now`) given how many attempts have already happened, or `null` if
- * the row should be moved to `dead`.
- *
- *   attempt 1 fails -> retry in ~1s
- *   attempt 2 fails -> ~10s
- *   attempt 3 fails -> ~1m
- *   attempt 4 fails -> ~10m
- *   attempt 5 fails -> ~1h
- *   attempt 6 fails -> ~6h
- *   attempt 7 fails -> ~24h
- *   attempt 8+ fails -> dead
- *
- * Each delay is multiplied by jitter ∈ [0.8, 1.2].
- */
-declare function nextRetryDelayMs(attemptsSoFar: number, rng?: () => number): number | null;
-/**
- * Compose an `AckResult` from an `AttemptOutcome`, applying the retry
- * schedule on retriable failures.
- */
-declare function classifyAttempt(outcome: AttemptOutcome, attemptsSoFar: number, now?: number, rng?: () => number): AckResult;
-
-/**
- * Minimal logger surface — kernel's `Logger` is compatible (extra params
- * accepted). Keeping it permissive avoids a hard dependency on the spec
- * Logger interface here.
- */
-interface DispatcherLogger {
-    warn: (msg: string, meta?: any) => void;
-    info?: (msg: string, meta?: any) => void;
-}
-interface DispatcherOptions {
-    /** Stable id identifying this dispatcher node. */
-    nodeId: string;
-    /** Cluster service providing `lock` (and optional metrics). */
-    cluster: IClusterService;
-    /** Outbox backend. */
-    outbox: IWebhookOutbox;
-    /**
-     * How many partitions to split work across. Each tick the dispatcher
-     * attempts to acquire each partition's lock independently — the node
-     * that wins owns that partition for the duration of the batch.
-     *
-     * Default: 8 (matches webhook-delivery.mdx §4 example).
-     */
-    partitionCount?: number;
-    /** Max rows to claim from each partition per tick. Default 32. */
-    batchSize?: number;
-    /** Tick interval in ms. Default 250. */
-    intervalMs?: number;
-    /** Per-partition lock TTL. Default = 5 × intervalMs. */
-    lockTtlMs?: number;
-    /** Visibility timeout for claimed rows. Default = 2 × lockTtlMs. */
-    claimTtlMs?: number;
-    /** Override `globalThis.fetch` (tests). */
-    fetchImpl?: FetchImpl;
-    /** Hook fired after every attempt — observability hook. */
-    onAttempt?: (delivery: WebhookDelivery, success: boolean) => void;
-    /** RNG override for the retry-jitter schedule (tests). */
-    rng?: () => number;
-    /** Logger callback (optional). */
-    logger?: DispatcherLogger;
-}
-/**
- * Cross-node webhook dispatcher.
- *
- * **Design** — each tick the dispatcher iterates over `partitionCount`
- * logical partitions. For each, it tries to acquire a cluster-scoped lock
- * (`webhook.dispatcher.partition.{i}`) with a short TTL. If it wins the
- * lock, it claims up to `batchSize` ready rows whose `hash(webhookId) mod
- * partitionCount === i`, POSTs them, and acks. The lock is released
- * immediately after the batch so other nodes can fairly rotate through.
- *
- * **Why per-partition locks rather than one global lock?**
- *
- *   1. Throughput — N nodes can process N partitions concurrently.
- *   2. Partition affinity — rows for the same webhook always sort into the
- *      same partition, preserving in-order delivery per webhook.
- *   3. Failure isolation — a stuck node only blocks its partition until the
- *      TTL elapses; other partitions keep moving.
- *
- * **At-least-once, not exactly-once.** Receivers MUST be idempotent on the
- * `X-Objectstack-Delivery` (== row id) header. If the HTTP call succeeds
- * but the ack write fails, the row reverts to pending after the claim TTL
- * and will be re-posted.
- */
-declare class WebhookDispatcher {
-    private readonly opts;
-    private timer;
-    private running;
-    private inflightTick;
-    constructor(options: DispatcherOptions);
-    /** Begin the periodic loop. Safe to call once; subsequent calls are no-ops. */
-    start(): void;
-    /** Stop the loop and wait for the in-flight tick to drain. */
-    stop(): Promise<void>;
-    /**
-     * Run one full tick (all partitions, single attempt each). Exposed for
-     * deterministic tests that want to step the dispatcher manually.
-     */
-    tick(): Promise<void>;
-    private scheduleTick;
-    private runTick;
-    private runPartition;
-    private processRow;
-}
-
-interface OptionalLogger {
-    info?(msg: string, meta?: unknown): void;
-    warn?(msg: string, meta?: unknown): void;
-    debug?(msg: string, meta?: unknown): void;
-}
-interface DeliveryRetentionOptions {
-    /**
-     * Object name backing the outbox. Defaults to `sys_webhook_delivery`.
-     */
-    objectName?: string;
-    /**
-     * How long to keep `success` rows. Default 7 days. Set to `0` to
-     * disable the success sweep (keep forever — not recommended in
-     * production).
-     */
-    successTtlMs?: number;
-    /**
-     * How long to keep `dead` rows. Default 30 days. Set to `0` to
-     * keep forever.
-     */
-    deadTtlMs?: number;
-    /**
-     * How often to run the sweep. Default 1h.
-     */
-    sweepIntervalMs?: number;
-    logger?: OptionalLogger;
-}
-/**
- * Periodically prunes `sys_webhook_delivery` rows so the table doesn't
- * grow unbounded.
- *
- * Without this every successful POST would leave a permanent row. At
- * even moderate scale (10 events/s × 3 webhooks = 30 rows/s = ~2.6M
- * rows/day) the table becomes a problem within a week.
- *
- * Retention defaults mirror Stripe/GitHub:
- *   - `success`: 7 days
- *   - `dead`:   30 days (kept longer for audit & manual re-delivery)
- *   - `pending`/`in_flight`/`failed`: never auto-pruned (they're
- *     either live work or signal something needs human attention)
- *
- * Runs on whichever node holds the sweeper interval — it doesn't need
- * a cluster lock because DELETE WHERE created_at < threshold is
- * idempotent; multiple nodes running concurrently is wasteful but
- * safe.
- */
-declare class DeliveryRetentionSweeper {
-    private readonly engine;
-    private readonly objectName;
-    private readonly successTtlMs;
-    private readonly deadTtlMs;
-    private readonly sweepIntervalMs;
-    private readonly logger;
-    private timer;
-    private running;
-    constructor(engine: IDataEngine, opts?: DeliveryRetentionOptions);
-    start(): void;
-    stop(): void;
-    /** Run one sweep immediately. Returns the number of rows deleted. */
-    sweep(now?: number): Promise<{
-        success: number;
-        dead: number;
-    }>;
-}
-
-interface WebhookOutboxPluginOptions extends Partial<Omit<DispatcherOptions, 'cluster' | 'outbox' | 'nodeId'>> {
-    /**
-     * Override the outbox backend. If omitted a fresh `MemoryWebhookOutbox`
-     * is used — fine for local development, **not for production**: each
-     * node will see only its own rows.
-     *
-     * Pass a factory if you need the kernel-resolved `IDataEngine`:
-     *
-     * ```ts
-     * outbox: (ctx) => new SqlWebhookOutbox(
-     *   ctx.getService('objectql'), { partitionCount: 8 },
-     * ),
-     * ```
-     */
-    outbox?: IWebhookOutbox | ((ctx: PluginContext) => IWebhookOutbox);
-    /**
-     * Stable node id. If omitted, uses `process.env.OS_NODE_ID`
-     * (legacy `OBJECTSTACK_NODE_ID` still honoured with deprecation warning)
-     * or a random UUID generated at plugin init.
-     */
-    nodeId?: string;
-    /**
-     * If `false`, the plugin registers the outbox/dispatcher services but
-     * does NOT auto-start the loop — useful for tests that want to step
-     * the dispatcher manually via `dispatcher.tick()`.
-     *
-     * Default: true.
-     */
-    autoStart?: boolean;
+interface WebhookOutboxPluginOptions {
     /**
-     * Auto-enqueue config. When enabled (default `true` if the realtime
-     * + data engine services are available), the plugin subscribes to
-     * `data.record.*` events emitted by the engine and automatically
-     * enqueues a delivery row for every matching `sys_webhook` row.
+     * Auto-enqueue config. When enabled (default `true` if the realtime + data
+     * engine services are available), the plugin subscribes to `data.record.*`
+     * events and enqueues a delivery onto the shared messaging HTTP outbox for
+     * every matching `sys_webhook` row.
      *
-     * Set `false` to disable and only use the imperative
-     * `outbox.enqueue()` API.
+     * Set `false` to disable and enqueue webhooks imperatively elsewhere.
      */
     autoEnqueue?: boolean | AutoEnqueuerOptions;
-    /**
-     * Retention sweep config. When enabled (default `true` if a SQL
-     * outbox is in use), a periodic timer prunes old `success` and
-     * `dead` rows from `sys_webhook_delivery`.
-     *
-     * Set `false` to disable (e.g. when using `MemoryWebhookOutbox`).
-     */
-    retention?: boolean | DeliveryRetentionOptions;
 }
 /**
- * Wires a persistent, cluster-aware webhook outbox into the kernel.
+ * Wires webhook fan-out on top of the shared outbound-HTTP delivery substrate
+ * (ADR-0018 M3).
  *
- * Registered services:
- *   - `webhook.outbox`     → `IWebhookOutbox` (enqueue / claim / ack / list)
- *   - `webhook.dispatcher` → `WebhookDispatcher` (manual `tick()` if needed)
- *   - `webhook.autoEnqueuer` → `AutoEnqueuer` when auto-enqueue is on
- *   - `webhook.retention`    → `DeliveryRetentionSweeper` when retention is on
+ * Webhooks are no longer their own delivery engine: the durable outbox, the
+ * cluster-coordinated dispatcher, the retry/backoff/dead-letter schedule, and
+ * the retention sweep all live in `@objectstack/service-messaging`
+ * (`sys_http_delivery` + `HttpDispatcher`). This plugin owns only the
+ * webhook-specific concerns:
+ *   - the `sys_webhook` configuration object,
+ *   - the {@link AutoEnqueuer} that turns `data.record.*` events into outbox
+ *     rows (`source: 'webhook'`), and
+ *   - the redeliver admin endpoint.
  *
- * End-to-end flow once auto-enqueue is enabled:
+ * End-to-end flow:
  *
  *   engine.insert('contact', {...})
  *     → engine publishes data.record.created via IRealtimeService
  *     → AutoEnqueuer matches active sys_webhook rows in O(1)
- *     → outbox.enqueue() runs fire-and-forget (not on the write path)
- *     → dispatcher claims and POSTs (cluster-coordinated)
+ *     → messaging.enqueueHttp() runs fire-and-forget (off the write path)
+ *     → messaging HttpDispatcher claims and POSTs (cluster-coordinated, retried)
  *
- * **Cluster requirement** — this plugin depends on the cluster service
- * (`ClusterServicePlugin`). With the default `memory` driver the
- * dispatcher works correctly inside a single process; with a real driver
- * (`@objectstack/service-cluster-redis`) it correctly coordinates work
- * across nodes.
+ * **Requires** `MessagingServicePlugin` (`@objectstack/service-messaging`),
+ * which is a foundational, always-on capability.
  */
 declare class WebhookOutboxPlugin implements Plugin {
     private readonly options;
@@ -406,65 +167,20 @@ declare class WebhookOutboxPlugin implements Plugin {
     version: string;
     type: "standard";
     dependencies: string[];
-    private dispatcher;
     private autoEnqueuer;
-    private retention;
-    private outboxInstance;
     constructor(options?: WebhookOutboxPluginOptions);
     init(ctx: PluginContext): Promise<void>;
     dispose(): Promise<void>;
-    private resolveOutbox;
+    private getMessaging;
     private bootAutoEnqueue;
-    private bootRetention;
     private tryGetService;
     /**
-     * Mount POST /api/v1/webhooks/redeliver on the host Hono app, if one
-     * is available. Silently no-ops in environments without an HTTP
-     * server (MSW, edge tests, pure library use). Auth is delegated to
-     * the better-auth session cookie — every authenticated user counts.
+     * Mount POST /api/v1/webhooks/redeliver on the host Hono app, if one is
+     * available. Delegates to `messaging.redeliverHttp(deliveryId)`. Auth is the
+     * better-auth session cookie — every authenticated user counts.
      */
     private registerAdminRoutes;
-    /**
-     * Resolve the requesting user's id from a better-auth session cookie.
-     * Returns `undefined` for anonymous callers — the caller decides
-     * whether that's a 401.
-     */
     private resolveSessionUserId;
 }
 
-/**
- * In-memory `IWebhookOutbox` for tests and single-process development.
- *
- * Implements the atomic-claim semantics by running its claim/ack logic
- * synchronously (single-threaded JS event loop) inside one `Map`. Two
- * `MemoryWebhookOutbox` instances do NOT share state — for the cross-node
- * test the *same* instance is passed to both dispatchers (simulating one
- * shared database).
- *
- * A production SQL-backed implementation will live in a sibling file and
- * use `SELECT ... FOR UPDATE SKIP LOCKED`.
- */
-declare class MemoryWebhookOutbox implements IWebhookOutbox {
-    private readonly rows;
-    /** Dedup index keyed by `${eventId}::${webhookId}` -> row id. */
-    private readonly dedup;
-    enqueue(input: EnqueueInput): Promise<string>;
-    claim(opts: ClaimOptions): Promise<WebhookDelivery[]>;
-    ack(id: string, result: AckResult): Promise<void>;
-    list(filter?: {
-        status?: DeliveryStatus;
-    }): Promise<WebhookDelivery[]>;
-    redeliver(id: string): Promise<WebhookDelivery>;
-}
-
-/**
- * Stable, framework-free partition hash. The dispatcher uses this to
- * assign webhooks to partitions; the in-memory outbox uses the same hash
- * to filter rows in `claim()`. Both call sites MUST agree, which is why
- * this is a single shared helper.
- *
- * Uses a 32-bit FNV-1a variant — fast, no allocations, deterministic.
- */
-declare function hashPartition(key: string, count: number): number;
-
-export { AckResult, type AttemptOutcome, AutoEnqueuer, type AutoEnqueuerOptions, ClaimOptions, DEFAULT_TIMEOUT_MS, type DeliveryRetentionOptions, DeliveryRetentionSweeper, DeliveryStatus, type DispatcherOptions, EnqueueInput, type FetchImpl, IWebhookOutbox, MemoryWebhookOutbox, WebhookDelivery, WebhookDispatcher, WebhookOutboxPlugin, type WebhookOutboxPluginOptions, classifyAttempt, hashPartition, nextRetryDelayMs, sendOnce };
+export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn, WebhookOutboxPlugin, type WebhookOutboxPluginOptions };