@olimsaidov/icdp 0.1.0

package/dist/relay/core.mjs

@@ -0,0 +1,411 @@
+import { CDP_METHOD_NOT_FOUND, CDP_SERVER_ERROR, parseJson } from "../protocol.mjs";
+//#region src/relay/core.ts
+/** Sentinel: the method was handled and a response was already sent. */
+const RESPONDED = Symbol("responded");
+var RelayCore = class {
+	product;
+	browserWsUrl;
+	hostSocket = null;
+	clients = /* @__PURE__ */ new Map();
+	sessions = /* @__PURE__ */ new Map();
+	targets = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	nextBridgeId = 1;
+	nextSessionId = 1;
+	constructor(options = {}) {
+		this.product = options.product ?? "icdp/0.1";
+		this.browserWsUrl = options.browserWsUrl ?? "";
+	}
+	/** A Host bridge connected. New-wins: any previous Host is dropped. */
+	hostConnected(socket) {
+		if (this.hostSocket && this.hostSocket !== socket) {
+			const previous = this.hostSocket;
+			this.hostSocket = null;
+			this.dropAllTargets("Host replaced by a newer connection");
+			try {
+				previous.close(1008, "replaced by a newer host");
+			} catch {}
+		}
+		this.hostSocket = socket;
+	}
+	hostDisconnected(socket) {
+		if (this.hostSocket !== socket) return;
+		this.hostSocket = null;
+		this.dropAllTargets("Host disconnected");
+	}
+	hostMessage(socket, raw) {
+		if (this.hostSocket !== socket) return;
+		const message = parseJson(raw);
+		if (!message) return;
+		switch (message.kind) {
+			case "ready":
+				this.dropAllTargets("Host re-announced");
+				for (const target of message.targets) this.addTarget(target);
+				return;
+			case "targetCreated":
+				this.addTarget(message.target);
+				return;
+			case "targetDestroyed":
+				this.removeTarget(message.targetId, "Target destroyed");
+				return;
+			case "targetInfoChanged":
+				this.targets.set(message.target.targetId, message.target);
+				this.broadcastTargetEvent("Target.targetInfoChanged", { targetInfo: this.targetInfo(message.target) });
+				return;
+			case "response": {
+				const id = Number(message.id);
+				const call = this.pending.get(id);
+				if (!call) return;
+				this.pending.delete(id);
+				this.sendToClient(call.client, {
+					id: call.clientId,
+					sessionId: call.sessionId,
+					...message.error ? { error: message.error } : { result: message.result ?? {} }
+				});
+				return;
+			}
+			case "event":
+				for (const session of this.sessions.values()) {
+					if (session.targetId !== message.targetId) continue;
+					this.sendToClient(session.client, {
+						method: message.method,
+						params: message.params,
+						sessionId: session.sessionId
+					});
+				}
+				return;
+		}
+	}
+	clientConnected(socket) {
+		this.clients.set(socket, {
+			socket,
+			autoAttach: false,
+			discoverTargets: false,
+			sessions: /* @__PURE__ */ new Set()
+		});
+	}
+	clientDisconnected(socket) {
+		const client = this.clients.get(socket);
+		if (!client) return;
+		this.clients.delete(socket);
+		for (const sessionId of client.sessions) this.endSession(sessionId, { notifyClient: false });
+	}
+	clientMessage(socket, raw) {
+		const client = this.clients.get(socket);
+		if (!client) return;
+		const message = parseJson(raw);
+		if (!message) return;
+		if (message.sessionId) {
+			this.routeSessionCommand(client, message);
+			return;
+		}
+		const local = this.browserLevelResult(client, message);
+		if (local === RESPONDED) return;
+		if (local !== void 0) {
+			this.sendToClient(client, {
+				id: message.id,
+				result: local
+			});
+			return;
+		}
+		this.sendToClient(client, {
+			id: message.id,
+			error: {
+				code: CDP_METHOD_NOT_FOUND,
+				message: `Method not available on the browser target: ${message.method ?? "<missing>"}. Attach to a target and send it with a sessionId.`
+			}
+		});
+	}
+	jsonVersion() {
+		return {
+			Browser: this.product,
+			"Protocol-Version": "1.3",
+			"User-Agent": this.product,
+			"V8-Version": "synthetic",
+			"WebKit-Version": "synthetic",
+			webSocketDebuggerUrl: this.browserWsUrl
+		};
+	}
+	jsonList() {
+		return Array.from(this.targets.values(), (target) => ({
+			description: "icdp iframe target",
+			devtoolsFrontendUrl: "",
+			id: target.targetId,
+			title: target.title,
+			type: "page",
+			url: target.url,
+			webSocketDebuggerUrl: this.browserWsUrl
+		}));
+	}
+	status() {
+		return {
+			hostConnected: this.hostSocket !== null,
+			targets: Array.from(this.targets.values()),
+			clients: this.clients.size
+		};
+	}
+	targetInfo(target) {
+		return {
+			targetId: target.targetId,
+			type: "page",
+			title: target.title,
+			url: target.url,
+			attached: Array.from(this.sessions.values()).some((session) => session.targetId === target.targetId),
+			canAccessOpener: false
+		};
+	}
+	sendToClient(client, message) {
+		try {
+			client.socket.send(JSON.stringify(message));
+		} catch {}
+	}
+	sendToHost(message) {
+		try {
+			this.hostSocket?.send(JSON.stringify(message));
+		} catch {}
+	}
+	broadcastTargetEvent(method, params) {
+		for (const client of this.clients.values()) {
+			if (!client.discoverTargets) continue;
+			this.sendToClient(client, {
+				method,
+				params
+			});
+		}
+	}
+	addTarget(target) {
+		this.targets.set(target.targetId, target);
+		this.broadcastTargetEvent("Target.targetCreated", { targetInfo: this.targetInfo(target) });
+		for (const client of this.clients.values()) if (client.autoAttach) this.startSession(client, target.targetId);
+	}
+	removeTarget(targetId, reason) {
+		if (!this.targets.delete(targetId)) return;
+		for (const session of Array.from(this.sessions.values())) if (session.targetId === targetId) this.endSession(session.sessionId, {
+			notifyClient: true,
+			failReason: reason
+		});
+		this.broadcastTargetEvent("Target.targetDestroyed", { targetId });
+	}
+	dropAllTargets(reason) {
+		for (const targetId of Array.from(this.targets.keys())) this.removeTarget(targetId, reason);
+	}
+	startSession(client, targetId) {
+		const session = {
+			sessionId: `icdp-session-${this.nextSessionId++}`,
+			targetId,
+			client
+		};
+		this.sessions.set(session.sessionId, session);
+		client.sessions.add(session.sessionId);
+		const target = this.targets.get(targetId);
+		if (target) this.sendToClient(client, {
+			method: "Target.attachedToTarget",
+			params: {
+				sessionId: session.sessionId,
+				targetInfo: this.targetInfo(target),
+				waitingForDebugger: false
+			}
+		});
+		return session;
+	}
+	endSession(sessionId, options) {
+		const session = this.sessions.get(sessionId);
+		if (!session) return;
+		this.sessions.delete(sessionId);
+		session.client.sessions.delete(sessionId);
+		for (const [bridgeId, call] of this.pending) {
+			if (call.sessionId !== sessionId) continue;
+			this.pending.delete(bridgeId);
+			if (options.notifyClient) this.sendToClient(session.client, {
+				id: call.clientId,
+				sessionId,
+				error: {
+					code: CDP_SERVER_ERROR,
+					message: options.failReason ?? "Session detached"
+				}
+			});
+		}
+		if (options.notifyClient) this.sendToClient(session.client, {
+			method: "Target.detachedFromTarget",
+			params: {
+				sessionId,
+				targetId: session.targetId
+			}
+		});
+		this.sendToHost({
+			kind: "detached",
+			sessionId,
+			targetId: session.targetId
+		});
+	}
+	routeSessionCommand(client, message) {
+		const sessionId = message.sessionId;
+		const session = this.sessions.get(sessionId);
+		if (!session || session.client !== client) {
+			this.sendToClient(client, {
+				id: message.id,
+				sessionId,
+				error: {
+					code: CDP_SERVER_ERROR,
+					message: `Session not found: ${sessionId}`
+				}
+			});
+			return;
+		}
+		if (!message.method) {
+			this.sendToClient(client, {
+				id: message.id,
+				sessionId,
+				error: {
+					code: CDP_METHOD_NOT_FOUND,
+					message: "Method not found: <missing>"
+				}
+			});
+			return;
+		}
+		const local = this.sessionLevelResult(session, message);
+		if (local !== void 0) {
+			this.sendToClient(client, {
+				id: message.id,
+				sessionId,
+				result: local
+			});
+			return;
+		}
+		if (!this.hostSocket) {
+			this.sendToClient(client, {
+				id: message.id,
+				sessionId,
+				error: {
+					code: CDP_SERVER_ERROR,
+					message: "Host is not connected"
+				}
+			});
+			return;
+		}
+		const bridgeId = this.nextBridgeId++;
+		this.pending.set(bridgeId, {
+			client,
+			clientId: message.id,
+			sessionId
+		});
+		this.sendToHost({
+			kind: "command",
+			sessionId,
+			targetId: session.targetId,
+			id: bridgeId,
+			method: message.method,
+			params: message.params ?? {}
+		});
+	}
+	/** Session-scoped methods the Relay answers itself; undefined = forward to the frame. */
+	sessionLevelResult(session, message) {
+		switch (message.method) {
+			case "Browser.getVersion": return {
+				protocolVersion: "1.3",
+				product: this.product,
+				revision: `icdp-v1`,
+				userAgent: this.product,
+				jsVersion: "synthetic"
+			};
+			case "Schema.getDomains": return { domains: [] };
+			case "Target.setAutoAttach":
+			case "Target.setDiscoverTargets":
+			case "Target.setRemoteLocations":
+			case "Target.activateTarget": return {};
+			case "Target.getTargetInfo": {
+				const target = this.targets.get(session.targetId);
+				if (!target) return { targetInfo: {
+					targetId: session.targetId,
+					type: "page",
+					title: "",
+					url: "",
+					attached: true
+				} };
+				return { targetInfo: this.targetInfo(target) };
+			}
+			default: return;
+		}
+	}
+	/** Browser-level methods the Relay answers itself; undefined = not local. */
+	browserLevelResult(client, message) {
+		switch (message.method) {
+			case "Browser.getVersion": return {
+				protocolVersion: "1.3",
+				product: this.product,
+				revision: `icdp-v1`,
+				userAgent: this.product,
+				jsVersion: "synthetic"
+			};
+			case "Browser.close":
+			case "Browser.setDownloadBehavior":
+			case "Browser.setWindowBounds":
+			case "Security.setIgnoreCertificateErrors":
+			case "Target.setRemoteLocations":
+			case "Target.activateTarget":
+			case "Target.closeTarget": return {};
+			case "Schema.getDomains": return { domains: [] };
+			case "Target.getTargets": return { targetInfos: Array.from(this.targets.values(), (target) => this.targetInfo(target)) };
+			case "Target.getTargetInfo": {
+				const targetId = String(message.params?.targetId ?? "");
+				const target = this.targets.get(targetId);
+				if (!target) return { targetInfo: {
+					targetId,
+					type: "page",
+					title: "",
+					url: "",
+					attached: false
+				} };
+				return { targetInfo: this.targetInfo(target) };
+			}
+			case "Target.setDiscoverTargets": {
+				const discover = Boolean(message.params?.discover);
+				client.discoverTargets = discover;
+				if (discover) for (const target of this.targets.values()) this.sendToClient(client, {
+					method: "Target.targetCreated",
+					params: { targetInfo: this.targetInfo(target) }
+				});
+				return {};
+			}
+			case "Target.setAutoAttach": {
+				const autoAttach = Boolean(message.params?.autoAttach);
+				client.autoAttach = autoAttach;
+				if (autoAttach) {
+					for (const target of this.targets.values()) if (!Array.from(client.sessions).some((sessionId) => this.sessions.get(sessionId)?.targetId === target.targetId)) this.startSession(client, target.targetId);
+				}
+				return {};
+			}
+			case "Target.attachToTarget": {
+				const targetId = String(message.params?.targetId ?? "");
+				if (!this.targets.has(targetId)) {
+					this.sendToClient(client, {
+						id: message.id,
+						error: {
+							code: CDP_SERVER_ERROR,
+							message: `No target with given id found: ${targetId}`
+						}
+					});
+					return RESPONDED;
+				}
+				return { sessionId: this.startSession(client, targetId).sessionId };
+			}
+			case "Target.detachFromTarget": {
+				const sessionId = String(message.params?.sessionId ?? "");
+				this.endSession(sessionId, { notifyClient: false });
+				return {};
+			}
+			case "Target.createTarget":
+				this.sendToClient(client, {
+					id: message.id,
+					error: {
+						code: CDP_SERVER_ERROR,
+						message: "Target.createTarget is not supported: icdp targets are iframes paired by the Host."
+					}
+				});
+				return RESPONDED;
+			default: return;
+		}
+	}
+};
+//#endregion
+export { RelayCore };

package/dist/relay/node.d.mts

@@ -0,0 +1,24 @@
+import { RelayCore } from "./core.mjs";
+import { IncomingMessage, Server, ServerResponse } from "node:http";
+
+//#region src/relay/node.d.ts
+type ServeRelayOptions = {
+  port?: number;
+  hostname?: string;
+  product?: string; /** Path Clients connect to. Advertised by /json/version. */
+  browserPath?: string; /** Path the Host bridge connects to. */
+  hostPath?: string; /** Handles requests the relay doesn't own (anything but its WS + /json + /icdp paths). */
+  fallback?: (request: IncomingMessage, response: ServerResponse) => void;
+};
+type RelayServer = {
+  core: RelayCore;
+  server: Server;
+  port: number;
+  browserWsUrl: string;
+  hostWsUrl: string;
+  stop(): Promise<void>;
+};
+/** Serve a Relay on Node. One Host, many Clients, flat-session protocol only. */
+declare function serveRelay(options?: ServeRelayOptions): Promise<RelayServer>;
+//#endregion
+export { RelayServer, ServeRelayOptions, serveRelay };

package/dist/relay/node.mjs

@@ -0,0 +1,99 @@
+import { RelayCore } from "./core.mjs";
+import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
+//#region src/relay/node.ts
+function asSocketLike(ws) {
+	return {
+		send: (data) => {
+			try {
+				ws.send(data);
+			} catch {}
+		},
+		close: (code, reason) => {
+			try {
+				ws.close(code, reason);
+			} catch {}
+		}
+	};
+}
+function sendJson(response, payload) {
+	response.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+	response.end(JSON.stringify(payload));
+}
+/** Serve a Relay on Node. One Host, many Clients, flat-session protocol only. */
+async function serveRelay(options = {}) {
+	const hostname = options.hostname ?? "127.0.0.1";
+	const browserPath = options.browserPath ?? "/devtools/browser";
+	const hostPath = options.hostPath ?? "/icdp/host";
+	const server = createServer((request, response) => {
+		const url = new URL(request.url ?? "/", `http://${hostname}`);
+		if (process.env.ICDP_DEBUG === "1") console.log(`[icdp:http] ${request.method} ${url.pathname}`);
+		if (url.pathname === "/json/version") return sendJson(response, core.jsonVersion());
+		if (url.pathname === "/json" || url.pathname === "/json/list") return sendJson(response, core.jsonList());
+		if (url.pathname === "/icdp/status") return sendJson(response, core.status());
+		if (options.fallback) return options.fallback(request, response);
+		response.writeHead(404);
+		response.end("not found");
+	});
+	const wss = new WebSocketServer({ noServer: true });
+	const socketLikes = /* @__PURE__ */ new WeakMap();
+	const wrap = (ws) => {
+		let like = socketLikes.get(ws);
+		if (!like) {
+			like = asSocketLike(ws);
+			socketLikes.set(ws, like);
+		}
+		return like;
+	};
+	server.on("upgrade", (request, socket, head) => {
+		const url = new URL(request.url ?? "/", `http://${hostname}`);
+		const kind = url.pathname === browserPath ? "client" : url.pathname === hostPath ? "host" : null;
+		if (process.env.ICDP_DEBUG === "1") console.log(`[icdp:http] UPGRADE ${url.pathname} -> ${kind ?? "reject"}`);
+		if (!kind) {
+			socket.destroy();
+			return;
+		}
+		wss.handleUpgrade(request, socket, head, (ws) => {
+			if (kind === "host") core.hostConnected(wrap(ws));
+			else core.clientConnected(wrap(ws));
+			ws.on("message", (data) => {
+				const raw = data.toString();
+				if (process.env.ICDP_DEBUG === "1") console.log(`[icdp:${kind}]`, raw.slice(0, 400));
+				if (kind === "host") core.hostMessage(wrap(ws), raw);
+				else core.clientMessage(wrap(ws), raw);
+			});
+			ws.on("close", () => {
+				if (kind === "host") core.hostDisconnected(wrap(ws));
+				else core.clientDisconnected(wrap(ws));
+			});
+			ws.on("error", () => ws.close());
+		});
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(options.port ?? 0, hostname, resolve);
+	});
+	const address = server.address();
+	if (address === null || typeof address === "string") throw new Error("relay server has no TCP address");
+	const port = address.port;
+	const browserWsUrl = `ws://${hostname}:${port}${browserPath}`;
+	const core = new RelayCore({
+		product: options.product,
+		browserWsUrl
+	});
+	return {
+		core,
+		server,
+		port,
+		browserWsUrl,
+		hostWsUrl: `ws://${hostname}:${port}${hostPath}`,
+		stop: () => new Promise((resolve) => {
+			for (const ws of wss.clients) ws.terminate();
+			wss.close();
+			server.closeAllConnections();
+			server.close(() => resolve());
+		})
+	};
+}
+//#endregion
+export { serveRelay };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@olimsaidov/icdp",
+  "version": "0.1.0",
+  "description": "Chrome DevTools Protocol over an iframe boundary: drive and inspect embedded (including cross-origin) apps with CDP tools, without a real browser debugging session.",
+  "homepage": "https://github.com/olimsaidov/icdp#readme",
+  "bugs": "https://github.com/olimsaidov/icdp/issues",
+  "license": "MIT",
+  "author": "Olim Saidov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/olimsaidov/icdp.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./frame": {
+      "types": "./dist/frame/index.d.mts",
+      "default": "./dist/frame/index.mjs"
+    },
+    "./host": {
+      "types": "./dist/host/index.d.mts",
+      "default": "./dist/host/index.mjs"
+    },
+    "./relay": {
+      "types": "./dist/relay/core.d.mts",
+      "default": "./dist/relay/core.mjs"
+    },
+    "./relay/node": {
+      "types": "./dist/relay/node.d.mts",
+      "default": "./dist/relay/node.mjs"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.mts",
+      "default": "./dist/protocol.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc --noEmit && oxlint && oxfmt --check .",
+    "fmt": "oxfmt .",
+    "gen:conformance": "node scripts/gen-conformance.ts",
+    "playground": "node playground/server.ts",
+    "test": "vitest run --exclude '**/*.e2e.test.ts'",
+    "test:e2e": "vitest run tests/agent-browser.e2e.test.ts",
+    "test:all": "vitest run"
+  },
+  "dependencies": {
+    "aria-query": "^5.3.2",
+    "chobitsu": "1.8.6",
+    "devtools-protocol": "^0.0.1624250",
+    "dom-accessibility-api": "^0.7.1",
+    "ws": "^8.21.0"
+  },
+  "devDependencies": {
+    "@types/aria-query": "^5.0.4",
+    "@types/node": "^24",
+    "@types/ws": "^8",
+    "jsdom": "^29.1.1",
+    "oxfmt": "^0.54.0",
+    "oxlint": "^1.69.0",
+    "rolldown": "^1.1.1",
+    "tsdown": "^0.22.2",
+    "typescript": "^5",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}