@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

package/examples/kitchen-sink/test/routes.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, flow, Layer } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Tools } from "../src/Actions.js";
+import { AdminHttp, Http } from "../src/Api.js";
+import { memory } from "../src/memory.js";
+import { adminRoutes, builders, publicRoutes } from "../src/routes.js";
+
+// The host's surfaces, as routes.ts builds them, answering in memory: no port is opened. Two
+// ports are two `Testing.layer`s, each a layer graph of its own, as two servers are. What they
+// share is provided above both, as server.ts does: the builders, then the services.
+const shared = builders.pipe(Layer.provideMerge(memory));
+
+const onPublicPort = Effect.provide(Testing.layer(publicRoutes));
+
+const onAdminPort = Effect.provide(Testing.layer(adminRoutes));
+
+const ada = {
+  transformClient: HttpClient.mapRequest(
+    flow(HttpClientRequest.bearerToken("ada"), HttpClientRequest.setHeader("x-workspace", "acme")),
+  ),
+};
+
+const ops = {
+  transformClient: HttpClient.mapRequest(HttpClientRequest.setHeader("x-operator-key", "ops-key")),
+};
+
+const post = (path: string) =>
+  HttpClient.execute(HttpClientRequest.post(path).pipe(HttpClientRequest.bodyJsonUnsafe({})));
+
+describe("the public port", () => {
+  it.effect("answers the public action without a token and refuses the rest", () =>
+    Effect.gen(function* () {
+      const anyone = yield* ActionHttp.client(Http);
+
+      expect(yield* anyone.getStatus()).toMatchObject({ service: "tracker", workspaces: 2 });
+      expect(yield* Effect.flip(anyone.whoAmI())).toBeInstanceOf(Action.Unauthenticated);
+    }).pipe(onPublicPort, Effect.provide(shared)),
+  );
+
+  it.effect("lists the tools to a signed-out MCP client, the unlisted action left out", () =>
+    Effect.gen(function* () {
+      const listing = yield* HttpClient.execute(Testing.mcpRequest("tools/list"));
+      const text = yield* listing.text;
+
+      expect(listing.status).toBe(200);
+      expect(text).toContain('"name":"createIssue"');
+      expect(text).not.toContain('"name":"attachImage"');
+    }).pipe(onPublicPort, Effect.provide(shared)),
+  );
+
+  it.effect("serves one store to both surfaces: an issue filed over HTTP is read as a tool", () =>
+    Effect.gen(function* () {
+      const http = yield* ActionHttp.client(Http, ada);
+      const mcp = yield* Testing.mcpClient(Tools, ada);
+      const issue = yield* http.createIssue({ title: "Crash", body: "On save." });
+
+      expect(yield* mcp.getIssue({ id: issue.id })).toEqual(issue);
+    }).pipe(onPublicPort, Effect.provide(shared)),
+  );
+
+  it.effect("refuses, at the MCP endpoint, a page of this host that is not on its list", () =>
+    Effect.gen(function* () {
+      // The request policy lets both through: one is the request's own origin, one is listed.
+      const from = (url: string, origin: string) =>
+        HttpClient.execute(Testing.mcpRequest("tools/list", {}, { url, headers: { origin } }));
+
+      const listed = yield* from("/mcp", "http://localhost:6274");
+      const sameHost = yield* from("http://127.0.0.1/mcp", "http://127.0.0.1");
+
+      expect([listed.status, sameHost.status]).toEqual([200, 403]);
+    }).pipe(onPublicPort, Effect.provide(shared)),
+  );
+});
+
+describe("the two ports", () => {
+  it.effect("serve each audience its own routes, and none of the other's", () =>
+    Effect.gen(function* () {
+      const admin = yield* post("/admin/listWorkspaces").pipe(onPublicPort);
+      const member = yield* post("/api/v1/whoAmI").pipe(onAdminPort);
+
+      expect([admin.status, member.status]).toEqual([404, 404]);
+    }).pipe(Effect.provide(shared)),
+  );
+
+  it.effect("run a builder once for an implementation both serve", () =>
+    Effect.gen(function* () {
+      const onPublic = yield* Effect.flatMap(ActionHttp.client(Http), (client) =>
+        client.getStatus(),
+      ).pipe(onPublicPort);
+
+      const onAdmin = yield* Effect.flatMap(ActionHttp.client(AdminHttp), (client) =>
+        client.getStatus(),
+      ).pipe(onAdminPort);
+
+      // `status`'s builder names the start it ran in. With `builders` above both ports it ran
+      // once. Provide `memory` alone instead, and each port runs it: two instances.
+      expect(onAdmin.instance).toBe(onPublic.instance);
+    }).pipe(Effect.provide(shared)),
+  );
+
+  it.effect("share their services: a workspace suspended on one is refused on the other", () =>
+    Effect.gen(function* () {
+      const whoAmI = Effect.flatMap(ActionHttp.client(Http, ada), (client) => client.whoAmI());
+
+      expect(yield* whoAmI.pipe(onPublicPort)).toMatchObject({ id: "ada" });
+
+      const suspended = yield* Effect.flatMap(ActionHttp.client(AdminHttp, ops), (client) =>
+        client.suspendWorkspace({ workspace: "acme" }),
+      ).pipe(onAdminPort);
+
+      expect(suspended).toEqual({ slug: "acme", name: "Acme", suspended: true });
+
+      const refused = yield* Effect.flip(whoAmI).pipe(onPublicPort);
+
+      expect(refused).toBeInstanceOf(Action.Forbidden);
+      expect(refused.message).toBe("This workspace is suspended.");
+    }).pipe(Effect.provide(shared)),
+  );
+});

package/examples/kitchen-sink/test/support/scripted.ts

@@ -0,0 +1,40 @@
+import { Effect, Layer, Ref, Stream } from "effect";
+import { AiError, LanguageModel, type Response } from "effect/ai";
+
+type Reply = ReadonlyArray<Response.PartEncoded>;
+
+// A model for a test: it answers its first request with the first reply it was given, its
+// second with the second, whatever the prompt says. A reply is the parts a provider sends, or
+// an Effect that makes them: `down` to fail as a provider that is down does, or one that waits.
+export const scripted = (
+  ...replies: ReadonlyArray<Reply | Effect.Effect<Reply, AiError.AiError>>
+) =>
+  Layer.effect(
+    LanguageModel.LanguageModel,
+    Effect.gen(function* () {
+      const answered = yield* Ref.make(0);
+
+      return yield* LanguageModel.make({
+        generateText: () =>
+          Effect.flatMap(
+            Ref.getAndUpdate(answered, (count) => count + 1),
+            (count) => {
+              const reply = replies[count] ?? [];
+
+              return Effect.isEffect(reply)
+                ? Effect.map(reply, (parts) => [...parts])
+                : Effect.succeed([...reply]);
+            },
+          ),
+        streamText: () => Stream.empty,
+      });
+    }),
+  );
+
+export const down: Effect.Effect<never, AiError.AiError> = Effect.fail(
+  AiError.make({
+    module: "scripted",
+    method: "generateText",
+    reason: new AiError.UnknownError({ description: "The provider is down." }),
+  }),
+);

package/examples/live-rpc/README.md

@@ -0,0 +1,107 @@
+# live-rpc
+
+A chat served as Effect RPC over a WebSocket: one connection per page, many calls on it.
+Members post, read and delete messages in the rooms they belong to; anyone may list the rooms.
+Each message on the socket carries its own token and names its room, so a socket has no
+identity of its own. A message naming no room is about the default one, `lobby`.
+
+Start here if a client keeps a connection open and calls often, or if the application already
+speaks Effect RPC. For a JSON API or MCP tools, start from [notes-service](../notes-service/).
+Actions are unary, so nothing streams: the page reads again, passing the last id it holds.
+
+## Run it
+
+From the repository root, after `vp install` (from an installed package, see
+[Run one](../README.md#run-one)):
+
+```sh
+node --import tsx examples/live-rpc/src/server.ts     # 127.0.0.1:3000, HOST and PORT to change
+node --import tsx examples/live-rpc/src/client.ts     # CHAT_URL to change, ws://127.0.0.1:3000/rpc
+
+vp test examples/live-rpc
+```
+
+`client.ts` runs the browser's client from Node: two members on one socket, then each failure
+a page handles. `browser.ts` is imported by a page, not run: `openChat` for a page that is an
+Effect program, `connect(url)` for one that calls with promises. The tokens are fixed names (`ada`,
+`grace`) and the store is memory: replace both before deploying anything.
+
+## When you copy this
+
+Three choices here show a feature. Decide each for your application before keeping it:
+
+- **`listRooms` is public** to show a public rpc beside protected ones. It tells a signed-out
+  caller every room's name.
+- **A message naming no room is about `lobby`**, to show a default in request context. Yours may
+  refuse instead.
+- **The room is a header, not an input**, because `authorize` sees the action and not its input:
+  the membership rule reads the room from request context. With the room in the input, the
+  check belongs in the store, never in a helper each handler must remember to call: the store's
+  method takes the member and refuses, as `MessageStore.remove` in `src/chat/store.ts` takes the
+  author and refuses with `NotAuthor`.
+
+## Layout
+
+```text
+src/
+├── chat/
+│   ├── Chat.ts        contract: schemas, errors, actions, the room header and its default
+│   ├── store.ts       MessageStore, the service the handlers call, and its Layer
+│   ├── room.ts        CurrentRoom, and the RPC middleware providing it per message
+│   ├── authorize.ts   the one authorization rule: a member of the room
+│   └── handlers.ts    Action.implement: contract to store
+├── identity/
+│   ├── Identity.ts    contract: CurrentMember and the Login descriptor
+│   ├── members.ts     the demo members
+│   └── verifier.ts    Authentication.layer: tokens to members, server only
+├── Rpc.ts             the RPC binding of every action
+├── routes.ts          the rpcs, authenticated and with their middleware, not yet on a protocol
+├── server.ts          entrypoint: the rpcs over a WebSocket at /rpc, its messages bounded
+├── browser.ts         client module: the connection and the chat, as Effects and as promises
+└── client.ts          entrypoint: that client, run from Node
+test/
+├── chat/              in process, with Action.client
+├── routes.test.ts     over RPC in memory, with Testing.layer
+├── browser.test.ts    the page's client against the same rpcs
+└── server.test.ts     the socket itself: a listening port, connect(url), the bound on a message
+```
+
+- **The PascalCase files are what a page imports.** `Chat.ts`, `Identity.ts` and `Rpc.ts` import
+  no server code. `browser.ts` imports them, the library's `ActionRpc`, and `effect`,
+  `effect/rpc` and `effect/socket`, nothing else, so it bundles for a browser.
+- **A request-time service is never a startup service.** `CurrentMember` comes from
+  authentication and `CurrentRoom` from middleware, both per message. Neither has a Layer, and
+  no entrypoint provides one: a value provided at startup would serve every caller as one
+  member in one room.
+- **The entrypoint chooses the protocol.** `routes.ts` exports the rpcs without one. `server.ts`
+  gives them a WebSocket, its only route. `browser.ts` leaves the WebSocket constructor to its
+  host: a page provides the browser's, `client.ts` provides Node's.
+- **The socket belongs to the Layer providing it.** `connection(url)` opens it when it is built
+  and closes it when it is released: provide it once around the page's program, or keep it in
+  a `ManagedRuntime`, as `connect(url)` does. The scope `openChat` needs holds only the client.
+- **One test file opens a port.** `Testing.layer` answers HTTP requests and cannot upgrade a
+  WebSocket, so `routes.test.ts` and `browser.test.ts` give the same rpcs Effect's HTTP protocol,
+  in memory. `server.test.ts` covers what that leaves out: it serves them over a WebSocket on a
+  port the system picks, calls with `connect(url)`, and sends a message over the server's bound.
+
+## Where to look
+
+| To see                                                                 | Read                                            |
+| ---------------------------------------------------------------------- | ----------------------------------------------- |
+| An RPC binding naming its authentication descriptor                    | `src/Rpc.ts`                                    |
+| The rpcs on Effect's `RpcServer`, before a protocol is chosen          | `src/routes.ts`                                 |
+| Serving them over a WebSocket, speaking JSON                           | `src/server.ts`                                 |
+| The same rpcs over Effect's HTTP protocol, for a test                  | `test/routes.test.ts`                           |
+| A verifier that runs for every message, not once per connection        | `src/identity/verifier.ts`                      |
+| Native `RpcMiddleware` providing a per-request service, with a default | `src/chat/room.ts`                              |
+| Handlers reading that service, and the rule that reads it              | `src/chat/handlers.ts`, `src/chat/authorize.ts` |
+| A public rpc beside protected ones                                     | `src/chat/Chat.ts`                              |
+| A socket client sending its token and room on each message             | `src/browser.ts`                                |
+| Who owns the socket, and how a promise page keeps it open              | `src/browser.ts`                                |
+| A declared error and the built-in refusals handled by tag              | `src/browser.ts`                                |
+| Running that client from Node, two callers on one socket               | `src/client.ts`                                 |
+| Testing handlers and authorization with no transport                   | `test/chat/chat.test.ts`                        |
+| Testing rpcs, authentication and middleware in memory                  | `test/routes.test.ts`                           |
+| The binding's native `RpcGroup` called by Effect's own client          | `test/routes.test.ts`                           |
+| Testing the client's handling of each error and refusal                | `test/browser.test.ts`                          |
+| Testing over a real WebSocket, and a message over `maxPayload`         | `test/server.test.ts`                           |

package/examples/live-rpc/src/Rpc.ts

@@ -0,0 +1,8 @@
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import { ListRooms, Messages } from "./chat/Chat.js";
+import { Login } from "./identity/Identity.js";
+
+// The RPC binding: one native rpc per action, named after it, the protected ones requiring
+// `Login`. It is plain data and imports no server code, so the server and a browser page both
+// import this one value. `Rpc.group` is the native `RpcGroup`, for Effect's own `RpcClient.make`.
+export const Rpc = ActionRpc.make([ListRooms, ...Messages], { authentication: Login });

package/examples/live-rpc/src/browser.ts

@@ -0,0 +1,98 @@
+import { Context, Effect, Layer, ManagedRuntime } from "effect";
+import { RpcClient, RpcSerialization } from "effect/rpc";
+import { Socket } from "effect/socket";
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import { roomHeader } from "./chat/Chat.js";
+import { Rpc } from "./Rpc.js";
+
+// Client module: what a web page imports. It holds the binding and nothing of the server, so a
+// bundler gets the contracts and Effect's RPC client, no handler and nothing of Node.
+
+// Effect's own client protocol: one WebSocket, speaking the server's JSON. This layer owns
+// the socket: it opens when the layer is built and closes when the layer is released, so
+// provide it once, around the page's whole program, never around one call. Which WebSocket is
+// left to the host: a page provides `Socket.layerWebSocketConstructorGlobal`, the browser's
+// own, and client.ts provides Node's.
+export const connection = (url: string) =>
+  RpcClient.layerProtocolSocket().pipe(
+    Layer.provide(Socket.layerWebSocket(url)),
+    Layer.provide(RpcSerialization.layerJson),
+  );
+
+// The chat as a page uses it, on the connection provided around it. The scope it needs holds
+// only the typed client built on that connection, not the socket.
+export const openChat = Effect.gen(function* () {
+  // One typed method per action of the binding, all on the one connection.
+  const client = yield* ActionRpc.client(Rpc);
+
+  return {
+    // The public rpc: no token.
+    rooms: Effect.map(client.listRooms(), ({ rooms }) => rooms),
+
+    room: (name: string, token: string) => {
+      // A browser WebSocket sets no header when it connects, so the token travels on each
+      // message, and the room beside it. A refreshed token needs no new socket.
+      const here = RpcClient.withHeaders({ authorization: `Bearer ${token}`, [roomHeader]: name });
+
+      return {
+        // Called again and again while the page is open, with the last id it holds. A token
+        // may expire under a socket that stays up, so the refusals are handled here. Each is
+        // a typed failure matched by its tag, and only that call fails: the socket stays open.
+        read: (after: number) =>
+          client.readMessages({ after }).pipe(
+            here,
+            Effect.map(({ messages }) => ({ access: "member" as const, messages })),
+            Effect.catchTags({
+              Unauthenticated: () =>
+                Effect.succeed({ access: "signed-out" as const, messages: [] }),
+              Forbidden: () => Effect.succeed({ access: "not-a-member" as const, messages: [] }),
+            }),
+          ),
+
+        post: (text: string) => client.postMessage({ text }).pipe(here),
+
+        // A declared error arrives as the contract's class. A message someone else already
+        // removed is gone, which is what the page asked for.
+        remove: (id: number) =>
+          client.deleteMessage({ id }).pipe(
+            here,
+            Effect.as("removed" as const),
+            Effect.catchTags({
+              MessageNotFound: () => Effect.succeed("removed" as const),
+              NotAuthor: () => Effect.succeed("not-yours" as const),
+            }),
+          ),
+      };
+    },
+  };
+});
+
+// The chat for a page that is not one Effect program: the same client, each call a promise.
+// A `ManagedRuntime` keeps the protocol's layer, and so the socket, between calls. It builds
+// the layer on the first call, which is when the socket opens, and `close` releases it. A
+// failure `openChat` does not handle, such as `InvalidInput`, rejects the promise.
+class Chat extends Context.Service<Chat, Effect.Success<typeof openChat>>()("live-rpc/Chat") {}
+
+export const chatOver = <E>(protocol: Layer.Layer<RpcClient.Protocol, E>) => {
+  const runtime = ManagedRuntime.make(Layer.effect(Chat, openChat).pipe(Layer.provide(protocol)));
+
+  const call = <A, E2>(use: (chat: Chat["Service"]) => Effect.Effect<A, E2>) =>
+    runtime.runPromise(Effect.flatMap(Chat, use));
+
+  return {
+    rooms: () => call((chat) => chat.rooms),
+
+    room: (name: string, token: string) => ({
+      read: (after: number) => call((chat) => chat.room(name, token).read(after)),
+      post: (text: string) => call((chat) => chat.room(name, token).post(text)),
+      remove: (id: number) => call((chat) => chat.room(name, token).remove(id)),
+    }),
+
+    close: () => runtime.dispose(),
+  };
+};
+
+// What a page calls: `const chat = connect("wss://chat.example/rpc")`, on the browser's own
+// WebSocket, then `await chat.room("lobby", token).post("Hello")`.
+export const connect = (url: string) =>
+  chatOver(connection(url).pipe(Layer.provide(Socket.layerWebSocketConstructorGlobal)));

package/examples/live-rpc/src/chat/Chat.ts

@@ -0,0 +1,77 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentMember } from "../identity/Identity.js";
+
+// A message's `id` counts up within its room, so a client asks for what came after the last
+// one it holds.
+export const Message = Schema.Struct({
+  id: Schema.Int,
+  author: Schema.String,
+  text: Schema.String,
+});
+
+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 a JSON binding, should these actions be served as one too: an rpc carries no status,
+// and an error without one answers 422 over HTTP.
+export class MessageNotFound extends Schema.TaggedError<MessageNotFound>()(
+  "MessageNotFound",
+  { id: Schema.Int },
+  { httpApiStatus: 404 },
+) {}
+
+// A refusal carries what the caller sent and no more: who wrote the message is for the actions
+// that read it, under their own rule.
+export class NotAuthor extends Schema.TaggedError<NotAuthor>()(
+  "NotAuthor",
+  { id: Schema.Int },
+  { httpApiStatus: 403 },
+) {}
+
+// Which room a call is about is not an input of any action: it travels beside the call, in
+// this header, as the token does. The client sets it; on the server, room.ts reads it. A call
+// without the header is about the default room, so `listRooms`, which is about none, sends none.
+export const roomHeader = "x-room";
+
+export const defaultRoom = "lobby";
+
+// Public: `caller: Action.Anyone`. A page shows the rooms before anyone has signed in.
+export const ListRooms = Action.make("listRooms", {
+  description: "List the rooms someone has posted in, and how many messages each holds.",
+  success: {
+    rooms: Schema.Array(Schema.Struct({ name: Schema.String, messages: Schema.Int })),
+  },
+  readOnly: true,
+  caller: Action.Anyone,
+});
+
+const signedIn = { caller: CurrentMember } as const;
+
+// Actions are unary: nothing streams. A page keeps up by calling this again on its open
+// socket, passing the last id it has seen.
+export const ReadMessages = Action.make("readMessages", {
+  ...signedIn,
+  description: "Read the room's messages after the given id; 0 reads them all.",
+  input: { after: Schema.Int },
+  success: { messages: Schema.Array(Message) },
+  readOnly: true,
+});
+
+export const PostMessage = Action.make("postMessage", {
+  ...signedIn,
+  description: "Post a message to the room.",
+  input: { text: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(500)) },
+  success: Message,
+  readOnly: false,
+});
+
+export const DeleteMessage = Action.make("deleteMessage", {
+  ...signedIn,
+  description: "Delete one of your own messages from the room.",
+  input: { id: Schema.Int },
+  error: [MessageNotFound, NotAuthor],
+  readOnly: false,
+});
+
+export const Messages = [ReadMessages, PostMessage, DeleteMessage] as const;

package/examples/live-rpc/src/chat/authorize.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentMember } from "../identity/Identity.js";
+import { CurrentRoom } from "./room.js";
+
+// The one rule: a member reads and writes only the rooms they belong to. It runs before every
+// protected handler, on every surface, and reads two request-time services: the caller, from
+// authentication, and the room, from the middleware.
+export const authorize = Effect.fn("authorize")(function* () {
+  const member = yield* CurrentMember;
+  const room = yield* CurrentRoom;
+
+  if (!member.rooms.includes(room)) {
+    return yield* new Action.Forbidden({ message: `Not a member of ${room}.` });
+  }
+});

package/examples/live-rpc/src/chat/handlers.ts

@@ -0,0 +1,50 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentMember } from "../identity/Identity.js";
+import { authorize } from "./authorize.js";
+import { ListRooms, Messages } from "./Chat.js";
+import { CurrentRoom } from "./room.js";
+import { MessageStore } from "./store.js";
+
+// A public action takes no `authorize`: nothing would run it.
+export const rooms = Action.implement(
+  ListRooms,
+  Effect.gen(function* () {
+    const store = yield* MessageStore;
+
+    return () => Effect.map(store.rooms, (found) => ({ rooms: found }));
+  }),
+);
+
+// The builder runs once, at startup: it is where a handler gets its startup services. The
+// caller and the room are read per call, inside each handler, because every message has its own.
+export const messages = Action.implement(
+  Messages,
+  Effect.gen(function* () {
+    const store = yield* MessageStore;
+
+    return {
+      readMessages: ({ after }) =>
+        Effect.gen(function* () {
+          const room = yield* CurrentRoom;
+
+          return { messages: yield* store.read(room, after) };
+        }),
+      postMessage: ({ text }) =>
+        Effect.gen(function* () {
+          const room = yield* CurrentRoom;
+          const member = yield* CurrentMember;
+
+          return yield* store.post(room, member.id, text);
+        }),
+      deleteMessage: ({ id }) =>
+        Effect.gen(function* () {
+          const room = yield* CurrentRoom;
+          const member = yield* CurrentMember;
+
+          return yield* store.remove(room, member.id, id);
+        }),
+    };
+  }),
+  { authorize },
+);

package/examples/live-rpc/src/chat/room.ts

@@ -0,0 +1,23 @@
+import { Context, Effect, Layer } from "effect";
+import { RpcMiddleware } from "effect/rpc";
+import { defaultRoom, roomHeader } from "./Chat.js";
+
+/**
+ * The room a message is about. A request-time service: handlers and `authorize` read it per
+ * call, and it has no Layer, because no one value of it is right for a whole server.
+ */
+export class CurrentRoom extends Context.Service<CurrentRoom, string>()("live-rpc/CurrentRoom") {}
+
+// Native Effect RPC middleware, declared as providing `CurrentRoom`. Listed in
+// `ActionRpc.layer`'s `middleware`, it runs around every rpc, once per message.
+export class ResolveRoom extends RpcMiddleware.Service<ResolveRoom, { provides: CurrentRoom }>()(
+  "live-rpc/ResolveRoom",
+) {}
+
+// The middleware's implementation. It gets the message's headers, which over a WebSocket are
+// the upgrade request's merged with the message's own, and runs the rest of the call with the
+// room they name, or the default room when they name none. It refuses nothing: whether the
+// caller may be in that room is `authorize`'s rule.
+export const resolveRoom = Layer.succeed(ResolveRoom, (call, { headers }) =>
+  Effect.provideService(call, CurrentRoom, headers[roomHeader] ?? defaultRoom),
+);

package/examples/live-rpc/src/chat/store.ts

@@ -0,0 +1,54 @@
+import { Context, Effect, Layer } from "effect";
+import { type Message, MessageNotFound, NotAuthor } from "./Chat.js";
+
+/**
+ * Where messages live, by room. That only its author deletes a message is checked here, in the
+ * data access, so no surface and no handler can skip it.
+ */
+export class MessageStore extends Context.Service<
+  MessageStore,
+  {
+    readonly rooms: Effect.Effect<ReadonlyArray<{ name: string; messages: number }>>;
+    readonly read: (room: string, after: number) => Effect.Effect<ReadonlyArray<Message>>;
+    readonly post: (room: string, author: string, text: string) => Effect.Effect<Message>;
+    readonly remove: (
+      room: string,
+      author: string,
+      id: number,
+    ) => Effect.Effect<void, MessageNotFound | NotAuthor>;
+  }
+>()("live-rpc/MessageStore") {
+  // DEMO ONLY: memory, lost when the process stops. A real store is another Layer of this
+  // service, chosen by the entrypoint.
+  static readonly layerMemory = Layer.sync(MessageStore, () => {
+    const rooms = new Map<string, { last: number; messages: ReadonlyArray<Message> }>();
+
+    const room = (name: string) => rooms.get(name) ?? { last: 0, messages: [] };
+
+    return MessageStore.of({
+      rooms: Effect.sync(() =>
+        Array.from(rooms, ([name, { messages }]) => ({ name, messages: messages.length })),
+      ),
+      read: (name, after) => Effect.sync(() => room(name).messages.filter(({ id }) => id > after)),
+      post: (name, author, text) =>
+        Effect.sync(() => {
+          const { last, messages } = room(name);
+          const message = { id: last + 1, author, text };
+
+          rooms.set(name, { last: message.id, messages: [...messages, message] });
+
+          return message;
+        }),
+      remove: Effect.fn("MessageStore.remove")(function* (name, author, id) {
+        const { last, messages } = room(name);
+        const message = messages.find((candidate) => candidate.id === id);
+
+        if (message === undefined) return yield* new MessageNotFound({ id });
+
+        if (message.author !== author) return yield* new NotAuthor({ id });
+
+        rooms.set(name, { last, messages: messages.filter((kept) => kept !== message) });
+      }),
+    });
+  });
+}

package/examples/live-rpc/src/client.ts

@@ -0,0 +1,37 @@
+import { NodeRuntime, NodeSocket } from "@effect/platform-node";
+import { Config, Console, Effect, Layer } from "effect";
+import { connection, openChat } from "./browser.js";
+
+// Entrypoint: `node --import tsx examples/live-rpc/src/client.ts`, with the server running.
+// The page's client, run from Node: the same `openChat`, given Node's WebSocket.
+const visit = Effect.gen(function* () {
+  const chat = yield* openChat;
+
+  // Two members on the one socket: each call is whoever its token says.
+  const ada = chat.room("lobby", "ada");
+  const grace = chat.room("lobby", "grace");
+
+  yield* Console.log("rooms, before signing in:", yield* chat.rooms);
+
+  const posted = yield* ada.post("Deploying at noon.");
+
+  yield* Console.log("ada posts:", posted);
+  yield* Console.log("grace reads:", yield* grace.read(posted.id - 1));
+  yield* Console.log("grace removes it:", yield* grace.remove(posted.id));
+  yield* Console.log("ada removes it:", yield* ada.remove(posted.id));
+  yield* Console.log("grace reads ops:", yield* chat.room("ops", "grace").read(0));
+  yield* Console.log("an expired token reads:", yield* chat.room("lobby", "expired").read(0));
+});
+
+const main = Effect.gen(function* () {
+  const url = yield* Config.String("CHAT_URL").pipe(Config.withDefault("ws://127.0.0.1:3000/rpc"));
+
+  // The socket belongs to `connection(url)`: provided once around the whole visit, it opens
+  // for it and closes when this `Effect.provide` ends. `Effect.scoped` holds the client alone.
+  yield* visit.pipe(
+    Effect.scoped,
+    Effect.provide(connection(url).pipe(Layer.provide(NodeSocket.layerWebSocketConstructor))),
+  );
+});
+
+NodeRuntime.runMain(main);

package/examples/live-rpc/src/identity/Identity.ts

@@ -0,0 +1,19 @@
+import { Context } from "effect";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+
+export interface Member {
+  readonly id: string;
+  readonly rooms: ReadonlyArray<string>;
+}
+
+/**
+ * Who sent a message. A protected action declares it, `caller: CurrentMember`; authentication
+ * provides it for each message, and a test calling in process provides it itself.
+ */
+export class CurrentMember extends Context.Service<CurrentMember, Member>()(
+  "live-rpc/CurrentMember",
+) {}
+
+// How a remote caller proves it is CurrentMember: a bearer token, the default scheme. Clients
+// import this descriptor with the binding; its verifier, in verifier.ts, stays on the server.
+export const Login = Authentication.make("live-rpc.Login", CurrentMember);