@blokjs/runner 0.2.1 → 0.2.2

package/dist/adapters/grpc/GrpcCodec.d.ts

@@ -0,0 +1,226 @@
+import type { Context } from "@blokjs/shared";
+import { type ServiceClientConstructor } from "@grpc/grpc-js";
+import type RunnerNode from "../../RunnerNode";
+/**
+ * The {@link NodeRuntime} service client constructor — used by
+ * {@link GrpcClientPool} to instantiate clients.
+ */
+export declare const NodeRuntimeService: ServiceClientConstructor;
+export interface ExecuteRequestProto {
+    node: NodeRefProto;
+    inputs: Buffer;
+    step: StepInfoProto;
+    trigger: TriggerInfoProto;
+    state: RuntimeStateProto;
+    workflow: WorkflowInfoProto;
+    options: ExecuteOptionsProto;
+}
+export interface NodeRefProto {
+    name: string;
+    type: string;
+    version: string;
+}
+export interface StepInfoProto {
+    name: string;
+    index: number;
+    total: number;
+    depth: number;
+}
+export interface TriggerInfoProto {
+    body: Buffer;
+    headers: Record<string, string>;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    cookies: Record<string, string>;
+    method: string;
+    url: string;
+    baseUrl: string;
+    triggerKind: string;
+}
+export interface RuntimeStateProto {
+    previousOutput: Buffer;
+    vars: Buffer;
+    env: Record<string, string>;
+}
+export interface WorkflowInfoProto {
+    runId: string;
+    name: string;
+    path: string;
+    version: string;
+    startedAt: {
+        seconds: string;
+        nanos: number;
+    } | null;
+}
+export interface ExecuteOptionsProto {
+    deadlineMs: string;
+    streamLogs: boolean;
+    captureMetrics: boolean;
+    hints: Record<string, string>;
+}
+export interface ExecuteResponseProto {
+    success: boolean;
+    data: Buffer;
+    contentType: string;
+    error: NodeErrorProto | null;
+    varsDelta: Buffer;
+    logs: LogLineProto[];
+    metrics: MetricsProto | null;
+}
+export interface NodeErrorProto {
+    code: string;
+    category: string;
+    severity: string;
+    node: string;
+    sdk: string;
+    sdkVersion: string;
+    runtimeKind: string;
+    at: {
+        seconds: string;
+        nanos: number;
+    } | null;
+    message: string;
+    description: string;
+    remediation: string;
+    docUrl: string;
+    causes: NodeErrorProto[];
+    stack: string;
+    contextSnapshotJson: Buffer;
+    httpStatus: number;
+    retryable: boolean;
+    retryAfterMs: string;
+    detailsJson: Buffer;
+}
+export interface LogLineProto {
+    timestamp: {
+        seconds: string;
+        nanos: number;
+    } | null;
+    level: string;
+    message: string;
+    attributes: Record<string, string>;
+}
+export interface MetricsProto {
+    durationMs: number;
+    cpuMs: number;
+    memoryBytes: string;
+    requestBytes: string;
+    responseBytes: string;
+}
+export interface DecodedExecuteResponse {
+    readonly success: boolean;
+    readonly data: unknown;
+    readonly contentType: string;
+    readonly varsDelta: Record<string, unknown>;
+    readonly logs: ReadonlyArray<DecodedLogLine>;
+    readonly error: DecodedNodeError | null;
+    readonly metrics: DecodedMetrics;
+}
+export interface DecodedLogLine {
+    readonly timestamp: number;
+    readonly level: string;
+    readonly message: string;
+    readonly attributes: Record<string, string>;
+}
+export interface DecodedNodeError {
+    readonly code: string;
+    readonly category: string;
+    readonly severity: string;
+    readonly node: string;
+    readonly sdk: string;
+    readonly sdkVersion: string;
+    readonly runtimeKind: string;
+    readonly at: number;
+    readonly message: string;
+    readonly description: string;
+    readonly remediation: string;
+    readonly docUrl: string;
+    readonly causes: ReadonlyArray<DecodedNodeError>;
+    readonly stack: string;
+    readonly contextSnapshot: unknown;
+    readonly httpStatus: number;
+    readonly retryable: boolean;
+    readonly retryAfterMs: number;
+    readonly details: unknown;
+}
+export interface DecodedMetrics {
+    readonly durationMs: number;
+    readonly cpuMs: number;
+    readonly memoryBytes: number;
+    readonly requestBytes: number;
+    readonly responseBytes: number;
+}
+/**
+ * Encode a workflow {@link Context} and a {@link RunnerNode} into a
+ * {@link ExecuteRequestProto} ready for the gRPC wire.
+ *
+ * Pure function — no I/O. The opaque JSON-shaped fields (`inputs`,
+ * `previous_output`, `vars`, body) are serialized to UTF-8 bytes here so the
+ * SDK side can JSON-decode lazily.
+ *
+ * Critically, `inputs` is the resolved node config (from the Blueprint
+ * Mapper) sent UNWRAPPED — no `{inputs:{...}}` envelope. This closes the
+ * `BLOK_FRAMEWORK_FIXES.md` #3 unwrap-hack family of bugs at the wire format
+ * layer.
+ */
+export declare function encodeExecuteRequest(node: RunnerNode, ctx: Context, stepIndex: number, stepTotal: number, stepDepth: number, deadlineMs: number): ExecuteRequestProto;
+/**
+ * Proto envelope for a streamed event. proto-loader with `oneofs: true`
+ * exposes the active oneof case via the `event` property AND mirrors the
+ * matching field at the top level. We discriminate on `event`.
+ */
+export interface ExecuteEventProto {
+    event: "started" | "log" | "progress" | "partial" | "final" | undefined;
+    started?: {
+        at: {
+            seconds: string;
+            nanos: number;
+        } | null;
+    };
+    log?: LogLineProto;
+    progress?: {
+        percent: number;
+        phase: string;
+    };
+    partial?: {
+        snapshotJson: Buffer;
+    };
+    final?: ExecuteResponseProto;
+}
+/**
+ * Adapter-facing discriminated union — keeps callers free of proto-loader
+ * shape concerns and lets TypeScript narrow on the `type` field.
+ */
+export type DecodedExecuteEvent = {
+    readonly type: "started";
+    readonly at: number;
+} | {
+    readonly type: "log";
+    readonly log: DecodedLogLine;
+} | {
+    readonly type: "progress";
+    readonly percent: number;
+    readonly phase: string;
+} | {
+    readonly type: "partial";
+    readonly snapshot: unknown;
+} | {
+    readonly type: "final";
+    readonly response: DecodedExecuteResponse;
+};
+/**
+ * Decode a single streamed `ExecuteEvent` proto into the discriminated union
+ * the adapter exposes. Returns `null` when the proto envelope is empty (no
+ * oneof field set) — the caller skips such frames.
+ */
+export declare function decodeExecuteEvent(event: ExecuteEventProto): DecodedExecuteEvent | null;
+/**
+ * Decode a {@link ExecuteResponseProto} from the wire into the shape the
+ * adapter consumes. Defensive against missing fields (proto-loader fills in
+ * defaults, but we guard against malformed responses too).
+ */
+export declare function decodeExecuteResponse(response: ExecuteResponseProto): DecodedExecuteResponse;
+/** Encode a value as UTF-8 JSON bytes. `null`/`undefined` → empty buffer. */
+export declare function jsonToBuffer(value: unknown): Buffer;
+/** Decode a buffer as UTF-8 JSON. Empty/missing buffer → `null`. */
+export declare function bufferToJson(buf: Buffer | undefined): unknown;

package/dist/adapters/grpc/GrpcCodec.js

@@ -0,0 +1,275 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadPackageDefinition } from "@grpc/grpc-js";
+import { loadSync } from "@grpc/proto-loader";
+// =============================================================================
+// Proto loading — single point of I/O in this module
+// =============================================================================
+/**
+ * Resolve the path to `runtime.proto`. Prefers the dist-bundled copy at
+ * runtime; falls back to the src copy when running from source.
+ */
+function resolveProtoPath() {
+    // `import.meta.url` works under both Node ESM and Bun. The dist copy
+    // sits next to the compiled JS; src copy sits next to TS source.
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "proto/blok/runtime/v1/runtime.proto");
+}
+/** Options for `@grpc/proto-loader` — chosen for fidelity with our schema. */
+const PROTO_LOADER_OPTIONS = {
+    keepCase: false, // snake_case in proto -> camelCase in JS for ergonomic field access
+    longs: String,
+    enums: String,
+    defaults: true,
+    oneofs: true,
+    includeDirs: [],
+};
+/** Loaded once at module init; reused for every encode/decode. */
+const PROTO_PATH = resolveProtoPath();
+const PACKAGE_DEFINITION = loadSync(PROTO_PATH, PROTO_LOADER_OPTIONS);
+const PROTO_DESCRIPTOR = loadPackageDefinition(PACKAGE_DEFINITION);
+/** Path to the `NodeRuntime` service constructor inside the loaded proto. */
+const NODE_RUNTIME_NAMESPACE = PROTO_DESCRIPTOR.blok.runtime.v1;
+/**
+ * The {@link NodeRuntime} service client constructor — used by
+ * {@link GrpcClientPool} to instantiate clients.
+ */
+export const NodeRuntimeService = NODE_RUNTIME_NAMESPACE.NodeRuntime;
+// =============================================================================
+// Encoder — Context + RunnerNode → proto ExecuteRequest
+// =============================================================================
+/**
+ * Encode a workflow {@link Context} and a {@link RunnerNode} into a
+ * {@link ExecuteRequestProto} ready for the gRPC wire.
+ *
+ * Pure function — no I/O. The opaque JSON-shaped fields (`inputs`,
+ * `previous_output`, `vars`, body) are serialized to UTF-8 bytes here so the
+ * SDK side can JSON-decode lazily.
+ *
+ * Critically, `inputs` is the resolved node config (from the Blueprint
+ * Mapper) sent UNWRAPPED — no `{inputs:{...}}` envelope. This closes the
+ * `BLOK_FRAMEWORK_FIXES.md` #3 unwrap-hack family of bugs at the wire format
+ * layer.
+ */
+export function encodeExecuteRequest(node, ctx, stepIndex, stepTotal, stepDepth, deadlineMs) {
+    const resolvedInputs = extractResolvedInputs(ctx, node.name);
+    const previousOutput = ctx.response?.data ?? null;
+    const vars = ctx.vars ?? {};
+    const env = stringEnv(ctx.env);
+    const request = ctx.request ?? {};
+    const requestBody = request.body;
+    return {
+        node: {
+            name: node.node,
+            type: node.type ?? "",
+            version: "",
+        },
+        inputs: jsonToBuffer(resolvedInputs),
+        step: {
+            name: node.name,
+            index: stepIndex,
+            total: stepTotal,
+            depth: stepDepth,
+        },
+        trigger: {
+            body: bodyToBuffer(requestBody),
+            headers: stringMap(request.headers),
+            params: stringMap(request.params),
+            query: stringMap(request.query),
+            cookies: stringMap(request.cookies),
+            method: stringField(request.method),
+            url: stringField(request.url),
+            baseUrl: stringField(request.baseUrl),
+            triggerKind: "",
+        },
+        state: {
+            previousOutput: jsonToBuffer(previousOutput),
+            vars: jsonToBuffer(vars),
+            env,
+        },
+        workflow: {
+            runId: ctx.id,
+            name: ctx.workflow_name ?? "",
+            path: ctx.workflow_path ?? "",
+            version: "",
+            startedAt: null,
+        },
+        options: {
+            deadlineMs: String(deadlineMs),
+            streamLogs: false,
+            captureMetrics: true,
+            hints: {},
+        },
+    };
+}
+/**
+ * Decode a single streamed `ExecuteEvent` proto into the discriminated union
+ * the adapter exposes. Returns `null` when the proto envelope is empty (no
+ * oneof field set) — the caller skips such frames.
+ */
+export function decodeExecuteEvent(event) {
+    switch (event.event) {
+        case "started":
+            return { type: "started", at: timestampToMs(event.started?.at ?? null) };
+        case "log":
+            return event.log ? { type: "log", log: decodeLogLine(event.log) } : null;
+        case "progress":
+            return {
+                type: "progress",
+                percent: event.progress?.percent ?? 0,
+                phase: event.progress?.phase ?? "",
+            };
+        case "partial":
+            return { type: "partial", snapshot: bufferToJson(event.partial?.snapshotJson) };
+        case "final":
+            return event.final ? { type: "final", response: decodeExecuteResponse(event.final) } : null;
+        default:
+            return null;
+    }
+}
+// =============================================================================
+// Decoder — proto ExecuteResponse → DecodedExecuteResponse
+// =============================================================================
+/**
+ * Decode a {@link ExecuteResponseProto} from the wire into the shape the
+ * adapter consumes. Defensive against missing fields (proto-loader fills in
+ * defaults, but we guard against malformed responses too).
+ */
+export function decodeExecuteResponse(response) {
+    return {
+        success: response.success ?? false,
+        data: bufferToJson(response.data),
+        contentType: response.contentType || "application/json",
+        varsDelta: bufferToJson(response.varsDelta) ?? {},
+        logs: (response.logs ?? []).map(decodeLogLine),
+        error: response.error ? decodeNodeError(response.error) : null,
+        metrics: decodeMetrics(response.metrics),
+    };
+}
+function decodeLogLine(line) {
+    return {
+        timestamp: timestampToMs(line.timestamp),
+        level: line.level,
+        message: line.message,
+        attributes: line.attributes ?? {},
+    };
+}
+function decodeNodeError(err) {
+    return {
+        code: err.code,
+        category: err.category,
+        severity: err.severity,
+        node: err.node,
+        sdk: err.sdk,
+        sdkVersion: err.sdkVersion,
+        runtimeKind: err.runtimeKind,
+        at: timestampToMs(err.at),
+        message: err.message,
+        description: err.description,
+        remediation: err.remediation,
+        docUrl: err.docUrl,
+        causes: (err.causes ?? []).map(decodeNodeError),
+        stack: err.stack,
+        contextSnapshot: bufferToJson(err.contextSnapshotJson),
+        httpStatus: err.httpStatus,
+        retryable: err.retryable,
+        retryAfterMs: Number(err.retryAfterMs ?? 0),
+        details: bufferToJson(err.detailsJson),
+    };
+}
+function decodeMetrics(metrics) {
+    return {
+        durationMs: metrics?.durationMs ?? 0,
+        cpuMs: metrics?.cpuMs ?? 0,
+        memoryBytes: Number(metrics?.memoryBytes ?? 0),
+        requestBytes: Number(metrics?.requestBytes ?? 0),
+        responseBytes: Number(metrics?.responseBytes ?? 0),
+    };
+}
+// =============================================================================
+// Internal serialization helpers
+// =============================================================================
+/**
+ * Pull resolved node inputs from `ctx.config[nodeName].inputs` (the shape
+ * established by the Blueprint Mapper) and return them as a plain object.
+ *
+ * Falls back to `ctx.response.data` when no resolved inputs exist (matches
+ * the legacy zero-config-chaining behavior of `HttpRuntimeAdapter`).
+ */
+function extractResolvedInputs(ctx, nodeName) {
+    const nodeConfig = ctx.config
+        ? ctx.config[nodeName]
+        : undefined;
+    const resolved = nodeConfig?.inputs;
+    if (resolved !== undefined)
+        return resolved;
+    return ctx.response?.data ?? {};
+}
+/** Encode a value as UTF-8 JSON bytes. `null`/`undefined` → empty buffer. */
+export function jsonToBuffer(value) {
+    if (value === null || value === undefined)
+        return Buffer.alloc(0);
+    return Buffer.from(JSON.stringify(value), "utf-8");
+}
+/** Decode a buffer as UTF-8 JSON. Empty/missing buffer → `null`. */
+export function bufferToJson(buf) {
+    if (!buf || buf.length === 0)
+        return null;
+    try {
+        return JSON.parse(buf.toString("utf-8"));
+    }
+    catch {
+        // Malformed JSON — return raw string so callers can salvage what they can.
+        return buf.toString("utf-8");
+    }
+}
+/**
+ * Encode a request body. Strings stay UTF-8; objects become JSON; Buffers
+ * pass through. Anything else stringifies via JSON.
+ */
+function bodyToBuffer(body) {
+    if (body === null || body === undefined)
+        return Buffer.alloc(0);
+    if (Buffer.isBuffer(body))
+        return body;
+    if (typeof body === "string")
+        return Buffer.from(body, "utf-8");
+    return Buffer.from(JSON.stringify(body), "utf-8");
+}
+/** Coerce an unknown record-like value into `Record<string, string>`. */
+function stringMap(value) {
+    if (!value || typeof value !== "object")
+        return {};
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+        if (typeof val === "string")
+            out[key] = val;
+        else if (val !== null && val !== undefined)
+            out[key] = String(val);
+    }
+    return out;
+}
+/** Coerce an unknown value into a string field; default empty. */
+function stringField(value) {
+    return typeof value === "string" ? value : "";
+}
+/** Filter env to string-valued entries (process.env can carry undefined). */
+function stringEnv(env) {
+    if (!env)
+        return {};
+    const out = {};
+    for (const [key, val] of Object.entries(env)) {
+        if (typeof val === "string")
+            out[key] = val;
+    }
+    return out;
+}
+/** Convert a proto Timestamp to ms-since-epoch. */
+function timestampToMs(ts) {
+    if (!ts)
+        return 0;
+    const seconds = Number(ts.seconds ?? 0);
+    const nanos = ts.nanos ?? 0;
+    return seconds * 1000 + Math.floor(nanos / 1_000_000);
+}
+//# sourceMappingURL=GrpcCodec.js.map

package/dist/adapters/grpc/GrpcCodec.js.map

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

package/dist/adapters/grpc/GrpcErrors.d.ts

@@ -0,0 +1,59 @@
+import { BlokError, ErrorCategory } from "@blokjs/shared";
+import { status as GrpcStatus, type ServiceError } from "@grpc/grpc-js";
+/**
+ * Mapping table from `@grpc/grpc-js` `status` codes to canonical
+ * `(ErrorCategory, defaultHttpStatus)` pairs.
+ *
+ * Single source of truth for gRPC-side error classification. Adapters never
+ * branch on status codes inline; they call {@link toBlokError} which uses
+ * this table.
+ *
+ * The table is exhaustive — every gRPC status defined in
+ * `@grpc/grpc-js#status` has an entry. CI verifies coverage in the unit test.
+ */
+export declare const GRPC_STATUS_MAP: Readonly<Record<GrpcStatus, {
+    category: ErrorCategory;
+    httpStatus: number;
+    codePrefix: string;
+}>>;
+/**
+ * Context passed alongside a gRPC error so the resulting {@link BlokError}
+ * carries origin information (which SDK, which kind, which step) without
+ * the adapter having to know the proto layout.
+ */
+export interface GrpcErrorContext {
+    readonly node: string;
+    readonly sdk: string;
+    readonly sdkVersion: string;
+    readonly runtimeKind: string;
+}
+/**
+ * Convert a gRPC `ServiceError` (or any thrown value from a gRPC call) into a
+ * canonical {@link BlokError}. Lossless when the SDK populates structured
+ * details: gRPC `status.details` carrying a serialized {@link NodeErrorPayload}
+ * is decoded and merged into the resulting error.
+ *
+ * Behavior:
+ * - `ServiceError` with a known `code`: looked up in {@link GRPC_STATUS_MAP}.
+ *   If `metadata` carries `blok-error-bin` (a serialized NodeErrorPayload),
+ *   the payload is reconstructed via {@link BlokError.fromJSON} and the
+ *   gRPC status only refines the http_status / category fallback.
+ * - Plain `Error`: wrapped via {@link BlokError.fromUnknown}.
+ * - Anything else: stringified and wrapped as `INTERNAL`.
+ */
+export declare function toBlokError(err: unknown, ctx: GrpcErrorContext): BlokError;
+/**
+ * Type guard for {@link ServiceError}. Duck-typed because `instanceof` checks
+ * across `@grpc/grpc-js` module boundaries are unreliable when the dep is
+ * deduped at multiple versions.
+ */
+export declare function isServiceError(err: unknown): err is ServiceError;
+/**
+ * Translate a `BlokError` produced by the runner side back into a gRPC status
+ * code, for cases where the runner needs to report failure to a downstream
+ * caller using gRPC. Inverse of {@link GRPC_STATUS_MAP}.
+ *
+ * Currently used only by tests; will be used by Phase 5 streaming when the
+ * runner re-emits node errors as `ExecuteStream` `final` frames.
+ */
+export declare function categoryToGrpcStatus(category: ErrorCategory): GrpcStatus;