adispatchd 0.0.0-stage → 0.1.0

package/dist/notifications/service.js

@@ -0,0 +1,364 @@
+/**
+ * Central orchestrator notifications (Spec §18): `retry_block_created`,
+ * `lifecycle_action_failed`, `recovery_failed`.
+ *
+ * Flow: {@link NotificationService.notify} persists the notification plus one
+ * delivery row per subscribed channel synchronously (a few SQLite writes,
+ * never network I/O) and wakes the dispatcher; the dispatcher delivers due
+ * deliveries asynchronously as JSON `POST` to the webhook channels with a
+ * timeout, retries with backoff and stores every attempt. Delivery problems
+ * are logged and persisted, never propagated: orchestration must not hang or
+ * fail because a webhook is down.
+ *
+ * Secrets: webhook URLs (literal or from env) and header values are
+ * registered with the shared {@link SecretRedactor}; error texts never
+ * contain the URL and are redacted before they are stored or logged.
+ */
+import { errorMessage, noopLogger, SecretRedactor, systemClock, systemTimers, } from '../core/index.js';
+/** Default backoff between delivery attempts (attempt n failed → wait `delays[n-1]`). */
+export const DEFAULT_NOTIFICATION_RETRY_DELAYS_MS = [5_000, 30_000, 120_000, 600_000, 1_800_000];
+/** Default request timeout of one webhook call. */
+export const DEFAULT_NOTIFICATION_TIMEOUT_MS = 10_000;
+/** Max deliveries processed per dispatcher pass. */
+const BATCH = 50;
+/** Upper bound for the dispatcher's wake-up timer (re-checks the DB at least this often). */
+const MAX_TIMER_MS = 60 * 60_000;
+/** See module docs. Implements the core {@link Notifier} contract. */
+export class NotificationService {
+    options;
+    repos;
+    clock;
+    timers;
+    logger;
+    redactor;
+    fetchFn;
+    env;
+    timeoutMs;
+    delays;
+    started = false;
+    stopped = false;
+    timer;
+    running;
+    again = false;
+    inflight = new Set();
+    constructor(options) {
+        this.options = options;
+        this.repos = options.repositories;
+        this.clock = options.clock ?? systemClock;
+        this.timers = options.timers ?? systemTimers;
+        this.logger = (options.logger ?? noopLogger).child({ component: 'notifications' });
+        this.redactor = options.redactor ?? new SecretRedactor();
+        this.fetchFn = options.fetch ?? ((input, init) => fetch(input, init));
+        this.env = options.env ?? process.env;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_NOTIFICATION_TIMEOUT_MS;
+        this.delays = options.retryDelaysMs ?? DEFAULT_NOTIFICATION_RETRY_DELAYS_MS;
+        this.registerChannelSecrets();
+    }
+    /** Max attempts per delivery. */
+    get maxAttempts() {
+        return this.delays.length + 1;
+    }
+    /**
+     * Persist a notification (if its event type is enabled) and schedule the
+     * delivery. Synchronous, never throws.
+     */
+    notify(type, payload) {
+        try {
+            const settings = this.options.settings();
+            if (!settings.on.includes(type)) {
+                this.logger.debug('notification event disabled', { type });
+                return;
+            }
+            const channels = settings.channels.filter((c) => c.on.includes(type)).map((c) => c.id);
+            const { notification, deliveries } = this.repos.notifications.createWithDeliveries(type, payload, channels);
+            this.logger.info('notification recorded', { id: notification.id, type, channels });
+            this.emit({ ...notification, deliveries });
+            if (deliveries.length > 0)
+                this.kick();
+        }
+        catch (err) {
+            this.logger.error('failed to record notification', { type, error: errorMessage(err) });
+        }
+    }
+    /** Start dispatching (also delivers notifications left pending by a previous process). */
+    start() {
+        if (this.started || this.stopped)
+            return;
+        this.started = true;
+        this.kick();
+    }
+    /**
+     * Stop the dispatcher: no new attempts; in-flight requests get `graceMs`
+     * to finish, then they are aborted (they stay `pending` and are retried by
+     * the next process).
+     */
+    async stop(graceMs = 2_000) {
+        this.stopped = true;
+        if (this.timer)
+            this.timers.clearTimeout(this.timer);
+        this.timer = undefined;
+        const running = this.running;
+        if (!running)
+            return;
+        let graceTimer;
+        await Promise.race([
+            running,
+            new Promise((resolve) => {
+                graceTimer = this.timers.setTimeout(() => {
+                    for (const c of this.inflight)
+                        c.abort(new Error('notification service stopping'));
+                    resolve();
+                }, graceMs);
+            }),
+        ]);
+        if (graceTimer)
+            this.timers.clearTimeout(graceTimer);
+        await running.catch(() => undefined);
+    }
+    /** Resolves when no dispatcher pass is running (tests). */
+    async whenIdle() {
+        while (this.running)
+            await this.running.catch(() => undefined);
+    }
+    /** Notifications (newest first) with their deliveries. */
+    list(options = {}) {
+        return this.repos.notifications.list(options).map((n) => ({ ...n, deliveries: this.repos.notifications.listDeliveries(n.id) }));
+    }
+    /** One notification with deliveries, or `null`. */
+    get(id) {
+        const n = this.repos.notifications.get(id);
+        return n ? { ...n, deliveries: this.repos.notifications.listDeliveries(id) } : null;
+    }
+    /**
+     * Manually re-queue all `failed` deliveries of a notification. Returns the
+     * updated notification, or `null` if it does not exist.
+     */
+    retry(id) {
+        const n = this.repos.notifications.get(id);
+        if (!n)
+            return null;
+        let requeued = 0;
+        for (const d of this.repos.notifications.listDeliveries(id)) {
+            if (d.state === 'failed' && this.repos.notifications.requeueDelivery(d.id))
+                requeued++;
+        }
+        const view = this.get(id);
+        if (requeued > 0) {
+            this.emit(view);
+            this.kick();
+        }
+        return { notification: view, requeued };
+    }
+    /** Wake the dispatcher (no-op before `start()` / after `stop()`). */
+    kick() {
+        if (!this.started || this.stopped)
+            return;
+        if (this.running) {
+            this.again = true;
+            return;
+        }
+        if (this.timer) {
+            this.timers.clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        const pass = this.dispatch()
+            .catch((err) => this.logger.error('notification dispatcher failed', { error: errorMessage(err) }))
+            .finally(() => {
+            if (this.running === pass)
+                this.running = undefined;
+            if (this.again) {
+                this.again = false;
+                this.kick();
+            }
+            else {
+                this.armTimer();
+            }
+        });
+        this.running = pass;
+    }
+    armTimer() {
+        if (this.stopped)
+            return;
+        const next = this.repos.notifications.nextDeliveryDue();
+        if (next === null)
+            return;
+        const delay = Math.min(MAX_TIMER_MS, Math.max(0, Date.parse(next) - this.clock.now().getTime()));
+        this.timer = this.timers.setTimeout(() => {
+            this.timer = undefined;
+            this.kick();
+        }, delay);
+    }
+    async dispatch() {
+        for (;;) {
+            if (this.stopped)
+                return;
+            const due = this.repos.notifications.listDueDeliveries(this.clock.now(), BATCH);
+            if (due.length === 0)
+                return;
+            for (const delivery of due) {
+                if (this.stopped)
+                    return;
+                await this.deliver(delivery);
+            }
+            if (due.length < BATCH)
+                return;
+        }
+    }
+    async deliver(delivery) {
+        const notification = this.repos.notifications.get(delivery.notificationId);
+        if (!notification)
+            return;
+        const attempt = delivery.attempts + 1;
+        let failure;
+        let status = null;
+        const channel = this.options.settings().channels.find((c) => c.id === delivery.channelId);
+        if (!channel) {
+            failure = { message: `notification channel '${delivery.channelId}' is no longer configured`, status: null, retryable: false };
+        }
+        else {
+            const result = await this.post(channel, notification);
+            failure = result.failure;
+            status = result.status;
+        }
+        if (this.stopped && failure?.message === 'aborted')
+            return; // stays pending for the next process
+        try {
+            let updated;
+            if (!failure) {
+                updated = this.repos.notifications.recordDeliveryAttempt(delivery.id, { success: true, status });
+                this.logger.info('notification delivered', { id: notification.id, channel: delivery.channelId, attempt });
+            }
+            else {
+                const delay = failure.retryable && attempt < this.maxAttempts ? (this.delays[attempt - 1] ?? null) : null;
+                const nextAttemptAt = delay === null ? null : new Date(this.clock.now().getTime() + delay);
+                const error = this.redactor.redact(failure.message);
+                updated = this.repos.notifications.recordDeliveryAttempt(delivery.id, {
+                    success: false,
+                    error,
+                    status: failure.status,
+                    nextAttemptAt,
+                });
+                this.logger.warn('notification delivery failed', {
+                    id: notification.id,
+                    channel: delivery.channelId,
+                    attempt,
+                    error,
+                    final: updated.state === 'failed',
+                    nextAttemptAt: updated.nextAttemptAt,
+                });
+            }
+            const view = this.get(notification.id);
+            if (view)
+                this.emit(view);
+        }
+        catch (err) {
+            this.logger.error('failed to record notification delivery attempt', { id: delivery.id, error: errorMessage(err) });
+        }
+    }
+    async post(channel, notification) {
+        const url = channel.url ?? (channel.urlEnv ? this.env[channel.urlEnv] : undefined);
+        if (!url) {
+            return {
+                failure: { message: `webhook URL is not set (environment variable ${channel.urlEnv ?? '?'})`, status: null, retryable: false },
+                status: null,
+            };
+        }
+        this.redactor.add(url);
+        const headers = { 'content-type': 'application/json', 'user-agent': 'adispatchd' };
+        for (const [name, envName] of Object.entries(channel.headersEnv)) {
+            const value = this.env[envName];
+            if (value === undefined || value === '') {
+                return {
+                    failure: { message: `header '${name}' is not set (environment variable ${envName})`, status: null, retryable: false },
+                    status: null,
+                };
+            }
+            this.redactor.add(value);
+            headers[name] = value;
+        }
+        const body = JSON.stringify(webhookBody(notification));
+        const controller = new AbortController();
+        this.inflight.add(controller);
+        const timer = this.timers.setTimeout(() => controller.abort(new Error('timeout')), this.timeoutMs);
+        try {
+            const response = await this.fetchFn(url, { method: 'POST', headers, body, signal: controller.signal, redirect: 'manual' });
+            // Drain the body so the connection can be reused/closed.
+            await response.text().catch(() => '');
+            if (response.status >= 200 && response.status < 300)
+                return { failure: null, status: response.status };
+            const retryable = response.status >= 500 || response.status === 408 || response.status === 429;
+            return { failure: { message: `webhook responded with HTTP ${response.status}`, status: response.status, retryable }, status: response.status };
+        }
+        catch (err) {
+            if (controller.signal.aborted) {
+                const reason = controller.signal.reason instanceof Error ? controller.signal.reason.message : 'aborted';
+                if (reason === 'timeout') {
+                    return { failure: { message: `webhook request timed out after ${this.timeoutMs} ms`, status: null, retryable: true }, status: null };
+                }
+                return { failure: { message: 'aborted', status: null, retryable: true }, status: null };
+            }
+            // Never include the URL: fetch errors may echo it.
+            const cause = err.cause;
+            const detail = cause instanceof Error ? cause.message : errorMessage(err);
+            return {
+                failure: { message: `webhook request failed: ${this.redactor.redact(detail).replaceAll(url, '[REDACTED]')}`, status: null, retryable: true },
+                status: null,
+            };
+        }
+        finally {
+            this.timers.clearTimeout(timer);
+            this.inflight.delete(controller);
+        }
+    }
+    registerChannelSecrets() {
+        try {
+            for (const c of this.options.settings().channels) {
+                if (c.url)
+                    this.redactor.add(c.url);
+                if (c.urlEnv)
+                    this.redactor.add(this.env[c.urlEnv]);
+                for (const envName of Object.values(c.headersEnv))
+                    this.redactor.add(this.env[envName]);
+            }
+        }
+        catch {
+            // settings not available yet – values are registered on first delivery
+        }
+    }
+    /** Re-register channel secrets after a configuration reload. */
+    refreshSecrets() {
+        this.registerChannelSecrets();
+    }
+    emit(view) {
+        try {
+            this.options.onChange?.(view);
+        }
+        catch (err) {
+            this.logger.warn('notification change listener failed', { error: errorMessage(err) });
+        }
+    }
+}
+/** JSON body posted to webhook channels (Slack-compatible `text` + structured data). */
+export function webhookBody(n) {
+    return {
+        source: 'adispatchd',
+        id: n.id,
+        event: n.eventType,
+        createdAt: n.createdAt,
+        text: summarize(n.eventType, n.payload),
+        payload: n.payload,
+    };
+}
+/** One-line human-readable summary of a notification. */
+export function summarize(type, p) {
+    const s = (v) => (typeof v === 'string' || typeof v === 'number' ? String(v) : '-');
+    switch (type) {
+        case 'retry_block_created':
+            return `[adispatchd] Retry block created for workflow ${s(p.workflowId)} (item ${s(p.itemKey ?? 'workflow')}): ${s(p.reason)}`;
+        case 'lifecycle_action_failed':
+            return `[adispatchd] Lifecycle action ${s(p.actionName ?? p.actionId)} (${s(p.hook)}) of run ${s(p.runId)} failed finally`;
+        case 'recovery_failed':
+            return `[adispatchd] Recovery of run ${s(p.runId)} (workflow ${s(p.workflowId)}) failed: ${s(p.reason)}`;
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/notifications/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/notifications/service.ts"],"names":[],"mappings":"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"}

package/dist/persistence/actions.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Lifecycle action journal (Spec §10, §12): `run_actions` + `action_attempts`.
+ * `succeeded` and `skipped` are final – a succeeded action is never executed again.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { ActionStatus, Clock, HookName } from '../core/index.js';
+/** Allowed action status changes. */
+export declare const ACTION_STATUS_TRANSITIONS: Readonly<Record<ActionStatus, readonly ActionStatus[]>>;
+/** Definition of one action when creating a journal. */
+export interface ActionJournalEntry {
+    /** Action type, e.g. `source.comment`. */
+    type: string;
+    /** Optional configured name/ID of the action. */
+    name?: string | null;
+    /** Action configuration from the run's config snapshot (no secrets). */
+    config: unknown;
+}
+/** A journaled action. */
+export interface RunActionRecord {
+    /** Stable ID (also used for comment markers). */
+    id: number;
+    runId: string;
+    hook: HookName;
+    ordinal: number;
+    type: string;
+    name: string | null;
+    config: unknown;
+    status: ActionStatus;
+    externalKey: string | null;
+    /** Number of attempts started. */
+    attempts: number;
+    lastError: unknown;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One execution attempt of an action. */
+export interface ActionAttemptRecord {
+    id: number;
+    actionId: number;
+    attempt: number;
+    startedAt: string;
+    finishedAt: string | null;
+    outcome: 'succeeded' | 'failed' | null;
+    error: unknown;
+    externalKey: string | null;
+}
+/** Failed action joined with its run (GUI "Failed Actions"). */
+export interface FailedActionRecord extends RunActionRecord {
+    workflowId: string;
+    sourceItemKey: string | null;
+    sourceUrl: string | null;
+}
+/** Repository for the action journal. */
+export declare class ActionRepository {
+    private readonly db;
+    private readonly clock;
+    constructor(db: DatabaseSync, clock: Clock);
+    /**
+     * Create the journal for all actions of a hook (`pending`, ordinal 0..n-1).
+     * Idempotent: if a journal for `(runId, hook)` already exists it is returned
+     * unchanged (resume after restart).
+     */
+    createJournal(runId: string, hook: HookName, actions: readonly ActionJournalEntry[]): RunActionRecord[];
+    /** Action by ID or `null`. */
+    get(id: number): RunActionRecord | null;
+    /** Action by ID; throws {@link NotFoundError}. */
+    require(id: number): RunActionRecord;
+    /** All actions of a run, by hook creation then ordinal. */
+    listForRun(runId: string): RunActionRecord[];
+    /** Actions of one hook in ordinal order. */
+    listForHook(runId: string, hook: HookName): RunActionRecord[];
+    /**
+     * Change an action's status (validated against {@link ACTION_STATUS_TRANSITIONS}).
+     * `externalKey`/`error` are stored when given.
+     */
+    setStatus(id: number, status: ActionStatus, options?: {
+        externalKey?: string | null;
+        error?: unknown;
+        expectedFrom?: ActionStatus;
+    }): RunActionRecord;
+    /**
+     * Start a new attempt: inserts `action_attempts` row (attempt = previous + 1),
+     * increments `attempts` and sets the action `running`.
+     */
+    startAttempt(actionId: number): ActionAttemptRecord;
+    /**
+     * Record the end of an attempt. Does not change the action status – the
+     * lifecycle engine decides (retry → stays `running`/`pending`, give up → `failed`).
+     */
+    finishAttempt(attemptId: number, outcome: 'succeeded' | 'failed', options?: {
+        error?: unknown;
+        externalKey?: string | null;
+    }): ActionAttemptRecord;
+    /** Attempts of an action in order. */
+    listAttempts(actionId: number): ActionAttemptRecord[];
+    /** All `failed` actions with run context, newest first (GUI / retry). */
+    listFailed(): FailedActionRecord[];
+    /** IDs of runs with `pending` or `running` actions (recovery: resume chains). */
+    runIdsWithIncompleteActions(): string[];
+    private requireAttempt;
+}