@objectstack/plugin-webhooks 7.4.1 → 7.6.0

package/src/outbox.ts

@@ -1,175 +0,0 @@
-// 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;
-
-/**
- * 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`).
- */
-export class RedeliverError extends Error {
-    constructor(
-        message: string,
-        readonly code: 'not_found' | 'not_eligible',
-    ) {
-        super(message);
-        this.name = 'RedeliverError';
-    }
-}
-
-/**
- * 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[]>;
-
-    /**
-     * 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>;
-}

package/src/partition.ts

@@ -1,19 +0,0 @@
-// 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

@@ -1,116 +0,0 @@
-// 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

@@ -1,144 +0,0 @@
-// 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 };
-    }
-}