@nice-code/action 0.23.0 → 0.25.0

package/README.md

@@ -31,7 +31,7 @@ The pieces:
 | **ActionDomain** | A named group of typed actions (your API surface) |
 | **ActionSchema** | Input/output schema + declared error types for one action |
 | **ActionRuntime** | One per runtime; identifies it and dispatches actions to handlers |
-| **Channel** | The transport-agnostic routing contract between two runtimes, declared *by role* (`toAcceptor` / `toConnector`) — `defineChannel` (plain) or `defineSecureChannel` (binary + encryption) |
+| **Channel** | The transport-agnostic routing contract + binary wire identity between two runtimes, declared *by role* (`toAcceptor` / `toConnector`) with `defineChannel`. Security is a per-transport choice, not a channel one |
 | **Carrier** | How bytes actually move: `wsCarrier` / `httpCarrier` / `inMemoryCarrier` / `rtcCarrier` (connector side), `wsAcceptorCarrier` / `httpAcceptorCarrier` (acceptor side) |
 | **Transport** | A carrier wrapped with a security policy (handshake + optional encryption, or plain). You don't build these directly — `connectChannel` / `serveChannel` apply the policy to each carrier for you |
 | **RuntimeCoordinate** | Identifies an environment (frontend, backend, worker…) and is how actions are routed |
@@ -130,30 +130,21 @@ Define it once in code shared by both ends:
 import { defineChannel } from "@nice-code/action";
 
 export const appChannel = defineChannel({
-  toAcceptor: [userDomain],   // client → server requests
-  toConnector: [],            // server → client pushes (none here)
+  toAcceptor: [userDomain, lobbyDomain],  // client → server requests
+  toConnector: [lobbyDomain],             // server → client pushes (lobbyDomain is bidirectional)
 });
 ```
 
-For an authenticated/encrypted binary WebSocket, use **`defineSecureChannel`** instead — same role-based
-shape, plus it bakes in the positional binary wire dictionary and a version derived from the domains, so
-the codec and version can never drift between the two ends:
-
-```ts
-import { defineSecureChannel } from "@nice-code/action";
-
-export const appChannel = defineSecureChannel({
-  toAcceptor: [userDomain, lobbyDomain],  // requests
-  toConnector: [lobbyDomain],             // pushes (lobbyDomain is bidirectional)
-});
-```
+A channel carries both its routing (`toAcceptor` / `toConnector` domains) **and** its wire identity — the
+positional binary wire dictionary and a version derived from the domains, so the per-connection codec and
+version can never drift between the two ends. Whether a given transport actually runs encrypted is a
+per-transport choice (`secure` on `connectChannel`'s transports and the acceptor's `securityLevel`), not a
+property of the channel — so this one definition serves both plain and secure transports.
 
 > The lists are **positional** for the binary wire dictionary — **add new domains to the end** of their
 > list. Reordering shifts the version, and a stale peer is then cleanly rejected by the handshake instead
 > of silently misrouting a frame.
 
-A secure channel is still an ordinary channel, so it works anywhere a channel is expected.
-
 ---
 
 ## Runtimes & handlers
@@ -243,9 +234,17 @@ const server = serveChannel(runtime, appChannel, {
 - **`handlers`** — the acceptor handlers it built, one per duplex carrier (reach for these for per-handler
   `broadcast`).
 
-Key options: `clientEnv` (required), `storage` (required only when a carrier is secure — the default),
-`carriers`, `handlers`, `channelCases` (connection-aware cases — see below), plus `securityLevel` /
-`link` / `verifyKeyResolver` / `defaultTimeout`.
+Key options: `clientEnv` (optional — see below), `storage` (required only when a carrier is secure — the
+default), `carriers`, `handlers`, `channelCases` (connection-aware cases — see below), plus
+`securityLevel` / `link` / `verifyKeyResolver` / `defaultTimeout`.
+
+> **One server, several client envs (multi-role).** `clientEnv` is **optional**. A result or push to a
+> *connected* client always routes back over the carrier it actually connected on (the acceptor knows each
+> client's exact coordinate from its handshake), so a single `serveChannel` accepts clients of *different*
+> envs — e.g. a `wallet` role and a `partner` role on one bridge — over one acceptor. Omit `clientEnv`
+> entirely for a multi-role server; only set it if you want a scoring fallback for returning to a client
+> that is *no longer connected* (the offline case). This replaces the old workaround of standing up a
+> second `serveChannel` per role.
 
 > On Cloudflare, [`@nice-code/action/platform/cloudflare`](#cloudflare-durable-objects) collapses the
 > Durable Object carrier + storage + lifecycle boilerplate into a single `serveDurableObject` call.
@@ -353,7 +352,7 @@ export const lobbyDomain = appRoot.createChildDomain({
   },
 });
 
-export const appChannel = defineSecureChannel({
+export const appChannel = defineChannel({
   toAcceptor: [userDomain, lobbyDomain],  // start_feed flows here
   toConnector: [lobbyDomain],             // position_update pushes back here
 });
@@ -462,7 +461,7 @@ export class MyDurableObject extends DurableObject {
 }
 ```
 
-`serveDurableObject(ctx, channel, options)` takes the same `serveChannel` surface (`clientEnv`,
+`serveDurableObject(ctx, channel, options)` takes the same `serveChannel` surface (`clientEnv` — optional,
 `handlers`, `channelCases`, `connectionState`, …) plus the host knobs:
 
 - **`runtime`** — this DO's runtime.
@@ -475,6 +474,45 @@ For finer control the lower-level pieces are still exported: `cloudflareDurableO
 builds just the `{ carriers, storage, onServed }` host adapter (hand it to `serveHost`), and
 `durableObjectWsCarrier` / `durableObjectStorage` build the individual carrier / storage adapter.
 
+### Fanning HTTP out to a per-id Durable Object — `forwardExchangeToDurableObject`
+
+When each DO instance is one *thing* (a bridge, a room, a game) and the Worker has to pick the right one
+per request, route by the **URL** — a secure exchange body is opaque to the Worker (handshake / encrypted
+frames), so it can't choose by inspecting the body. `forwardExchangeToDurableObject` picks the stub, hands
+the request to its `fetch` (where `serveDurableObject` serves the exchange), and answers the CORS
+`OPTIONS` preflight *at the edge* so a per-id DO is never woken (or billed) just to reply to a preflight:
+
+```ts
+import { forwardExchangeToDurableObject } from "@nice-code/action/platform/cloudflare";
+
+export default {
+  fetch(request: Request, env: Env) {
+    return forwardExchangeToDurableObject(request, (req, url) => {
+      const bridgeId = url.pathname.split("/")[2];        // e.g. /bridge/:id/action
+      return env.BRIDGE.get(env.BRIDGE.idFromName(bridgeId));
+    });
+  },
+};
+```
+
+Inside the DO, serve the exchange (and the WS upgrade) exactly as above — make the HTTP fallback secure so
+the whole path is handshake-protected:
+
+```ts
+this._server = serveDurableObject(this.ctx, bridgeChannel, { runtime, httpFallback: "secure" });
+// fetch(request) => this._server.fetch(request)
+```
+
+The matching connector points its `httpCarrier` at `/bridge/:id/action`. `pickStub` may be async (e.g. to
+resolve an id first) and receives the parsed `URL` alongside the request.
+
+> Need to handle the exchange yourself instead of handing the endpoint to `serveChannel`? The secure
+> exchange acceptor and its plain `{k:"act",w}` envelope codec are exported from the **main** entry:
+> `ExchangeAcceptor` (drive the handshake + token sessions + decrypt over your own `fetch`), and
+> `encodeExchange` / `decodeExchangeRequest` / `decodeExchangeReply` (read/write the plain envelope when
+> you must inspect or rewrite the wire before running it). Secure bodies are only decodable through an
+> `ExchangeAcceptor` session — route-before-decode by URL, as above.
+
 ### Per-connection state + broadcast (stateful DOs)
 
 A presence/room DO that tracks who's on each socket and fans messages out adds two knobs —
@@ -694,18 +732,25 @@ try {
 crypto identity for you. The pieces below are what they're built on; reach for them only for the rare
 routing that isn't a single channel.
 
+> Most of these live under the **`@nice-code/action/advanced`** subpath, not the main entry — the default
+> `@nice-code/action` export stays focused on the high-level API (`acceptChannel` /
+> `acceptChannelConnections` and the carriers remain on the main entry). Import the raw handler classes
+> (`AcceptorHandler`, `ConnectorHandler`, …), the transport classes/codec, and the handshake primitives
+> from `@nice-code/action/advanced`.
+
 - **Carriers vs transports.** A *carrier* (`wsCarrier`, `httpCarrier`, `inMemoryCarrier`, `rtcCarrier`) is
   raw byte movement; a *transport* wraps one with a security policy. You name carriers in
   `connectChannel`'s `transports` (the `secure` flag picks the policy) and in `serveChannel`'s `carriers`;
   the transport wrapping happens internally, so there's no separate transport-builder to call.
 
-- **`acceptChannel(runtime, channel, { clientEnv, storageAdapter, send, ... })`** — build the secure
+- **`acceptChannel(runtime, channel, { storage, send, clientEnv?, ... })`** — build the secure
   `AcceptorHandler` for a channel by hand (the accept-in counterpart to a single transport), when you're
-  not using `serveChannel`. Pair it with **`acceptChannelConnections(handler, channel, cases)`** to
+  not using `serveChannel`. `clientEnv` is optional here too (one acceptor serves several client envs — a
+  live connection always wins the return path). Pair it with **`acceptChannelConnections(handler, channel, cases)`** to
   register connection-aware execution — each case receives the request *and* the originating connection:
 
   ```ts
-  const acceptor = acceptChannel(runtime, appChannel, { clientEnv, storageAdapter, send });
+  const acceptor = acceptChannel(runtime, appChannel, { clientEnv, storage, send });
   const cases = acceptChannelConnections(acceptor, appChannel, {
     join: ({ input }, conn) => { if (conn != null) rooms.add(input.roomId, conn); return { ok: true }; },
   });
@@ -720,7 +765,7 @@ routing that isn't a single channel.
   `AcceptorHandler`.
 
 - **`createBinaryWireAdapter(domains)`** / **`createBinaryWireSessionFactory(domains)`** — the positional
-  binary codecs `defineSecureChannel` builds for you; useful for custom carriers.
+  binary codecs `defineChannel` builds for you; useful for custom carriers.
 
 - **`createInMemoryChannelPair()` / `inMemoryCarrier`** — wire two runtimes together in-process (tests,
   same-process peers) with no network.