@gjermundgaraba/effect-actions-cloudflare 0.0.0-stage → 0.22.0

package/docs/ActionDurableObject-stub.md

@@ -0,0 +1,135 @@
+# ActionDurableObject over the stub
+
+A **stub** is what a Worker, or another object, reaches an object through, `env.<BINDING>.getByName(name)`, and a **stub call** a call of one of the object's methods over it, with Cloudflare's own RPC, Workers RPC. An object serves rpcs on one such method, `effectActionsRpc`, named for the package so it does not collide with the class's own, and a caller calls them with a typed client whose errors are the declared ones. Read [ActionDurableObject.md](ActionDurableObject.md) first. A message the library throws says its fix; for workerd's, a compiler diagnostic or Effect's own error, search [ActionDurableObject-failures.md](ActionDurableObject-failures.md).
+
+## Serve an object's own API over its stub
+
+Declare what only the Worker and other objects call as a plain Effect `RpcGroup`:
+
+```ts example=chat-rooms/src/lobby/Calls.ts
+import { Schema } from "effect";
+import { Rpc, RpcGroup } from "effect/rpc";
+
+import { RoomPreview } from "./Lobby.js";
+
+// The lobby's own API, over its stub: a room tells it its latest activity, and the Worker reads
+// the previews. A plain Effect `RpcGroup`, not actions: no page calls it, so it needs no contract
+// checks, no authentication and no JSON route, and nothing authenticates a stub call anyway, as
+// only a binding reaches it. Why a report heard late never overwrites a later one is at
+// `tellLobby`, in lobby-stubs.ts, which sends it.
+export const LobbyCalls = RpcGroup.make(
+  Rpc.make("roomChanged", { payload: RoomPreview }),
+  Rpc.make("previews", { success: Schema.Array(RoomPreview) })
+);
+```
+
+Its handlers read the store the instance built ([chat-rooms/src/lobby/handlers.ts](../examples/chat-rooms/src/lobby/handlers.ts)), and `RpcServer.layer(LobbyCalls)` over them is the object's `calls`, beside its routes ([chat-rooms/src/routes.ts](../examples/chat-rooms/src/routes.ts)), given to `make` in [chat-rooms/src/worker.ts](../examples/chat-rooms/src/worker.ts). `make` gives the calls their protocol; what crosses it, as values and not JSON, what it refuses and what the calls may require are on `ActionDurableObject.Options`' `calls`.
+
+A plain group suits an object's own API, which no page calls. Actions served on other surfaces too are served the same way, `calls: ActionRpc.layer(RoomRpc, room)`, and called with `ActionRpc.client(RoomRpc)` over `layerStubClient(env.CHAT_ROOM.getByName(room))`: their values cross as JSON, and a protected action authenticates each call from its headers, so the caller forwards the user's credential with `RpcClient.withHeaders`.
+
+## Call it from a Worker or another object
+
+`client(group)` makes one client, in the caller's `Scope`, for every object of a class, and returns `(stubOf) => client`: each call gets a new stub from `stubOf`, as it is sent, and fails with the rpc's declared errors or the stub's own, an `RpcClientError`, which the caller retries or makes a defect. The Worker reads the previews through `layerLobbyHost`, and a room tells the lobby through `tellLobby`, a task, below:
+
+```ts example=chat-rooms/src/platform/lobby-stubs.ts
+import * as ActionDurableObject from "@gjermundgaraba/effect-actions-cloudflare/ActionDurableObject";
+import { env } from "cloudflare:workers";
+import { Effect, Layer } from "effect";
+
+import { Activity } from "../chat/activity.js";
+import { Room } from "../chat/room.js";
+import { MessageStore } from "../chat/store.js";
+import { LobbyCalls } from "../lobby/Calls.js";
+import { LobbyHost } from "../lobby/host.js";
+
+// The lobby is one object, named `lobby`: a new stub for each call, read from `env` as the call
+// is sent, never as the module loads.
+const lobbyStub = () => env.CHAT_LOBBY.getByName("lobby");
+
+// The lobby's object as the Worker reaches it, for the previews: a lobby that cannot be reached
+// is the deployment's failure, not the caller's, so it is a defect, the Worker answers 500, and
+// the cause is in its logs.
+export const layerLobbyHost = Layer.effect(LobbyHost)(
+  Effect.map(ActionDurableObject.client(LobbyCalls), (lobby) =>
+    LobbyHost.of({ previews: Effect.orDie(lobby(lobbyStub).previews()) })
+  )
+);
+
+// The room's task, worker.ts's `lobby`: telling the lobby the room's latest activity. The room's
+// alarm runs its tasks one run at a time, each waiting for the lobby's answer, and each run reads
+// the activity as it is then: the lobby hears a room's reports in the order the room made them,
+// so a report heard late never overwrites a later one, and the last it hears is the room's
+// latest. A run repeated after a lost answer sends what the lobby holds, which `record` finds
+// unchanged, notifying no page.
+export const tellLobby = Effect.gen(function* () {
+  const room = yield* Room;
+  const latest = yield* MessageStore.use((store) => store.latest);
+  const lobby = yield* ActionDurableObject.client(LobbyCalls);
+
+  yield* lobby(lobbyStub).roomChanged({ room, latestAt: latest?.at ?? null });
+});
+
+// A room's activity, a startup service of the room's: each change runs the `lobby` task after it,
+// on the room's alarm once the call has answered, and again until the lobby hears it, so a lobby
+// that cannot be reached fails no post and misses no change. `runAfter` marks the task before the
+// change and again after it, so a crash at any point leaves the task to the alarm.
+export const layerActivity = Layer.effect(Activity)(
+  Effect.map(ActionDurableObject.Tasks, (tasks) =>
+    Activity.of({ changing: (change) => tasks.runAfter("lobby", change) })
+  )
+);
+```
+
+Why no stub is held, when one breaks and when a call may be repeated are on `ActionDurableObject.client`. `RpcClient.make` requires a `Scope` natively, so no client without one is offered. Where a Worker builds a client, as each request or once as the module loads, and why one built lazily inside a request strands, are on `ActionDurableObject.layerStubClient`'s gotchas: chat-rooms' `worker.ts` builds its handler as the module loads. In a Durable Object, `make` and `handlers` run every Effect under the scheduler that does not strand it, as `handlers` says.
+
+A Worker's entrypoint that is no Effect program, such as a `WorkerEntrypoint` method or a queue consumer, runs each call as its own program. chat-rooms' `RoomsEntrypoint`, which `worker.ts` exports, serves the rooms' activity to another Worker:
+
+```ts example=chat-rooms/src/rooms-entrypoint.ts
+import { WorkerEntrypoint } from "cloudflare:workers";
+import { Effect, Schema } from "effect";
+
+import { RoomName } from "./chat/Chat.js";
+import { LobbyHost } from "./lobby/host.js";
+import { layerLobbyHost } from "./platform/lobby-stubs.js";
+
+const decodeRoom = Schema.decodeUnknownEffect(RoomName);
+
+// The rooms' activity for another Worker, over a service binding to this one's `RoomsEntrypoint`,
+// which worker.ts exports, as the lobby keeps it. A method of a `WorkerEntrypoint` is no Effect
+// program, so each call runs as one, given the lobby's Layer: its client is built in the request
+// that uses it and closed with it, which costs no I/O. Why a client kept across requests strands
+// is on `ActionDurableObject.layerStubClient`.
+export class RoomsEntrypoint extends WorkerEntrypoint {
+  // The calling Worker is another deployment, so its room is checked as any input is: an unknown
+  // room rejects the call with the schema's error, as a lobby that cannot be reached rejects it
+  // with the defect lobby-stubs.ts makes of it.
+  async latestAt(room: string) {
+    return await Effect.runPromise(
+      Effect.flatMap(decodeRoom(room), (name) =>
+        LobbyHost.use((lobby) =>
+          Effect.map(
+            lobby.previews,
+            (previews) =>
+              previews.find((preview) => preview.room === name)?.latestAt ??
+              null
+          )
+        )
+      ).pipe(Effect.provide(layerLobbyHost))
+    );
+  }
+}
+```
+
+## Tell another object of a change
+
+An object telling another of its changes, as a room tells the lobby, does it as a task: give `make` or `handlers` `tasks`, a name for each Effect, and wrap each change in `ActionDurableObject.Tasks`' `runAfter`, as `layerActivity` above does. The task is marked in the object's storage before the change and again after it, and the object's alarm runs it once the call has answered, so one that fails, or that an eviction or a crash cuts off, the change's own included, runs again until it succeeds; the caller never fails with it, and a caller reading the object told at once may find it not yet told. A task reads what it sends as it runs, so one run covers every change before it, and the object told ignores what it already holds, as the lobby's `record` does. `worker.ts` gives the room's class `tasks: { lobby: tellLobby }`. What a run marks, and when it runs again, are on `ActionDurableObject.Tasks`.
+
+## Name the object in its errors
+
+An object reached by `getByName` knows its name, `ActionDurableObject.name`. Make it a startup service, decoded once as the instance builds, as chat-rooms' [worker.ts](../examples/chat-rooms/src/worker.ts) makes `Room`, and build each error from it in the handler, with nothing more from the caller.
+
+An object reached by `get(idFromString(id))` has no name: its caller sends the key in the payload, for the error to name.
+
+## Call an object's routes
+
+For the object's routes, `ActionHttp.client`, `ActionMcp.client`, or `ActionRpc.client` over `RpcClient.layerProtocolHttp`, give the client `layerHttpClient(stub)`: every request goes to the object's `fetch` in place of the network, as the example's tests call the Worker ([chat-rooms/test/worker.test.ts](../examples/chat-rooms/test/worker.test.ts)). Its URL and credentials are on `ActionDurableObject.layerHttpClient`. To pass a page's request on, forward the `Request` itself, as `worker.ts` does.

package/docs/ActionDurableObject-testing.md

@@ -0,0 +1,35 @@
+# ActionDurableObject: testing and deploying
+
+An object's tests run inside the Workers runtime, on the Worker its Wrangler configuration describes. Read [ActionDurableObject.md](ActionDurableObject.md) first. A message the library throws says its fix; for workerd's, a compiler diagnostic or Effect's own error, search [ActionDurableObject-failures.md](ActionDurableObject-failures.md).
+
+## Test on the Workers runtime
+
+Run the tests inside the runtime with `@cloudflare/vitest-plugin`, on the Worker the Wrangler configuration describes:
+
+```ts example=chat-rooms/vite.config.ts
+import { cloudflareTest } from "@cloudflare/vitest-plugin";
+import { defineConfig } from "vite-plus";
+
+// Its tests run inside the Workers runtime, on the Worker wrangler.jsonc describes.
+export default defineConfig({
+  plugins: [
+    cloudflareTest({
+      wrangler: { configPath: "./wrangler.jsonc" },
+    }),
+  ],
+  test: {
+    include: ["test/**/*.test.ts"],
+    // Why: under @cloudflare/vitest-plugin 1.4.4, the warm-module response for a later file in a
+    // pool slot can exceed what the runner's control socket accepts, 41 MB in 709 entries
+    // measured on chat-rooms, which closes it with 1009 and loses the file as "Worker exited
+    // unexpectedly"; two small files alone did not trigger it.
+    fsModuleCache: false,
+  },
+});
+```
+
+From `cloudflare:test`, `evictDurableObject(stub)` evicts an instance as hibernation does, its sockets staying open, the runtime runs an alarm set in the past at once, which chat-rooms' `test/worker.test.ts` waits for, and `runInDurableObject(stub, fn)` reads or changes the object's storage directly. Call the Worker as a deployment would with `layerHttpClient(exports.default)`, and open a socket by upgrading through its `fetch`, handing `response.webSocket` to `Socket.fromWebSocket` under `RpcClient.layerProtocolSocket` ([chat-rooms/test/support/socket.ts](../examples/chat-rooms/test/support/socket.ts), [chat-rooms/test/worker.test.ts](../examples/chat-rooms/test/worker.test.ts)). The core's `Testing.layer` serves the same routes in memory, but cannot upgrade a socket. Under **celld**, Deno's self-hosted Durable Object runtime, `CELLD_IDLE_EVICT_S` is the equivalent of `evictDurableObject`: the idle seconds after which it evicts an object.
+
+## Deploy
+
+workerd, Cloudflare's runtime, serves an object's sockets under any `compatibility_date`. celld 0.6.2 differs from it twice, each difference a gotcha of the declaration it touches: a socket's upgrade headers after an eviction, on `ActionDurableObject.layerWebSocket`, and an alarm set on a class without an `alarm` method, on `ActionDurableObject.handlers`. What an eviction loses is on `ActionDurableObject.handlers`.

package/docs/ActionDurableObject.md

@@ -0,0 +1,235 @@
+# ActionDurableObject
+
+Actions served from a Cloudflare Durable Object. A **Durable Object** is a class a Worker's Wrangler configuration binds, with one **object** per id or name, running in one place at a time with its own storage. The runtime constructs an **instance** of the class for an object's first event, **evicts** it when idle, and constructs another for the next. An object serves the routes the core serves elsewhere, Effect RPC on WebSockets the runtime holds open while the object **hibernates**, evicted with its sockets kept, rpcs over its stub, and an alarm. Reach for it when state belongs to one thing, such as a room, a document or a tenant, and its callers should meet in one place.
+
+Import `@gjermundgaraba/effect-actions-cloudflare/ActionDurableObject`. A message the library throws says its fix; for workerd's, a compiler diagnostic or Effect's own error, search [ActionDurableObject-failures.md](ActionDurableObject-failures.md). For one symbol, `grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions-cloudflare/dist/`: each declaration's JSDoc carries its rules and gotchas, and this page only what an example cannot show. Events are on [ActionDurableObject-events.md](ActionDurableObject-events.md), calls over the stub on [ActionDurableObject-stub.md](ActionDurableObject-stub.md), tests and runtimes on [ActionDurableObject-testing.md](ActionDurableObject-testing.md), and a class that cannot extend `make`'s on [ActionDurableObject-own-class.md](ActionDurableObject-own-class.md).
+
+## Serve actions from an object
+
+Give `make` the routes, as the core's surfaces build them, and their startup services, and export the class it returns, or one extending it, under the name the Wrangler configuration binds. The entrypoint holds the room's class beside the Worker's own `fetch`:
+
+```ts example=chat-rooms/src/worker.ts
+import * as ActionDurableObject from "@gjermundgaraba/effect-actions-cloudflare/ActionDurableObject";
+import { Effect, Layer, Schema } from "effect";
+import { HttpRouter, HttpServer } from "effect/http";
+
+import { Activity } from "./chat/activity.js";
+import { RoomName } from "./chat/Chat.js";
+import { Room } from "./chat/room.js";
+import { MessageStore } from "./chat/store.js";
+import { layerKvPreviews } from "./platform/kv-previews.js";
+import {
+  layerActivity,
+  layerLobbyHost,
+  tellLobby,
+} from "./platform/lobby-stubs.js";
+import { layerSql } from "./platform/sql-store.js";
+import {
+  lobbyCalls,
+  lobbyRoutes,
+  roomRoutes,
+  rooms,
+  workerRoutes,
+} from "./routes.js";
+
+// The rooms for another Worker, over a service binding: a named entrypoint of this one.
+export { RoomsEntrypoint } from "./rooms-entrypoint.js";
+
+// Entrypoint, Wrangler's `main`: the composition root of the Worker and of every object. It
+// chooses the stores, the room and the stubs, and routes each request.
+
+const decodeRoom = Schema.decodeUnknownEffect(RoomName);
+
+// A room's Durable Object, bound as CHAT_ROOM in wrangler.jsonc under this export's name. Each
+// instance builds its services, the store, the room and its activity, then its routes, as it is
+// constructed, again after every eviction. The room is the name the Worker reached the object by,
+// `getByName(room)`, decoded once there: `ActionDurableObject.name` dies for an object reached by
+// an id, and the build fails for a name `RoomName` does not list, each a bug in the Worker. Given
+// `rooms`, it refuses a call or a watch whose input names another room. Its `lobby` task tells
+// the lobby of each change, on the alarm until the lobby hears. The alarm expires old messages
+// and tells the lobby, as an expired message can be the room's latest.
+export class ChatRoom extends ActionDurableObject.make({
+  placed: rooms,
+  services: () =>
+    Layer.mergeAll(layerSql, layerActivity).pipe(
+      Layer.provideMerge(
+        Layer.effect(Room)(Effect.flatMap(ActionDurableObject.name, decodeRoom))
+      )
+    ),
+  routes: roomRoutes,
+  tasks: { lobby: tellLobby },
+  alarm: () =>
+    Activity.use((activity) =>
+      activity.changing(MessageStore.use((store) => store.expire))
+    ),
+}) {}
+
+// The lobby's Durable Object, bound as CHAT_LOBBY: one for the Worker, named `lobby`, keeping
+// every room's preview, which each room tells it of and its pages follow.
+export class ChatLobby extends ActionDurableObject.make({
+  services: () => layerKvPreviews,
+  routes: lobbyRoutes,
+  calls: lobbyCalls,
+}) {}
+
+// The Worker's own handler, built once, when the module loads, which keeps the lobby's client
+// from stranding as `ActionDurableObject.layerStubClient`'s gotchas say: building it does no I/O,
+// which a Worker refuses outside a request. `toWebHandler` reads no `MaxBodySize`, so the
+// platform limits request bodies.
+const served = HttpRouter.toWebHandler(
+  workerRoutes.pipe(
+    Layer.provide(layerLobbyHost),
+    Layer.provide(HttpServer.layerServices)
+  )
+);
+
+const isRoomName = Schema.is(RoomName);
+
+// A page's socket, `/rooms/<room>/rpc` or `/lobby/rpc`, is its object's `/rpc`: forwarding the
+// request forwards its upgrade, and the object answers it. Everything else is the Worker's own,
+// the rooms' calls among them, which it sends on to each room's object itself.
+export default {
+  async fetch(request: Request, env: Cloudflare.Env) {
+    const url = new URL(request.url);
+
+    const room =
+      /^\/rooms\/(?<room>[^/]+)\/rpc$/u.exec(url.pathname)?.groups?.room ?? "";
+
+    if (url.pathname === "/lobby/rpc" || isRoomName(room)) {
+      url.pathname = "/rpc";
+
+      const object = isRoomName(room)
+        ? env.CHAT_ROOM.getByName(room)
+        : env.CHAT_LOBBY.getByName("lobby");
+
+      return await object.fetch(new Request(url, request));
+    }
+
+    return await served.handler(request);
+  },
+} satisfies ExportedHandler<Cloudflare.Env>;
+```
+
+[chat-rooms/wrangler.jsonc](../examples/chat-rooms/wrangler.jsonc) binds each class with a SQLite migration. The rules of each option, when it builds and what it may require, are on `ActionDurableObject.Options`; what an instance builds, and when again, on `ActionDurableObject.handlers`; the class itself on `ActionDurableObject.make`, whose `services` is a function of the instance's `env`, `() => layer` for services reading none.
+
+- A service read from the object is a Layer requiring `State`: a store over its SQLite database ([chat-rooms/src/platform/sql-store.ts](../examples/chat-rooms/src/platform/sql-store.ts)), or what the object is, such as its name, `ActionDurableObject.name`, the room in `worker.ts` above.
+- An authorizer that depends on the object, such as on its room, yields that startup service once, when it is built ([chat-rooms/src/chat/authorize.ts](../examples/chat-rooms/src/chat/authorize.ts)).
+- A class extending the one `make` returns overrides only the handlers it has reason to write, and reaches `make`'s with `super`; a socket it accepts itself is its own to answer.
+
+## Serve rpcs over hibernating WebSockets
+
+Give `ActionRpc.layer` the protocol `layerWebSocket` makes, at a path of the object's, beside the JSON routes in one routes Layer:
+
+```ts example=chat-rooms/src/routes.ts
+import * as ActionDurableObject from "@gjermundgaraba/effect-actions-cloudflare/ActionDurableObject";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import { env } from "cloudflare:workers";
+import { Layer } from "effect";
+import { RpcServer } from "effect/rpc";
+
+import { LobbyHttp, RoomHttp } from "./Api.js";
+import { messageEvents } from "./chat/events.js";
+import { messages } from "./chat/handlers.js";
+import { Login } from "./identity/Identity.js";
+import { authenticate } from "./identity/verifier.js";
+import { LobbyCalls } from "./lobby/Calls.js";
+import { previewEvents } from "./lobby/events.js";
+import { calls as lobbyHandlers, lobby } from "./lobby/handlers.js";
+import {
+  LobbyRpc,
+  protocolVersion,
+  RoomRpc,
+  unsupportedProtocol,
+} from "./Rpc.js";
+
+const room = [messages, messageEvents];
+
+const byRoom = (input: { readonly room: string }) => input.room;
+
+// Where each room's calls and watches are served: in the room's object, the one each contract's
+// key names. worker.ts gives it to the room's class, which then refuses an input naming another
+// room, on its socket too; the Worker serves it below.
+export const rooms = ActionDurableObject.placed(RoomHttp, {
+  readMessages: byRoom,
+  postMessage: byRoom,
+  deleteMessage: byRoom,
+  "message.posted": byRoom,
+});
+
+// One socket route for each object's pages, refusing a page of another version.
+const pageSocket = ActionDurableObject.layerWebSocket({
+  path: "/rpc",
+  protocol: { version: protocolVersion, code: unsupportedProtocol },
+});
+
+// What a room's object serves. Its rpcs on WebSockets the runtime holds while the object
+// hibernates: a socket keeps the token its upgrade request carried, and each message is
+// authenticated with it, or with the message's own. The socket's route refuses a page naming
+// another version in its URL, `?protocol=<n>` as browser.ts sends it, with a close code the page's
+// client reads as `SocketCloseError` and stops connecting again at, not a 403, which a browser
+// reports as a bare 1006 its page connects again after. Its JSON routes, where the Worker sends
+// each call and watch on, the token with it: the object authenticates it again, and authorizes.
+// It requires `MessageStore`, `Room` and `Activity` at startup: worker.ts chooses them.
+export const roomRoutes = Layer.mergeAll(
+  ActionRpc.layer(RoomRpc, room).pipe(Layer.provide(pageSocket)),
+  ActionHttp.layer(RoomHttp, room)
+).pipe(Layer.provide(authenticate));
+
+// What the lobby's object serves: `PreviewsChanged` on its pages' sockets, a socket a page
+// signed out opens too, as nothing on it is protected. It requires `PreviewStore` at startup.
+export const lobbyRoutes = ActionRpc.layer(LobbyRpc, [previewEvents]).pipe(
+  Layer.provide(pageSocket)
+);
+
+// What the lobby's object serves over its stub: its own calls, on Effect's own RpcServer, for
+// the rooms and the Worker, which call them with Cloudflare's own RPC. It requires `PreviewStore`
+// at startup.
+export const lobbyCalls = RpcServer.layer(LobbyCalls).pipe(
+  Layer.provide(lobbyHandlers)
+);
+
+// The rooms as the Worker serves them, each call sent on to its room's object. The room is read
+// from `env` as each call is sent.
+const inRooms = ActionDurableObject.reaching(rooms, () => env.CHAT_ROOM);
+
+// What the Worker serves: the rooms' JSON routes and `previews`, which it asks the lobby's object
+// for, at `/api`, and all of them at `/mcp`, the actions as tools and `MessagePosted` as an MCP
+// event, so one agent's connection reaches every room. Nothing in a Worker outlives a request, so
+// the endpoint is request scoped: MCP 2026-07-28 alone, and events by `events/poll`, a poll every
+// 30 seconds as events.ts asks. The Worker authenticates each call, and the room's object again.
+// It requires `LobbyHost`.
+export const workerRoutes = Layer.mergeAll(
+  ActionHttp.layer(LobbyHttp, lobby),
+  ActionHttp.layer(RoomHttp, inRooms),
+  ActionMcp.layerHttp([lobby, ...inRooms], {
+    name: "chat-rooms",
+    version: "1.0.0",
+    authentication: Login,
+    requestScoped: true,
+  })
+).pipe(Layer.provide(authenticate));
+```
+
+What a socket keeps across hibernation, how each message authenticates, and what the runtime answers itself are on `ActionDurableObject.layerWebSocket`. Its `protocol` option refuses a page naming another version of the rpcs in its URL with a close code the page's client reads, as a browser cannot read a refused upgrade's status; the page's client stops connecting at that code given the core's `ActionRpc.reconnectUntil` as its `retryPolicy`. Router middleware provided to it runs for the upgrade alone, and refuses one by any other judge, such as a foreign `Origin`, with `ActionDurableObject.refuseUpgrade`. A page's client speaks JSON over `RpcClient.layerProtocolSocket` and `Socket.layerWebSocket(url)`, its token on each message ([chat-rooms/src/browser.ts](../examples/chat-rooms/src/browser.ts)), and the Worker forwards a page's upgrade to the room's object by forwarding its `Request`, as `worker.ts` does above.
+
+## Follow an event
+
+List an event's implementation beside the actions in `ActionRpc.layer`, as `routes.ts` above does, and a page watches it on its socket, an agent over MCP or by webhook: [ActionDurableObject-events.md](ActionDurableObject-events.md).
+
+## Serve the objects' actions from the Worker
+
+Give each of a binding's contracts a key of its input, `rooms` in `routes.ts` above, and the Worker serves them on any surface, each call sent on to the object the key names, which refuses one naming another: [ActionDurableObject-placement.md](ActionDurableObject-placement.md).
+
+## Run an alarm
+
+Give `make` an `alarm`, and set when it runs from a handler or a store with the `Alarm` service, which keeps the earliest time it is given: the room's store sets it for each message's expiry as it is posted and, each run, for the oldest left ([chat-rooms/src/platform/sql-store.ts](../examples/chat-rooms/src/platform/sql-store.ts)), and `worker.ts` above gives the alarm the store the routes read. How it runs, and how a failure is retried, are on `ActionDurableObject.Options`' `alarm`; how to postpone it, and why `State`'s `storage.setAlarm` is not the way, on `ActionDurableObject.Alarm`.
+
+## Call an object from a Worker
+
+Call its `calls` with `client`, the declared errors typed, and its routes with the core's clients over `layerHttpClient(stub)`: [ActionDurableObject-stub.md](ActionDurableObject-stub.md).
+
+## Test and deploy
+
+Test an object on the Workers runtime, and what differs between runtimes: [ActionDurableObject-testing.md](ActionDurableObject-testing.md).

package/docs/README.md

@@ -0,0 +1,28 @@
+# effect-actions-cloudflare
+
+`@gjermundgaraba/effect-actions-cloudflare` serves Effect RPC from Cloudflare Durable Objects, over WebSockets the runtime holds while the object hibernates: any plain `RpcGroup`, on Effect's own `RpcServer`, with no action at all. Actions are the option: the routes `ActionHttp.layer`, `ActionRpc.layer` and `ActionMcp.layerHttp` serve elsewhere, in an object, its events kept in its storage and followed over its sockets, over MCP or by webhook. A Worker, or another object, calls an object's rpcs over its **stub**, the handle `getByName(name)` gives, with Cloudflare's own RPC, or its routes with the core's own clients.
+
+These pages cover what this package adds. Everything else, contracts, implementations, authentication and each surface, is in the core package's docs, at `node_modules/@gjermundgaraba/effect-actions/docs/`: read its `docs/README.md` first, then its `docs/Action.md`, and the page of each surface you serve.
+
+## How to read these pages
+
+**Arriving with an error?** A message the library throws says its fix; for any other, step 4.
+
+1. **Open one page per tool call, with your file-reading tool.** Pages are kept small to reduce truncation; if an output says it was truncated, read that page again alone.
+2. **Start from [chat-rooms](../examples/chat-rooms/)**, the one example: its README has a layout tree and a "Where to look" table naming the file for each thing, and its comments carry the traps it shows.
+3. **Read [ActionDurableObject.md](ActionDurableObject.md) completely**, then the page of each task you have ([Pages](#pages)), and the example files their sections link.
+4. **For workerd's, a compiler diagnostic or Effect's own error, search [ActionDurableObject-failures.md](ActionDurableObject-failures.md)** for a fragment of the message without quotes, then the core's `*-failures.md` pages.
+
+Where things are, in a project that installs the package: these pages in `node_modules/@gjermundgaraba/effect-actions-cloudflare/docs/`, the example in `examples/` beside them, and the declarations with their JSDoc, the reference for rules and gotchas, under `dist/`. Install it beside the core, at the same version: the two are released together. Its declarations name the Workers runtime's types, from `wrangler types` or `@cloudflare/workers-types`.
+
+## Pages
+
+| Read | When you need to |
+| --- | --- |
+| [ActionDurableObject.md](ActionDurableObject.md) | serve an `RpcGroup`, or actions, from an object, over hibernating WebSockets and JSON; run its alarm |
+| [ActionDurableObject-events.md](ActionDurableObject-events.md) | follow an event over an object's socket, serve actions and events over MCP, deliver events by webhook |
+| [ActionDurableObject-stub.md](ActionDurableObject-stub.md) | serve an object's own API over its stub, call it from a Worker, tell another object of a change until it hears, name the object in errors, call its routes |
+| [ActionDurableObject-placement.md](ActionDurableObject-placement.md) | serve objects' actions and events from the Worker, each call reaching the object its input names |
+| [ActionDurableObject-own-class.md](ActionDurableObject-own-class.md) | serve them from a class that cannot extend `make`'s, delegating to `handlers` |
+| [ActionDurableObject-testing.md](ActionDurableObject-testing.md) | test an object on the Workers runtime, evict it, run its alarm in a test; what differs between workerd and celld |
+| [ActionDurableObject-failures.md](ActionDurableObject-failures.md) | find what workerd's, the compiler's or Effect's message means, and the fix |

package/examples/chat-rooms/README.md

@@ -0,0 +1,97 @@
+# chat-rooms
+
+Chat rooms on Cloudflare: each room is one Durable Object, holding its messages in its own SQLite database and its pages' WebSockets while it hibernates. Members read, post and delete messages in the rooms they belong to over the room's socket, or the Worker's JSON routes and MCP endpoint, which reach every room. A page follows its room through an event, `MessagePosted`, its subscription kept while the object hibernates; an agent polls it over MCP. A message expires a day after it was posted, when the room's alarm runs. A lobby, one more object, keeps when each room was last active: each room tells it its latest activity over its stub, with Cloudflare's own RPC, and a page follows it, every preview whole at each change. The Worker in front serves the rooms' JSON routes and MCP endpoint itself, sending each call on to the room its input names, serves the previews, asking the lobby, and forwards a page's socket, `/rooms/<room>/rpc`, to the room's object and `/lobby/rpc` to the lobby's.
+
+Start here to serve actions from Durable Objects. The same chat on a long-lived server is live-rpc, in the core package's `examples/`.
+
+## Run it
+
+From the repository root, after `vp install`:
+
+```sh
+vp test packages/cloudflare/examples/chat-rooms
+```
+
+The tests run inside the Workers runtime, on the Worker `wrangler.jsonc` describes, with `@cloudflare/vitest-plugin`. `browser.ts` is imported by a page, not run. The tokens are fixed names (`ada`, `grace`): replace them before deploying anything.
+
+In a project that installs the package, copy this directory out of `node_modules/@gjermundgaraba/effect-actions-cloudflare/examples/`. It imports both packages by name and needs `effect` beside them, `@cloudflare/workers-types` for its `tsconfig.json`, and `wrangler` to serve it (`wrangler dev`, `wrangler deploy` in its directory). Its tests need `vitest`, `@effect/vitest` and `@cloudflare/vitest-plugin`; `vite.config.ts` imports `defineConfig` from the repository's toolchain, `vite-plus`, which is Vitest's `vitest/config` elsewhere.
+
+## When you copy this
+
+Each trap is a comment in the file named.
+
+- **A page sends its token on each message**, as a browser WebSocket sets no header on its upgrade: `src/browser.ts`; `test/worker.test.ts` connects both ways.
+- **The room is the object's name**, and only a room `RoomName` lists is reached: `src/chat/Chat.ts`, `src/worker.ts`.
+- **The Worker serves every room, each room answers**, through the placement `rooms`: `src/routes.ts`.
+- **A page reads, then watches from the last message it holds**: `src/browser.ts`, `src/chat/events.ts`.
+- **`postMessage` notifies `MessagePosted`**: `src/chat/handlers.ts`, `src/chat/events.ts`.
+- **Objects call each other over their stubs, not their `fetch`**: `src/lobby/Calls.ts`, `src/platform/lobby-stubs.ts`.
+- **A room tells the lobby its latest activity, and the lobby notifies**: `tellLobby` in `src/platform/lobby-stubs.ts`, `src/lobby/handlers.ts`.
+- **The lobby's event is a whole value**, followed with no read first: `src/lobby/events.ts`, `src/browser.ts`.
+
+## Layout
+
+```text
+src/
+├── chat/
+│   ├── Chat.ts        contract: the rooms, the message, its errors, the room's actions
+│   ├── room.ts        Room, the room an instance holds: a startup service
+│   ├── activity.ts    Activity, where a room says it changed: the lobby
+│   ├── store.ts       MessageStore, the service the handlers call
+│   ├── events.ts      MessagePosted's check source, read from the store
+│   ├── authorize.ts   the one authorization rule: a member of the instance's room
+│   └── handlers.ts    Action.implement: contract to store
+├── identity/
+│   ├── Identity.ts    contract: CurrentMember and the Login descriptor
+│   ├── members.ts     the demo members
+│   └── verifier.ts    Authentication.layer: tokens to members, server only
+├── lobby/
+│   ├── Lobby.ts       contract: the previews, the Worker's action and the lobby's event
+│   ├── Calls.ts       the lobby's own API over its stub, for the rooms and the Worker
+│   ├── store.ts       PreviewStore, the previews the lobby keeps
+│   ├── events.ts      PreviewsChanged's current source, the whole value
+│   ├── host.ts        LobbyHost, the lobby's object as the Worker reaches it
+│   └── handlers.ts    the Worker's action, and the lobby's calls recording a room's activity
+├── platform/
+│   ├── sql-store.ts   MessageStore over the object's SQLite database, and its alarm
+│   ├── kv-previews.ts PreviewStore over the lobby's synchronous key-value storage
+│   └── lobby-stubs.ts LobbyHost, Activity and the room's task over the lobby's stub
+├── Api.ts             the JSON bindings: a room's and the lobby's
+├── Rpc.ts             the RPC bindings: a room's actions and event, and the lobby's event
+├── routes.ts          each object's routes, the lobby's calls over its stub, the Worker's routes
+├── worker.ts          entrypoint: the room's and the lobby's classes and the Worker's fetch
+├── rooms-entrypoint.ts  the rooms' activity for another Worker, a program per call
+├── browser.ts         client module: a page's socket, its room and the lobby
+└── env.d.ts           the bindings' types, as `wrangler types` writes them
+test/
+├── platform/          the store against a real object's database
+├── support/           a page's socket, upgraded through the Worker
+└── worker.test.ts     through the Worker's fetch: sockets, JSON routes, MCP, the lobby, the alarm
+```
+
+- **An instance is built per wake.** The runtime evicts an idle object and constructs a new instance for its next event, which builds its services and routes again: anything in memory is gone, and `layerSql` creates its table if it is not there. The database and the sockets stay.
+- **The room is a startup service, the caller is not.** An instance holds one room, so the authorizer yields `Room` once, when it is built, as a builder yields a store. `CurrentMember` comes from authentication, per message.
+- **The entrypoint chooses everything.** `worker.ts` gives a room's object the SQLite store, the room, its name, and the lobby's stub as its services, which an instance builds once for the routes, the task and the alarm; it gives the lobby's object its store, and the Worker's handler the lobby's stub.
+- **The Worker forwards a socket, the object answers.** Forwarding a request forwards its upgrade, so the Worker passes a page's socket request to the room's object unchanged but its path; every other call it serves itself, through the placement.
+
+## Where to look
+
+| To see | Read |
+| --- | --- |
+| A Durable Object class serving actions, and its alarm | `src/worker.ts` |
+| Rpcs on hibernating WebSockets beside JSON routes, in one object | `src/routes.ts` |
+| An authorizer that yields the instance's room once, when it is built | `src/chat/authorize.ts`, `src/chat/handlers.ts` |
+| A store over the object's SQLite database, setting its alarm with `Alarm` | `src/platform/sql-store.ts` |
+| A startup service read from the object's state, its name | `src/worker.ts` |
+| A Worker calling an object's own API over its stub, with Cloudflare's RPC | `src/lobby/Calls.ts`, `src/routes.ts`, `src/platform/lobby-stubs.ts` |
+| An object telling another of a change, which notifies its own event | `src/platform/lobby-stubs.ts`, `src/lobby/handlers.ts` |
+| An event sent as a whole value, followed with no read first | `src/lobby/events.ts`, `src/browser.ts`, `test/worker.test.ts` |
+| Routing requests and upgrades from the Worker to an object | `src/worker.ts` |
+| A page's socket client, its token on each message | `src/browser.ts` |
+| An event a page watches on its socket, kept while the object hibernates | `src/chat/events.ts`, `src/browser.ts`, `test/worker.test.ts` |
+| A Worker serving every room's actions and event, each in the room it names | `src/routes.ts`, `src/worker.ts`, `test/worker.test.ts` |
+| One MCP endpoint for every room, its event polled | `src/routes.ts`, `test/worker.test.ts` |
+| A room refusing a call that names another room | `src/chat/Chat.ts`, `src/worker.ts`, `test/worker.test.ts` |
+| Refusing a page of another version with a close code it reads | `src/routes.ts`, `src/browser.ts` |
+| Testing on the Workers runtime: an eviction, the alarm, the database | `test/worker.test.ts`, `test/platform/` |
+| A socket that keeps the token of its upgrade request | `test/worker.test.ts` |

package/examples/chat-rooms/src/Api.ts

@@ -0,0 +1,14 @@
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+
+import { MessagePosted, Messages } from "./chat/Chat.js";
+import { Login } from "./identity/Identity.js";
+import { Previews } from "./lobby/Lobby.js";
+
+// The rooms' JSON routes, at `/api/<action>` and `/api/events/<name>`: the Worker's, which a
+// client without a socket calls, and each room's object's, where the Worker sends each call on.
+export const RoomHttp = ActionHttp.make([...Messages, MessagePosted], {
+  authentication: Login,
+});
+
+// The Worker's own JSON routes.
+export const LobbyHttp = ActionHttp.make([Previews]);

package/examples/chat-rooms/src/Rpc.ts

@@ -0,0 +1,22 @@
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+
+import { MessagePosted, Messages } from "./chat/Chat.js";
+import { Login } from "./identity/Identity.js";
+import { PreviewsChanged } from "./lobby/Lobby.js";
+
+// A room's rpcs and its event, on the socket a page keeps open to its object. Plain data: the
+// object and a browser page both import it.
+export const RoomRpc = ActionRpc.make([...Messages, MessagePosted], {
+  authentication: Login,
+});
+
+// The lobby's event, on the socket a page keeps open to the lobby's object: public, so a page
+// signed out follows it, and refused at another version as a room's socket is.
+export const LobbyRpc = ActionRpc.make([PreviewsChanged]);
+
+// The version of these rpcs a page was built with, which it names in its socket's URL, and the
+// close code an object answers a page naming another with: raise the version when a change would
+// break a page still open from before a deployment.
+export const protocolVersion = "1";
+
+export const unsupportedProtocol = 4000;