@ezghcloud/workflows 0.0.0 → 1.0.0

package/dist/runtime/live.d.ts

@@ -0,0 +1,23 @@
+import type { Checkpoint, Journal } from "../protocol/index.ts";
+export interface LiveIO {
+    checkpoint(cp: Checkpoint): Promise<void>;
+    journalPage(afterSeq: number): Promise<Journal>;
+    payload(id: string): Promise<unknown>;
+}
+export declare class InvocationSuperseded extends Error {
+    name: string;
+}
+export declare class CheckpointFailed extends Error {
+    readonly code: "checkpoint_failed" | "payload_unavailable";
+    name: string;
+    constructor(message: string, code?: "checkpoint_failed" | "payload_unavailable");
+}
+export interface LiveOptions {
+    deadline?: number;
+    reserveMs?: number;
+    now?: () => number;
+    attempts?: number;
+    retryDelayMs?: number;
+}
+export declare function httpLive(base: string, token: string, fetchImpl?: FetchLike, opts?: LiveOptions): LiveIO;
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;

package/dist/runtime/live.js

@@ -0,0 +1,103 @@
+// The engine has moved on: another invocation owns the run. Stop at once.
+export class InvocationSuperseded extends Error {
+    name = "InvocationSuperseded";
+}
+// workflows-live refused or couldn't take a call after retries: the step must not run. code is
+// what serve() tells dispatch: "payload_unavailable" when the live host's last answer was a 503
+// payload_unavailable (its payload store is down: dispatch charges no step attempt), else
+// "checkpoint_failed".
+export class CheckpointFailed extends Error {
+    code;
+    name = "CheckpointFailed";
+    constructor(message, code = "checkpoint_failed") {
+        super(message);
+        this.code = code;
+    }
+}
+// errorCode reads the kit's {"error":{"code"}} from a small error body, or undefined.
+async function errorCode(res) {
+    try {
+        const text = await res.text();
+        if (text.length > 64 * 1024)
+            return undefined;
+        const code = JSON.parse(text).error?.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const MAX_BACKOFF_MS = 5000;
+function retryAfterMs(res) {
+    const v = res.headers.get("Retry-After");
+    if (!v)
+        return undefined;
+    const n = Number(v);
+    if (Number.isFinite(n) && n >= 0)
+        return n * 1000;
+    const at = Date.parse(v);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now());
+}
+// httpLive talks to workflows-live (plan D2, D25) with Authorization: Bearer <invocation token>.
+// 409 means superseded; 429, 5xx and network errors are retried; anything else non-2xx fails
+// the invocation (CheckpointFailed).
+export function httpLive(base, token, fetchImpl = (u, i) => fetch(u, i), opts = {}) {
+    const root = base.replace(/\/+$/, "");
+    const now = opts.now ?? Date.now;
+    const reserve = opts.reserveMs ?? 0;
+    const firstDelay = opts.retryDelayMs ?? 200;
+    async function call(path, init) {
+        const headers = { Authorization: `Bearer ${token}` };
+        if (init.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const what = path.split("?")[0];
+        let last = "";
+        let payloadDown = false; // the last answer was 503 payload_unavailable
+        const failed = (message) => new CheckpointFailed(message, payloadDown ? "payload_unavailable" : "checkpoint_failed");
+        for (let attempt = 0;; attempt++) {
+            const timeout = opts.deadline === undefined ? 30_000 : opts.deadline - now();
+            if (timeout <= 0)
+                throw failed(`No time left for ${what}: ${last || "the deadline passed"}`);
+            let res;
+            let wait;
+            try {
+                res = await fetchImpl(root + path, { ...init, headers, signal: AbortSignal.timeout(Math.max(1, Math.floor(timeout))), redirect: "manual" });
+            }
+            catch (e) {
+                last = e instanceof Error ? e.name : "network error";
+                payloadDown = false;
+            }
+            if (res) {
+                if (res.ok)
+                    return res;
+                const code = res.status === 503 ? await errorCode(res) : (await res.body?.cancel().catch(() => { }), undefined);
+                if (res.status === 409)
+                    throw new InvocationSuperseded("The engine superseded this invocation");
+                if (res.status !== 429 && res.status < 500)
+                    throw new CheckpointFailed(`workflows-live answered ${res.status} for ${what}`);
+                last = code ? `HTTP ${res.status} ${code}` : `HTTP ${res.status}`;
+                payloadDown = code === "payload_unavailable";
+                wait = retryAfterMs(res);
+            }
+            // Retry-After never shortens the backoff (a 0 or a past date mustn't spin).
+            const delay = Math.max(wait ?? 0, Math.min(MAX_BACKOFF_MS, firstDelay * 2 ** attempt));
+            const more = opts.deadline === undefined ? attempt + 1 < (opts.attempts ?? 4) : opts.deadline - now() - delay > reserve;
+            if (!more)
+                throw failed(`workflows-live didn't take ${what}: ${last}`);
+            await sleep(delay);
+        }
+    }
+    return {
+        async checkpoint(cp) {
+            const res = await call("/v1/invocations/checkpoint", { method: "POST", body: JSON.stringify(cp) });
+            await res.body?.cancel().catch(() => { });
+        },
+        async journalPage(afterSeq) {
+            return (await (await call(`/v1/invocations/journal?afterSeq=${afterSeq}`, { method: "GET" })).json());
+        },
+        async payload(id) {
+            return (await call(`/v1/invocations/payloads/${encodeURIComponent(id)}`, { method: "GET" })).json();
+        },
+    };
+}

package/dist/runtime/workflow.d.ts

@@ -0,0 +1,26 @@
+import type { RetryPolicy } from "../protocol/index.ts";
+import type { WorkflowContext } from "./context.ts";
+export interface WorkflowOptions {
+    retry?: Partial<RetryPolicy>;
+    timeoutMs?: number;
+}
+declare const io: unique symbol;
+export interface Workflow<I = unknown, O = unknown> {
+    readonly name: string;
+    readonly [io]?: (input: I) => O;
+}
+export interface WorkflowDefinition {
+    readonly name: string;
+    readonly fn: (ctx: WorkflowContext<any>) => Promise<unknown>;
+    readonly opts: {
+        readonly retry?: RetryPolicy;
+        readonly timeoutMs?: number;
+    };
+}
+export declare function definitionOf(wf: Workflow<any, any>): WorkflowDefinition;
+export declare function workflow<I = unknown, O = unknown>(name: string, fn: (ctx: WorkflowContext<I>) => Promise<O>, opts?: WorkflowOptions): Workflow<I, O>;
+export declare function mergeRetry(base: RetryPolicy, over: Partial<RetryPolicy> | undefined): RetryPolicy;
+export declare function checkRetry(p: Partial<RetryPolicy>): void;
+export declare const MAX_TIMEOUT_MS = 86400000;
+export declare function checkTimeout(ms: number): void;
+export {};

package/dist/runtime/workflow.js

@@ -0,0 +1,49 @@
+import { DEFAULT_RETRY, validWorkflowName } from "../protocol/index.js";
+const definitions = new WeakMap();
+// definitionOf returns what workflow() recorded, or throws for anything else.
+export function definitionOf(wf) {
+    const d = typeof wf === "object" && wf !== null ? definitions.get(wf) : undefined;
+    if (!d)
+        throw new TypeError("Not a workflow: create workflows with workflow()");
+    return d;
+}
+export function workflow(name, fn, opts = {}) {
+    if (!validWorkflowName(name))
+        throw new TypeError(`Workflow names match ^[A-Za-z0-9_-]{1,64}$; got "${name}"`);
+    if (typeof fn !== "function")
+        throw new TypeError("A workflow needs a function");
+    if (opts.timeoutMs !== undefined)
+        checkTimeout(opts.timeoutMs);
+    const retry = opts.retry === undefined ? undefined : mergeRetry(DEFAULT_RETRY, opts.retry);
+    const wf = Object.freeze({ name });
+    definitions.set(wf, Object.freeze({
+        name, fn: fn,
+        opts: Object.freeze({ ...(retry ? { retry: Object.freeze(retry) } : {}), ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) }),
+    }));
+    return wf;
+}
+// mergeRetry overlays the defined fields of over on base and checks the result.
+export function mergeRetry(base, over) {
+    const merged = { ...base };
+    for (const [k, v] of Object.entries(over ?? {}))
+        if (v !== undefined && k in merged)
+            merged[k] = v;
+    checkRetry(merged);
+    return merged;
+}
+// checkRetry enforces the protocol's bounds (protocol/schemas; the engine refuses others):
+// maxAttempts 1–100, initialMs ≥ 0, maxMs 0–86,400,000, multiplier 1–10.
+export function checkRetry(p) {
+    const ok = (v, min, max, int) => v === undefined || (typeof v === "number" && Number.isFinite(v) && v >= min && v <= max && (!int || Number.isInteger(v)));
+    if (!ok(p.maxAttempts, 1, 100, true) || !ok(p.initialMs, 0, Number.MAX_SAFE_INTEGER, true) || !ok(p.maxMs, 0, 86_400_000, true) || !ok(p.multiplier, 1, 10, false))
+        throw new TypeError("A retry policy has integer maxAttempts 1–100, integer initialMs ≥ 0, integer maxMs 0–86,400,000 and multiplier 1–10");
+}
+// The longest step timeout: 24 hours, a pull invocation's longest deadline (a pull app's deadline
+// is its longest announced workflow timeout, at least 15 minutes). Pushed invocations are shorter
+// (serve()'s maxInvocationSeconds, at most 900 s), and serve() refuses a workflow default longer
+// than that; a step can never outlive its invocation.
+export const MAX_TIMEOUT_MS = 86_400_000;
+export function checkTimeout(ms) {
+    if (typeof ms !== "number" || !Number.isInteger(ms) || ms <= 0 || ms > MAX_TIMEOUT_MS)
+        throw new TypeError("timeoutMs is a whole number of milliseconds from 1 to 86,400,000 (24 hours)");
+}

package/dist/serve.d.ts

@@ -0,0 +1,12 @@
+import { type FetchLike } from "./runtime/live.ts";
+import { type Workflow } from "./runtime/workflow.ts";
+export interface ServeOptions {
+    workflows: Workflow<any, any>[];
+    signingSecrets: (string | undefined)[];
+    maxInvocationSeconds?: number;
+    deployment?: string;
+    fetch?: FetchLike;
+    maxStepsPerInvocation?: number;
+    apiBaseUrl?: string;
+}
+export declare function serve(opts: ServeOptions): (req: Request) => Promise<Response>;

package/dist/serve.js

@@ -0,0 +1,149 @@
+import { PROTOCOL_VERSIONS, SIGNATURE_HEADER, SignatureError, decodeSecret, parseSignature, verifyParsed } from "./protocol/index.js";
+import { cleanDeployment, detectDeployment } from "./env.js";
+import { execute } from "./runtime/execution.js";
+import { InvalidInvocation, parseInvocation } from "./runtime/invocation.js";
+import { CheckpointFailed, InvocationSuperseded, httpLive } from "./runtime/live.js";
+import { definitionOf } from "./runtime/workflow.js";
+import { SDK_NAME, SDK_VERSION } from "./version.js";
+const MAX_BODY = 8 * 1024 * 1024;
+// The result dispatch reads back (workflows-dispatch's cap).
+const MAX_RESULT = 16 * 1024 * 1024;
+const json = (status, body) => new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
+class TooLarge extends Error {
+}
+async function readBody(req) {
+    const declared = Number(req.headers.get("Content-Length") ?? "0");
+    if (declared > MAX_BODY)
+        throw new TooLarge();
+    if (!req.body)
+        return new Uint8Array(0);
+    const reader = req.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.length;
+        if (size > MAX_BODY) {
+            await reader.cancel().catch(() => { });
+            throw new TooLarge();
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(size);
+    let at = 0;
+    for (const c of chunks) {
+        out.set(c, at);
+        at += c.length;
+    }
+    return out;
+}
+// serve returns a Fetch-API handler for push invocations. Bun, Deno, Cloudflare Workers and
+// Next.js route handlers take it as is; Node needs a small adapter (examples/node). Answers
+// (plan D25): 200 SyncReply or InvocationResult, 401 bad signature, 400 bad invocation, 409
+// superseded, 503 checkpoint failed, 500 SDK error, 405 non-POST, 413 over 8 MiB.
+export function serve(opts) {
+    const byName = new Map();
+    for (const wf of opts.workflows) {
+        const def = definitionOf(wf);
+        if (byName.has(def.name))
+            throw new TypeError(`Two workflows are named "${def.name}"`);
+        byName.set(def.name, { wf, def });
+    }
+    if (!Array.isArray(opts.signingSecrets) || opts.signingSecrets.length === 0)
+        throw new TypeError("serve() needs at least one signing secret");
+    // A malformed secret fails now; an unset or empty one (an env var at build time) is skipped.
+    for (const s of opts.signingSecrets)
+        if (s !== undefined && s !== "")
+            decodeSecret(s);
+    let secrets;
+    const keys = () => (secrets ??= opts.signingSecrets.filter((s) => typeof s === "string" && s !== "").map(decodeSecret));
+    if (opts.maxStepsPerInvocation !== undefined && (!Number.isInteger(opts.maxStepsPerInvocation) || opts.maxStepsPerInvocation < 1))
+        throw new TypeError("maxStepsPerInvocation is a whole number ≥ 1");
+    const maxSeconds = opts.maxInvocationSeconds ?? 300;
+    if (!Number.isInteger(maxSeconds) || maxSeconds < 1 || maxSeconds > 900)
+        throw new TypeError("maxInvocationSeconds is a whole number from 1 to 900");
+    for (const { def } of byName.values())
+        if (def.opts.timeoutMs !== undefined && def.opts.timeoutMs > maxSeconds * 1000)
+            throw new TypeError(`Workflow "${def.name}" has timeoutMs ${def.opts.timeoutMs}, longer than an invocation (maxInvocationSeconds ${maxSeconds}): a step can't outlive its invocation; long steps need a pull worker`);
+    const deployment = opts.deployment !== undefined ? cleanDeployment(opts.deployment) : detectDeployment();
+    const sdk = { name: SDK_NAME, version: SDK_VERSION };
+    const fetchImpl = opts.fetch ?? ((u, i) => fetch(u, i));
+    return async (req) => {
+        const receivedAt = Date.now();
+        if (req.method !== "POST")
+            return json(405, { code: "method_not_allowed" });
+        const active = keys();
+        if (active.length === 0)
+            return json(500, { code: "sdk_error", message: "No signing secret is configured" });
+        // The header and its timestamp first: a stale or malformed signature costs no body read.
+        let sig;
+        try {
+            sig = parseSignature(req.headers.get(SIGNATURE_HEADER) ?? "", new Date(receivedAt));
+        }
+        catch (e) {
+            if (e instanceof SignatureError)
+                return json(401, { code: e.reason === "expired" ? "expired_signature" : "invalid_signature" });
+            return json(500, { code: "sdk_error" });
+        }
+        let body;
+        try {
+            body = await readBody(req);
+        }
+        catch (e) {
+            if (e instanceof TooLarge)
+                return json(413, { code: "payload_too_large" });
+            return json(400, { code: "invalid_invocation" });
+        }
+        try {
+            await verifyParsed(sig, active, body);
+        }
+        catch (e) {
+            if (e instanceof SignatureError)
+                return json(401, { code: "invalid_signature" });
+            return json(500, { code: "sdk_error" });
+        }
+        let inv;
+        try {
+            inv = parseInvocation(new TextDecoder().decode(body));
+        }
+        catch (e) {
+            if (e instanceof InvalidInvocation)
+                return json(400, { code: "invalid_invocation", message: e.message });
+            return json(500, { code: "sdk_error" });
+        }
+        // A push request carries the traceparent as a header (only while the setting is on).
+        inv = { ...inv, traceparent: req.headers.get("traceparent") ?? "" };
+        if (inv.kind === "sync") {
+            const reply = {
+                protocolVersions: [...PROTOCOL_VERSIONS], sdk, maxInvocationSeconds: maxSeconds,
+                workflows: [...byName.values()].map(({ def }) => ({ name: def.name, ...(def.opts.retry ? { retry: def.opts.retry } : {}), ...(def.opts.timeoutMs ? { timeoutMs: def.opts.timeoutMs } : {}) })),
+                ...(deployment ? { deployment } : {}),
+            };
+            return json(200, reply);
+        }
+        const result = (commands) => ({ commands, ...(deployment ? { deployment } : {}), sdk });
+        const wf = byName.get(inv.run.workflow)?.wf;
+        if (!wf)
+            return json(200, result([{ type: "workflowNotFound", workflow: inv.run.workflow }]));
+        // The deadline on this machine's clock: the engine's budget (deadline − t) from receipt, and
+        // never later than the deadline as this clock reads it.
+        const deadline = Math.min(receivedAt + (Date.parse(inv.deadline) - sig.t * 1000), Date.parse(inv.deadline));
+        const total = Math.max(0, deadline - receivedAt);
+        const reserveMs = Math.max(5000, total * 0.1);
+        try {
+            const io = httpLive(inv.endpoints.live, inv.token, fetchImpl, { deadline, reserveMs });
+            return json(200, result(await execute(inv, wf, io, { deadline, maxResultBytes: MAX_RESULT, ...(opts.apiBaseUrl ? { apiBaseUrl: opts.apiBaseUrl } : {}), ...(opts.maxStepsPerInvocation ? { maxStepsPerInvocation: opts.maxStepsPerInvocation } : {}) })));
+        }
+        catch (e) {
+            if (e instanceof InvocationSuperseded)
+                return json(409, { code: "invocation_superseded" });
+            // The code goes top level (as before) and in the kit's error shape, which dispatch reads:
+            // payload_unavailable costs the run no step attempt.
+            if (e instanceof CheckpointFailed)
+                return json(503, { code: e.code, error: { code: e.code, message: e.message } });
+            return json(500, { code: "sdk_error" });
+        }
+    };
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const SDK_NAME = "@ezghcloud/workflows";
+export declare const SDK_VERSION = "1.0.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+export const SDK_NAME = "@ezghcloud/workflows";
+export const SDK_VERSION = "1.0.0";

package/dist/worker.d.ts

@@ -0,0 +1,43 @@
+import { type FetchLike } from "./runtime/live.ts";
+import { type Workflow } from "./runtime/workflow.ts";
+export interface WorkerOptions {
+    apiKey: string;
+    organizationId: string;
+    projectId: string;
+    app: string;
+    queue?: string;
+    workflows: Workflow<any, any>[];
+    maxTasks?: number;
+    concurrency?: number;
+    liveUrl?: string;
+    apiBaseUrl?: string;
+    workerId?: string;
+    dev?: boolean | {
+        user?: string;
+    };
+    heartbeatIntervalMs?: number;
+    backoffMaxMs?: number;
+    maxStepsPerInvocation?: number;
+    deployment?: string;
+    fetch?: FetchLike;
+    onError?: (error: unknown, context: string) => void;
+}
+export interface Worker {
+    run(): Promise<void>;
+    stop(opts?: {
+        graceMs?: number;
+    }): Promise<void>;
+}
+export declare class WorkerAuthError extends Error {
+    readonly status: number;
+    name: string;
+    constructor(status: number, message: string);
+}
+export declare class WorkerConfigError extends Error {
+    readonly status: number;
+    readonly code: string;
+    name: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare function devQueue(user?: string): string;
+export declare function worker(opts: WorkerOptions): Worker;