Files

@effect/platform-cloudflare

Runs Effect Cluster on Cloudflare Durable Objects. Every entity instance is one Durable Object, the Worker is the edge, and each object's SQLite storage is the system of record.

This package is experimental. Its APIs may change in patch releases.

Installation

npm install effect@rc @effect/platform-cloudflare@rc

Usage

The package ships four Durable Object classes. Re-export them from your Worker entry module and bind each one as a SQLite-backed class:

// wrangler.jsonc
{
  "name": "my-worker",
  "main": "src/worker.ts",
  "compatibility_date": "2026-08-01",
  "durable_objects": {
    "bindings": [
      { "name": "CLUSTER_ENTITY", "class_name": "ClusterEntity" },
      { "name": "CLUSTER_WORKFLOW", "class_name": "ClusterWorkflow" },
      { "name": "CLUSTER_QUEUE", "class_name": "ClusterDurableQueue" },
      { "name": "CLUSTER_SINGLETON", "class_name": "ClusterSingleton" },
    ],
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": [
        "ClusterEntity",
        "ClusterWorkflow",
        "ClusterDurableQueue",
        "ClusterSingleton",
      ],
    },
  ],
  "triggers": {
    "crons": ["0 * * * *"],
  },
}
// src/worker.ts
import { CloudflareCluster, CloudflareDurableObjects } from "@effect/platform-cloudflare"
import { Effect, Layer, ManagedRuntime, Schema } from "effect"
import { Entity, Singleton } from "effect/cluster"
import { Rpc } from "effect/rpc"

export {
  ClusterDurableQueue,
  ClusterEntity,
  ClusterSingleton,
  ClusterWorkflow
} from "@effect/platform-cloudflare/CloudflareDurableObjects"

// The same Entity + RpcGroup definitions as on every other cluster path
const Counter = Entity.make("Counter", [
  Rpc.make("Increment", { success: Schema.Number })
])

const CounterLayer = Counter.toLayer({
  Increment: () => Effect.succeed(1)
})

const MaintenanceLayer = Singleton.make(
  "hourly-maintenance",
  Effect.logInfo("Running hourly maintenance")
)

const clusterLayer = (env: Env) =>
  Layer.merge(CounterLayer, MaintenanceLayer).pipe(
    Layer.provideMerge(CloudflareCluster.layer({
      entities: [Counter],
      entityNamespace: env.CLUSTER_ENTITY,
      workflowNamespace: env.CLUSTER_WORKFLOW,
      queueNamespace: env.CLUSTER_QUEUE,
      singletonNamespace: env.CLUSTER_SINGLETON
    }))
  )

// Build registration lazily inside the first Worker or Durable Object event.
// Each call builds a fresh ManagedRuntime, so a retry after a failed or
// stalled build starts over. The first runtime to finish is kept for the
// lifetime of this Worker isolate.
let application: ManagedRuntime.ManagedRuntime<any, any> | undefined
const initialize = CloudflareDurableObjects.setInitializer(async (env: Env) => {
  if (application !== undefined) return application.context()
  const runtime = ManagedRuntime.make(clusterLayer(env))
  const context = await runtime.context().catch(async (error) => {
    await runtime.dispose()
    throw error
  })
  if (application === undefined) {
    application = runtime
    return context
  }
  // A stalled build finished after a replacement: keep the replacement.
  await runtime.dispose()
  return application.context()
})

The initializer is the readiness contract shared by all four Durable Object classes. Each cold object waits for it through blockConcurrencyWhile before handling a request or alarm, and concurrent cold objects still build the application only once per Worker isolate. If initialization fails, the failure is returned to every caller waiting on that build, and the next cold object runs the initializer again. Because 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 15 seconds is treated as abandoned. Only an object that has waited less than 15 seconds runs the initializer itself, whether it replaces a stalled build or retries after a failure, so any replacement also gets at least 15 seconds. A slow build can therefore run more than once in an isolate, and the initializer must tolerate that. The example above keeps the first runtime to finish and disposes any other. Worker request handlers should call the same initialize(env) function before using application.

Applications whose registrations are complete synchronously during module evaluation can keep the previous bare re-export pattern without an initializer. Asynchronous layer builds must register one before serving traffic.

The Cron Trigger wakes the named singleton through its same-Worker binding. The call returns after one run, allowing the Durable Object to hibernate; do not make the singleton effect a forever loop. A failed run is logged by the singleton object and resolves wake() with { _tag: "Failure", message }, so a rejected wake() means the call failed in transit and can be retried.

export default {
  scheduled(_controller: ScheduledController, env: Env, ctx: ExecutionContext) {
    const singleton = env.CLUSTER_SINGLETON.getByName("Singleton/hourly-maintenance")
    ctx.waitUntil(singleton.wake())
  }
}

Entity.client stays the user API. The Worker encodes (type, id) into the Durable Object name and resolves the object with getByName; an unknown entity type fails at the Worker before any Durable Object is contacted.

Waking a ClusterCron

ClusterCron.make registers a seed singleton named ClusterCron/<name> that schedules the first run. On the other cluster backends that singleton starts as soon as a runner holds its shard. Here a singleton runs only when something wakes it, and nothing seeds it for you, so a ClusterCron never fires until a Cron Trigger wakes its seed singleton.

CloudflareCluster.clusterCronSingletonName(name) returns that singleton name. After the first wake each run schedules the next one through a destination alarm. Waking it on every trigger is safe: a run already scheduled for the same instant is deduplicated, and the wake restarts a schedule that was lost.

const NightlyReport = ClusterCron.make({
  name: "nightly-report",
  cron: Cron.parseUnsafe("0 2 * * *", "UTC"),
  execute: Effect.logInfo("Sending the nightly report")
})

export default {
  scheduled(_controller: ScheduledController, env: Env, ctx: ExecutionContext) {
    const name = CloudflareCluster.clusterCronSingletonName("nightly-report")
    ctx.waitUntil(env.CLUSTER_SINGLETON.getByName(`Singleton/${name}`).wake())
  }
}

Merge NightlyReport into the layer passed to CloudflareCluster.layer, like any other singleton.

Deploying with Alchemy

Alchemy v2 ("Infrastructure as Effects") is the second deployment story, behind the optional @alchemy.run/cloudflare peer dependency (>=2.0.0-beta.85 <3). The Wrangler path above never imports it.

npm install alchemy@beta @alchemy.run/cloudflare@beta

With Alchemy there is no wrangler config, no class re-exports, and no initializer: AlchemyCloudflareCluster.make runs inside the Effect-native Cloudflare.Worker init program and registers the four Durable Object classes itself, so Alchemy owns the bindings, class exports, and SQLite migrations across deploys. Cron Triggers stay user-declared through cluster.wake:

// src/worker.ts
import * as Cloudflare from "@alchemy.run/cloudflare"
import * as AlchemyCloudflareCluster from "@effect/platform-cloudflare/AlchemyCloudflareCluster"
import * as CloudflareCluster from "@effect/platform-cloudflare/CloudflareCluster"
import * as Effect from "effect/Effect"
import * as Layer from "effect/Layer"

export default Cloudflare.Worker(
  "MyApp",
  {
    main: import.meta.url
  },
  Effect.gen(function*() {
    const cluster = yield* AlchemyCloudflareCluster.make({
      entities: [Counter],
      layer: Layer.mergeAll(CounterLayer, MaintenanceLayer, NightlyReport)
    })

    yield* Cloudflare.Workers.cron("0 * * * *", cluster.wake("hourly-maintenance"))
    // A ClusterCron fires only after a Cron Trigger wakes its seed singleton
    yield* Cloudflare.Workers.cron(
      "30 * * * *",
      cluster.wake(CloudflareCluster.clusterCronSingletonName("nightly-report"))
    )

    return {
      // routes using Entity.client, etc.
      fetch: cluster.provide(handler)
    }
  }).pipe(Effect.provide(Cloudflare.Workers.CronEventSourceLive))
)
// alchemy.run.ts
import * as Cloudflare from "@alchemy.run/cloudflare"
import * as Alchemy from "alchemy"
import * as Effect from "effect/Effect"
import App from "./src/worker.ts"

export default Alchemy.Stack(
  "MyApp",
  { providers: Cloudflare.providers(), state: Cloudflare.state() },
  Effect.gen(function*() {
    const app = yield* App
    return { url: app.url }
  })
)

make builds the cluster layer merged with your handler layer into the isolate-lifetime scope and hands back provide for the Worker's handlers, so do not wrap the init program in Effect.provide for cluster services — that would tear the layer down when init returns. The handle also exposes the four native namespace bindings (entityNamespace, workflowNamespace, queueNamespace, singletonNamespace) as escape hatches. These bindings and context are runtime-only; reading them during plan evaluation throws a diagnostic. During planning, provide passes through its Effect and wake does nothing.

A complete runnable example (one entity, one singleton, one Cron Trigger) lives at examples/alchemy.

Manual live smoke

The live deployment smoke has not yet been verified.

Alchemy tracks the published effect release, so CI covers this integration with typechecks only (plus the manual Alchemy Canary workflow against the latest alchemy@beta). After changing the integration, run one live smoke with Cloudflare credentials configured:

  1. cd packages/platform/cloudflare/examples/alchemy
  2. alchemy deploy — expect the Worker plus the four SQLite-backed Durable Object classes (ClusterEntity, ClusterWorkflow, ClusterDurableQueue, ClusterSingleton) and the 0 * * * * Cron Trigger.
  3. curl https://<worker-url>/counter-1 twice — expect 1 then 2.
  4. Trigger the cron (or wait for the top of the hour) and check the Worker logs for Running hourly maintenance.
  5. alchemy destroy to clean up.

Worker routes

The existing EntityProxy / EntityProxyServer and WorkflowProxy / WorkflowProxyServer modules remain the route helpers. Define an HTTP or RPC surface with the proxy module, then provide its server layer with CloudflareCluster.layer. Entity proxy handlers call Entity.client, and workflow proxy handlers call the workflow API, so the Cloudflare layers encode the entity or workflow name and resolve the corresponding Durable Object stub. There is no runner-fleet proxy on this path.

These are Worker routes, not Durable Object routes. The Durable Object classes are internal transport: they trust the same-Worker namespace bindings and must not be exposed on a public route. HTTP or RPC authentication and authorization are user code on the Worker.

Long waits and delivery

  • A long ask pins the caller. A delayed ask made directly by a Worker also keeps the destination RPC open, so it pins the destination too.
  • Caller eviction or deployment drops the in-memory wait even though the destination may still run the persisted request.
  • Prefer a tell when no response is needed. For durable long waits, prefer a workflow with DurableClock and DurableDeferred.
  • Stream asks with a future DeliverAt are outside v1.

Handler concurrency

Entity.toLayer(..., { concurrency }) applies inside the entity Durable Object. The default of 1 runs one handler at a time, a number allows that many in-flight handlers per entity, and "unbounded" removes the limit. Durable Object isolates are single-threaded, so this is interleaving of suspended handlers, not parallelism.

  • Envelope decode, persist-before-run, dedupe, duplicate resume, and alarm arming stay serialized at any setting.
  • With concurrency above 1, strict mailbox ordering holds per permit, the same as the classic runner path: in-flight handlers interleave at every suspension point.
  • An ask cycle (entity A asks B while B's handler asks A back) needs concurrency of at least 2 on the entity receiving the second ask. At the default of 1 the cycle deadlocks, matching the classic contract.
  • Replayed mailbox rows and alarm-due runs draw from the same budget as live requests.

defectRetryPolicy and spanAttributes also apply inside the entity Durable Object. disableFatalDefects, maxIdleTime, and mailboxCapacity are accepted for parity and have no effect. Hibernation owns idle entities, and the mailbox capacity is fixed at 4096.

Defects on this path are always request-local, as if disableFatalDefects were true. A handler defect is retried under defectRetryPolicy when one is set, then the request gets a terminal defect reply and the handlers are rebuilt. Other in-flight requests finish on the build they started on and are not replayed.

Entity SQL storage

Each entity Durable Object provides CloudflareCluster.DurableObjectSqlClient to its handler build and handlers: an SqlClient on the object's own SQLite storage. It is a separate tag, so an app-wide SqlClient from the Worker layer (a D1 database, say) keeps working inside the handlers.

Register the handlers with Entity.toLayer and read the client with CloudflareCluster.DurableObjectSqlClient.orDie in the build. orDie has no requirements, so the layer needs nothing extra. Yielding DurableObjectSqlClient directly would leave it as a layer requirement. Handlers registered with Entity.toLayerQueue get the client the same way.

import { CloudflareCluster } from "@effect/platform-cloudflare"
import { Effect, Schema } from "effect"
import { Entity } from "effect/cluster"
import { Rpc } from "effect/rpc"

const Journal = Entity.make("Journal", [
  Rpc.make("Append", { payload: { entries: Schema.Array(Schema.String) } }),
  Rpc.make("List", { success: Schema.Array(Schema.String) })
])

const build = Effect.gen(function*() {
  const sql = yield* CloudflareCluster.DurableObjectSqlClient.orDie
  yield* sql`CREATE TABLE IF NOT EXISTS journal (seq INTEGER PRIMARY KEY AUTOINCREMENT, entry TEXT NOT NULL)`
  return Journal.of({
    // Every entry commits together, or none do.
    Append: ({ payload }) =>
      sql.withTransaction(
        Effect.forEach(payload.entries, (entry) => sql`INSERT INTO journal (entry) VALUES (${entry})`)
      ).pipe(Effect.asVoid, Effect.orDie),
    List: () =>
      sql<{ readonly entry: string }>`SELECT entry FROM journal ORDER BY seq`.pipe(
        Effect.map((rows) => rows.map((row) => row.entry)),
        Effect.orDie
      )
  })
}).pipe(Effect.orDie)

const JournalLayer = Journal.toLayer(build)

To run code written against SqlClient.SqlClient, such as SqlSchema or Model.makeRepository, provide the entity client as that service locally: Effect.provideService(effect, SqlClient.SqlClient, sql).

  • orDie dies on the first handler build when no DurableObjectSqlClient is provided, such as outside an entity Durable Object or in a test without a SQL layer.
  • Rows live and die with the entity's Durable Object. They cannot be queried from outside it or from another entity.
  • Tables whose names start with cluster_ are reserved. The entity mailbox uses cluster_messages and cluster_replies, and reset / clearReplies only touch those tables.
  • A row cannot exceed 2 MB, the same SQLite ceiling as an encoded message.
  • A storage transaction closes the Durable Object's input gate until it finishes. Timers and I/O awaited inside withTransaction never resume, so keep transactions to SQL work.
  • Mailbox writes wait for an open transaction to finish, so a rollback never takes another handler's stored reply with it.

To test the handlers, run the same layer with Entity.makeTestClient, providing DurableObjectSqlClient from any SQL layer, for example an in-memory @effect/sql-sqlite-node client:

import { SqliteClient } from "@effect/sql-sqlite-node"
import { Effect, Layer } from "effect"
import { Entity, ShardingConfig } from "effect/cluster"
import { SqlClient } from "effect/sql"

const EntitySqlTest = Layer.effect(
  CloudflareCluster.DurableObjectSqlClient,
  Effect.service(SqlClient.SqlClient)
).pipe(Layer.provide(SqliteClient.layer({ filename: ":memory:" })))

const program = Effect.gen(function*() {
  const makeClient = yield* Entity.makeTestClient(Journal, JournalLayer)
  const journal = yield* makeClient("one")
  yield* journal.Append({ entries: ["a", "b"] })
  return yield* journal.List()
}).pipe(
  Effect.scoped,
  Effect.provide(Layer.merge(ShardingConfig.layer(), EntitySqlTest))
)

Restarts and recovery

A deploy, a runtime update, or an eviction kills the entity Durable Object. Cloudflare does not re-create it by itself: the object stays cold until a request, an alarm, or a WebSocket event arrives. To recover without outside contact, the entity keeps an alarm in storage while it has something to come back for:

  • While it holds Entity.keepAlive, the alarm re-arms every keepAliveHeartbeat interval (30 seconds by default, set on CloudflareCluster.layer or AlchemyCloudflareCluster.make). After a restart the alarm rebuilds the entity, which runs its handler build, and restores the hold. Entity.keepAlive(false) ends it.
  • While a persisted request runs, the alarm stays armed one interval ahead. After a restart it replays every unprocessed row, so an interrupted request runs again without a new message. Replay is alarm-driven; any later request to the entity replays the rows too.

The interval is recovery latency, not a liveness check. At 30 seconds a kept-alive entity costs about 2,880 alarm requests a day, which is small next to the duration billing of the held object itself.

Things to plan for:

  • After a deploy, kept-alive entities keep running the old code for about 5 minutes, then die without warning. Schema changes must tolerate old code still running against the same storage.
  • Recovery after a deploy takes about those 5 minutes plus one interval. The hold cannot see the deploy; only the heartbeat brings the entity back.
  • The keep-alive flag is persisted, the holder count is not. Each handler build counts its own holders, so two EntityResources need two releases. Classic cluster drops the hold when the first one releases.
  • An EntityResource that is not acquired eagerly in the handler build leaves the object pinned after a restart until a later Entity.keepAlive(false). Classic cluster behaves the same.
  • A deploy that removes an entity type leaves its heartbeat behind. The alarm fails, Cloudflare retries it 6 times, and the chain stops; the stored keep-alive flag is never cleaned up.

v1 compatibility

The status vocabulary is maps 1:1, adapted, and out of scope.

Capability Status Rationale
Entity + RpcGroup definition adapted Same definition; handlers register at Worker init onto one shared Durable Object class
Entity.client / location-transparent ask-tell adapted Worker encodes (type, id) and calls getByName; there is no ShardId routing
EntityProxy / EntityProxyServer and workflow equivalents adapted Worker route helpers encode the name and stub the Durable Object through the Cloudflare layers
Non-Persisted RPC adapted Best-effort in-request only; it can be lost on hibernation or a crash
Persisted ask/tell + mailbox adapted Per-entity Durable Object SQLite, persist-before-run, and uuidv7 request ids
PrimaryKey dedupe / Duplicate resume maps 1:1 Same contract
Stream ask Chunk / AckChunk / lastSentChunk / WithExit maps 1:1 Same reply protocol on Durable Object storage
clearReplies / reset maps 1:1 Same re-run semantics
DeliverAt mailbox delivery adapted Destination due column and alarm instead of storage polling
Ask + future DeliverAt adapted Destination may hibernate through replyTo; ask pins its caller, and a Worker ask pins the destination too
Worker to Durable Object transport failures adapted Typed PersistenceError; persisted requests retry retryable errors on a fresh stub, others fail at once
MailboxFull / 4096 cap / 2 MB row rejection maps 1:1 Same limits; the SQLite row is the hard ceiling
defectRetryPolicy then terminal defect adapted Rebuilds handlers in the wake; crash or deployment wipes memory and replays unprocessed rows
Entity.toLayer concurrency maps 1:1 Same per-entity handler interleaving contract; storage entry stays serialized at any setting
Entity.keepAlive maps 1:1 Survives restarts through a heartbeat alarm; the holder count is per handler build, not persisted
CurrentRunnerAddress adapted Synthetic address for identity and telemetry; no peer dialing
EntityResource.make adapted External lifetimes such as a browser; close or idle TTL unpins
DurableObjectSqlClient in entity handlers (Entity.toLayer + orDie) adapted The entity Durable Object's own SQLite; cluster_ tables reserved, 2 MB rows, transactions per object
EntityResource.makeK8sPod out of scope Requires K8sHttpClient
Workflow / Activity / DurableDeferred user APIs maps 1:1 Unchanged; the engine behind them changes
CloudflareWorkflowEngine (WorkflowEngine.Encoded) adapted Dedicated workflow Durable Object, SQLite, and one alarm
DurableClock adapted Always durable; there is no short in-memory timer path
DurableQueue adapted One Durable Object per queue name with SQLite and an alarm watchdog
PersistedQueue.layerCleanup out of scope Fails explicitly; namespace bindings cannot enumerate queue objects. Completed rows are retained for dedup.
Singleton adapted Named Durable Object; runs once per wake and then may hibernate
ClusterCron adapted Per-fire entity ids, DeliverAt destination alarms, and a singleton seed
Address (EntityType, EntityId) adapted Length-prefixed Durable Object name; cold first contact is normal
Sharding.getSnowflake out of scope Dies; isolates have no fleet-unique machine id. Request ids are uuidv7
ShardId / shard locks / runner ring out of scope One-instance-per-id replaces ownership
MessageStorage / RunnerStorage / RunnerHealth / Runners as user seams out of scope The Durable Object path owns persistence and alarms internally
HttpRunner / SocketRunner / peer runner fleet out of scope Worker edge only
EntityReaper / maxIdleTime out of scope Cloudflare hibernation owns sleep; keepAlive holders provide pinning
Activate/deactivate / shard handoff / EntityNotAssignedToRunner out of scope Whole-wake handlers with no handoff
Park-and-replay caller hibernation out of scope Not part of v1
Stream ask + future DeliverAt out of scope Delayed asks support non-stream WithExit only
External SQL as the system of record out of scope Durable Object SQLite is the system of record
Non-Worker long-lived runners as a first-class edge out of scope The Worker is the supported edge model

Documentation