@camera.ui/transport 0.0.25 → 0.0.27

package/dist/effects/backgroundProbe.d.ts

@@ -2,7 +2,7 @@ import { Kernel } from '../core/kernel.js';
 import { ConnectionTarget, Endpoint, Tokens } from '../core/types.js';
 import { TimeoutByModeFn } from '../race.js';
 import { ProbeContext } from './probeLoop.js';
-export type BackgroundProbeOutcome = 'swap' | 'same' | 'failed' | 'skipped';
+export type BackgroundProbeOutcome = 'swap' | 'same' | 'kept' | 'failed' | 'skipped';
 export interface BackgroundProbeOptions {
     readonly kernel: Kernel;
     readonly discover: (signal: AbortSignal) => Promise<readonly Endpoint[]>;
@@ -11,6 +11,7 @@ export interface BackgroundProbeOptions {
     readonly timeoutByMode?: TimeoutByModeFn;
     readonly prefer?: (endpoint: Endpoint) => boolean;
     readonly preferGraceMs?: number;
+    readonly isCurrentHealthy?: () => boolean;
     readonly onResult?: (outcome: BackgroundProbeOutcome, detail?: string) => void;
 }
 export interface BackgroundProbe {

package/dist/effects/workerBridge.d.ts

@@ -1,10 +1,17 @@
 import { Kernel } from '../core/kernel.js';
+import { ConnectionTarget } from '../core/types.js';
 import { WorkerHost } from '../worker/protocol.js';
 export type Detach = () => void;
+export interface BridgeResolveContext {
+    readonly target: ConnectionTarget;
+    readonly connId: string;
+    readonly defaultServers: readonly string[];
+}
 export interface WorkerBridgeOptions {
     readonly kernel: Kernel;
-    readonly hosts: () => Iterable<WorkerHost>;
     readonly listenForResyncRequests?: boolean;
+    readonly hosts: () => Iterable<WorkerHost>;
+    readonly resolveServers?: (ctx: BridgeResolveContext) => Promise<string[]>;
     readonly onBroadcast?: (generation: number, hostCount: number) => void;
     readonly onSyncHost?: (generation: number) => void;
 }

package/dist/index.d.ts

@@ -28,10 +28,10 @@ export type { PresenceCallback, PresenceOptions, VisibilitySource } from './effe
 export type { ProbeContext, ProbeFailure, ProbeFailureKind, ProbeLoopOptions } from './effects/probeLoop.js';
 export type { Detach, RefreshReason, TokenLifecycle, TokenLifecycleOptions } from './effects/tokenLifecycle.js';
 export type { TransportSyncOptions } from './effects/transportSync.js';
-export type { WorkerBridge, WorkerBridgeOptions } from './effects/workerBridge.js';
+export type { BridgeResolveContext, WorkerBridge, WorkerBridgeOptions } from './effects/workerBridge.js';
 export type { ConnectionJournal, JournalEntry, JournalOptions } from './journal.js';
 export type { RaceCandidate, RaceFirstOptions, RaceFirstResult, TimeoutByModeFn } from './race.js';
 export type { ConnectionSignal, ConnectionSignalHandle, ConnectionSignalOptions } from './signal.js';
 export type { CloseClass, CloseLike } from './transports/closeCodes.js';
 export type { PerResourceTransport, Transport, TransportEvent, TransportEventHandler, TransportEventPayload } from './transports/contract.js';
-export type { KernelSyncMessage, KernelSyncRequestMessage, MessageSource, WorkerHost, WorkerMessage } from './worker/protocol.js';
+export type { KernelResolveReplyMessage, KernelResolveRequestMessage, KernelSyncMessage, KernelSyncRequestMessage, MessageSource, WorkerHost, WorkerMessage, } from './worker/protocol.js';

package/dist/index.js

@@ -331,7 +331,12 @@ function createBackgroundProbe(options) {
 				options.onResult?.("skipped", `phase=${phase.kind}`);
 				return "skipped";
 			}
-			const same = phase.target.endpoint.url === endpoint.url && phase.target.endpoint.mode === endpoint.mode;
+			const current = phase.target.endpoint;
+			const same = current.url === endpoint.url && current.mode === endpoint.mode;
+			if (!same && options.prefer && options.prefer(current) && !options.prefer(endpoint) && options.isCurrentHealthy?.() === true) {
+				options.onResult?.("kept", current.url);
+				return "kept";
+			}
 			options.kernel.dispatch({
 				type: "ENDPOINT_SWAP",
 				endpoint,
@@ -780,8 +785,10 @@ function attachProbeLoop(options) {
 					return tokens;
 				} catch (err) {
 					let finalErr = err;
-					if (signal.aborted && !ctrl.signal.aborted && !isProbeFailure(err)) if (signal.reason === "race-settled") finalErr = makeProbeFailure("transient", "superseded");
-					else finalErr = makeProbeFailure("transient", `timeout (${(options.timeoutByMode ?? ((m) => DEFAULT_RACE_TIMEOUT_BY_MODE[m] ?? 5e3))(endpoint.mode)}ms)`);
+					if (signal.aborted && !ctrl.signal.aborted && !isProbeFailure(err)) {
+						if (signal.reason === "race-settled") finalErr = makeProbeFailure("transient", "superseded");
+						else finalErr = makeProbeFailure("transient", `timeout (${(options.timeoutByMode ?? ((m) => DEFAULT_RACE_TIMEOUT_BY_MODE[m] ?? 5e3))(endpoint.mode)}ms)`);
+					}
 					options.onProbeError?.(endpoint, finalErr);
 					throw finalErr;
 				}
@@ -1119,7 +1126,8 @@ function attachWorkerBridge(options) {
 		return {
 			type: "kernel-sync",
 			generation,
-			phase
+			phase,
+			resolver: options.resolveServers !== void 0
 		};
 	}
 	function broadcast(phase) {
@@ -1153,13 +1161,46 @@ function attachWorkerBridge(options) {
 			});
 		}
 	}
+	async function answerResolve(host, req) {
+		const reply = (msg) => {
+			try {
+				host.postMessage({
+					type: "kernel-resolve-reply",
+					id: req.id,
+					...msg
+				});
+			} catch (err) {
+				log.warn("resolve reply postMessage failed", err);
+			}
+		};
+		if (!options.resolveServers) {
+			reply({ servers: [...req.defaultServers] });
+			return;
+		}
+		const phase = options.kernel.phase;
+		if (phase.kind !== "online") {
+			reply({ error: `kernel ${phase.kind}` });
+			return;
+		}
+		try {
+			reply({ servers: await options.resolveServers({
+				target: phase.target,
+				connId: req.connId,
+				defaultServers: req.defaultServers
+			}) });
+		} catch (err) {
+			reply({ error: err instanceof Error ? err.message : String(err) });
+		}
+	}
 	function maybeAttachHostListener(host) {
-		if (!options.listenForResyncRequests) return;
+		if (!options.listenForResyncRequests && !options.resolveServers) return;
 		if (!host.addEventListener) return;
 		if (hostListenerCleanups.has(host)) return;
 		const listener = (event) => {
 			if (detached) return;
-			if (event.data?.type === "kernel-sync-request") syncOne(host);
+			const msg = event.data;
+			if (msg?.type === "kernel-sync-request" && options.listenForResyncRequests) syncOne(host);
+			else if (msg?.type === "kernel-resolve-request") answerResolve(host, msg);
 		};
 		host.addEventListener("message", listener);
 		hostListenerCleanups.set(host, () => {

package/dist/transports/http.d.ts

@@ -1,12 +1,14 @@
 import { Logger } from '@camera.ui/logger';
-import { AxiosInstance, AxiosRequestConfig } from 'axios';
-import { TransportSpec } from '../core/types.js';
+import { AxiosInstance, AxiosRequestConfig, InternalAxiosRequestConfig } from 'axios';
+import { ConnectionTarget, TransportSpec } from '../core/types.js';
 import { Transport } from './contract.js';
+export type HttpAuthorizer = (config: InternalAxiosRequestConfig, target: ConnectionTarget) => void | Promise<void>;
 export interface HttpTransportOptions {
     readonly apiPrefix?: string;
     readonly timeoutMs?: number;
     readonly targetWaitMs?: number;
     readonly spec?: Partial<TransportSpec>;
+    readonly authorize?: HttpAuthorizer;
     readonly logger?: Logger;
 }
 export interface HttpTransport extends Transport {

package/dist/transports/http.js

@@ -57,7 +57,8 @@ function createHttpTransport(options = {}) {
 		const target = currentTarget;
 		if (!target) throw new axios.Cancel("http-transport: no target");
 		if (!config.baseURL) config.baseURL = `${target.endpoint.url}${apiPrefix}`;
-		config.headers.set("Authorization", `Bearer ${target.tokens.access}`);
+		if (options.authorize) await options.authorize(config, target);
+		else config.headers.set("Authorization", `Bearer ${target.tokens.access}`);
 		if (target.tokens.proxySession) config.headers.set("X-Proxy-Session", target.tokens.proxySession);
 		return config;
 	});

package/dist/transports/nats.d.ts

@@ -1,10 +1,17 @@
 import { Logger } from '@camera.ui/logger';
 import { RPCClient } from '@camera.ui/rpc';
-import { TransportSpec, TransportStatus } from '../core/types.js';
+import { ConnectionTarget, TransportSpec, TransportStatus } from '../core/types.js';
 import { Transport, Unsubscribe } from './contract.js';
+export interface ResolveServersContext {
+    readonly target: ConnectionTarget;
+    readonly connId: string;
+    readonly defaultServers: readonly string[];
+}
+export type ServersResolver = (ctx: ResolveServersContext) => Promise<string[]>;
 export interface NatsTransportOptions {
     readonly spec?: Partial<TransportSpec>;
     readonly proxyPath?: string;
+    readonly resolveRefreshMs?: number;
     readonly clientName?: string;
     readonly natsUser?: string;
     readonly natsPassword?: string;
@@ -17,6 +24,7 @@ export interface NatsTransportOptions {
     readonly pingTimeout?: number;
     readonly maxPingOut?: number;
     readonly logger?: Logger;
+    readonly resolveServers?: ServersResolver;
 }
 export type NatsClientListener = (client: RPCClient | null) => void;
 export interface NatsTransport extends Transport {

package/dist/transports/nats.js

@@ -35,8 +35,11 @@ function createNatsTransport(options = {}) {
 	const pingTimeout = options.pingTimeout ?? 2e4;
 	const maxPingOut = options.maxPingOut ?? 1;
 	const logger = options.logger;
+	const resolveServers = options.resolveServers;
+	const resolveRefreshMs = options.resolveRefreshMs ?? 0;
 	const emitter = new TransportEmitter();
 	const clientListeners = /* @__PURE__ */ new Set();
+	let refreshTimer = null;
 	let proxy = null;
 	let currentTarget = null;
 	let status = { up: false };
@@ -55,6 +58,53 @@ function createNatsTransport(options = {}) {
 		if (connId) params.set("connId", connId);
 		return [`${wsProtocol}//${url.hostname}:${port}${prefix}${proxyPath}?${params.toString()}`];
 	}
+	async function serversFor(target) {
+		const defaultServers = buildServers(target);
+		if (!resolveServers) return defaultServers;
+		return resolveServers({
+			target,
+			connId: connId ?? "",
+			defaultServers
+		});
+	}
+	async function refreshPool(p) {
+		const target = currentTarget;
+		if (!resolveServers || !target || disposed) return;
+		try {
+			const servers = await serversFor(target);
+			if (proxy === p && !disposed) p.setServers(servers);
+		} catch (err) {
+			logger?.warn(`server refresh failed: ${stringifyError(err)}`);
+		}
+	}
+	function stopRefresh() {
+		if (refreshTimer) {
+			clearInterval(refreshTimer);
+			refreshTimer = null;
+		}
+	}
+	function startRefresh(p) {
+		stopRefresh();
+		if (!resolveServers || resolveRefreshMs <= 0) return;
+		refreshTimer = setInterval(() => void refreshPool(p), resolveRefreshMs);
+	}
+	async function resign(reason) {
+		const target = currentTarget;
+		if (!proxy || !target || disposed) return;
+		logger?.debug(`resign (${reason})`);
+		const epoch = ++applyEpoch;
+		stopStatusMonitor();
+		stopRefresh();
+		try {
+			proxy.abortClose();
+		} catch {}
+		proxy = null;
+		notifyClient();
+		markDown(`signature-expired: ${reason}`);
+		try {
+			await rebuildClient(target, epoch);
+		} catch {}
+	}
 	function notifyClient() {
 		const next = status.up ? proxy : null;
 		for (const fn of [...clientListeners]) try {
@@ -98,14 +148,13 @@ function createNatsTransport(options = {}) {
 					case "disconnect":
 						markDown("disconnect");
 						notifyClient();
+						if (resolveServers) refreshPool(p);
 						break;
 					case "staleConnection":
 						markDown("staleConnection");
 						notifyClient();
 						break;
-					case "error":
-						handleErrorEvent(event);
-						break;
+					case "error": handleErrorEvent(event);
 				}
 			}
 		})().catch(() => {});
@@ -121,6 +170,10 @@ function createNatsTransport(options = {}) {
 			message
 		} : message);
 		if (cls === "auth-expired") {
+			if (resolveServers) {
+				resign(message);
+				return;
+			}
 			emitter.emit("auth-error", { message });
 			return;
 		}
@@ -135,6 +188,7 @@ function createNatsTransport(options = {}) {
 		logger?.debug(`rebuildClient start (epoch=${epoch})`);
 		const t0 = Date.now();
 		stopStatusMonitor();
+		stopRefresh();
 		pendingConnectAbort?.abort();
 		if (proxy) {
 			try {
@@ -144,8 +198,19 @@ function createNatsTransport(options = {}) {
 			notifyClient();
 		}
 		connId = newConnId();
+		let servers;
+		try {
+			servers = await serversFor(target);
+		} catch (err) {
+			if (disposed || epoch !== applyEpoch) return;
+			const msg = stringifyError(err);
+			logger?.debug(`rebuildClient resolve FAILED: ${msg}`);
+			markDown(msg);
+			throw err;
+		}
+		if (disposed || epoch !== applyEpoch) return;
 		const next = createRPCClient({
-			servers: buildServers(target),
+			servers,
 			name: clientName,
 			connId,
 			auth: {
@@ -175,7 +240,7 @@ function createNatsTransport(options = {}) {
 			if (disposed || epoch !== applyEpoch) return;
 			const msg = err instanceof Error ? err.message : String(err);
 			logger?.debug(`rebuildClient connect FAILED after ${Date.now() - t0}ms: ${msg}`);
-			if (classifyClose(err instanceof Error ? err : msg) === "auth-expired") emitter.emit("auth-error", { message: msg });
+			if (!resolveServers && classifyClose(err instanceof Error ? err : msg) === "auth-expired") emitter.emit("auth-error", { message: msg });
 			markDown(msg);
 			throw err;
 		} finally {
@@ -192,6 +257,7 @@ function createNatsTransport(options = {}) {
 		markUp();
 		notifyClient();
 		startStatusMonitor(next);
+		startRefresh(next);
 	}
 	async function apply(target) {
 		if (disposed) throw new Error("nats-transport disposed");
@@ -201,6 +267,7 @@ function createNatsTransport(options = {}) {
 		currentTarget = target;
 		if (!target) {
 			stopStatusMonitor();
+			stopRefresh();
 			pendingConnectAbort?.abort();
 			pendingConnectAbort = null;
 			if (proxy) {
@@ -222,8 +289,9 @@ function createNatsTransport(options = {}) {
 			}
 			return;
 		}
-		const newServers = buildServers(target);
-		proxy.setServers(newServers);
+		const p = proxy;
+		const newServers = await serversFor(target);
+		if (proxy === p && epoch === applyEpoch) p.setServers(newServers);
 	}
 	function health() {
 		if (status.up && proxy?.isStale) return {
@@ -239,6 +307,7 @@ function createNatsTransport(options = {}) {
 		disposed = true;
 		applyEpoch++;
 		stopStatusMonitor();
+		stopRefresh();
 		pendingConnectAbort?.abort();
 		pendingConnectAbort = null;
 		if (proxy) {

package/dist/transports/socketio.d.ts

@@ -1,11 +1,19 @@
 import { Manager, Socket } from 'socket.io-client';
 import { Logger } from '@camera.ui/logger';
-import { TransportSpec, TransportStatus } from '../core/types.js';
+import { ConnectionTarget, TransportSpec, TransportStatus } from '../core/types.js';
 import { Transport } from './contract.js';
 export type { Socket };
+export interface ResolveSocketQueryContext {
+    readonly target: ConnectionTarget;
+    readonly path: string;
+    readonly query: Record<string, string>;
+}
+export type SocketQueryResolver = (ctx: ResolveSocketQueryContext) => Promise<Record<string, string>>;
 export interface SocketioTransportOptions {
     readonly spec?: Partial<TransportSpec>;
     readonly path?: string;
+    readonly resolveQuery?: SocketQueryResolver;
+    readonly resolveRefreshMs?: number;
     readonly mainNamespace?: string;
     readonly reconnection?: boolean;
     readonly reconnectionDelay?: number;

package/dist/transports/socketio.js

@@ -19,10 +19,14 @@ function createSocketioTransport(options = {}) {
 	const reconnectionDelayMax = options.reconnectionDelayMax ?? 5e3;
 	const timeout = options.timeout ?? 2e4;
 	const logger = options.logger;
+	const resolveQuery = options.resolveQuery;
+	const resolveRefreshMs = options.resolveRefreshMs ?? 0;
 	const emitter = new TransportEmitter();
 	const sockets = /* @__PURE__ */ new Map();
 	let manager = null;
 	let currentTarget = null;
+	let currentQuery = {};
+	let refreshTimer = null;
 	let status = { up: false };
 	let disposed = false;
 	const staleAfterMs = options.staleAfterMs ?? 6e4;
@@ -43,6 +47,38 @@ function createSocketioTransport(options = {}) {
 		if (target.tokens.proxySession) q.session = target.tokens.proxySession;
 		return q;
 	}
+	async function queryFor(target) {
+		const base = buildQuery(target);
+		if (!resolveQuery) return base;
+		return resolveQuery({
+			target,
+			path: socketPath(target),
+			query: base
+		});
+	}
+	async function refreshQuery() {
+		const target = currentTarget;
+		if (!resolveQuery || !target || disposed) return;
+		try {
+			const query = await queryFor(target);
+			if (currentTarget !== target || disposed) return;
+			currentQuery = query;
+			for (const sock of sockets.values()) sock.io.opts.query = query;
+		} catch (err) {
+			logger?.warn(`query refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	function stopRefresh() {
+		if (refreshTimer) {
+			clearInterval(refreshTimer);
+			refreshTimer = null;
+		}
+	}
+	function startRefresh() {
+		stopRefresh();
+		if (!resolveQuery || resolveRefreshMs <= 0) return;
+		refreshTimer = setInterval(() => void refreshQuery(), resolveRefreshMs);
+	}
 	function markUp() {
 		if (status.up) return;
 		status = { up: true };
@@ -63,7 +99,10 @@ function createSocketioTransport(options = {}) {
 	}
 	function bindMainSocketEvents(socket) {
 		socket.on("connect", () => markUp());
-		socket.on("disconnect", (reason) => markDown(reason));
+		socket.on("disconnect", (reason) => {
+			markDown(reason);
+			if (resolveQuery) refreshQuery();
+		});
 		socket.on("connect_error", (err) => {
 			const msg = err?.message ?? "connect_error";
 			logger?.debug(`connect_error (main): ${msg}`);
@@ -87,10 +126,11 @@ function createSocketioTransport(options = {}) {
 		return `${new URL(target.endpoint.url).pathname.replace(/\/$/, "")}${path}`;
 	}
 	function openSocket(namespace, target) {
-		const sock = io(`${socketOrigin(target)}${namespace}`, {
+		const url = `${socketOrigin(target)}${namespace}`;
+		const sock = io(url, {
 			path: socketPath(target),
 			auth: buildAuth(target),
-			query: buildQuery(target),
+			query: currentQuery,
 			reconnection,
 			reconnectionDelay,
 			reconnectionDelayMax,
@@ -101,8 +141,18 @@ function createSocketioTransport(options = {}) {
 		sockets.set(namespace, sock);
 		return sock;
 	}
-	function rebuildManager(target) {
+	async function rebuildManager(target) {
+		stopRefresh();
+		let query;
+		try {
+			query = await queryFor(target);
+		} catch (err) {
+			markDown(err instanceof Error ? err.message : String(err));
+			throw err;
+		}
+		if (currentTarget !== target || disposed) return;
 		closeAllSockets();
+		currentQuery = query;
 		manager = new Manager(socketOrigin(target), {
 			path: socketPath(target),
 			autoConnect: false,
@@ -115,6 +165,7 @@ function createSocketioTransport(options = {}) {
 		});
 		const main = openSocket(mainNs, target);
 		bindMainSocketEvents(main);
+		startRefresh();
 		lastActivityAt = Date.now();
 		main.io.on("open", touchActivity);
 		main.io.on("ping", touchActivity);
@@ -145,12 +196,13 @@ function createSocketioTransport(options = {}) {
 		currentTarget = target;
 		if (!target) {
 			closeAllSockets();
+			stopRefresh();
 			lastActivityAt = 0;
 			markDown("detached");
 			return;
 		}
 		if (endpointChanged || !manager) {
-			rebuildManager(target);
+			await rebuildManager(target);
 			return;
 		}
 		rebindAuth(target);
@@ -168,6 +220,7 @@ function createSocketioTransport(options = {}) {
 	async function dispose() {
 		disposed = true;
 		closeAllSockets();
+		stopRefresh();
 		currentTarget = null;
 		status = { up: false };
 		emitter.clear();
@@ -176,7 +229,7 @@ function createSocketioTransport(options = {}) {
 		return sockets.get(namespace) ?? null;
 	}
 	function ensureSocket(namespace) {
-		if (!currentTarget) return null;
+		if (!currentTarget || !manager) return null;
 		let sock = sockets.get(namespace);
 		if (!sock) {
 			sock = openSocket(namespace, currentTarget);
@@ -203,6 +256,7 @@ function createSocketioTransport(options = {}) {
 	}
 	async function ensureAlive() {
 		if (disposed || !currentTarget) return health();
+		if (resolveQuery) await refreshQuery();
 		reviveDeadSockets();
 		return health();
 	}

package/dist/transports/ws.d.ts

@@ -1,5 +1,5 @@
 import { Logger } from '@camera.ui/logger';
-import { TransportSpec } from '../core/types.js';
+import { ConnectionTarget, TransportSpec } from '../core/types.js';
 import { PerResourceTransport, Unsubscribe } from './contract.js';
 export interface WsHandleSpec {
     readonly path: string;
@@ -23,12 +23,19 @@ export interface WsHandle {
     on<E extends WsEvent>(event: E, handler: WsEventHandler<E>): Unsubscribe;
     dispose(): void;
 }
+export interface ResolveWsUrlContext {
+    readonly target: ConnectionTarget;
+    readonly spec: WsHandleSpec;
+    readonly defaultUrl: string;
+}
+export type WsUrlResolver = (ctx: ResolveWsUrlContext) => Promise<string>;
 export interface WsTransportOptions {
     readonly spec?: Partial<TransportSpec>;
     readonly webSocketCtor?: typeof WebSocket;
     readonly tokenParam?: string;
     readonly sessionParam?: string;
     readonly logger?: Logger;
+    readonly resolveUrl?: WsUrlResolver;
 }
 export interface WsTransport extends PerResourceTransport<WsHandle, WsHandleSpec> {
     readonly handleCount: number;

package/dist/transports/ws.js

@@ -9,6 +9,7 @@ var WS_SPEC = {
 var WS_CLOSE_TARGET_CHANGED = 4e3;
 var WS_CLOSE_DETACHED = 4001;
 var WS_CLOSE_DISPOSED = 4002;
+var WS_CLOSE_RESOLVE_FAILED = 4003;
 function createWsTransport(options = {}) {
 	const spec = {
 		...WS_SPEC,
@@ -17,6 +18,7 @@ function createWsTransport(options = {}) {
 	const tokenParam = options.tokenParam ?? "token";
 	const sessionParam = options.sessionParam ?? "session";
 	const WsCtor = options.webSocketCtor ?? (typeof WebSocket !== "undefined" ? WebSocket : void 0);
+	const resolveUrl = options.resolveUrl;
 	const logger = options.logger;
 	const emitter = new TransportEmitter();
 	const handles = /* @__PURE__ */ new Set();
@@ -83,6 +85,7 @@ function createWsTransport(options = {}) {
 		};
 	}
 	function closeWs(handle, code, reason) {
+		handle.openSeq++;
 		const ws = handle.ws;
 		if (!ws) return;
 		const Ctor = ensureCtor();
@@ -105,16 +108,42 @@ function createWsTransport(options = {}) {
 		};
 		for (const fn of [...handle.listeners.close]) fn(info);
 	}
-	function openWs(handle) {
-		if (handle.disposed) return;
-		if (!currentTarget) return;
-		const url = buildUrl(currentTarget, handle.spec);
+	function connectWs(handle, url) {
 		const ws = new (ensureCtor())(url, handle.spec.protocols);
 		if (handle.spec.binaryType) ws.binaryType = handle.spec.binaryType;
 		handle.ws = ws;
 		handle.url = url;
 		bindWs(handle, ws);
 	}
+	function openWs(handle) {
+		if (handle.disposed) return;
+		if (!currentTarget) return;
+		const target = currentTarget;
+		const defaultUrl = buildUrl(target, handle.spec);
+		if (!resolveUrl) {
+			connectWs(handle, defaultUrl);
+			return;
+		}
+		const seq = ++handle.openSeq;
+		resolveUrl({
+			target,
+			spec: handle.spec,
+			defaultUrl
+		}).then((url) => {
+			if (handle.disposed || seq !== handle.openSeq || currentTarget !== target) return;
+			connectWs(handle, url);
+		}, (err) => {
+			if (handle.disposed || seq !== handle.openSeq) return;
+			const reason = err instanceof Error ? err.message : String(err);
+			logger?.warn(`resolveUrl failed for ${handle.spec.path}: ${reason}`);
+			const info = {
+				code: WS_CLOSE_RESOLVE_FAILED,
+				reason: "resolve-failed",
+				wasClean: false
+			};
+			for (const fn of [...handle.listeners.close]) fn(info);
+		});
+	}
 	function recycleAll(code, reason) {
 		const snapshot = [...handles];
 		logger?.debug(`recycleAll (${reason}) handles=${snapshot.length}`);
@@ -178,7 +207,8 @@ function createWsTransport(options = {}) {
 			},
 			ws: null,
 			url: null,
-			disposed: false
+			disposed: false,
+			openSeq: 0
 		};
 		function send(data) {
 			if (handle.disposed) throw new Error("ws-handle disposed");

package/dist/worker/index.d.ts

@@ -1,3 +1,3 @@
 export { createWorkerKernelMirror } from './mirror.js';
-export type { MirrorListener, Unsubscribe, WorkerKernelMirror, WorkerKernelMirrorOptions } from './mirror.js';
-export type { KernelSyncMessage, KernelSyncRequestMessage, MessageSource, WorkerHost, WorkerMessage } from './protocol.js';
+export type { MirrorListener, MirrorResolveContext, Unsubscribe, WorkerKernelMirror, WorkerKernelMirrorOptions } from './mirror.js';
+export type { KernelResolveReplyMessage, KernelResolveRequestMessage, KernelSyncMessage, KernelSyncRequestMessage, MessageSource, WorkerHost, WorkerMessage, } from './protocol.js';

package/dist/worker/mirror.d.ts

@@ -2,16 +2,23 @@ import { ConnectionPhase, ConnectionTarget } from '../core/types.js';
 import { MessageSource } from './protocol.js';
 export type Unsubscribe = () => void;
 export type MirrorListener = (next: ConnectionPhase, prev: ConnectionPhase) => void;
+export interface MirrorResolveContext {
+    readonly connId: string;
+    readonly defaultServers: readonly string[];
+}
 export interface WorkerKernelMirror {
     readonly phase: ConnectionPhase;
     readonly target: ConnectionTarget | null;
+    readonly hasResolver: boolean;
     subscribe(listener: MirrorListener): Unsubscribe;
     onRevalidate(listener: () => void): Unsubscribe;
     requestSync(): void;
+    resolveServers(ctx: MirrorResolveContext): Promise<string[]>;
     dispose(): void;
 }
 export interface WorkerKernelMirrorOptions {
     readonly source: MessageSource;
     readonly initial?: ConnectionPhase;
+    readonly resolveTimeoutMs?: number;
 }
 export declare function createWorkerKernelMirror(options: WorkerKernelMirrorOptions): WorkerKernelMirror;

package/dist/worker/protocol.d.ts

@@ -3,6 +3,7 @@ export interface KernelSyncMessage {
     readonly type: 'kernel-sync';
     readonly generation: number;
     readonly phase: ConnectionPhase;
+    readonly resolver?: boolean;
 }
 export interface KernelSyncRequestMessage {
     readonly type: 'kernel-sync-request';
@@ -10,7 +11,19 @@ export interface KernelSyncRequestMessage {
 export interface KernelRevalidateMessage {
     readonly type: 'kernel-revalidate';
 }
-export type WorkerMessage = KernelSyncMessage | KernelSyncRequestMessage | KernelRevalidateMessage;
+export interface KernelResolveRequestMessage {
+    readonly type: 'kernel-resolve-request';
+    readonly id: number;
+    readonly connId: string;
+    readonly defaultServers: readonly string[];
+}
+export interface KernelResolveReplyMessage {
+    readonly type: 'kernel-resolve-reply';
+    readonly id: number;
+    readonly servers?: string[];
+    readonly error?: string;
+}
+export type WorkerMessage = KernelSyncMessage | KernelSyncRequestMessage | KernelRevalidateMessage | KernelResolveRequestMessage | KernelResolveReplyMessage;
 export interface MessageSource {
     postMessage(message: WorkerMessage): void;
     addEventListener(type: 'message', listener: (event: MessageEvent<WorkerMessage>) => void): void;

package/dist/worker.js

@@ -2,13 +2,29 @@
 function createWorkerKernelMirror(options) {
 	let current = options.initial ?? { kind: "idle" };
 	let lastGeneration = -1;
+	let hasResolver = false;
 	const listeners = /* @__PURE__ */ new Set();
 	const revalidateListeners = /* @__PURE__ */ new Set();
+	const pending = /* @__PURE__ */ new Map();
+	const resolveTimeoutMs = options.resolveTimeoutMs ?? 15e3;
+	let nextResolveId = 1;
 	let disposed = false;
+	function settleResolve(id, servers, error) {
+		const entry = pending.get(id);
+		if (!entry) return;
+		pending.delete(id);
+		clearTimeout(entry.timer);
+		if (error !== void 0 || !servers) entry.reject(new Error(error ?? "resolve failed"));
+		else entry.resolve(servers);
+	}
 	function handler(event) {
 		if (disposed) return;
 		const msg = event.data;
 		if (!msg) return;
+		if (msg.type === "kernel-resolve-reply") {
+			settleResolve(msg.id, msg.servers, msg.error);
+			return;
+		}
 		if (msg.type === "kernel-revalidate") {
 			for (const l of [...revalidateListeners]) try {
 				l();
@@ -18,6 +34,7 @@ function createWorkerKernelMirror(options) {
 		if (msg.type !== "kernel-sync") return;
 		if (msg.generation <= lastGeneration) return;
 		lastGeneration = msg.generation;
+		hasResolver = msg.resolver === true;
 		const prev = current;
 		current = msg.phase;
 		if (phaseEquals(prev, current)) return;
@@ -44,6 +61,9 @@ function createWorkerKernelMirror(options) {
 		get target() {
 			return targetOf(current);
 		},
+		get hasResolver() {
+			return hasResolver;
+		},
 		subscribe(listener) {
 			listeners.add(listener);
 			return () => {
@@ -60,11 +80,30 @@ function createWorkerKernelMirror(options) {
 			if (disposed) return;
 			options.source.postMessage({ type: "kernel-sync-request" });
 		},
+		resolveServers(ctx) {
+			if (disposed) return Promise.reject(/* @__PURE__ */ new Error("mirror disposed"));
+			const id = nextResolveId++;
+			return new Promise((resolve, reject) => {
+				const timer = setTimeout(() => settleResolve(id, void 0, "resolve timeout"), resolveTimeoutMs);
+				pending.set(id, {
+					resolve,
+					reject,
+					timer
+				});
+				options.source.postMessage({
+					type: "kernel-resolve-request",
+					id,
+					connId: ctx.connId,
+					defaultServers: [...ctx.defaultServers]
+				});
+			});
+		},
 		dispose() {
 			disposed = true;
 			options.source.removeEventListener("message", handler);
 			listeners.clear();
 			revalidateListeners.clear();
+			for (const id of [...pending.keys()]) settleResolve(id, void 0, "mirror disposed");
 		}
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camera.ui/transport",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "camera.ui transport layer — framework-agnostic connection kernel, reducer state, pluggable transports (HTTP/WS/Socket.IO/NATS), lifecycle effects and worker bridge",
   "author": "seydx (https://github.com/cameraui/clients)",
   "type": "module",
@@ -56,26 +56,26 @@
   },
   "dependencies": {
     "@camera.ui/logger": ">=0.0.3",
-    "@camera.ui/rpc": ">=1.0.10",
-    "axios": ">=1.18.1",
+    "@camera.ui/rpc": ">=1.0.11",
+    "axios": ">=1.20.0",
     "socket.io-client": ">=4.8.3"
   },
   "devDependencies": {
     "@eslint/js": "9.39.4",
     "@stylistic/eslint-plugin": "^5.10.0",
-    "@typescript-eslint/parser": "^8.65.0",
-    "@vue/language-core": "^3.3.8",
+    "@typescript-eslint/parser": "^8.68.0",
+    "@vue/language-core": "^3.3.11",
     "eslint": "9.39.2",
-    "globals": "^17.8.0",
+    "globals": "^17.11.0",
     "jiti": "^2.7.0",
     "prettier": "^3.9.6",
     "rimraf": "^6.1.3",
     "typescript": "5.9.3",
-    "typescript-eslint": "^8.65.0",
+    "typescript-eslint": "^8.68.0",
     "unplugin-dts": "^1.0.3",
-    "updates": "^17.19.1",
-    "vite": "^8.1.5",
-    "vitest": "^4.1.10"
+    "updates": "^18.0.7",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
   },
   "overrides": {
     "@vue/language-core": "$@vue/language-core"