@blokjs/runner 0.4.0 → 0.6.1

package/dist/scheduling/NatsKvDebounceBackend.js

@@ -0,0 +1,334 @@
+/**
+ * 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.
+ */
+const DEFAULT_BUCKET_NAME = "blok-debounce";
+const MAX_CAS_RETRIES = 10;
+export function readNatsKvDebounceConfigFromEnv() {
+    const serversRaw = process.env.BLOK_DEBOUNCE_NATS_SERVERS ?? "nats://localhost:4222";
+    const servers = serversRaw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return {
+        servers,
+        token: process.env.BLOK_DEBOUNCE_NATS_TOKEN,
+        user: process.env.BLOK_DEBOUNCE_NATS_USER,
+        pass: process.env.BLOK_DEBOUNCE_NATS_PASS,
+        bucketName: process.env.BLOK_DEBOUNCE_NATS_KV_BUCKET ?? DEFAULT_BUCKET_NAME,
+    };
+}
+export class NatsKvDebounceBackend {
+    name = "nats-kv";
+    nc = null;
+    kv = null;
+    config;
+    connected = false;
+    constructor(config) {
+        const env = readNatsKvDebounceConfigFromEnv();
+        this.config = {
+            servers: config?.servers ?? env.servers,
+            token: config?.token ?? env.token,
+            user: config?.user ?? env.user,
+            pass: config?.pass ?? env.pass,
+            bucketName: config?.bucketName ?? env.bucketName,
+        };
+    }
+    async connect() {
+        if (this.connected)
+            return;
+        // Security review FW-5 parity — refuse to start in production with
+        // the default bucket name (same risk as the concurrency NATS KV
+        // bucket).
+        const blokEnv = process.env.BLOK_ENV;
+        const nodeEnv = process.env.NODE_ENV;
+        const isProd = blokEnv === "production" || nodeEnv === "production";
+        if (isProd && this.config.bucketName === DEFAULT_BUCKET_NAME) {
+            throw new Error(`[blok] NATS KV debounce backend refuses to start in production with the default bucket name ('${DEFAULT_BUCKET_NAME}'). Set BLOK_DEBOUNCE_NATS_KV_BUCKET to a deployment-unique value (e.g. 'blok-debounce-acme-prod') to prevent cross-deployment collision on a shared NATS server.`);
+        }
+        let natsModule;
+        try {
+            natsModule = (await import("nats"));
+        }
+        catch (err) {
+            throw new Error(`NatsKvDebounceBackend requires the 'nats' package. Install it: \`bun add nats\` or \`npm install nats\`. Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const connectOpts = { servers: this.config.servers };
+        if (this.config.token)
+            connectOpts.token = this.config.token;
+        if (this.config.user)
+            connectOpts.user = this.config.user;
+        if (this.config.pass)
+            connectOpts.pass = this.config.pass;
+        this.nc = await natsModule.connect(connectOpts);
+        // nats.js v2.x — KV lives at `nc.jetstream().views.kv(name)`.
+        const js = this.nc.jetstream();
+        this.kv = await js.views.kv(this.config.bucketName);
+        this.connected = true;
+    }
+    async disconnect() {
+        if (!this.connected)
+            return;
+        try {
+            await this.nc?.drain();
+        }
+        finally {
+            this.nc = null;
+            this.kv = null;
+            this.connected = false;
+        }
+    }
+    bucketKey(workflowName, debounceKey) {
+        return `${this.encodeSegment(workflowName)}__${this.encodeSegment(debounceKey)}`;
+    }
+    encodeSegment(s) {
+        return s.replace(/[^-_=.a-zA-Z0-9]/g, (ch) => `_${ch.codePointAt(0)?.toString(16)}_`);
+    }
+    requireKv() {
+        if (!this.kv) {
+            throw new Error("NatsKvDebounceBackend not connected — call connect() first.");
+        }
+        return this.kv;
+    }
+    computeScheduledAt(opts, existing) {
+        const naive = opts.now + opts.delayMs;
+        const deadline = existing?.maxDelayDeadline ?? (opts.maxDelayMs !== undefined ? opts.now + opts.maxDelayMs : undefined);
+        return deadline !== undefined ? Math.min(naive, deadline) : naive;
+    }
+    async registerPing(opts) {
+        const kv = this.requireKv();
+        const key = this.bucketKey(opts.workflowName, opts.debounceKey);
+        for (let attempt = 0; attempt < MAX_CAS_RETRIES; attempt++) {
+            const entry = await this.safeGet(kv, key);
+            if (entry === "fetch-failed") {
+                // Surface but don't retry on broker outage — debounce is
+                // fail-open per the coordinator wrapper.
+                throw new Error(`registerPing fetch-failed for ${key} (attempt ${attempt + 1})`);
+            }
+            const existing = entry ? this.parseDoc(entry) : null;
+            // Owner-lease expired → treat as no existing window.
+            const ownerActive = existing !== null && existing.ownerLeaseExpiresAt > opts.now;
+            if (!existing || !ownerActive) {
+                // Take ownership — new doc or owner-lease handoff.
+                const doc = {
+                    mode: opts.mode,
+                    delayMs: opts.delayMs,
+                    maxDelayMs: opts.maxDelayMs,
+                    maxDelayDeadline: existing?.maxDelayDeadline ?? (opts.maxDelayMs !== undefined ? opts.now + opts.maxDelayMs : undefined),
+                    firstPingAt: existing?.firstPingAt ?? opts.now,
+                    lastPingAt: opts.now,
+                    pingCount: (existing?.pingCount ?? 0) + 1,
+                    activeRunId: opts.runId,
+                    ownerProcessId: opts.processId,
+                    ownerLeaseExpiresAt: opts.now + opts.ownerLeaseMs,
+                    scheduledAt: this.computeScheduledAt(opts, existing),
+                };
+                try {
+                    if (entry) {
+                        await kv.update(key, JSON.stringify(doc), entry.revision);
+                    }
+                    else {
+                        await kv.create(key, JSON.stringify(doc));
+                    }
+                    return {
+                        outcome: "owner-new",
+                        activeRunId: doc.activeRunId,
+                        scheduledAt: doc.scheduledAt,
+                        pingCount: doc.pingCount,
+                    };
+                }
+                catch {
+                    continue; // CAS conflict — retry.
+                }
+            }
+            // existing && ownerActive
+            if (existing.ownerProcessId === opts.processId) {
+                // We still own — extend the window.
+                const next = {
+                    ...existing,
+                    lastPingAt: opts.now,
+                    pingCount: existing.pingCount + 1,
+                    ownerLeaseExpiresAt: opts.now + opts.ownerLeaseMs,
+                    scheduledAt: this.computeScheduledAt(opts, existing),
+                    // activeRunId stays — owner's run id from owner-new is the source of truth.
+                };
+                try {
+                    await kv.update(key, JSON.stringify(next), entry?.revision ?? 0);
+                    return {
+                        outcome: "owner-extend",
+                        activeRunId: existing.activeRunId,
+                        scheduledAt: next.scheduledAt,
+                        pingCount: next.pingCount,
+                    };
+                }
+                catch {
+                    continue;
+                }
+            }
+            // Different process owns. Coalesce — bump pingCount + push scheduledAt only.
+            const next = {
+                ...existing,
+                lastPingAt: opts.now,
+                pingCount: existing.pingCount + 1,
+                scheduledAt: this.computeScheduledAt(opts, existing),
+            };
+            try {
+                await kv.update(key, JSON.stringify(next), entry?.revision ?? 0);
+                return {
+                    outcome: "coalesce",
+                    activeRunId: existing.activeRunId,
+                    scheduledAt: next.scheduledAt,
+                    pingCount: next.pingCount,
+                };
+            }
+            catch {
+                // CAS conflict — fall through to the next loop iteration.
+            }
+        }
+        // CAS retries exhausted — over-coalesce: read the current owner and
+        // return coalesce. Last-resort fallback that prefers admitting a
+        // ping (with attribution to whoever currently owns) over dropping it.
+        const entry = await this.safeGet(kv, key);
+        if (entry && entry !== "fetch-failed") {
+            const existing = this.parseDoc(entry);
+            if (existing) {
+                return {
+                    outcome: "coalesce",
+                    activeRunId: existing.activeRunId,
+                    scheduledAt: existing.scheduledAt,
+                    pingCount: existing.pingCount,
+                };
+            }
+        }
+        // No doc readable — best-effort owner-new with caller's runId so
+        // the coordinator drives a local timer; the next ping will resolve
+        // the race.
+        return {
+            outcome: "owner-new",
+            activeRunId: opts.runId,
+            scheduledAt: opts.now + opts.delayMs,
+            pingCount: 1,
+        };
+    }
+    async finalize(workflowName, debounceKey, runId, now) {
+        const kv = this.requireKv();
+        const key = this.bucketKey(workflowName, debounceKey);
+        for (let attempt = 0; attempt < MAX_CAS_RETRIES; attempt++) {
+            const entry = await this.safeGet(kv, key);
+            if (entry === "fetch-failed") {
+                return { finalize: "abandoned" };
+            }
+            if (!entry)
+                return { finalize: "abandoned" };
+            const doc = this.parseDoc(entry);
+            if (!doc)
+                return { finalize: "abandoned" };
+            // Different runId now owns → abandoned (owner lease handed off).
+            if (doc.activeRunId !== runId)
+                return { finalize: "abandoned" };
+            // Coalesce pings pushed scheduledAt forward → reschedule.
+            if (now < doc.scheduledAt) {
+                return { finalize: "reschedule", scheduledAt: doc.scheduledAt };
+            }
+            // Same owner + scheduledAt elapsed → try to fire (DELETE).
+            try {
+                await kv.delete(key);
+                return { finalize: "fire" };
+            }
+            catch {
+                // Race — another op modified the bucket; fall through to retry.
+            }
+        }
+        return { finalize: "abandoned" };
+    }
+    async cancel(workflowName, debounceKey) {
+        const kv = this.requireKv();
+        const key = this.bucketKey(workflowName, debounceKey);
+        const entry = await this.safeGet(kv, key);
+        if (!entry || entry === "fetch-failed")
+            return false;
+        try {
+            await kv.delete(key);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async purgeExpired(now) {
+        const kv = this.requireKv();
+        let purged = 0;
+        // Drain `kv.keys()` to an array BEFORE doing per-key reads.
+        // nats.js v2.x's `QueuedIterator` silently drops yields when
+        // `kv.get()` is interleaved with the iteration (the watch's
+        // internal consumer gets confused). Collect first, then operate.
+        const allKeys = [];
+        for await (const key of await kv.keys()) {
+            allKeys.push(key);
+        }
+        for (const key of allKeys) {
+            const entry = await this.safeGet(kv, key);
+            if (!entry || entry === "fetch-failed")
+                continue;
+            const doc = this.parseDoc(entry);
+            if (!doc)
+                continue;
+            // Bucket is purgeable when both: owner-lease expired AND
+            // scheduledAt elapsed (no active owner with a pending fire).
+            if (doc.ownerLeaseExpiresAt <= now && doc.scheduledAt <= now) {
+                try {
+                    await kv.delete(key);
+                    purged += 1;
+                }
+                catch {
+                    // CAS conflict — leave for next sweep.
+                }
+            }
+        }
+        return purged;
+    }
+    async safeGet(kv, key) {
+        try {
+            const e = await kv.get(key);
+            return e ?? null;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "NotFound" || code === "404")
+                return null;
+            return "fetch-failed";
+        }
+    }
+    parseDoc(entry) {
+        try {
+            const parsed = JSON.parse(entry.string());
+            if (!parsed || typeof parsed.activeRunId !== "string")
+                return null;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=NatsKvDebounceBackend.js.map

package/dist/scheduling/NatsKvDebounceBackend.js.map

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

package/dist/scheduling/RedisDebounceBackend.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tier C #1 · Redis-backed debounce backend.
+ *
+ * Coordinates per-(workflow, debounceKey) window state across processes
+ * via a single Redis string key per bucket. Atomicity comes from
+ * server-side **Lua scripts** — `registerPing` / `finalize` /
+ * `cancel` / `purgeExpired` each run as a single `EVAL` with no OCC
+ * retry loop (Lua runs single-threaded against the keyspace).
+ *
+ * Storage shape: one JSON document per `(workflowName, debounceKey)`
+ * bucket. Owner identity is encoded in the doc itself as
+ * `(activeRunId, ownerProcessId, ownerLeaseExpiresAt)`; lease handoff
+ * happens atomically when a ping arrives after the lease expired.
+ *
+ * **Owner-local payload**: this backend tracks `pingCount`,
+ * `lastPingAt`, and `scheduledAt` only — payloads do NOT travel across
+ * processes. The owning process's local `onFire` closure fires when
+ * its timer elapses.
+ */
+import type { DebounceBackend, DebounceFinalizeResult, DebounceRegisterBackendOpts, DebounceRegisterBackendResult } from "./DebounceBackend";
+export interface RedisDebounceConfig {
+    url?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    db?: number;
+    tls?: boolean;
+    keyPrefix: string;
+}
+export declare function readRedisDebounceConfigFromEnv(): RedisDebounceConfig;
+export declare class RedisDebounceBackend implements DebounceBackend {
+    readonly name = "redis";
+    private client;
+    private readonly config;
+    private connected;
+    constructor(config?: Partial<RedisDebounceConfig>);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private bucketKey;
+    private encodeSegment;
+    private requireClient;
+    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 parseRegisterResult;
+    private parseFinalizeResult;
+}