@blokjs/runner 0.2.2 → 0.4.0

package/dist/SubworkflowNode.js

@@ -0,0 +1,221 @@
+import Configuration from "./Configuration";
+import RunnerNode from "./RunnerNode";
+import { RunTracker } from "./tracing/RunTracker";
+import { createChildContext } from "./utils/createChildContext";
+import { applyStepOutput } from "./workflow/PersistenceHelper";
+import { WorkflowRegistry } from "./workflow/WorkflowRegistry";
+/**
+ * Hard cap on `parent → child → grandchild → …` recursion. Bounds the
+ * blast radius of an accidental cycle (workflow A calls B calls A) or
+ * a legitimate-but-pathological deep nesting. Tunable via
+ * `BLOK_MAX_SUBWORKFLOW_DEPTH` env var; falls back to 10.
+ */
+function getMaxDepth() {
+    const raw = process.env.BLOK_MAX_SUBWORKFLOW_DEPTH;
+    if (typeof raw === "string" && raw.length > 0) {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isInteger(parsed) && parsed > 0)
+            return parsed;
+    }
+    return 10;
+}
+/**
+ * Internal ctx field that carries the current sub-workflow depth.
+ * Incremented by `SubworkflowNode.run` before invoking the child;
+ * read on entry to enforce the cap.
+ */
+const SUBWORKFLOW_DEPTH_KEY = "_subworkflowDepth";
+/**
+ * `SubworkflowNode` — the runner-side dispatch primitive that powers
+ * the v2 `subworkflow:` step shape. Looks up the named child workflow
+ * in the `WorkflowRegistry`, materializes a child `Configuration` +
+ * `Runner`, runs the child to completion in its own isolated `Context`,
+ * and returns the child's `ctx.response` as this step's `model.data`.
+ *
+ * **Composition with Tier 1**:
+ * - Parent step's `idempotencyKey` is consulted by `RunnerSteps` BEFORE
+ *   `SubworkflowNode.run` is even called — cache hit short-circuits the
+ *   entire sub-workflow (no child invocation, no side effects fire).
+ *   This is the headline pattern AND the documented footgun.
+ * - Parent step's `retry` retries the whole sub-workflow on failure;
+ *   each retry creates a fresh child run record under the same parent.
+ * - Replay re-creates fresh sub-run lineage automatically — the new
+ *   parent run invokes the sub-workflow fresh.
+ *
+ * **Lineage**: child's `WorkflowRun.parentRunId` and
+ * `WorkflowRun.parentNodeRunId` carry the parent run + step that
+ * invoked it. Studio renders a "called from #..." breadcrumb on the
+ * child and a "Sub-runs" list on the parent.
+ *
+ * **Recursion guard**: `BLOK_MAX_SUBWORKFLOW_DEPTH` (default 10) bounds
+ * cycle / deep-nesting blast radius. Throws a clear error past the cap.
+ */
+export class SubworkflowNode extends RunnerNode {
+    /**
+     * Runner-wide options (carries the `nodes` registry that the child
+     * Configuration needs for `module` step resolution). Set by
+     * `Configuration.subworkflowResolver` before this node runs.
+     */
+    globalOptions;
+    async run(ctx) {
+        // === 1. Recursion guard ===
+        const depth = (ctx[SUBWORKFLOW_DEPTH_KEY] ?? 0) + 1;
+        const maxDepth = getMaxDepth();
+        if (depth > maxDepth) {
+            throw new Error(`[blok] Sub-workflow recursion limit exceeded (depth ${depth} > ${maxDepth}). Likely a cycle: workflow "${ctx.workflow_name}" called sub-workflow "${this.subworkflow}" too deep. Bump via BLOK_MAX_SUBWORKFLOW_DEPTH if intentional.`);
+        }
+        // === 2. Look up the child workflow ===
+        const registry = WorkflowRegistry.getInstance();
+        const entry = registry.get(this.subworkflow);
+        if (!entry) {
+            const known = registry.list().map((w) => w.name);
+            const knownStr = known.length > 0 ? known.join(", ") : "(none registered yet)";
+            throw new Error(`[blok] Sub-workflow "${this.subworkflow}" not found in WorkflowRegistry. Available: ${knownStr}. Workflows are registered automatically by the HTTP trigger at boot — make sure the child workflow file is in the scanned directory and has \`name: "${this.subworkflow}"\`.`);
+        }
+        // === 3. Materialize child Configuration + Runner ===
+        // `preloaded` = entry.workflow skips the disk re-read; the
+        // normalizer still runs so v1→v2 conversion happens for legacy
+        // child workflows.
+        const childConfig = new Configuration();
+        await childConfig.init(entry.name, this.globalOptions, entry.workflow);
+        // Lazy import of Runner to avoid a circular dep
+        // (Configuration → RunnerNode → ... — Runner has its own chain).
+        const { default: Runner } = await import("./Runner");
+        const childRunner = new Runner(childConfig.steps);
+        // === 4. Build the child Context ===
+        // Parent step's resolved inputs (from blueprint mapper) live on
+        // `ctx.config[this.name].inputs` — the blueprint mapper has
+        // mutated the wrapper in place, so `js/...` and `$.<path>`
+        // expressions are now concrete values. These become the child's
+        // `request.body` so the child reads them via `$.req.body.<key>`
+        // exactly as if HTTP-triggered (function-call semantics).
+        const parentNodeConfig = ctx.config?.[this.name];
+        const parentInputs = parentNodeConfig?.inputs ?? {};
+        const childCtx = createChildContext(ctx, {
+            workflowName: entry.name,
+            workflowPath: entry.source,
+            body: parentInputs,
+            config: childConfig.nodes,
+        });
+        // Carry the depth counter forward so nested sub-workflows hit the cap.
+        childCtx[SUBWORKFLOW_DEPTH_KEY] = depth;
+        // === 5. Tracing — child gets its own run record + lineage ===
+        const tracker = RunTracker.getInstance();
+        const parentRunId = ctx._traceRunId;
+        const parentNodeRunId = ctx._traceNodeId;
+        const childTriggerSummary = `${ctx.workflow_name ?? "?"} → ${entry.name}`;
+        let childRunId;
+        if (tracker.active) {
+            const childRun = tracker.startRun({
+                workflowName: entry.name,
+                workflowPath: entry.source,
+                triggerType: "subworkflow",
+                triggerSummary: childTriggerSummary,
+                nodeCount: childConfig.steps.length,
+                parentRunId,
+                parentNodeRunId,
+            });
+            childRunId = childRun.id;
+            childCtx._traceRunId = childRun.id;
+        }
+        // === 6. Dispatch — sync or fire-and-forget based on `this.wait` ===
+        if (this.wait === false) {
+            return this.dispatchAsync(ctx, childRunner, childCtx, childRunId, entry.name);
+        }
+        // === 6a. Synchronous dispatch (wait: true / default) ===
+        try {
+            await childRunner.run(childCtx);
+            if (childRunId)
+                tracker.completeRun(childRunId, childCtx.response);
+        }
+        catch (err) {
+            if (childRunId)
+                tracker.failRun(childRunId, err);
+            throw err;
+        }
+        finally {
+            // PR 1 follow-up · A3 fix. Abort the listener-cleanup signal so
+            // the parent.signal listener (registered in createChildContext)
+            // auto-removes. Without this, listeners accumulate on long-lived
+            // parents that fire many sub-workflows.
+            const childPrivate = childCtx._PRIVATE_;
+            if (childPrivate?.listenerCleanup && !childPrivate.listenerCleanup.signal.aborted) {
+                childPrivate.listenerCleanup.abort();
+            }
+        }
+        // === 7. Apply parent persistence + return child's response ===
+        // Mirrors HTTP function-call semantics: parent reads child output
+        // at `$.state[<this.name>]`. Child author controls the shape via
+        // `@blokjs/respond` (or the last step's natural output).
+        //
+        // Persistence-helper call mirrors the RuntimeAdapterNode pattern
+        // (RuntimeAdapterNode.ts:100). The parent step's `as` / `spread`
+        // / `ephemeral` knobs apply identically here — sub-workflow
+        // output is just data, persistence rules are uniform.
+        const result = { success: !childCtx.response?.error, data: childCtx.response };
+        applyStepOutput(ctx, this, result);
+        return {
+            success: result.success,
+            data: childCtx.response,
+            error: childCtx.response?.error ?? null,
+        };
+    }
+    /**
+     * Fire-and-forget dispatch (Tier 2 #4 follow-up — `wait: false`).
+     *
+     * Schedules the child runner via `setImmediate` so the parent step
+     * can return immediately. Child errors are caught and routed to
+     * `tracker.failRun(childRunId, err)` — visible in Studio, NOT
+     * propagated to the parent step (which has already returned). Also
+     * logged via `console.error` for ops visibility.
+     *
+     * Parent step's output is the dispatch metadata `{runId,
+     * workflowName, scheduledAt}` — NOT the child's response (which
+     * doesn't exist yet). Caller polls `GET /__blok/runs/<runId>` for
+     * the actual outcome.
+     */
+    dispatchAsync(parentCtx, childRunner, childCtx, childRunId, childWorkflowName) {
+        const scheduledAt = Date.now();
+        const tracker = RunTracker.getInstance();
+        setImmediate(() => {
+            void (async () => {
+                try {
+                    await childRunner.run(childCtx);
+                    if (childRunId)
+                        tracker.completeRun(childRunId, childCtx.response);
+                }
+                catch (err) {
+                    if (childRunId) {
+                        tracker.failRun(childRunId, err instanceof Error ? err : new Error(String(err)));
+                    }
+                    console.error(`[blok][subworkflow] async child '${childWorkflowName}' (run ${childRunId ?? "?"}) failed:`, err instanceof Error ? err.stack || err.message : err);
+                }
+                finally {
+                    // PR 1 follow-up · A3 fix. Same listener-cleanup hook as the
+                    // sync path so async sub-workflows also auto-remove the
+                    // parent.signal listener on completion.
+                    const childPrivate = childCtx._PRIVATE_;
+                    if (childPrivate?.listenerCleanup && !childPrivate.listenerCleanup.signal.aborted) {
+                        childPrivate.listenerCleanup.abort();
+                    }
+                }
+            })();
+        });
+        // Parent step's output: dispatch metadata (the runId is the
+        // canonical handle for at-most-once dispatch deduplication when
+        // combined with `idempotencyKey`).
+        const dispatchData = {
+            runId: childRunId ?? null,
+            workflowName: childWorkflowName,
+            scheduledAt,
+        };
+        const result = { success: true, data: dispatchData };
+        applyStepOutput(parentCtx, this, result);
+        return {
+            success: true,
+            data: dispatchData,
+            error: null,
+        };
+    }
+}
+//# sourceMappingURL=SubworkflowNode.js.map

package/dist/SubworkflowNode.js.map

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

package/dist/TriggerBase.d.ts

@@ -12,6 +12,20 @@ import { RateLimiter } from "./monitoring/RateLimiter";
 import type { RateLimitConfig, RateLimitResult } from "./monitoring/RateLimiter";
 import { TriggerMetricsCollector } from "./monitoring/TriggerMetricsCollector";
 import type TriggerResponse from "./types/TriggerResponse";
+/**
+ * Tier 2 quick-wins follow-up · structural logger interface used by
+ * `installCrashHandlers` and `recoverOrphanedRuns`. Both `error` and
+ * `log` are optional so callers can pass a `DefaultLogger`, the Hono
+ * `console` shim, a custom logger, or omit it entirely.
+ *
+ * Single-arg calls (one pre-formatted string) are intentional — Node's
+ * `process.on("uncaughtException")` handlers can't await, and the
+ * `DefaultLogger` interface only takes `(message: string)`.
+ */
+interface CrashAutoflipLogger {
+    error?: (message: string) => void;
+    log?: (message: string) => void;
+}
 export default abstract class TriggerBase extends Trigger {
     configuration: Configuration;
     /** Health check instance for this trigger */
@@ -32,6 +46,94 @@ export default abstract class TriggerBase extends Trigger {
     abstract listen(): Promise<number>;
     getConfiguration(): Configuration;
     getRunner(): Runner;
+    /**
+     * Tier 2 #5+#7 follow-up — durable scheduler hook.
+     *
+     * When a trigger supports re-firing deferred dispatches across process
+     * restarts, it overrides this method to extract a JSON-serializable
+     * subset of `ctx` sufficient for `restoreDispatch(payload)` (defined
+     * by the trigger) to reconstruct an equivalent ctx and re-enter
+     * `dispatchDeferred`.
+     *
+     * Returns `null` (default) when the trigger does NOT support
+     * cross-restart durability — the scheduler then runs purely in-memory
+     * for that trigger (existing pre-follow-up behaviour).
+     *
+     * Override in `HttpTrigger` to return `{method, path, headers, body,
+     * params, query, workflowPath}` (with sensitive header keys stripped).
+     * Worker triggers don't override — broker handles delay durability.
+     */
+    protected extractDispatchPayload(_ctx: Context): unknown | null;
+    /**
+     * Returns the trigger type string used to tag persisted scheduled
+     * dispatch rows (`scheduled_dispatches.trigger_type`). Mirrors the
+     * convention from `tracker.startRun({triggerType})`. Override when
+     * the class name doesn't naturally produce the right tag.
+     */
+    protected getTriggerType(): string;
+    /** Flag — set true after `installCrashHandlers` has run once in this process. */
+    private static crashHandlersInstalled;
+    /**
+     * Tier 2 quick-wins follow-up — install process-level handlers for
+     * `uncaughtException` and `unhandledRejection`. When fired, flip
+     * every in-flight `running` run to `"crashed"` (with the captured
+     * error) BEFORE re-throwing / letting Node's default behavior take
+     * over. Idempotent — safe to call from every trigger's `listen()`;
+     * only the first call installs handlers.
+     *
+     * Kill-switch: `BLOK_CRASH_AUTOFLIP_DISABLED=1`.
+     *
+     * Why sync: `process.on("uncaughtException")` handlers can't await.
+     * `markAllRunningRunsAsCrashed` is sync (sqlite + in-memory writes
+     * complete before the handler returns).
+     */
+    static installCrashHandlers(logger?: CrashAutoflipLogger): void;
+    /** Test-only — reset the install flag so tests can re-install handlers. */
+    static resetCrashHandlersInstalled(): void;
+    /** Flag — set true after `installShutdownHandlers` has run once in this process. */
+    private static shutdownHandlersInstalled;
+    /**
+     * Install SIGTERM + SIGINT handlers that drain process resources
+     * cleanly before exit. Mirrors the `installCrashHandlers` pattern —
+     * idempotent + opt-out via `BLOK_GRACEFUL_SHUTDOWN_DISABLED=1`.
+     *
+     * Drain order:
+     * 1. Stop accepting new work — calls `trigger.stop()` if available
+     *    (HttpTrigger drains in-flight requests + closes the server).
+     * 2. Stop the periodic janitor sweep so it doesn't fire mid-drain.
+     * 3. Cancel pending deferred dispatches in the in-memory scheduler.
+     *    (Persisted rows in `scheduled_dispatches` survive — the next
+     *    boot recovers them.)
+     * 4. Disconnect the cross-process concurrency backend (NATS KV)
+     *    so locks held by this process release on the broker side.
+     * 5. `process.exit(0)`.
+     *
+     * Errors during drain are caught + logged; the process still exits
+     * (cleanup is best-effort; the operator wants a clean exit).
+     *
+     * Why this is a `static` method: shutdown handlers must be installed
+     * once per process, regardless of how many trigger subclasses
+     * coexist. Subclasses pass `this` so the handler can call their
+     * specific `stop()`.
+     */
+    static installShutdownHandlers(trigger: TriggerBase, logger?: CrashAutoflipLogger): void;
+    /** Test-only — reset the install flag so tests can re-install handlers. */
+    static resetShutdownHandlersInstalled(): void;
+    /**
+     * Tier 2 quick-wins follow-up — boot recovery for orphaned `running`
+     * runs. Scans the store for runs in `running` status whose
+     * `startedAt` is older than `thresholdMs` ago (default 2 minutes,
+     * override via `BLOK_ORPHAN_THRESHOLD_MS` env var). Flips each to
+     * `"crashed"` with `Error("Orphaned — process restarted before run completed")`.
+     *
+     * Catches the case where the previous process died via SIGKILL or
+     * OOM and the `installCrashHandlers` path never ran. Returns the
+     * count flipped for observability + tests.
+     *
+     * Idempotent — safe to call multiple times; runs are flipped to
+     * a terminal status so a second pass finds none.
+     */
+    static recoverOrphanedRuns(thresholdMs?: number, logger?: CrashAutoflipLogger): number;
     /**
      * Enable hot reload for this trigger. Only active in development
      * (NODE_ENV !== 'production') unless BLOK_HMR=true is explicitly set.
@@ -67,6 +169,31 @@ export default abstract class TriggerBase extends Trigger {
      */
     destroyHmr(): Promise<void>;
     run(ctx: Context): Promise<TriggerResponse>;
+    /**
+     * Tier 2 #5 + #7 — evaluate the scheduling gates and either return a
+     * `DeferredDispatchSignal` (the caller throws it) or null (the caller
+     * proceeds with immediate dispatch).
+     *
+     * Order: debounce → delay. They DON'T compose in a single PR (a
+     * trigger may use one or the other; both at once would be unusual).
+     * If both are configured, debounce takes precedence — the debounce
+     * coordinator handles its own scheduling (the `delay` field is
+     * effectively ignored on debounced triggers).
+     */
+    private maybeDeferRun;
+    /**
+     * Tier 2 #5 + #7 — re-enter the dispatch pipeline for a deferred run.
+     *
+     * Called by the `DeferredRunScheduler` timer (delay) or
+     * `DebounceCoordinator.onFire` (debounce trailing) when the wait
+     * window closes. Checks TTL, transitions the run to `running`, and
+     * re-enters `run(ctx)` with the `_blokDispatchReentry` flag so the
+     * scheduling gates are skipped on the second pass.
+     *
+     * The re-entered `run(ctx)` reuses the existing `traceRunId` (already
+     * stashed on `ctx._traceRunId` from the first pass).
+     */
+    protected dispatchDeferred(ctx: Context, traceRunId: string, expiresAt: number | undefined): Promise<void>;
     /**
      * Build a human-readable trigger summary for trace display.
      */
@@ -117,3 +244,4 @@ export default abstract class TriggerBase extends Trigger {
      */
     destroyMonitoring(): void;
 }
+export {};