@nice-code/action 0.23.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
@@ -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
 });
@@ -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.