@porulle/jobs-cloudflare 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unified-commerce-engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# `@porulle/jobs-cloudflare`
+
+Cloudflare Workflows binding adapter and task runner for Porulle. Keyed exclusivity and supersession require a durable coordinator (normally a Durable Object); the adapter fails fast when a keyed task is used without one.
+
+```ts
+import { WorkflowEntrypoint } from "cloudflare:workers";
+import { CloudflareExecutionEngine } from "@porulle/jobs-cloudflare";
+
+export const jobs = new CloudflareExecutionEngine({
+  workflow: env.PORULLE_WORKFLOW,
+  coordinator,
+});
+
+export class PorulleWorkflow extends WorkflowEntrypoint {
+  async run(event, step) {
+    return jobs.run(event.payload, step);
+  }
+}
+```
+
+The coordinator must durably supersede pending instances at enqueue and serialize `run()` by concurrency key. Unkeyed tasks can use the Workflow binding directly.

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import type { EnqueueOptions, ExecutionEngine, ExecutionEngineSetup } from "@porulle/core";
+export interface CloudflareJobPayload {
+    taskSlug: string;
+    input: Record<string, unknown>;
+    organizationId: string;
+    maxAttempts: number;
+    delayMs?: number;
+    concurrencyKey?: string;
+    exclusive: boolean;
+    supersedes: boolean;
+}
+export interface WorkflowBinding {
+    create(options: {
+        id?: string;
+        params: CloudflareJobPayload;
+    }): Promise<{
+        id: string;
+    }>;
+}
+export interface WorkflowStep {
+    sleep(name: string, duration: number | string): Promise<void>;
+    do<T>(name: string, config: {
+        retries: {
+            limit: number;
+            delay: number;
+            backoff: "constant" | "exponential";
+        };
+    }, callback: (context: {
+        attempt: number;
+    }) => Promise<T>): Promise<T>;
+}
+export interface CloudflareConcurrencyCoordinator {
+    enqueue(payload: CloudflareJobPayload, create: () => Promise<{
+        id: string;
+    }>): Promise<{
+        id: string;
+    }>;
+    run<T>(key: string, handler: () => Promise<T>): Promise<T>;
+}
+export interface CloudflareExecutionEngineOptions {
+    workflow: WorkflowBinding;
+    coordinator?: CloudflareConcurrencyCoordinator;
+}
+export declare class CloudflareExecutionEngine implements ExecutionEngine {
+    private readonly options;
+    readonly execution: {
+        mode: "push";
+    };
+    private setup;
+    constructor(options: CloudflareExecutionEngineOptions);
+    register(setup: ExecutionEngineSetup): void;
+    enqueue(taskSlug: string, input: Record<string, unknown>, options: EnqueueOptions): Promise<string>;
+    run(payload: CloudflareJobPayload, step: WorkflowStep): Promise<Record<string, unknown>>;
+    private requireSetup;
+}

package/dist/index.js

@@ -0,0 +1,81 @@
+export class CloudflareExecutionEngine {
+    options;
+    execution = { mode: "push" };
+    setup;
+    constructor(options) {
+        this.options = options;
+    }
+    register(setup) {
+        this.setup = setup;
+    }
+    async enqueue(taskSlug, input, options) {
+        const task = this.requireSetup().tasks.get(taskSlug);
+        if (!task)
+            throw new Error(`Unknown task slug: ${taskSlug}`);
+        const organizationId = options.organizationId.trim();
+        if (!organizationId)
+            throw new Error("Jobs enqueue requires a non-empty organizationId.");
+        const concurrencyKey = options.concurrencyKey ?? task.concurrency?.key(input);
+        const exclusive = Boolean(task.concurrency && task.concurrency.exclusive !== false);
+        const supersedes = Boolean(options.supersedes ?? task.concurrency?.supersedes);
+        if ((exclusive || supersedes) &&
+            concurrencyKey &&
+            !this.options.coordinator) {
+            throw new Error("Cloudflare Workflows has no per-key queue concurrency primitive. Configure a durable CloudflareConcurrencyCoordinator for exclusive or superseding tasks.");
+        }
+        const payload = {
+            taskSlug,
+            input,
+            organizationId,
+            maxAttempts: options.maxAttempts ?? task.retries?.attempts ?? 1,
+            exclusive,
+            supersedes,
+            ...(options.delayMs !== undefined ? { delayMs: options.delayMs } : {}),
+            ...(concurrencyKey ? { concurrencyKey } : {}),
+        };
+        const create = () => this.options.workflow.create({
+            id: crypto.randomUUID(),
+            params: payload,
+        });
+        const instance = this.options.coordinator && concurrencyKey
+            ? await this.options.coordinator.enqueue(payload, create)
+            : await create();
+        return instance.id;
+    }
+    async run(payload, step) {
+        const setup = this.requireSetup();
+        const task = setup.tasks.get(payload.taskSlug);
+        if (!task)
+            throw new Error(`Unknown task slug: ${payload.taskSlug}`);
+        if (payload.delayMs && payload.delayMs > 0) {
+            await step.sleep("porulle-delay", payload.delayMs);
+        }
+        const backoff = task.retries?.backoff;
+        const execute = () => step.do(`porulle:${payload.taskSlug}`, {
+            retries: {
+                limit: payload.maxAttempts,
+                delay: backoff?.delay ?? 1_000,
+                backoff: backoff?.type === "exponential" ? "exponential" : "constant",
+            },
+        }, async ({ attempt }) => {
+            const result = await task.handler({
+                input: payload.input,
+                ctx: setup.context,
+                job: { attemptNumber: attempt, maxAttempts: payload.maxAttempts },
+            });
+            return result.output;
+        });
+        if (payload.exclusive && payload.concurrencyKey) {
+            if (!this.options.coordinator) {
+                throw new Error("Exclusive Cloudflare task requires a durable concurrency coordinator.");
+            }
+            return this.options.coordinator.run(payload.concurrencyKey, execute);
+        }
+        return execute();
+    }
+    requireSetup() {
+        if (!this.setup)
+            throw new Error("CloudflareExecutionEngine must be registered before use.");
+        return this.setup;
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@porulle/jobs-cloudflare",
+  "version": "0.9.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@porulle/core": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4",
+    "@porulle/eslint-config": "0.1.0",
+    "@porulle/typescript-config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "description": "Cloudflare Workflows execution engine for Porulle background jobs.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/jobs-cloudflare"
+  },
+  "author": "Porulle contributors",
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,165 @@
+import type {
+  EnqueueOptions,
+  ExecutionEngine,
+  ExecutionEngineSetup,
+} from "@porulle/core";
+
+export interface CloudflareJobPayload {
+  taskSlug: string;
+  input: Record<string, unknown>;
+  organizationId: string;
+  maxAttempts: number;
+  delayMs?: number;
+  concurrencyKey?: string;
+  exclusive: boolean;
+  supersedes: boolean;
+}
+
+export interface WorkflowBinding {
+  create(options: {
+    id?: string;
+    params: CloudflareJobPayload;
+  }): Promise<{ id: string }>;
+}
+
+export interface WorkflowStep {
+  sleep(name: string, duration: number | string): Promise<void>;
+  do<T>(
+    name: string,
+    config: {
+      retries: {
+        limit: number;
+        delay: number;
+        backoff: "constant" | "exponential";
+      };
+    },
+    callback: (context: { attempt: number }) => Promise<T>,
+  ): Promise<T>;
+}
+
+export interface CloudflareConcurrencyCoordinator {
+  enqueue(
+    payload: CloudflareJobPayload,
+    create: () => Promise<{ id: string }>,
+  ): Promise<{ id: string }>;
+  run<T>(key: string, handler: () => Promise<T>): Promise<T>;
+}
+
+export interface CloudflareExecutionEngineOptions {
+  workflow: WorkflowBinding;
+  coordinator?: CloudflareConcurrencyCoordinator;
+}
+
+export class CloudflareExecutionEngine implements ExecutionEngine {
+  readonly execution = { mode: "push" as const };
+  private setup: ExecutionEngineSetup | undefined;
+
+  constructor(private readonly options: CloudflareExecutionEngineOptions) {}
+
+  register(setup: ExecutionEngineSetup): void {
+    this.setup = setup;
+  }
+
+  async enqueue(
+    taskSlug: string,
+    input: Record<string, unknown>,
+    options: EnqueueOptions,
+  ): Promise<string> {
+    const task = this.requireSetup().tasks.get(taskSlug);
+    if (!task) throw new Error(`Unknown task slug: ${taskSlug}`);
+    const organizationId = options.organizationId.trim();
+    if (!organizationId)
+      throw new Error("Jobs enqueue requires a non-empty organizationId.");
+
+    const concurrencyKey =
+      options.concurrencyKey ?? task.concurrency?.key(input);
+    const exclusive = Boolean(
+      task.concurrency && task.concurrency.exclusive !== false,
+    );
+    const supersedes = Boolean(
+      options.supersedes ?? task.concurrency?.supersedes,
+    );
+    if (
+      (exclusive || supersedes) &&
+      concurrencyKey &&
+      !this.options.coordinator
+    ) {
+      throw new Error(
+        "Cloudflare Workflows has no per-key queue concurrency primitive. Configure a durable CloudflareConcurrencyCoordinator for exclusive or superseding tasks.",
+      );
+    }
+
+    const payload: CloudflareJobPayload = {
+      taskSlug,
+      input,
+      organizationId,
+      maxAttempts: options.maxAttempts ?? task.retries?.attempts ?? 1,
+      exclusive,
+      supersedes,
+      ...(options.delayMs !== undefined ? { delayMs: options.delayMs } : {}),
+      ...(concurrencyKey ? { concurrencyKey } : {}),
+    };
+    const create = () =>
+      this.options.workflow.create({
+        id: crypto.randomUUID(),
+        params: payload,
+      });
+    const instance =
+      this.options.coordinator && concurrencyKey
+        ? await this.options.coordinator.enqueue(payload, create)
+        : await create();
+    return instance.id;
+  }
+
+  async run(
+    payload: CloudflareJobPayload,
+    step: WorkflowStep,
+  ): Promise<Record<string, unknown>> {
+    const setup = this.requireSetup();
+    const task = setup.tasks.get(payload.taskSlug);
+    if (!task) throw new Error(`Unknown task slug: ${payload.taskSlug}`);
+
+    if (payload.delayMs && payload.delayMs > 0) {
+      await step.sleep("porulle-delay", payload.delayMs);
+    }
+    const backoff = task.retries?.backoff;
+    const execute = () =>
+      step.do(
+        `porulle:${payload.taskSlug}`,
+        {
+          retries: {
+            limit: payload.maxAttempts,
+            delay: backoff?.delay ?? 1_000,
+            backoff:
+              backoff?.type === "exponential" ? "exponential" : "constant",
+          },
+        },
+        async ({ attempt }) => {
+          const result = await task.handler({
+            input: payload.input,
+            ctx: setup.context,
+            job: { attemptNumber: attempt, maxAttempts: payload.maxAttempts },
+          });
+          return result.output;
+        },
+      );
+
+    if (payload.exclusive && payload.concurrencyKey) {
+      if (!this.options.coordinator) {
+        throw new Error(
+          "Exclusive Cloudflare task requires a durable concurrency coordinator.",
+        );
+      }
+      return this.options.coordinator.run(payload.concurrencyKey, execute);
+    }
+    return execute();
+  }
+
+  private requireSetup(): ExecutionEngineSetup {
+    if (!this.setup)
+      throw new Error(
+        "CloudflareExecutionEngine must be registered before use.",
+      );
+    return this.setup;
+  }
+}