@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/docs/ActionRpc-events.md

@@ -0,0 +1,126 @@
+# Events over rpcs
+
+An [event type](Event.md) in an RPC binding is a stream rpc named after it, taking `{ input, cursor }`, which pushes each occurrence as the server reads it. A client's `watch(event, input, options)` holds it open over the client's protocol, a socket or HTTP, as `Action.client`'s does, and connects again after a drop, resuming from the last occurrence it delivered. Experimental, as [events](Event.md) are.
+
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [ActionRpc-failures.md](ActionRpc-failures.md). For one symbol, `grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions/dist/`.
+
+## Bind and serve events
+
+List the event types in `ActionRpc.make` beside the actions, and their implementations in `ActionRpc.layer`'s list ([ActionRpc.md](ActionRpc.md#serve-the-rpcs)); live-rpc's binding holds `MessagePosted` beside its actions. The same implementations serve HTTP and MCP too: [build-events/src/routes.ts](../examples/build-events/src/routes.ts) serves them all three ways, and says which serialization a watch needs over HTTP.
+
+```ts example=build-events/src/Rpc.ts
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+
+import {
+  BuildFinished,
+  FinishBuild,
+  PipelineStatus,
+  StartBuild,
+  TailLog,
+} from "./builds/Builds.js";
+import { DeployRequested, RequestDeploy } from "./deploys/Deploys.js";
+import { Login } from "./identity/Identity.js";
+
+// The RPC binding: each action an rpc named after it, and each event a stream rpc named after
+// it, which pushes each occurrence as the server reads it. Plain data, as the HTTP binding is.
+export const Rpc = ActionRpc.make(
+  [
+    FinishBuild,
+    StartBuild,
+    TailLog,
+    BuildFinished,
+    PipelineStatus,
+    RequestDeploy,
+    DeployRequested,
+  ],
+  { authentication: Login }
+);
+```
+
+What a stream rpc sends is on `ActionRpc.layer`; what a watch fails with, and when it reconnects, on `ActionRpc.client`.
+
+## Follow what a request names
+
+A watch runs the layer's `middleware` and its authentication as it starts, and again each time it connects, so its source reads the same request-time services an action's handler does. live-rpc's room travels in a header, which `ResolveRoom` turns into `CurrentRoom` ([ActionRpc.md](ActionRpc.md#send-request-context-with-a-call)): the event's check reads that room's messages, and its `key` is the room, so `postMessage`'s notify for one room wakes that room's pages alone.
+
+```ts example=live-rpc/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 { CurrentRoom } from "./room.js";
+import { MessageStore } from "./store.js";
+
+const idOf = Schema.decodeUnknownOption(
+  Schema.NumberFromString.pipe(Schema.check(Schema.isInt()))
+);
+
+// A cursor this source gives is `<epoch>:<id>`, the store's epoch and the id of the last message
+// a page holds, so one from before a restart of the memory store is told apart. A page starting
+// a watch gives the id alone, as `readMessages`' `after` is, which is the store's now.
+const positionOf = (epoch: string, cursor: string | null) => {
+  const parts =
+    cursor?.includes(":") === true ? cursor.split(":") : [epoch, cursor];
+
+  return parts.length === 2 && parts[0] === epoch
+    ? idOf(parts[1])
+    : Option.none();
+};
+
+// 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, not at its next read
+// every 5 seconds.
+export const messageEvents = Event.implement(
+  MessagePosted,
+  Effect.gen(function* () {
+    const store = yield* MessageStore;
+
+    return {
+      check: (_input, cursor) =>
+        Effect.gen(function* () {
+          const room = yield* CurrentRoom;
+          const last = yield* store.last(room);
+
+          const after = Option.filter(
+            positionOf(store.epoch, cursor),
+            (id) => id >= 0 && id <= last
+          );
+
+          // No cursor starts after the room's last message. One this room never gave, such as
+          // one from before a restart, is answered `truncated` from there: the page learns its
+          // messages may be another run's, and reads the room again with `readMessages`.
+          if (Option.isNone(after)) {
+            return {
+              cursor: `${store.epoch}:${last}`,
+              events: [],
+              truncated: cursor !== null,
+            };
+          }
+
+          const messages = yield* store.read(room, after.value);
+
+          return {
+            cursor: `${store.epoch}:${messages.at(-1)?.id ?? after.value}`,
+            // A message's id counts within its room and the store's epoch, so the event's id
+            // names all three: a watch drops an id it has seen, and after a restart of the memory
+            // store `lobby:1` is another message.
+            events: messages.map((data) => ({
+              eventId: `${store.epoch}:${room}:${data.id}`,
+              data,
+            })),
+          };
+        }),
+      // A notify for one room wakes that room's pages alone: the key is the room the watch's
+      // header names, read as `check` reads it.
+      key: () => CurrentRoom,
+    };
+  }),
+  { authorize }
+);
+```
+
+The page sends the room and its token with the watch: `RpcClient.withHeaders` wraps an Effect, so `browser.ts`'s `messages` sets them around the stream, and so on every request it sends again after a drop ([live-rpc/src/browser.ts](../examples/live-rpc/src/browser.ts)).
+
+- **No poll.** An rpc client holds the stream open; a client that cannot, such as a serverless function, watches over [HTTP](ActionHttp.md#serve-and-watch-events) or MCP.
+- **Which deployment.** A notify wakes the watches its process holds, so the process serving the sockets is the one whose `Event.Events` the handlers notify; another process's watches read the post at their next read, 5 seconds on. A log source fed by `emit` and a `subscription` hook need a server that outlives a request, as over MCP.

package/docs/ActionRpc-failures.md

@@ -1,7 +1,6 @@
 # ActionRpc failure modes
 
-What you see when something is wrong, and the fix. Search for a fragment of the message.
-The tasks are in [ActionRpc.md](ActionRpc.md).
+What you see when something is wrong, and the fix. Search for a fragment of the message. The tasks are in [ActionRpc.md](ActionRpc.md).
 
 - A type error on `middleware` naming `"Layer middleware fails only with the binding's errors and needs no client"`: a middleware declares an error neither the binding nor the built-ins hold, or is `requiredForClient`. Add the error to the binding's `error`, or check in the handler, declaring the error on its actions.
 - `Type 'HttpRouter' is not assignable to type 'never'` where the server is launched: an rpc protocol was provided around `HttpRouter.serve`, whose router it adds its route to. Provide the protocol to the rpc layer.

package/docs/ActionRpc.md

@@ -1,39 +1,39 @@
 # ActionRpc
 
-Actions as Effect RPC, on Effect's own `RpcServer` and `RpcClient`: one unary rpc per action.
+Actions as Effect RPC, on Effect's own `RpcServer` and `RpcClient`: one rpc per action, a stream rpc per event type, and native rpcs of your own beside them.
 
 A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [ActionRpc-failures.md](ActionRpc-failures.md). For one symbol, `grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions/dist/`: each declaration's JSDoc carries its rules and gotchas, and this page only what an example cannot show.
 
 ## Bind actions to rpcs
 
-A binding that holds a protected action names its authentication descriptor
-([Authentication.md](Authentication.md#declare-how-callers-sign-in)); the rules of each option
-are on `ActionRpc.Options`. Call `ActionRpc.make` once and export the binding:
+A binding that holds a protected action names its authentication descriptor ([Authentication.md](Authentication.md#declare-how-callers-sign-in)); the rules of each option are on `ActionRpc.Options`. Call `ActionRpc.make` once and export the binding:
 
 ```ts example=live-rpc/src/Rpc.ts
 import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
-import { ListRooms, Messages } from "./chat/Chat.js";
+
+import { ListRooms, MessagePosted, 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 });
+// The RPC binding: one native rpc per action, named after it, and a stream rpc for
+// `MessagePosted`, 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, MessagePosted], {
+  authentication: Login,
+});
 ```
 
-[kitchen-sink/src/Rpc.ts](../examples/kitchen-sink/src/Rpc.ts) adds `error`, what its
-middleware fails with.
+[kitchen-sink/src/Rpc.ts](../examples/kitchen-sink/src/Rpc.ts) adds `error`, what its middleware fails with.
 
 ## Serve the rpcs
 
-In the routes file, give `ActionRpc.layer` the binding and the implementations, and provide
-what it requires except the protocol and the startup services the entrypoint chooses: the
-service of each listed middleware and, where it serves a protected action, the authentication
-provider ([Authentication.md](Authentication.md#verify-credentials)).
+In the routes file, give `ActionRpc.layer` the binding and the implementations, and provide what it requires except the protocol and the startup services the entrypoint chooses: the service of each listed middleware and, where it serves a protected action, the authentication provider ([Authentication.md](Authentication.md#verify-credentials)).
 
 ```ts example=live-rpc/src/routes.ts
-import { Layer } from "effect";
 import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import { Layer } from "effect";
+
+import { messageEvents } from "./chat/events.js";
 import { messages, rooms } from "./chat/handlers.js";
 import { ResolveRoom, resolveRoom } from "./chat/room.js";
 import { authenticate } from "./identity/verifier.js";
@@ -42,28 +42,32 @@ import { Rpc } from "./Rpc.js";
 // The binding's rpcs on Effect's own RpcServer, the protected ones behind `Login`'s verifier;
 // `listRooms` needs no token.
 //
-// `ResolveRoom`, listed in `middleware`, provides `CurrentRoom`, which the handlers and
-// `authorize` read. Only something that runs per message can, since each message names its own
-// room: `Layer.succeed(CurrentRoom, "lobby")` provided here would leave the layer still
-// requiring it, in its type.
+// `ResolveRoom`, listed in `middleware`, provides `CurrentRoom`, which the handlers, the event's
+// source and `authorize` read; on a watch it runs as the watch starts, and each time it connects
+// again. Only something that runs per message can, since each message names its own room:
+// `Layer.succeed(CurrentRoom, "lobby")` provided here would leave the layer still requiring it,
+// in its type.
 //
-// It still requires three things, each chosen by whoever serves it. The protocol and its
+// It still requires four things, each chosen by whoever serves it. The protocol and its
 // serialization: server.ts gives it a WebSocket, and a test Effect's HTTP protocol, which
-// answers in memory. And `MessageStore`.
-export const rpc = ActionRpc.layer(Rpc, [rooms, messages], { middleware: [ResolveRoom] }).pipe(
-  Layer.provide([resolveRoom, authenticate]),
-);
+// answers in memory. `MessageStore`, and `Event.Events`, which `postMessage` notifies and the
+// watches wait on: one of each, provided around the whole server.
+export const rpc = ActionRpc.layer(Rpc, [rooms, messages, messageEvents], {
+  middleware: [ResolveRoom],
+}).pipe(Layer.provide([resolveRoom, authenticate]));
 ```
 
-The entrypoint serves the result with `HttpRouter.serve`; a test serves it in memory
-([Testing.md](Testing.md#test-rpcs)).
+The entrypoint serves the result with `HttpRouter.serve`; a test serves it in memory ([Testing.md](Testing.md#test-rpcs)).
 
 ```ts example=live-rpc/src/server.ts
 import { createServer } from "node:http";
+
 import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
 import { Config, Effect, Layer } from "effect";
 import { HttpRouter } from "effect/http";
 import { RpcSerialization, RpcServer } from "effect/rpc";
+
 import { MessageStore } from "./chat/store.js";
 import { rpc } from "./routes.js";
 
@@ -76,13 +80,16 @@ import { rpc } from "./routes.js";
 // serialization.
 const socket = rpc.pipe(
   Layer.provide(RpcServer.layerProtocolWebsocket({ path: "/rpc" })),
-  Layer.provide(RpcSerialization.layerJson),
+  Layer.provide(RpcSerialization.layerJson)
 );
 
 const server = Layer.unwrap(
   Effect.gen(function* () {
     // The loopback default serves this machine alone; HOST=0.0.0.0 lets others reach it.
-    const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));
+    const host = yield* Config.String("HOST").pipe(
+      Config.withDefault("127.0.0.1")
+    );
+
     const port = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
 
     return HttpRouter.serve(socket).pipe(
@@ -94,46 +101,41 @@ const server = Layer.unwrap(
           // does not bound it: Node's WebSocket server reads one of up to 100 MiB whole unless
           // told otherwise. A chat message is short, and a larger one closes the socket (1009).
           websocket: { maxPayload: 64 * 1024 },
-        }),
+        })
       ),
       // DEMO ONLY: messages live in this process's memory; a deployment provides a store that
       // lasts.
       Layer.provide(MessageStore.layerMemory),
+      // The pages watching a room are this process's sockets, so what wakes them lives in its
+      // memory too: one for the whole server. Several processes behind a balancer would each
+      // wake only their own pages, the others reading a post at their next read, 5 seconds on.
+      Layer.provide(Event.layerMemory)
     );
-  }),
+  })
 );
 
-Layer.launch(server).pipe(NodeRuntime.runMain);
+Layer.launch(server).pipe(NodeRuntime.runMain());
 ```
 
-Where the protocol goes, why one protocol takes one layer, and what a protocol with no router
-lacks are on `ActionRpc.layer`; the order of `middleware`, and which actions a middleware
-reading the identity may serve, on `ActionRpc.LayerOptions.middleware`.
-[kitchen-sink/src/identity/quota.ts](../examples/kitchen-sink/src/identity/quota.ts) is a limit
-in `middleware`, keyed on the caller, and
-[kitchen-sink/src/Rpc.ts](../examples/kitchen-sink/src/Rpc.ts) binds the protected actions
-alone for it.
-
-- **The same actions as JSON too.** Merge `ActionHttp.layer(Http, implementations)` beside the
-  rpc layer, each given its descriptor's provider
-  ([kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) defines both, and
-  [server.ts](../examples/kitchen-sink/src/server.ts) merges them): one provider given to both
-  is built once. The routes need what the rpcs did not: an `httpApiStatus` on a declared error,
-  by the rule on `Action.Options.error`, and router middleware for a service an `RpcMiddleware`
-  provides ([ActionHttp.md](ActionHttp.md#serve-the-routes)).
+Where the protocol goes, why one protocol takes one layer, and what a protocol with no router lacks are on `ActionRpc.layer`; the order of `middleware`, and which actions a middleware reading the identity may serve, on `ActionRpc.LayerOptions.middleware`. [kitchen-sink/src/identity/quota.ts](../examples/kitchen-sink/src/identity/quota.ts) is a limit in `middleware`, keyed on the caller, and [kitchen-sink/src/Rpc.ts](../examples/kitchen-sink/src/Rpc.ts) binds the protected actions alone for it.
+
+- **On Cloudflare Workers**, serve the rpcs from a Durable Object, with `@gjermundgaraba/effect-actions-cloudflare`'s `ActionDurableObject.layerWebSocket`.
+- **The same actions as JSON too.** Merge `ActionHttp.layer(Http, implementations)` beside the rpc layer, each given its descriptor's provider ([kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) defines both, and [server.ts](../examples/kitchen-sink/src/server.ts) merges them): one provider given to both is built once. The routes need what the rpcs did not: an `httpApiStatus` on a declared error, by the rule on `Action.Options.error`, and router middleware for a service an `RpcMiddleware` provides ([ActionHttp.md](ActionHttp.md#serve-the-routes)).
+- **An rpc of your own beside the actions.** Give `ActionRpc.make` native rpcs in `rpcs`, `ActionRpc.make(actions, { authentication, rpcs: RpcGroup.make(Upload) })`, each with its own schemas: under the binding's `authentication` each message authenticates as a protected action's does, and the client has their methods beside the actions'. Implement them with the binding's own `Rpc.rpcs.toLayer(handlers)`, whose handlers read the identity and authorize it themselves, and provide that to `ActionRpc.layer`, which otherwise does not compile. The rules are on `ActionRpc.Options.rpcs`.
+- **An action reporting progress or answering a stream is a stream rpc.** Over a WebSocket, or HTTP under `RpcSerialization.layerNdjson`, its values and elements arrive as sent; under `layerJson` over HTTP, all at the end (`ActionRpc.layer`).
 
 ## Call the rpcs
 
-`ActionRpc.client(Rpc)` has the methods of `ActionHttp.client`
-([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)), and what one call fails with is
-`ActionRpc.MethodError`. A page's client module:
+`ActionRpc.client(Rpc)` has the methods of `ActionHttp.client` ([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)), and what one call fails with is `ActionRpc.MethodError`. A page's client module:
 
 ```ts example=live-rpc/src/browser.ts
-import { Effect, Layer } from "effect";
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import { Effect, Layer, Stream } from "effect";
+import { Headers } from "effect/http";
 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 { MessagePosted, 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
@@ -146,7 +148,7 @@ import { Rpc } from "./Rpc.js";
 export const connection = (url: string) =>
   RpcClient.layerProtocolSocket().pipe(
     Layer.provide(Socket.layerWebSocket(url)),
-    Layer.provide(RpcSerialization.layerJson),
+    Layer.provide(RpcSerialization.layerJson)
   );
 
 // The chat as a page uses it, on the connection provided around it.
@@ -161,24 +163,50 @@ export const openChat = Effect.gen(function* () {
     room: (name: string, token: string) => {
       // A browser WebSocket cannot set an `Authorization` header on its upgrade, 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 });
+      const headers = { authorization: `Bearer ${token}`, [roomHeader]: name };
+      const here = RpcClient.withHeaders(headers);
 
       return {
-        // Called again and again while the page is open, with the last id it holds. A token
-        // may expire while the page stays open, so each refusal becomes what the page shows.
+        // What the room holds after the last id the page has. A token may expire while the
+        // page stays open, so each refusal becomes what the page shows.
         read: (after: number) =>
           client.readMessages({ after }).pipe(
             here,
-            Effect.map(({ messages }) => ({ access: "member" as const, messages })),
+            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: [] }),
-            }),
+              Forbidden: () =>
+                Effect.succeed({
+                  access: "not-a-member" as const,
+                  messages: [],
+                }),
+            })
           ),
 
         post: (text: string) => client.postMessage({ text }).pipe(here),
 
+        // Each message posted to the room after the last id the page holds: a page opening a
+        // room reads it, then watches from the last id it read, so a post between the two is
+        // not lost; 0 sends the room's history first. `watch` connects again after a drop and
+        // resumes from the last message it delivered, so the page never subscribes by hand; a
+        // `Gap` says some were missed, or are another run's, so the page reads the room again
+        // with `read(0)`. The headers go with the
+        // stream, as `here` puts them on a call, and so with every request it sends again. A
+        // refusal ends it, as when it connects again with a token that has expired.
+        messages: (after: number) =>
+          client
+            .watch(MessagePosted, {}, { cursor: String(after) })
+            .pipe(
+              Stream.updateService(
+                RpcClient.CurrentHeaders,
+                Headers.merge(Headers.fromInput(headers))
+              )
+            ),
+
         // 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) =>
@@ -188,7 +216,7 @@ export const openChat = Effect.gen(function* () {
             Effect.catchTags({
               MessageNotFound: () => Effect.succeed("removed" as const),
               NotAuthor: () => Effect.succeed("not-yours" as const),
-            }),
+            })
           ),
       };
     },
@@ -196,47 +224,48 @@ export const openChat = Effect.gen(function* () {
 });
 ```
 
-[live-rpc/src/client.ts](../examples/live-rpc/src/client.ts) runs it from Node, and
-[live-rpc/src/page.ts](../examples/live-rpc/src/page.ts) wraps it in promises for a page that is
-not one Effect program. The client's traps are on `ActionRpc.client`.
+[live-rpc/src/client.ts](../examples/live-rpc/src/client.ts) runs it from Node, and [live-rpc/src/page.ts](../examples/live-rpc/src/page.ts) wraps it in promises for a page that is not one Effect program. The client's traps are on `ActionRpc.client`.
+
+- **A server that closes a socket to refuse it.** Effect's socket client connects again after any close, backing off to every five seconds, for good. Give `RpcClient.layerProtocolSocket` the `retryPolicy` `ActionRpc.reconnectUntil(code)`, and a close with that code ends its calls instead.
+
+## Serve and watch events
+
+List [event types](Event.md) in the binding beside the actions: each is a stream rpc, which a client's `watch` holds open on its socket. How, with a room's messages over a WebSocket: [ActionRpc-events.md](ActionRpc-events.md).
 
 ## Send request context with a call
 
-What travels beside a call's input, such as a token, a tenant or a room, goes in headers: the
-client wraps the call in `RpcClient.withHeaders`, as `room` does in `browser.ts` above. On the
-server, authentication decodes the credential from those headers. Anything else is read by
-native `RpcMiddleware` listed in `ActionRpc.layer`'s `middleware`:
+What travels beside a call's input, such as a token, a tenant or a room, goes in headers: the client wraps the call in `RpcClient.withHeaders`, as `room` does in `browser.ts` above. On the server, authentication decodes the credential from those headers. Anything else is read by native `RpcMiddleware` listed in `ActionRpc.layer`'s `middleware`:
 
 ```ts example=live-rpc/src/chat/room.ts
 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") {}
+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 once per message.
-export class ResolveRoom extends RpcMiddleware.Service<ResolveRoom, { provides: CurrentRoom }>()(
-  "live-rpc/ResolveRoom",
-) {}
+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),
+  Effect.provideService(call, CurrentRoom, headers[roomHeader] ?? defaultRoom)
 );
 ```
 
-Why router middleware is no substitute over a WebSocket is on
-`ActionRpc.LayerOptions.middleware`.
+Why router middleware is no substitute over a WebSocket is on `ActionRpc.LayerOptions.middleware`.
 
-- **A cookie the browser attaches to the upgrade covers every message**
-  ([kitchen-sink/src/browser.ts](../examples/kitchen-sink/src/browser.ts)). A browser attaches
-  it from any page, so refuse a foreign `Origin` on the upgrade, with a request policy
-  ([Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication)).
+- **A cookie the browser attaches to the upgrade covers every message** ([kitchen-sink/src/browser.ts](../examples/kitchen-sink/src/browser.ts)). A browser attaches it from any page, so refuse a foreign `Origin` on the upgrade, with a request policy ([Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication)).

package/docs/ActionToolkit-failures.md

@@ -1,7 +1,6 @@
 # ActionToolkit failure modes
 
-What you see when something is wrong, and the fix. Search for a fragment of the message.
-The tasks are in [ActionToolkit.md](ActionToolkit.md).
+What you see when something is wrong, and the fix. Search for a fragment of the message. The tasks are in [ActionToolkit.md](ActionToolkit.md).
 
 - `Type 'X' is not assignable to type 'never'` where a turn or a call by hand runs, or `Service not found` in plain JavaScript: a request service, the caller first, is provided around the whole turn or call effect, never to the stream alone or to `layer`; a startup service's Layer is provided to `layer`.
 - A returned failure whose `result` is an `AiError` with reason `ToolParameterValidationError` (`failureOrigin: "parameters"`), not a declared error: the arguments did not decode, and neither `authorize` nor the handler ran.