@ezghcloud/workflows 0.0.0 → 1.0.0

package/dist/protocol/codec.js

@@ -0,0 +1,38 @@
+import { utf8 } from "./bytes.js";
+export const MAX_OUTPUT_BYTES = 1_048_576;
+// encodeValue passes a value through JSON exactly as the wire will, so a step's live result and
+// its replayed result are the same value (design, "Return values are JSON").
+export function encodeValue(v) {
+    if (v === undefined)
+        return null;
+    const text = JSON.stringify(v, (_key, value) => {
+        if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint")
+            throw new TypeError(`A ${typeof value} can't be a step result or workflow output; return JSON values`);
+        return value;
+    });
+    return text === undefined ? null : JSON.parse(text);
+}
+export function jsonByteLength(v) {
+    return utf8(JSON.stringify(v ?? null)).length;
+}
+const units = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+// parseDuration: milliseconds, or a string such as 500ms, 30s, 5m, 2h or 3d.
+export function parseDuration(d) {
+    if (typeof d === "number") {
+        if (!Number.isFinite(d) || d < 0)
+            throw new TypeError("A duration is a non-negative number of milliseconds");
+        return Math.floor(d);
+    }
+    const m = typeof d === "string" ? /^(\d+)(ms|s|m|h|d)$/.exec(d.trim()) : null;
+    if (!m)
+        throw new TypeError(`"${String(d)}" isn't a duration: use 500ms, 30s, 5m, 2h or 3d`);
+    return Number(m[1]) * units[m[2]];
+}
+// backoff is the delay before attempt+1: min(maxMs, floor(initialMs * multiplier^(attempt-1))).
+// Attempts count from 1 (internal/protocol RetryPolicy.Backoff).
+export function backoff(p, attempt) {
+    const ms = Math.floor(p.initialMs * p.multiplier ** (Math.max(1, attempt) - 1));
+    if (!Number.isFinite(ms) || ms > p.maxMs)
+        return p.maxMs;
+    return Math.max(0, ms);
+}

package/dist/protocol/derived.d.ts

@@ -0,0 +1,5 @@
+export declare function derivedRunId(domain: string, a: string, b: string): Promise<string>;
+export declare function rfc3339Nano(t: string | Date): string;
+export declare const childRunId: (parentRunId: string, stepId: string) => Promise<string>;
+export declare const scheduledRunId: (scheduleId: string, scheduledTime: string | Date) => Promise<string>;
+export declare const triggeredRunId: (scheduleId: string, idempotencyKey: string) => Promise<string>;

package/dist/protocol/derived.js

@@ -0,0 +1,41 @@
+import { toHex, utf8 } from "./bytes.js";
+// Derived run IDs (plan D2-8, protocol/vectors/derived-ids.json): a UUIDv8 from the first 16
+// bytes of SHA-256(domain + "\0" + a + "\0" + b), with version 8, the RFC 4122 variant, and
+// rand_a carrying the shard: big-endian uint16 of sum[16:18] mod 1024 (byte 6's low two bits and
+// byte 7), as shardOf reads it.
+export async function derivedRunId(domain, a, b) {
+    const sum = new Uint8Array(await crypto.subtle.digest("SHA-256", utf8(`${domain}\u0000${a}\u0000${b}`)));
+    const shard = ((sum[16] << 8) | sum[17]) % 1024;
+    const h = sum.slice(0, 16);
+    h[6] = 0x80 | ((shard >> 8) & 0x03);
+    h[7] = shard & 0xff;
+    h[8] = 0x80 | (h[8] & 0x3f);
+    const x = toHex(h);
+    return `${x.slice(0, 8)}-${x.slice(8, 12)}-${x.slice(12, 16)}-${x.slice(16, 20)}-${x.slice(20)}`;
+}
+// rfc3339Nano formats a time like Go's time.RFC3339Nano in UTC: fractional seconds without
+// trailing zeros, and none at all for a whole second. A string keeps its sub-millisecond digits.
+export function rfc3339Nano(t) {
+    let ms;
+    let frac = "";
+    if (typeof t === "string") {
+        const m = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/i.exec(t);
+        if (!m)
+            throw new TypeError(`Not an RFC 3339 time: "${t}"`);
+        ms = Date.parse(`${m[1]}${m[3]}`);
+        frac = m[2] ?? "";
+    }
+    else {
+        ms = t.getTime();
+        frac = String(((ms % 1000) + 1000) % 1000).padStart(3, "0");
+        ms -= ((ms % 1000) + 1000) % 1000;
+    }
+    if (Number.isNaN(ms))
+        throw new TypeError("Not a time");
+    const whole = new Date(ms).toISOString().slice(0, 19);
+    frac = frac.replace(/0+$/, "");
+    return `${whole}${frac ? `.${frac}` : ""}Z`;
+}
+export const childRunId = (parentRunId, stepId) => derivedRunId("workflows.child", parentRunId, stepId);
+export const scheduledRunId = (scheduleId, scheduledTime) => derivedRunId("workflows.schedule", scheduleId, rfc3339Nano(scheduledTime));
+export const triggeredRunId = (scheduleId, idempotencyKey) => derivedRunId("workflows.trigger", scheduleId, idempotencyKey);

package/dist/protocol/index.d.ts

@@ -0,0 +1,14 @@
+import type { RetryPolicy } from "./types.ts";
+export type * from "./types.ts";
+export { MAX_OUTPUT_BYTES, backoff, encodeValue, jsonByteLength, parseDuration } from "./codec.ts";
+export { MAX_SIGNATURE_AGE_SECONDS, MAX_SIGNATURES, SECRET_PREFIX, SIGNATURE_HEADER, SignatureError, decodeSecret, parseSignature, sign, verify, verifyParsed } from "./signature.ts";
+export type { ParsedSignature } from "./signature.ts";
+export { stepId, validRunKey, validStepIdOverride, validWorkflowName } from "./stepid.ts";
+export { isInvocationToken, shardOf } from "./tokens.ts";
+export declare const PROTOCOL_VERSION = "1.2";
+export declare const PROTOCOL_VERSIONS: readonly string[];
+export declare function supportsParallel(version: string): boolean;
+export declare function supportsMessages(version: string): boolean;
+export { callbackTokenHash, mintCallbackToken, parseCallbackToken } from "./callback.ts";
+export { childRunId, derivedRunId, rfc3339Nano, scheduledRunId, triggeredRunId } from "./derived.ts";
+export declare const DEFAULT_RETRY: Readonly<RetryPolicy>;

package/dist/protocol/index.js

@@ -0,0 +1,21 @@
+export { MAX_OUTPUT_BYTES, backoff, encodeValue, jsonByteLength, parseDuration } from "./codec.js";
+export { MAX_SIGNATURE_AGE_SECONDS, MAX_SIGNATURES, SECRET_PREFIX, SIGNATURE_HEADER, SignatureError, decodeSecret, parseSignature, sign, verify, verifyParsed } from "./signature.js";
+export { stepId, validRunKey, validStepIdOverride, validWorkflowName } from "./stepid.js";
+export { isInvocationToken, shardOf } from "./tokens.js";
+// The newest protocol version this SDK speaks, and every one it speaks (sync replies and pull polls
+// declare them; the engine picks the newest it shares).
+export const PROTOCOL_VERSION = "1.2";
+export const PROTOCOL_VERSIONS = Object.freeze(["1.0", "1.1", "1.2"]);
+// supportsParallel: protocol 1.1 and later plan parallel steps and allow callbacks and invoke.
+export function supportsParallel(version) {
+    const [major, minor] = String(version).split(".").map(Number);
+    return major === 1 && (minor ?? 0) >= 1;
+}
+// supportsMessages: protocol 1.2 and later wait for queue messages (step.waitForMessage).
+export function supportsMessages(version) {
+    const [major, minor] = String(version).split(".").map(Number);
+    return major === 1 && (minor ?? 0) >= 2;
+}
+export { callbackTokenHash, mintCallbackToken, parseCallbackToken } from "./callback.js";
+export { childRunId, derivedRunId, rfc3339Nano, scheduledRunId, triggeredRunId } from "./derived.js";
+export const DEFAULT_RETRY = Object.freeze({ maxAttempts: 5, initialMs: 1000, maxMs: 600_000, multiplier: 2 });

package/dist/protocol/public.d.ts

@@ -0,0 +1,2 @@
+export type { Cancel, Checkpoint, Command, Endpoints, HeartbeatResponse, Invocation, InvocationResult, Journal, JournalEntry, PlannedStep, PollRequest, PollResponse, RetryPolicy, RunInfo, ScheduleInfo, SDKInfo, SyncReply, WireError, WorkflowInfo, } from "./types.ts";
+export { SignatureError, decodeSecret, sign, verify } from "./signature.ts";

package/dist/protocol/public.js

@@ -0,0 +1 @@
+export { SignatureError, decodeSecret, sign, verify } from "./signature.js";

package/dist/protocol/signature.d.ts

@@ -0,0 +1,17 @@
+export declare const SIGNATURE_HEADER = "EZGH-Signature";
+export declare const SECRET_PREFIX = "whsec_";
+export declare const MAX_SIGNATURE_AGE_SECONDS = 300;
+export declare class SignatureError extends Error {
+    readonly reason: "expired" | "invalid";
+    constructor(reason: "expired" | "invalid", message: string);
+}
+export declare function decodeSecret(secret: string): Uint8Array;
+export declare function sign(secrets: Uint8Array[], t: Date, body: Uint8Array): Promise<string>;
+export declare const MAX_SIGNATURES = 8;
+export interface ParsedSignature {
+    t: number;
+    signatures: Uint8Array[];
+}
+export declare function parseSignature(header: string, now: Date): ParsedSignature;
+export declare function verifyParsed(sig: ParsedSignature, secrets: Uint8Array[], body: Uint8Array): Promise<void>;
+export declare function verify(header: string, secrets: Uint8Array[], body: Uint8Array, now: Date): Promise<void>;

package/dist/protocol/signature.js

@@ -0,0 +1,101 @@
+import { concat, fromBase64url, fromHex, toHex, utf8 } from "./bytes.js";
+export const SIGNATURE_HEADER = "EZGH-Signature";
+export const SECRET_PREFIX = "whsec_";
+export const MAX_SIGNATURE_AGE_SECONDS = 300;
+export class SignatureError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "SignatureError";
+    }
+}
+const malformedSecret = "A signing secret is whsec_ and 43 base64url characters, as the API returned it";
+// decodeSecret: "whsec_" + 43 base64url characters → the 32 HMAC key bytes (D22).
+export function decodeSecret(secret) {
+    const s = typeof secret === "string" ? secret.trim() : "";
+    if (!s.startsWith(SECRET_PREFIX) || s.length !== SECRET_PREFIX.length + 43)
+        throw new TypeError(malformedSecret);
+    let b;
+    try {
+        b = fromBase64url(s.slice(SECRET_PREFIX.length));
+    }
+    catch {
+        throw new TypeError(malformedSecret);
+    }
+    if (b.length !== 32)
+        throw new TypeError(malformedSecret);
+    return b;
+}
+const key = (secret) => crypto.subtle.importKey("raw", new Uint8Array(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+const mac = async (secret, payload) => new Uint8Array(await crypto.subtle.sign("HMAC", await key(secret), payload));
+// equal compares in constant time for equal lengths.
+function equal(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d |= a[i] ^ b[i];
+    return d === 0;
+}
+// sign: EZGH-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>." + body)>, one v1 per secret.
+export async function sign(secrets, t, body) {
+    const ts = Math.floor(t.getTime() / 1000);
+    const payload = concat(utf8(`${ts}.`), body);
+    const parts = [`t=${ts}`];
+    for (const s of secrets)
+        parts.push(`v1=${toHex(await mac(s, payload))}`);
+    return parts.join(",");
+}
+export const MAX_SIGNATURES = 8;
+// parseSignature checks the header's shape and timestamp without the body, so a request with a
+// malformed or stale signature is refused before its body is read. It throws
+// SignatureError("invalid") for a malformed header (or more than 8 v1 values) and
+// SignatureError("expired") when t is more than 300 s from now either way.
+export function parseSignature(header, now) {
+    if (typeof header !== "string" || header.length > 1024)
+        throw new SignatureError("invalid", "The EZGH-Signature header is missing or malformed");
+    let t;
+    const signatures = [];
+    for (const raw of header.split(",")) {
+        const part = raw.trim();
+        const i = part.indexOf("=");
+        if (i < 0)
+            throw new SignatureError("invalid", "The EZGH-Signature header is malformed");
+        const k = part.slice(0, i);
+        const v = part.slice(i + 1);
+        if (k === "t") {
+            if (!/^\d{1,12}$/.test(v))
+                throw new SignatureError("invalid", "The EZGH-Signature timestamp is malformed");
+            t = Number(v);
+        }
+        else if (k === "v1" && /^[0-9a-fA-F]{64}$/.test(v)) {
+            if (signatures.length === MAX_SIGNATURES)
+                throw new SignatureError("invalid", `The EZGH-Signature header has more than ${MAX_SIGNATURES} signatures`);
+            signatures.push(fromHex(v.toLowerCase()));
+        }
+    }
+    if (t === undefined || signatures.length === 0)
+        throw new SignatureError("invalid", "The EZGH-Signature header is missing or malformed");
+    if (Math.abs(now.getTime() / 1000 - t) > MAX_SIGNATURE_AGE_SECONDS)
+        throw new SignatureError("expired", "The EZGH-Signature timestamp is more than 5 minutes from now");
+    return { t, signatures };
+}
+// verifyParsed checks a parsed signature against the body: one HMAC per secret, each candidate
+// compared in constant time.
+export async function verifyParsed(sig, secrets, body) {
+    const payload = concat(utf8(`${sig.t}.`), body);
+    let ok = false;
+    for (const s of secrets) {
+        const want = await mac(s, payload);
+        for (const got of sig.signatures)
+            if (equal(want, got))
+                ok = true;
+    }
+    if (!ok)
+        throw new SignatureError("invalid", "The EZGH-Signature doesn't match any signing secret");
+}
+// verify = parseSignature then verifyParsed.
+export async function verify(header, secrets, body, now) {
+    await verifyParsed(parseSignature(header, now), secrets, body);
+}

package/dist/protocol/stepid.d.ts

@@ -0,0 +1,4 @@
+export declare function stepId(name: string, occurrence: number): Promise<string>;
+export declare const validStepIdOverride: (s: string) => boolean;
+export declare const validWorkflowName: (s: string) => boolean;
+export declare const validRunKey: (s: string) => boolean;

package/dist/protocol/stepid.js

@@ -0,0 +1,9 @@
+import { toHex, utf8 } from "./bytes.js";
+// stepId: lowercase hex of the first 16 bytes of SHA-256(name + "\0" + decimal occurrence).
+export async function stepId(name, occurrence) {
+    const d = new Uint8Array(await crypto.subtle.digest("SHA-256", utf8(`${name}\u0000${occurrence}`)));
+    return toHex(d.subarray(0, 16));
+}
+export const validStepIdOverride = (s) => typeof s === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(s);
+export const validWorkflowName = (s) => typeof s === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(s);
+export const validRunKey = validStepIdOverride;

package/dist/protocol/tokens.d.ts

@@ -0,0 +1,2 @@
+export declare function shardOf(runId: string): number | undefined;
+export declare function isInvocationToken(s: string): boolean;

package/dist/protocol/tokens.js

@@ -0,0 +1,38 @@
+import { fromBase64url } from "./bytes.js";
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+// shardOf reads the shard (0–1023) from a v7 or v8 run ID: rand_a holds 0b00 and the 10-bit
+// shard. It returns undefined for anything else (internal/protocol ShardOf).
+export function shardOf(runId) {
+    if (typeof runId !== "string" || !uuid.test(runId))
+        return undefined;
+    const hex = runId.replace(/-/g, "");
+    const b6 = parseInt(hex.slice(12, 14), 16);
+    const b7 = parseInt(hex.slice(14, 16), 16);
+    const b8 = parseInt(hex.slice(16, 18), 16);
+    const version = b6 >> 4;
+    if ((version !== 7 && version !== 8) || (b8 & 0xc0) !== 0x80 || (b6 & 0x0c) !== 0)
+        return undefined;
+    return ((b6 & 0x03) << 8) | b7;
+}
+// isInvocationToken: "<shard 3 hex>.<run UUID>.<invocation ID>.<43 base64url secret>", the shard
+// being the run ID's (internal/protocol ParseInvocationToken). SDKs pass tokens through; they
+// check the shape only to fail fast.
+export function isInvocationToken(s) {
+    if (typeof s !== "string")
+        return false;
+    const parts = s.split(".");
+    if (parts.length !== 4)
+        return false;
+    const [shard, runId, invocationId, secret] = parts;
+    if (!/^[0-9a-f]{3}$/.test(shard) || !/^inv_[a-z2-7]{26}$/.test(invocationId))
+        return false;
+    const runShard = shardOf(runId);
+    if (runShard === undefined || runShard !== parseInt(shard, 16))
+        return false;
+    try {
+        return fromBase64url(secret).length === 32;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/protocol/types.d.ts

@@ -0,0 +1,185 @@
+export interface RetryPolicy {
+    maxAttempts: number;
+    initialMs: number;
+    maxMs: number;
+    multiplier: number;
+}
+export interface WireError {
+    code: string;
+    name: string;
+    message: string;
+    data?: unknown;
+    stack?: string;
+    cause?: WireError;
+}
+export interface JournalEntry {
+    seq: number;
+    stepId: string;
+    name: string;
+    kind: "run" | "sleep" | "value" | "callback" | "invoke" | "message" | (string & {});
+    status: "running" | "retrying" | "completed" | "failed" | "cancelled" | "sleeping" | "waiting" | (string & {});
+    attempt: number;
+    output?: unknown;
+    outputRef?: string;
+    error?: WireError;
+    token?: string;
+    createdSeq?: number;
+    queueId?: string;
+    key?: string;
+    timedOut?: boolean;
+}
+export interface Journal {
+    complete: boolean;
+    entries: JournalEntry[];
+}
+export interface ScheduleInfo {
+    id: string;
+    scheduledTime: string;
+}
+export interface RunInfo {
+    id: string;
+    runKey?: string;
+    workflow: string;
+    input?: unknown;
+    inputRef?: string;
+    attempt: number;
+    startedAt: string;
+    schedule?: ScheduleInfo;
+}
+export interface Cancel {
+    requestedAt: string;
+    graceUntil: string;
+}
+export interface Endpoints {
+    live: string;
+    api?: string;
+}
+export interface Invocation {
+    protocolVersion: string;
+    kind: "orchestrate" | "step" | "sync";
+    invocationId: string;
+    token: string;
+    endpoints: Endpoints;
+    run?: RunInfo;
+    journal?: Journal;
+    targetStepId?: string;
+    deadline: string;
+    cancel: Cancel | null;
+    traceparent?: string;
+}
+export interface PlannedStep {
+    stepId: string;
+    name: string;
+    retry: RetryPolicy;
+    timeoutMs?: number;
+}
+export type Command = {
+    type: "stepStarted";
+    stepId: string;
+    name: string;
+    attempt: number;
+    retry: RetryPolicy;
+    timeoutMs?: number;
+} | {
+    type: "stepCompleted";
+    stepId: string;
+    name: string;
+    output: unknown;
+} | {
+    type: "stepFailed";
+    stepId: string;
+    name: string;
+    attempt: number;
+    error: WireError;
+    retryable: boolean;
+    retryAfterMs?: number;
+} | {
+    type: "valueRecorded";
+    stepId: string;
+    name: string;
+    value: unknown;
+} | {
+    type: "sleep";
+    stepId: string;
+    name: string;
+    until: string;
+} | {
+    type: "callbackCreated";
+    stepId: string;
+    name: string;
+    token: string;
+    timeoutMs: number;
+} | {
+    type: "waitForCallback";
+    stepId: string;
+} | {
+    type: "invoke";
+    stepId: string;
+    name: string;
+    workflow: string;
+    input?: unknown;
+} | {
+    type: "planParallel";
+    steps: PlannedStep[];
+} | {
+    type: "messageWaitCreated";
+    stepId: string;
+    name: string;
+    queueId: string;
+    key: string;
+    timeoutMs: number;
+} | {
+    type: "waitForMessage";
+    stepId: string;
+} | {
+    type: "runCompleted";
+    output: unknown;
+} | {
+    type: "runFailed";
+    error: WireError;
+    causeStepId?: string;
+} | {
+    type: "workflowNotFound";
+    workflow: string;
+};
+export interface Checkpoint {
+    invocationId: string;
+    seq: number;
+    commands: Command[];
+}
+export interface SDKInfo {
+    name: string;
+    version: string;
+}
+export interface InvocationResult {
+    commands: Command[];
+    deployment?: string;
+    sdk: SDKInfo;
+}
+export interface WorkflowInfo {
+    name: string;
+    retry?: RetryPolicy;
+    timeoutMs?: number;
+}
+export interface SyncReply {
+    protocolVersions: string[];
+    sdk: SDKInfo;
+    maxInvocationSeconds: number;
+    workflows: WorkflowInfo[];
+    deployment?: string;
+}
+export interface PollRequest {
+    app: string;
+    queue: string;
+    maxTasks: number;
+    workerId: string;
+    protocolVersions: string[];
+    sdk: SDKInfo;
+    workflows?: WorkflowInfo[];
+}
+export interface PollResponse {
+    invocations: Invocation[];
+}
+export interface HeartbeatResponse {
+    cancel: Cancel | null;
+}

package/dist/protocol/types.js

@@ -0,0 +1 @@
+export {};

package/dist/protocol/validate.d.ts

@@ -0,0 +1,15 @@
+export declare const MAX_ERROR_DEPTH = 8;
+export declare const MAX_PLANNED_STEPS = 1000;
+export declare const UUID: RegExp;
+export declare const MESSAGE_KEY: RegExp;
+export declare const MIN_MESSAGE_TIMEOUT_MS = 1000;
+export declare const MAX_MESSAGE_TIMEOUT_MS = 2592000000;
+export declare class InvalidMessage extends Error {
+    name: string;
+}
+export declare function validateRetry(p: unknown): void;
+export declare function validateError(e: unknown): void;
+export declare function validateCommand(cmd: unknown): void;
+export declare function validateCheckpoint(cp: unknown): void;
+export declare function validateInvocationResult(r: unknown): void;
+export declare function validatePollRequest(r: unknown): void;