@statelyai/sdk 0.14.2 → 0.16.0

package/dist/relay.mjs

@@ -1,6 +1,29 @@
 import { INSPECTION_PROTOCOL_VERSION, PREFIX } from "./protocol.mjs";
 
 //#region src/relay.ts
+const REPLAYABLE_MESSAGE_TYPES = new Set([
+	"@statelyai.init",
+	"@statelyai.inspectSnapshot",
+	"@statelyai.system.init",
+	"@statelyai.system.actorRegistered",
+	"@statelyai.system.actorEvent",
+	"@statelyai.system.actorSnapshot",
+	"@statelyai.system.actorStopped"
+]);
+const FORWARD_ONLY_MESSAGE_TYPES = new Set([
+	"@statelyai.system.selectActor",
+	"@statelyai.retrieve",
+	"@statelyai.retrieved",
+	"@statelyai.error",
+	"@statelyai.ready",
+	"@statelyai.loaded",
+	"@statelyai.capabilityDenied",
+	"@statelyai.register",
+	"@statelyai.registered"
+]);
+function isSupportedMessageType(type) {
+	return REPLAYABLE_MESSAGE_TYPES.has(type) || FORWARD_ONLY_MESSAGE_TYPES.has(type);
+}
 function parseMessage(raw) {
 	if (raw instanceof ArrayBuffer) raw = new TextDecoder().decode(raw);
 	if (typeof raw === "string") try {
@@ -12,6 +35,22 @@ function parseMessage(raw) {
 	const message = raw;
 	return typeof message.type === "string" && message.type.startsWith(PREFIX) ? message : null;
 }
+function validationError(message) {
+	if (!isSupportedMessageType(message.type)) return `Unsupported inspection message type ${String(message.type)}`;
+	const hasString = (key) => typeof message[key] === "string" && message[key] !== "";
+	switch (message.type) {
+		case "@statelyai.system.init": return message.protocolVersion === INSPECTION_PROTOCOL_VERSION && Array.isArray(message.actors) ? null : "system.init requires the current protocolVersion and actors array";
+		case "@statelyai.system.selectActor":
+		case "@statelyai.system.actorStopped": return hasString("sessionId") ? null : `${message.type} requires sessionId`;
+		case "@statelyai.system.actorRegistered": return hasString("sessionId") && hasString("actorId") ? null : "actorRegistered requires sessionId and actorId";
+		case "@statelyai.system.actorEvent": return hasString("sessionId") && "event" in message ? null : "actorEvent requires sessionId and event";
+		case "@statelyai.system.actorSnapshot": return hasString("sessionId") && "snapshot" in message ? null : "actorSnapshot requires sessionId and snapshot";
+		case "@statelyai.retrieve":
+		case "@statelyai.retrieved": return hasString("requestId") ? null : `${message.type} requires requestId`;
+		case "@statelyai.error": return hasString("code") && hasString("message") ? null : "error requires code and message";
+		default: return null;
+	}
+}
 function errorMessage(code, message) {
 	return {
 		type: "@statelyai.error",
@@ -30,10 +69,10 @@ function compactReplay(replay, message, max) {
 		const index = replay.findIndex((entry) => entry.type === "@statelyai.init");
 		if (index >= 0) replay.splice(index, 1);
 	} else if (type === "@statelyai.system.actorSnapshot" || type === "@statelyai.inspectSnapshot") {
-		const actorId = record.actorId;
+		const sessionId = record.sessionId;
 		const index = replay.findIndex((entry) => {
 			const candidate = entry;
-			return candidate.type === type && candidate.actorId === actorId;
+			return candidate.type === type && candidate.sessionId === sessionId;
 		});
 		if (index >= 0) replay.splice(index, 1);
 	}
@@ -41,110 +80,92 @@ function compactReplay(replay, message, max) {
 	if (replay.length > max) replay.splice(0, replay.length - max);
 }
 /**
-* Runtime-neutral WebSocket inspection room.
+* Runtime-neutral implementation of one inspection room.
 *
-* It owns protocol registration, routing, multiplexed session membership, and
-* bounded late-join replay. Node and Durable Object adapters only translate
-* `send` effects to their native WebSocket APIs and persist `snapshot()`.
+* The hosting adapter selects the room from the WebSocket URL. This module
+* owns protocol registration, multi-producer/viewer routing, and bounded
+* per-producer replay.
 */
 function createInspectionRelay(options = {}) {
 	const maxReplayMessages = options.maxReplayMessages ?? 200;
-	const maxReplaySessions = Math.max(1, options.maxReplaySessions ?? 100);
+	const maxReplayProducers = Math.max(1, options.maxReplayProducers ?? 100);
 	const peers = /* @__PURE__ */ new Map();
-	const sessions = new Map(Object.entries(options.snapshot?.sessions ?? {}).slice(-maxReplaySessions).map(([id, replay]) => [id, [...replay]]));
+	const producers = new Map(Object.entries(options.snapshot?.producers ?? {}).slice(-maxReplayProducers).map(([id, replay]) => [id, [...replay]]));
 	const send = (peerId, message) => ({
 		type: "send",
 		peerId,
 		message
 	});
-	function replayTo(peerId, sessionId) {
-		return (sessions.get(sessionId) ?? []).map((message) => send(peerId, message));
-	}
-	function oppositePeers(sender, sessionId) {
-		return Array.from(peers.values()).filter((peer) => peer.id !== sender.id && peer.role !== sender.role && peer.sessionIds.includes(sessionId));
-	}
-	function retainReplay(sessionId, replay) {
-		sessions.delete(sessionId);
-		sessions.set(sessionId, replay);
-		while (sessions.size > maxReplaySessions) {
-			const oldestSessionId = sessions.keys().next().value;
-			if (oldestSessionId === void 0) break;
-			sessions.delete(oldestSessionId);
+	function retainReplay(producerId, replay) {
+		producers.delete(producerId);
+		producers.set(producerId, replay);
+		while (producers.size > maxReplayProducers) {
+			const oldestProducerId = producers.keys().next().value;
+			if (oldestProducerId === void 0) break;
+			producers.delete(oldestProducerId);
 		}
 	}
 	return {
 		connect(peer) {
-			peers.set(peer.id, {
-				...peer,
-				sessionIds: Array.from(new Set([peer.primarySessionId, ...peer.sessionIds]))
-			});
+			peers.set(peer.id, { ...peer });
 		},
 		disconnect(peerId) {
 			peers.delete(peerId);
 		},
 		clear() {
 			peers.clear();
-			sessions.clear();
+			producers.clear();
 		},
 		peer(peerId) {
 			const peer = peers.get(peerId);
-			return peer ? {
-				...peer,
-				sessionIds: [...peer.sessionIds]
-			} : void 0;
+			return peer ? { ...peer } : void 0;
 		},
 		receive(peerId, raw) {
 			const message = parseMessage(raw);
-			if (!message) return [];
+			if (!message) return [send(peerId, errorMessage("invalid_message", "Expected a JSON protocol message"))];
+			const invalid = validationError(message);
+			if (invalid) return [send(peerId, errorMessage("invalid_message", invalid))];
 			if (message.type === "@statelyai.register") {
 				const role = message.role;
-				const sessionId = message.sessionId;
 				const protocolVersion = message.protocolVersion;
-				if (role !== "client" && role !== "viz" || typeof sessionId !== "string" || sessionId.length === 0) return [send(peerId, errorMessage("invalid_registration", "Invalid relay registration"))];
-				if (typeof protocolVersion === "number" && protocolVersion > INSPECTION_PROTOCOL_VERSION) return [send(peerId, errorMessage("unsupported_protocol", `Protocol ${protocolVersion} is not supported`))];
+				const producerId = message.producerId;
+				if (role !== "producer" && role !== "viewer" || role === "producer" && (typeof producerId !== "string" || producerId.length === 0)) return [send(peerId, errorMessage("invalid_registration", "Invalid relay registration"))];
+				if (protocolVersion !== INSPECTION_PROTOCOL_VERSION) return [send(peerId, errorMessage("unsupported_protocol", `Protocol ${String(protocolVersion)} is not supported; expected ${INSPECTION_PROTOCOL_VERSION}`))];
 				const peer = {
 					id: peerId,
 					role,
-					primarySessionId: sessionId,
-					sessionIds: [sessionId]
+					...role === "producer" && { producerId }
 				};
 				peers.set(peerId, peer);
 				const effects = [send(peerId, {
 					type: "@statelyai.registered",
 					protocolVersion: INSPECTION_PROTOCOL_VERSION,
-					sessionId
+					...peer.producerId && { producerId: peer.producerId }
 				})];
-				if (role === "viz") effects.push(...replayTo(peerId, sessionId));
+				if (role === "viewer") for (const replay of producers.values()) effects.push(...replay.map((entry) => send(peerId, entry)));
 				return effects;
 			}
 			const sender = peers.get(peerId);
 			if (!sender) return [send(peerId, errorMessage("not_registered", "Register before sending messages"))];
-			if (message.type === "@statelyai.addSession") {
-				const sessionId = message.sessionId;
-				if (typeof sessionId !== "string" || sessionId.length === 0) return [send(peerId, errorMessage("invalid_session", "Invalid session id"))];
-				if (!sender.sessionIds.includes(sessionId)) sender.sessionIds.push(sessionId);
-				const effects = [send(peerId, {
-					type: "@statelyai.sessionAdded",
-					sessionId
-				})];
-				if (sender.role === "viz") effects.push(...replayTo(peerId, sessionId));
-				return effects;
-			}
-			const sessionId = (typeof message.sessionId === "string" ? message.sessionId : void 0) ?? sender.primarySessionId;
-			if (!sender.sessionIds.includes(sessionId)) return [send(peerId, errorMessage("unknown_session", "Peer is not registered for session"))];
-			const stamped = {
-				...message,
-				sessionId
-			};
-			if (sender.role === "client") {
-				const replay = sessions.get(sessionId) ?? [];
-				compactReplay(replay, stamped, maxReplayMessages);
-				retainReplay(sessionId, replay);
+			if (sender.role === "producer") {
+				const producerId = sender.producerId;
+				const stamped = {
+					...message,
+					producerId
+				};
+				if (REPLAYABLE_MESSAGE_TYPES.has(message.type)) {
+					const replay = producers.get(producerId) ?? [];
+					compactReplay(replay, stamped, maxReplayMessages);
+					retainReplay(producerId, replay);
+				}
+				return Array.from(peers.values()).filter((peer) => peer.role === "viewer").map((peer) => send(peer.id, stamped));
 			}
-			return oppositePeers(sender, sessionId).map((peer) => send(peer.id, stamped));
+			const targetProducerId = typeof message.producerId === "string" ? message.producerId : void 0;
+			return Array.from(peers.values()).filter((peer) => peer.role === "producer" && (!targetProducerId || peer.producerId === targetProducerId)).map((peer) => send(peer.id, message));
 		},
-		snapshot() {
-			return { sessions: Object.fromEntries(Array.from(sessions, ([sessionId, replay]) => [sessionId, [...replay]])) };
+		snapshot(producerId) {
+			const entries = producerId ? producers.has(producerId) ? [[producerId, producers.get(producerId)]] : [] : Array.from(producers.entries());
+			return { producers: Object.fromEntries(entries.map(([producerId, replay]) => [producerId, [...replay]])) };
 		}
 	};
 }