@blokjs/runner 0.6.20 → 0.7.0

package/dist/scheduling/NatsKvDebounceBackend.js

@@ -1,334 +0,0 @@
-/**
- * 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

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

package/dist/scheduling/RedisDebounceBackend.d.ts

@@ -1,49 +0,0 @@
-/**
- * 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;
-}