@objectstack/plugin-webhooks 7.5.0 → 7.6.0

package/dist/outbox-CIn7LSyB.d.ts

@@ -1,155 +0,0 @@
-/**
- * Webhook outbox contracts.
- *
- * The outbox stores webhook delivery rows that must be POSTed exactly once
- * (modulo at-least-once + receiver-side idempotency). Implementations are
- * pluggable so the same dispatcher can run against an in-memory test store
- * or a SQL-backed production table.
- *
- * See `content/docs/concepts/webhook-delivery.mdx` §3.2 for the full schema.
- */
-type DeliveryStatus = 'pending' | 'in_flight' | 'success' | 'failed' | 'dead';
-interface WebhookDelivery {
-    /** UUID — also doubles as the receiver-side idempotency key. */
-    id: string;
-    /** FK to sys_webhook.id — opaque to the dispatcher; only used for hashing. */
-    webhookId: string;
-    /** Origin event id. UNIQUE(event_id, webhook_id) prevents double-enqueue. */
-    eventId: string;
-    /** Origin event type, e.g. `data.record.created`. */
-    eventType: string;
-    /** Destination URL (snapshotted on enqueue — config edits don't rewrite live rows). */
-    url: string;
-    /** HTTP method — defaults to POST. */
-    method?: string;
-    /** Custom headers configured on the sink. */
-    headers?: Record<string, string>;
-    /** HMAC-SHA256 secret. If present, signature is added. */
-    secret?: string;
-    /** Per-request timeout in ms. */
-    timeoutMs?: number;
-    /** JSON-serialisable body. */
-    payload: unknown;
-    /** Lifecycle state. */
-    status: DeliveryStatus;
-    /** Number of POST attempts made so far (0 before first attempt). */
-    attempts: number;
-    /** Node id currently working on this row, when `status = in_flight`. */
-    claimedBy?: string;
-    /** Wall-clock ms when the row was claimed. */
-    claimedAt?: number;
-    /** Earliest ms at which this row becomes eligible for the next attempt. */
-    nextRetryAt?: number;
-    /** Wall-clock ms of the last attempt (success or fail). */
-    lastAttemptedAt?: number;
-    /** HTTP status code from the most recent attempt. */
-    responseCode?: number;
-    /** Truncated response body for diagnostics. */
-    responseBody?: string;
-    /** Last transport / timeout error message. */
-    error?: string;
-    createdAt: number;
-    updatedAt: number;
-}
-interface EnqueueInput {
-    webhookId: string;
-    eventId: string;
-    eventType: string;
-    url: string;
-    method?: string;
-    headers?: Record<string, string>;
-    secret?: string;
-    timeoutMs?: number;
-    payload: unknown;
-}
-interface ClaimOptions {
-    /** Identifier of the node doing the claim (for `claimedBy`). */
-    nodeId: string;
-    /** Max rows to claim per call. */
-    limit: number;
-    /**
-     * Partition assignment for this worker. Only rows whose
-     * `hash(webhookId) mod count === index` are claimed. Omit to claim
-     * across all partitions (single-node mode).
-     */
-    partition?: {
-        index: number;
-        count: number;
-    };
-    /** Visibility timeout — claimed rows revert to pending after this many ms. */
-    claimTtlMs: number;
-    /** "Now" reference, ms since epoch. Defaults to Date.now(). */
-    now?: number;
-}
-interface AckSuccess {
-    success: true;
-    httpStatus: number;
-    responseBody?: string;
-    durationMs: number;
-}
-interface AckFailure {
-    success: false;
-    httpStatus?: number;
-    responseBody?: string;
-    error?: string;
-    durationMs: number;
-    /** Computed by the dispatcher per the retry schedule, or undefined for dead. */
-    nextRetryAt?: number;
-    /** Marks the row terminal — no more attempts. */
-    dead?: boolean;
-}
-type AckResult = AckSuccess | AckFailure;
-/**
- * Error raised by `IWebhookOutbox.redeliver` when the requested row is
- * either missing or in a non-terminal state. The dispatcher / admin UI
- * surfaces this verbatim to the caller — never throw it for transient
- * conditions (transport errors should bubble as native `Error`).
- */
-declare class RedeliverError extends Error {
-    readonly code: 'not_found' | 'not_eligible';
-    constructor(message: string, code: 'not_found' | 'not_eligible');
-}
-/**
- * Pluggable storage backend for delivery rows. Implementations MUST make
- * `claim()` atomic across concurrent callers — that property is the
- * exactly-once guarantee.
- */
-interface IWebhookOutbox {
-    /**
-     * Insert a new delivery row. Implementations MUST treat
-     * `(eventId, webhookId)` as unique and silently drop duplicates.
-     * Returns the row id (existing or new).
-     */
-    enqueue(input: EnqueueInput): Promise<string>;
-    /**
-     * Atomically claim up to `limit` rows whose `nextRetryAt <= now` (or
-     * null) and matching the partition predicate. Claimed rows MUST be
-     * marked `in_flight` so concurrent claimers don't see them.
-     */
-    claim(opts: ClaimOptions): Promise<WebhookDelivery[]>;
-    /** Record the outcome of an attempt. */
-    ack(id: string, result: AckResult): Promise<void>;
-    /** Snapshot accessor for tests / admin tooling. */
-    list(filter?: {
-        status?: DeliveryStatus;
-    }): Promise<WebhookDelivery[]>;
-    /**
-     * Reset a terminal row back to `pending` so the dispatcher will pick
-     * it up again on its next tick.
-     *
-     * - Eligible source states: `success`, `failed`, `dead`.
-     * - Rejects `pending` / `in_flight` rows — replaying those would
-     *   double-deliver because they're either already queued or actively
-     *   being sent.
-     * - Resets `attempts=0` so the retry budget restarts.
-     * - Clears `claimed_by`, `claimed_at`, `next_retry_at`, `error`,
-     *   `response_code`, `response_body`. URL / payload / secret are NOT
-     *   touched — replay reproduces the original POST byte-for-byte.
-     *
-     * Throws `RedeliverError` with code `not_found` or `not_eligible`.
-     * Returns the post-reset row.
-     */
-    redeliver(id: string): Promise<WebhookDelivery>;
-}
-
-export { type AckFailure as A, type ClaimOptions as C, type DeliveryStatus as D, type EnqueueInput as E, type IWebhookOutbox as I, RedeliverError as R, type WebhookDelivery as W, type AckResult as a, type AckSuccess as b };

package/dist/sql-outbox.cjs

@@ -1,8 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});
-
-var _chunkHF7CCDPBcjs = require('./chunk-HF7CCDPB.cjs');
-require('./chunk-TDSI7UHY.cjs');
-
-
-exports.SqlWebhookOutbox = _chunkHF7CCDPBcjs.SqlWebhookOutbox;
-//# sourceMappingURL=sql-outbox.cjs.map

package/dist/sql-outbox.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/home/runner/work/framework/framework/packages/plugins/plugin-webhooks/dist/sql-outbox.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B;AACE;AACF,8DAAC","file":"/home/runner/work/framework/framework/packages/plugins/plugin-webhooks/dist/sql-outbox.cjs"}

package/dist/sql-outbox.d.cts

@@ -1,55 +0,0 @@
-import { IDataEngine } from '@objectstack/spec/contracts';
-import { I as IWebhookOutbox, E as EnqueueInput, C as ClaimOptions, W as WebhookDelivery, a as AckResult, D as DeliveryStatus } from './outbox-CIn7LSyB.cjs';
-
-interface SqlWebhookOutboxOptions {
-    /**
-     * Total partition count — MUST match the dispatcher's `partitionCount`.
-     * Used at enqueue time to precompute `partition_key`.
-     */
-    partitionCount: number;
-    /**
-     * Object name to read/write. Defaults to `sys_webhook_delivery`. Override
-     * only if you've registered the schema under a different name.
-     */
-    objectName?: string;
-}
-/**
- * Durable `IWebhookOutbox` backed by ObjectQL — the production storage
- * impl. Works against any registered driver (SQL, Turso, Mongo, in-memory)
- * because everything goes through the driver-agnostic `IDataEngine` API.
- *
- * **Why no `FOR UPDATE SKIP LOCKED`?** ObjectQL is driver-agnostic — that
- * SQL feature is Postgres-only. We get equivalent safety from two layers:
- *
- *   1. `cluster.lock` held per partition by the dispatcher (the primary
- *      mutex). One node owns one partition at a time → no two claimers.
- *   2. Atomic `UPDATE WHERE status='pending'` (the backup). Even if two
- *      claimers slip through (e.g. admin reschedule + dispatcher), only
- *      the first UPDATE matches each row.
- *
- * **Why precompute `partition_key` on enqueue?** ObjectQL has no
- * cross-driver `hash()` function in WHERE clauses. Storing the partition
- * as a column makes the claim query a plain indexed lookup.
- *
- * **Dedup race**: SELECT-then-INSERT has a tiny window where two
- * concurrent producers both miss the SELECT and both INSERT. The unique
- * index `(event_id, webhook_id)` on the table catches it — the second
- * INSERT errors, the producer ignores it. Receivers MUST be idempotent
- * on the `X-Objectstack-Delivery` header anyway.
- */
-declare class SqlWebhookOutbox implements IWebhookOutbox {
-    private readonly engine;
-    private readonly objectName;
-    private readonly partitionCount;
-    constructor(engine: IDataEngine, opts: SqlWebhookOutboxOptions);
-    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>;
-    private toDelivery;
-}
-
-export { SqlWebhookOutbox, type SqlWebhookOutboxOptions };

package/dist/sql-outbox.d.ts

@@ -1,55 +0,0 @@
-import { IDataEngine } from '@objectstack/spec/contracts';
-import { I as IWebhookOutbox, E as EnqueueInput, C as ClaimOptions, W as WebhookDelivery, a as AckResult, D as DeliveryStatus } from './outbox-CIn7LSyB.js';
-
-interface SqlWebhookOutboxOptions {
-    /**
-     * Total partition count — MUST match the dispatcher's `partitionCount`.
-     * Used at enqueue time to precompute `partition_key`.
-     */
-    partitionCount: number;
-    /**
-     * Object name to read/write. Defaults to `sys_webhook_delivery`. Override
-     * only if you've registered the schema under a different name.
-     */
-    objectName?: string;
-}
-/**
- * Durable `IWebhookOutbox` backed by ObjectQL — the production storage
- * impl. Works against any registered driver (SQL, Turso, Mongo, in-memory)
- * because everything goes through the driver-agnostic `IDataEngine` API.
- *
- * **Why no `FOR UPDATE SKIP LOCKED`?** ObjectQL is driver-agnostic — that
- * SQL feature is Postgres-only. We get equivalent safety from two layers:
- *
- *   1. `cluster.lock` held per partition by the dispatcher (the primary
- *      mutex). One node owns one partition at a time → no two claimers.
- *   2. Atomic `UPDATE WHERE status='pending'` (the backup). Even if two
- *      claimers slip through (e.g. admin reschedule + dispatcher), only
- *      the first UPDATE matches each row.
- *
- * **Why precompute `partition_key` on enqueue?** ObjectQL has no
- * cross-driver `hash()` function in WHERE clauses. Storing the partition
- * as a column makes the claim query a plain indexed lookup.
- *
- * **Dedup race**: SELECT-then-INSERT has a tiny window where two
- * concurrent producers both miss the SELECT and both INSERT. The unique
- * index `(event_id, webhook_id)` on the table catches it — the second
- * INSERT errors, the producer ignores it. Receivers MUST be idempotent
- * on the `X-Objectstack-Delivery` header anyway.
- */
-declare class SqlWebhookOutbox implements IWebhookOutbox {
-    private readonly engine;
-    private readonly objectName;
-    private readonly partitionCount;
-    constructor(engine: IDataEngine, opts: SqlWebhookOutboxOptions);
-    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>;
-    private toDelivery;
-}
-
-export { SqlWebhookOutbox, type SqlWebhookOutboxOptions };

package/dist/sql-outbox.js

@@ -1,8 +0,0 @@
-import {
-  SqlWebhookOutbox
-} from "./chunk-KNGLLSSP.js";
-import "./chunk-7HS5DLU2.js";
-export {
-  SqlWebhookOutbox
-};
-//# sourceMappingURL=sql-outbox.js.map

package/dist/sql-outbox.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/src/dispatcher.test.ts

@@ -1,324 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Cross-node webhook dispatcher contract test.
- *
- * Builds two `WebhookDispatcher` instances that share one in-memory outbox
- * AND one cluster `ILock`/`IPubSub` (simulating two nodes sharing one
- * Redis/Postgres). Asserts:
- *
- *   1. Every enqueued delivery is POSTed *exactly once* (no double-fire).
- *   2. Work is distributed across both nodes (no starvation).
- *   3. 5xx responses are retried per the Stripe-style schedule.
- *   4. 4xx (permanent) responses go straight to `dead`.
- */
-
-import { describe, expect, it } from 'vitest';
-import {
-    ComposedClusterService,
-    MemoryCounter,
-    MemoryKV,
-    MemoryLock,
-    MemoryPubSub,
-} from '@objectstack/service-cluster';
-import type { IClusterService } from '@objectstack/spec/contracts';
-import { WebhookDispatcher } from './dispatcher.js';
-import type { FetchImpl } from './http-sender.js';
-import { MemoryWebhookOutbox } from './memory-outbox.js';
-import { hashPartition } from './partition.js';
-
-interface SharedCluster {
-    nodeA: IClusterService;
-    nodeB: IClusterService;
-}
-
-function makeSharedCluster(): SharedCluster {
-    // ONE lock + pubsub shared by both "nodes" — this is what makes the test
-    // a realistic cross-node simulation.
-    const lock = new MemoryLock();
-    const pubsub = new MemoryPubSub();
-    const kv = new MemoryKV();
-    const counter = new MemoryCounter();
-    return {
-        nodeA: new ComposedClusterService('node-A', 'memory', pubsub, lock, kv, counter),
-        nodeB: new ComposedClusterService('node-B', 'memory', pubsub, lock, kv, counter),
-    };
-}
-
-function makeFetchImpl(opts: {
-    status?: number;
-    log?: { url: string; deliveryId: string }[];
-}): FetchImpl {
-    const status = opts.status ?? 200;
-    return async (url, init) => {
-        opts.log?.push({
-            url,
-            deliveryId: init.headers['X-Objectstack-Delivery'] ?? '',
-        });
-        return {
-            ok: status >= 200 && status < 300,
-            status,
-            async text() {
-                return '';
-            },
-        };
-    };
-}
-
-async function flushTicks(...dispatchers: WebhookDispatcher[]): Promise<void> {
-    // Run several rounds with the nodes ticking *concurrently* so they
-    // genuinely contend for the cluster lock — sequential ticks would let
-    // whichever node ran first drain every partition.
-    for (let round = 0; round < 6; round++) {
-        await Promise.all(dispatchers.map((d) => d.tick()));
-    }
-}
-
-describe('WebhookDispatcher cross-node', () => {
-    it('exactly-once: 50 deliveries across 2 nodes → 50 POSTs total', async () => {
-        const cluster = makeSharedCluster();
-        const outbox = new MemoryWebhookOutbox();
-        const log: { url: string; deliveryId: string }[] = [];
-        const fetchImpl = makeFetchImpl({ status: 200, log });
-
-        const partitionCount = 4;
-        const a = new WebhookDispatcher({
-            nodeId: 'node-A',
-            cluster: cluster.nodeA,
-            outbox,
-            fetchImpl,
-            partitionCount,
-            intervalMs: 1_000_000, // disable timer; we drive with tick()
-        });
-        const b = new WebhookDispatcher({
-            nodeId: 'node-B',
-            cluster: cluster.nodeB,
-            outbox,
-            fetchImpl,
-            partitionCount,
-            intervalMs: 1_000_000,
-        });
-
-        for (let i = 0; i < 50; i++) {
-            await outbox.enqueue({
-                webhookId: `wh-${i % 10}`, // 10 webhooks → spread across 4 partitions
-                eventId: `evt-${i}`,
-                eventType: 'data.record.created',
-                url: `https://example.test/${i}`,
-                payload: { i },
-            });
-        }
-
-        await flushTicks(a, b);
-
-        expect(log).toHaveLength(50);
-        const uniqueIds = new Set(log.map((l) => l.deliveryId));
-        expect(uniqueIds.size).toBe(50);
-
-        const success = await outbox.list({ status: 'success' });
-        expect(success).toHaveLength(50);
-    });
-
-    it('partition affinity: dispatcher only claims rows for partitions it locked', async () => {
-        const cluster = makeSharedCluster();
-        const outbox = new MemoryWebhookOutbox();
-        const partitionCount = 8;
-
-        // For each attempt, record (nodeId, partitionForWebhook).
-        const observed: { nodeId: string; partition: number }[] = [];
-
-        const make = (nodeId: string, c: IClusterService) =>
-            new WebhookDispatcher({
-                nodeId,
-                cluster: c,
-                outbox,
-                fetchImpl: makeFetchImpl({ status: 200 }),
-                partitionCount,
-                intervalMs: 1_000_000,
-                onAttempt: (delivery) => {
-                    observed.push({
-                        nodeId,
-                        partition: hashPartition(delivery.webhookId, partitionCount),
-                    });
-                },
-            });
-
-        const a = make('node-A', cluster.nodeA);
-        const b = make('node-B', cluster.nodeB);
-
-        for (let i = 0; i < 30; i++) {
-            await outbox.enqueue({
-                webhookId: `wh-${i % 5}`,
-                eventId: `evt-${i}`,
-                eventType: 't',
-                url: 'https://example.test/x',
-                payload: { i },
-            });
-        }
-        await flushTicks(a, b);
-
-        expect(observed).toHaveLength(30);
-        // Each row's partition came from hash(webhookId, 8) — only 5 distinct
-        // webhook ids → at most 5 distinct partitions.
-        const partitionsTouched = new Set(observed.map((o) => o.partition));
-        expect(partitionsTouched.size).toBeLessThanOrEqual(5);
-    });
-
-    it('load distribution: both nodes process some rows', async () => {
-        const cluster = makeSharedCluster();
-        const outbox = new MemoryWebhookOutbox();
-        const partitionCount = 8;
-        const counts: Record<string, number> = { 'node-A': 0, 'node-B': 0 };
-
-        const make = (nodeId: string, c: IClusterService) =>
-            new WebhookDispatcher({
-                nodeId,
-                cluster: c,
-                outbox,
-                fetchImpl: makeFetchImpl({ status: 200 }),
-                partitionCount,
-                intervalMs: 1_000_000,
-                onAttempt: () => {
-                    counts[nodeId] += 1;
-                },
-            });
-
-        const a = make('node-A', cluster.nodeA);
-        const b = make('node-B', cluster.nodeB);
-
-        // Lots of distinct webhookIds → spreads work across many partitions.
-        for (let i = 0; i < 200; i++) {
-            await outbox.enqueue({
-                webhookId: `wh-${i}`,
-                eventId: `evt-${i}`,
-                eventType: 't',
-                url: 'https://example.test/x',
-                payload: { i },
-            });
-        }
-        await flushTicks(a, b);
-
-        // Each node should have processed at least one row — proving the
-        // rotation/offset isn't pinning all work to node A.
-        expect(counts['node-A']).toBeGreaterThan(0);
-        expect(counts['node-B']).toBeGreaterThan(0);
-        expect(counts['node-A'] + counts['node-B']).toBe(200);
-    });
-
-    it('5xx is retried: row stays pending with future nextRetryAt', async () => {
-        const cluster = makeSharedCluster();
-        const outbox = new MemoryWebhookOutbox();
-        const a = new WebhookDispatcher({
-            nodeId: 'node-A',
-            cluster: cluster.nodeA,
-            outbox,
-            fetchImpl: makeFetchImpl({ status: 503 }),
-            partitionCount: 1,
-            intervalMs: 1_000_000,
-            rng: () => 0.5,
-        });
-
-        await outbox.enqueue({
-            webhookId: 'wh-x',
-            eventId: 'evt-x',
-            eventType: 't',
-            url: 'https://example.test/fail',
-            payload: {},
-        });
-
-        await a.tick();
-        const rows = await outbox.list();
-        expect(rows[0].status).toBe('pending');
-        expect(rows[0].attempts).toBe(1);
-        expect(rows[0].nextRetryAt).toBeGreaterThan(Date.now());
-    });
-
-    it('4xx is permanent: row moves to dead', async () => {
-        const cluster = makeSharedCluster();
-        const outbox = new MemoryWebhookOutbox();
-        const a = new WebhookDispatcher({
-            nodeId: 'node-A',
-            cluster: cluster.nodeA,
-            outbox,
-            fetchImpl: makeFetchImpl({ status: 404 }),
-            partitionCount: 1,
-            intervalMs: 1_000_000,
-        });
-
-        await outbox.enqueue({
-            webhookId: 'wh-x',
-            eventId: 'evt-x',
-            eventType: 't',
-            url: 'https://example.test/missing',
-            payload: {},
-        });
-
-        await a.tick();
-        const dead = await outbox.list({ status: 'dead' });
-        expect(dead).toHaveLength(1);
-        expect(dead[0].responseCode).toBe(404);
-    });
-
-    it('dedup: identical (eventId, webhookId) enqueues collapse to one row', async () => {
-        const outbox = new MemoryWebhookOutbox();
-        const id1 = await outbox.enqueue({
-            webhookId: 'wh-1',
-            eventId: 'evt-dup',
-            eventType: 't',
-            url: 'https://example.test/',
-            payload: {},
-        });
-        const id2 = await outbox.enqueue({
-            webhookId: 'wh-1',
-            eventId: 'evt-dup',
-            eventType: 't',
-            url: 'https://example.test/',
-            payload: {},
-        });
-        expect(id1).toBe(id2);
-        const rows = await outbox.list();
-        expect(rows).toHaveLength(1);
-    });
-
-    it('lock prevents same partition being claimed twice in a tick', async () => {
-        const cluster = makeSharedCluster();
-        const outbox = new MemoryWebhookOutbox();
-        const log: { url: string; deliveryId: string }[] = [];
-        const fetchImpl = makeFetchImpl({ status: 200, log });
-
-        // Single partition → both nodes contend for the same lock.
-        const a = new WebhookDispatcher({
-            nodeId: 'node-A',
-            cluster: cluster.nodeA,
-            outbox,
-            fetchImpl,
-            partitionCount: 1,
-            intervalMs: 1_000_000,
-        });
-        const b = new WebhookDispatcher({
-            nodeId: 'node-B',
-            cluster: cluster.nodeB,
-            outbox,
-            fetchImpl,
-            partitionCount: 1,
-            intervalMs: 1_000_000,
-        });
-
-        for (let i = 0; i < 5; i++) {
-            await outbox.enqueue({
-                webhookId: 'wh-1',
-                eventId: `evt-${i}`,
-                eventType: 't',
-                url: 'https://example.test/',
-                payload: { i },
-            });
-        }
-
-        // Fire both ticks "simultaneously" — only one should claim the partition.
-        await Promise.all([a.tick(), b.tick()]);
-
-        expect(log).toHaveLength(5);
-        const uniqueIds = new Set(log.map((l) => l.deliveryId));
-        expect(uniqueIds.size).toBe(5);
-    });
-});