@blokjs/runner 0.2.2 → 0.6.0

package/dist/tracing/Janitor.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Tier 2 follow-up · periodic janitor sweep for stale storage rows.
+ *
+ * Background task that runs on a configurable interval (default 5 min,
+ * override via `BLOK_JANITOR_INTERVAL_MS`) and invokes the existing
+ * lazy-purge methods to clean up:
+ *
+ * - `idempotency_cache` — entries past `expires_at`
+ * - `concurrency_locks` — leases past `expires_at`
+ * - `scheduled_dispatches` — rows past `expires_at` (Tier 2 #5+#7 follow-up)
+ *
+ * Each store's per-call lazy-purge handles the hot path (e.g.,
+ * `acquireConcurrencySlot` purges the bucket it touches). The janitor
+ * catches stale entries in cold buckets that nothing else accesses.
+ *
+ * Idempotent + interval-bounded — runs every `intervalMs`; concurrent
+ * `runOnce()` calls are serialized via the `inFlight` flag to prevent
+ * overlapping sweeps under slow stores. Errors per sweep are caught
+ * and logged; one failing sweep doesn't stop the loop or block others.
+ *
+ * Kill-switch: `BLOK_JANITOR_DISABLED=1`.
+ */
+import type { RunStore } from "./RunStore";
+interface JanitorLogger {
+    error?: (message: string) => void;
+    log?: (message: string) => void;
+}
+export interface JanitorStats {
+    idempotencyCachePurged: number;
+    concurrencySlotsPurged: number;
+    scheduledDispatchesPurged: number;
+    durationMs: number;
+}
+export declare class Janitor {
+    private static instance;
+    private readonly store;
+    private readonly logger?;
+    private timer;
+    private inFlight;
+    private stopped;
+    private constructor();
+    /**
+     * Get or initialize the singleton. The first call wins — subsequent
+     * calls return the existing instance regardless of arguments.
+     */
+    static getInstance(store: RunStore, logger?: JanitorLogger): Janitor;
+    /** Test-only — reset the singleton. Stops any running interval. */
+    static resetInstance(): void;
+    /**
+     * Start the periodic sweep. Idempotent — calling twice is a no-op.
+     * Returns false when the kill-switch is set or the janitor was
+     * already started.
+     */
+    start(intervalMs?: number): boolean;
+    /** Stop the periodic sweep. Idempotent. */
+    stop(): void;
+    /**
+     * Run one sweep immediately. Useful for tests + as a manual janitor
+     * command. Concurrent invocations are serialized via the `inFlight`
+     * flag — overlapping calls return the same in-progress sweep's stats
+     * via the resolved promise.
+     *
+     * Errors per individual purge method are caught + logged; one failing
+     * purge doesn't abort the others.
+     */
+    runOnce(): Promise<JanitorStats>;
+    /** Whether the janitor is currently running on its interval. */
+    isRunning(): boolean;
+}
+export {};

package/dist/tracing/Janitor.js

@@ -0,0 +1,150 @@
+/**
+ * Tier 2 follow-up · periodic janitor sweep for stale storage rows.
+ *
+ * Background task that runs on a configurable interval (default 5 min,
+ * override via `BLOK_JANITOR_INTERVAL_MS`) and invokes the existing
+ * lazy-purge methods to clean up:
+ *
+ * - `idempotency_cache` — entries past `expires_at`
+ * - `concurrency_locks` — leases past `expires_at`
+ * - `scheduled_dispatches` — rows past `expires_at` (Tier 2 #5+#7 follow-up)
+ *
+ * Each store's per-call lazy-purge handles the hot path (e.g.,
+ * `acquireConcurrencySlot` purges the bucket it touches). The janitor
+ * catches stale entries in cold buckets that nothing else accesses.
+ *
+ * Idempotent + interval-bounded — runs every `intervalMs`; concurrent
+ * `runOnce()` calls are serialized via the `inFlight` flag to prevent
+ * overlapping sweeps under slow stores. Errors per sweep are caught
+ * and logged; one failing sweep doesn't stop the loop or block others.
+ *
+ * Kill-switch: `BLOK_JANITOR_DISABLED=1`.
+ */
+import { JanitorMetrics } from "../monitoring/JanitorMetrics";
+const DEFAULT_INTERVAL_MS = 5 * 60 * 1000;
+export class Janitor {
+    static instance = null;
+    store;
+    logger;
+    timer = null;
+    inFlight = false;
+    stopped = false;
+    constructor(store, logger) {
+        this.store = store;
+        this.logger = logger;
+    }
+    /**
+     * Get or initialize the singleton. The first call wins — subsequent
+     * calls return the existing instance regardless of arguments.
+     */
+    static getInstance(store, logger) {
+        if (!Janitor.instance) {
+            Janitor.instance = new Janitor(store, logger);
+        }
+        return Janitor.instance;
+    }
+    /** Test-only — reset the singleton. Stops any running interval. */
+    static resetInstance() {
+        Janitor.instance?.stop();
+        Janitor.instance = null;
+    }
+    /**
+     * Start the periodic sweep. Idempotent — calling twice is a no-op.
+     * Returns false when the kill-switch is set or the janitor was
+     * already started.
+     */
+    start(intervalMs) {
+        if (process.env.BLOK_JANITOR_DISABLED === "1")
+            return false;
+        if (this.timer !== null)
+            return false;
+        this.stopped = false;
+        const envIntervalRaw = process.env.BLOK_JANITOR_INTERVAL_MS;
+        const envInterval = envIntervalRaw && /^\d+$/.test(envIntervalRaw) ? Number(envIntervalRaw) : null;
+        const interval = intervalMs ?? envInterval ?? DEFAULT_INTERVAL_MS;
+        // `unref()` so the janitor doesn't keep the event loop alive on
+        // its own — when all triggers shut down, the process should exit.
+        this.timer = setInterval(() => {
+            void this.runOnce();
+        }, interval);
+        this.timer.unref?.();
+        this.logger?.log?.(`[blok][janitor] started — interval=${interval}ms`);
+        return true;
+    }
+    /** Stop the periodic sweep. Idempotent. */
+    stop() {
+        this.stopped = true;
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Run one sweep immediately. Useful for tests + as a manual janitor
+     * command. Concurrent invocations are serialized via the `inFlight`
+     * flag — overlapping calls return the same in-progress sweep's stats
+     * via the resolved promise.
+     *
+     * Errors per individual purge method are caught + logged; one failing
+     * purge doesn't abort the others.
+     */
+    async runOnce() {
+        if (this.stopped) {
+            return { idempotencyCachePurged: 0, concurrencySlotsPurged: 0, scheduledDispatchesPurged: 0, durationMs: 0 };
+        }
+        if (this.inFlight) {
+            // Skip overlapping invocations — return zero stats so callers
+            // don't wait on a sweep that's already running.
+            return { idempotencyCachePurged: 0, concurrencySlotsPurged: 0, scheduledDispatchesPurged: 0, durationMs: 0 };
+        }
+        this.inFlight = true;
+        const start = Date.now();
+        const stats = {
+            idempotencyCachePurged: 0,
+            concurrencySlotsPurged: 0,
+            scheduledDispatchesPurged: 0,
+            durationMs: 0,
+        };
+        try {
+            // PR 3 D3 — record per-table duration + rows purged via OTel.
+            const idemStart = Date.now();
+            try {
+                stats.idempotencyCachePurged = this.store.purgeExpiredIdempotencyCache(start);
+            }
+            catch (err) {
+                this.logger?.error?.(`[blok][janitor] purgeExpiredIdempotencyCache failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            JanitorMetrics.getInstance().recordSweep({ table: "idempotency_cache" }, Date.now() - idemStart, stats.idempotencyCachePurged);
+            const locksStart = Date.now();
+            try {
+                stats.concurrencySlotsPurged = this.store.purgeExpiredConcurrencySlots(start);
+            }
+            catch (err) {
+                this.logger?.error?.(`[blok][janitor] purgeExpiredConcurrencySlots failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            JanitorMetrics.getInstance().recordSweep({ table: "concurrency_locks" }, Date.now() - locksStart, stats.concurrencySlotsPurged);
+            const dispStart = Date.now();
+            try {
+                stats.scheduledDispatchesPurged = this.store.purgeExpiredScheduledDispatches(start);
+            }
+            catch (err) {
+                this.logger?.error?.(`[blok][janitor] purgeExpiredScheduledDispatches failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            JanitorMetrics.getInstance().recordSweep({ table: "scheduled_dispatches" }, Date.now() - dispStart, stats.scheduledDispatchesPurged);
+            stats.durationMs = Date.now() - start;
+            const totalPurged = stats.idempotencyCachePurged + stats.concurrencySlotsPurged + stats.scheduledDispatchesPurged;
+            if (totalPurged > 0) {
+                this.logger?.log?.(`[blok][janitor] sweep done — idem=${stats.idempotencyCachePurged} locks=${stats.concurrencySlotsPurged} dispatches=${stats.scheduledDispatchesPurged} (${stats.durationMs}ms)`);
+            }
+        }
+        finally {
+            this.inFlight = false;
+        }
+        return stats;
+    }
+    /** Whether the janitor is currently running on its interval. */
+    isRunning() {
+        return this.timer !== null;
+    }
+}
+//# sourceMappingURL=Janitor.js.map

package/dist/tracing/Janitor.js.map

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

package/dist/tracing/PostgresRunStore.d.ts

@@ -1,5 +1,5 @@
 import type { RunStore } from "./RunStore";
-import type { Dashboard, MetricsResult, NodeRun, RunEvent, RunQuery, TraceLogEntry, WorkflowRun, WorkflowSummary } from "./types";
+import type { Dashboard, MetricsResult, NodeRun, RunEvent, RunQuery, SavedFilter, ScheduledDispatchRow, TraceLogEntry, WorkflowRun, WorkflowSample, WorkflowSummary } from "./types";
 /**
  * PostgreSQL connection configuration.
  */
@@ -41,6 +41,14 @@ export declare class PostgresRunStore implements RunStore {
     ready(): Promise<void>;
     private initialize;
     private migrate;
+    /**
+     * Review fix-up · CONCERN-2. Per-table cap on `loadRecent`'s rehydration
+     * queries. Without it, a deployment with 1M+ idempotency cache entries
+     * spends seconds + memory on every boot loading rows it'll never read
+     * before the Janitor sweeps them. Default 100K rows per table — well
+     * above any reasonable hot-set size yet bounded for boot latency.
+     */
+    private getLoadRecentLimit;
     private loadRecent;
     saveRun(run: WorkflowRun): void;
     updateRun(runId: string, updates: Partial<WorkflowRun>): void;
@@ -55,6 +63,7 @@ export declare class PostgresRunStore implements RunStore {
     };
     getNodeRuns(runId: string): NodeRun[];
     getNodeRun(nodeRunId: string): NodeRun | undefined;
+    getRunsByParent(parentRunId: string): WorkflowRun[];
     getEvents(runId: string, since?: number): RunEvent[];
     getLogs(runId: string, nodeId?: string): TraceLogEntry[];
     getWorkflowSummaries(): WorkflowSummary[];
@@ -66,10 +75,57 @@ export declare class PostgresRunStore implements RunStore {
     listDashboards(): Dashboard[];
     deleteDashboard(dashboardId: string): boolean;
     updateDashboard(dashboardId: string, updates: Partial<Dashboard>): void;
+    upsertSavedFilter(filter: SavedFilter): SavedFilter;
+    listSavedFilters(): SavedFilter[];
+    deleteSavedFilter(name: string): boolean;
+    recordWorkflowSample(sample: WorkflowSample): WorkflowSample;
+    getWorkflowSample(workflowName: string): WorkflowSample | undefined;
+    deleteWorkflowSample(workflowName: string): boolean;
     clearAll(): number;
     deleteRunsBefore(timestamp: number): number;
     evictOldRuns(maxRuns: number): void;
     close(): void;
+    getIdempotencyCache(workflowName: string, stepId: string, key: string): import("./types").CachedStepResult | null;
+    setIdempotencyCache(workflowName: string, stepId: string, key: string, entry: Parameters<typeof this.memory.setIdempotencyCache>[3]): void;
+    purgeExpiredIdempotencyCache(now: number): number;
+    acquireConcurrencySlot(workflowName: string, concurrencyKey: string, concurrencyLimit: number, runId: string, leaseExpiresAt: number): import("./types").ConcurrencySlotResult;
+    releaseConcurrencySlot(workflowName: string, concurrencyKey: string, runId: string): void;
+    purgeExpiredConcurrencySlots(now: number): number;
+    getConcurrencySnapshot(now: number): {
+        workflowName: string;
+        concurrencyKey: string;
+        leases: Array<{
+            runId: string;
+            expiresAt: number;
+        }>;
+    }[];
+    upsertScheduledDispatch(row: Parameters<typeof this.memory.upsertScheduledDispatch>[0]): void;
+    claimDispatchesAsync(processId: string, leaseMs: number, now: number, opts?: {
+        triggerType?: string;
+    }): Promise<ScheduledDispatchRow[]>;
+    /**
+     * Sync wrapper required by the `RunStore` interface. PG's claim API
+     * is fundamentally async (network round-trip); the sync wrapper
+     * returns the LAST snapshot from the in-memory mirror.
+     *
+     * **For cross-process correctness, callers MUST use
+     * `claimDispatchesAsync()` directly.** The sync wrapper exists so
+     * the interface contract is satisfied for sqlite + in-memory
+     * callers; PG users opt into the async path via the trigger's
+     * recovery code (`HttpTrigger.recoverDispatches()` calls the
+     * async version when the store is a `PostgresRunStore`).
+     */
+    claimDispatches(processId: string, leaseMs: number, now: number, opts?: {
+        triggerType?: string;
+    }): ScheduledDispatchRow[];
+    heartbeatClaims(processId: string, now: number): number;
+    releaseClaim(runId: string): boolean;
+    deleteScheduledDispatch(runId: string): boolean;
+    getScheduledDispatches(opts?: {
+        triggerType?: string;
+        status?: string;
+    }): ScheduledDispatchRow[];
+    purgeExpiredScheduledDispatches(now: number): number;
     private enqueueWrite;
     private flush;
     private startFlushLoop;