@blokjs/runner 0.2.2 → 0.6.0

package/dist/SwitchNode.js

@@ -0,0 +1,153 @@
+/**
+ * SwitchNode — v0.5 primitive. N-way branch keyed on a value. First
+ * matching case wins; an optional `default` block runs when no case
+ * matches.
+ *
+ * The runtime config is read from `ctx.config[this.name]`:
+ *   {
+ *     on: unknown,                                      // resolved by mapper
+ *     cases: [{ when, steps: NodeBase[] }],             // pre-resolved by Configuration
+ *     default?: NodeBase[],                             // pre-resolved
+ *   }
+ *
+ * Match semantics:
+ * - `when` is a literal scalar (string/number/boolean) → match if `on === when`.
+ * - `when` is an array → match if `array.includes(on)` (group related cases).
+ *
+ * Mutations to state inside the matched case's sub-pipeline DO carry
+ * forward to subsequent top-level steps — switch is a passthrough flow,
+ * NOT an isolation boundary like forEach. The matched case's last step
+ * output becomes the switch step's `response.data`.
+ *
+ * If no case matches and there's no default, the step is a no-op
+ * (success, data: null).
+ *
+ * v0.6 Phase 4 — switch + wait support. The cursor schema
+ * (`SwitchIterationContext`) records `caseIndex` (or -1 for `default`)
+ * plus `innerStepIndex` within that arm. On re-entry after a wait,
+ * SwitchNode reads its cursor from the rehydrated map (keyed by its
+ * own NodeRun id), walks back into the matched arm at the right step,
+ * and ignores the `on` value entirely — we already committed to a
+ * specific arm in the first pass.
+ */
+import RunnerNode from "./RunnerNode";
+import { consumeRehydratedCursor, popPrimitiveFrame, pushPrimitiveFrame, readRehydratedCursor, } from "./runtime/PrimitiveStack";
+import { applyStepOutput } from "./workflow/PersistenceHelper";
+/** Sentinel `caseIndex` value meaning "the `default` arm matched". */
+const DEFAULT_ARM = -1;
+function caseMatches(when, on) {
+    if (Array.isArray(when)) {
+        return when.some((w) => w === on);
+    }
+    return when === on;
+}
+export class SwitchNode extends RunnerNode {
+    async run(ctx) {
+        this.contentType = "application/json";
+        const response = { success: true, data: null, error: null };
+        const opts = (ctx.config?.[this.name] ?? {});
+        const on = opts.on;
+        const cases = Array.isArray(opts.cases) ? opts.cases : [];
+        const defaultSteps = Array.isArray(opts.default) ? opts.default : undefined;
+        // v0.6 Phase 4 — resume cursor lookup. On re-entry from a wait
+        // fired inside a switch case, the persisted NodeRun's
+        // iteration_context carries the matched arm + inner step index.
+        const ctxAny = ctx;
+        const myNodeRunId = ctxAny._traceNodeId;
+        // Phase 4 — lookup by step NAME (stable across re-entries).
+        const resumeRaw = readRehydratedCursor(ctx, this.name);
+        const resume = resumeRaw && resumeRaw.mode === "switch" ? resumeRaw : undefined;
+        if (resume) {
+            consumeRehydratedCursor(ctx, this.name);
+        }
+        // Case selection. On resume, skip re-evaluating the `when`
+        // expressions — we've already committed to a specific arm and
+        // `on` could have changed mid-flight (different ctx state after
+        // pre-wait mutations). Walk straight back into the cached arm.
+        let selected;
+        let selectedCaseIndex = DEFAULT_ARM;
+        if (resume !== undefined) {
+            if (resume.caseIndex === DEFAULT_ARM) {
+                selected = defaultSteps;
+            }
+            else if (resume.caseIndex >= 0 && resume.caseIndex < cases.length) {
+                selected = cases[resume.caseIndex].steps;
+                selectedCaseIndex = resume.caseIndex;
+            }
+            // Cursor pointed at an arm that no longer exists (case removed
+            // between deploys, etc.). Fall through to fresh first-match
+            // behaviour — better than crashing the resume.
+        }
+        if (selected === undefined && resume === undefined) {
+            for (let idx = 0; idx < cases.length; idx++) {
+                if (caseMatches(cases[idx].when, on)) {
+                    selected = cases[idx].steps;
+                    selectedCaseIndex = idx;
+                    break;
+                }
+            }
+            if (selected === undefined) {
+                selected = defaultSteps;
+                if (selected !== undefined)
+                    selectedCaseIndex = DEFAULT_ARM;
+            }
+        }
+        if (selected === undefined || selected.length === 0) {
+            // No matching case + no default → no-op success. State
+            // entry is `null` so downstream `$.state[<id>]` reads return
+            // null (not undefined) — keeps the persistence model uniform.
+            applyStepOutput(ctx, this, { data: null });
+            // Preserve the previous step's ctx.response so the NEXT
+            // top-level step doesn't dereference null when RunnerSteps
+            // assigns `ctx.response.contentType`.
+            response.data = ctx.response;
+            return response;
+        }
+        // v0.6 Phase 4 — push a primitive frame so a nested wait fired
+        // inside this case's sub-pipeline persists the cursor on
+        // THIS switch's NodeRun. `innerStepIndex` is updated at each
+        // step boundary inside the case body by RunnerSteps; we just
+        // keep `caseIndex` pinned for the duration of this run.
+        const initialCursor = {
+            mode: "switch",
+            caseIndex: selectedCaseIndex,
+            innerStepIndex: resume?.innerStepIndex ?? 0,
+            completedResults: [],
+        };
+        const frame = myNodeRunId
+            ? { nodeRunId: myNodeRunId, cursor: initialCursor }
+            : undefined;
+        if (frame)
+            pushPrimitiveFrame(ctx, frame);
+        try {
+            // Lazy import — same circular-dep guard ForEach/Loop use.
+            const { default: Runner } = await import("./Runner");
+            const runner = new Runner(selected);
+            // On resume, pass the inner-step resume index — INCLUDING
+            // the index-0 case where the wait is the very first step
+            // of the matched arm. The deep runSteps' wait re-entry
+            // detection uses `innerResumeIndex !== undefined` as the
+            // "this primitive resumed here" signal (Phase 4 fix).
+            if (resume) {
+                ctxAny._blokInnerResumeIndex = resume.innerStepIndex;
+            }
+            // `deep: true` so the inner runSteps doesn't inherit the
+            // outer run's `lastCompletedStepIndex` cursor (PR 4 wait/
+            // resume logic).
+            await runner.run(ctx, { deep: true, stepName: this.name });
+            // Switch is a passthrough — the matched case ran on the
+            // parent ctx, so state mutations are already visible to
+            // downstream steps. The switch step's own data is the last
+            // inner step's response.
+            const data = ctx.response;
+            response.data = data;
+            applyStepOutput(ctx, this, { data });
+            return response;
+        }
+        finally {
+            if (frame)
+                popPrimitiveFrame(ctx);
+        }
+    }
+}
+//# sourceMappingURL=SwitchNode.js.map

package/dist/SwitchNode.js.map

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

package/dist/TriggerBase.d.ts

@@ -11,7 +11,22 @@ import { PrometheusMetricsBridge } from "./monitoring/PrometheusMetricsBridge";
 import { RateLimiter } from "./monitoring/RateLimiter";
 import type { RateLimitConfig, RateLimitResult } from "./monitoring/RateLimiter";
 import { TriggerMetricsCollector } from "./monitoring/TriggerMetricsCollector";
+import type GlobalOptions from "./types/GlobalOptions";
 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 +47,143 @@ 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;
+    /**
+     * v0.6 — apply the merged middleware chain (process-global → workflow-level
+     * → trigger-level) to `ctx` before the main workflow body runs.
+     *
+     * Trigger-level names are read from
+     * `this.configuration.trigger[<this.getTriggerType()>].middleware`, so
+     * HttpTrigger reads `trigger.http.middleware`, WorkerTrigger reads
+     * `trigger.worker.middleware`, CronTrigger reads `trigger.cron.middleware`.
+     *
+     * Pre-v0.6 the merge code lived inline in `HttpTrigger.run` and worker
+     * + cron triggers silently skipped middleware. Centralising it on
+     * TriggerBase gives all three trigger families uniform semantics.
+     *
+     * Resolution order outer→inner:
+     *   process-global → workflow-level → trigger-level → main workflow body.
+     *
+     * State mutations from earlier middleware (e.g. `ctx.state.identity`
+     * from auth-check) carry forward to later middleware and the main
+     * workflow because they share the same ctx. Middleware authors
+     * short-circuit via `@blokjs/throw` — the throw propagates to the
+     * caller's outer catch, and the main workflow does NOT run.
+     */
+    protected applyMiddlewareChain(ctx: Context, nodeMap: GlobalOptions): Promise<void>;
+    /**
+     * v0.6 — dispatch a chain of middleware workflows on the same parent
+     * ctx. Each entry in `names` is the `name:` of a workflow registered
+     * with `middleware: true`. For each:
+     *
+     * - Materialise a fresh `Configuration` for the middleware (resolves
+     *   its inner steps + nodes against `nodeMap` so `@blokjs/throw`
+     *   etc. resolve from `@blokjs/helpers`).
+     * - Save the parent ctx.config; swap in the middleware's resolved
+     *   `mwConfig.nodes` so the blueprint mapper finds the middleware's
+     *   step inputs.
+     * - Run via `new Runner(...).run(ctx, { deep: true })` — `deep: true`
+     *   prevents the inner runSteps from inheriting the outer run's
+     *   `lastCompletedStepIndex` cursor (PR 4 wait/resume hazard).
+     * - Restore parent ctx.config in `finally`.
+     *
+     * Missing middleware (name not registered) is a configuration error
+     * — throws a clear message naming the unknown middleware. Authors
+     * typically use `@blokjs/throw` inside middleware with a `code:` to
+     * produce structured HTTP responses (e.g. 401) — those throws
+     * propagate to the outer catch in the calling trigger.
+     *
+     * Pre-v0.6 this lived as a private method on `HttpTrigger`. Lifted
+     * here so worker + cron triggers can reuse it without duplication.
+     */
+    protected runMiddlewareChain(ctx: Context, names: readonly string[], nodeMap: GlobalOptions): Promise<void>;
+    /** 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 +219,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 +294,4 @@ export default abstract class TriggerBase extends Trigger {
      */
     destroyMonitoring(): void;
 }
+export {};