@objectstack/plugin-webhooks 5.0.0 → 5.2.0

package/src/outbox.ts

@@ -0,0 +1,141 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * 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.
+ */
+
+export type DeliveryStatus =
+    | 'pending'
+    | 'in_flight'
+    | 'success'
+    | 'failed'
+    | 'dead';
+
+export 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;
+}
+
+export interface EnqueueInput {
+    webhookId: string;
+    eventId: string;
+    eventType: string;
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    secret?: string;
+    timeoutMs?: number;
+    payload: unknown;
+}
+
+export 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;
+}
+
+export interface AckSuccess {
+    success: true;
+    httpStatus: number;
+    responseBody?: string;
+    durationMs: number;
+}
+
+export 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;
+}
+
+export type AckResult = AckSuccess | AckFailure;
+
+/**
+ * Pluggable storage backend for delivery rows. Implementations MUST make
+ * `claim()` atomic across concurrent callers — that property is the
+ * exactly-once guarantee.
+ */
+export 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[]>;
+}

package/src/partition.ts

@@ -0,0 +1,19 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * 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.
+ */
+export function hashPartition(key: string, count: number): number {
+    if (count <= 0) throw new Error('partition count must be > 0');
+    let h = 0x811c9dc5;
+    for (let i = 0; i < key.length; i++) {
+        h ^= key.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return Math.abs(h | 0) % count;
+}

package/src/retention.test.ts

@@ -0,0 +1,116 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * DeliveryRetentionSweeper test.
+ *
+ * Verifies the retention policy applied to `sys_webhook_delivery`:
+ *   - success rows older than `successTtlMs` are deleted
+ *   - dead rows older than `deadTtlMs` are deleted
+ *   - pending / in_flight / failed rows are NEVER auto-pruned
+ *   - rows newer than the TTL stay
+ *   - successTtlMs=0 disables the success sweep
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { IDataEngine } from '@objectstack/spec/contracts';
+import { DeliveryRetentionSweeper } from './retention.js';
+
+class FakeEngine implements IDataEngine {
+    rows: any[] = [];
+    async find(): Promise<any[]> {
+        return this.rows;
+    }
+    async findOne(): Promise<any> {
+        return null;
+    }
+    async insert(_n: string, data: any): Promise<any> {
+        const arr = Array.isArray(data) ? data : [data];
+        for (const r of arr) this.rows.push(r);
+        return data;
+    }
+    async update(): Promise<any> {
+        return { affected: 0 };
+    }
+    async delete(_name: string, opts?: any): Promise<any> {
+        const before = this.rows.length;
+        const where = opts?.where ?? {};
+        this.rows = this.rows.filter((r) => {
+            if (where.status && r.status !== where.status) return true;
+            if (where.updated_at?.$lt != null && !(r.updated_at < where.updated_at.$lt))
+                return true;
+            return false;
+        });
+        return { affected: before - this.rows.length };
+    }
+    async count(): Promise<number> {
+        return this.rows.length;
+    }
+    async aggregate(): Promise<any[]> {
+        return [];
+    }
+}
+
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+
+describe('DeliveryRetentionSweeper', () => {
+    it('deletes old success rows past TTL', async () => {
+        const engine = new FakeEngine();
+        const now = Date.now();
+        engine.rows.push(
+            { id: 'a', status: 'success', updated_at: now - 8 * DAY },
+            { id: 'b', status: 'success', updated_at: now - 6 * DAY }, // inside TTL
+            { id: 'c', status: 'success', updated_at: now - 30 * DAY },
+        );
+        const sweeper = new DeliveryRetentionSweeper(engine, { successTtlMs: 7 * DAY });
+        const res = await sweeper.sweep(now);
+        expect(res.success).toBe(2);
+        expect(engine.rows.map((r) => r.id)).toEqual(['b']);
+    });
+
+    it('keeps pending / in_flight / failed rows regardless of age', async () => {
+        const engine = new FakeEngine();
+        const now = Date.now();
+        engine.rows.push(
+            { id: 'p', status: 'pending', updated_at: now - 100 * DAY },
+            { id: 'i', status: 'in_flight', updated_at: now - 100 * DAY },
+            { id: 'f', status: 'failed', updated_at: now - 100 * DAY },
+        );
+        const sweeper = new DeliveryRetentionSweeper(engine);
+        await sweeper.sweep(now);
+        expect(engine.rows).toHaveLength(3);
+    });
+
+    it('deletes old dead rows past deadTtlMs', async () => {
+        const engine = new FakeEngine();
+        const now = Date.now();
+        engine.rows.push(
+            { id: 'd1', status: 'dead', updated_at: now - 31 * DAY },
+            { id: 'd2', status: 'dead', updated_at: now - 29 * DAY }, // inside TTL
+        );
+        const sweeper = new DeliveryRetentionSweeper(engine, { deadTtlMs: 30 * DAY });
+        const res = await sweeper.sweep(now);
+        expect(res.dead).toBe(1);
+        expect(engine.rows.map((r) => r.id)).toEqual(['d2']);
+    });
+
+    it('successTtlMs=0 disables the success sweep', async () => {
+        const engine = new FakeEngine();
+        const now = Date.now();
+        engine.rows.push({ id: 'a', status: 'success', updated_at: now - 100 * DAY });
+        const sweeper = new DeliveryRetentionSweeper(engine, { successTtlMs: 0 });
+        const res = await sweeper.sweep(now);
+        expect(res.success).toBe(0);
+        expect(engine.rows).toHaveLength(1);
+    });
+
+    it('deadTtlMs=0 disables the dead sweep', async () => {
+        const engine = new FakeEngine();
+        const now = Date.now();
+        engine.rows.push({ id: 'd', status: 'dead', updated_at: now - 100 * DAY });
+        const sweeper = new DeliveryRetentionSweeper(engine, { deadTtlMs: 0 });
+        const res = await sweeper.sweep(now);
+        expect(res.dead).toBe(0);
+        expect(engine.rows).toHaveLength(1);
+    });
+});

package/src/retention.ts

@@ -0,0 +1,144 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { IDataEngine } from '@objectstack/spec/contracts';
+import { SYS_WEBHOOK_DELIVERY } from './schema.js';
+
+interface OptionalLogger {
+    info?(msg: string, meta?: unknown): void;
+    warn?(msg: string, meta?: unknown): void;
+    debug?(msg: string, meta?: unknown): void;
+}
+
+export 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;
+}
+
+const DEFAULTS = {
+    successTtlMs: 7 * 24 * 60 * 60 * 1000,
+    deadTtlMs: 30 * 24 * 60 * 60 * 1000,
+    sweepIntervalMs: 60 * 60 * 1000,
+};
+
+/**
+ * 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.
+ */
+export class DeliveryRetentionSweeper {
+    private readonly objectName: string;
+    private readonly successTtlMs: number;
+    private readonly deadTtlMs: number;
+    private readonly sweepIntervalMs: number;
+    private readonly logger: OptionalLogger;
+    private timer: ReturnType<typeof setInterval> | undefined;
+    private running = false;
+
+    constructor(
+        private readonly engine: IDataEngine,
+        opts: DeliveryRetentionOptions = {},
+    ) {
+        this.objectName = opts.objectName ?? SYS_WEBHOOK_DELIVERY;
+        this.successTtlMs = opts.successTtlMs ?? DEFAULTS.successTtlMs;
+        this.deadTtlMs = opts.deadTtlMs ?? DEFAULTS.deadTtlMs;
+        this.sweepIntervalMs = opts.sweepIntervalMs ?? DEFAULTS.sweepIntervalMs;
+        this.logger = opts.logger ?? {};
+    }
+
+    start(): void {
+        if (this.running) return;
+        this.running = true;
+        // First sweep deferred by one interval — let the system boot first.
+        this.timer = setInterval(() => {
+            this.sweep().catch((err) =>
+                this.logger.warn?.('[webhook-retention] sweep failed', err),
+            );
+        }, this.sweepIntervalMs);
+        this.timer.unref?.();
+    }
+
+    stop(): void {
+        if (!this.running) return;
+        this.running = false;
+        if (this.timer) clearInterval(this.timer);
+        this.timer = undefined;
+    }
+
+    /** Run one sweep immediately. Returns the number of rows deleted. */
+    async sweep(now: number = Date.now()): Promise<{ success: number; dead: number }> {
+        let successDeleted = 0;
+        let deadDeleted = 0;
+
+        if (this.successTtlMs > 0) {
+            try {
+                const res = await this.engine.delete(this.objectName, {
+                    where: {
+                        status: 'success',
+                        updated_at: { $lt: now - this.successTtlMs },
+                    },
+                });
+                successDeleted = res?.affected ?? 0;
+            } catch (err) {
+                this.logger.warn?.('[webhook-retention] success sweep failed', err);
+            }
+        }
+
+        if (this.deadTtlMs > 0) {
+            try {
+                const res = await this.engine.delete(this.objectName, {
+                    where: {
+                        status: 'dead',
+                        updated_at: { $lt: now - this.deadTtlMs },
+                    },
+                });
+                deadDeleted = res?.affected ?? 0;
+            } catch (err) {
+                this.logger.warn?.('[webhook-retention] dead sweep failed', err);
+            }
+        }
+
+        if (successDeleted + deadDeleted > 0) {
+            this.logger.info?.('[webhook-retention] sweep complete', {
+                success: successDeleted,
+                dead: deadDeleted,
+            });
+        }
+        return { success: successDeleted, dead: deadDeleted };
+    }
+}

package/src/schema.ts

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Public schema subpath: `@objectstack/plugin-webhooks/schema`.
+ *
+ * Thin re-export barrel kept stable across refactors. The actual object
+ * definition lives in `sys-webhook-delivery.object.ts` (matching the
+ * `*.object.ts` convention used everywhere else in the monorepo for
+ * `sys_*` schemas).
+ *
+ * Note: callers that just need the runtime should import from the
+ * package root (`@objectstack/plugin-webhooks`), which auto-registers
+ * `sys_webhook` + `sys_webhook_delivery` via the plugin manifest. This
+ * subpath exists for the rare case where you want the schema without
+ * installing the dispatcher plugin (e.g. read-only inspection from a
+ * different runtime).
+ */
+
+export {
+  SysWebhookDelivery,
+  SYS_WEBHOOK_DELIVERY,
+} from './sys-webhook-delivery.object.js';