@nice-code/action 0.20.0 → 0.21.0

package/README.md

@@ -33,7 +33,7 @@ The pieces:
 | **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) |
 | **Carrier** | How bytes actually move: `wsCarrier` / `httpCarrier` / `inMemoryCarrier` / `rtcCarrier` (connector side), `wsAcceptorCarrier` / `httpAcceptorCarrier` (acceptor side) |
-| **Transport** | A carrier wrapped with a security policy: `secureTransport` (handshake + optional encryption) or `plainTransport` |
+| **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 |
 
 > **One runtime per client.** A client (a frontend, a backend, a worker) has a *single* `ActionRuntime`
@@ -243,9 +243,12 @@ Key options: `clientEnv` (required), `storage` (required only when a carrier is
 
 ### Connecting — `connectChannel`
 
-The connector has one runtime and `connectChannel`s to each acceptor it talks to. It routes the channel's
-`toAcceptor` domains out over the transports (first = preferred, rest = fallback) and registers local
-handlers for the `toConnector` pushes from `onPush` — all derived from the channel, no restated lists.
+The connector has one runtime and `connectChannel`s to each acceptor it talks to. One call binds the
+shared facts — the channel (its codec + routing), the runtime, and one crypto identity over `storage` —
+into every transport, so you state them *once*. It routes the channel's `toAcceptor` domains out over the
+transports (first = preferred, rest = fallback) and registers local handlers for the `toConnector` pushes
+from `onPush` — all derived from the channel, no restated lists. It's the exact dial-out dual of
+`serveChannel`.
 
 ```ts
 import {
@@ -253,39 +256,35 @@ import {
   RuntimeCoordinate,
   ESecurityLevel,
   connectChannel,
-  secureTransport,
-  plainTransport,
   wsCarrier,
   httpCarrier,
 } from "@nice-code/action";
 
 export const clientRuntime = new ActionRuntime(RuntimeCoordinate.env("frontend"));
 
-// A carrier wrapped in a security policy = a transport.
-const wsTransport = secureTransport({
-  channel: appChannel,
-  runtime: clientRuntime,        // its coordinate is the authenticated identity in the handshake
-  storageAdapter,                // persists this client's crypto identity across reloads
+connectChannel(clientRuntime, appChannel, {
+  peer: serverCoord,
+  storage,                            // one crypto identity, fanned across every secure transport
   securityLevel: ESecurityLevel.encrypted,
-  carrier: wsCarrier("wss://api.example.com/resolve_action/ws"),
-});
-const httpTransport = plainTransport({
-  carrier: httpCarrier(() => ({ url: "https://api.example.com/resolve_action" })),
-});
-
-connectChannel(clientRuntime, serverCoord, {
-  channel: appChannel,
-  transports: [wsTransport, httpTransport], // secure WS preferred, HTTP fallback
+  transports: [
+    { carrier: wsCarrier("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)
 });
 ```
 
-`connectChannel(runtime, acceptorCoordinate, options)` returns the `ConnectorHandler` so you can later
+`connectChannel(runtime, channel, options)` returns the `ConnectorHandler` so you can later
 `handler.clearTransportCache()` (which also closes any live sockets) on teardown. Options:
 
-- **`channel`** — the shared channel; its `toAcceptor`/`toConnector` drive all routing.
-- **`transports`** — to the acceptor, in preference order; all carry the same `toAcceptor` domains and the
-  manager falls through on failure.
+- **`peer`** — the acceptor's `RuntimeCoordinate` this connection dials.
+- **`transports`** — declared by *carrier* `{ carrier, secure? }`, in preference order; all carry the
+  channel's `toAcceptor` domains and the manager falls through on failure. `secure` defaults to `true`.
+- **`storage`** — one backing store for the connection's crypto identity, fanned across every secure
+  transport. Required when any transport is secure; omit for a fully-plain connection. (`link` shares an
+  existing identity instead.)
+- **`securityLevel`** — default level for secure transports (`authenticated` if omitted; override per
+  transport with `securityLevel` on the descriptor).
 - **`onPush`** — handlers for the channel's `toConnector` pushes (optional; omit for send-only).
 - **`defaultTimeout`** — default per-action timeout.
 
@@ -348,9 +347,10 @@ export const appChannel = defineSecureChannel({
 ### Connector side — handle pushes with `onPush`
 
 ```ts
-connectChannel(clientRuntime, serverCoord, {
-  channel: appChannel,
-  transports: [wsTransport, httpTransport],
+connectChannel(clientRuntime, appChannel, {
+  peer: serverCoord,
+  storage,
+  transports: [{ carrier: wsCarrier(wsUrl) }, { carrier: httpCarrier(httpUrl), secure: false }],
   onPush: {
     // Keyed by the toConnector action id; input + output typed from the channel.
     position_update: async ({ player, x, y }) => {
@@ -489,7 +489,7 @@ and pushes still route to the right socket after the object wakes from eviction.
 
 ## Security levels
 
-`ESecurityLevel` (used by `secureTransport` and `serveChannel`):
+`ESecurityLevel` (used by `connectChannel` and `serveChannel`):
 
 - **`none`** — identity self-asserted, no handshake. Fastest; fine for dev/trusted networks.
 - **`authenticated`** — the handshake verifies identity (sign/verify + trust-on-first-use key pin);
@@ -502,7 +502,7 @@ crypto identity; the server pins client keys trust-on-first-use. Persisting the
 hibernatable carrier) lets an `authenticated`/`encrypted` connection resume after eviction without
 re-handshaking.
 
-The whole thing rides one channel: the same `secureTransport({ carrier: wsCarrier(...) })` works at any
+The whole thing rides one channel: the same secure `{ carrier: wsCarrier(...) }` transport works at any
 level, and `httpCarrier` runs the *same* secure session over HTTP (handshake → token → encrypted frames),
 with the request/reply correlation provided for free by the HTTP transaction. Pair a secure WS with a
 plain HTTP fallback by giving the acceptor a `httpAcceptorCarrier({ secure: false })`.
@@ -542,17 +542,19 @@ holds, with no reconnect.
 
 ```ts
 // Prefer the secure socket, but only once a session id exists; fall back to HTTP meanwhile.
-const wsTransport = secureTransport({
-  channel, runtime, storageAdapter, securityLevel,
-  available: () => sessionId != null,
-  carrier: wsCarrier(`${url}/ws`, {
-    // Only ever called once `available` passes, so no need for a placeholder cache key.
-    getTransportCacheKey: () => [sessionId],
-  }),
-});
-
-connectChannel(runtime, serverCoord, {
-  transports: [wsTransport, httpTransport], // ws preferred; HTTP serves while ws is gated off
+connectChannel(runtime, appChannel, {
+  peer: serverCoord,
+  storage,
+  transports: [
+    {
+      carrier: wsCarrier(`${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 },
+  ],
 });
 ```
 
@@ -656,17 +658,14 @@ try {
 
 ## Lower-level building blocks
 
-`connectChannel` and `serveChannel` are sugar; reach for these when you need finer control.
-
-- **`ActionRuntime.connectTo(coordinate, { transports, domains, actions, localHandlers, defaultTimeout })`**
-  — what `connectChannel` desugars to: build a `ConnectorHandler` for a peer, route domains/actions to
-  it, register it (plus any local push handlers), and apply — in one call. Use it directly when your
-  routing isn't expressed as a single channel.
+`connectChannel` and `serveChannel` are the supported entry points — they bind the channel, runtime, and
+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.
 
 - **Carriers vs transports.** A *carrier* (`wsCarrier`, `httpCarrier`, `inMemoryCarrier`, `rtcCarrier`) is
-  raw byte movement; a *transport* (`secureTransport`, `plainTransport`) wraps one with a security policy.
-  `connectTo` takes transports; `serveChannel` takes acceptor carriers (`wsAcceptorCarrier`,
-  `httpAcceptorCarrier`) and applies the security policy itself.
+  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
   `AcceptorHandler` for a channel by hand (the accept-in counterpart to a single transport), when you're
@@ -695,5 +694,5 @@ try {
   same-process peers) with no network.
 
 - **Custom carriers** — for any channel nice-action doesn't model natively, implement an
-  `IDuplexCarrierSource` / `IExchangeCarrierSource` and hand it to `secureTransport` / `plainTransport`
+  `IDuplexCarrierSource` / `IExchangeCarrierSource` and name it in `connectChannel`'s `transports`
   (connector) or build an acceptor carrier for `serveChannel`.

package/build/{ActionDevtoolsCore-D_JvgPmz.d.mts → ActionDevtoolsCore-baIHExfj.d.mts}

@@ -1,4 +1,4 @@
-import { Lr as IRuntimeCoordinate, _ as TActionProgress } from "./ActionPayload.types-D0DM-g65.mjs";
+import { Pr as IRuntimeCoordinate, _ as TActionProgress } from "./ActionPayload.types-DXGiw1SF.mjs";
 //#region ../nice-devtools-shared/src/components/PanelChrome.d.ts
 /** Where a devtools panel is docked. */
 type TDevtoolsPosition = "dock-bottom" | "dock-top" | "dock-left" | "dock-right";
@@ -76,4 +76,4 @@ declare class ActionDevtoolsCore {
 }
 //#endregion
 export { TDevtoolsActionStatus as a, IDevtoolsObservableDomain as i, IActionDevtoolsCoreOptions as n, TDevtoolsListener as o, IDevtoolsActionEntry as r, TDevtoolsPosition as s, ActionDevtoolsCore as t };
-//# sourceMappingURL=ActionDevtoolsCore-D_JvgPmz.d.mts.map
+//# sourceMappingURL=ActionDevtoolsCore-baIHExfj.d.mts.map

package/build/{ActionDevtoolsCore-dV-IVPcP.d.cts → ActionDevtoolsCore-dApyYvTS.d.cts}

@@ -1,4 +1,4 @@
-import { Lr as IRuntimeCoordinate, _ as TActionProgress } from "./ActionPayload.types-CnfWlkA1.cjs";
+import { Pr as IRuntimeCoordinate, _ as TActionProgress } from "./ActionPayload.types-CQM1HRw_.cjs";
 //#region ../nice-devtools-shared/src/components/PanelChrome.d.ts
 /** Where a devtools panel is docked. */
 type TDevtoolsPosition = "dock-bottom" | "dock-top" | "dock-left" | "dock-right";
@@ -76,4 +76,4 @@ declare class ActionDevtoolsCore {
 }
 //#endregion
 export { TDevtoolsActionStatus as a, IDevtoolsObservableDomain as i, IActionDevtoolsCoreOptions as n, TDevtoolsListener as o, IDevtoolsActionEntry as r, TDevtoolsPosition as s, ActionDevtoolsCore as t };
-//# sourceMappingURL=ActionDevtoolsCore-dV-IVPcP.d.cts.map
+//# sourceMappingURL=ActionDevtoolsCore-dApyYvTS.d.cts.map