@objectstack/plugin-webhooks 16.1.0 → 17.0.0-rc.1

package/src/auto-enqueuer.ts

@@ -1,383 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { IDataEngine, IRealtimeService, RealtimeEventPayload } from '@objectstack/spec/contracts';
-import type { EnqueueHttpInput } from '@objectstack/service-messaging';
-
-/**
- * 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.
- */
-export type HttpEnqueueFn = (input: EnqueueHttpInput) => Promise<string>;
-
-/**
- * Optional logger interface (subset of console / kernel logger).
- */
-interface OptionalLogger {
-    info?(msg: string, meta?: unknown): void;
-    warn?(msg: string, meta?: unknown): void;
-    debug?(msg: string, meta?: unknown): void;
-    error?(msg: string, err?: unknown, meta?: unknown): void;
-}
-
-/**
- * Per-row subscription cached in memory. Mirrors a subset of the
- * `sys_webhook` object — only what the auto-enqueuer needs to match an
- * event and build an `EnqueueInput`.
- */
-interface CachedSubscription {
-    id: string;
-    name: string;
-    objectName: string | undefined; // empty = matches all objects
-    triggers: Set<'create' | 'update' | 'delete'>;
-    url: string;
-    method?: string;
-    headers?: Record<string, string>;
-    secret?: string;
-    timeoutMs?: number;
-}
-
-export interface AutoEnqueuerOptions {
-    /**
-     * Object name holding webhook subscriptions. Defaults to `sys_webhook`,
-     * the platform-objects schema authored in apps.
-     */
-    subscriptionsObject?: string;
-
-    /**
-     * Periodic full-cache refresh interval (ms). Belt-and-braces in case
-     * the subscription-change event is missed. Default 60s.
-     */
-    refreshIntervalMs?: number;
-
-    logger?: OptionalLogger;
-}
-
-/**
- * Bridge between `IRealtimeService` (`data.record.*` events emitted by
- * the engine) and `IWebhookOutbox` (durable delivery rows the dispatcher
- * picks up).
- *
- * ## Why a separate class
- * Keeps `WebhookOutboxPlugin` lean: the plugin wires services, this
- * class owns the runtime fan-out logic + subscription cache.
- *
- * ## Hot path
- * Every `engine.insert/update/delete` fires a `data.record.*` event.
- * The handler:
- *   1. Looks up matching subscriptions in an in-memory `Map<object, sub[]>`
- *      — O(1) per event, no DB hit on the write path.
- *   2. Calls `outbox.enqueue()` fire-and-forget for each match. The
- *      enqueue itself is a single INSERT, which runs *after* the user's
- *      request has already returned.
- *
- * Net cost on the write path: one synchronous Map lookup (~microseconds).
- *
- * ## Cache freshness
- * The cache is rebuilt:
- *   1. Once on `start()`.
- *   2. On every `data.record.{created,updated,deleted}` event whose
- *      object is `sys_webhook` (self-healing — when a user toggles a
- *      webhook, the handler refreshes the cache before returning).
- *   3. Periodically (default 60s) as belt-and-braces.
- *
- * For multi-node clusters this is *eventually consistent* — node B may
- * not see node A's edit for up to one cycle. That's acceptable for
- * webhook configuration changes (humans don't expect millisecond
- * propagation) and matches Hasura's behaviour.
- *
- * ## Determinism
- * `eventId` is computed from `${object}:${recordId}:${type}:${timestamp}`
- * so the outbox dedup index catches duplicates that could arise from
- * upstream replay or buggy producers — and is stable across nodes.
- */
-export class AutoEnqueuer {
-    private readonly subscriptions = new Map<string, CachedSubscription[]>();
-    private readonly subscriptionsObject: string;
-    private readonly refreshIntervalMs: number;
-    private readonly logger: OptionalLogger;
-    private subId: string | undefined;
-    private subIdSelfHeal: string | undefined;
-    private refreshTimer: ReturnType<typeof setInterval> | undefined;
-    private running = false;
-    private refreshing: Promise<void> | undefined;
-
-    constructor(
-        private readonly engine: IDataEngine,
-        private readonly realtime: IRealtimeService,
-        private readonly enqueue: HttpEnqueueFn,
-        opts: AutoEnqueuerOptions = {},
-    ) {
-        this.subscriptionsObject = opts.subscriptionsObject ?? 'sys_webhook';
-        this.refreshIntervalMs = opts.refreshIntervalMs ?? 60_000;
-        this.logger = opts.logger ?? {};
-    }
-
-    /**
-     * Load the subscription cache and start listening for events.
-     */
-    async start(): Promise<void> {
-        if (this.running) return;
-        this.running = true;
-
-        await this.refresh();
-
-        // Main subscription: every data event → match → enqueue.
-        this.subId = await this.realtime.subscribe(
-            'webhook-auto-enqueuer',
-            (event) => this.handleEvent(event),
-        );
-
-        // Self-healing: any change to sys_webhook refreshes the cache.
-        this.subIdSelfHeal = await this.realtime.subscribe(
-            'webhook-auto-enqueuer-self-heal',
-            (event) => this.handleSelfHealEvent(event),
-            { object: this.subscriptionsObject },
-        );
-
-        if (this.refreshIntervalMs > 0) {
-            this.refreshTimer = setInterval(() => {
-                this.refresh().catch((err) =>
-                    this.logger.warn?.('[webhook-auto-enqueuer] periodic refresh failed', err),
-                );
-            }, this.refreshIntervalMs);
-            // Don't keep the process alive solely for this timer.
-            this.refreshTimer.unref?.();
-        }
-    }
-
-    async stop(): Promise<void> {
-        if (!this.running) return;
-        this.running = false;
-        if (this.subId) await this.realtime.unsubscribe(this.subId);
-        if (this.subIdSelfHeal) await this.realtime.unsubscribe(this.subIdSelfHeal);
-        if (this.refreshTimer) clearInterval(this.refreshTimer);
-        this.subId = undefined;
-        this.subIdSelfHeal = undefined;
-        this.refreshTimer = undefined;
-    }
-
-    /**
-     * Force-refresh the subscription cache from storage. Concurrent
-     * callers share a single in-flight refresh.
-     */
-    async refresh(): Promise<void> {
-        if (this.refreshing) return this.refreshing;
-        this.refreshing = this.doRefresh().finally(() => {
-            this.refreshing = undefined;
-        });
-        return this.refreshing;
-    }
-
-    private async doRefresh(): Promise<void> {
-        let rows: any[];
-        try {
-            rows = await this.engine.find(this.subscriptionsObject, {
-                where: { active: true },
-            });
-        } catch (err) {
-            this.logger.warn?.(
-                `[webhook-auto-enqueuer] failed to load ${this.subscriptionsObject}`,
-                err,
-            );
-            return;
-        }
-
-        const next = new Map<string, CachedSubscription[]>();
-        for (const row of rows) {
-            const sub = this.parseRow(row);
-            if (!sub) continue;
-            // Empty objectName == "any object" → indexed under '*'.
-            const key = sub.objectName ?? '*';
-            const arr = next.get(key) ?? [];
-            arr.push(sub);
-            next.set(key, arr);
-        }
-
-        this.subscriptions.clear();
-        for (const [k, v] of next) this.subscriptions.set(k, v);
-
-        this.logger.debug?.('[webhook-auto-enqueuer] cache refreshed', {
-            objects: this.subscriptions.size,
-            rows: rows.length,
-        });
-    }
-
-    private parseRow(row: any): CachedSubscription | null {
-        if (!row?.id || !row?.url) return null;
-        // `triggers` is now authored as a multi-select (stored as an array), but
-        // legacy rows stored a comma-separated string (and some drivers hand a
-        // JSON-encoded array back as a string). Accept all three shapes so a
-        // schema change never silently drops a subscription's events.
-        const rawTriggers = row.triggers;
-        let triggerList: string[];
-        if (Array.isArray(rawTriggers)) {
-            triggerList = rawTriggers.map((t) => String(t));
-        } else {
-            const s = String(rawTriggers ?? '').trim();
-            if (s.startsWith('[')) {
-                try {
-                    const parsed = JSON.parse(s);
-                    triggerList = Array.isArray(parsed) ? parsed.map((t) => String(t)) : [s];
-                } catch {
-                    triggerList = s.split(',');
-                }
-            } else {
-                triggerList = s.split(',');
-            }
-        }
-        const normalized = triggerList.map((t) => t.trim().toLowerCase()).filter(Boolean);
-        // [#3196] Drop (and warn about) any trigger the enqueuer can't map to an
-        // emitted record event — e.g. a legacy `sys_webhook` row authored with
-        // the now-removed `undelete`/`api` values, which would otherwise sit in
-        // the cache matching nothing. A loud drift-guard so a dead trigger can't
-        // silently no-op again.
-        const unknown = normalized.filter((t) => !DISPATCHABLE_WEBHOOK_TRIGGERS.has(t));
-        if (unknown.length > 0) {
-            this.logger.warn?.(
-                `[webhook-auto-enqueuer] webhook '${(row.name as string) ?? row.id}' declares trigger(s) the engine never emits: ` +
-                    `${unknown.join(', ')} — ignored. Dispatchable triggers: create, update, delete.`,
-                { id: row.id, unknown },
-            );
-        }
-        const triggers = new Set(
-            normalized.filter((t) => DISPATCHABLE_WEBHOOK_TRIGGERS.has(t)) as Array<'create' | 'update' | 'delete'>,
-        );
-        if (triggers.size === 0) {
-            // No dispatchable triggers (or a manual-only webhook with none) —
-            // skip auto-enqueue.
-            return null;
-        }
-
-        // The "definition_json" field carries advanced config (headers,
-        // secret, timeout); attempt a best-effort parse. Fall back to
-        // top-level fields where present.
-        let defn: Record<string, any> = {};
-        if (typeof row.definition_json === 'string' && row.definition_json.length > 0) {
-            try {
-                defn = JSON.parse(row.definition_json) ?? {};
-            } catch {
-                defn = {};
-            }
-        }
-
-        return {
-            id: row.id as string,
-            name: (row.name as string) ?? row.id,
-            objectName: row.object_name ? String(row.object_name) : undefined,
-            triggers,
-            url: String(row.url),
-            // Method is authored via a select whose option values are lowercased
-            // (get/post/…); upper-case here so delivery uses a canonical HTTP
-            // method regardless of whether the row was authored before or after
-            // the select change (legacy rows stored 'POST').
-            method: String(row.method ?? defn.method ?? 'POST').toUpperCase(),
-            headers: defn.headers,
-            secret: defn.secret,
-            timeoutMs: defn.timeoutMs,
-        };
-    }
-
-    /**
-     * Handler for the firehose subscription.
-     *
-     * NOTE: we intentionally `void` the inner enqueue() so the realtime
-     * publisher (and therefore the user's request) is never blocked on
-     * webhook persistence.
-     */
-    private handleEvent(event: RealtimeEventPayload): void {
-        if (!event.type?.startsWith('data.record.')) return;
-        if (!event.object) return;
-        if (event.object === this.subscriptionsObject) return; // self-heal handles its own
-
-        const action = event.type.slice('data.record.'.length) as
-            | 'created' | 'updated' | 'deleted' | string;
-        const trigger = mapActionToTrigger(action);
-        if (!trigger) return;
-
-        const subs = [
-            ...(this.subscriptions.get(event.object) ?? []),
-            ...(this.subscriptions.get('*') ?? []),
-        ];
-        if (subs.length === 0) return;
-
-        const payload = event.payload ?? {};
-        const recordId =
-            (payload as any).recordId ??
-            (payload as any).id ??
-            (payload as any).after?.id ??
-            (payload as any).before?.id ??
-            'unknown';
-
-        // Deterministic eventId — same input on any node → same id.
-        // Includes timestamp so two distinct updates to the same record
-        // don't accidentally dedup.
-        const eventId = `${event.object}:${recordId}:${action}:${event.timestamp}`;
-
-        for (const sub of subs) {
-            if (!sub.triggers.has(trigger)) continue;
-
-            // Fire-and-forget — never await on the hot path. Map the webhook
-            // delivery onto the generic HTTP-outbox shape (ADR-0018 M3):
-            //  - source 'webhook' + dedupKey '<webhookId>:<eventId>' preserves
-            //    the old (event_id, webhook_id) at-most-once enqueue;
-            //  - refId = webhookId keeps per-webhook partition affinity / ordering;
-            //  - label = event type → X-Objectstack-Event header.
-            void this.enqueue({
-                source: 'webhook',
-                refId: sub.id,
-                dedupKey: `${sub.id}:${eventId}`,
-                label: event.type,
-                url: sub.url,
-                method: sub.method,
-                headers: sub.headers,
-                signingSecret: sub.secret,
-                timeoutMs: sub.timeoutMs,
-                payload: {
-                    object: event.object,
-                    recordId,
-                    action,
-                    timestamp: event.timestamp,
-                    ...payload,
-                },
-            }).catch((err) =>
-                this.logger.warn?.('[webhook-auto-enqueuer] enqueue failed', {
-                    webhook: sub.name,
-                    eventId,
-                    err: (err as Error)?.message ?? err,
-                }),
-            );
-        }
-    }
-
-    private handleSelfHealEvent(event: RealtimeEventPayload): void {
-        if (event.object !== this.subscriptionsObject) return;
-        if (!event.type?.startsWith('data.record.')) return;
-        this.refresh().catch((err) =>
-            this.logger.warn?.('[webhook-auto-enqueuer] self-heal refresh failed', err),
-        );
-    }
-
-    /** Test / admin accessor. */
-    snapshot(): ReadonlyMap<string, ReadonlyArray<CachedSubscription>> {
-        return this.subscriptions;
-    }
-}
-
-function mapActionToTrigger(
-    action: string,
-): 'create' | 'update' | 'delete' | null {
-    switch (action) {
-        case 'created':
-            return 'create';
-        case 'updated':
-            return 'update';
-        case 'deleted':
-            return 'delete';
-        default:
-            return null;
-    }
-}
-
-/** The trigger values the enqueuer can actually map from an emitted record event. */
-const DISPATCHABLE_WEBHOOK_TRIGGERS: ReadonlySet<string> = new Set(['create', 'update', 'delete']);

package/src/index.ts

@@ -1,29 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * @objectstack/plugin-webhooks
- *
- * Webhook fan-out on top of the shared outbound-HTTP delivery substrate
- * (ADR-0018 M3). The durable outbox, cluster-coordinated dispatcher, retry /
- * backoff / dead-letter, and retention all live in
- * `@objectstack/service-messaging` (`sys_http_delivery` + `HttpDispatcher`).
- *
- * This package ships only the webhook-specific concerns:
- *   - the `sys_webhook` configuration object,
- *   - the {@link AutoEnqueuer} that turns `data.record.*` events into outbox
- *     rows (`source: 'webhook'`),
- *   - the redeliver admin endpoint.
- *
- * **Requires** `MessagingServicePlugin` (a foundational, always-on capability).
- *
- * ## Subpath exports
- * - `@objectstack/plugin-webhooks/schema` — `SysWebhook` object schema.
- */
-
-export {
-    WebhookOutboxPlugin,
-    type WebhookOutboxPluginOptions,
-} from './webhook-outbox-plugin.js';
-
-export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn } from './auto-enqueuer.js';
-export { SysWebhook } from './sys-webhook.object.js';

package/src/schema.ts

@@ -1,21 +0,0 @@
-// 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 object definition
- * lives in `sys-webhook.object.ts` (matching the `*.object.ts` convention used
- * everywhere else in the monorepo for `sys_*` schemas).
- *
- * `sys_webhook` moved here from `@objectstack/platform-objects` per ADR-0029
- * (K2.a) so this plugin owns its configuration object. Delivery telemetry is no
- * longer a webhook-owned object: post-ADR-0018 M3 deliveries are rows in the
- * shared `sys_http_delivery` outbox owned by `@objectstack/service-messaging`.
- *
- * Note: callers that just need the runtime should import from the package root
- * (`@objectstack/plugin-webhooks`), which auto-registers `sys_webhook` via the
- * plugin manifest. This subpath exists for read-only inspection from a
- * different runtime.
- */
-
-export { SysWebhook } from './sys-webhook.object.js';

package/src/sys-webhook.object.ts

@@ -1,193 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { ObjectSchema, Field } from '@objectstack/spec/data';
-
-/**
- * sys_webhook — Outbound HTTP integration configuration (runtime).
- *
- * Persists a single {@link Webhook} envelope per row so administrators
- * can author, enable/disable, and edit webhook subscriptions from the
- * Studio UI without code changes. The canonical Zod schema for the
- * `definition_json` envelope lives at `@objectstack/spec/automation/webhook`.
- *
- * One row per `name`. The automation runtime
- * (`@objectstack/service-automation`, built-in `http_request` node) loads
- * active rows on boot + on `sys_webhook:changed` events, registers
- * `afterInsert` / `afterUpdate` / `afterDelete` listeners for the
- * targeted object, and dispatches outbound HTTP calls when matching
- * record events fire.
- *
- * Ownership (ADR-0029 K2.a): this object is **owned by
- * `@objectstack/plugin-webhooks`** — the plugin that consumes these rows —
- * alongside its sibling `sys_webhook_delivery`. It used to live in the
- * `@objectstack/platform-objects` monolith and be imported here; the
- * definition now lives with its owner so the plugin ships both data and
- * behavior as one unit.
- *
- * Platform-wide on purpose: every project (standalone, single-tenant,
- * cloud) can integrate with external systems (Slack, Stripe, internal
- * services) the same way.
- *
- * @namespace sys
- */
-export const SysWebhook = ObjectSchema.create({
-  name: 'sys_webhook',
-  label: 'Webhook',
-  pluralLabel: 'Webhooks',
-  icon: 'webhook',
-  isSystem: true,
-  managedBy: 'config',
-  // Authoring a webhook from the UI requires a structured form for the
-  // headers / auth / retry / payload blocks — the generic JSON textarea
-  // is acceptable as a v1 until a dedicated builder lands. Re-enable
-  // create/edit/delete so admins can at least toggle `active` and edit
-  // simple URL/method fields without round-tripping through code.
-  userActions: { create: true, edit: true, delete: true, import: false },
-  description: 'Outbound HTTP webhook subscription. Authored via defineWebhook() in code or the Studio editor; executed by the HTTP connector plugin.',
-  displayNameField: 'name',
-  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
-  titleFormat: '{label}',
-  highlightFields: ['name', 'object_name', 'url', 'active', 'updated_at'],
-
-  listViews: {
-    active: {
-      type: 'grid',
-      name: 'active',
-      label: 'Active',
-      data: { provider: 'object', object: 'sys_webhook' },
-      columns: ['label', 'object_name', 'url', 'method', 'active', 'updated_at'],
-      filter: [{ field: 'active', operator: 'equals', value: true }],
-      sort: [{ field: 'label', order: 'asc' }],
-      pagination: { pageSize: 50 },
-    },
-    inactive: {
-      type: 'grid',
-      name: 'inactive',
-      label: 'Inactive',
-      data: { provider: 'object', object: 'sys_webhook' },
-      columns: ['label', 'object_name', 'url', 'method', 'active', 'updated_at'],
-      filter: [{ field: 'active', operator: 'equals', value: false }],
-      sort: [{ field: 'label', order: 'asc' }],
-      pagination: { pageSize: 50 },
-    },
-    by_object: {
-      type: 'grid',
-      name: 'by_object',
-      label: 'By Object',
-      data: { provider: 'object', object: 'sys_webhook' },
-      columns: ['object_name', 'label', 'url', 'active', 'updated_at'],
-      sort: [{ field: 'object_name', order: 'asc' }, { field: 'label', order: 'asc' }],
-      grouping: { fields: [{ field: 'object_name', order: 'asc', collapsed: false }] },
-      pagination: { pageSize: 100 },
-    },
-    all_webhooks: {
-      type: 'grid',
-      name: 'all_webhooks',
-      label: 'All',
-      data: { provider: 'object', object: 'sys_webhook' },
-      columns: ['label', 'object_name', 'url', 'method', 'active', 'updated_at'],
-      sort: [{ field: 'label', order: 'asc' }],
-      pagination: { pageSize: 50 },
-    },
-  },
-
-  fields: {
-    id: Field.text({ label: 'Webhook ID', required: true, readonly: true, group: 'System' }),
-
-    name: Field.text({
-      label: 'Name',
-      required: true,
-      maxLength: 100,
-      description: 'Unique snake_case name — referenced in logs and audit',
-      group: 'Definition',
-    }),
-
-    label: Field.text({
-      label: 'Display Label',
-      required: false,
-      maxLength: 200,
-      group: 'Definition',
-    }),
-
-    object_name: Field.text({
-      label: 'Object',
-      required: false,
-      maxLength: 100,
-      // Object picker (same widget as sys_sharing_rule) instead of a free-text
-      // machine name. Falls back to a text input when the widget is unavailable.
-      widget: 'object-ref',
-      description: 'Short object name whose record events (create/update/delete) fire this webhook',
-      group: 'Definition',
-    }),
-
-    triggers: Field.select(
-      ['create', 'update', 'delete'],
-      {
-        label: 'Triggers',
-        required: false,
-        // Multi-select instead of a hand-typed comma-separated string. Stored as
-        // an array; the auto-enqueuer parser also tolerates the legacy
-        // comma-separated / JSON-string forms so existing rows keep working.
-        multiple: true,
-        description: 'Record events that fire this webhook',
-        group: 'Definition',
-      },
-    ),
-
-    url: Field.text({
-      label: 'Target URL',
-      required: true,
-      maxLength: 2048,
-      description: 'External endpoint that receives the POST',
-      group: 'Definition',
-    }),
-
-    method: Field.select(
-      ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
-      {
-        label: 'HTTP Method',
-        required: true,
-        // Select instead of free text. Option values are lowercased by the
-        // Field.select helper (get/post/…); the auto-enqueuer upper-cases the
-        // resolved method before delivery, so existing 'POST' rows and the
-        // lowercase option values both normalise correctly.
-        defaultValue: 'post',
-        description: 'HTTP method used for the callback request',
-        group: 'Definition',
-      },
-    ),
-
-    description: Field.textarea({ label: 'Description', required: false, group: 'Definition' }),
-
-    active: Field.boolean({
-      label: 'Active',
-      required: true,
-      defaultValue: true,
-      description: 'Inactive webhooks are skipped by the dispatcher',
-      group: 'Definition',
-    }),
-
-    definition_json: Field.textarea({
-      label: 'Definition',
-      required: true,
-      description: 'Serialised Webhook JSON (see @objectstack/spec/automation/webhook) — full headers/auth/retry/payload config',
-      group: 'Definition',
-    }),
-
-    created_at: Field.datetime({
-      label: 'Created At',
-      required: true,
-      defaultValue: 'NOW()',
-      readonly: true,
-      group: 'System',
-    }),
-
-    updated_at: Field.datetime({ label: 'Updated At', required: false, group: 'System' }),
-  },
-
-  indexes: [
-    { fields: ['name'], unique: true },
-    { fields: ['object_name'] },
-    { fields: ['active', 'object_name'] },
-  ],
-});