@deepseek-ai/dsh-experimental-liveshare 0.0.0-stage → 0.2.2-alpha.2

package/lib/owner-gateway/cli.js

@@ -0,0 +1,370 @@
+import { a as relayRefusal, c as relayEndpoint, i as retryBackoffSettled, r as retryBackoffNext, t as INITIAL_RETRY_BACKOFF } from "../retry-backoff-ccJYtzOj.js";
+import { randomUUID } from "node:crypto";
+import { LIVESHARE_CAPABILITIES, LIVESHARE_PROTOCOL_VERSION, parseRelayFrame, parseTunnelWorkerCommand, rawText, sendFrame, unsupportedFrameRefusal, viewerRequestFields } from "@deepseek-ai/dsh-experimental-liveshare-protocol";
+import { WebSocket } from "ws";
+//#region lib/types/owner-gateway/registration-url.js
+/**
+* The registration handshake one share is published with.
+*
+* This URL is the one surface an older owner meets a newer Relay on, so what it states about the
+* owner — the protocol version it reads frames with, and the capabilities it offers beyond them — is
+* the only thing a Relay can compare instead of assuming. Keeping the whole handshake in one function
+* is what lets a check pin it: every parameter here is read by a peer this repository does not build.
+*/
+/**
+* Build the WebSocket URL one share registers with.
+*
+* Absent optionals stay absent rather than being sent empty: the Relay reads a missing `sessionMode`
+* as view-only and a missing `allowsFork` as no forking, so an older owner publishes the narrower
+* share instead of a share whose fields a peer must interpret.
+* @param spec - Share the owner host asked this worker to carry.
+* @returns The registration URL, with this build's protocol version and capabilities stated.
+*/
+function registrationUrl(spec) {
+	const relay = relayEndpoint(spec.relay);
+	const url = new URL(`${relay.basePath}/__tunnel_gateway__`, relay.origin);
+	url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	url.searchParams.set("shareId", spec.shareId);
+	url.searchParams.set("sessionId", spec.sessionId);
+	url.searchParams.set("sessionTitle", spec.sessionTitle);
+	url.searchParams.set("accessMode", spec.accessMode);
+	url.searchParams.set("ownerDisplayName", spec.ownerDisplayName);
+	if (spec.dshVersion !== void 0 && spec.dshVersion !== "") url.searchParams.set("dshVersion", spec.dshVersion);
+	if (spec.ownerInstanceId !== void 0 && spec.ownerInstanceId !== "") url.searchParams.set("ownerInstanceId", spec.ownerInstanceId);
+	url.searchParams.set("protocolVersion", String(LIVESHARE_PROTOCOL_VERSION));
+	url.searchParams.set("capabilities", LIVESHARE_CAPABILITIES.join(","));
+	if (spec.allowsFork === true) url.searchParams.set("allowsFork", "1");
+	if (spec.sessionMode !== void 0) url.searchParams.set("sessionMode", spec.sessionMode);
+	if (spec.ownerProviderId !== void 0 && spec.ownerProviderId !== "") url.searchParams.set("ownerProviderId", spec.ownerProviderId);
+	if (spec.ownerTenantId !== void 0 && spec.ownerTenantId !== "") url.searchParams.set("ownerTenantId", spec.ownerTenantId);
+	for (const subject of spec.allowedSubjectIds) url.searchParams.append("allowedSubjectId", subject);
+	if (spec.expiresAt !== void 0 && spec.expiresAt !== "") url.searchParams.set("expiresAt", spec.expiresAt);
+	return url;
+}
+//#endregion
+//#region lib/types/owner-gateway/pending-rpc.js
+/** Correlate IPC requests by worker-issued tokens and Relay ids by their exact socket. */
+/** Request identities remain distinct when a Relay reconnects and reuses its numeric ids. */
+var PendingRpc = class {
+	tokens = /* @__PURE__ */ new Map();
+	owners = /* @__PURE__ */ new Map();
+	/**
+	* Register a request with a new IPC token.
+	* @param shareId Share carrying the request.
+	* @param id Relay id on this socket.
+	* @param owner Exact socket that received the request.
+	* @returns Registered request; an existing id must be cancelled before reuse on the same socket.
+	*/
+	add(shareId, id, owner) {
+		const request = {
+			token: randomUUID(),
+			shareId,
+			id,
+			owner,
+			since: Date.now()
+		};
+		let requests = this.owners.get(owner);
+		if (requests === void 0) {
+			requests = /* @__PURE__ */ new Map();
+			this.owners.set(owner, requests);
+		}
+		if (requests.has(id)) throw new Error("Relay request id is already pending on this socket");
+		requests.set(id, request);
+		this.tokens.set(request.token, request);
+		return request;
+	}
+	/**
+	* Claim an answer only when all IPC correlation fields match.
+	* @param answer Token, share and Relay id echoed by the Host.
+	* @returns The request removed from pending state, or undefined for a stale or mismatched answer.
+	*/
+	take(answer) {
+		const request = this.tokens.get(answer.token);
+		if (request === void 0 || request.shareId !== answer.shareId || request.id !== answer.id) return void 0;
+		return this.cancel(request.owner, request.id);
+	}
+	/**
+	* Remove one socket-local request.
+	* @param owner Socket receiving the cancellation.
+	* @param id Relay id on that socket.
+	* @returns Removed request for cancellation notification, or undefined if it already settled.
+	*/
+	cancel(owner, id) {
+		const requests = this.owners.get(owner);
+		const request = requests?.get(id);
+		if (request === void 0) return void 0;
+		this.tokens.delete(request.token);
+		requests?.delete(id);
+		if (requests?.size === 0) this.owners.delete(owner);
+		return request;
+	}
+	/**
+	* Remove all requests on a closed socket.
+	* @param owner Socket being disposed.
+	* @returns Removed requests for Host cancellation notifications.
+	*/
+	clear(owner) {
+		const requests = [...this.owners.get(owner)?.values() ?? []];
+		for (const request of requests) this.tokens.delete(request.token);
+		this.owners.delete(owner);
+		return requests;
+	}
+};
+//#endregion
+//#region lib/types/owner-gateway/worker.js
+/** Owner-side gateway worker: one process multiplexes every share over IPC to the owner host. */
+const HEARTBEAT_INTERVAL_MS = 25e3;
+/**
+* Consecutive unanswered heartbeats tolerated before this worker drops its own Relay socket.
+*
+* One miss means a busy event loop, not a dead connection: terminating there aborts every in-flight
+* viewer stream on the share and forces a re-registration, which is the periodic reconnect an owner
+* would otherwise never see the cause of.
+*/
+const GATEWAY_MAX_MISSED_PONGS = 2;
+/** IPC tokens identify requests; socket-local Relay ids never select a Host response. */
+const pendingRpc = new PendingRpc();
+/**
+* Run one owner worker that multiplexes every share over IPC. The worker owns
+* one outbound Relay socket per share, but one process and one owner DSH.
+*/
+function runGatewayWorker() {
+	const shares = /* @__PURE__ */ new Map();
+	notifyWorker({ type: "ready" });
+	process.on("message", (value) => {
+		const command = parseTunnelWorkerCommand(value);
+		if (command === void 0) {
+			console.warn("[liveshare] worker refused one owner command");
+			return;
+		}
+		if (command.type === "share-rpc-response") {
+			if ((shares.get(command.shareId)?.gateway)?.registrationToken !== command.registrationToken) return;
+			const request = pendingRpc.take(command);
+			if (request === void 0) {
+				console.warn(`[liveshare] worker dropped late read response relayId=${String(command.id)}`);
+				return;
+			}
+			const gateway = request.owner.socket;
+			if (gateway.readyState === WebSocket.OPEN) {
+				const observed = viewerRequestFields(command.body);
+				console.log(`[liveshare] worker read answered share=${request.shareId} relayId=${String(command.id)} op=${observed.op} streamId=${observed.streamId} status=${String(command.status)} elapsedMs=${String(Date.now() - request.since)}`);
+				sendFrame(gateway, {
+					type: "share-rpc-res",
+					id: command.id,
+					status: command.status,
+					...command.body === void 0 ? {} : { body: command.body }
+				});
+			} else console.warn(`[liveshare] worker cannot deliver read response share=${request.shareId} relayId=${String(command.id)} — gateway is not connected`);
+			return;
+		}
+		if (command.type === "add-share") addShare(shares, command.share, command.registrationToken);
+		else if (command.type === "remove-share") {
+			console.warn(`[liveshare] worker dropping one share by owner command share=${command.shareId}`);
+			removeShare(shares, command.shareId);
+		} else {
+			console.warn(`[liveshare] worker shutting down command=${String(command.type)} shares=${String(shares.size)}`);
+			for (const shareId of [...shares.keys()]) removeShare(shares, shareId);
+			process.exit(0);
+		}
+	});
+	process.on("disconnect", () => {
+		console.warn(`[liveshare] worker lost its host connection shares=${String(shares.size)}`);
+		for (const shareId of [...shares.keys()]) removeShare(shares, shareId);
+		process.exit(0);
+	});
+}
+function addShare(shares, spec, registrationToken) {
+	if (shares.get(spec.shareId)?.registrationToken === registrationToken) return;
+	removeShare(shares, spec.shareId);
+	const state = {
+		spec,
+		registrationToken,
+		accessVersion: void 0,
+		gateway: void 0,
+		heartbeat: void 0,
+		retryTimer: void 0,
+		retry: INITIAL_RETRY_BACKOFF,
+		openedAt: void 0,
+		stopped: false
+	};
+	shares.set(spec.shareId, state);
+	connectShare(shares, state);
+}
+function removeShare(shares, shareId) {
+	const state = shares.get(shareId);
+	if (state === void 0) return;
+	state.stopped = true;
+	if (state.retryTimer !== void 0) clearTimeout(state.retryTimer);
+	clearInterval(state.heartbeat);
+	if (state.gateway !== void 0) clearPendingRpc(state.gateway);
+	state.gateway?.socket.close(1e3, "share removed");
+	shares.delete(shareId);
+}
+function connectShare(shares, state) {
+	const gateway = new WebSocket(registrationUrl(state.spec), { headers: {
+		authorization: `Bearer ${state.spec.gatewayToken}`,
+		...state.spec.ownerCredential === void 0 || state.spec.ownerCredential === "" ? {} : { "x-liveshare-owner-credential": state.spec.ownerCredential }
+	} });
+	const connection = {
+		socket: gateway,
+		registrationToken: state.registrationToken
+	};
+	state.gateway = connection;
+	let awaitingPong = false;
+	let missedPongs = 0;
+	let closeReason = "unknown";
+	let handshakeStatus;
+	state.heartbeat = setInterval(() => {
+		if (gateway.readyState !== WebSocket.OPEN) return;
+		if (awaitingPong) {
+			missedPongs += 1;
+			if (missedPongs >= GATEWAY_MAX_MISSED_PONGS) {
+				closeReason = `heartbeat-timeout missedPongs=${String(missedPongs)}`;
+				gateway.terminate();
+				return;
+			}
+			console.warn(`[liveshare] worker heartbeat missed share=${state.spec.shareId} missedPongs=${String(missedPongs)}`);
+			return;
+		}
+		awaitingPong = true;
+		gateway.ping();
+	}, HEARTBEAT_INTERVAL_MS);
+	gateway.on("pong", () => {
+		awaitingPong = false;
+		missedPongs = 0;
+	});
+	gateway.on("open", () => {
+		if (state.stopped || state.gateway !== connection) return;
+		state.openedAt = Date.now();
+		notifyWorker({
+			type: "share-connected",
+			registrationToken: state.registrationToken,
+			shareId: state.spec.shareId
+		});
+	});
+	gateway.on("message", (data) => {
+		awaitingPong = false;
+		missedPongs = 0;
+		const text = rawText(data);
+		const frame = parseRelayFrame(text);
+		if (frame !== void 0) {
+			if (!state.stopped && state.gateway === connection) handleGatewayFrame(state, connection, frame);
+			return;
+		}
+		const refusal = unsupportedFrameRefusal(text);
+		console.warn(`[liveshare] worker refused one relay frame share=${state.spec.shareId} frame=${refusal === void 0 ? "unanswerable" : `status=${String(refusal.status)} relayId=${String(refusal.id)}`}`);
+		if (refusal !== void 0 && !state.stopped && state.gateway === connection) sendFrame(gateway, refusal);
+	});
+	gateway.on("close", (code, socketReason) => {
+		clearPendingRpc(connection);
+		if (state.gateway !== connection) return;
+		clearInterval(state.heartbeat);
+		state.gateway = void 0;
+		state.accessVersion = void 0;
+		if (state.stopped) return;
+		console.warn(`[liveshare] worker gateway closed share=${state.spec.shareId} code=${String(code)} reason=${closeReason} socketReason=${socketReason.toString()} retryMs=${String(state.retry.delayMs)}`);
+		const refusal = relayRefusal(handshakeStatus);
+		if (refusal !== void 0) {
+			state.stopped = true;
+			shares.delete(state.spec.shareId);
+			console.warn(`[liveshare] worker stopped share=${state.spec.shareId} ${refusal}`);
+			return;
+		}
+		if (state.openedAt !== void 0 && Date.now() - state.openedAt >= 3e4) state.retry = retryBackoffSettled();
+		state.openedAt = void 0;
+		const delayMs = state.retry.delayMs;
+		state.retry = retryBackoffNext(state.retry);
+		state.retryTimer = setTimeout(() => {
+			connectShare(shares, state);
+		}, delayMs);
+		notifyWorker({
+			type: "share-closed",
+			registrationToken: state.registrationToken,
+			shareId: state.spec.shareId
+		});
+	});
+	gateway.on("error", (error) => {
+		if (state.stopped || state.gateway !== connection) return;
+		const detail = (handshakeStatus === void 0 ? void 0 : relayRefusal(handshakeStatus) ?? `relay answered registration status=${String(handshakeStatus)}`) ?? (error instanceof Error ? error.message : String(error));
+		closeReason = `gateway-error ${detail}`;
+		notifyWorker({
+			type: "share-error",
+			registrationToken: state.registrationToken,
+			shareId: state.spec.shareId,
+			message: detail
+		});
+		gateway.terminate();
+	});
+	gateway.on("unexpected-response", (_request, response) => {
+		handshakeStatus = response.statusCode;
+		gateway.terminate();
+	});
+}
+function handleGatewayFrame(state, connection, frame) {
+	const shareId = state.spec.shareId;
+	switch (frame.type) {
+		case "share-access-state": {
+			if (state.accessVersion !== void 0 && state.accessVersion >= frame.version) return;
+			const { expiresAt: _expiresAt, ...retained } = state.spec;
+			state.spec = {
+				...retained,
+				accessMode: frame.accessMode,
+				allowedSubjectIds: frame.allowedSubjectIds,
+				sessionMode: frame.sessionMode,
+				allowsFork: frame.allowsFork === true,
+				...frame.expiresAt === void 0 ? {} : { expiresAt: frame.expiresAt }
+			};
+			state.accessVersion = frame.version;
+			notifyWorker({
+				...frame,
+				registrationToken: state.registrationToken,
+				shareId
+			});
+			return;
+		}
+		case "share-rpc": {
+			const previous = pendingRpc.cancel(connection, frame.id);
+			if (previous !== void 0) notifyCancellation(previous);
+			const request = pendingRpc.add(shareId, frame.id, connection);
+			const observed = viewerRequestFields(frame.body);
+			console.log(`[liveshare] worker read received share=${shareId} relayId=${String(frame.id)} op=${observed.op} streamId=${observed.streamId}`);
+			notifyWorker({
+				type: "share-rpc-request",
+				registrationToken: connection.registrationToken,
+				token: request.token,
+				id: frame.id,
+				shareId,
+				body: frame.body,
+				actor: frame.actor
+			});
+			return;
+		}
+		case "share-rpc-cancel": {
+			const request = pendingRpc.cancel(connection, frame.id);
+			if (request !== void 0) notifyCancellation(request);
+		}
+	}
+}
+function notifyWorker(event) {
+	if (process.send !== void 0) process.send(event);
+}
+/** Cancel Host work before forgetting requests on a closed Relay socket. */
+function clearPendingRpc(connection) {
+	for (const request of pendingRpc.clear(connection)) notifyCancellation(request);
+}
+function notifyCancellation(request) {
+	notifyWorker({
+		type: "share-rpc-cancel",
+		registrationToken: request.owner.registrationToken,
+		token: request.token,
+		shareId: request.shareId,
+		id: request.id
+	});
+}
+//#endregion
+//#region lib/types/owner-gateway/cli.js
+/** Entry point for the owner gateway worker, launched by the host over an IPC channel. */
+if (process.send === void 0) throw new Error("Liveshare gateway requires the owner worker IPC channel");
+runGatewayWorker();
+//#endregion
+export {};

package/lib/retry-backoff-ccJYtzOj.js

@@ -0,0 +1,121 @@
+//#region lib/types/host/relay-url.js
+/**
+* Normalize a public Relay base URL by removing query, hash, and trailing slashes.
+* @param value Public Relay URL or base URL.
+* @returns Canonical base URL without credentials, query, hash, or trailing slash.
+*/
+function normalizeRelayUrl(value) {
+	if (value === "") throw new Error("liveshare relayUrl must not be empty");
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error("liveshare relayUrl must be an absolute URL");
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("liveshare relayUrl must use http or https");
+	if (url.username !== "" || url.password !== "") throw new Error("liveshare relayUrl must not include credentials");
+	url.search = "";
+	url.hash = "";
+	url.pathname = url.pathname.replace(/\/+$/u, "");
+	return url.href.replace(/\/$/u, "");
+}
+/**
+* Split one Relay base URL into its origin and base path.
+* @param relay Public Relay URL or base URL.
+* @returns Validated origin and trailing-slash-free base path.
+*/
+function relayEndpoint(relay) {
+	const url = new URL(normalizeRelayUrl(relay));
+	return {
+		origin: url.origin,
+		basePath: url.pathname.replace(/\/+$/u, "")
+	};
+}
+//#endregion
+//#region lib/types/owner-gateway/relay-refusal.js
+/**
+* When a Relay handshake response ends one registration for good.
+*
+* The Relay answers a gateway handshake it will not establish with an HTTP status instead of
+* upgrading. A credential the Relay does not accept (401), one it forbids for this share (403), or a
+* share it no longer serves (410), or an unsupported protocol (426) ends this registration.
+* Reconnecting with the same token and protocol reaches the same answer, so the share stays offline and the status becomes its diagnostic
+* instead of a silent retry. Every other failure — a Relay that is down (5xx), a rate limit, a
+* timeout, a refused socket — is transient and keeps the ordinary reconnect schedule.
+*/
+/** The Relay handshake statuses that end a registration for good. */
+const RELAY_REFUSAL_STATUSES = [
+	401,
+	403,
+	410,
+	426
+];
+/**
+* Read one handshake status as a decision about the registration it carried.
+* @param status HTTP status the Relay answered the gateway handshake with, if it answered.
+* @returns The refusal to report, or undefined when the failure is worth retrying.
+*/
+function relayRefusal(status) {
+	if (status !== void 0 && RELAY_REFUSAL_STATUSES.includes(status)) return `relay refused registration status=${String(status)}`;
+}
+/** The one form every permanent refusal reaches a Host as; nothing else composes it. */
+const RELAY_REFUSAL_MESSAGE = /^relay refused registration status=(\d+)$/u;
+/**
+* Read one reported registration failure as the Relay status that decided it.
+*
+* The gateway reports a permanent refusal exactly as `relayRefusal` composes it, and every other
+* failure it reports — a status it did not refuse with, a dropped socket, a timeout — is worth
+* another attempt. A Host reading the message can therefore tell the owner to act on this address
+* instead of promising a retry that reaches the same answer, and can say which status decided it.
+* @param message - Failure the gateway reported for one registration.
+* @returns The refusing status, or undefined when the failure is worth retrying.
+*/
+function relayRefusalStatus(message) {
+	const match = RELAY_REFUSAL_MESSAGE.exec(message);
+	if (match === null) return void 0;
+	const status = Number(match[1]);
+	return RELAY_REFUSAL_STATUSES.includes(status) ? status : void 0;
+}
+//#endregion
+//#region lib/types/owner-gateway/retry-backoff.js
+/**
+* Delay schedule for one connection that keeps failing.
+*
+* The owner host's worker supervisor and the gateway's per-share Relay socket both reconnect rather
+* than give up, and both treat a connection that stayed up long enough as healthy, so the failure
+* after one starts the delays over instead of continuing the previous run's growth. Extracted from
+* the socket lifecycle so the schedule is deterministic and testable apart from spawning processes.
+*/
+/** Schedule of a connection that has not (yet) proven itself stable. */
+const INITIAL_RETRY_BACKOFF = {
+	delayMs: 500,
+	attempt: 0
+};
+/** Ceiling for the doubling delay: a failing peer is retried, never hammered. */
+const RETRY_BACKOFF_MAX_MS = 1e4;
+/**
+* A connection that stays up this long is healthy, so the next failure starts the delays over.
+* A peer that replaces the connection right after the handshake keeps the previous backoff instead
+* of retrying every 500 ms.
+*/
+const RETRY_STABLE_MS = 3e4;
+/**
+* Advance the schedule after one failed attempt.
+* @param state Backoff of the attempt that just failed.
+* @returns Schedule the retry starts from: the delay to wait and the state after that attempt.
+*/
+function retryBackoffNext(state) {
+	return {
+		delayMs: Math.min(state.delayMs * 2, RETRY_BACKOFF_MAX_MS),
+		attempt: state.attempt + 1
+	};
+}
+/**
+* Schedule for a connection that has proven itself stable.
+* @returns The schedule's first entry, so the next failure is retried promptly.
+*/
+function retryBackoffSettled() {
+	return INITIAL_RETRY_BACKOFF;
+}
+//#endregion
+export { relayRefusal as a, relayEndpoint as c, retryBackoffSettled as i, RETRY_STABLE_MS as n, relayRefusalStatus as o, retryBackoffNext as r, normalizeRelayUrl as s, INITIAL_RETRY_BACKOFF as t };

package/lib/typert.host.d.ts

@@ -0,0 +1,3 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
+
+export declare const TYPERT: unknown