@orkestrel/browser 0.0.5 → 0.0.6

package/dist/src/server/index.cjs

@@ -1,17 +1,18 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _src_core = require("../core/index.cjs");
+let _orkestrel_contract = require("@orkestrel/contract");
 let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
+let node_os = require("node:os");
 let node_path = require("node:path");
 let node_child_process = require("node:child_process");
 let node_timers_promises = require("node:timers/promises");
-let _orkestrel_contract = require("@orkestrel/contract");
 let node_crypto = require("node:crypto");
 let node_http = require("node:http");
 let node_https = require("node:https");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 let _orkestrel_websocket = require("@orkestrel/websocket");
 let node_events = require("node:events");
-let node_fs_promises = require("node:fs/promises");
 //#region src/server/constants.ts
 /** Default CDP port probed for an existing browser and used for launches. */
 var BROWSER_DEFAULT_CDP_PORT = 9222;
@@ -27,6 +28,8 @@ var BROWSER_CDP_LIST_PATH = "/json/list";
 var BROWSER_LAUNCH_ARGS = Object.freeze(["--no-first-run", "--no-default-browser-check"]);
 /** Flag enabling headless mode on a launched browser process. */
 var BROWSER_HEADLESS_ARG = "--headless=new";
+/** Prefix for isolated browser profiles created beneath the operating-system temp directory. */
+var BROWSER_PROFILE_PREFIX = "orkestrel-browser-";
 /** Grace period after SIGTERM before a launched process is escalated to SIGKILL during teardown. */
 var BROWSER_KILL_GRACE_MS = 3e3;
 /** Bound for the `discover: false` port-occupancy probe before launching — short, since it only needs to detect an already-listening CDP endpoint, not perform full discovery. */
@@ -158,7 +161,7 @@ var BrowserDestroyedError = class extends _src_core.BrowserError {
 * @returns True when value is a BrowserConnectionError instance
 */
 function isBrowserConnectionError(value) {
-	return value instanceof BrowserConnectionError;
+	return (0, _orkestrel_contract.isInstance)(value, BrowserConnectionError);
 }
 /**
 * Narrow an unknown value to BrowserNotConnectedError.
@@ -167,7 +170,7 @@ function isBrowserConnectionError(value) {
 * @returns True when value is a BrowserNotConnectedError instance
 */
 function isBrowserNotConnectedError(value) {
-	return value instanceof BrowserNotConnectedError;
+	return (0, _orkestrel_contract.isInstance)(value, BrowserNotConnectedError);
 }
 /**
 * Narrow an unknown value to BrowserDestroyedError.
@@ -176,7 +179,7 @@ function isBrowserNotConnectedError(value) {
 * @returns True when value is a BrowserDestroyedError instance
 */
 function isBrowserDestroyedError(value) {
-	return value instanceof BrowserDestroyedError;
+	return (0, _orkestrel_contract.isInstance)(value, BrowserDestroyedError);
 }
 //#endregion
 //#region src/server/helpers.ts
@@ -264,6 +267,44 @@ function browserToEngine(browser) {
 	if (browser?.includes("Chrome/") === true) return "chrome";
 	return "chromium";
 }
+/**
+* Resolve a persistent caller profile or create an isolated temporary one.
+*
+* @param path - Optional caller-owned persistent user-data directory
+* @returns The resolved profile and whether the library owns its lifecycle
+*/
+async function createBrowserProfile(path) {
+	if (path !== void 0) return {
+		path,
+		temporary: false
+	};
+	return {
+		path: await (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.tmpdir)(), BROWSER_PROFILE_PREFIX)),
+		temporary: true
+	};
+}
+/**
+* Remove a library-owned isolated browser profile.
+*
+* @remarks
+* The path must remain a direct child of the operating-system temp directory
+* with {@link BROWSER_PROFILE_PREFIX}; this defensive check prevents a
+* malformed profile value from widening recursive deletion.
+*
+* @param profile - Resolved profile lifecycle result
+*/
+async function removeBrowserProfile(profile) {
+	if (!profile.temporary) return;
+	const path = (0, node_path.resolve)(profile.path);
+	const temporary = (0, node_path.resolve)((0, node_os.tmpdir)());
+	if ((0, node_path.dirname)(path) !== temporary || !(0, node_path.basename)(path).startsWith("orkestrel-browser-")) throw new Error("Refusing to remove an unsafe browser profile path");
+	await (0, node_fs_promises.rm)(path, {
+		recursive: true,
+		force: true,
+		maxRetries: 3,
+		retryDelay: 100
+	});
+}
 /** Check the env-override keys (`PLAYWRIGHT_EXECUTABLE_PATH`, `CHROME_PATH`) in order for an existing file. */
 function findEnvOverride(env) {
 	return findAllEnvOverrides(env)[0];
@@ -416,7 +457,7 @@ async function fetchCDPTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
 		const response = await fetch(url, { signal: controller.signal });
 		if (!response.ok) return [];
 		const list = await response.json();
-		if (!Array.isArray(list)) return [];
+		if (!(0, _orkestrel_contract.isArray)(list)) return [];
 		const targets = [];
 		for (const entry of list) {
 			if (!(0, _orkestrel_contract.isRecord)(entry)) continue;
@@ -480,12 +521,12 @@ var WebSocketCDPTransport = class {
 		}
 		this.#socket?.destroy();
 		this.#socket = void 0;
-		const attempt = this.#open();
-		this.#starting = attempt;
+		const transition = this.#open();
+		this.#starting = transition;
 		try {
-			await attempt;
+			await transition;
 		} finally {
-			if (this.#starting === attempt) this.#starting = void 0;
+			if (this.#starting === transition) this.#starting = void 0;
 		}
 	}
 	async send(data) {
@@ -499,16 +540,21 @@ var WebSocketCDPTransport = class {
 			await active;
 			return;
 		}
-		const attempt = this.#stop();
-		this.#closing = attempt;
+		const transition = this.#stop();
+		this.#closing = transition;
 		try {
-			await attempt;
+			await transition;
 		} finally {
-			if (this.#closing === attempt) this.#closing = void 0;
+			if (this.#closing === transition) this.#closing = void 0;
 		}
 	}
 	async #open() {
-		const url = new URL(this.#url);
+		const parsed = (0, _orkestrel_contract.attempt)(() => new URL(this.#url));
+		if (!parsed.success) throw new BrowserConnectionError(`WebSocket CDP URL is invalid: ${this.#url}`, {
+			url: this.#url,
+			error: parsed.error
+		});
+		const url = parsed.value;
 		if (url.protocol !== "ws:" && url.protocol !== "wss:") throw new BrowserConnectionError(`WebSocket CDP connection requires a ws: or wss: URL: ${this.#url}`, { url: this.#url });
 		const key = (0, node_crypto.randomBytes)(16).toString("base64");
 		const deferred = Promise.withResolvers();
@@ -670,6 +716,9 @@ function createScreenshotWriter() {
 }
 //#endregion
 //#region src/server/Browser.ts
+/**
+* Discovers, launches, connects to, and owns Chromium-family browser sessions.
+*/
 var Browser = class {
 	#emitter;
 	#options;
@@ -683,6 +732,7 @@ var Browser = class {
 	#endpoint;
 	#client;
 	#process;
+	#profile;
 	#contexts = [];
 	#destroyed = false;
 	#connecting;
@@ -780,6 +830,35 @@ var Browser = class {
 	contexts() {
 		return [...this.#contexts];
 	}
+	async isolate(options) {
+		if (this.#destroyed) throw new BrowserDestroyedError();
+		const client = this.#client;
+		if (this.#status !== "connected" || client === void 0) throw new BrowserNotConnectedError();
+		(0, _src_core.validateBrowserContextOptions)(options);
+		const params = { disposeOnDetach: false };
+		if (options?.proxy !== void 0) {
+			params["proxyServer"] = options.proxy.server;
+			if (options.proxy.bypass !== void 0) params["proxyBypassList"] = options.proxy.bypass.join(",");
+		}
+		if (options?.origins !== void 0) params["originsWithUniversalNetworkAccess"] = [...options.origins];
+		const result = await client.send("Target.createBrowserContext", params);
+		if (!(0, _orkestrel_contract.isRecord)(result) || !(0, _orkestrel_contract.isString)(result["browserContextId"])) throw new BrowserConnectionError("Failed to create isolated browser context");
+		const id = result["browserContextId"];
+		const context = new _src_core.BrowserContext(client, id, options?.emulation?.viewport ?? this.#options.viewport, createScreenshotWriter(), options?.emulation, options?.downloads);
+		try {
+			if (options?.downloads !== void 0) await client.send("Browser.setDownloadBehavior", {
+				behavior: options.downloads.named === true ? "allowAndName" : "allow",
+				browserContextId: id,
+				downloadPath: options.downloads.path,
+				eventsEnabled: true
+			});
+		} catch (error) {
+			await context.close().catch(() => void 0);
+			throw error;
+		}
+		this.#registerContext(context);
+		return context;
+	}
 	async create(options) {
 		if (this.#destroyed) throw new BrowserDestroyedError();
 		const client = this.#client;
@@ -787,7 +866,7 @@ var Browser = class {
 		let context = this.#contexts[0];
 		if (context === void 0) {
 			context = new _src_core.BrowserContext(client, void 0, this.#options.viewport, createScreenshotWriter());
-			this.#contexts.push(context);
+			this.#registerContext(context);
 		}
 		const page = await context.create(options);
 		this.#emitter.emit("page", page);
@@ -840,8 +919,8 @@ var Browser = class {
 			if (this.#destroyed) throw new BrowserDestroyedError();
 			this.#status = "error";
 			this.#emitter.emit("error", error);
-			if (error instanceof BrowserConnectionError) throw error;
-			throw new BrowserConnectionError(error instanceof Error ? error.message : String(error), { executable: this.#options.executable });
+			if (isBrowserConnectionError(error)) throw error;
+			throw new BrowserConnectionError((0, _orkestrel_contract.isError)(error) ? error.message : String(error), { executable: this.#options.executable });
 		}
 	}
 	async #detach() {
@@ -890,6 +969,7 @@ var Browser = class {
 		this.#unbindTransport();
 		this.#unbindProcess();
 		this.#process = void 0;
+		this.#releaseProfile().catch((error) => this.#emitter.emit("error", error));
 		this.#client = void 0;
 		this.#contexts = [];
 		this.#connection = void 0;
@@ -1064,8 +1144,16 @@ var Browser = class {
 		}
 		if (executable === void 0) throw new BrowserConnectionError("No Chromium browser found. Install Chrome, Edge, or Chromium.", requestedEngine === void 0 ? void 0 : { engine: requestedEngine });
 		this.#engine = resolvedEngine ?? "chromium";
-		const profile = this.#options.profile;
-		const process = launchBrowserProcess(executable, this.#cdpPort, this.#options.headless ?? true, profile, this.#options.args);
+		await this.#releaseProfile();
+		const profile = await createBrowserProfile(this.#options.profile);
+		this.#profile = profile;
+		let process;
+		try {
+			process = launchBrowserProcess(executable, this.#cdpPort, this.#options.headless ?? true, profile.path, this.#options.args);
+		} catch (error) {
+			await this.#releaseProfile();
+			throw error;
+		}
 		this.#process = process;
 		let client;
 		try {
@@ -1079,7 +1167,7 @@ var Browser = class {
 				timeout: this.#timeout()
 			});
 			await this.#raceAbort(client.connect());
-			const connection = profile === void 0 ? "launch" : "persistent";
+			const connection = this.#options.profile === void 0 ? "launch" : "persistent";
 			this.#client = client;
 			this.#endpoint = endpoint;
 			this.#connection = connection;
@@ -1095,6 +1183,7 @@ var Browser = class {
 			this.#unbindProcess();
 			await this.#closeClient(client);
 			await this.#terminate(process);
+			await this.#releaseProfile();
 			this.#process = void 0;
 			this.#client = void 0;
 			this.#endpoint = void 0;
@@ -1111,16 +1200,16 @@ var Browser = class {
 		const signal = AbortSignal.any([controller.signal, this.#signal()]);
 		const ready = waitForCDPReady(this.#cdpPort, this.#timeout(), this.#cdpHost, signal);
 		const exited = (0, node_events.once)(process, "exit", { signal }).then((values) => {
-			const code = typeof values[0] === "number" ? values[0] : null;
-			const exitSignal = typeof values[1] === "string" ? values[1] : null;
+			const code = (0, _orkestrel_contract.isInteger)(values[0]) ? values[0] : null;
+			const exitSignal = (0, _orkestrel_contract.isString)(values[1]) ? values[1] : null;
 			throw new BrowserConnectionError(this.#formatLaunchExit(code, exitSignal), context);
 		});
 		try {
 			return await Promise.race([ready, exited]);
 		} catch (error) {
-			if (error instanceof BrowserConnectionError) throw error;
+			if (isBrowserConnectionError(error)) throw error;
 			if (this.#signal().aborted) throw new BrowserConnectionError("Connection aborted", context);
-			throw new BrowserConnectionError(error instanceof Error ? error.message : String(error), context);
+			throw new BrowserConnectionError((0, _orkestrel_contract.isError)(error) ? error.message : String(error), context);
 		} finally {
 			controller.abort();
 			ready.catch(() => void 0);
@@ -1145,7 +1234,7 @@ var Browser = class {
 		} catch {
 			return;
 		}
-		if (!(0, _orkestrel_contract.isRecord)(result) || !Array.isArray(result["targetInfos"])) return;
+		if (!(0, _orkestrel_contract.isRecord)(result) || !(0, _orkestrel_contract.isArray)(result["targetInfos"])) return;
 		const pages = [];
 		for (const target of result["targetInfos"]) {
 			if (!(0, _orkestrel_contract.isRecord)(target) || !(0, _orkestrel_contract.isString)(target["targetId"]) || target["type"] !== "page" || !(0, _orkestrel_contract.isString)(target["title"]) || !(0, _orkestrel_contract.isString)(target["url"])) continue;
@@ -1159,7 +1248,7 @@ var Browser = class {
 		if (pages.length === 0 || this.#contexts.length > 0) return;
 		const context = new _src_core.BrowserContext(client, void 0, this.#options.viewport, createScreenshotWriter());
 		await context.sync(pages);
-		this.#contexts.push(context);
+		this.#registerContext(context);
 	}
 	async #destroyResources() {
 		try {
@@ -1177,7 +1266,11 @@ var Browser = class {
 			await this.#closeClient(client);
 			this.#client = void 0;
 		} finally {
-			this.#finish();
+			try {
+				await this.#releaseProfile();
+			} finally {
+				this.#finish();
+			}
 		}
 	}
 	async #closeResources() {
@@ -1197,7 +1290,11 @@ var Browser = class {
 			await this.#closeClient(client);
 			this.#client = void 0;
 		} finally {
-			this.#finish();
+			try {
+				await this.#releaseProfile();
+			} finally {
+				this.#finish();
+			}
 		}
 	}
 	async #settle() {
@@ -1229,12 +1326,20 @@ var Browser = class {
 		if (temporary) await this.#closeClient(remote);
 	}
 	async #closeContexts() {
-		for (const context of this.#contexts) try {
+		for (const context of [...this.#contexts]) try {
 			await context.close();
 		} catch {}
 	}
 	async #destroyContexts() {
-		await this.#destroyContextList(this.#contexts);
+		await this.#destroyContextList([...this.#contexts]);
+	}
+	#registerContext(context) {
+		this.#contexts.push(context);
+		context.emitter.on("close", () => {
+			const index = this.#contexts.indexOf(context);
+			if (index >= 0) this.#contexts.splice(index, 1);
+		});
+		this.#emitter.emit("context", context);
 	}
 	async #destroyContextList(contexts) {
 		for (const context of contexts) try {
@@ -1247,6 +1352,11 @@ var Browser = class {
 			await client.close();
 		} catch {}
 	}
+	async #releaseProfile() {
+		const profile = this.#profile;
+		this.#profile = void 0;
+		if (profile !== void 0) await removeBrowserProfile(profile);
+	}
 	async #waitForProcess(process) {
 		if (process.exitCode !== null || process.signalCode !== null) return;
 		await (0, node_events.once)(process, "exit");
@@ -1306,6 +1416,7 @@ exports.BROWSER_KILL_GRACE_MS = BROWSER_KILL_GRACE_MS;
 exports.BROWSER_LAUNCH_ARGS = BROWSER_LAUNCH_ARGS;
 exports.BROWSER_PORT_PROBE_TIMEOUT_MS = BROWSER_PORT_PROBE_TIMEOUT_MS;
 exports.BROWSER_PROCESS_EXIT_CAUSE = BROWSER_PROCESS_EXIT_CAUSE;
+exports.BROWSER_PROFILE_PREFIX = BROWSER_PROFILE_PREFIX;
 exports.BROWSER_STORE_CACHE_DIRS = BROWSER_STORE_CACHE_DIRS;
 exports.BROWSER_STORE_DEFAULT_DIRS = BROWSER_STORE_DEFAULT_DIRS;
 exports.BROWSER_STORE_ENV_KEY = BROWSER_STORE_ENV_KEY;
@@ -1322,6 +1433,7 @@ exports.BrowserNotConnectedError = BrowserNotConnectedError;
 exports.WebSocketCDPTransport = WebSocketCDPTransport;
 exports.browserToEngine = browserToEngine;
 exports.createBrowser = createBrowser;
+exports.createBrowserProfile = createBrowserProfile;
 exports.createCDPTransport = createCDPTransport;
 exports.createScreenshotWriter = createScreenshotWriter;
 exports.defaultInstallPaths = defaultInstallPaths;
@@ -1343,6 +1455,7 @@ exports.normalizeExecutablePath = normalizeExecutablePath;
 exports.parseBrowserEngine = parseBrowserEngine;
 exports.probeAllPathNames = probeAllPathNames;
 exports.probePathNames = probePathNames;
+exports.removeBrowserProfile = removeBrowserProfile;
 exports.waitForCDPReady = waitForCDPReady;
 exports.windowsRoots = windowsRoots;