@blokjs/runner 0.2.1 → 0.4.0

package/dist/concurrency/NatsKvConcurrencyBackend.js

@@ -0,0 +1,297 @@
+/**
+ * Tier 2 #6 follow-up · NATS KV-backed concurrency backend.
+ *
+ * Coordinates per-(workflow, concurrencyKey) lease state across processes
+ * via a single NATS JetStream KV value per bucket using revision-based
+ * compare-and-swap (OCC).
+ *
+ * Storage model: one KV key per `(workflowName, concurrencyKey)` pair.
+ * Value is a JSON `{leases: [{runId, expiresAt}]}` document. Bounded
+ * cardinality assumption — typical concurrency keys hold 1-50 active
+ * leases (per-tenant rate limits). For higher cardinality, a per-lease
+ * key model would scale better; revisit when needed.
+ *
+ * Atomicity: NATS KV's only guarantee is `kv.create(key, value)` (fails
+ * on conflict) and `kv.update(key, value, expectedRevision)` (fails on
+ * concurrent modification). The acquire loop reads → filters → checks
+ * limit → CAS update. On CAS failure, retry up to 10 times then
+ * fail-closed (deny the slot).
+ *
+ * Lease leak: each lease carries an `expiresAt`. Expired leases are
+ * lazy-purged inside the same `acquireSlot` call that observes them;
+ * an explicit `purgeExpired` sweep is also exposed for janitor use.
+ */
+import { ConcurrencyMetrics } from "../monitoring/ConcurrencyMetrics";
+const DEFAULT_BUCKET_NAME = "blok-concurrency";
+const MAX_CAS_RETRIES = 10;
+/**
+ * Read configuration from environment variables. Used by
+ * {@link createConcurrencyBackend} when the user opts into NATS KV.
+ */
+export function readNatsKvConfigFromEnv() {
+    const serversRaw = process.env.BLOK_CONCURRENCY_NATS_SERVERS ?? "nats://localhost:4222";
+    const servers = serversRaw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return {
+        servers,
+        token: process.env.BLOK_CONCURRENCY_NATS_TOKEN,
+        user: process.env.BLOK_CONCURRENCY_NATS_USER,
+        pass: process.env.BLOK_CONCURRENCY_NATS_PASS,
+        bucketName: process.env.BLOK_CONCURRENCY_NATS_KV_BUCKET ?? DEFAULT_BUCKET_NAME,
+    };
+}
+export class NatsKvConcurrencyBackend {
+    name = "nats-kv";
+    nc = null;
+    kv = null;
+    config;
+    connected = false;
+    constructor(config) {
+        const env = readNatsKvConfigFromEnv();
+        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 — refuse to start in production with the
+        // default bucket name. Two deployments sharing a NATS server with
+        // the default would contend on the same `(workflow, key)` buckets,
+        // silently corrupting concurrency state across tenants. The fix
+        // is operator-mandatory: set BLOK_CONCURRENCY_NATS_KV_BUCKET
+        // per-deployment.
+        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 concurrency backend refuses to start in production with the default bucket name ('${DEFAULT_BUCKET_NAME}'). Set BLOK_CONCURRENCY_NATS_KV_BUCKET to a deployment-unique value (e.g. 'blok-concurrency-acme-prod') to prevent cross-deployment collision on a shared NATS server.`);
+        }
+        let natsModule;
+        try {
+            natsModule = (await import("nats"));
+        }
+        catch (err) {
+            throw new Error(`NatsKvConcurrencyBackend 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));
+        // `kv()` auto-creates the bucket on first use (NATS JetStream KV semantics).
+        this.kv = await this.nc.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, concurrencyKey) {
+        // Use `__` (double underscore) — KV keys cannot contain `.` or
+        // `>` per NATS subject grammar; `__` is unambiguous and allows
+        // arbitrary workflow / key strings.
+        return `${this.encodeSegment(workflowName)}__${this.encodeSegment(concurrencyKey)}`;
+    }
+    encodeSegment(s) {
+        // NATS KV keys must match `[-/_=\.a-zA-Z0-9]+`. Replace anything
+        // outside the safe set with hex escape `_HHHH_` to keep the
+        // roundtrip lossless.
+        return s.replace(/[^-_=.a-zA-Z0-9]/g, (ch) => `_${ch.codePointAt(0)?.toString(16)}_`);
+    }
+    requireKv() {
+        if (!this.kv) {
+            throw new Error("NatsKvConcurrencyBackend not connected — call connect() first.");
+        }
+        return this.kv;
+    }
+    async acquireSlot(workflowName, concurrencyKey, concurrencyLimit, runId, leaseExpiresAt) {
+        const kv = this.requireKv();
+        const bucketKey = this.bucketKey(workflowName, concurrencyKey);
+        // PR 3 D2 — record OCC retry depth + outcome on every exit path.
+        const metricAttrs = { workflow_name: workflowName, concurrency_key: concurrencyKey };
+        for (let attempt = 0; attempt < MAX_CAS_RETRIES; attempt++) {
+            const entry = await this.safeGet(kv, bucketKey);
+            // PR 2 A6 — fetch failure (broker unreachable / non-NotFound
+            // error). Spinning 10× CAS retries on a connection problem just
+            // burns latency. Fail-fast so the trigger sees the issue and
+            // can fall back / alert. Existing run continues with no slot;
+            // the gate is conservative.
+            if (entry === "fetch-failed") {
+                console.warn(`[blok][concurrency][nats-kv] acquireSlot fetch-failed for ${workflowName}:${concurrencyKey} (attempt ${attempt + 1}); failing closed`);
+                ConcurrencyMetrics.getInstance().recordOccRetries({ ...metricAttrs, outcome: "fail-closed" }, attempt);
+                return { acquired: false, currentInFlight: -1 };
+            }
+            if (!entry) {
+                // Bucket doesn't exist — create with first lease.
+                const initial = { leases: [{ runId, expiresAt: leaseExpiresAt }] };
+                try {
+                    await kv.create(bucketKey, JSON.stringify(initial));
+                    ConcurrencyMetrics.getInstance().recordOccRetries({ ...metricAttrs, outcome: "success" }, attempt);
+                    return { acquired: true, currentInFlight: 1 };
+                }
+                catch {
+                    // Race — another process created. Retry.
+                    continue;
+                }
+            }
+            // Read current state, lazy-purge expired.
+            const current = this.parseBucket(entry);
+            const now = Date.now();
+            const active = current.leases.filter((l) => l.expiresAt > now);
+            // Idempotent re-acquire: refresh lease, don't grow count.
+            const existingIdx = active.findIndex((l) => l.runId === runId);
+            if (existingIdx >= 0) {
+                active[existingIdx] = { runId, expiresAt: leaseExpiresAt };
+                try {
+                    await kv.update(bucketKey, JSON.stringify({ leases: active }), entry.revision);
+                    ConcurrencyMetrics.getInstance().recordOccRetries({ ...metricAttrs, outcome: "success" }, attempt);
+                    return { acquired: true, currentInFlight: active.length };
+                }
+                catch {
+                    continue;
+                }
+            }
+            // Limit check.
+            if (active.length >= concurrencyLimit) {
+                ConcurrencyMetrics.getInstance().recordOccRetries({ ...metricAttrs, outcome: "denied" }, attempt);
+                return { acquired: false, currentInFlight: active.length };
+            }
+            // Insert + CAS.
+            const updated = { leases: [...active, { runId, expiresAt: leaseExpiresAt }] };
+            try {
+                await kv.update(bucketKey, JSON.stringify(updated), entry.revision);
+                ConcurrencyMetrics.getInstance().recordOccRetries({ ...metricAttrs, outcome: "success" }, attempt);
+                return { acquired: true, currentInFlight: updated.leases.length };
+            }
+            catch { }
+        }
+        // Retry exhausted — fail-closed.
+        console.warn(`[blok][concurrency][nats-kv] acquireSlot exhausted ${MAX_CAS_RETRIES} CAS retries for ${workflowName}:${concurrencyKey}; denying slot to runId=${runId}`);
+        ConcurrencyMetrics.getInstance().recordOccRetries({ ...metricAttrs, outcome: "fail-closed" }, MAX_CAS_RETRIES);
+        return { acquired: false, currentInFlight: -1 };
+    }
+    async releaseSlot(workflowName, concurrencyKey, runId) {
+        const kv = this.requireKv();
+        const bucketKey = this.bucketKey(workflowName, concurrencyKey);
+        for (let attempt = 0; attempt < MAX_CAS_RETRIES; attempt++) {
+            const entry = await this.safeGet(kv, bucketKey);
+            // PR 2 A6 — fetch failure on release. Lease will expire via
+            // TTL; safe to fail-fast.
+            if (entry === "fetch-failed") {
+                console.warn(`[blok][concurrency][nats-kv] releaseSlot fetch-failed for ${workflowName}:${concurrencyKey} (attempt ${attempt + 1}); lease for runId=${runId} will expire via TTL`);
+                return;
+            }
+            if (!entry)
+                return; // Idempotent — bucket already gone.
+            const current = this.parseBucket(entry);
+            const next = current.leases.filter((l) => l.runId !== runId);
+            // No-op when the runId wasn't holding a slot.
+            if (next.length === current.leases.length)
+                return;
+            if (next.length === 0) {
+                try {
+                    await kv.delete(bucketKey);
+                    return;
+                }
+                catch {
+                    // Another process beat us to delete — fine.
+                    return;
+                }
+            }
+            try {
+                await kv.update(bucketKey, JSON.stringify({ leases: next }), entry.revision);
+                return;
+            }
+            catch { }
+        }
+        console.warn(`[blok][concurrency][nats-kv] releaseSlot exhausted ${MAX_CAS_RETRIES} CAS retries for ${workflowName}:${concurrencyKey}; lease for runId=${runId} will expire via TTL`);
+    }
+    async purgeExpired(now) {
+        const kv = this.requireKv();
+        let purged = 0;
+        // Iterate all bucket keys.
+        for await (const key of kv.keys()) {
+            const entry = await this.safeGet(kv, key);
+            // Treat both legitimate misses and fetch failures as "skip
+            // this bucket" — purge is a best-effort sweep.
+            if (!entry || entry === "fetch-failed")
+                continue;
+            const current = this.parseBucket(entry);
+            const active = current.leases.filter((l) => l.expiresAt > now);
+            const expired = current.leases.length - active.length;
+            if (expired === 0)
+                continue;
+            if (active.length === 0) {
+                try {
+                    await kv.delete(key);
+                    purged += expired;
+                }
+                catch {
+                    // best-effort
+                }
+                continue;
+            }
+            try {
+                await kv.update(key, JSON.stringify({ leases: active }), entry.revision);
+                purged += expired;
+            }
+            catch {
+                // CAS conflict — leave for next sweep.
+            }
+        }
+        return purged;
+    }
+    /**
+     * PR 2 A6 — distinguishes legitimate "key not found" from "broker
+     * unreachable / non-NotFound error". Returns:
+     *   - `NatsKvEntry` on a successful fetch.
+     *   - `null` when the key doesn't exist (NotFound code or null entry).
+     *   - `"fetch-failed"` for any other error (transient broker outage,
+     *     auth failure, network blip, etc.) so the OCC loop can fail-fast
+     *     instead of spinning 10× before fail-closing.
+     */
+    async safeGet(kv, key) {
+        try {
+            const e = await kv.get(key);
+            return e ?? null;
+        }
+        catch (err) {
+            // NATS surfaces "not found" via a code. Different `nats`
+            // package versions use different shapes; cover the common ones.
+            const code = err.code;
+            if (code === "NotFound" || code === "404")
+                return null;
+            return "fetch-failed";
+        }
+    }
+    parseBucket(entry) {
+        try {
+            const parsed = JSON.parse(entry.string());
+            if (!parsed || !Array.isArray(parsed.leases))
+                return { leases: [] };
+            return parsed;
+        }
+        catch {
+            return { leases: [] };
+        }
+    }
+}
+//# sourceMappingURL=NatsKvConcurrencyBackend.js.map

package/dist/concurrency/NatsKvConcurrencyBackend.js.map

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

package/dist/concurrency/QueueExpiredError.d.ts

@@ -0,0 +1,40 @@
+/**
+ * PR 1-5 polish · thrown by `TriggerBase.run()` when a queued run's
+ * `concurrencyQueueTimeoutMs` (PR 5 B2) has elapsed before the gate granted
+ * a slot.
+ *
+ * Distinct from `ConcurrencyLimitError`: a TTL-expired queued run will NEVER
+ * succeed (the timer won't re-fire). Conflating it with a transient denial
+ * misleads HTTP clients into retrying — the queued run is permanently dead,
+ * so the only correct response is `410 Gone`.
+ *
+ * Triggers catch this and translate:
+ * - HTTP trigger → `410 Gone` with structured body (no `Retry-After` — it
+ *   would contradict the 410 contract).
+ * - Worker trigger → ACK without retry (the in-process scheduler owns the
+ *   eventual dispatch and won't reschedule an expired run).
+ *
+ * The run record itself is already flipped to `expired` by
+ * `tracker.markRunExpired` before this error is thrown, so observability
+ * surfaces (Studio status badge, `RUN_EXPIRED` event) are independent of
+ * the transport-level response.
+ */
+export interface QueueExpiredInfo {
+    /** Workflow name whose queue TTL elapsed. */
+    workflowName: string;
+    /** Resolved key value (after evaluating the `concurrencyKey` expression). */
+    concurrencyKey: string;
+    /**
+     * The deadline that was breached (ms since epoch). The run was queued
+     * with `expiresAt = scheduledAt + concurrencyQueueTimeoutMs` and the
+     * dispatcher observed `now > expiresAt`.
+     */
+    queueExpiredAt: number;
+    /** Run id allocated by the tracer; flipped to `expired` before throw. */
+    runId: string;
+}
+export declare class QueueExpiredError extends Error {
+    readonly info: QueueExpiredInfo;
+    constructor(info: QueueExpiredInfo);
+}
+export declare function isQueueExpiredError(err: unknown): err is QueueExpiredError;

package/dist/concurrency/QueueExpiredError.js

@@ -0,0 +1,15 @@
+export class QueueExpiredError extends Error {
+    info;
+    constructor(info) {
+        super(`Queued run expired for workflow '${info.workflowName}' (key='${info.concurrencyKey}', ` +
+            `queueExpiredAt=${info.queueExpiredAt}). Run will not be retried.`);
+        this.name = "QueueExpiredError";
+        this.info = info;
+        // Restore prototype chain when extending Error in transpiled code.
+        Object.setPrototypeOf(this, QueueExpiredError.prototype);
+    }
+}
+export function isQueueExpiredError(err) {
+    return err instanceof QueueExpiredError;
+}
+//# sourceMappingURL=QueueExpiredError.js.map

package/dist/concurrency/QueueExpiredError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueExpiredError.js","sourceRoot":"","sources":["../../src/concurrency/QueueExpiredError.ts"],"names":[],"mappings":"AAoCA,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC3B,IAAI,CAAmB;IAEvC,YAAY,IAAsB;QACjC,KAAK,CACJ,oCAAoC,IAAI,CAAC,YAAY,WAAW,IAAI,CAAC,cAAc,KAAK;YACvF,kBAAkB,IAAI,CAAC,cAAc,6BAA6B,CACnE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,mEAAmE;QACnE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC1D,CAAC;CACD;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC/C,OAAO,GAAG,YAAY,iBAAiB,CAAC;AACzC,CAAC"}

package/dist/concurrency/createConcurrencyBackend.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tier 2 #6 follow-up · concurrency backend factory.
+ *
+ * Reads `BLOK_CONCURRENCY_BACKEND` and returns the matching backend
+ * instance, or `null` when the user wants the default in-process behavior.
+ *
+ * Trigger packages call this in `listen()` and pass the result to
+ * `RunTracker.getInstance().setConcurrencyBackend(backend)`.
+ */
+import type { ConcurrencyBackend } from "./ConcurrencyBackend";
+/**
+ * Returns a configured `ConcurrencyBackend` based on
+ * `BLOK_CONCURRENCY_BACKEND`, or `null` for the default in-process backend.
+ *
+ * Recognized values:
+ * - unset / `""` / `"memory"` — null (use default in-process via RunStore)
+ * - `"nats-kv"` — NATS KV backend (requires `nats` package + reachable NATS server)
+ *
+ * Unknown values throw at startup with a clear error message — silently
+ * falling back would be dangerous (operator thinks they configured cross-
+ * process coordination but they didn't).
+ */
+export declare function createConcurrencyBackend(): ConcurrencyBackend | null;

package/dist/concurrency/createConcurrencyBackend.js

@@ -0,0 +1,34 @@
+/**
+ * Tier 2 #6 follow-up · concurrency backend factory.
+ *
+ * Reads `BLOK_CONCURRENCY_BACKEND` and returns the matching backend
+ * instance, or `null` when the user wants the default in-process behavior.
+ *
+ * Trigger packages call this in `listen()` and pass the result to
+ * `RunTracker.getInstance().setConcurrencyBackend(backend)`.
+ */
+import { NatsKvConcurrencyBackend } from "./NatsKvConcurrencyBackend";
+/**
+ * Returns a configured `ConcurrencyBackend` based on
+ * `BLOK_CONCURRENCY_BACKEND`, or `null` for the default in-process backend.
+ *
+ * Recognized values:
+ * - unset / `""` / `"memory"` — null (use default in-process via RunStore)
+ * - `"nats-kv"` — NATS KV backend (requires `nats` package + reachable NATS server)
+ *
+ * Unknown values throw at startup with a clear error message — silently
+ * falling back would be dangerous (operator thinks they configured cross-
+ * process coordination but they didn't).
+ */
+export function createConcurrencyBackend() {
+    const kind = (process.env.BLOK_CONCURRENCY_BACKEND ?? "").trim().toLowerCase();
+    if (!kind || kind === "memory" || kind === "in-process")
+        return null;
+    switch (kind) {
+        case "nats-kv":
+            return new NatsKvConcurrencyBackend();
+        default:
+            throw new Error(`Unknown BLOK_CONCURRENCY_BACKEND='${kind}'. Expected one of: 'memory' (default), 'nats-kv'.`);
+    }
+}
+//# sourceMappingURL=createConcurrencyBackend.js.map

package/dist/concurrency/createConcurrencyBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createConcurrencyBackend.js","sourceRoot":"","sources":["../../src/concurrency/createConcurrencyBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAEtE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB;IACvC,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/E,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IAErE,QAAQ,IAAI,EAAE,CAAC;QACd,KAAK,SAAS;YACb,OAAO,IAAI,wBAAwB,EAAE,CAAC;QACvC;YACC,MAAM,IAAI,KAAK,CAAC,qCAAqC,IAAI,oDAAoD,CAAC,CAAC;IACjH,CAAC;AACF,CAAC"}

package/dist/concurrency/readConcurrencyConfig.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Tier 2 #6 — extract concurrency-key config from a workflow's trigger
+ * block, regardless of which trigger type owns it (HTTP, Worker, …).
+ *
+ * Returns null when the trigger has no concurrency gate. The caller (a
+ * `TriggerBase.run()` invocation) treats null as "skip the gate, run the
+ * workflow normally" — zero-overhead default.
+ *
+ * Triggers that gain support for concurrency keys later only need to
+ * appear in {@link CONCURRENCY_TRIGGER_KEYS}.
+ */
+/** Parsed, normalized concurrency config ready for the gate. */
+export interface NormalizedConcurrencyConfig {
+    /** The literal or `js/...` expression to resolve at run time. */
+    keyExpression: string;
+    /** Maximum concurrent runs per resolved key. */
+    limit: number;
+    /** Lease duration for the slot in milliseconds. */
+    leaseMs: number;
+    /**
+     * Behavior when the gate denies acquisition.
+     * - `"throw"` (default): emit `ConcurrencyLimitError` → HTTP 429 / Worker NACK.
+     * - `"queue"`: defer the run via `DeferredRunScheduler`, throw
+     *   `DeferredDispatchSignal` with status `"queued"`.
+     *
+     * Tier 2 #6 follow-up. Reuses the Tier 2 #5+#7 deferred-dispatch plumbing.
+     */
+    onLimit: "throw" | "queue";
+    /**
+     * PR 5 B2 — TTL on queued runs in milliseconds. When set AND
+     * `onLimit === "queue"`, queued runs that age past this timeout flip
+     * to `expired` instead of re-queueing. Undefined = retry indefinitely
+     * (lease-bounded).
+     */
+    queueTimeoutMs?: number;
+    /**
+     * PR 5 B3 — capped exponential backoff config for `onLimit:queue`
+     * re-defer. Replaces the fixed 1s. Defaults applied at gate time:
+     * min=1000, max=30000, factor=2.
+     */
+    queueRetry?: {
+        minBackoffMs?: number;
+        maxBackoffMs?: number;
+        factor?: number;
+    };
+}
+/**
+ * Read a workflow's trigger config and return the normalized concurrency
+ * gate configuration, or null when the workflow has no gate.
+ *
+ * Defaults are applied here:
+ * - `concurrencyLimit` → `1` (Trigger.dev "named mutex per key" parity).
+ * - `concurrencyLeaseMs` → 1 hour, override via `BLOK_CONCURRENCY_LEASE_MS`
+ *   process-wide.
+ */
+export declare function readConcurrencyConfig(trigger: Record<string, unknown> | undefined | null): NormalizedConcurrencyConfig | null;
+export declare const CONCURRENCY_DEFAULTS: {
+    readonly limit: 1;
+    readonly leaseMs: number;
+};

package/dist/concurrency/readConcurrencyConfig.js

@@ -0,0 +1,60 @@
+/**
+ * Tier 2 #6 — extract concurrency-key config from a workflow's trigger
+ * block, regardless of which trigger type owns it (HTTP, Worker, …).
+ *
+ * Returns null when the trigger has no concurrency gate. The caller (a
+ * `TriggerBase.run()` invocation) treats null as "skip the gate, run the
+ * workflow normally" — zero-overhead default.
+ *
+ * Triggers that gain support for concurrency keys later only need to
+ * appear in {@link CONCURRENCY_TRIGGER_KEYS}.
+ */
+/** Trigger types whose schema declares the `ConcurrencyOptsFields` mixin. */
+const CONCURRENCY_TRIGGER_KEYS = ["http", "worker"];
+const DEFAULT_LIMIT = 1;
+const DEFAULT_LEASE_MS = 60 * 60 * 1000;
+/**
+ * Read a workflow's trigger config and return the normalized concurrency
+ * gate configuration, or null when the workflow has no gate.
+ *
+ * Defaults are applied here:
+ * - `concurrencyLimit` → `1` (Trigger.dev "named mutex per key" parity).
+ * - `concurrencyLeaseMs` → 1 hour, override via `BLOK_CONCURRENCY_LEASE_MS`
+ *   process-wide.
+ */
+export function readConcurrencyConfig(trigger) {
+    if (!trigger)
+        return null;
+    for (const key of CONCURRENCY_TRIGGER_KEYS) {
+        const cfg = trigger[key];
+        if (!cfg)
+            continue;
+        const keyExpression = typeof cfg.concurrencyKey === "string" ? cfg.concurrencyKey.trim() : "";
+        if (!keyExpression)
+            continue;
+        const limit = Number.isInteger(cfg.concurrencyLimit) ? cfg.concurrencyLimit : DEFAULT_LIMIT;
+        const envLeaseRaw = process.env.BLOK_CONCURRENCY_LEASE_MS;
+        const envLease = envLeaseRaw && /^\d+$/.test(envLeaseRaw) ? Number(envLeaseRaw) : null;
+        const perTriggerLease = Number.isInteger(cfg.concurrencyLeaseMs) ? cfg.concurrencyLeaseMs : null;
+        // Per-trigger value wins over env override; env wins over the hard default.
+        const leaseMs = perTriggerLease ?? envLease ?? DEFAULT_LEASE_MS;
+        // onLimit: only "throw" (default) and "queue" are valid; anything else
+        // falls back to "throw" (defensive — schema already rejects bad values).
+        const onLimit = cfg.onLimit === "queue" ? "queue" : "throw";
+        // PR 5 B2 — queue TTL. Only meaningful when onLimit === "queue".
+        const queueTimeoutMs = onLimit === "queue" && Number.isInteger(cfg.concurrencyQueueTimeoutMs)
+            ? cfg.concurrencyQueueTimeoutMs
+            : undefined;
+        // PR 5 B3 — capped exponential backoff. Only meaningful when onLimit === "queue".
+        const queueRetry = onLimit === "queue" && cfg.concurrencyQueueRetry && typeof cfg.concurrencyQueueRetry === "object"
+            ? cfg.concurrencyQueueRetry
+            : undefined;
+        return { keyExpression, limit, leaseMs, onLimit, queueTimeoutMs, queueRetry };
+    }
+    return null;
+}
+export const CONCURRENCY_DEFAULTS = {
+    limit: DEFAULT_LIMIT,
+    leaseMs: DEFAULT_LEASE_MS,
+};
+//# sourceMappingURL=readConcurrencyConfig.js.map

package/dist/concurrency/readConcurrencyConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readConcurrencyConfig.js","sourceRoot":"","sources":["../../src/concurrency/readConcurrencyConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,6EAA6E;AAC7E,MAAM,wBAAwB,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAU,CAAC;AAE7D,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,gBAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAsCxC;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACpC,OAAmD;IAEnD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,KAAK,MAAM,GAAG,IAAI,wBAAwB,EAAE,CAAC;QAC5C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CASX,CAAC;QACb,IAAI,CAAC,GAAG;YAAE,SAAS;QAEnB,MAAM,aAAa,GAAG,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9F,IAAI,CAAC,aAAa;YAAE,SAAS;QAE7B,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,gBAA2B,CAAC,CAAC,CAAC,aAAa,CAAC;QAExG,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;QAC1D,MAAM,QAAQ,GAAG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACvF,MAAM,eAAe,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,kBAA6B,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7G,4EAA4E;QAC5E,MAAM,OAAO,GAAG,eAAe,IAAI,QAAQ,IAAI,gBAAgB,CAAC;QAEhE,uEAAuE;QACvE,yEAAyE;QACzE,MAAM,OAAO,GAAsB,GAAG,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QAE/E,iEAAiE;QACjE,MAAM,cAAc,GACnB,OAAO,KAAK,OAAO,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,yBAAyB,CAAC;YACrE,CAAC,CAAE,GAAG,CAAC,yBAAoC;YAC3C,CAAC,CAAC,SAAS,CAAC;QAEd,kFAAkF;QAClF,MAAM,UAAU,GACf,OAAO,KAAK,OAAO,IAAI,GAAG,CAAC,qBAAqB,IAAI,OAAO,GAAG,CAAC,qBAAqB,KAAK,QAAQ;YAChG,CAAC,CAAE,GAAG,CAAC,qBAAmE;YAC1E,CAAC,CAAC,SAAS,CAAC;QAEd,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC;IAC/E,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAG;IACnC,KAAK,EAAE,aAAa;IACpB,OAAO,EAAE,gBAAgB;CAChB,CAAC"}

package/dist/idempotency/resolveIdempotencyKey.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from "@blokjs/shared";
+/**
+ * Resolve a step's `idempotencyKey` value against the live context.
+ *
+ * Authors may write a literal string (`"static-key"`) OR a `$ proxy`
+ * expression that compiled to a `js/...` string at workflow-definition
+ * time (`"js/ctx.req.body.requestId"` produced by `$.req.body.requestId`).
+ * This helper handles both.
+ *
+ * Returns `null` when:
+ * - the key is undefined / empty / not a string
+ * - the `js/` expression evaluates to null/undefined
+ * - the `js/` expression throws (treat as cache miss; the step still runs)
+ *
+ * The helper never throws — a failed key resolution falls back to "no
+ * caching for this step on this run", which is the safest interpretation.
+ *
+ * @internal Used by `RunnerSteps` before consulting the idempotency cache.
+ */
+export declare function resolveIdempotencyKey(rawKey: string | undefined, ctx: Context): string | null;

package/dist/idempotency/resolveIdempotencyKey.js

@@ -0,0 +1,37 @@
+const JS_PREFIX = "js/";
+/**
+ * Resolve a step's `idempotencyKey` value against the live context.
+ *
+ * Authors may write a literal string (`"static-key"`) OR a `$ proxy`
+ * expression that compiled to a `js/...` string at workflow-definition
+ * time (`"js/ctx.req.body.requestId"` produced by `$.req.body.requestId`).
+ * This helper handles both.
+ *
+ * Returns `null` when:
+ * - the key is undefined / empty / not a string
+ * - the `js/` expression evaluates to null/undefined
+ * - the `js/` expression throws (treat as cache miss; the step still runs)
+ *
+ * The helper never throws — a failed key resolution falls back to "no
+ * caching for this step on this run", which is the safest interpretation.
+ *
+ * @internal Used by `RunnerSteps` before consulting the idempotency cache.
+ */
+export function resolveIdempotencyKey(rawKey, ctx) {
+    if (typeof rawKey !== "string" || rawKey.length === 0)
+        return null;
+    if (!rawKey.startsWith(JS_PREFIX))
+        return rawKey;
+    const expr = rawKey.slice(JS_PREFIX.length);
+    try {
+        const fn = new Function("ctx", `"use strict"; return (${expr});`);
+        const value = fn(ctx);
+        if (value === null || value === undefined)
+            return null;
+        return String(value);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=resolveIdempotencyKey.js.map

package/dist/idempotency/resolveIdempotencyKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveIdempotencyKey.js","sourceRoot":"","sources":["../../src/idempotency/resolveIdempotencyKey.ts"],"names":[],"mappings":"AAEA,MAAM,SAAS,GAAG,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAA0B,EAAE,GAAY;IAC7E,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,MAAM,CAAC;IAEjD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC;QACJ,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,KAAK,EAAE,yBAAyB,IAAI,IAAI,CAAC,CAAC;QAClE,MAAM,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACvD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC"}