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

package/examples/chat-rooms/src/platform/lobby-stubs.ts

@@ -0,0 +1,46 @@
+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) })
+  )
+);

package/examples/chat-rooms/src/platform/sql-store.ts

@@ -0,0 +1,110 @@
+import * as ActionDurableObject from "@gjermundgaraba/effect-actions-cloudflare/ActionDurableObject";
+import { Clock, DateTime, Effect, Layer, Schema } from "effect";
+
+import { Message, MessageNotFound, NotAuthor } from "../chat/Chat.js";
+import { MessageStore } from "../chat/store.js";
+
+const day = 24 * 60 * 60 * 1000;
+
+const decodeMessage = Schema.decodeUnknownSync(Message);
+
+const decodeSequence = Schema.decodeUnknownSync(
+  Schema.Array(Schema.Struct({ seq: Schema.Int }))
+);
+
+// The room's messages in the object's own SQLite database, which outlives every instance: an
+// evicted instance loses its memory, never these. The Layer runs each time an instance is
+// constructed, so creating the table is idempotent.
+export const layerSql = Layer.effect(MessageStore)(
+  Effect.gen(function* () {
+    const { storage } = yield* ActionDurableObject.State;
+    const alarm = yield* ActionDurableObject.Alarm;
+
+    const query = (sql: string, ...bindings: ReadonlyArray<string | number>) =>
+      storage.sql
+        .exec(sql, ...bindings)
+        .toArray()
+        .map((row) => decodeMessage(row));
+
+    storage.sql.exec(
+      "CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY AUTOINCREMENT, author TEXT NOT NULL, text TEXT NOT NULL, at INTEGER NOT NULL)"
+    );
+
+    // Every expiry looks up the oldest message: indexed, it reads one row, where a scan would read
+    // the whole table, and SQLite storage is billed by rows read.
+    storage.sql.exec(
+      "CREATE INDEX IF NOT EXISTS messages_by_at ON messages (at)"
+    );
+
+    // The room's alarm is due no later than the oldest message's expiry: `Alarm.set` keeps the
+    // earliest time it is given, so each post sets its own message's, and `expire`, which runs on
+    // the alarm, sets the next from the oldest message left. Removing the oldest message leaves
+    // its alarm, which then finds nothing due and moves on.
+    const alarmForOldest = Effect.suspend(() => {
+      const [oldest] = query("SELECT * FROM messages ORDER BY at LIMIT 1");
+
+      return oldest === undefined
+        ? Effect.void
+        : alarm.set(DateTime.makeUnsafe(oldest.at + day));
+    });
+
+    return MessageStore.of({
+      latest: Effect.sync(
+        () =>
+          query("SELECT * FROM messages ORDER BY id DESC LIMIT 1")[0] ?? null
+      ),
+      // AUTOINCREMENT keeps the highest id it ever gave in `sqlite_sequence`, so the last id
+      // outlives the message: one that expired or was deleted still counts.
+      last: Effect.sync(
+        () =>
+          decodeSequence(
+            storage.sql
+              .exec("SELECT seq FROM sqlite_sequence WHERE name = 'messages'")
+              .toArray()
+          )[0]?.seq ?? 0
+      ),
+      read: (after) =>
+        Effect.sync(() =>
+          query("SELECT * FROM messages WHERE id > ? ORDER BY id", after)
+        ),
+      post: Effect.fn("MessageStore.post")(function* (author, text) {
+        const at = yield* Clock.currentTimeMillis;
+
+        const message = decodeMessage(
+          storage.sql
+            .exec(
+              "INSERT INTO messages (author, text, at) VALUES (?, ?, ?) RETURNING *",
+              author,
+              text,
+              at
+            )
+            .one()
+        );
+
+        yield* alarm.set(DateTime.makeUnsafe(message.at + day));
+
+        return message;
+      }),
+      remove: Effect.fn("MessageStore.remove")(function* (author, id) {
+        const [message] = query("SELECT * FROM messages WHERE id = ?", id);
+
+        if (message === undefined) {
+          return yield* new MessageNotFound({ id });
+        }
+
+        if (message.author !== author) {
+          return yield* new NotAuthor({ id });
+        }
+
+        storage.sql.exec("DELETE FROM messages WHERE id = ?", id);
+      }),
+      expire: Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+
+        storage.sql.exec("DELETE FROM messages WHERE at <= ?", now - day);
+
+        yield* alarmForOldest;
+      }),
+    });
+  })
+);

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

@@ -0,0 +1,33 @@
+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))
+    );
+  }
+}

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

@@ -0,0 +1,89 @@
+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));

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

@@ -0,0 +1,99 @@
+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>;

package/examples/chat-rooms/test/platform/sql-store.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as ActionDurableObject from "@gjermundgaraba/effect-actions-cloudflare/ActionDurableObject";
+import { runInDurableObject } from "cloudflare:test";
+import { env } from "cloudflare:workers";
+import { Clock, Effect, Layer } from "effect";
+
+import { MessageNotFound, NotAuthor } from "../../src/chat/Chat.js";
+import { MessageStore } from "../../src/chat/store.js";
+import { layerSql } from "../../src/platform/sql-store.js";
+
+const day = 24 * 60 * 60 * 1000;
+
+let objects = 0;
+
+// The adapter against a room's real SQLite database, inside a fresh object of its own: what it
+// reaches is the Workers runtime, so the runtime is its stand-in.
+const inObject = <A, E>(
+  use: (
+    store: MessageStore["Service"],
+    state: DurableObjectState
+  ) => Effect.Effect<A, E>
+) =>
+  Effect.promise(async () => {
+    objects += 1;
+
+    return await runInDurableObject(
+      env.CHAT_ROOM.getByName(`sql-store-${objects}`),
+      async (_, state) =>
+        await Effect.runPromise(
+          MessageStore.use((store) => use(store, state)).pipe(
+            Effect.provide(
+              layerSql.pipe(
+                Layer.provide(ActionDurableObject.Alarm.layer),
+                Layer.provide(Layer.succeed(ActionDurableObject.State, state))
+              )
+            )
+          )
+        )
+    );
+  });
+
+// A clock a millisecond later at each read, which never yields: posts running at once read
+// times of their own, where at one shared time the oldest message and the latest would set the
+// same alarm. Effect's TestClock moves on through a semaphore, which lets each post finish first.
+const tickingFrom = (start: number): Clock.Clock => {
+  let now = start;
+  const tick = () => (now += 1);
+  const nanos = () => BigInt(now) * 1_000_000n;
+
+  return {
+    currentTimeMillisUnsafe: tick,
+    currentTimeMillis: Effect.sync(tick),
+    currentTimeNanosUnsafe: nanos,
+    currentTimeNanos: Effect.sync(nanos),
+    monotonicTimeNanosUnsafe: nanos,
+    monotonicTimeNanos: Effect.sync(nanos),
+    sleep: () => Effect.void,
+  };
+};
+
+describe("the SQL message store", () => {
+  it.live("numbers a room's messages and reads those after an id", () =>
+    inObject((store) =>
+      Effect.gen(function* () {
+        const first = yield* store.post("ada", "One.");
+        const second = yield* store.post("grace", "Two.");
+
+        expect(second.id).toBe(first.id + 1);
+        expect(yield* store.read(0)).toStrictEqual([first, second]);
+        expect(yield* store.read(first.id)).toStrictEqual([second]);
+        expect(yield* store.latest).toStrictEqual(second);
+      })
+    )
+  );
+
+  it.live("deletes only its author's message", () =>
+    inObject((store) =>
+      Effect.gen(function* () {
+        const posted = yield* store.post("ada", "Mine.");
+
+        expect(
+          yield* Effect.flip(store.remove("grace", posted.id))
+        ).toStrictEqual(new NotAuthor({ id: posted.id }));
+        expect(
+          yield* Effect.flip(store.remove("ada", posted.id + 1))
+        ).toStrictEqual(new MessageNotFound({ id: posted.id + 1 }));
+
+        yield* store.remove("ada", posted.id);
+
+        expect(yield* store.latest).toBeNull();
+      })
+    )
+  );
+
+  it.live(
+    "sets the alarm for the oldest message's expiry when messages are posted at once",
+    () =>
+      inObject((store, state) =>
+        Effect.gen(function* () {
+          const posted = yield* Effect.forEach(
+            Array.from({ length: 32 }, (_, i) => `Message ${i}.`),
+            (text) => store.post("ada", text),
+            { concurrency: "unbounded" }
+          ).pipe(Effect.provideService(Clock.Clock, tickingFrom(Date.now())));
+
+          expect(new Set(posted.map(({ at }) => at)).size).toBe(32);
+          expect(
+            yield* Effect.promise(async () => await state.storage.getAlarm())
+          ).toBe(Math.min(...posted.map(({ at }) => at)) + day);
+        })
+      )
+  );
+
+  it.live(
+    "sets the alarm for the first message's expiry and leaves it for later ones",
+    () =>
+      inObject((store, state) =>
+        Effect.gen(function* () {
+          const first = yield* store.post("ada", "One.");
+
+          yield* Effect.sleep("1 millis");
+
+          const second = yield* store.post("ada", "Two.");
+
+          expect(second.at).toBeGreaterThan(first.at);
+          expect(
+            yield* Effect.promise(async () => await state.storage.getAlarm())
+          ).toBe(first.at + day);
+        })
+      )
+  );
+});

package/examples/chat-rooms/test/support/socket.ts

@@ -0,0 +1,70 @@
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import { exports } from "cloudflare:workers";
+import { Effect, Layer } from "effect";
+import { RpcClient, RpcSerialization } from "effect/rpc";
+import { Socket } from "effect/socket";
+
+import { protocolVersion, unsupportedProtocol } from "../../src/Rpc.js";
+
+// A page's socket to an object, `<at>/rpc` upgraded through the Worker as a browser's would be,
+// naming the version of the rpcs as `connection(url)` does. A test has no network to open one by
+// its URL, so it hands the upgraded socket to Effect's client protocol, the protocol
+// `connection(url)` builds over a URL, its reconnection included, and keeps the socket, which a
+// test listens on for what the object sent. The socket is accepted as Effect's client listens to
+// it, as a browser's socket is constructed with its listeners: accepted before, a close the
+// object sent at once could go unheard. `connects` counts the client's attempts: each after the
+// first would be another upgrade in a browser.
+export const pageSocket = (
+  at: string,
+  headers: Record<string, string> = {},
+  version = protocolVersion
+) =>
+  Effect.gen(function* () {
+    const response = yield* Effect.promise(
+      async () =>
+        await exports.default.fetch(
+          `https://chat.example${at}/rpc?protocol=${version}`,
+          {
+            headers: { ...headers, upgrade: "websocket" },
+          }
+        )
+    );
+
+    const socket = response.webSocket;
+
+    if (socket === null) {
+      return yield* Effect.die(new Error(`No WebSocket: ${response.status}`));
+    }
+
+    let connects = 0;
+
+    const accepted = Effect.sync(() => {
+      if (connects === 0) {
+        socket.accept();
+      }
+
+      connects += 1;
+
+      return socket;
+    });
+
+    const protocol = yield* Layer.build(
+      RpcClient.layerProtocolSocket({
+        retryPolicy: ActionRpc.reconnectUntil(unsupportedProtocol),
+      }).pipe(
+        Layer.provide(
+          Layer.effect(Socket.Socket)(Socket.fromWebSocket(accepted))
+        ),
+        Layer.provide(RpcSerialization.layerJson)
+      )
+    );
+
+    return { socket, protocol, connects: () => connects };
+  });
+
+// A page's socket to a room.
+export const roomSocket = (
+  room: string,
+  headers: Record<string, string> = {},
+  version = protocolVersion
+) => pageSocket(`/rooms/${room}`, headers, version);