@ezghcloud/workflows 0.0.0-stage → 1.0.0

package/dist/runtime/errors.js

@@ -0,0 +1,160 @@
+import { truncateUtf8, utf8Length } from "../protocol/bytes.js";
+// A step error that retrying won't fix: the step fails at once (code workflows.non_retriable).
+export class NonRetriableError extends Error {
+    name = "NonRetriableError";
+    code = "workflows.non_retriable";
+}
+// A retryable step error with the delay before the next attempt.
+export class RetryAfterError extends Error {
+    delayMs;
+    name = "RetryAfterError";
+    constructor(message, delayMs) {
+        super(message);
+        this.delayMs = delayMs;
+    }
+}
+// Thrown into a workflow's pending call when its run is cancelled (code workflows.cancelled).
+export class CancelledError extends Error {
+    name = "CancelledError";
+    code = "workflows.cancelled";
+}
+// WorkflowError is an error with a code and JSON data, and what a recorded failure is rebuilt as
+// on replay. Codes on the wire are "user" or the platform's own "workflows.*" codes: any other
+// code is sent as "user", with
+// the custom code as the name (when no name was given) and as data.code (when data is absent or a
+// plain object without a code), so a replay sees code "user" and finds the custom code there.
+export class WorkflowError extends Error {
+    code;
+    data;
+    constructor(message, opts = {}) {
+        super(message, opts.cause === undefined ? undefined : { cause: opts.cause });
+        this.code = opts.code ?? "user";
+        this.name = opts.name ?? "WorkflowError";
+        if (opts.data !== undefined)
+            this.data = opts.data;
+    }
+}
+// A callback that wasn't completed before its timeout: what Callback.wait() rejects with
+// (code workflows.callback_timeout). Catchable; it isn't retried.
+export class CallbackTimeout extends WorkflowError {
+    constructor(message, opts = {}) {
+        super(message, { ...opts, code: "workflows.callback_timeout", name: opts.name ?? "CallbackTimeout" });
+    }
+}
+// A child run that failed: what step.invoke rejects with (code workflows.child_failed); cause is
+// the child's own error.
+export class ChildFailed extends WorkflowError {
+    constructor(message, opts = {}) {
+        super(message, { ...opts, code: "workflows.child_failed", name: opts.name ?? "ChildFailed" });
+    }
+}
+// Errors the runtime raises itself.
+export class StepTimeout extends Error {
+    name = "StepTimeout";
+}
+export class DuplicateStepName extends Error {
+    name = "DuplicateStepName";
+}
+export class OutputTooLarge extends Error {
+    name = "OutputTooLarge";
+}
+const MAX_STACK_BYTES = 8192;
+const MAX_MESSAGE_BYTES = 8192;
+const MAX_DATA_BYTES = 65_536;
+// At most 8 levels in all, the error and 7 causes (internal/protocol MaxErrorDepth).
+const MAX_DEPTH = 8;
+// The platform's own codes (internal/protocol); a customer error with any other code is sent as user.
+const PLATFORM_CODES = new Set([
+    "workflows.callback_timeout", "workflows.cancelled", "workflows.child_failed", "workflows.step_timeout",
+    "workflows.invocation_lost", "workflows.non_retriable", "workflows.output_too_large", "workflows.duplicate_step_name",
+    "workflows.workflow_not_found", "workflows.invocation_failed", "workflows.timed_out",
+]);
+const wireCode = (code) => code === "user" || PLATFORM_CODES.has(code);
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+function codeOf(e) {
+    if (e instanceof NonRetriableError)
+        return "workflows.non_retriable";
+    if (e instanceof CancelledError)
+        return "workflows.cancelled";
+    if (e instanceof StepTimeout)
+        return "workflows.step_timeout";
+    if (e instanceof DuplicateStepName)
+        return "workflows.duplicate_step_name";
+    if (e instanceof OutputTooLarge)
+        return "workflows.output_too_large";
+    if (e instanceof WorkflowError)
+        return e.code;
+    return "user";
+}
+function jsonData(v) {
+    try {
+        return v === undefined ? undefined : JSON.parse(JSON.stringify(v));
+    }
+    catch {
+        return undefined;
+    }
+}
+// encodeError: the wire shape of anything a workflow throws (design, "Errors"). Codes are "user"
+// or "workflows.*" (see WorkflowError); messages and stacks are cut to 8 KiB of UTF-8 and data
+// over 64 KiB of JSON is dropped; the error and its causes are at most 8 levels in all.
+export function encodeError(e, depth = 0) {
+    if (!(e instanceof Error))
+        return { code: "user", name: "Error", message: truncateUtf8(typeof e === "string" ? e : safeString(e), MAX_MESSAGE_BYTES) };
+    let code = codeOf(e);
+    let name = e.name || "Error";
+    let data = jsonData(e.data);
+    if (!wireCode(code)) {
+        if (e instanceof WorkflowError && name === "WorkflowError")
+            name = code;
+        if (data === undefined)
+            data = { code };
+        else if (isPlainObject(data) && !("code" in data))
+            data = { ...data, code };
+        code = "user";
+    }
+    const w = { code, name: truncateUtf8(String(name), 256), message: truncateUtf8(String(e.message), MAX_MESSAGE_BYTES) };
+    if (data !== undefined && utf8Length(JSON.stringify(data)) <= MAX_DATA_BYTES)
+        w.data = data;
+    if (typeof e.stack === "string" && e.stack)
+        w.stack = truncateUtf8(e.stack, MAX_STACK_BYTES);
+    if (e.cause !== undefined && depth + 1 < MAX_DEPTH)
+        w.cause = encodeError(e.cause, depth + 1);
+    return w;
+}
+function safeString(v) {
+    try {
+        return String(v);
+    }
+    catch {
+        return "A non-Error value was thrown";
+    }
+}
+// decodeError rebuilds the SDK's own classes from code, so instanceof works after replay.
+// encodeError(decodeError(w)) gives back w.
+export function decodeError(w) {
+    const cause = w.cause ? decodeError(w.cause) : undefined;
+    let e;
+    switch (w.code) {
+        case "workflows.non_retriable":
+            e = new NonRetriableError(w.message, cause ? { cause } : undefined);
+            break;
+        case "workflows.cancelled":
+            e = new CancelledError(w.message, cause ? { cause } : undefined);
+            break;
+        case "workflows.callback_timeout":
+            e = new CallbackTimeout(w.message, { name: w.name, data: w.data, cause });
+            break;
+        case "workflows.child_failed":
+            e = new ChildFailed(w.message, { name: w.name, data: w.data, cause });
+            break;
+        default: e = new WorkflowError(w.message, { code: w.code, name: w.name, data: w.data, cause });
+    }
+    e.name = w.name;
+    if (w.data !== undefined)
+        e.data = w.data;
+    if (w.stack !== undefined)
+        e.stack = w.stack;
+    else
+        delete e.stack;
+    return e;
+}

package/dist/runtime/execution.d.ts

@@ -0,0 +1,17 @@
+import type { Command, Invocation } from "../protocol/index.ts";
+import type { LiveIO } from "./live.ts";
+import { type Workflow } from "./workflow.ts";
+export interface ExecOptions {
+    now?: () => Date;
+    maxStepsPerInvocation?: number;
+    deadline?: number;
+    apiBaseUrl?: string;
+    cancelSignal?: AbortSignal;
+    maxResultBytes?: number;
+}
+export declare const MAX_SLEEP_MS = 31536000000;
+export declare const MAX_RETRY_AFTER_MS = 86400000;
+export declare const DEFAULT_CALLBACK_TIMEOUT_MS = 604800000;
+export declare const MIN_CALLBACK_TIMEOUT_MS = 1000;
+export declare const DEFAULT_API_BASE = "https://workflows-api.ezghcloud.com";
+export declare function execute(inv: Invocation, wf: Workflow<any, any>, io: LiveIO, opts?: ExecOptions): Promise<Command[]>;