@nice-code/action 0.13.0 → 0.15.0

package/README.md

@@ -14,10 +14,13 @@ Peer deps: `valibot` (or any [Standard Schema](https://github.com/standard-schem
 
 - **ActionDomain** — a named group of typed actions (like an API surface)
 - **ActionSchema** — input/output schema + declared error types for one action
-- **ActionRuntime** — processes incoming requests and dispatches them to handlers
+- **ActionRuntime** — one per client; processes incoming requests and dispatches them to handlers. Wire each backend it talks to with `runtime.connectTo(...)`
 - **ActionLocalHandler** — executes actions in the current process
-- **ActionExternalClientHandler** — forwards/receives actions over HTTP or WebSocket
-- **RuntimeCoordinate** — identifies an environment (frontend, backend, worker…)
+- **ActionExternalClientHandler** — forwards/receives actions over HTTP or WebSocket to another client
+- **ActionServerHandler** — server-side handler for backends accepting many client connections over one open channel; ferries results back and can push/broadcast server-initiated actions to clients
+- **RuntimeCoordinate** — identifies an environment (frontend, backend, worker…) and is how actions are routed
+
+> **One runtime per client.** A client (a frontend, a backend, a worker) has a *single* `ActionRuntime` identifying it across every peer it talks to — not one per feature or per backend. Register your local handlers on it, then call `runtime.connectTo(peerCoordinate, { transports, domains })` once per peer to wire the outbound channels. This keeps one identity (and one crypto identity, for secure channels) per client and avoids routing ambiguity.
 
 ---
 
@@ -140,33 +143,80 @@ app.post("/resolve_action", async (c) => {
 });
 ```
 
-### Client (external handler)
+Or fold the whole endpoint (CORS + preflight, the `/action` POST, an optional WebSocket upgrade, and a
+404 fallback) into one web-standard `fetch` handler with `createActionFetchHandler`:
 
 ```ts
-import {
-  ActionRuntime,
-  ActionExternalClientHandler,
-  RuntimeCoordinate,
-  HttpTransport,
-} from "@nice-code/action";
+import { createActionFetchHandler } from "@nice-code/action";
+
+// Works anywhere Request/Response exist (Workers, Durable Objects, Bun, …).
+const fetchHandler = createActionFetchHandler(serverRuntime, {
+  // Omit for an HTTP-only endpoint. For a Durable Object:
+  onWebSocketUpgrade: () => {
+    const pair = new WebSocketPair();
+    ctx.acceptWebSocket(pair[1]);
+    return new Response(null, { status: 101, webSocket: pair[0] });
+  },
+});
+
+// async fetch(request) { return fetchHandler(request); }
+```
+
+By default a `POST` whose path ends in `/action` carries an action wire, and an `Upgrade: websocket`
+request whose path ends in `/ws` is upgraded; override with `isActionPath` / `isWebSocketPath`.
+
+### Client (connecting to a backend)
+
+A client has one runtime. Call `connectTo` once per backend it talks to: it builds the
+`ActionExternalClientHandler`, routes the listed `domains`/`actions` to it, registers it, and applies —
+all in one call.
+
+```ts
+import { ActionRuntime, RuntimeCoordinate, HttpTransport } from "@nice-code/action";
 
 export const clientCoord = RuntimeCoordinate.env("frontend");
 export const serverCoord = RuntimeCoordinate.env("backend");
 
+// The single runtime that identifies this client everywhere.
+export const clientRuntime = new ActionRuntime(clientCoord);
+
 // Transport definitions are plain, reusable objects you construct once.
 const serverHttp = HttpTransport.create({
   createRequest: () => ({ url: "https://api.example.com/resolve_action" }),
 });
 
+// Wire the backend — route the userDomain's actions over this transport.
+clientRuntime.connectTo(serverCoord, {
+  transports: [serverHttp],
+  domains: [userDomain],
+});
+
+// Connect to more backends on the same runtime as needed:
+// clientRuntime.connectTo(authCoord, { transports: [authWs], domains: [authDomain] });
+```
+
+`connectTo(peerCoordinate, options)` accepts:
+
+- `transports` — one or more transports, tried in declared order (first = preferred, e.g. a WebSocket; later = fallback, e.g. HTTP)
+- `domains` / `actions` — which domains (or individual actions) route to this peer
+- `localHandlers` — handlers that run *locally* on this same channel, e.g. to answer **server→client pushes** (see [Bi-directional communication](#bi-directional-communication-server--client))
+- `defaultTimeout` — default per-action timeout
+
+It returns the `ActionExternalClientHandler` so you can later `handler.clearTransportCache()` (which also
+closes any live sockets) on teardown.
+
+<details>
+<summary>What <code>connectTo</code> desugars to</summary>
+
+```ts
 const serverHandler = new ActionExternalClientHandler({
   runtimeCoordinate: serverCoord,
   transports: [serverHttp],
 }).forDomain(userDomain);
 
-export const clientRuntime = new ActionRuntime(clientCoord)
-  .addHandlers([serverHandler])
-  .apply();
+clientRuntime.addHandlers([serverHandler]).apply();
 ```
+</details>
 
 ---
 
@@ -191,6 +241,162 @@ const output = await userDomain.action.getUser
 
 ---
 
+## Bi-directional communication (server ⇆ client)
+
+Actions flow both ways. The frontend calls the backend the way shown above; the **backend can call the
+frontend** over the *same* open connection — no second channel, no polling. This needs a duplex transport
+(a WebSocket), so both ends share one channel.
+
+The shape:
+
+- **Define the client-facing actions in their own domain**, shared by both ends (same as any other domain).
+- **On the client**, register a *local handler* for those actions and route them as `localHandlers` on the
+  `connectTo` channel — so when the server pushes a request, the client executes it locally and the result
+  is sent straight back over the same socket.
+- **On the server**, use an `ActionServerHandler` (one per connection-accepting channel). It ferries
+  results back to the originating socket automatically, and gives you `pushToClient` / `broadcast` to
+  initiate actions toward connected clients.
+
+### Shared domains
+
+```ts
+// Client implements these — the server pushes them.
+export const clientPushDomain = appRoot.createChildDomain({
+  domain: "client_push",
+  actions: {
+    notify: actionSchema()
+      .input({ schema: v.object({ text: v.string() }) })
+      .output({ schema: v.object({ seen: v.boolean() }) }),
+  },
+});
+
+// Server implements these — the client calls them (normal direction).
+export const gameDomain = appRoot.createChildDomain({
+  domain: "game",
+  actions: {
+    join: actionSchema()
+      .input({ schema: v.object({ roomId: v.string() }) })
+      .output({ schema: v.object({ ok: v.boolean() }) }),
+  },
+});
+```
+
+### Server side
+
+```ts
+import {
+  ActionRuntime,
+  RuntimeCoordinate,
+  createServerHandler,
+} from "@nice-code/action";
+
+const backendCoord = RuntimeCoordinate.env("backend");
+const clientEnv = RuntimeCoordinate.env("frontend"); // the env of connecting clients
+
+const serverRuntime = new ActionRuntime(backendCoord);
+
+// Handles inbound client→server actions locally.
+const gameHandler = gameDomain.wrapAsLocalHandler({
+  join: async ({ roomId }) => ({ ok: true }),
+});
+
+// Accepts many client connections over one channel; you tell it how to send a frame.
+const serverHandler = createServerHandler<WebSocket>({
+  clientEnv,
+  formatMessage: adapter, // e.g. createBinaryWsAdapter([gameDomain, clientPushDomain])
+  send: (ws, frame) => ws.send(frame),
+  runtime: serverRuntime, // lets broadcast() find the runtime without threading it through
+});
+
+serverRuntime.addHandlers([gameHandler, serverHandler]).apply();
+
+// Per inbound socket message (e.g. a Durable Object's webSocketMessage):
+//   serverHandler.receive(ws, message);
+// On close/error:
+//   serverHandler.dropConnection(ws);
+```
+
+Push a server-initiated action to a specific client (await its reply just like any action), or fan one
+out to everyone:
+
+```ts
+// One client — pass the connection token or the client's RuntimeCoordinate.
+const running = serverHandler.pushToClient(
+  serverRuntime,
+  ws,
+  clientPushDomain.action.notify.request({ text: "hi" }),
+);
+const result = await running.waitForResultPayload();
+console.log(result.output); // { seen: true }
+
+// Everyone currently connected (fire-and-forget); skip the origin, or filter with `where`.
+serverHandler.broadcast(() => clientPushDomain.action.notify.request({ text: "room update" }), {
+  except: originWs,
+  where: (ws) => ws.deserializeAttachment()?.role === "player",
+});
+```
+
+When an inbound client action needs the originating socket (to reply on it, register it in a room, etc.),
+use `forConnectionDomainCases` — each case receives the request *and* that client's live connection,
+saving the manual `getConnectionForClient(action.context.originClient)` lookup:
+
+```ts
+const gameCases = serverHandler.forConnectionDomainCases(gameDomain, {
+  join: ({ input }, conn) => {
+    if (conn != null) rooms.add(input.roomId, conn);
+    return { ok: conn != null };
+  },
+});
+
+serverRuntime.addHandlers([gameCases, serverHandler]).apply();
+```
+
+### Client side
+
+The client registers a local handler for the pushed actions and hands it to `connectTo` as a
+`localHandler` on the WebSocket channel. Results route back over the same socket automatically.
+
+```ts
+const clientRuntime = new ActionRuntime(RuntimeCoordinate.env("frontend"));
+
+// Execute server→client pushes locally.
+const pushHandler = clientPushDomain.wrapAsLocalHandler({
+  notify: async ({ text }) => {
+    showToast(text);
+    return { seen: true };
+  },
+});
+
+clientRuntime.connectTo(backendCoord, {
+  transports: [gameWs], // a WebSocketTransport (duplex)
+  domains: [gameDomain], // client→server actions routed out over this socket
+  localHandlers: [pushHandler], // server→client pushes handled locally on the same socket
+});
+```
+
+### Durable Objects / hibernation
+
+For transports whose sockets outlive process eviction (e.g. a Durable Object's hibernatable
+WebSockets), pair the server handler with `createHibernatableWsServerAdapter`. It owns persistence:
+it stores each connection's binding on bind and replays them on construction, so results and pushes
+still route to the right socket after the object wakes.
+
+```ts
+import { createHibernatableWsServerAdapter } from "@nice-code/action";
+
+const wsServer = createHibernatableWsServerAdapter({
+  handler: serverHandler,
+  getWebSockets: () => ctx.getWebSockets(),
+  getAttachment: (ws) => ws.deserializeAttachment(),
+  setAttachment: (ws, binding) => ws.serializeAttachment(binding),
+});
+
+// webSocketMessage(ws, msg) => wsServer.receive(ws, msg);
+// webSocketClose/Error(ws) => wsServer.drop(ws);
+```
+
+---
+
 ## React Query integration
 
 ```ts
@@ -253,17 +459,18 @@ devtools.attachToDomain(appRoot);
 ## WebSocket transport
 
 ```ts
-import { WebSocketTransport } from "@nice-code/action";
+import { ActionRuntime, WebSocketTransport, HttpTransport } from "@nice-code/action";
 
 const serverWs = WebSocketTransport.create({
   createWebSocket: () => new WebSocket("wss://api.example.com/resolve_action/ws"),
   getTransportCacheKey: () => ["wss://api.example.com/resolve_action/ws"],
 });
 
-const serverHandler = new ActionExternalClientHandler({
-  runtimeCoordinate: serverCoord,
-  transports: [serverWs, serverHttp], // WebSocket preferred, HTTP as fallback
-}).forDomain(userDomain);
+// One channel, WebSocket preferred with HTTP as fallback.
+clientRuntime.connectTo(serverCoord, {
+  transports: [serverWs, serverHttp],
+  domains: [userDomain],
+});
 ```
 
 The socket is opened lazily and reused across actions sharing a `getTransportCacheKey`. Multiple
@@ -276,6 +483,73 @@ derive the request per action straight from the params (e.g.
 control over readiness (support detection, async init), `WebSocketTransport` / `CustomTransport` also
 offer `.createAdvanced({ getTransport })`.
 
+A WebSocket is duplex, so it's also the channel the server pushes back over — see
+[Bi-directional communication](#bi-directional-communication-server--client).
+
+### Secure WebSocket channel
+
+For an authenticated (and optionally end-to-end encrypted) socket, define the channel once in shared
+code and hand it to both ends — the binary codec and wire-dictionary version can never drift apart. The
+client identifies itself with its runtime coordinate + a persisted crypto identity; the server pins
+client keys trust-on-first-use.
+
+```ts
+// shared.ts — both ends import this
+import { defineSecureWsChannel } from "@nice-code/action";
+
+// Domains in a stable order (the binary wire dictionary is positional — add new ones to the end).
+export const channel = defineSecureWsChannel({ domains: [userDomain, clientPushDomain] });
+```
+
+```ts
+// client.ts
+import { createSecureWebSocketTransport, ESecurityLevel } from "@nice-code/action";
+
+const secureWs = createSecureWebSocketTransport({
+  channel,
+  runtime: clientRuntime, // its coordinate is the authenticated identity in the handshake
+  storageAdapter, // persists this client's verify key across reloads (@nice-code/util)
+  securityLevel: ESecurityLevel.encrypted, // none | authenticated | encrypted
+  url: "wss://api.example.com/meta/ws",
+});
+
+clientRuntime.connectTo(serverCoord, {
+  transports: [secureWs, serverHttp], // secure WS preferred, HTTP fallback
+  domains: [userDomain],
+  localHandlers: [pushHandler], // server pushes ride the same secure socket
+});
+```
+
+```ts
+// server.ts (e.g. inside a Durable Object)
+import {
+  createSecureActionServerHandler,
+  createHibernatableWsServerAdapter,
+} from "@nice-code/action";
+
+const serverHandler = createSecureActionServerHandler<WebSocket>({
+  channel, // same shared channel
+  clientEnv, // env of the connecting clients
+  runtime: serverRuntime, // its coordinate is the server identity in the handshake
+  storageAdapter, // backs BOTH the server's identity and its TOFU key pins — use persistent storage
+  send: (ws, frame) => ws.send(frame),
+  // securityLevel defaults to negotiating any of none / authenticated / encrypted per connection
+});
+
+const wsServer = createHibernatableWsServerAdapter({
+  handler: serverHandler,
+  getWebSockets: () => ctx.getWebSockets(),
+  getAttachment: (ws) => ws.deserializeAttachment(),
+  setAttachment: (ws, binding) => ws.serializeAttachment(binding),
+});
+```
+
+Security levels: `none` (self-asserted identity, fine for dev/trusted networks), `authenticated`
+(handshake-verified identity), `encrypted` (authenticated + per-connection AES-GCM payload encryption).
+A server can accept a negotiable set so a single endpoint serves all three. Persisting the channel's
+binding (via the hibernatable adapter) lets an `authenticated`/`encrypted` connection resume after the
+server is evicted without re-handshaking.
+
 ---
 
 ## RuntimeCoordinate