@gjermundgaraba/effect-actions-cloudflare 0.22.0 → 0.23.0

package/dist/webhooks.mjs

@@ -4,12 +4,7 @@ import { Clock, Context, Deferred, Duration, Effect, Exit, Layer, Option, Schema
 import * as Webhook from "@gjermundgaraba/effect-actions/Webhook";
 import { KeyValueStore } from "effect/persistence";
 // src/durable/webhooks.ts
-/** The owner of the object's alarm times that end its long waits. */
 const clockOwner = "webhooks";
-/**
-* Where `layerWebhooks` keeps its subscriptions in the object's storage: every key of its store,
-* whatever layout `Webhook.layer`'s `persist` gives them, is under it.
-*/
 const webhookPrefix = "effect-actions/webhooks/";
 /**
 * The instance's long waits, which the object's alarm ends: `until(at)` waits until the alarm
@@ -17,13 +12,9 @@ const webhookPrefix = "effect-actions/webhooks/";
 * `make` provide it to the routes, over the instance's schedule, for `layerWebhooks`.
 */
 var Waits = class extends Context.Service()("effect-actions-cloudflare/ActionDurableObject/Waits") {};
-/**
-* The instance's `Waits`, their time set on `schedule`, the one its `alarm` handler runs, and
-* `wakeDue`, which that handler runs at their time.
-*/
 const makeWaits = (schedule) => {
 	const held = /* @__PURE__ */ new Set();
-	const armed = Semaphore.makeUnsafe(1).withPermits(1)(Effect.suspend(() => held.size === 0 ? schedule.clear(clockOwner) : schedule.set(clockOwner, Math.min(...[...held].map(({ at }) => at)))));
+	const armForEarliestWait = Semaphore.makeUnsafe(1).withPermits(1)(Effect.suspend(() => held.size === 0 ? schedule.clear(clockOwner) : schedule.set(clockOwner, Math.min(...[...held].map(({ at }) => at)))));
 	return {
 		waits: Waits.of({ until: (at) => Effect.suspend(() => {
 			const wait = {
@@ -31,25 +22,19 @@ const makeWaits = (schedule) => {
 				woken: Deferred.makeUnsafe()
 			};
 			held.add(wait);
-			return Effect.andThen(armed, Deferred.await(wait.woken)).pipe(Effect.ensuring(Effect.suspend(() => held.delete(wait) ? armed : Effect.void)));
+			return Effect.andThen(armForEarliestWait, Deferred.await(wait.woken)).pipe(Effect.ensuring(Effect.suspend(() => held.delete(wait) ? armForEarliestWait : Effect.void)));
 		}) }),
-		/** Ends each wait that is due, and sets the alarm for the next. */
 		wakeDue: Effect.gen(function* () {
 			const now = yield* Clock.currentTimeMillis;
 			for (const wait of held) if (wait.at <= now) {
 				held.delete(wait);
 				Deferred.doneUnsafe(wait.woken, Exit.void);
 			}
-			yield* armed;
+			yield* armForEarliestWait;
 		})
 	};
 };
-const timed = Duration.seconds(10);
-/**
-* The Clock the webhook layer runs on: a wait of 10 seconds or more waits on the object's alarm
-* and holds no timer, so the object may hibernate meanwhile; if the instance is evicted, the
-* alarm builds the next, which restores the subscriptions from storage.
-*/
+const alarmWaitThreshold = Duration.seconds(10);
 const alarmClock = (base, { until }) => ({
 	currentTimeMillisUnsafe: () => base.currentTimeMillisUnsafe(),
 	currentTimeMillis: base.currentTimeMillis,
@@ -57,7 +42,7 @@ const alarmClock = (base, { until }) => ({
 	currentTimeNanos: base.currentTimeNanos,
 	monotonicTimeNanosUnsafe: () => base.monotonicTimeNanosUnsafe(),
 	monotonicTimeNanos: base.monotonicTimeNanos,
-	sleep: (duration) => Duration.isLessThan(duration, timed) || !Duration.isFinite(duration) ? base.sleep(duration) : until(base.currentTimeMillisUnsafe() + Duration.toMillis(duration))
+	sleep: (duration) => Duration.isLessThan(duration, alarmWaitThreshold) || !Duration.isFinite(duration) ? base.sleep(duration) : until(base.currentTimeMillisUnsafe() + Duration.toMillis(duration))
 });
 const stringOf = Schema.decodeUnknownOption(Schema.String);
 const attempted = (method, key, run) => Effect.tryPromise({
@@ -70,7 +55,6 @@ const attempted = (method, key, run) => Effect.tryPromise({
 	})
 });
 const keyOf = (key) => `${webhookPrefix}${key}`;
-/** A `KeyValueStore` over the object's storage under `webhookPrefix`, every key of it there. */
 const storageStore = (storage) => {
 	const listed = attempted("list", void 0, async () => await storage.list({ prefix: webhookPrefix }));
 	return KeyValueStore.makeStringOnly({

package/docs/ActionDurableObject-events.md

@@ -14,19 +14,12 @@ import { authorize } from "./authorize.js";
 import { MessagePosted } from "./Chat.js";
 import { MessageStore } from "./store.js";
 
-// A cursor is the id of the last message a page holds, as `readMessages`' `after` is.
 const idOf = Schema.decodeUnknownOption(
   Schema.NumberFromString.pipe(Schema.check(Schema.isInt()))
 );
 
-// An agent polling over MCP asks again after `nextPoll`, 5 seconds by default: a request that
-// often keeps the object from the 10 idle seconds after which the runtime may hibernate it, so it
-// asks every 30 seconds, and an agent that needs a message sooner holds a stream open instead.
 const nextPoll = "30 seconds";
 
-// The room's messages as an event, read from the store that keeps them: a check source.
-// `postMessage` notifies after each post, so a page receives it at once: when an object reads a
-// check source, and what a write that does not notify misses, is on `ActionDurableObject.handlers`.
 export const messageEvents = Event.implement(
   MessagePosted,
   Effect.gen(function* () {
@@ -42,11 +35,6 @@ export const messageEvents = Event.implement(
             (id) => id >= 0 && id <= last
           );
 
-          // No cursor starts after the room's last message. One this room never gave, such as
-          // an id past its last from another copy of its database, is answered `truncated` from
-          // there: the page learns it missed messages, and reads them with `readMessages`. A
-          // message deleted or expired after a cursor is simply not read: the store keeps no
-          // record of either, so no gap marks it.
           if (Option.isNone(after)) {
             return {
               cursor: String(last),
@@ -89,7 +77,6 @@ import { LobbyHost } from "./host.js";
 import { Previews, PreviewsChanged } from "./Lobby.js";
 import { PreviewStore } from "./store.js";
 
-// The Worker's `previews`, as the lobby's object keeps them.
 export const lobby = Action.implement(
   Previews,
   Effect.map(
@@ -98,8 +85,6 @@ export const lobby = Action.implement(
   )
 );
 
-// The lobby's own API, in its object. A change notifies `PreviewsChanged`, which an object
-// outside this one could not do itself: its event is this object's.
 export const calls = LobbyCalls.toLayer(
   Effect.gen(function* () {
     const store = yield* PreviewStore;
@@ -125,11 +110,6 @@ import { Effect } from "effect";
 import { PreviewsChanged } from "./Lobby.js";
 import { PreviewStore } from "./store.js";
 
-// Every room's preview as one event, read from the lobby's store: a current source, for a value
-// small enough to send whole. A page watching is sent the previews as they are, then again after
-// each notify, which `roomChanged` makes after each change, so it needs no read before it and is
-// never sent each change it missed, which a whole value makes needless. The object keeps the
-// revision a page's cursor holds, so a page resuming at the latest is sent nothing.
 export const previewEvents = Event.implement(
   PreviewsChanged,
   Effect.map(PreviewStore, (store) => ({

package/docs/ActionDurableObject-failures.md

@@ -15,4 +15,4 @@ Messages the library does not own, workerd's, the compiler's and Effect's, and t
 - `Could not serialize object of type "<Class>". This type does not support serialization`, workerd's `DataCloneError`, as an `RpcClientError`'s cause: a value of the call, success, error or defect, is one structured clone refuses, such as a class instance in a `Schema.Unknown`; declare its schema, whose plain form clones, or die with an `Error`.
 - `Your Durable Object class must have an alarm() handler in order to call setAlarm()`, workerd's, from `storage.setAlarm`, which `Alarm.set` calls: the class delegating to `handlers` defines no `alarm`; delegate `handlers`' own, as `make`'s classes do, and on celld 0.6.2, Deno's self-hosted Durable Object runtime, which accepts the call and drops the alarm when it is due, an alarm that never runs means the same.
 - `The Workers runtime canceled this request because it detected that your Worker's code had hung and would never generate a response`, workerd's, from every call through a client kept across a Worker's requests, `client` or `RpcClient.make` over `layerStubClient`, or through a handler or runtime holding one: it was first built lazily inside a request that ended without waiting on I/O, succeeding or refused, whose timer would have started the client's own fiber; run each call as its own program, or share it built at module scope under Effect's sync scheduler, as `HttpRouter.toWebHandler`'s gotchas show, a `ManagedRuntime.make` there building only at its first run, as `ActionDurableObject.layerStubClient`'s gotchas say.
-- `RpcClientError` from every call over a stub, Effect's own error: the stub failed, its `reason.cause` the runtime's or the object's message; a stub an exception broke fails every later call with the same one, so call through `client`, or give `layerStubClient` a function, `() => stub`, either making a new stub for each call.
+- `RpcClientError` from every call over a stub, Effect's own error: the stub failed, its `reason.cause` the runtime's or the object's message; a stub an exception broke fails every later call with the same one, so call through `client` or `layerStubClient`, either making a new stub for each call from its function.

package/docs/ActionDurableObject-placement.md

@@ -13,13 +13,10 @@ 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]);
 ```
 
@@ -30,7 +27,7 @@ Then, as `routes.ts` on [ActionDurableObject.md](ActionDurableObject.md) does:
 - The class is given the placement as `make`'s `placed`, in `worker.ts`: the object then refuses `Forbidden`, on every surface, its socket and its stub included, a call or a watch whose key names another object, so a page's socket to one room cannot reach another.
 - The Worker serves `ActionDurableObject.reaching(rooms, () => env.CHAT_ROOM)` beside its own implementations, in `ActionHttp.layer` and `ActionMcp.layerHttp`, each call sent to the room's object with the caller's headers.
 
-The Worker authenticates each protected call as its own, and the object authenticates and authorizes it again, so both are given the verifier. A key's schema, `RoomName` in `Chat.ts`, is what keeps a caller from creating objects: an unknown room is `InvalidInput` before any object is reached. [chat-rooms/test/worker.test.ts](../examples/chat-rooms/test/worker.test.ts) reaches two rooms through one MCP connection and has a room refuse a call naming another.
+The Worker authenticates each protected call as its own, and the object authenticates and authorizes it again, so both are given the verifier. A key's schema, `DemoRoomName` in `Chat.ts`, is what keeps a caller from creating objects: an unknown room is `InvalidInput` before any object is reached. [chat-rooms/test/worker.test.ts](../examples/chat-rooms/test/worker.test.ts) reaches two rooms through one MCP connection and has a room refuse a call naming another.
 
 ## Serve them over MCP from the Worker
 

package/docs/ActionDurableObject-stub.md

@@ -12,11 +12,6 @@ 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) })
@@ -25,7 +20,7 @@ export const LobbyCalls = RpcGroup.make(
 
 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`.
+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
 
@@ -42,25 +37,14 @@ 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);
@@ -69,10 +53,6 @@ export const tellLobby = Effect.gen(function* () {
   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) })
@@ -88,21 +68,13 @@ A Worker's entrypoint that is no Effect program, such as a `WorkerEntrypoint` me
 import { WorkerEntrypoint } from "cloudflare:workers";
 import { Effect, Schema } from "effect";
 
-import { RoomName } from "./chat/Chat.js";
+import { DemoRoomName } from "./chat/Chat.js";
 import { LobbyHost } from "./lobby/host.js";
 import { layerLobbyHost } from "./platform/lobby-stubs.js";
 
-const decodeRoom = Schema.decodeUnknownEffect(RoomName);
+const decodeRoom = Schema.decodeUnknownEffect(DemoRoomName);
 
-// 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) =>

package/docs/ActionDurableObject-testing.md

@@ -10,7 +10,6 @@ Run the tests inside the runtime with `@cloudflare/vitest-plugin`, on the Worker
 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({
@@ -19,10 +18,6 @@ export default defineConfig({
   ],
   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,
   },
 });

package/docs/ActionDurableObject.md

@@ -14,7 +14,7 @@ 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 { DemoRoomName } from "./chat/Chat.js";
 import { Room } from "./chat/room.js";
 import { MessageStore } from "./chat/store.js";
 import { layerKvPreviews } from "./platform/kv-previews.js";
@@ -32,22 +32,10 @@ import {
   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(DemoRoomName);
 
-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: () =>
@@ -64,18 +52,12 @@ export class ChatRoom extends ActionDurableObject.make({
     ),
 }) {}
 
-// 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),
@@ -83,11 +65,8 @@ const served = HttpRouter.toWebHandler(
   )
 );
 
-const isRoomName = Schema.is(RoomName);
+const isRoomName = Schema.is(DemoRoomName);
 
-// 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);
@@ -148,9 +127,6 @@ 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,
@@ -158,48 +134,26 @@ export const rooms = ActionDurableObject.placed(RoomHttp, {
   "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),

package/docs/README.md

@@ -9,7 +9,7 @@ These pages cover what this package adds. Everything else, contracts, implementa
 **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.
+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 code and README 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.
 

package/examples/chat-rooms/README.md

@@ -18,10 +18,10 @@ In a project that installs the package, copy this directory out of `node_modules
 
 ## When you copy this
 
-Each trap is a comment in the file named.
+Each trap below is shown in the code of the files it names.
 
 - **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 room is the object's name**, and only a room `DemoRoomName` 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`.

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

@@ -4,11 +4,8 @@ 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

@@ -4,19 +4,12 @@ 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;

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

@@ -5,7 +5,7 @@ import { RpcClient, RpcSerialization } from "effect/rpc";
 import { Socket } from "effect/socket";
 
 import { MessagePosted } from "./chat/Chat.js";
-import type { RoomName } from "./chat/Chat.js";
+import type { DemoRoomName } from "./chat/Chat.js";
 import { PreviewsChanged } from "./lobby/Lobby.js";
 import {
   LobbyRpc,
@@ -14,17 +14,6 @@ import {
   unsupportedProtocol,
 } from "./Rpc.js";
 
-// Client module: what a web page imports. It holds the binding and nothing of the server.
-
-// Effect's own client protocol, one WebSocket to an object, speaking JSON: the socket's URL is
-// `wss://<host>/rooms/<room>/rpc` for a room and `wss://<host>/lobby/rpc` for the lobby, given the version of the rpcs the page was built
-// with. An object serving another closes the socket at once with `unsupportedProtocol`, which
-// fails every call and stream with a `SocketCloseError` of that code; `reconnectUntil` stops
-// the client there, which Effect's own policy would not, connecting again every five seconds,
-// each attempt waking the object: show "reload". The layer owns the socket, so provide it
-// once, around the page's whole program; a page provides `Socket.layerWebSocketConstructorGlobal`, the browser's own
-// WebSocket. The client pings every five seconds and the object's runtime answers, so a page
-// left open does not wake the object.
 export const connection = (url: string) =>
   RpcClient.layerProtocolSocket({
     retryPolicy: ActionRpc.reconnectUntil(unsupportedProtocol),
@@ -33,27 +22,18 @@ export const connection = (url: string) =>
     Layer.provide(RpcSerialization.layerJson)
   );
 
-// A room as a page uses it, over the socket to that room's object: each call names the room, as
-// every call of a room does, and the object refuses one naming another. A browser WebSocket sets
-// no header when it connects, so the token travels on each message; a client that can set headers
-// on the upgrade, such as a Worker or a native app, sends it once there, and the socket keeps it.
-export const openRoom = (room: RoomName, token: string) =>
+export const openRoom = (room: DemoRoomName, token: string) =>
   Effect.gen(function* () {
     const client = yield* ActionRpc.client(RoomRpc);
     const headers = { authorization: `Bearer ${token}` };
     const signedIn = RpcClient.withHeaders(headers);
 
     return {
-      // The room's messages after `after`, the id of the last one the page holds: 0 reads them
-      // all.
       read: (after: number) =>
         client.readMessages({ room, after }).pipe(
           signedIn,
           Effect.map(({ messages }) => messages)
         ),
-      // A post the socket lost, as the room's object restarted, fails with an `RpcClientError`,
-      // whether or not it reached the room: sent again with its `request`, made once for the
-      // message, it is posted once.
       post: (text: string) =>
         Effect.flatMap(
           Effect.sync(() => crypto.randomUUID()),
@@ -66,14 +46,6 @@ export const openRoom = (room: RoomName, token: string) =>
               })
             )
         ),
-      // Each message posted to the room after `after`, the id of the last one the page holds: a
-      // page opening the room reads it, then watches from the last id it read, so a post between
-      // the two is not lost. The room's object keeps the watch while it hibernates, and resumes it
-      // when it next wakes, authenticating its token again: a token that expired meanwhile ends
-      // the watch with `Unauthenticated`, so watch again with a fresh one. `watch` connects again
-      // after a drop and resumes from the last message it delivered; a `Gap` says some were
-      // missed, which the page reads with `read`. The headers go with the stream, as `signedIn`
-      // puts them on a call, and so with every request it sends again.
       messages: (after: number) =>
         client
           .watch(MessagePosted, { room }, { cursor: String(after) })
@@ -95,10 +67,6 @@ export const openRoom = (room: RoomName, token: string) =>
     };
   });
 
-// The lobby as a page follows it, signed in or not: every room's preview, first as it is, then
-// whole again at each change. A watch given no cursor starts with the previews, so the page reads
-// nothing first; after a drop it resumes from the last it received, and hears the previews again
-// only if they changed meanwhile. A `Gap` needs no read either: the next occurrence is whole.
 export const followLobby = Effect.map(ActionRpc.client(LobbyRpc), (client) =>
   client.watch(PreviewsChanged, {}).pipe(
     Stream.filter((received) => Predicate.isTagged(received, "Occurrence")),

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

@@ -4,15 +4,10 @@ import { Schema } from "effect";
 
 import { CurrentMember } from "../identity/Identity.js";
 
-// DEMO ONLY: the rooms, fixed. Each name is one Durable Object, which the Worker reaches only
-// for a name listed here, so no caller creates an object of its own. A real application keeps
-// its rooms in a store and checks a name there before it reaches `getByName`.
-export const RoomName = Schema.Literals(["general", "design"]);
+export const DemoRoomName = Schema.Literals(["general", "design"]);
 
-export type RoomName = typeof RoomName.Type;
+export type DemoRoomName = typeof DemoRoomName.Type;
 
-// A message's `id` counts up within its room, so a client asks for what came after the last
-// one it holds. `at` is when it was posted, in milliseconds: messages expire a day later.
 export const Message = Schema.Struct({
   id: Schema.Int,
   author: Schema.String,
@@ -22,8 +17,6 @@ export const Message = Schema.Struct({
 
 export type Message = typeof Message.Type;
 
-// A declared error is part of the contract: every client decodes it as this class. Its status is
-// for the JSON routes; an rpc carries none.
 export class MessageNotFound extends Schema.TaggedError<
   MessageNotFound,
   { readonly brand: unique symbol }
@@ -34,16 +27,10 @@ export class NotAuthor extends Schema.TaggedError<
   { readonly brand: unique symbol }
 >()("NotAuthor", { id: Schema.Int }, { httpApiStatus: 403 }) {}
 
-// Every call and watch of a room names it in its input: the Worker sends each on to the room's
-// object, and the object refuses an input naming another room, so a page's socket to one room
-// cannot reach another. Its schema is the room names, so an unknown room is `InvalidInput`
-// before any object is reached.
-const inRoom = { room: RoomName };
+const inRoom = { room: DemoRoomName };
 
 const signedIn = { caller: CurrentMember } as const;
 
-// Reads once: a page opening a room reads what is there, then watches `MessagePosted` below from
-// the last id it read.
 export const ReadMessages = Action.make("readMessages", {
   ...signedIn,
   description: "Read the room's messages after the given id; 0 reads them all.",
@@ -52,9 +39,6 @@ export const ReadMessages = Action.make("readMessages", {
   readOnly: true,
 });
 
-// `request` is the post's idempotency key: a page makes one at random for each message and
-// sends it again when it retries the post, and the room answers the repeat as it answered the
-// first, posting once. A model reads its description beside the tool, so it does the same.
 export const PostMessage = Action.make("postMessage", {
   ...signedIn,
   description: "Post a message to the room. It expires a day later.",
@@ -83,10 +67,6 @@ export const DeleteMessage = Action.make("deleteMessage", {
 
 export const Messages = [ReadMessages, PostMessage, DeleteMessage] as const;
 
-// Each message posted to the room, as it is posted: a page watches it on the socket it keeps
-// open to the room's object. Signed-in, so each watch authenticates and runs `authorize` as it
-// starts, and again each time the object wakes after hibernating, refused for a member outside
-// the room, or one whose token has expired meanwhile.
 export const MessagePosted = Event.make("message.posted", {
   description: "A message posted to the room.",
   input: inRoom,

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

@@ -1,11 +1,6 @@
 import { Context } from "effect";
 import type { Effect } from "effect";
 
-/**
- * Where a room says its latest activity may have changed: the lobby's object, which worker.ts
- * chooses. `changing` runs a change, then tells, answering as the change did: a post stands
- * whether the lobby hears of it or not.
- */
 export class Activity extends Context.Service<
   Activity,
   {

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

@@ -4,9 +4,6 @@ import { Effect } from "effect";
 import { CurrentMember } from "../identity/Identity.js";
 import { Room } from "./room.js";
 
-// The one rule: a member reads and writes only the rooms they belong to. It is built as
-// handlers are: this Effect runs once per instance and gets the room, a startup service; the
-// function it returns runs before every handler and reads the caller of that call.
 export const authorize = Effect.gen(function* () {
   const room = yield* Room;