@blokjs/runner 0.2.1 → 0.4.0

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 {};