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

package/dist/subscriptions.mjs

@@ -0,0 +1,104 @@
+import { deleted } from "./batches.mjs";
+import { RequestId, closeQuietly, groupTag, socketIdOf } from "./frames.mjs";
+import { Effect, Function, Match, Option, Predicate, Schema } from "effect";
+// src/durable/subscriptions.ts
+/** Where an object keeps its sockets' event subscriptions. */
+const keptPrefix = "effect-actions/subscription/";
+const Request = Schema.TaggedStruct("Request", {
+	id: RequestId,
+	tag: Schema.String,
+	headers: Schema.mutable(Schema.Array(Schema.mutable(Schema.Tuple([Schema.String, Schema.String]))))
+});
+const requestOf = Schema.decodeUnknownOption(Request);
+const payloadOf = Schema.decodeUnknownOption(Schema.Json);
+const unresumable = "This server could not resume this socket's subscriptions: connect again";
+const suffixOf = (socket, id) => `${socket}#${Predicate.isNumber(id) ? "n" : "s"}${id}`;
+const socketOf = (suffix) => Number(suffix.slice(0, suffix.indexOf("#")));
+/**
+* The event subscriptions of the sockets one `layerWebSocket` path accepted, kept in storage:
+* `keeper` stores each request as `ActionRpc.layer` admits it, `sent` stores the payload that
+* resumes it with each chunk sent and forgets it at its exit, `closed` forgets a socket's, and
+* `resumed` writes each kept one whose socket of this path is still open to the server again,
+* from there.
+*/
+const makeSubscriptions = (state, path) => {
+	const { storage } = state;
+	const group = groupTag(path);
+	const requests = `${keptPrefix}request/${path}#`;
+	const payloads = `${keptPrefix}payload/${path}#`;
+	const keysOf = (suffix) => [`${requests}${suffix}`, `${payloads}${suffix}`];
+	const live = /* @__PURE__ */ new Map();
+	const listed = (prefix) => Effect.map(Effect.promise(async () => await storage.list({ prefix })), (found) => [...found].map(([key, value]) => [key.slice(prefix.length), value]));
+	const closed = (socket) => Effect.suspend(() => {
+		const owned = [...live.keys()].filter((suffix) => socketOf(suffix) === socket);
+		for (const suffix of owned) live.delete(suffix);
+		return deleted(storage, owned.flatMap(keysOf));
+	});
+	const keeper = { keep: ({ clientId, requestId, tag, payload, headers, resumeFrom }) => Effect.suspend(() => {
+		const suffix = suffixOf(clientId, requestId);
+		const resuming = live.has(suffix);
+		live.set(suffix, resumeFrom);
+		if (resuming) return Effect.void;
+		return Effect.promise(async () => {
+			await storage.put({
+				[`${requests}${suffix}`]: Request.make({
+					id: requestId,
+					tag,
+					headers: headers.map(([name, value]) => [name, value])
+				}),
+				[`${payloads}${suffix}`]: payload
+			});
+		});
+	}) };
+	const moved = (suffix, values) => Effect.suspend(() => {
+		const payload = live.get(suffix)?.(values);
+		return payload === void 0 ? Effect.void : Effect.promise(async () => {
+			await storage.put(`${payloads}${suffix}`, payload);
+		});
+	});
+	const sent = (socket, response) => Match.value(response).pipe(Match.tag("Defect", () => closed(socket)), Match.tag("Chunk", ({ requestId, values }) => moved(suffixOf(socket, requestId), values)), Match.tag("Exit", ({ requestId }) => Effect.suspend(() => {
+		const suffix = suffixOf(socket, requestId);
+		return live.delete(suffix) ? Effect.promise(async () => await storage.delete(keysOf(suffix))) : Effect.void;
+	})), Match.orElse(() => Effect.void));
+	const unresumed = (socket) => Effect.andThen(Effect.logWarning(`layerWebSocket at ${path} could not resume a socket's kept event subscriptions, and closes it`), Effect.sync(() => {
+		closeQuietly(socket, 1e3, unresumable);
+	}));
+	/**
+	* Writes each kept subscription of a socket of this path still open to the server, from where
+	* it reached, and forgets the rest: `held` answers whether a socket stays open, given whether
+	* one of its requests is a subscription kept for it, and closes one that does not.
+	*/
+	const resumed = (write, held) => Effect.gen(function* () {
+		const kept = yield* listed(requests);
+		const resumeFrom = new Map(yield* listed(payloads));
+		const keptIds = new Set(kept.map(([suffix]) => suffix));
+		const open = /* @__PURE__ */ new Map();
+		for (const socket of state.getWebSockets(group)) {
+			const id = socketIdOf(state.getTags(socket));
+			if (held(socket, (requestId) => keptIds.has(suffixOf(id, requestId)))) open.set(id, socket);
+		}
+		const entries = kept.map(([suffix, value]) => ({
+			suffix,
+			socket: socketOf(suffix),
+			request: Option.zipWith(requestOf(value), payloadOf(resumeFrom.get(suffix)), (request, payload) => ({
+				...request,
+				payload
+			}))
+		}));
+		const unread = new Set(entries.flatMap(({ socket, request }) => open.has(socket) && Option.isNone(request) ? [socket] : []));
+		const gone = [...resumeFrom.keys()].flatMap((suffix) => keptIds.has(suffix) ? [] : [`${payloads}${suffix}`]);
+		for (const { suffix, socket, request } of entries) if (open.has(socket) && !unread.has(socket) && Option.isSome(request)) {
+			live.set(suffix, Function.constUndefined);
+			yield* write(socket, request.value);
+		} else gone.push(...keysOf(suffix));
+		yield* deleted(storage, gone);
+		for (const [id, socket] of open) if (unread.has(id)) yield* unresumed(socket);
+	});
+	return {
+		keeper,
+		sent,
+		closed,
+		resumed
+	};
+};
+export { keptPrefix, makeSubscriptions };

package/dist/tasks.d.mts

@@ -0,0 +1,24 @@
+import "./alarm.mjs";
+import { Context, Effect } from "effect";
+declare const Tasks_base: Context.ServiceClass<Tasks, "effect-actions-cloudflare/ActionDurableObject/Tasks", {
+  /**
+   * Marks the task `name` due now in the object's storage, runs `change`, and marks it again
+   * however `change` ended: the object's alarm, set for now, runs it after the call, and a
+   * crash at any point leaves the mark, so the alarm still runs it.
+   */
+  readonly runAfter: <A, E, R>(name: string, change: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}>;
+/**
+ * Runs the object's tasks, `make`'s or `handlers`' `tasks`, by name, after a change, on the
+ * object's alarm until it succeeds, so the work it does, such as telling another object of the
+ * change, is done at least once. A startup service, as `Alarm` is.
+ *
+ * **Gotchas**
+ *
+ * - A task runs on the alarm after the call that changed it has answered: a caller reading the object it tells at once may find it not yet told.
+ * - A task reads what it sends as it runs, such as the state it announces: one run covers every change before it, so it may repeat, and the object it calls ignores what it already holds.
+ * - The alarm may run a task as a change waits, on another object say, over part of that change: the change marks it again as it ends, so a run over the whole change follows.
+ * - A run that fails is logged and retried as the alarm retries an owner: 2 seconds later, doubling, six times, then hourly.
+ */
+export declare class Tasks extends Tasks_base {}
+export {};

package/dist/tasks.mjs

@@ -0,0 +1,31 @@
+import { Clock, Context, Effect } from "effect";
+// src/durable/tasks.ts
+/** The alarm owner a task's time is kept under, one per task name. */
+const taskOwner = (name) => `task:${name}`;
+/**
+* Runs the object's tasks, `make`'s or `handlers`' `tasks`, by name, after a change, on the
+* object's alarm until it succeeds, so the work it does, such as telling another object of the
+* change, is done at least once. A startup service, as `Alarm` is.
+*
+* **Gotchas**
+*
+* - A task runs on the alarm after the call that changed it has answered: a caller reading the object it tells at once may find it not yet told.
+* - A task reads what it sends as it runs, such as the state it announces: one run covers every change before it, so it may repeat, and the object it calls ignores what it already holds.
+* - The alarm may run a task as a change waits, on another object say, over part of that change: the change marks it again as it ends, so a run over the whole change follows.
+* - A run that fails is logged and retried as the alarm retries an owner: 2 seconds later, doubling, six times, then hourly.
+*/
+var Tasks = class extends Context.Service()("effect-actions-cloudflare/ActionDurableObject/Tasks") {};
+/**
+* The instance's `Tasks` over its `schedule`, and the alarm owners that run each of `tasks`, by
+* the name `runAfter` takes.
+*/
+const makeTasks = (schedule, tasks) => ({
+	tasks: Tasks.of({ runAfter: (name, change) => Effect.gen(function* () {
+		if (!Object.hasOwn(tasks, name)) return yield* Effect.die(/* @__PURE__ */ new Error(`ActionDurableObject.Tasks: this object has no task ${name} (give make or handlers a tasks entry named ${name})`));
+		const marked = schedule.set(taskOwner(name), yield* Clock.currentTimeMillis);
+		yield* marked;
+		return yield* Effect.ensuring(change, marked);
+	}) }),
+	owners: Object.fromEntries(Object.entries(tasks).map(([name, task]) => [taskOwner(name), () => task]))
+});
+export { Tasks, makeTasks, taskOwner };

package/dist/webhooks.d.mts

@@ -0,0 +1,36 @@
+import { State } from "./state.mjs";
+import "./alarm.mjs";
+import { Context, Effect, Layer } from "effect";
+import { HttpClient } from "effect/http";
+import * as Webhook from "@gjermundgaraba/effect-actions/Webhook";
+type Webhooks = Layer.Success<ReturnType<typeof Webhook.layer>>;
+declare const Waits_base: Context.ServiceClass<Waits, "effect-actions-cloudflare/ActionDurableObject/Waits", {
+  readonly until: (at: number) => Effect.Effect<void>;
+}>;
+/**
+ * The instance's long waits, which the object's alarm ends: `until(at)` waits until the alarm
+ * runs at or after `at`, holding no timer, so the object may hibernate meanwhile. `handlers` and
+ * `make` provide it to the routes, over the instance's schedule, for `layerWebhooks`.
+ */
+export declare class Waits extends Waits_base {}
+/** How `layerWebhooks` grants, verifies and retries: `Webhook.Options` but what it fixes. */
+export type LayerWebhooksOptions = Omit<Webhook.Options, "persist" | "resolveCallbacks">;
+/**
+ * The core's `Webhook.layer` in an object: each subscription kept in the object's storage, under
+ * `effect-actions/webhooks/`, restored as the object builds after an eviction, and each wait of 10
+ * seconds or more, a retry's backoff or a subscription's expiry, ended by the object's alarm, so
+ * the object hibernates between deliveries and wakes to retry one. Provide it to the routes
+ * beside the surfaces offering webhooks, with an `HttpClient` for the deliveries; its `Waits` are
+ * the instance's, which `handlers` and `make` provide.
+ *
+ * **Gotchas**
+ *
+ * - A callback's name is not resolved for the address check, as Workers have no resolver: a literal address is checked, and a name is left to Cloudflare's egress, which reaches no private network of yours without a Tunnel or a VPC binding of your own.
+ * - A delivery in flight when the instance is evicted is sent again by the next, from the subscription's last kept position: a subscriber drops the repeat by its `eventId`.
+ * - A protected event offered by webhook needs its authentication's `schema`, as `Webhook.Options`' `persist` says: the subscriber's identity is kept by it, not authenticated again at a wake.
+ * - The subscriptions live beside the application's data: a store deleting every key deletes them too, and a subscriber hears nothing more.
+ * - Call it once per object and provide that Layer to every surface offering webhooks: two calls are two layers over one store, each losing the other's subscriptions at an eviction.
+ * - The source, authorizer and client a delivery runs share its Clock: a wait of 10 seconds or more in them, a timeout included, waits on the object's alarm, holding no timer.
+ */
+export declare const layerWebhooks: (options?: LayerWebhooksOptions) => Layer.Layer<Webhooks, never, HttpClient.HttpClient | State | Waits>;
+export {};

package/dist/webhooks.mjs

@@ -0,0 +1,108 @@
+import { State } from "./state.mjs";
+import { batches } from "./batches.mjs";
+import { Clock, Context, Deferred, Duration, Effect, Exit, Layer, Option, Schema, Semaphore } from "effect";
+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
+* runs at or after `at`, holding no timer, so the object may hibernate meanwhile. `handlers` and
+* `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)))));
+	return {
+		waits: Waits.of({ until: (at) => Effect.suspend(() => {
+			const wait = {
+				at,
+				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)));
+		}) }),
+		/** 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;
+		})
+	};
+};
+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 alarmClock = (base, { until }) => ({
+	currentTimeMillisUnsafe: () => base.currentTimeMillisUnsafe(),
+	currentTimeMillis: base.currentTimeMillis,
+	currentTimeNanosUnsafe: () => base.currentTimeNanosUnsafe(),
+	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))
+});
+const stringOf = Schema.decodeUnknownOption(Schema.String);
+const attempted = (method, key, run) => Effect.tryPromise({
+	try: run,
+	catch: (cause) => new KeyValueStore.KeyValueStoreError({
+		message: `The object's storage failed to ${method}`,
+		method,
+		...key === void 0 ? {} : { key },
+		cause
+	})
+});
+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({
+		get: (key) => Effect.map(attempted("get", key, async () => await storage.get(keyOf(key))), (value) => Option.getOrUndefined(stringOf(value))),
+		set: (key, value) => attempted("set", key, async () => {
+			await storage.put(keyOf(key), value);
+		}),
+		remove: (key) => Effect.asVoid(attempted("remove", key, async () => await storage.delete(keyOf(key)))),
+		clear: Effect.flatMap(listed, (found) => Effect.forEach(batches([...found.keys()]), (keys) => attempted("clear", void 0, async () => await storage.delete([...keys])), { discard: true })),
+		size: Effect.map(listed, (found) => found.size)
+	});
+};
+/**
+* The core's `Webhook.layer` in an object: each subscription kept in the object's storage, under
+* `effect-actions/webhooks/`, restored as the object builds after an eviction, and each wait of 10
+* seconds or more, a retry's backoff or a subscription's expiry, ended by the object's alarm, so
+* the object hibernates between deliveries and wakes to retry one. Provide it to the routes
+* beside the surfaces offering webhooks, with an `HttpClient` for the deliveries; its `Waits` are
+* the instance's, which `handlers` and `make` provide.
+*
+* **Gotchas**
+*
+* - A callback's name is not resolved for the address check, as Workers have no resolver: a literal address is checked, and a name is left to Cloudflare's egress, which reaches no private network of yours without a Tunnel or a VPC binding of your own.
+* - A delivery in flight when the instance is evicted is sent again by the next, from the subscription's last kept position: a subscriber drops the repeat by its `eventId`.
+* - A protected event offered by webhook needs its authentication's `schema`, as `Webhook.Options`' `persist` says: the subscriber's identity is kept by it, not authenticated again at a wake.
+* - The subscriptions live beside the application's data: a store deleting every key deletes them too, and a subscriber hears nothing more.
+* - Call it once per object and provide that Layer to every surface offering webhooks: two calls are two layers over one store, each losing the other's subscriptions at an eviction.
+* - The source, authorizer and client a delivery runs share its Clock: a wait of 10 seconds or more in them, a timeout included, waits on the object's alarm, holding no timer.
+*/
+const layerWebhooks = (options = {}) => Webhook.layer({
+	...options,
+	persist: true,
+	resolveCallbacks: false
+}).pipe(Layer.provide([Layer.effect(KeyValueStore.KeyValueStore)(Effect.map(State, ({ storage }) => storageStore(storage))), Layer.effect(Clock.Clock)(Effect.map(Effect.all([Clock.Clock, Waits]), ([base, waits]) => alarmClock(base, waits)))]));
+export { Waits, clockOwner, layerWebhooks, makeWaits, webhookPrefix };

package/docs/ActionDurableObject-events.md

@@ -0,0 +1,153 @@
+# ActionDurableObject: events
+
+The core's events, the `Event` module, in a Durable Object: a page follows one over its socket, an agent over MCP. Read [ActionDurableObject.md](ActionDurableObject.md) first, and the core's `docs/Event.md` for check, current and log sources, `notify` and `publish`.
+
+## Follow an event over a socket
+
+List the event type in the rpcs' binding and its implementation beside the actions' in `ActionRpc.layer`, as `routes.ts` on [ActionDurableObject.md](ActionDurableObject.md) does, and a page watches it on its socket. `make` and `handlers` provide the object's own `Event.Events`, its logs kept in the object's storage, in place of the core's `Event.layerMemory`, so a handler announces with `notify` or `publish` as it does elsewhere. The room's messages are a check source over its store, which `postMessage` notifies after each post:
+
+```ts example=chat-rooms/src/chat/events.ts
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect, Option, Schema } from "effect";
+
+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* () {
+    const store = yield* MessageStore;
+
+    return {
+      check: (_input, cursor) =>
+        Effect.gen(function* () {
+          const last = yield* store.last;
+
+          const after = Option.filter(
+            idOf(cursor),
+            (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),
+              events: [],
+              truncated: cursor !== null,
+              nextPoll,
+            };
+          }
+
+          const messages = yield* store.read(after.value);
+
+          return {
+            cursor: String(messages.at(-1)?.id ?? after.value),
+            events: messages.map((data) => ({
+              eventId: String(data.id),
+              data,
+            })),
+            nextPoll,
+          };
+        }),
+    };
+  }),
+  { authorize }
+);
+```
+
+The page reads, then watches from the last id it read: `messages` in [chat-rooms/src/browser.ts](../examples/chat-rooms/src/browser.ts). The object keeps each socket's subscription in its storage while it hibernates and resumes it from the position it reached when it next wakes, on any event, authenticating it again from the headers it was made with: a token that expired meanwhile ends the watch with `Unauthenticated`. What a check, current and log source do in an object is on `ActionDurableObject.handlers`; which calls the object keeps across hibernation, on `ActionDurableObject.layerWebSocket`. To empty an object, `ctx.storage.deleteAll()` deletes its subscriptions, webhook subscriptions and alarm times with the rest: close its sockets as it does, so their pages connect again and watch anew.
+
+## Announce a change another object makes
+
+An object's `Event.Events` is its own: `notify` and `publish` reach the subscribers of the object they run in, and no other, so every surface serving an event, a socket's rpcs, MCP or an HTTP watch, is among that object's `routes`, and a Worker's own routes serve actions alone. A change another object makes reaches them through a call, a plain `RpcGroup` on this object's stub, whose handler notifies. chat-rooms' lobby is one object, which pages follow for every room's preview: a room's `lobby` task sends the lobby's `roomChanged` the room's latest activity after each post, deletion and expiry ([chat-rooms/src/platform/lobby-stubs.ts](../examples/chat-rooms/src/platform/lobby-stubs.ts)), and the lobby records it and notifies:
+
+```ts example=chat-rooms/src/lobby/handlers.ts
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { LobbyCalls } from "./Calls.js";
+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(
+    LobbyHost,
+    (host) => () => Effect.map(host.previews, (previews) => ({ previews }))
+  )
+);
+
+// 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;
+    const events = yield* Event.Events;
+
+    return LobbyCalls.of({
+      roomChanged: ({ room, latestAt }) =>
+        Effect.flatMap(store.record(room, latestAt), (changed) =>
+          changed ? events.notify(PreviewsChanged) : Effect.void
+        ),
+      previews: () => store.read,
+    });
+  })
+);
+```
+
+The lobby's event is a whole value, every room's preview in each occurrence, so it has a current source, whose revisions the object keeps in its storage: a page is sent the previews as they are, then again after each notify, and watches with no read before it, `followLobby` in [chat-rooms/src/browser.ts](../examples/chat-rooms/src/browser.ts):
+
+```ts example=chat-rooms/src/lobby/events.ts
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+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) => ({
+    current: () => Effect.map(store.read, (previews) => ({ previews })),
+  }))
+);
+```
+
+## Serve the actions and events over MCP
+
+An object can serve `ActionMcp.layerHttp` among its routes, but an agent then needs one connection per object. chat-rooms serves its MCP endpoint from the Worker instead, every room's actions and `MessagePosted` reaching the room the input names: [ActionDurableObject-placement.md](ActionDurableObject-placement.md). The core's `docs/ActionMcp.md` says what each method answers; in an object:
+
+- A held request keeps the object in memory, billed for its duration, until it ends: an `events/stream`, and a `subscriptions/listen`, the stream an MCP 2026-07-28 client holds open for list changes and resource updates, which `layerHttp` allows wherever it serves events. Its `allowSubscriptions: false` serves events by poll alone.
+- An agent polling with `events/poll` lets the object hibernate only if it asks less often than the runtime's idle window, 10 seconds: a check source answers `nextPoll`, 30 seconds in `events.ts` above, and the agent reads on from its cursor on whichever instance answers.
+- A poll reads the source each time; a stream reads it as `ActionDurableObject.handlers` says.
+- A client of a 2025 revision opens a session, which lives in the instance: once it is evicted, the session's next request is answered 404, at which the MCP specification has the client open a new one. Events are the 2026-07-28 revision's alone, which keeps no session.
+- A tool call is answered once its result is ready, so a reset of the object before then fails the request itself, which the client sees. A tool reporting progress is answered by a stream that opens with its first progress: a reset cuts the stream off with no answer, which a client may take for a call still running, so give such a client a timeout.
+
+## Deliver an event by webhook
+
+Provide `layerWebhooks` to an object's MCP endpoint, or to its `ActionHttp.layer`, with an `HttpClient` for the deliveries, such as fetch's, and an agent that holds no request subscribes a callback with `events/subscribe`. It is the core's `Webhook.layer`, described in its `docs/Webhook.md`, kept in the object's storage and restored as the object builds after an eviction, with each wait of 10 seconds or more, a retry's backoff or a subscription's expiry, ended by the object's alarm, so the object hibernates between deliveries. The event's authentication needs `principal` and `schema`, given to `Authentication.make`: a delivery restored after an eviction runs as the subscriber its `schema` kept. What a callback's address check is in an object is on `ActionDurableObject.layerWebhooks`. A Worker serving an object's events through a placement cannot deliver them: nothing in it outlives a request. A test answers the object's deliveries with Miniflare's `outboundService`, given to `@cloudflare/vitest-plugin`'s `miniflare` options.

package/docs/ActionDurableObject-failures.md

@@ -0,0 +1,18 @@
+# ActionDurableObject failure modes
+
+Messages the library does not own, workerd's, the compiler's and Effect's, and the fix. Search for a fragment of the message; one the library throws says its own fix. The tasks are in [ActionDurableObject.md](ActionDurableObject.md); a surface's own failures are in the core's `*-failures.md` pages.
+
+- `is not assignable to type 'Allowed<never, never>'` at `make`'s or `handlers`' `routes`, or `Allowed<X, Y>` where the routes provide `X` and `services` provides `Y`: the routes require a service no Layer provides; those in the union other than `State`, `Alarm`, `Tasks`, `Events`, `Idempotency`, `Sockets`, `Waits`, `HttpRouter`, the platform's and `Y` are missing, so add their Layers to `services` or provide them to the routes, and a `Request<"Requires", Z>` is read per request, as the core's `ActionRpc-failures.md` says.
+- `is not assignable to type 'Layer<never, never, ` at `make`'s or `handlers`' `calls`, the union `Alarm`, `Events`, `Idempotency`, `Protocol`, `State` and `Tasks`, with the services among them at `make`, sorted by name: the rpc server requires what no Layer provides, such as its group's handlers given with `RpcServer.layer(group)` alone, or a binding's authentication; provide it to the calls, or add its Layer to `services`.
+- `is not assignable to type 'Layer<never, never, Alarm | Events | Idempotency | Protocol | State | Tasks>'` at `handlers`' `calls`, the source type naming a service that `services` gives with `Layer.succeed(Tag, value)`: TypeScript infers no services from the two-argument form there; write `Layer.succeed(Tag)(value)`.
+- `is not assignable to type 'Layer<never, never, never>'` at `handlers`' `services`, beside an error at its `calls`: TypeScript infers no services once the calls fail; fix the calls' error, as the entries above say.
+- `is not assignable to type 'Alarm | Events | Idempotency | State | Tasks'` at `make`'s or `handlers`' `services`, after `is not assignable to type 'Layer<` naming the services: they require a service other than `State`, `Alarm`, `Tasks`, `Event.Events` and `Action.Idempotency`, which nothing before them builds; provide its Layer to them, `Layer.provide`, or merge it in with `Layer.provideMerge`.
+- `provides no match for the signature '(env: Env): Layer<` at `make`'s `services`: `make` takes its services as a function of `env`, never a Layer; write `services: () => layer`.
+- `Property 'effectActionsRpc' is missing in type 'DurableObjectStub<...>' but required in type 'Stub'` at `layerStubClient` or `client`'s factory: the class serves no calls over its stub; give `make` `calls`, or define the method in a class of your own, delegating to `handlers`.
+- `Effect<Context<Protocol>, never, Sockets>` is not assignable, or `Sockets` missing among a Layer's requirements: `layerWebSocket` registers with the dispatcher of the instance's sockets, which `make` and `handlers` provide; serve the routes through one of them.
+- `The RPC receiver does not implement the method "effectActionsRpc"`, workerd's, as an `RpcClientError`'s cause: the class defines no such method; define it, delegating to `handlers` ([ActionDurableObject-own-class.md](ActionDurableObject-own-class.md)).
+- `Serialized RPC arguments or return values are limited to 32MiB`, workerd's, as an `RpcClientError`'s cause: the call's request or answer passed Workers RPC's limit; page large answers, or keep large values in storage, R2 or a socket's stream.
+- `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.

package/docs/ActionDurableObject-own-class.md

@@ -0,0 +1,9 @@
+# ActionDurableObject in a class of your own
+
+A class with methods, sockets or handlers of its own extends the one `make` returns and overrides them, its `services` a function of its `env` ([ActionDurableObject.md](ActionDurableObject.md)). This page is for a class that cannot, such as one extending another base class: it delegates to the handlers `make` is built from. 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).
+
+## Delegate to handlers
+
+`handlers(this.ctx, options)` takes `make`'s options, with `services` a Layer, built from `this.env` when they read it, and returns the object's handlers, each taking the runtime's own arguments. Keep it in a private field, delegate the handlers the class serves this way, and write the others. A class serving `calls` defines the method a stub calls, delegating: `effectActionsRpc(request: ActionDurableObject.StubRequest) { return this.#object.effectActionsRpc(request); }`. Its own methods run their Effects with `run(effect)`, which gives them the services, `State`, `Alarm`, `Event.Events` and a `Scope`, and stay callable over the stub beside it. Delegate `alarm` too, given an `alarm` option or not: `Alarm`'s times and `layerWebhooks`' waits run through it.
+
+How the object builds, when it builds again, and which handlers resolve without a build are on `ActionDurableObject.handlers`; the rules of each option on `ActionDurableObject.Options`; what `run` builds per call on `ActionDurableObject.Handlers`' `run`.

package/docs/ActionDurableObject-placement.md

@@ -0,0 +1,41 @@
+# ActionDurableObject: placement
+
+A **placement** says which Durable Object serves each call and each watch of an HTTP binding's contracts: the one its contract's **key** names for its input, `getByName(key(input))`. The Worker serves the contracts on any surface without implementing them, sending each call on to its object, so one client, or one agent's MCP connection, reaches every object. Read [ActionDurableObject.md](ActionDurableObject.md) first; what the Worker sends on and what comes back is on the core's `ActionHttp.placed`, which this builds on.
+
+## Place a binding's contracts in objects
+
+Each contract names its object in its input, chat-rooms' room in every action and in `MessagePosted`, and one HTTP binding holds them, served by the Worker and by each object alike:
+
+```ts example=chat-rooms/src/Api.ts
+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]);
+```
+
+Then, as `routes.ts` on [ActionDurableObject.md](ActionDurableObject.md) does:
+
+- `ActionDurableObject.placed(RoomHttp, { readMessages: byRoom, … })` is the placement, shared by both sides: a key for each contract of the binding, by its name, each reading its own contract's input, so a contract added to the binding without one is a type error.
+- Each object's routes serve the binding in `ActionHttp.layer`, where each call arrives, beside whatever else they serve, a page's socket among them.
+- 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.
+
+## Serve them over MCP from the Worker
+
+Nothing in a Worker outlives a request, so its MCP endpoint is `requestScoped`, as `routes.ts`'s is: MCP 2026-07-28 alone, and an event by `events/poll` alone, since a request-scoped server pushes nothing. An event that agents follow by stream or by webhook is served from its object's own endpoint instead, as [ActionDurableObject-events.md](ActionDurableObject-events.md) shows, one connection per object. Where every event lives in one object, such as a single lobby, that object serves the one MCP endpoint, its own implementations beside `reaching` the other objects' actions, and the Worker forwards `/mcp` to it.
+
+## What a watch through the Worker costs
+
+Cloudflare bills a Worker for its requests and CPU time, not for how long a request stays open, and an object for the wall-clock time it is active or cannot hibernate, as its pricing page says. A watch held through the Worker, an HTTP client's stream, holds a request to the object open for as long as it lasts, so the object is billed for all of it; a poll lets it hibernate between requests. An event an object's socket serves through a placement of another object's holds both awake: serve an event in the object whose socket follows it, as `ActionDurableObject.reaching` says.