@nice-code/action 0.22.0 → 0.24.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
@@ -281,7 +272,7 @@ connectChannel(clientRuntime, appChannel, {
   storage,                            // one crypto identity, fanned across every secure transport
   securityLevel: ESecurityLevel.encrypted,
   transports: [
-    { carrier: wsCarrier("wss://api.example.com/resolve_action/ws") }, // secure WS, preferred
+    { carrier: wsCarrier(() => ({ url: "wss://api.example.com/resolve_action/ws" })) }, // secure WS, preferred
     { carrier: httpCarrier(() => ({ url: "https://api.example.com/resolve_action" })), secure: false }, // plain HTTP fallback
   ],
   // onPush: { ... }  // handlers for the channel's toConnector pushes (see below)
@@ -353,7 +344,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
 });
@@ -366,7 +357,7 @@ export const appChannel = defineSecureChannel({
 connectChannel(clientRuntime, appChannel, {
   peer: serverCoord,
   storage,
-  transports: [{ carrier: wsCarrier(wsUrl) }, { carrier: httpCarrier(httpUrl), secure: false }],
+  transports: [{ carrier: wsCarrier(() => ({ url: wsUrl })) }, { carrier: httpCarrier(() => ({ url: httpUrl })), secure: false }],
   onPush: {
     // Keyed by the toConnector action id; input + output typed from the channel.
     position_update: async ({ player, x, y }) => {
@@ -579,13 +570,13 @@ connectChannel(runtime, appChannel, {
   storage,
   transports: [
     {
-      carrier: wsCarrier(`${url}/ws`, {
+      carrier: wsCarrier(() => ({ url: `${url}/ws` }), {
         // Only ever called once `available` passes, so no need for a placeholder cache key.
         getTransportCacheKey: () => [sessionId],
       }),
       available: () => sessionId != null, // ws preferred; HTTP serves while ws is gated off
     },
-    { carrier: httpCarrier(httpUrl), secure: false },
+    { carrier: httpCarrier(() => ({ url: httpUrl })), secure: false },
   ],
 });
 ```
@@ -694,18 +685,24 @@ 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, { clientEnv, storage, send, ... })`** — 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
   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 +717,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.