@nice-code/action 0.22.0 → 0.24.0

package/build/devtools/browser/index.d.cts

@@ -1,4 +1,4 @@
-import { a as TDevtoolsActionStatus, i as IDevtoolsObservableDomain, n as IActionDevtoolsCoreOptions, o as TDevtoolsListener, r as IDevtoolsActionEntry, s as TDevtoolsPosition, t as ActionDevtoolsCore } from "../../ActionDevtoolsCore-CQ0vrvPD.cjs";
+import { a as TDevtoolsActionStatus, i as IDevtoolsObservableDomain, n as IActionDevtoolsCoreOptions, o as TDevtoolsListener, r as IDevtoolsActionEntry, s as TDevtoolsPosition, t as ActionDevtoolsCore } from "../../ActionDevtoolsCore-37JP4bOG.cjs";
 
 //#region src/devtools/browser/NiceActionDevtools.d.ts
 interface INiceActionDevtoolsProps {

package/build/devtools/browser/index.d.mts

@@ -1,4 +1,4 @@
-import { a as TDevtoolsActionStatus, i as IDevtoolsObservableDomain, n as IActionDevtoolsCoreOptions, o as TDevtoolsListener, r as IDevtoolsActionEntry, s as TDevtoolsPosition, t as ActionDevtoolsCore } from "../../ActionDevtoolsCore-CiLBYC3K.mjs";
+import { a as TDevtoolsActionStatus, i as IDevtoolsObservableDomain, n as IActionDevtoolsCoreOptions, o as TDevtoolsListener, r as IDevtoolsActionEntry, s as TDevtoolsPosition, t as ActionDevtoolsCore } from "../../ActionDevtoolsCore-Cgq-go1R.mjs";
 
 //#region src/devtools/browser/NiceActionDevtools.d.ts
 interface INiceActionDevtoolsProps {

package/build/devtools/server/index.d.cts

@@ -1,4 +1,4 @@
-import { a as TDevtoolsActionStatus, i as IDevtoolsObservableDomain, n as IActionDevtoolsCoreOptions, o as TDevtoolsListener, r as IDevtoolsActionEntry, t as ActionDevtoolsCore } from "../../ActionDevtoolsCore-CQ0vrvPD.cjs";
+import { a as TDevtoolsActionStatus, i as IDevtoolsObservableDomain, n as IActionDevtoolsCoreOptions, o as TDevtoolsListener, r as IDevtoolsActionEntry, t as ActionDevtoolsCore } from "../../ActionDevtoolsCore-37JP4bOG.cjs";
 
 //#region src/devtools/server/NiceActionServerDevtools.d.ts
 type TServerDevtoolsLogFn = (message: string, data?: Record<string, unknown>) => void;

package/build/devtools/server/index.d.mts

@@ -1,4 +1,4 @@
-import { a as TDevtoolsActionStatus, i as IDevtoolsObservableDomain, n as IActionDevtoolsCoreOptions, o as TDevtoolsListener, r as IDevtoolsActionEntry, t as ActionDevtoolsCore } from "../../ActionDevtoolsCore-CiLBYC3K.mjs";
+import { a as TDevtoolsActionStatus, i as IDevtoolsObservableDomain, n as IActionDevtoolsCoreOptions, o as TDevtoolsListener, r as IDevtoolsActionEntry, t as ActionDevtoolsCore } from "../../ActionDevtoolsCore-Cgq-go1R.mjs";
 
 //#region src/devtools/server/NiceActionServerDevtools.d.ts
 type TServerDevtoolsLogFn = (message: string, data?: Record<string, unknown>) => void;

package/build/httpAcceptorCarrier-C3S_bDkL.cjs

@@ -0,0 +1,454 @@
+const require_createHibernatableWsServerAdapter = require("./createHibernatableWsServerAdapter-BNi4k9j3.cjs");
+let _nice_code_util = require("@nice-code/util");
+//#region src/ActionRuntime/Transport/Carrier/Carrier.types.ts
+/**
+* Narrow a carrier source to the exchange shape via its `shape` discriminant — the one branch the
+* internal `transport()` factory uses to pick the duplex vs exchange transport. A duplex source carries
+* no `shape`, so the `else` branch is the duplex one.
+*/
+function isExchangeCarrierSource(carrier) {
+	return "shape" in carrier && carrier.shape === "exchange";
+}
+//#endregion
+//#region src/ActionRuntime/Transport/createTransport.ts
+function transport(options) {
+	const { carrier, channel, available, label } = options;
+	const labelFor = label ?? carrier.carrierLabel;
+	let security;
+	if (options.secure) {
+		const link = options.link ?? (options.storage != null ? new _nice_code_util.ClientCryptoKeyLink({ storageAdapter: options.storage }) : void 0);
+		if (link == null) throw new Error("transport: a secure transport requires `link` or `storage` for the crypto identity.");
+		security = {
+			securityLevel: options.securityLevel ?? "authenticated",
+			link,
+			localCoordinate: options.runtime.coordinate.toJsonObject(),
+			dictionaryVersion: channel.dictionaryVersion
+		};
+	}
+	if (isExchangeCarrierSource(carrier)) return require_createHibernatableWsServerAdapter.ExchangeTransport.create({
+		openCarrier: carrier.open,
+		getTransportCacheKey: carrier.getCacheKey,
+		available,
+		getRouteInfo: carrier.getRouteInfo,
+		label: labelFor,
+		security
+	});
+	return require_createHibernatableWsServerAdapter.LinkTransport.create({
+		openChannel: carrier.open,
+		createFormatMessage: channel.createCodec,
+		getTransportCacheKey: carrier.getCacheKey,
+		available,
+		getRouteInfo: carrier.getRouteInfo,
+		label: labelFor,
+		security
+	});
+}
+//#endregion
+//#region src/ActionRuntime/Channel/ActionChannel.ts
+/**
+* Derive a stable wire-dictionary version from the ordered route list (FNV-1a over `domain:id,…`), so
+* the version moves automatically whenever the transported domains change — a stale peer is then
+* rejected by the handshake instead of silently misrouting a positionally-packed frame.
+*/
+function deriveDictionaryVersion(domains) {
+	const { intToRoute } = require_createHibernatableWsServerAdapter.buildActionRouteDictionary(domains);
+	const signature = intToRoute.map((route) => `${route.domain}:${route.id}`).join(",");
+	let hash = 2166136261;
+	for (let i = 0; i < signature.length; i++) {
+		hash ^= signature.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return `auto:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+/**
+* Declare a transport-agnostic channel by role — the single source of truth both peers share. Each end
+* MUST call this with the same domains in the same order (the binary wire dictionary is positional); the
+* `dictionaryVersion` is derived from those domains unless you pin an explicit one. The wire dictionary
+* spans `[...toAcceptor, ...toConnector]` in that order, so add new domains to the end of their list to
+* keep older peers compatible.
+*
+* Declare the domains *by role* — `toAcceptor` (connector→acceptor requests) and `toConnector`
+* (acceptor→connector pushes) — so the routing for both ends is derived from the channel (see
+* {@link connectChannel} and {@link serveChannel}) instead of being restated at each end. Security is a
+* per-transport concern, not a channel one, so this same definition is used whether a transport runs
+* plain or encrypted.
+*/
+function defineChannel(options) {
+	const allDomains = [...options.toAcceptor, ...options.toConnector];
+	return {
+		toAcceptorDomains: options.toAcceptor,
+		toConnectorDomains: options.toConnector,
+		dictionaryVersion: options.dictionaryVersion ?? deriveDictionaryVersion(allDomains),
+		createCodec: require_createHibernatableWsServerAdapter.createBinaryWireSessionFactory(allDomains, options.sessionOptions)
+	};
+}
+/**
+* Open a connection to a peer from a single call — the dial-out dual of `serveChannel`. The channel is
+* the single source of truth for *what* is routed (`toAcceptor` domains forwarded to the peer,
+* `toConnector` pushes handled locally from `onPush`); the call binds the shared facts — the channel's
+* codec/dictionary version, the runtime, and one crypto identity (a {@link ClientCryptoKeyLink} over
+* `storage`) — into every transport in `transports`, so none of them restate the channel or runtime.
+* List several transports to make the path transport-agnostic (secure WS preferred, HTTP fallback):
+* ```ts
+* const handler = connectChannel(runtime, lobbyChannel, {
+*   peer: runtime_coordinate_lobby_do,
+*   storage,
+*   transports: [{ carrier: wsCarrier(() => ({ url })) }, { carrier: httpCarrier(...), secure: false }],
+*   onPush: { player_joined: (p) => { … } },
+* });
+* ```
+* Returns the {@link ConnectorHandler} so the caller can later `clearTransportCache()` it.
+*/
+function connectChannel(runtime, channel, options) {
+	const securityLevel = options.securityLevel ?? "authenticated";
+	const anySecure = options.transports.some((transport) => transport.secure ?? true);
+	let link = options.link;
+	if (anySecure && link == null) {
+		if (options.storage == null) throw new Error("connectChannel: a secure transport requires `storage` (or `link`). Pass it, or set `secure: false` on the transport for a plain connection.");
+		link = new _nice_code_util.ClientCryptoKeyLink({ storageAdapter: options.storage });
+	}
+	const transports = options.transports.map((descriptor) => transport({
+		carrier: descriptor.carrier,
+		channel,
+		runtime,
+		secure: descriptor.secure ?? true,
+		link,
+		securityLevel: descriptor.securityLevel ?? securityLevel,
+		available: descriptor.available,
+		label: descriptor.label
+	}));
+	const pushHandlers = options.onPush != null ? channel.toConnectorDomains.map((domain) => domain.wrapAsPartialLocalHandler(options.onPush)) : [];
+	return runtime.connectTo(options.peer, {
+		transports,
+		domains: [...channel.toAcceptorDomains],
+		localHandlers: pushHandlers,
+		defaultTimeout: options.defaultTimeout
+	});
+}
+/**
+* Register an acceptor handler's execution for a channel straight from its definition: the channel's
+* `toAcceptor` domains are served together with one merged, connection-aware case map (each case gets
+* the primed request + the originating connection, as with
+* {@link AcceptorHandler.forConnectionDomainCases}). The domain list is taken from the channel,
+* never restated. Add the returned handler to the runtime alongside the acceptor handler:
+* ```ts
+* runtime.addHandlers([acceptChannelConnections(serverHandler, channel, { … }), serverHandler]);
+* ```
+*
+* The case's second argument is the raw connection (`TConn | undefined`). For the richer state +
+* broadcast + pushBack context, serve the channel through `serveChannel`'s `channelCases` instead.
+*/
+function acceptChannelConnections(serverHandler, channel, cases) {
+	return serverHandler.forConnectionDomainCasesMulti(channel.toAcceptorDomains, cases, (connection) => connection);
+}
+/**
+* Build the secure {@link AcceptorHandler} for a channel — the accept-in counterpart to
+* {@link connectChannel}. It folds in the boilerplate of {@link createSecureAcceptorHandler} (the
+* `ClientCryptoKeyLink` + storage-backed TOFU resolver from one `storage`, the channel's codec +
+* dictionary version, the `security` block from the runtime coordinate) but takes the `(runtime, channel,
+* options)` shape of the channel family. Pair it with {@link acceptChannelConnections} for execution:
+* ```ts
+* const acceptor = acceptChannel(runtime, gameChannel, { clientEnv, storage, send });
+* runtime.addHandlers([acceptChannelConnections(acceptor, gameChannel, { … }), acceptor]);
+* ```
+*/
+function acceptChannel(runtime, channel, options) {
+	return require_createHibernatableWsServerAdapter.createSecureAcceptorHandler({
+		...options,
+		channel,
+		runtime
+	});
+}
+//#endregion
+//#region src/ActionRuntime/Transport/Carrier/AcceptorCarrier.types.ts
+/**
+* Build the inert lifecycle slot a duplex carrier factory spreads into its handle: `receive`/`drop` throw
+* (or no-op) until `serveChannel` calls `_activate` with the carrier's live router. Shared by every duplex
+* carrier factory (`wsAcceptorCarrier`, a WebRTC carrier, the Cloudflare DO helper, …) so the
+* stateful-handle wiring lives in exactly one place.
+*/
+function createDuplexCarrierLifecycle() {
+	let router;
+	return {
+		receive(connection, frame) {
+			if (router == null) throw new Error("acceptor carrier not served yet — pass it to serveChannel() before feeding frames");
+			router.receive(connection, frame);
+		},
+		drop(connection) {
+			router?.drop(connection);
+		},
+		_activate(liveRouter) {
+			router = liveRouter;
+		}
+	};
+}
+/**
+* Narrow an acceptor carrier to the exchange shape via its `shape` discriminant — the one branch
+* `serveChannel` uses to pick the duplex (push-capable) vs exchange (request/reply) wiring. A duplex
+* carrier carries `shape: ETransportShape.duplex`, so the `else` branch is the duplex one.
+*/
+function isExchangeAcceptorCarrier(carrier) {
+	return carrier.shape === "exchange";
+}
+//#endregion
+//#region src/ActionRuntime/Channel/serveChannel.ts
+/** Default accepted set, shared by every carrier: negotiate per connection to whatever the client picks. */
+const DEFAULT_SERVER_SECURITY_LEVELS = [
+	"none",
+	"authenticated",
+	"encrypted"
+];
+function serveChannel(runtime, channel, options) {
+	const duplexCarriers = options.carriers.filter((carrier) => !isExchangeAcceptorCarrier(carrier));
+	const exchangeCarriers = options.carriers.filter(isExchangeAcceptorCarrier);
+	if (exchangeCarriers.length > 1) throw new Error("serveChannel: at most one exchange carrier is supported");
+	const exchangeCarrier = exchangeCarriers[0];
+	const singleDuplex = duplexCarriers.length === 1;
+	if (options.connectionState != null && !singleDuplex) throw new Error("serveChannel: `connectionState` requires exactly one duplex carrier");
+	if (options.channelCases != null && !singleDuplex) throw new Error("serveChannel: `channelCases` requires exactly one duplex carrier");
+	const exchangeSecure = exchangeCarrier != null && (exchangeCarrier.secure ?? true);
+	const anyDuplexSecure = duplexCarriers.some((carrier) => carrier.secure ?? true);
+	const securityLevel = options.securityLevel ?? DEFAULT_SERVER_SECURITY_LEVELS;
+	let secure;
+	if (anyDuplexSecure || exchangeSecure) {
+		const storage = options.storage;
+		if (storage == null) throw new Error("serveChannel: a secure carrier requires `storage`. Pass it, or set `secure: false` on the carrier for a plain endpoint.");
+		secure = {
+			storage,
+			link: options.link ?? new _nice_code_util.ClientCryptoKeyLink({ storageAdapter: storage }),
+			verifyKeyResolver: options.verifyKeyResolver ?? require_createHibernatableWsServerAdapter.createStorageTofuVerifyKeyResolver(storage)
+		};
+	}
+	const plainRouter = (handler) => ({
+		receive: (connection, frame) => handler.receive(connection, frame),
+		drop: (connection) => handler.dropConnection(connection)
+	});
+	const asObject = (value) => typeof value === "object" && value != null ? value : {};
+	const handlers = [];
+	let connections;
+	for (const carrier of duplexCarriers) {
+		const handler = (carrier.secure ?? true) && secure != null ? acceptChannel(runtime, channel, {
+			clientEnv: options.clientEnv,
+			storage: secure.storage,
+			link: secure.link,
+			verifyKeyResolver: secure.verifyKeyResolver,
+			securityLevel,
+			send: carrier.send,
+			defaultTimeout: options.defaultTimeout
+		}) : require_createHibernatableWsServerAdapter.createAcceptorHandler({
+			clientEnv: options.clientEnv,
+			createFormatMessage: channel.createCodec,
+			send: carrier.send,
+			runtime,
+			defaultTimeout: options.defaultTimeout
+		});
+		const attach = carrier.attachmentStore;
+		let router;
+		if (attach == null) router = plainRouter(handler);
+		else if (options.connectionState != null) {
+			connections = require_createHibernatableWsServerAdapter.createConnectionStateStore(handler, {
+				schema: options.connectionState.schema,
+				getConnections: attach.getConnections,
+				read: attach.read,
+				write: attach.write
+			});
+			router = plainRouter(handler);
+		} else router = require_createHibernatableWsServerAdapter.createHibernatableWsServerAdapter({
+			handler,
+			getConnections: attach.getConnections,
+			getAttachment: (connection) => attach.read(connection)?.binding,
+			setAttachment: (connection, binding) => attach.write(connection, {
+				...asObject(attach.read(connection)),
+				binding
+			})
+		});
+		carrier._activate(router);
+		handlers.push(handler);
+	}
+	runtime.addHandlers([...options.handlers ?? [], ...handlers]);
+	const soleDuplex = singleDuplex ? duplexCarriers[0] : void 0;
+	const receive = (connection, frame) => {
+		if (soleDuplex == null) throw new Error(duplexCarriers.length === 0 ? "serveChannel: no duplex carrier to receive on (this server has no socket transport)" : "serveChannel: several duplex carriers — feed each carrier handle's receive() directly");
+		soleDuplex.receive(connection, frame);
+	};
+	const drop = (connection) => {
+		soleDuplex?.drop(connection);
+	};
+	const pushToClient = (target, request, pushOptions) => {
+		const owner = target instanceof require_createHibernatableWsServerAdapter.RuntimeCoordinate ? handlers.find((handler) => handler.ownsLiveConnectionFor(target)) : handlers.find((handler) => handler.hasConnection(target));
+		if (owner == null) throw new Error("serveChannel: no duplex carrier holds a connection for the push target");
+		return owner.pushToClient(runtime, target, request, pushOptions);
+	};
+	const broadcast = (makeRequest, broadcastOptions) => {
+		if (!singleDuplex) throw new Error("serveChannel: broadcast requires exactly one duplex carrier — broadcast over a specific handlers[i] instead");
+		handlers[0].broadcast(makeRequest, {
+			runtime,
+			...broadcastOptions
+		});
+	};
+	const makeConnectionContext = (connection, request) => ({
+		connection: connection ?? null,
+		origin: request.context.originClient,
+		get state() {
+			return connection != null && connections != null ? connections.get(connection) : null;
+		},
+		setState(value) {
+			if (connection != null && connections != null) connections.set(connection, value);
+		},
+		clearState() {
+			if (connection != null && connections != null) connections.clearApp(connection);
+		},
+		broadcast(makeRequest, contextOptions) {
+			broadcast(makeRequest, {
+				except: contextOptions?.exceptSelf ? connection ?? null : null,
+				where: contextOptions?.where,
+				timeout: contextOptions?.timeout,
+				onError: contextOptions?.onError
+			});
+		},
+		pushBack(pushRequest, pushOptions) {
+			if (connection == null) throw new Error("serveChannel: connection context has no live socket to push back to (HTTP-exchange path)");
+			return pushToClient(connection, pushRequest, pushOptions);
+		}
+	});
+	if (options.channelCases != null) runtime.addHandlers([handlers[0].forConnectionDomainCasesMulti(channel.toAcceptorDomains, options.channelCases, makeConnectionContext)]);
+	const exchangeSecurity = exchangeSecure && secure != null ? {
+		link: secure.link,
+		verifyKeyResolver: secure.verifyKeyResolver,
+		localCoordinate: runtime.coordinate.toJsonObject(),
+		dictionaryVersion: channel.dictionaryVersion,
+		securityLevel
+	} : void 0;
+	const defaultIsUpgrade = (request) => request.headers.get("Upgrade") === "websocket";
+	const upgraders = [];
+	for (const carrier of duplexCarriers) {
+		if (carrier.upgrade == null) continue;
+		upgraders.push({
+			isUpgrade: carrier.isUpgrade ?? defaultIsUpgrade,
+			upgrade: carrier.upgrade
+		});
+	}
+	return {
+		handlers,
+		fetch: require_createHibernatableWsServerAdapter.createActionFetchHandler(runtime, {
+			cors: exchangeCarrier?.cors,
+			onWebSocketUpgrade: upgraders.length === 0 ? void 0 : (request, url) => (upgraders.find((u) => u.isUpgrade(request, url)) ?? upgraders[0]).upgrade(request, url),
+			isWebSocketUpgrade: upgraders.length === 0 ? void 0 : (request, url) => upgraders.some((u) => u.isUpgrade(request, url)),
+			isActionPath: exchangeCarrier != null ? exchangeCarrier.isActionPath ?? (() => true) : () => false,
+			security: exchangeSecurity,
+			useErrorStatus: exchangeCarrier?.useErrorStatus
+		}),
+		receive,
+		drop,
+		pushToClient,
+		broadcast,
+		connections
+	};
+}
+//#endregion
+//#region src/ActionRuntime/Channel/serveHost.ts
+function serveHost(runtime, channel, host, options) {
+	const server = serveChannel(runtime, channel, {
+		...options,
+		carriers: host.carriers,
+		storage: host.storage
+	});
+	host.onServed?.(server);
+	return server;
+}
+//#endregion
+//#region src/ActionRuntime/Transport/Carrier/duplex/ws/wsAcceptorCarrier.ts
+/**
+* A WebSocket {@link IDuplexAcceptorCarrier}: the accept-in dual of {@link wsCarrier}. It describes how to
+* write frames back to a live socket, how to upgrade an inbound request into one, and (optionally) how to
+* persist bindings across hibernation. Hand it to `serveChannel`'s `carriers` list — the secure session,
+* codec, and crypto identity are supplied centrally there, so this only carries the WS-specific surface.
+*/
+function wsAcceptorCarrier(options) {
+	return {
+		...createDuplexCarrierLifecycle(),
+		shape: "duplex",
+		carrierLabel: options.carrierLabel ?? "ws",
+		secure: options.secure,
+		send: options.send,
+		upgrade: options.upgrade,
+		isUpgrade: options.isUpgrade ?? ((request) => request.headers.get("Upgrade") === "websocket"),
+		attachmentStore: options.attachmentStore
+	};
+}
+//#endregion
+//#region src/ActionRuntime/Transport/Carrier/exchange/http/httpAcceptorCarrier.ts
+/**
+* An HTTP {@link IExchangeAcceptorCarrier}: the accept-in dual of {@link httpCarrier}. It serves the
+* secure exchange protocol (handshake → token session → encrypted frames) over web-standard
+* `Request`/`Response`. The crypto identity, runtime coordinate, dictionary version, and accepted security
+* levels are all supplied centrally by `serveChannel`, so this only needs to say which requests carry an
+* action envelope and how to answer CORS.
+*/
+function httpAcceptorCarrier(options = {}) {
+	return {
+		shape: "exchange",
+		carrierLabel: options.carrierLabel ?? "http",
+		secure: options.secure,
+		isActionPath: options.isActionPath,
+		cors: options.cors,
+		useErrorStatus: options.useErrorStatus
+	};
+}
+//#endregion
+Object.defineProperty(exports, "acceptChannel", {
+	enumerable: true,
+	get: function() {
+		return acceptChannel;
+	}
+});
+Object.defineProperty(exports, "acceptChannelConnections", {
+	enumerable: true,
+	get: function() {
+		return acceptChannelConnections;
+	}
+});
+Object.defineProperty(exports, "connectChannel", {
+	enumerable: true,
+	get: function() {
+		return connectChannel;
+	}
+});
+Object.defineProperty(exports, "defineChannel", {
+	enumerable: true,
+	get: function() {
+		return defineChannel;
+	}
+});
+Object.defineProperty(exports, "httpAcceptorCarrier", {
+	enumerable: true,
+	get: function() {
+		return httpAcceptorCarrier;
+	}
+});
+Object.defineProperty(exports, "isExchangeAcceptorCarrier", {
+	enumerable: true,
+	get: function() {
+		return isExchangeAcceptorCarrier;
+	}
+});
+Object.defineProperty(exports, "serveChannel", {
+	enumerable: true,
+	get: function() {
+		return serveChannel;
+	}
+});
+Object.defineProperty(exports, "serveHost", {
+	enumerable: true,
+	get: function() {
+		return serveHost;
+	}
+});
+Object.defineProperty(exports, "wsAcceptorCarrier", {
+	enumerable: true,
+	get: function() {
+		return wsAcceptorCarrier;
+	}
+});
+
+//# sourceMappingURL=httpAcceptorCarrier-C3S_bDkL.cjs.map