CloudflareDurableObjects

The Durable Object classes behind CloudflareCluster.layer.

A Worker using the Cloudflare cluster re-exports these four classes from its entry module and binds each one in wrangler.jsonc as a SQLite-backed Durable Object class. The cluster resolves objects through the same-Worker namespace bindings only; none of these classes serve a public route, and any direct fetch of an object is rejected.

6 exports Since v4.1.3 Source

Durable Objects

ClusterDurableQueue

Since v4.1.3

The durable queue class behind the PersistedQueue implementation used by DurableQueue. One instance holds one named queue.

Details

The constructor stays cheap: it opens SQLite, ensures the queue table, and re-arms the single alarm from the earliest pending lease expiry. Items are leased to takers for a bounded time; the alarm watchdog expires overdue leases so an item whose worker died is redelivered. Requests and alarms wait for the registered setInitializer callback first.

Signature

declare class ClusterDurableQueue extends unknown<unknown> {
  constructor(ctx: DurableObjectState, env: unknown);
  fetch: () => never;
  alarm(): Promise<void>;
}

ClusterEntity

Since v4.1.3

The shared entity class. One instance holds one entity address; the handlers for every EntityType are registered at Worker init.

Details

The constructor stays cheap: it opens SQLite, ensures the mailbox tables, and re-arms the single alarm from the earliest pending deliver_at, or the keep-alive heartbeat when the entity holds Entity.keepAlive. User handlers are never built in the constructor; requests and alarms wait for the registered setInitializer callback, then handlers are built once per wake. Each build gets a DurableObjectSqlClient on this object's SQLite storage; tables whose names start with cluster_ are reserved for the mailbox.

Signature

declare class ClusterEntity extends unknown<unknown> {
  constructor(ctx: DurableObjectState, env: unknown);
  fetch: () => never;
  alarm(): Promise<void>;
}

ClusterSingleton

Since v4.1.3

The singleton class. One object holds one registered singleton under the name Singleton/<name> and is woken by a Worker Cron Trigger.

Details

The constructor opens SQLite, ensures the singleton state table, and re-arms the watchdog alarm for a wake interrupted by isolate loss. wake() runs the registered effect once and returns; it never appends Effect.never, so Cloudflare may hibernate the object afterward. A failed run is logged and resolves wake() with a Failure, so only a transport failure rejects it. Requests and alarms wait for the registered setInitializer callback before consulting the singleton registry.

Signature

declare class ClusterSingleton extends unknown<unknown> {
  constructor(ctx: DurableObjectState, env: unknown);
  fetch: () => never;
  alarm(): Promise<void>;
}

ClusterWorkflow

Since v4.1.3

The workflow execution class behind CloudflareWorkflowEngine. One instance holds one workflow execution: run state, activity results keyed ${name}/${attempt}, durable deferred exits, and the clock due table.

Details

The constructor stays cheap: it opens SQLite, ensures the workflow tables, and re-arms the single alarm from the earliest pending clock. Workflow requests and alarms wait for the registered setInitializer callback before handlers are looked up in the module-level registry and built once per wake.

Signature

declare class ClusterWorkflow extends unknown<unknown> {
  constructor(ctx: DurableObjectState, env: unknown);
  fetch: () => never;
  alarm(): Promise<void>;
}

Initialization

setInitializer

Since v4.1.3

Registers the Worker application initializer used by the Cloudflare cluster Durable Object classes.

Details

Call this once from the Worker entry module with the same lazy application build used by its request handlers. Every entity, workflow, queue, and singleton object blocks requests and alarms until that build completes. A failure is reported to every caller already waiting on that build, and the next cold caller runs the initializer again. The initializer must complete within 15 seconds. A build still pending after that is treated as abandoned, and a waiter runs the initializer itself, so a build can run more than once in an isolate. A Durable Object waiter starts a build only while it has waited less than 15 seconds, so any replacement keeps at least 15 seconds of the 30 second blockConcurrencyWhile limit. The returned function joins the same readiness state from Worker handlers.

Signature

declare function setInitializer<Env, A>(handler: Initializer<Env, A>): (env: Env) => Promise<A>

Models

Initializer

type

Since v4.1.3

Initializes the Worker application before a Cloudflare cluster Durable Object handles requests or alarms. The initializer is shared by all four Durable Object classes and runs once per Worker isolate unless a build fails or stalls.

Details

The initializer runs inside a Durable Object constructor's blockConcurrencyWhile, which Cloudflare cancels after 30 seconds. It must complete within 15 seconds: a build still pending after that is treated as abandoned, and a waiting object runs the initializer again.

Signature

type Initializer<Env = unknown, A = unknown> = (env: Env) => PromiseLike<A>