@blokjs/runner 0.2.2 → 0.6.0

package/dist/scheduling/DeferredDispatchSignal.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Tier 2 #5 + #7 — thrown by `TriggerBase.run()` when a workflow's
+ * scheduling gates (debounce / delay) defer the run to a future
+ * dispatch. Tier 2 #6 follow-up extends this to cover `onLimit:"queue"`
+ * (concurrency-gate-deferred runs); same transport translation.
+ *
+ * NOT a true error — a control-flow exception. Trigger transports
+ * catch it and translate it into the appropriate transport-level
+ * response:
+ *
+ * - HTTP trigger → `202 Accepted` with `Location: /__blok/runs/:id`
+ *   header and structured JSON body.
+ * - Worker trigger → ACK without retry (the deferred coordinator owns
+ *   the eventual dispatch).
+ *
+ * Carries the run-detail summary the transport needs to populate the
+ * response.
+ */
+export interface DeferredDispatchInfo {
+    /** Run id allocated by the tracer when the run was created. */
+    runId: string;
+    /** Workflow name. */
+    workflowName: string;
+    /**
+     * Resolved status the run was placed in:
+     * - `"delayed"` — Tier 2 #5 (`trigger.delay`).
+     * - `"debounced"` — Tier 2 #7 (`trigger.debounce`).
+     * - `"queued"` — Tier 2 #6 follow-up (`trigger.onLimit:"queue"`).
+     */
+    status: "delayed" | "debounced" | "queued";
+    /** ms since epoch when the run is scheduled to dispatch. */
+    scheduledAt: number;
+    /** ms since epoch when the run will expire if not dispatched. Undefined when no TTL. */
+    expiresAt?: number;
+    /** True when the run was placed in `"debounced"` status (Tier 2 #7). */
+    debounced: boolean;
+    /** Pings absorbed by the run so far (always 1+). */
+    pingCount: number;
+    /**
+     * For leading-mode debounce, the runId of the sibling that fired
+     * immediately. Lets transports return `Location: /__blok/runs/<sibling>`
+     * so the caller can poll the actually-running run.
+     */
+    intoRunId?: string;
+}
+export declare class DeferredDispatchSignal extends Error {
+    readonly info: DeferredDispatchInfo;
+    constructor(info: DeferredDispatchInfo);
+}
+export declare function isDeferredDispatchSignal(err: unknown): err is DeferredDispatchSignal;

package/dist/scheduling/DeferredDispatchSignal.js

@@ -0,0 +1,14 @@
+export class DeferredDispatchSignal extends Error {
+    info;
+    constructor(info) {
+        super(`Run ${info.runId} for workflow '${info.workflowName}' was deferred ` +
+            `(${info.status}; scheduledAt=${info.scheduledAt}; pingCount=${info.pingCount}).`);
+        this.name = "DeferredDispatchSignal";
+        this.info = info;
+        Object.setPrototypeOf(this, DeferredDispatchSignal.prototype);
+    }
+}
+export function isDeferredDispatchSignal(err) {
+    return err instanceof DeferredDispatchSignal;
+}
+//# sourceMappingURL=DeferredDispatchSignal.js.map

package/dist/scheduling/DeferredDispatchSignal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeferredDispatchSignal.js","sourceRoot":"","sources":["../../src/scheduling/DeferredDispatchSignal.ts"],"names":[],"mappings":"AA8CA,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAChC,IAAI,CAAuB;IAE3C,YAAY,IAA0B;QACrC,KAAK,CACJ,OAAO,IAAI,CAAC,KAAK,kBAAkB,IAAI,CAAC,YAAY,iBAAiB;YACpE,IAAI,IAAI,CAAC,MAAM,iBAAiB,IAAI,CAAC,WAAW,eAAe,IAAI,CAAC,SAAS,IAAI,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC;CACD;AAED,MAAM,UAAU,wBAAwB,CAAC,GAAY;IACpD,OAAO,GAAG,YAAY,sBAAsB,CAAC;AAC9C,CAAC"}

package/dist/scheduling/DeferredRunScheduler.d.ts

@@ -0,0 +1,96 @@
+import type { ScheduledDispatchRow } from "../tracing/types";
+export type DeferredDispatchFn = () => Promise<void>;
+/**
+ * Optional persistence payload — when supplied to `schedule()`, the
+ * scheduler writes a `scheduled_dispatches` row before registering the
+ * timer, and deletes it on cancel or fire. Trigger boot recovery
+ * (e.g. `HttpTrigger.recoverDispatches`) reads these rows to re-register
+ * timers across process restarts.
+ */
+export interface DeferredScheduleOptions {
+    workflowName: string;
+    /** Trigger type — `"http"` for v1; future triggers can opt in. */
+    triggerType: string;
+    /** TTL deadline (ms since epoch). When set, expired rows get marked `expired` on boot recovery. */
+    expiresAt?: number;
+    /** Mirrors the run record's status. */
+    dispatchStatus: ScheduledDispatchRow["dispatchStatus"];
+    /**
+     * JSON-serializable trigger-defined payload sufficient to reconstruct
+     * dispatch on boot. Trigger packages choose what to put here.
+     */
+    payload: unknown;
+}
+export declare class DeferredRunScheduler {
+    private static instance;
+    private entries;
+    /**
+     * Tier C #2 — stable per-process identity used for claim ownership.
+     * Generated once per scheduler instance; surviving across resets is
+     * intentional (a "process restart" in production gets a fresh
+     * scheduler singleton and therefore a fresh processId — peers' stale
+     * claims expire after the lease).
+     */
+    private readonly processId;
+    /** Tier C #2 — running heartbeat timer; one per scheduler instance. */
+    private heartbeatTimer;
+    /** Tier C #2 — count of persisted entries currently registered. Heartbeat is only active when > 0. */
+    private persistedEntryCount;
+    static getInstance(): DeferredRunScheduler;
+    /** Test-only — reset the singleton. Cancels all pending timers. */
+    static resetInstance(): void;
+    /**
+     * Register a deferred dispatch. The timer fires at `dispatchAt`
+     * (clamped to ≥ now); when it fires, the entry is removed from the
+     * map and `dispatchFn` is invoked. Errors thrown by `dispatchFn` are
+     * swallowed and logged — the scheduler is fire-and-forget by design.
+     *
+     * Re-scheduling the same `runId` cancels the previous timer and
+     * replaces it (used by the debounce coordinator's "reset on ping").
+     *
+     * When `persist` is provided, the scheduler also writes a
+     * `scheduled_dispatches` row before registering the timer (so a
+     * crash leaves the dispatch recoverable), and deletes the row on
+     * cancel or fire.
+     */
+    schedule(runId: string, dispatchAt: number, dispatchFn: DeferredDispatchFn, persist?: DeferredScheduleOptions): void;
+    /**
+     * Cancel a pending dispatch. Returns true if the entry existed and
+     * was cancelled; false otherwise. Idempotent. When the entry was
+     * persisted, also deletes the `scheduled_dispatches` row.
+     *
+     * `cancelPersistedOnly` (default false) lets callers force the
+     * persistence-row delete even when the in-memory timer is gone (e.g.
+     * recovery cleanup that knows about a row but never had a timer).
+     */
+    cancel(runId: string, cancelPersistedOnly?: boolean): boolean;
+    private deletePersistedRow;
+    /** True if `runId` has a pending timer. */
+    has(runId: string): boolean;
+    /** Number of pending timers. Useful for tests + observability. */
+    size(): number;
+    /**
+     * Fire ALL pending dispatches immediately and clear the queue.
+     * Awaits each `dispatchFn` so the caller knows when the queue is
+     * drained. Useful for graceful shutdown.
+     */
+    drainAll(): Promise<void>;
+    /** Cancel everything without dispatching. */
+    clear(): void;
+    /**
+     * Stable per-process identity used for the claim API. Trigger boot
+     * recovery passes this to `RunStore.claimDispatches(processId, …)`
+     * so peers can recognize each other's claims.
+     */
+    getProcessId(): string;
+    private maybeStartHeartbeat;
+    private maybeStopHeartbeat;
+    private runHeartbeat;
+}
+/**
+ * Public helper that returns the operator-configured claim-lease in
+ * ms. Used by `HttpTrigger.recoverDispatches()` to pass the lease to
+ * `RunStore.claimDispatches()`. Centralized so the env var name is
+ * defined in one place.
+ */
+export declare function getSchedulerClaimLeaseMs(): number;

package/dist/scheduling/DeferredRunScheduler.js

@@ -0,0 +1,256 @@
+/**
+ * Tier 2 #5 — in-memory scheduler for deferred workflow runs. Tier 2
+ * #5+#7 follow-up adds optional sqlite-backed durability via the
+ * {@link DeferredScheduleOptions.persist} parameter. Tier C #2 adds
+ * cross-process claim heartbeats so multi-process deployments sharing
+ * a PG store don't double-fire the same dispatch.
+ *
+ * Process-wide singleton; obtained via {@link DeferredRunScheduler.getInstance}.
+ * Reset between tests via {@link DeferredRunScheduler.resetInstance}.
+ */
+import { randomUUID } from "node:crypto";
+import { RunTracker } from "../tracing/RunTracker";
+const DEFAULT_CLAIM_LEASE_MS = 60_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 20_000;
+export class DeferredRunScheduler {
+    static instance = null;
+    entries = new Map();
+    /**
+     * Tier C #2 — stable per-process identity used for claim ownership.
+     * Generated once per scheduler instance; surviving across resets is
+     * intentional (a "process restart" in production gets a fresh
+     * scheduler singleton and therefore a fresh processId — peers' stale
+     * claims expire after the lease).
+     */
+    processId = randomUUID();
+    /** Tier C #2 — running heartbeat timer; one per scheduler instance. */
+    heartbeatTimer = null;
+    /** Tier C #2 — count of persisted entries currently registered. Heartbeat is only active when > 0. */
+    persistedEntryCount = 0;
+    static getInstance() {
+        if (!DeferredRunScheduler.instance) {
+            DeferredRunScheduler.instance = new DeferredRunScheduler();
+        }
+        return DeferredRunScheduler.instance;
+    }
+    /** Test-only — reset the singleton. Cancels all pending timers. */
+    static resetInstance() {
+        DeferredRunScheduler.instance?.clear();
+        DeferredRunScheduler.instance = null;
+    }
+    /**
+     * Register a deferred dispatch. The timer fires at `dispatchAt`
+     * (clamped to ≥ now); when it fires, the entry is removed from the
+     * map and `dispatchFn` is invoked. Errors thrown by `dispatchFn` are
+     * swallowed and logged — the scheduler is fire-and-forget by design.
+     *
+     * Re-scheduling the same `runId` cancels the previous timer and
+     * replaces it (used by the debounce coordinator's "reset on ping").
+     *
+     * When `persist` is provided, the scheduler also writes a
+     * `scheduled_dispatches` row before registering the timer (so a
+     * crash leaves the dispatch recoverable), and deletes the row on
+     * cancel or fire.
+     */
+    schedule(runId, dispatchAt, dispatchFn, persist) {
+        // Persist BEFORE the timer so a crash between persist + setTimeout
+        // still leaves the row recoverable.
+        const persisted = persist !== undefined;
+        if (persisted) {
+            const tracker = RunTracker.getInstance();
+            if (tracker.active) {
+                try {
+                    tracker.getStore().upsertScheduledDispatch({
+                        runId,
+                        workflowName: persist.workflowName,
+                        triggerType: persist.triggerType,
+                        scheduledAt: dispatchAt,
+                        expiresAt: persist.expiresAt,
+                        dispatchStatus: persist.dispatchStatus,
+                        payload: persist.payload,
+                        createdAt: Date.now(),
+                    });
+                }
+                catch (err) {
+                    // Don't block the dispatch on persistence failure — log and continue.
+                    console.error(`[blok][scheduling] persist failed for run ${runId}; continuing in-memory only:`, err instanceof Error ? err.stack || err.message : err);
+                }
+            }
+        }
+        // Replace any existing entry for this runId.
+        const existing = this.entries.get(runId);
+        if (existing)
+            clearTimeout(existing.timer);
+        const delay = Math.max(0, dispatchAt - Date.now());
+        const timer = setTimeout(() => {
+            this.entries.delete(runId);
+            // Best-effort delete the persisted row before invoking dispatchFn —
+            // dispatch will write the run's terminal status separately.
+            if (persisted) {
+                this.deletePersistedRow(runId);
+                this.persistedEntryCount = Math.max(0, this.persistedEntryCount - 1);
+                this.maybeStopHeartbeat();
+            }
+            void dispatchFn().catch((err) => {
+                console.error(`[blok][scheduling] DeferredRunScheduler dispatch failed for run ${runId}:`, err instanceof Error ? err.stack || err.message : err);
+            });
+        }, delay);
+        // `Node` will keep the event loop alive for pending timers — that's
+        // the desired behavior for delayed runs in long-running services.
+        // `unref()` would be wrong here.
+        const wasPersisted = existing?.persisted === true;
+        this.entries.set(runId, { runId, dispatchAt, timer, dispatchFn, persisted });
+        // Tier C #2 — track persisted entry count + manage heartbeat
+        // lifecycle. The heartbeat only runs while we have ≥1 persisted
+        // entry (otherwise there's nothing to keep claimed). Replace doesn't
+        // change the count.
+        if (persisted && !wasPersisted) {
+            this.persistedEntryCount++;
+            this.maybeStartHeartbeat();
+        }
+        else if (!persisted && wasPersisted) {
+            this.persistedEntryCount = Math.max(0, this.persistedEntryCount - 1);
+            this.maybeStopHeartbeat();
+        }
+    }
+    /**
+     * Cancel a pending dispatch. Returns true if the entry existed and
+     * was cancelled; false otherwise. Idempotent. When the entry was
+     * persisted, also deletes the `scheduled_dispatches` row.
+     *
+     * `cancelPersistedOnly` (default false) lets callers force the
+     * persistence-row delete even when the in-memory timer is gone (e.g.
+     * recovery cleanup that knows about a row but never had a timer).
+     */
+    cancel(runId, cancelPersistedOnly = false) {
+        const entry = this.entries.get(runId);
+        if (!entry) {
+            if (cancelPersistedOnly) {
+                return this.deletePersistedRow(runId);
+            }
+            return false;
+        }
+        clearTimeout(entry.timer);
+        this.entries.delete(runId);
+        if (entry.persisted) {
+            this.deletePersistedRow(runId);
+            this.persistedEntryCount = Math.max(0, this.persistedEntryCount - 1);
+            this.maybeStopHeartbeat();
+        }
+        return true;
+    }
+    deletePersistedRow(runId) {
+        const tracker = RunTracker.getInstance();
+        if (!tracker.active)
+            return false;
+        try {
+            return tracker.getStore().deleteScheduledDispatch(runId);
+        }
+        catch (err) {
+            console.error(`[blok][scheduling] persist-cleanup failed for run ${runId}:`, err instanceof Error ? err.stack || err.message : err);
+            return false;
+        }
+    }
+    /** True if `runId` has a pending timer. */
+    has(runId) {
+        return this.entries.has(runId);
+    }
+    /** Number of pending timers. Useful for tests + observability. */
+    size() {
+        return this.entries.size;
+    }
+    /**
+     * Fire ALL pending dispatches immediately and clear the queue.
+     * Awaits each `dispatchFn` so the caller knows when the queue is
+     * drained. Useful for graceful shutdown.
+     */
+    async drainAll() {
+        const toFire = Array.from(this.entries.values());
+        // Cancel all timers first so we don't double-dispatch.
+        for (const entry of toFire)
+            clearTimeout(entry.timer);
+        this.entries.clear();
+        // Sequential dispatch — preserves intended order if it matters.
+        for (const entry of toFire) {
+            try {
+                await entry.dispatchFn();
+            }
+            catch (err) {
+                console.error(`[blok][scheduling] drainAll dispatch failed for run ${entry.runId}:`, err instanceof Error ? err.stack || err.message : err);
+            }
+        }
+    }
+    /** Cancel everything without dispatching. */
+    clear() {
+        for (const entry of this.entries.values())
+            clearTimeout(entry.timer);
+        this.entries.clear();
+        this.persistedEntryCount = 0;
+        this.maybeStopHeartbeat();
+    }
+    // === Tier C #2 — cross-process claim heartbeat ===
+    /**
+     * Stable per-process identity used for the claim API. Trigger boot
+     * recovery passes this to `RunStore.claimDispatches(processId, …)`
+     * so peers can recognize each other's claims.
+     */
+    getProcessId() {
+        return this.processId;
+    }
+    maybeStartHeartbeat() {
+        if (this.heartbeatTimer !== null)
+            return;
+        if (this.persistedEntryCount === 0)
+            return;
+        if (process.env.BLOK_SCHEDULER_CLAIM_DISABLED === "1")
+            return;
+        const intervalMs = readEnvInt("BLOK_SCHEDULER_HEARTBEAT_INTERVAL_MS", DEFAULT_HEARTBEAT_INTERVAL_MS);
+        this.heartbeatTimer = setInterval(() => {
+            this.runHeartbeat();
+        }, intervalMs);
+        // Don't keep the event loop alive solely for the heartbeat —
+        // the persisted entries' timers already do that. `unref()`
+        // avoids blocking shutdown when no entries are pending.
+        this.heartbeatTimer.unref?.();
+    }
+    maybeStopHeartbeat() {
+        if (this.heartbeatTimer === null)
+            return;
+        if (this.persistedEntryCount > 0)
+            return;
+        clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+    }
+    runHeartbeat() {
+        const tracker = RunTracker.getInstance();
+        if (!tracker.active)
+            return;
+        try {
+            tracker.getStore().heartbeatClaims(this.processId, Date.now());
+        }
+        catch (err) {
+            // Heartbeat failures are non-fatal — the lease will expire if
+            // they continue, and a peer will take over. Log + continue.
+            console.warn(`[blok][scheduling] heartbeatClaims failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+function readEnvInt(name, fallback) {
+    const raw = process.env[name];
+    if (raw && /^\d+$/.test(raw)) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return fallback;
+}
+/**
+ * Public helper that returns the operator-configured claim-lease in
+ * ms. Used by `HttpTrigger.recoverDispatches()` to pass the lease to
+ * `RunStore.claimDispatches()`. Centralized so the env var name is
+ * defined in one place.
+ */
+export function getSchedulerClaimLeaseMs() {
+    return readEnvInt("BLOK_SCHEDULER_CLAIM_LEASE_MS", DEFAULT_CLAIM_LEASE_MS);
+}
+//# sourceMappingURL=DeferredRunScheduler.js.map

package/dist/scheduling/DeferredRunScheduler.js.map

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

package/dist/scheduling/NatsKvDebounceBackend.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Tier C #1 · NATS KV-backed debounce backend.
+ *
+ * Coordinates per-(workflow, debounceKey) window state across processes
+ * via a single NATS JetStream KV value per bucket with revision-based
+ * compare-and-swap (OCC). Mirrors the storage model of
+ * `NatsKvConcurrencyBackend` but with a different document shape (one
+ * window per bucket, not a leases array).
+ *
+ * Acquire / extend / coalesce: a bounded CAS loop (10 retries) that
+ * reads → decides ownership → atomically writes. On retry exhaustion,
+ * fall back to admitting the ping as a `coalesce` against the current
+ * owner — debounce is not a safety gate, so we'd rather over-coalesce
+ * than drop pings on a contention spike.
+ *
+ * Finalize: same OCC pattern. The owning process atomically reads the
+ * doc, confirms it still owns AND `now >= scheduledAt`, and atomically
+ * deletes. On lease handoff, the owner discovers it no longer owns and
+ * abandons silently.
+ *
+ * **Owner-local payload**: this backend tracks `pingCount`,
+ * `lastPingAt`, and `scheduledAt` only — not the payload. Cross-process
+ * latest-payload-wins is a deferred follow-up.
+ */
+import type { DebounceBackend, DebounceFinalizeResult, DebounceRegisterBackendOpts, DebounceRegisterBackendResult } from "./DebounceBackend";
+export interface NatsKvDebounceConfig {
+    servers: string[];
+    token?: string;
+    user?: string;
+    pass?: string;
+    bucketName: string;
+}
+export declare function readNatsKvDebounceConfigFromEnv(): NatsKvDebounceConfig;
+export declare class NatsKvDebounceBackend implements DebounceBackend {
+    readonly name = "nats-kv";
+    private nc;
+    private kv;
+    private readonly config;
+    private connected;
+    constructor(config?: Partial<NatsKvDebounceConfig>);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private bucketKey;
+    private encodeSegment;
+    private requireKv;
+    private computeScheduledAt;
+    registerPing(opts: DebounceRegisterBackendOpts): Promise<DebounceRegisterBackendResult>;
+    finalize(workflowName: string, debounceKey: string, runId: string, now: number): Promise<DebounceFinalizeResult>;
+    cancel(workflowName: string, debounceKey: string): Promise<boolean>;
+    purgeExpired(now: number): Promise<number>;
+    private safeGet;
+    private parseDoc;
+}