Testing & DeploymentCloudflare Workers

Cloudflare Workers

Notation Durable runs on Cloudflare inside one Durable Object. The object's SQLite storage holds the runtime, the object's alarm takes the place of the dispatcher's poll loop, and workflows run in the object's own isolate. Workflow and router files are the same as on Bun and Node.

How the pieces map

A Bun or Node deployment has a server process, worker processes and a SQLite file. On Cloudflare one Durable Object does all three jobs:

Bun or NodeCloudflare
SQLite file opened with createSqliteDbThe object's SQLite storage (ctx.storage.sql)
ExecutionDispatcher polling every 10 msThe object's alarm, set to the next time an execution is due
Worker processes forked by createWorkflowInvokerDeliveries run in the object's isolate
createRoutes mounted in Bun.serve or node:httpThe object's fetch handler

Setup

createWorkflowObject from @notation/durable/cloudflare builds the runtime, the dispatcher and the HTTP routes from the object's ctx. The Durable Object class forwards fetch and alarm to it:

import { DurableObject } from "cloudflare:workers";
import { createWorkflowObject } from "@notation/durable/cloudflare";
import { router } from "./workflows/router";

export class Workflows extends DurableObject {
  durable = createWorkflowObject(this.ctx, { router, basePath: "/durable" });

  fetch(request: Request) {
    return this.durable.fetch(request);
  }

  alarm() {
    return this.durable.alarm();
  }
}

export default {
  fetch(request: Request, env: Env) {
    // Authenticate the request here.
    const object = env.WORKFLOWS.get(env.WORKFLOWS.idFromName("default"));
    return object.fetch(request);
  },
};
{
  "name": "my-app",
  "main": "src/worker.ts",
  "compatibility_date": "2026-10-15",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "WORKFLOWS", "class_name": "Workflows" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Workflows"] }]
}

Two settings in wrangler.jsonc are required:

  • nodejs_compat – The SDK imports node:events and node:crypto.
  • new_sqlite_classes – The class must be SQLite-backed. A key-value-backed Durable Object has no ctx.storage.sql.

The alarm handler is required. Without it nothing resumes an execution after a step.delay, a retry or an eviction.

Triggering executions

The object serves the same routes as createRoutes under basePath: /trigger, /poll, /wait, /list, /events and /cancel. The HTTP SDK calls them over the public URL, or from another Worker through the object's stub by passing fetch:

src/signup.ts
import { createHttpSdkFactory } from "@notation/durable/client";
import type { Router } from "./workflows/router";

const createSdk = createHttpSdkFactory<Router>();

export async function signup(env: Env, email: string) {
  const object = env.WORKFLOWS.get(env.WORKFLOWS.idFromName("default"));
  const sdk = createSdk({
    url: "http://workflows/durable", // only the path is used
    fetch: (input, init) => object.fetch(input, init),
  });

  return sdk.trigger({ workflowId: "onboarding", params: { email } });
}

Code inside the Durable Object class can also call the local SDK on this.durable.runtime. Any write to the runtime, from a route or from the local SDK, sets the alarm and starts deliveries, so there is nothing else to call.

When deliveries run

The object does not poll. It claims executions at three moments:

  1. After a write. A trigger, a cancel, a store commit or an effect settlement commits to SQLite. In the same turn the object sets its alarm to the earliest time any execution is due, and claims what is due now.
  2. While deliveries are in flight. The object claims again when a delivery settles and when the next due time arrives.
  3. When the alarm fires. Once no delivery is in flight the object stops. The alarm starts it again at the next due time, such as the end of a step.delay.

If Cloudflare evicts the object during a delivery, the delivery's lease expires and the alarm delivers the execution again after the redelivery delay. The step that was running runs again, as it does after a worker crash on Bun or Node.

If claiming fails inside alarm, the object logs the error and sets the alarm to run again. The first retry is 0.5 seconds later, and each further failure doubles the wait, up to 60 seconds. alarm rejects only if it cannot set the alarm. Cloudflare runs a rejected alarm handler again six times and then drops the alarm.

Differences from Bun and Node

  • No process isolation. A delivery whose lease is lost cannot be killed. Its abort signal stops it before the next step, and its lease token rejects every later write.
  • One object, one thread. Every execution in the object shares one isolate and one database. For more throughput, route by tenant with idFromName(tenantId); executions in different objects cannot join each other or share stores.
  • Long deliveries. The object stays in memory while a step is pending, and Cloudflare bills that time. alarm returns after five minutes if deliveries are still in flight, because Cloudflare stops an alarm handler after 15 minutes; the deliveries carry on.

Keyless steps and deploys

Give every step an explicit key in a workflow that can be suspended across a deploy. A step without a key is keyed by the file, line and column of its call site, and in a Worker that is a position in the bundled output. A deploy that moves the position changes the key. An execution that was suspended before the deploy then finds no record under the new key:

StepAfter a deploy that moves its call site
Keyed step.run("charge", …)Replays its recorded result
Keyless step.run(…)Runs again
Keyless step.delay(300_000)Starts a new delay of the full length

The execution does not fail and logs no error. wrangler dev has the same effect on every restart, because the bundle path in the call site includes a temporary directory.