@voyantjs/workflows-orchestrator-cloudflare 0.6.7 → 0.6.9

package/dist/r2-sign.js

@@ -0,0 +1,98 @@
+// AWS SigV4 presigned URL generator for Cloudflare R2.
+//
+// R2 speaks S3, so any valid SigV4-GetObject presigned URL works.
+// We hand-roll the signer (Web Crypto + fetch only) so the tenant
+// Worker doesn't need the AWS SDK — which is heavy enough to matter
+// on Workers' bundle-size limits.
+//
+// Usage on the orchestrator side:
+//
+//   const presign = createR2Presigner({
+//     accountId: env.R2_ACCOUNT_ID,
+//     accessKeyId: env.R2_ACCESS_KEY_ID,
+//     secretAccessKey: env.R2_SECRET_ACCESS_KEY,
+//     bucket: "voyant-bundles",
+//   });
+//   const url = await presign({ key: "prj_1/v1/container.mjs", expiresIn: 300 });
+export function createR2Presigner(opts) {
+    const host = `${opts.accountId}.r2.cloudflarestorage.com`;
+    const region = "auto"; // R2's SigV4 region convention.
+    const service = "s3";
+    return async ({ key, expiresIn }) => {
+        if (expiresIn < 1 || expiresIn > 604_800) {
+            throw new Error(`R2 presign: expiresIn must be 1..604800, got ${expiresIn}`);
+        }
+        const normalizedKey = key.replace(/^\/+/, "");
+        const encodedKey = normalizedKey
+            .split("/")
+            .map((seg) => encodeURIComponent(seg))
+            .join("/");
+        const now = new Date();
+        const amzDate = toAmzDate(now);
+        const shortDate = amzDate.slice(0, 8);
+        const credentialScope = `${shortDate}/${region}/${service}/aws4_request`;
+        const credential = `${opts.accessKeyId}/${credentialScope}`;
+        const params = [
+            ["X-Amz-Algorithm", "AWS4-HMAC-SHA256"],
+            ["X-Amz-Credential", credential],
+            ["X-Amz-Date", amzDate],
+            ["X-Amz-Expires", String(expiresIn)],
+            ["X-Amz-SignedHeaders", "host"],
+        ];
+        params.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+        const canonicalQuery = params
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+            .join("&");
+        const canonicalRequest = [
+            "GET",
+            `/${opts.bucket}/${encodedKey}`,
+            canonicalQuery,
+            `host:${host}\n`,
+            "host",
+            "UNSIGNED-PAYLOAD",
+        ].join("\n");
+        const stringToSign = [
+            "AWS4-HMAC-SHA256",
+            amzDate,
+            credentialScope,
+            await sha256Hex(canonicalRequest),
+        ].join("\n");
+        const signingKey = await deriveSigningKey(opts.secretAccessKey, shortDate, region, service);
+        const signature = toHex(await hmac(signingKey, stringToSign));
+        return `https://${host}/${opts.bucket}/${encodedKey}?${canonicalQuery}&X-Amz-Signature=${signature}`;
+    };
+}
+// ---- Crypto helpers ----
+function toAmzDate(d) {
+    const yyyy = d.getUTCFullYear();
+    const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(d.getUTCDate()).padStart(2, "0");
+    const hh = String(d.getUTCHours()).padStart(2, "0");
+    const mi = String(d.getUTCMinutes()).padStart(2, "0");
+    const ss = String(d.getUTCSeconds()).padStart(2, "0");
+    return `${yyyy}${mm}${dd}T${hh}${mi}${ss}Z`;
+}
+function toHex(bytes) {
+    const arr = new Uint8Array(bytes);
+    let out = "";
+    for (const b of arr)
+        out += b.toString(16).padStart(2, "0");
+    return out;
+}
+async function sha256Hex(input) {
+    const bytes = new TextEncoder().encode(input);
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return toHex(digest);
+}
+async function hmac(key, msg) {
+    const keyBuf = key instanceof Uint8Array ? key.slice().buffer : key;
+    const cryptoKey = await crypto.subtle.importKey("raw", keyBuf, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(msg));
+}
+async function deriveSigningKey(secret, shortDate, region, service) {
+    const kDate = await hmac(new TextEncoder().encode(`AWS4${secret}`), shortDate);
+    const kRegion = await hmac(kDate, region);
+    const kService = await hmac(kRegion, service);
+    const kSigning = await hmac(kService, "aws4_request");
+    return kSigning;
+}

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+import type { WaitpointInjection } from "@voyantjs/workflows-orchestrator";
+/**
+ * Subset of Cloudflare's `DurableObjectStorage` we actually use.
+ * Keyed JSON blobs; no transactional guarantees beyond what a single
+ * method call gives.
+ *
+ * Alarm methods are optional so in-memory fakes can opt out. On the
+ * real CF runtime they are always available. The adapter uses them
+ * to wake parked runs when their earliest DATETIME waitpoint comes
+ * due — see `handleDurableObjectAlarm`.
+ */
+export interface DurableObjectStorageLike {
+    get<T>(key: string): Promise<T | undefined>;
+    put<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    list<T>(options?: {
+        prefix?: string;
+        limit?: number;
+    }): Promise<Map<string, T>>;
+    /** ms-since-epoch of the scheduled alarm, or null if none. */
+    getAlarm?(): Promise<number | null>;
+    /** Schedule the DO's alarm() method to fire at `wakeAt`. */
+    setAlarm?(wakeAt: number): Promise<void>;
+    /** Cancel any pending alarm. */
+    deleteAlarm?(): Promise<void>;
+}
+/**
+ * Subset of a Workers-for-Platforms dispatch namespace. `get(name)`
+ * returns a binding whose `fetch` delivers to the tenant Worker
+ * registered under that name.
+ */
+export interface DispatchNamespaceLike {
+    get(name: string, args?: Record<string, unknown>): {
+        fetch(request: Request): Promise<Response>;
+    };
+}
+/** Args the Worker passes when routing to a run DO. */
+export interface RunOperation {
+    op: "trigger" | "resume" | "cancel" | "get";
+    payload?: unknown;
+}
+/** Injection payload on resume ops. */
+export interface ResumePayload {
+    injection: WaitpointInjection;
+}
+/** Trigger payload. */
+export interface TriggerPayload {
+    workflowId: string;
+    workflowVersion: string;
+    input: unknown;
+    tenantMeta: {
+        tenantId: string;
+        projectId: string;
+        organizationId: string;
+        /** Dispatch-namespace name to forward step requests to. */
+        tenantScript: string;
+    };
+    environment?: "production" | "preview" | "development";
+    tags?: string[];
+    runId?: string;
+}
+/** Cancel payload. */
+export interface CancelPayload {
+    reason?: string;
+}
+/**
+ * The Worker runtime env the adapter expects. Callers provide their
+ * own wrangler config; this interface documents what we read.
+ */
+export interface AdapterEnv<DONamespace = unknown, DispatchNS = DispatchNamespaceLike> {
+    /** Durable Object namespace holding one DO per run. Typed loosely to avoid a CF types dep. */
+    WORKFLOW_RUN_DO: DONamespace;
+    /** Dispatch namespace containing tenant Workers. */
+    DISPATCHER: DispatchNS;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAA;AAE1E;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IAC3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAA;IAC/E,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,gCAAgC;IAChC,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B;QACD,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAC3C,CAAA;CACF;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAA;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,kBAAkB,CAAA;CAC9B;AAED,uBAAuB;AACvB,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;IACvB,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;QACjB,cAAc,EAAE,MAAM,CAAA;QACtB,2DAA2D;QAC3D,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,WAAW,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG,aAAa,CAAA;IACtD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,sBAAsB;AACtB,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,WAAW,GAAG,OAAO,EAAE,UAAU,GAAG,qBAAqB;IACnF,8FAA8F;IAC9F,eAAe,EAAE,WAAW,CAAA;IAC5B,oDAAoD;IACpD,UAAU,EAAE,UAAU,CAAA;CACvB"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Structural types for the Cloudflare surface we use. We don't take
+// a hard dependency on `@cloudflare/workers-types` — matching the
+// shape is enough, and tests can pass plain objects.
+export {};

package/dist/worker.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal shape of a DO namespace. `idFromName` returns an opaque id;
+ * `get(id)` returns a stub with `fetch` (matching the CF DO API).
+ * Typed loosely so tests can pass any matching object.
+ */
+export interface DurableObjectNamespaceLike<Id = unknown> {
+    idFromName(name: string): Id;
+    get(id: Id): {
+        fetch(req: Request): Promise<Response>;
+    };
+}
+export interface WorkerFetchDeps<Id = unknown> {
+    runDO: DurableObjectNamespaceLike<Id>;
+    /**
+     * Called before any routing. Throws/rejects to reject the request.
+     * Typical implementation validates a tenant access token.
+     */
+    verifyRequest?: (req: Request) => void | Promise<void>;
+    /** Optional logger. */
+    logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+    /** id generator for new triggers; defaults to `run_<random>`. */
+    idGenerator?: () => string;
+    /** Injectable clock for id generation. */
+    now?: () => number;
+}
+export declare function handleWorkerRequest<Id>(req: Request, deps: WorkerFetchDeps<Id>): Promise<Response>;
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,MAAM,WAAW,0BAA0B,CAAC,EAAE,GAAG,OAAO;IACtD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,EAAE,CAAA;IAC5B,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG;QAAE,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAA;CACxD;AAED,MAAM,WAAW,eAAe,CAAC,EAAE,GAAG,OAAO;IAC3C,KAAK,EAAE,0BAA0B,CAAC,EAAE,CAAC,CAAA;IACrC;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,uBAAuB;IACvB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;IAC1B,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,wBAAsB,mBAAmB,CAAC,EAAE,EAC1C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,eAAe,CAAC,EAAE,CAAC,GACxB,OAAO,CAAC,QAAQ,CAAC,CA6EnB"}

package/dist/worker.js

@@ -0,0 +1,165 @@
+// Public HTTP surface of the Cloudflare orchestrator. The outer
+// Worker receives a request, resolves the run DO by id (or creates
+// one for a new trigger), and forwards to the DO. This layer owns
+// only routing + auth; the state machine lives in the DO.
+//
+// Routes (all JSON bodies):
+//   POST /api/runs                     → trigger a run
+//   GET  /api/runs/:id                 → fetch a run
+//   POST /api/runs/:id/signals         → inject a SIGNAL waitpoint
+//   POST /api/runs/:id/events          → inject an EVENT waitpoint
+//   POST /api/runs/:id/tokens/:token   → inject a MANUAL (token) waitpoint
+//   POST /api/runs/:id/cancel          → cancel a run
+export async function handleWorkerRequest(req, deps) {
+    const url = new URL(req.url);
+    if (req.method === "OPTIONS") {
+        return new Response(null, {
+            status: 204,
+            headers: corsHeaders("GET,POST,OPTIONS"),
+        });
+    }
+    try {
+        if (deps.verifyRequest)
+            await deps.verifyRequest(req);
+    }
+    catch (err) {
+        return json(401, {
+            error: "unauthorized",
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+    // POST /api/runs — trigger a new run.
+    if (req.method === "POST" && url.pathname === "/api/runs") {
+        let payload;
+        try {
+            payload = (await req.json());
+        }
+        catch (err) {
+            return json(400, { error: "invalid_json", message: errMsg(err) });
+        }
+        const runId = typeof payload.runId === "string" ? payload.runId : defaultRunId(deps);
+        const forward = new Request(`https://do-internal/trigger`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ ...payload, runId }),
+        });
+        return forwardToRunDO(runId, forward, deps);
+    }
+    // Everything below operates on a specific runId.
+    const runMatch = url.pathname.match(/^\/api\/runs\/([^/]+)(\/.+)?$/);
+    if (!runMatch) {
+        return json(404, { error: "route_not_found", path: url.pathname });
+    }
+    const runId = decodeURIComponent(runMatch[1]);
+    const tail = runMatch[2] ?? "";
+    if (req.method === "GET" && tail === "") {
+        const forward = new Request(`https://do-internal/get`, { method: "GET" });
+        return forwardToRunDO(runId, forward, deps);
+    }
+    if (req.method === "POST" && tail === "/cancel") {
+        const body = await safeJson(req);
+        if (isErrorBody(body))
+            return json(400, body);
+        return forwardToRunDO(runId, new Request(`https://do-internal/cancel`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        }), deps);
+    }
+    // Waitpoint injections: events, signals, tokens.
+    const body = await safeJson(req);
+    if (isErrorBody(body))
+        return json(400, body);
+    const injection = parseInjection(tail, body);
+    if ("error" in injection)
+        return json(400, injection);
+    return forwardToRunDO(runId, new Request(`https://do-internal/resume`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ injection: injection.injection }),
+    }), deps);
+}
+function isErrorBody(body) {
+    return typeof body.error === "string";
+}
+function parseInjection(tail, body) {
+    if (tail === "/events") {
+        if (typeof body.eventType !== "string" || body.eventType.length === 0) {
+            return { error: "invalid_body", message: "`eventType` (string) is required" };
+        }
+        return {
+            injection: { kind: "EVENT", eventType: body.eventType, payload: body.payload },
+        };
+    }
+    if (tail === "/signals") {
+        if (typeof body.name !== "string" || body.name.length === 0) {
+            return { error: "invalid_body", message: "`name` (string) is required" };
+        }
+        return { injection: { kind: "SIGNAL", name: body.name, payload: body.payload } };
+    }
+    const tokenMatch = tail.match(/^\/tokens\/([^/]+)$/);
+    if (tokenMatch) {
+        return {
+            injection: {
+                kind: "MANUAL",
+                tokenId: decodeURIComponent(tokenMatch[1]),
+                payload: body.payload,
+            },
+        };
+    }
+    return { error: "route_not_found", message: `unknown path suffix ${tail}` };
+}
+async function forwardToRunDO(runId, req, deps) {
+    const id = deps.runDO.idFromName(runId);
+    const stub = deps.runDO.get(id);
+    const resp = await stub.fetch(req);
+    // Add CORS on outbound responses.
+    const out = new Response(resp.body, resp);
+    for (const [k, v] of Object.entries(corsHeaders("GET,POST,OPTIONS"))) {
+        out.headers.set(k, v);
+    }
+    return out;
+}
+function defaultRunId(deps) {
+    if (deps.idGenerator)
+        return deps.idGenerator();
+    const now = deps.now ?? (() => Date.now());
+    const ts = now().toString(36);
+    const rand = Math.floor(Math.random() * 1_000_000)
+        .toString(36)
+        .padStart(4, "0");
+    return `run_${ts}_${rand}`;
+}
+async function safeJson(req) {
+    // Some requests are bodyless (GET). Only parse when we have a body.
+    if (req.method === "GET" || req.method === "HEAD")
+        return {};
+    const text = await req.text();
+    if (text.length === 0)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        return { error: "invalid_json", message: errMsg(err) };
+    }
+}
+function corsHeaders(methods) {
+    return {
+        "access-control-allow-origin": "*",
+        "access-control-allow-methods": methods,
+        "access-control-allow-headers": "content-type, x-voyant-protocol",
+    };
+}
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            "content-type": "application/json; charset=utf-8",
+            ...corsHeaders("GET,POST,OPTIONS"),
+        },
+    });
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/workflows-orchestrator-cloudflare",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "Cloudflare Worker + Durable Object adapter for @voyantjs/workflows-orchestrator. Dispatches workflow-step requests to tenant Workers via a Workers-for-Platforms dispatch namespace.",
   "license": "Apache-2.0",
   "repository": {
@@ -12,35 +12,41 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "files": ["dist", "src", "!**/*.test.*", "!**/*.spec.*", "NOTICE"],
-  "scripts": {
-    "build": "pnpm -C ../.. --filter @voyantjs/workflows-orchestrator build && tsc -p tsconfig.json",
-    "check-types": "pnpm -C ../.. --filter @voyantjs/workflows-orchestrator build && tsc --noEmit",
-    "dev": "tsc -w -p tsconfig.json",
-    "test": "pnpm -C ../.. --filter @voyantjs/workflows-orchestrator build && vitest run",
-    "test:watch": "vitest",
-    "test:workers": "pnpm -C ../.. --filter @voyantjs/workflows-orchestrator build && vitest run --config vitest.workers.config.ts"
-  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "NOTICE"
+  ],
   "dependencies": {
-    "@voyantjs/workflows-orchestrator": "workspace:*",
-    "@voyantjs/workflows": "workspace:*"
+    "@voyantjs/workflows-orchestrator": "0.6.9",
+    "@voyantjs/workflows": "0.6.9"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.7.0",
     "@cloudflare/workers-types": "^4.20241218.0",
     "@types/node": "^20.12.0",
-    "@voyantjs/voyant-typescript-config": "workspace:*",
     "typescript": "^5.9.2",
     "vitest": "^3.2.0",
-    "wrangler": "^3.99.0"
+    "wrangler": "^3.99.0",
+    "@voyantjs/voyant-typescript-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm -C ../.. --filter @voyantjs/workflows-orchestrator build && tsc -p tsconfig.json",
+    "check-types": "pnpm -C ../.. --filter @voyantjs/workflows-orchestrator build && tsc --noEmit",
+    "dev": "tsc -w -p tsconfig.json",
+    "test": "pnpm -C ../.. --filter @voyantjs/workflows-orchestrator build && vitest run",
+    "test:watch": "vitest",
+    "test:workers": "pnpm -C ../.. --filter @voyantjs/workflows-orchestrator build && vitest run --config vitest.workers.config.ts"
   }
-}
+}