@nice-code/action 0.18.0 → 0.20.0

package/build/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("./rolldown-runtime-emK7D4bc.cjs");
 const require_RunningAction_types = require("./RunningAction.types-DjCX1xp5.cjs");
-const require_wsAcceptorCarrier = require("./wsAcceptorCarrier-DHRbsY1X.cjs");
+const require_wsAcceptorCarrier = require("./wsAcceptorCarrier-BDJRIPfu.cjs");
 let nanoid = require("nanoid");
 let _nice_code_error = require("@nice-code/error");
 let _nice_code_common_errors = require("@nice-code/common-errors");
@@ -879,6 +879,10 @@ var ConnectionTransportManager = class {
 		const candidates = [];
 		const unavailableTransports = [];
 		for (const transport of this._transports) {
+			if (!transport.isAvailable(routeActionParams)) {
+				unavailableTransports.push(transport);
+				continue;
+			}
 			const cacheKey = transport.getCacheKey(routeActionParams);
 			if (cacheKey != null) {
 				const cached = this._cache.get(cacheKey);
@@ -3534,6 +3538,113 @@ function createActionFetchHandler(runtime, options = {}) {
 	};
 }
 //#endregion
+//#region src/ActionRuntime/Handler/PeerLink/Acceptor/Hibernation/ConnectionStateStore.ts
+/**
+* A typed per-connection state store that co-owns the app state and the acceptor handler's routing
+* binding in one attachment, so neither the consumer nor the handler has to hand-merge the two. Create
+* it through {@link createConnectionStateStore} (which also wires binding persistence and replays
+* surviving connections after a wake), then `get`/`set`/`clearApp` the app state directly.
+*
+* The mechanism is carrier-neutral — it only needs read/write/enumerate callbacks for the connection's
+* attachment — but it pays off on transports whose connections outlive process eviction (e.g. a
+* Durable Object's hibernatable WebSockets), which is why it lives beside the hibernation adapter.
+*
+* ```ts
+* const players = createConnectionStateStore(serverHandler, {
+*   schema: vs_player,
+*   read: (ws) => ws.deserializeAttachment(),
+*   write: (ws, v) => ws.serializeAttachment(v),
+*   getConnections: () => ctx.getWebSockets(),
+* });
+* players.set(ws, player); // binding is preserved automatically
+* const player = players.get(ws);
+* ```
+*/
+var ConnectionStateStore = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/** The validated app state for a connection, or `null` if unset / invalid. */
+	get(connection) {
+		return this._readAttachment(connection).app ?? null;
+	}
+	/** Set the app state, preserving the runtime binding already pinned to the connection. */
+	set(connection, app) {
+		const existing = this._readAttachment(connection);
+		this.options.write(connection, {
+			app,
+			binding: existing.binding
+		});
+	}
+	/** Clear the app state but keep the binding (e.g. a spectator that stopped watching). */
+	clearApp(connection) {
+		const existing = this._readAttachment(connection);
+		this.options.write(connection, { binding: existing.binding });
+	}
+	/** Every live connection paired with its (validated) app state — for rebuilding in-memory state after a wake. */
+	entries() {
+		return this.options.getConnections().map((connection) => [connection, this._readAttachment(connection).app ?? null]);
+	}
+	/** @internal Persist a freshly-bound connection's binding, preserving any app state already stored. */
+	_persistBinding(connection, binding) {
+		const existing = this._readAttachment(connection);
+		this.options.write(connection, {
+			app: existing.app,
+			binding
+		});
+	}
+	/** @internal The persisted binding for a connection, if any (used to replay routing after a wake). */
+	_readBinding(connection) {
+		return this._readAttachment(connection).binding;
+	}
+	_readAttachment(connection) {
+		try {
+			const raw = this.options.read(connection);
+			if (typeof raw !== "object" || raw === null) return {};
+			const attachment = raw;
+			const result = {};
+			if (attachment.binding != null) result.binding = attachment.binding;
+			if (attachment.app !== void 0) {
+				const app = this._validateApp(attachment.app);
+				if (app !== void 0) result.app = app;
+			}
+			return result;
+		} catch {
+			return {};
+		}
+	}
+	_validateApp(value) {
+		const schema = this.options.schema;
+		if (schema == null) return value;
+		const result = schema["~standard"].validate(value);
+		if (result instanceof Promise) return void 0;
+		if (result.issues != null) return void 0;
+		return result.value;
+	}
+};
+/**
+* Build a per-connection {@link ConnectionStateStore} bound to an {@link AcceptorHandler}: it registers
+* itself as the handler's connection-bound persistence callback (so bindings are written without
+* overwriting app state) and immediately replays every live connection's stored binding via
+* {@link AcceptorHandler.rehydrateConnection} — so on a transport that resumes after eviction (e.g. a
+* Durable Object waking from hibernation) both the app identity and the action routing come back from a
+* single attachment, with no storage reads and no hand-rolled merge.
+*
+* Lives outside the handler so the generic {@link AcceptorHandler} stays free of any attachment/
+* hibernation concern — it exposes only the neutral `setOnConnectionBound` + `rehydrateConnection`
+* hooks this builder drives.
+*/
+function createConnectionStateStore(handler, options) {
+	const store = new ConnectionStateStore(options);
+	handler.setOnConnectionBound((connection, binding) => store._persistBinding(connection, binding));
+	for (const connection of options.getConnections()) {
+		const binding = store._readBinding(connection);
+		if (binding != null) handler.rehydrateConnection(connection, binding);
+	}
+	return store;
+}
+//#endregion
 //#region src/ActionRuntime/Handler/PeerLink/Acceptor/Hibernation/createHibernatableWsServerAdapter.ts
 /**
 * Wire the hibernation lifecycle for an acceptor handler on a transport whose connections outlive process
@@ -3572,34 +3683,14 @@ const DEFAULT_SERVER_SECURITY_LEVELS = [
 	"authenticated",
 	"encrypted"
 ];
-/**
-* Serve a secure channel over one or more carriers from a single call — the accept-in dual of
-* `connectChannel`. It builds the crypto identity (a {@link ClientCryptoKeyLink} + a storage-backed TOFU
-* resolver) and the security block (coordinate, dictionary version, accepted levels) *once* from
-* `(runtime, channel)` and fans them across every carrier, so the WebSocket and the secure-HTTP endpoint
-* can never drift apart. It registers your handlers (plus the duplex acceptor it builds) on the runtime,
-* wires hibernation when the duplex carrier declares it, and returns a single {@link IChannelServer} whose
-* `fetch` / `duplex` / `pushToClient` you forward straight to the host:
-* ```ts
-* const server = serveChannel(runtime, channel, {
-*   clientEnv, storage,
-*   carriers: [wsAcceptorCarrier({ send, upgrade, hibernation }), httpAcceptorCarrier()],
-*   handlers: [localHandler],
-* });
-* // fetch(req) => server.fetch(req)
-* // webSocketMessage(conn, m) => server.duplex?.receive(conn, m)
-* // webSocketClose/Error(conn) => server.duplex?.drop(conn)
-* ```
-*
-* `TConn` (the live-connection token a duplex carrier hands back through `send`/`receive`/`drop`) is
-* inferred from the carriers — `WebSocket` for `wsAcceptorCarrier`, the data-channel type for a WebRTC
-* carrier, and so on — so it stays carrier-agnostic.
-*/
 function serveChannel(runtime, channel, options) {
 	const duplexCarriers = options.carriers.filter((carrier) => !require_wsAcceptorCarrier.isExchangeAcceptorCarrier(carrier));
 	const exchangeCarriers = options.carriers.filter(require_wsAcceptorCarrier.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;
@@ -3613,7 +3704,13 @@ function serveChannel(runtime, channel, options) {
 			verifyKeyResolver: options.verifyKeyResolver ?? 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,
@@ -3630,17 +3727,31 @@ function serveChannel(runtime, channel, options) {
 			runtime,
 			defaultTimeout: options.defaultTimeout
 		});
-		const router = carrier.hibernation != null ? createHibernatableWsServerAdapter({
+		const attach = carrier.attachmentStore;
+		let router;
+		if (attach == null) router = plainRouter(handler);
+		else if (options.connectionState != null) {
+			connections = createConnectionStateStore(handler, {
+				schema: options.connectionState.schema,
+				getConnections: attach.getConnections,
+				read: attach.read,
+				write: attach.write
+			});
+			router = plainRouter(handler);
+		} else router = createHibernatableWsServerAdapter({
 			handler,
-			...carrier.hibernation
-		}) : {
-			receive: (connection, frame) => handler.receive(connection, frame),
-			drop: (connection) => handler.dropConnection(connection)
-		};
+			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]);
+	if (options.channelCases != null) runtime.addHandlers([acceptChannelConnections(handlers[0], channel, options.channelCases)]);
 	const exchangeSecurity = exchangeSecure && secure != null ? {
 		link: secure.link,
 		verifyKeyResolver: secure.verifyKeyResolver,
@@ -3671,121 +3782,23 @@ function serveChannel(runtime, channel, options) {
 		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
+		});
+	};
 	return {
 		handlers,
 		fetch,
 		duplex,
-		pushToClient
+		pushToClient,
+		broadcast,
+		connections
 	};
 }
 //#endregion
-//#region src/ActionRuntime/Handler/PeerLink/Acceptor/Hibernation/ConnectionStateStore.ts
-/**
-* A typed per-connection state store that co-owns the app state and the acceptor handler's routing
-* binding in one attachment, so neither the consumer nor the handler has to hand-merge the two. Create
-* it through {@link createConnectionStateStore} (which also wires binding persistence and replays
-* surviving connections after a wake), then `get`/`set`/`clearApp` the app state directly.
-*
-* The mechanism is carrier-neutral — it only needs read/write/enumerate callbacks for the connection's
-* attachment — but it pays off on transports whose connections outlive process eviction (e.g. a
-* Durable Object's hibernatable WebSockets), which is why it lives beside the hibernation adapter.
-*
-* ```ts
-* const players = createConnectionStateStore(serverHandler, {
-*   schema: vs_player,
-*   read: (ws) => ws.deserializeAttachment(),
-*   write: (ws, v) => ws.serializeAttachment(v),
-*   getConnections: () => ctx.getWebSockets(),
-* });
-* players.set(ws, player); // binding is preserved automatically
-* const player = players.get(ws);
-* ```
-*/
-var ConnectionStateStore = class {
-	options;
-	constructor(options) {
-		this.options = options;
-	}
-	/** The validated app state for a connection, or `null` if unset / invalid. */
-	get(connection) {
-		return this._readAttachment(connection).app ?? null;
-	}
-	/** Set the app state, preserving the runtime binding already pinned to the connection. */
-	set(connection, app) {
-		const existing = this._readAttachment(connection);
-		this.options.write(connection, {
-			app,
-			binding: existing.binding
-		});
-	}
-	/** Clear the app state but keep the binding (e.g. a spectator that stopped watching). */
-	clearApp(connection) {
-		const existing = this._readAttachment(connection);
-		this.options.write(connection, { binding: existing.binding });
-	}
-	/** Every live connection paired with its (validated) app state — for rebuilding in-memory state after a wake. */
-	entries() {
-		return this.options.getConnections().map((connection) => [connection, this._readAttachment(connection).app ?? null]);
-	}
-	/** @internal Persist a freshly-bound connection's binding, preserving any app state already stored. */
-	_persistBinding(connection, binding) {
-		const existing = this._readAttachment(connection);
-		this.options.write(connection, {
-			app: existing.app,
-			binding
-		});
-	}
-	/** @internal The persisted binding for a connection, if any (used to replay routing after a wake). */
-	_readBinding(connection) {
-		return this._readAttachment(connection).binding;
-	}
-	_readAttachment(connection) {
-		try {
-			const raw = this.options.read(connection);
-			if (typeof raw !== "object" || raw === null) return {};
-			const attachment = raw;
-			const result = {};
-			if (attachment.binding != null) result.binding = attachment.binding;
-			if (attachment.app !== void 0) {
-				const app = this._validateApp(attachment.app);
-				if (app !== void 0) result.app = app;
-			}
-			return result;
-		} catch {
-			return {};
-		}
-	}
-	_validateApp(value) {
-		const schema = this.options.schema;
-		if (schema == null) return value;
-		const result = schema["~standard"].validate(value);
-		if (result instanceof Promise) return void 0;
-		if (result.issues != null) return void 0;
-		return result.value;
-	}
-};
-/**
-* Build a per-connection {@link ConnectionStateStore} bound to an {@link AcceptorHandler}: it registers
-* itself as the handler's connection-bound persistence callback (so bindings are written without
-* overwriting app state) and immediately replays every live connection's stored binding via
-* {@link AcceptorHandler.rehydrateConnection} — so on a transport that resumes after eviction (e.g. a
-* Durable Object waking from hibernation) both the app identity and the action routing come back from a
-* single attachment, with no storage reads and no hand-rolled merge.
-*
-* Lives outside the handler so the generic {@link AcceptorHandler} stays free of any attachment/
-* hibernation concern — it exposes only the neutral `setOnConnectionBound` + `rehydrateConnection`
-* hooks this builder drives.
-*/
-function createConnectionStateStore(handler, options) {
-	const store = new ConnectionStateStore(options);
-	handler.setOnConnectionBound((connection, binding) => store._persistBinding(connection, binding));
-	for (const connection of options.getConnections()) {
-		const binding = store._readBinding(connection);
-		if (binding != null) handler.rehydrateConnection(connection, binding);
-	}
-	return store;
-}
-//#endregion
 //#region src/ActionRuntime/Transport/Carrier/duplex/inMemory/createInMemoryChannel.ts
 /**
 * Two cross-wired in-process byte channels — a loopback carrier with no socket. The client end is a
@@ -4440,6 +4453,15 @@ var TransportConnection = class {
 		if (inner == null) return null;
 		return `${this.transOrd}:${inner}`;
 	}
+	/**
+	* Whether this transport can serve the given action right now. Consulted by the manager before
+	* cache-key resolution and `getTransport`; a `false` result skips this transport (treated as
+	* `unsupported`) and the manager falls through to the next in preference order. Defaults to `true`
+	* when the transport declares no gate.
+	*/
+	isAvailable(input) {
+		return this.initialized.isAvailable?.(input) ?? true;
+	}
 	getTransport(input) {
 		return this._processTransportStatus(input);
 	}
@@ -4536,6 +4558,7 @@ var ExchangeTransport = class ExchangeTransport extends Transport {
 		const options = this.options;
 		return new ExchangeConnection({ initialize: () => ({
 			getTransportCacheKey: options.getTransportCacheKey,
+			isAvailable: options.available,
 			getTransport: (input) => ({
 				status: "ready",
 				readyData: {
@@ -4784,6 +4807,7 @@ var LinkTransport = class LinkTransport extends Transport {
 		const options = this.options;
 		return new LinkConnection({ initialize: () => ({
 			getTransportCacheKey: options.getTransportCacheKey,
+			isAvailable: options.available,
 			getTransport: (input) => ({
 				status: "ready",
 				readyData: {
@@ -4820,6 +4844,7 @@ function plainTransport(options) {
 	if (isExchangeCarrierSource(carrier)) return ExchangeTransport.create({
 		openCarrier: carrier.open,
 		getTransportCacheKey: carrier.getCacheKey,
+		available: options.available,
 		getRouteInfo: carrier.getRouteInfo,
 		label: options.label ?? carrier.carrierLabel,
 		updateRunConfig: options.updateRunConfig
@@ -4829,6 +4854,7 @@ function plainTransport(options) {
 		formatMessage: options.formatMessage,
 		createFormatMessage: options.createFormatMessage,
 		getTransportCacheKey: carrier.getCacheKey,
+		available: options.available,
 		getRouteInfo: carrier.getRouteInfo,
 		label: options.label ?? carrier.carrierLabel,
 		updateRunConfig: options.updateRunConfig
@@ -4848,6 +4874,7 @@ function secureTransport(options) {
 	if (isExchangeCarrierSource(carrier)) return ExchangeTransport.create({
 		openCarrier: carrier.open,
 		getTransportCacheKey: carrier.getCacheKey,
+		available: options.available,
 		getRouteInfo: carrier.getRouteInfo,
 		label: carrier.carrierLabel,
 		security
@@ -4856,6 +4883,7 @@ function secureTransport(options) {
 		openChannel: carrier.open,
 		createFormatMessage: options.channel.createCodec,
 		getTransportCacheKey: carrier.getCacheKey,
+		available: options.available,
 		getRouteInfo: carrier.getRouteInfo,
 		label: carrier.carrierLabel,
 		security
@@ -4912,9 +4940,12 @@ exports.createSecureAcceptorHandler = createSecureAcceptorHandler;
 exports.createServerHandshake = createServerHandshake;
 exports.createStorageTofuVerifyKeyResolver = createStorageTofuVerifyKeyResolver;
 exports.decodeActionFrame = decodeActionFrame;
+exports.decodeExchangeReply = decodeExchangeReply;
+exports.decodeExchangeRequest = decodeExchangeRequest;
 exports.decodeHandshakeMessage = decodeHandshakeMessage;
 exports.defineChannel = defineChannel;
 exports.defineSecureChannel = defineSecureChannel;
+exports.encodeExchange = encodeExchange;
 exports.encodeHandshakeMessage = encodeHandshakeMessage;
 exports.err_nice_action = err_nice_action;
 exports.err_nice_external_client = err_nice_external_client;