@blokjs/runner 0.2.1 → 0.4.0

package/dist/adapters/transport.js

@@ -0,0 +1,196 @@
+/**
+ * Resolve the transport to use for a given runtime kind from the environment.
+ *
+ * Precedence (most specific wins):
+ *   1. `RUNTIME_<KIND>_TRANSPORT` — per-kind override
+ *      e.g. `RUNTIME_PYTHON3_TRANSPORT=http` to opt one SDK out of gRPC.
+ *   2. `RUNTIME_TRANSPORT` — global override
+ *      e.g. `RUNTIME_TRANSPORT=http` to roll back the whole runner.
+ *   3. The hard-coded default — **`grpc`** as of Phase 6 (master plan §11).
+ *      Flipped from `http` to `grpc` after the cross-language parity matrix
+ *      (`bun run test:parity`, 33 tests across 6 SDKs × 5 workflows) and
+ *      the per-SDK §17 BlokError E2E suites stayed green for the full
+ *      Phase 5 observation window.
+ *
+ * Pure function — reads `process.env` once per call so tests can override.
+ *
+ * # Why the default flip is safe
+ *
+ * - HTTP transport remains available behind `RUNTIME_TRANSPORT=http` for at
+ *   least two minor versions (master plan §11 commitment).
+ * - PHP without RoadRunner (Path B from §16) sets
+ *   `RUNTIME_PHP_TRANSPORT=http` per host. The forever-supported escape
+ *   hatch is unaffected.
+ * - SDKs that fail to bind their gRPC listener fall through the
+ *   {@link GrpcHealthChecker} circuit-breaker and surface a typed
+ *   `BlokError(category=DEPENDENCY)` per §9 — no silent failure.
+ *
+ * @param kind The runtime kind (e.g. "python3").
+ * @param env Optional env source (defaults to `process.env`). Tests can
+ *            pass a stub map.
+ * @returns Either `"http"` or `"grpc"`. Invalid values fall back to the
+ *          Phase 6 default (`grpc`).
+ */
+export function resolveTransportForKind(kind, env = process.env) {
+    const perKindKey = `RUNTIME_${kind.toUpperCase()}_TRANSPORT`;
+    const perKind = env[perKindKey];
+    if (perKind === "grpc" || perKind === "http") {
+        if (perKind === "http")
+            warnDeprecatedHttpTransport(perKindKey);
+        return perKind;
+    }
+    const global = env.RUNTIME_TRANSPORT;
+    if (global === "grpc" || global === "http") {
+        if (global === "http")
+            warnDeprecatedHttpTransport("RUNTIME_TRANSPORT");
+        return global;
+    }
+    // Phase 6 default: gRPC. The flip from HTTP landed once the parity
+    // matrix had been green for the observation window.
+    return "grpc";
+}
+/**
+ * Set of env-var names that have already triggered the deprecation warning
+ * in this process. Prevents log spam when many runtime kinds resolve through
+ * the same global override on each request.
+ *
+ * Exported as a reset hook for tests — production code never touches it.
+ */
+const _httpDeprecationWarned = new Set();
+function warnDeprecatedHttpTransport(envKey) {
+    if (_httpDeprecationWarned.has(envKey))
+        return;
+    _httpDeprecationWarned.add(envKey);
+    console.warn(`[blok] ${envKey}=http is deprecated and will be removed in v0.4.0. Migrate to gRPC by dropping the env var (gRPC is the default since Phase 6) and ensuring your SDK process boots with BLOK_TRANSPORT=grpc.`);
+}
+/**
+ * Test-only — reset the per-process HTTP-transport deprecation cache so a
+ * test that flips `RUNTIME_TRANSPORT=http` can re-assert the warning fires.
+ *
+ * @internal
+ */
+export function _resetHttpDeprecationCache() {
+    _httpDeprecationWarned.clear();
+}
+/**
+ * Whether log streaming is enabled for runtime nodes. When true, the runner
+ * routes runtime nodes through `GrpcRuntimeAdapter.executeStream` instead of
+ * the unary `execute`, and `LogLine` frames flow into `RunTracker.addLog`
+ * — surfacing live in Studio's `/__blok/runs/:id/stream` SSE endpoint.
+ *
+ * Streaming is a pure additive capability: when the env var is unset, the
+ * legacy unary path runs unchanged. When enabled but the adapter doesn't
+ * support streaming (e.g. HttpRuntimeAdapter), `RuntimeAdapterNode` falls
+ * back to unary so misconfiguration never blocks execution.
+ *
+ * Recognized as truthy: `1`, `true`, `yes`, `on` (case-insensitive). Anything
+ * else (including unset, empty, `0`, `false`) returns false.
+ */
+export function isStreamLogsEnabled(env = process.env) {
+    return isTruthyFlag(env.BLOK_STREAM_LOGS);
+}
+/**
+ * Resolve the gRPC background health-check interval from the environment.
+ *
+ * `BLOK_GRPC_HEALTH_INTERVAL_MS` is the global override:
+ *   - any positive integer → use that interval
+ *   - `0` → disable the loop entirely (useful in tests)
+ *   - unset / non-numeric → return undefined; adapter uses
+ *     {@link GRPC_DEFAULTS.HEALTH_INTERVAL_MS}.
+ */
+export function resolveHealthCheckIntervalMs(env = process.env) {
+    const raw = env.BLOK_GRPC_HEALTH_INTERVAL_MS;
+    if (raw === undefined || raw === "")
+        return undefined;
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isNaN(parsed) || parsed < 0)
+        return undefined;
+    return parsed;
+}
+/**
+ * Resolve the consecutive-failure threshold for the gRPC circuit breaker.
+ *
+ * `BLOK_GRPC_HEALTH_FAILURE_THRESHOLD` overrides the default
+ * ({@link GRPC_DEFAULTS.HEALTH_FAILURE_THRESHOLD}). Values < 1 are ignored
+ * (the checker requires ≥ 1 failure to trip).
+ */
+export function resolveHealthCheckFailureThreshold(env = process.env) {
+    const raw = env.BLOK_GRPC_HEALTH_FAILURE_THRESHOLD;
+    if (raw === undefined || raw === "")
+        return undefined;
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isNaN(parsed) || parsed < 1)
+        return undefined;
+    return parsed;
+}
+/**
+ * Build a {@link TlsConfig} for a given runtime kind from environment
+ * variables. Returns `undefined` when nothing is configured (channel stays
+ * plaintext — appropriate for loopback dev).
+ *
+ * Per-kind env vars (taking precedence):
+ *   - `RUNTIME_<KIND>_TLS_CA`              CA cert path (PEM)
+ *   - `RUNTIME_<KIND>_TLS_CLIENT_CERT`     client cert path (PEM, mTLS)
+ *   - `RUNTIME_<KIND>_TLS_CLIENT_KEY`      client key path (PEM, mTLS)
+ *   - `RUNTIME_<KIND>_TLS_SERVER_NAME`     SNI override
+ *   - `RUNTIME_<KIND>_TLS_INSECURE_SKIP_VERIFY=true`  dev-only
+ *
+ * Global fallbacks (apply when the per-kind var is unset):
+ *   - `BLOK_GRPC_TLS_CA`, `BLOK_GRPC_TLS_CLIENT_CERT`, `BLOK_GRPC_TLS_CLIENT_KEY`,
+ *     `BLOK_GRPC_TLS_SERVER_NAME`, `BLOK_GRPC_TLS_INSECURE_SKIP_VERIFY`.
+ *
+ * If none of the relevant env vars are set, returns `undefined`.
+ */
+export function loadTlsConfigForKind(kind, env = process.env) {
+    const upperKind = kind.toUpperCase();
+    const pick = (suffix) => env[`RUNTIME_${upperKind}_TLS_${suffix}`] ?? env[`BLOK_GRPC_TLS_${suffix}`];
+    const caCertPath = pick("CA");
+    const clientCertPath = pick("CLIENT_CERT");
+    const clientKeyPath = pick("CLIENT_KEY");
+    const serverNameOverride = pick("SERVER_NAME");
+    const insecureSkipVerifyRaw = pick("INSECURE_SKIP_VERIFY");
+    const insecureSkipVerify = isTruthyFlag(insecureSkipVerifyRaw);
+    const anySet = caCertPath !== undefined ||
+        clientCertPath !== undefined ||
+        clientKeyPath !== undefined ||
+        serverNameOverride !== undefined ||
+        insecureSkipVerify;
+    if (!anySet)
+        return undefined;
+    return {
+        caCertPath,
+        clientCertPath,
+        clientKeyPath,
+        serverNameOverride,
+        insecureSkipVerify,
+    };
+}
+/**
+ * Whether `BLOK_GRPC_REQUIRE_TLS=true` enforces TLS on non-loopback hosts.
+ * When true, building a gRPC adapter with no TLS config against a non-loopback
+ * host throws at startup. Loopback (localhost, 127.0.0.0/8, ::1) is exempted.
+ */
+export function isStrictTlsEnabled(env = process.env) {
+    return isTruthyFlag(env.BLOK_GRPC_REQUIRE_TLS);
+}
+/**
+ * Returns true when the host is a loopback address that doesn't require
+ * TLS even under strict mode. Match is intentionally generous — covers
+ * `localhost`, the 127.x range, IPv6 loopback, and the wildcard 0.0.0.0
+ * (which dev SDKs commonly bind to).
+ */
+export function isLoopbackHost(host) {
+    const normalized = host.trim().toLowerCase();
+    if (normalized === "localhost" || normalized === "::1" || normalized === "0.0.0.0")
+        return true;
+    if (normalized.startsWith("127."))
+        return true;
+    return false;
+}
+function isTruthyFlag(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+//# sourceMappingURL=transport.js.map

package/dist/adapters/transport.js.map

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

package/dist/concurrency/ConcurrencyBackend.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Tier 2 #6 follow-up · cross-process concurrency backend.
+ *
+ * Optional capability layer that lets `RunTracker.acquireConcurrencySlot`
+ * delegate to a backend with cross-process semantics (NATS KV, future
+ * Redis) instead of the local sync `RunStore` impl.
+ *
+ * Default behavior is unchanged — when no backend is set, the tracker
+ * uses the existing `store.acquireConcurrencySlot` (single-process via
+ * SQLite locks or in-memory Map). The backend is opt-in via
+ * `BLOK_CONCURRENCY_BACKEND=nats-kv` and installed by trigger packages
+ * during `listen()`.
+ *
+ * Async-only — NATS KV operations require network round-trips. The
+ * sync `RunStore` interface remains untouched (no breaking change to
+ * existing extension points); the tracker bridges async + sync via
+ * `Promise.resolve()` when no backend is set.
+ */
+import type { ConcurrencySlotResult } from "../tracing/types";
+export interface ConcurrencyBackend {
+    /**
+     * Identifying string for logs/metrics. e.g. `"nats-kv"`, `"redis"`.
+     */
+    readonly name: string;
+    /**
+     * Lifecycle — open the underlying connection. Idempotent. Called
+     * once when the trigger installs the backend during `listen()`.
+     */
+    connect(): Promise<void>;
+    /**
+     * Lifecycle — close the underlying connection. Idempotent. Called
+     * on graceful process shutdown (when wired).
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Atomically attempt to acquire a slot for the
+     * `(workflowName, concurrencyKey)` bucket against the given limit.
+     *
+     * Contract — must match {@link RunStore.acquireConcurrencySlot}:
+     * - Lazy-purge expired leases on the bucket before counting.
+     * - Idempotent re-acquire: same `runId` refreshes the lease,
+     *   does NOT grow the count.
+     * - On count >= limit: return `{acquired: false, currentInFlight}`
+     *   without inserting.
+     * - On grant: return `{acquired: true, currentInFlight}` where
+     *   `currentInFlight` includes the just-acquired slot.
+     */
+    acquireSlot(workflowName: string, concurrencyKey: string, concurrencyLimit: number, runId: string, leaseExpiresAt: number): Promise<ConcurrencySlotResult>;
+    /**
+     * Release a slot. Idempotent. Safe to call on `runId`s that don't
+     * hold a slot (e.g. crash + restart releases via lease expiry).
+     */
+    releaseSlot(workflowName: string, concurrencyKey: string, runId: string): Promise<void>;
+    /**
+     * Janitor sweep — purge every lease whose `expiresAt <= now` across
+     * all buckets. Returns the count of purged leases. Cheap per-bucket
+     * lazy-purge happens on every acquire; this method is for global
+     * cleanup (e.g., periodic background task).
+     */
+    purgeExpired(now: number): Promise<number>;
+}

package/dist/concurrency/ConcurrencyBackend.js

@@ -0,0 +1,20 @@
+/**
+ * Tier 2 #6 follow-up · cross-process concurrency backend.
+ *
+ * Optional capability layer that lets `RunTracker.acquireConcurrencySlot`
+ * delegate to a backend with cross-process semantics (NATS KV, future
+ * Redis) instead of the local sync `RunStore` impl.
+ *
+ * Default behavior is unchanged — when no backend is set, the tracker
+ * uses the existing `store.acquireConcurrencySlot` (single-process via
+ * SQLite locks or in-memory Map). The backend is opt-in via
+ * `BLOK_CONCURRENCY_BACKEND=nats-kv` and installed by trigger packages
+ * during `listen()`.
+ *
+ * Async-only — NATS KV operations require network round-trips. The
+ * sync `RunStore` interface remains untouched (no breaking change to
+ * existing extension points); the tracker bridges async + sync via
+ * `Promise.resolve()` when no backend is set.
+ */
+export {};
+//# sourceMappingURL=ConcurrencyBackend.js.map

package/dist/concurrency/ConcurrencyBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConcurrencyBackend.js","sourceRoot":"","sources":["../../src/concurrency/ConcurrencyBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/concurrency/ConcurrencyLimitError.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tier 2 #6 — thrown by `TriggerBase.run()` when a workflow's concurrency
+ * gate denies a run because the in-flight count for the resolved
+ * `concurrencyKey` has reached `concurrencyLimit`.
+ *
+ * Triggers catch this and translate it into the appropriate transport-level
+ * response:
+ * - HTTP trigger → `429 Too Many Requests` with `Retry-After` header.
+ * - Worker trigger → NACK with redelivery (existing job-queue retry handles
+ *   spacing).
+ *
+ * Carries enough context for both observability (logs / Studio events) and
+ * client-facing error payloads.
+ */
+export interface ConcurrencyLimitInfo {
+    /** Workflow name whose gate fired. */
+    workflowName: string;
+    /** Resolved key value (after evaluating the `concurrencyKey` expression). */
+    concurrencyKey: string;
+    /** Per-key limit from the trigger config. */
+    concurrencyLimit: number;
+    /** Number of in-flight runs observed at the moment of denial. */
+    currentInFlight: number;
+    /**
+     * Suggested back-off in milliseconds before retrying. A heuristic — the
+     * gate doesn't observe a queue, so we recommend a minimum (the default
+     * matches the smallest meaningful HTTP `Retry-After` precision = 1s).
+     */
+    retryAfterMs: number;
+    /** Run id allocated by the tracer for this denied attempt. */
+    runId: string;
+}
+export declare class ConcurrencyLimitError extends Error {
+    readonly info: ConcurrencyLimitInfo;
+    constructor(info: ConcurrencyLimitInfo);
+}
+export declare function isConcurrencyLimitError(err: unknown): err is ConcurrencyLimitError;

package/dist/concurrency/ConcurrencyLimitError.js

@@ -0,0 +1,16 @@
+export class ConcurrencyLimitError extends Error {
+    info;
+    constructor(info) {
+        super(`Concurrency limit reached for workflow '${info.workflowName}' (key='${info.concurrencyKey}', ` +
+            `limit=${info.concurrencyLimit}, currentInFlight=${info.currentInFlight}). ` +
+            `Retry after ~${info.retryAfterMs}ms.`);
+        this.name = "ConcurrencyLimitError";
+        this.info = info;
+        // Restore prototype chain when extending Error in transpiled code.
+        Object.setPrototypeOf(this, ConcurrencyLimitError.prototype);
+    }
+}
+export function isConcurrencyLimitError(err) {
+    return err instanceof ConcurrencyLimitError;
+}
+//# sourceMappingURL=ConcurrencyLimitError.js.map

package/dist/concurrency/ConcurrencyLimitError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConcurrencyLimitError.js","sourceRoot":"","sources":["../../src/concurrency/ConcurrencyLimitError.ts"],"names":[],"mappings":"AAiCA,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC/B,IAAI,CAAuB;IAE3C,YAAY,IAA0B;QACrC,KAAK,CACJ,2CAA2C,IAAI,CAAC,YAAY,WAAW,IAAI,CAAC,cAAc,KAAK;YAC9F,SAAS,IAAI,CAAC,gBAAgB,qBAAqB,IAAI,CAAC,eAAe,KAAK;YAC5E,gBAAgB,IAAI,CAAC,YAAY,KAAK,CACvC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,mEAAmE;QACnE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC9D,CAAC;CACD;AAED,MAAM,UAAU,uBAAuB,CAAC,GAAY;IACnD,OAAO,GAAG,YAAY,qBAAqB,CAAC;AAC7C,CAAC"}

package/dist/concurrency/NatsKvConcurrencyBackend.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 type { ConcurrencySlotResult } from "../tracing/types";
+import type { ConcurrencyBackend } from "./ConcurrencyBackend";
+export interface NatsKvConcurrencyConfig {
+    servers: string[];
+    token?: string;
+    user?: string;
+    pass?: string;
+    bucketName: string;
+}
+/**
+ * Read configuration from environment variables. Used by
+ * {@link createConcurrencyBackend} when the user opts into NATS KV.
+ */
+export declare function readNatsKvConfigFromEnv(): NatsKvConcurrencyConfig;
+export declare class NatsKvConcurrencyBackend implements ConcurrencyBackend {
+    readonly name = "nats-kv";
+    private nc;
+    private kv;
+    private readonly config;
+    private connected;
+    constructor(config?: Partial<NatsKvConcurrencyConfig>);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private bucketKey;
+    private encodeSegment;
+    private requireKv;
+    acquireSlot(workflowName: string, concurrencyKey: string, concurrencyLimit: number, runId: string, leaseExpiresAt: number): Promise<ConcurrencySlotResult>;
+    releaseSlot(workflowName: string, concurrencyKey: string, runId: string): Promise<void>;
+    purgeExpired(now: number): Promise<number>;
+    /**
+     * 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.
+     */
+    private safeGet;
+    private parseBucket;
+}