@orkestrel/browser 0.0.5 → 0.0.6

package/dist/src/server/index.d.ts

@@ -1,4 +1,5 @@
 import { BrowserContextInterface } from '../core/index.ts';
+import { BrowserContextOptions } from '../core/index.ts';
 import { BrowserError } from '../core/index.ts';
 import { BrowserPageInterface } from '../core/index.ts';
 import { BrowserPageOptions } from '../core/index.ts';
@@ -14,6 +15,9 @@ import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { ScreenshotWriterInterface } from '../core/index.ts';
 
+/**
+ * Discovers, launches, connects to, and owns Chromium-family browser sessions.
+ */
 export declare class Browser implements BrowserInterface {
     #private;
     constructor(options?: BrowserOptions);
@@ -30,6 +34,7 @@ export declare class Browser implements BrowserInterface {
     disconnect(): Promise<void>;
     context(index?: number): BrowserContextInterface | undefined;
     contexts(): readonly BrowserContextInterface[];
+    isolate(options?: BrowserContextOptions): Promise<BrowserContextInterface>;
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
     destroy(): Promise<void>;
     close(): Promise<void>;
@@ -80,6 +85,9 @@ export declare const BROWSER_PORT_PROBE_TIMEOUT_MS = 200;
 /** Machine-readable error-context cause for an owned browser process exiting. */
 export declare const BROWSER_PROCESS_EXIT_CAUSE = "process-exit";
 
+/** Prefix for isolated browser profiles created beneath the operating-system temp directory. */
+export declare const BROWSER_PROFILE_PREFIX = "orkestrel-browser-";
+
 /** Per-OS default Playwright browser cache directory, relative to the home directory (win32 uses `LOCALAPPDATA` directly). */
 export declare const BROWSER_STORE_CACHE_DIRS: Readonly<Record<string, string>>;
 
@@ -190,6 +198,7 @@ export declare type BrowserEventMap = {
     readonly disconnect: readonly [];
     readonly launch: readonly [engine: BrowserEngine];
     readonly page: readonly [page: BrowserPageInterface];
+    readonly context: readonly [context: BrowserContextInterface];
     readonly error: readonly [error: unknown];
     readonly destroy: readonly [];
 };
@@ -266,6 +275,7 @@ export declare interface BrowserInterface {
     disconnect(): Promise<void>;
     context(index?: number): BrowserContextInterface | undefined;
     contexts(): readonly BrowserContextInterface[];
+    isolate(options?: BrowserContextOptions): Promise<BrowserContextInterface>;
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
     destroy(): Promise<void>;
     close(): Promise<void>;
@@ -315,6 +325,19 @@ export declare interface BrowserOptions {
     readonly browsers?: SystemBrowserOptions;
 }
 
+/**
+ * Resolved browser profile directory used for a Chromium-family launch.
+ *
+ * @remarks
+ * `temporary` is true only for an isolated profile created by
+ * {@link createBrowserProfile}; caller-supplied persistent profiles are
+ * never removed by the library.
+ */
+export declare interface BrowserProfileResult {
+    readonly path: string;
+    readonly temporary: boolean;
+}
+
 /** Lifecycle status of a browser wrapper. */
 export declare type BrowserStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
 
@@ -337,6 +360,14 @@ export declare function browserToEngine(browser?: string): BrowserEngine;
  */
 export declare function createBrowser(options?: BrowserOptions): BrowserInterface;
 
+/**
+ * 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
+ */
+export declare function createBrowserProfile(path?: string): Promise<BrowserProfileResult>;
+
 /**
  * Create a Node `WebSocket`-backed CDP transport.
  *
@@ -473,6 +504,18 @@ export declare function probeAllPathNames(names: readonly string[], platform: st
 /** Probe PATH (`which`/`where`) for the first resolvable command name. */
 export declare function probePathNames(names: readonly string[], platform: string): string | undefined;
 
+/**
+ * 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
+ */
+export declare function removeBrowserProfile(profile: BrowserProfileResult): Promise<void>;
+
 /**
  * One discovered browser executable on this machine.
  *

package/dist/src/server/index.js

@@ -1,16 +1,17 @@
-import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_WAIT_POLL_INTERVAL_MS, BrowserContext, BrowserError, CDPClient } from "../core/index.js";
+import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_WAIT_POLL_INTERVAL_MS, BrowserContext, BrowserError, CDPClient, validateBrowserContextOptions } from "../core/index.js";
+import { attempt, isArray, isError, isInstance, isInteger, isRecord, isString } from "@orkestrel/contract";
 import { existsSync, globSync } from "node:fs";
-import { dirname, posix, win32 } from "node:path";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, posix, resolve, win32 } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
-import { isRecord, isString } from "@orkestrel/contract";
 import { randomBytes } from "node:crypto";
 import { request } from "node:http";
 import { request as request$1 } from "node:https";
 import { Emitter } from "@orkestrel/emitter";
 import { WEBSOCKET_READY_CLOSED, WEBSOCKET_READY_OPEN, WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
 import { addAbortListener, once } from "node:events";
-import { mkdir, writeFile } from "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;
@@ -26,6 +27,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. */
@@ -157,7 +160,7 @@ var BrowserDestroyedError = class extends BrowserError {
 * @returns True when value is a BrowserConnectionError instance
 */
 function isBrowserConnectionError(value) {
-	return value instanceof BrowserConnectionError;
+	return isInstance(value, BrowserConnectionError);
 }
 /**
 * Narrow an unknown value to BrowserNotConnectedError.
@@ -166,7 +169,7 @@ function isBrowserConnectionError(value) {
 * @returns True when value is a BrowserNotConnectedError instance
 */
 function isBrowserNotConnectedError(value) {
-	return value instanceof BrowserNotConnectedError;
+	return isInstance(value, BrowserNotConnectedError);
 }
 /**
 * Narrow an unknown value to BrowserDestroyedError.
@@ -175,7 +178,7 @@ function isBrowserNotConnectedError(value) {
 * @returns True when value is a BrowserDestroyedError instance
 */
 function isBrowserDestroyedError(value) {
-	return value instanceof BrowserDestroyedError;
+	return isInstance(value, BrowserDestroyedError);
 }
 //#endregion
 //#region src/server/helpers.ts
@@ -263,6 +266,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 mkdtemp(join(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 = resolve(profile.path);
+	const temporary = resolve(tmpdir());
+	if (dirname(path) !== temporary || !basename(path).startsWith("orkestrel-browser-")) throw new Error("Refusing to remove an unsafe browser profile path");
+	await 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];
@@ -415,7 +456,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 (!isArray(list)) return [];
 		const targets = [];
 		for (const entry of list) {
 			if (!isRecord(entry)) continue;
@@ -479,12 +520,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) {
@@ -498,16 +539,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 = 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 = randomBytes(16).toString("base64");
 		const deferred = Promise.withResolvers();
@@ -669,6 +715,9 @@ function createScreenshotWriter() {
 }
 //#endregion
 //#region src/server/Browser.ts
+/**
+* Discovers, launches, connects to, and owns Chromium-family browser sessions.
+*/
 var Browser = class {
 	#emitter;
 	#options;
@@ -682,6 +731,7 @@ var Browser = class {
 	#endpoint;
 	#client;
 	#process;
+	#profile;
 	#contexts = [];
 	#destroyed = false;
 	#connecting;
@@ -779,6 +829,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();
+		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 (!isRecord(result) || !isString(result["browserContextId"])) throw new BrowserConnectionError("Failed to create isolated browser context");
+		const id = result["browserContextId"];
+		const context = new 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;
@@ -786,7 +865,7 @@ var Browser = class {
 		let context = this.#contexts[0];
 		if (context === void 0) {
 			context = new 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);
@@ -839,8 +918,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(isError(error) ? error.message : String(error), { executable: this.#options.executable });
 		}
 	}
 	async #detach() {
@@ -889,6 +968,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;
@@ -1063,8 +1143,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 {
@@ -1078,7 +1166,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;
@@ -1094,6 +1182,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;
@@ -1110,16 +1199,16 @@ var Browser = class {
 		const signal = AbortSignal.any([controller.signal, this.#signal()]);
 		const ready = waitForCDPReady(this.#cdpPort, this.#timeout(), this.#cdpHost, signal);
 		const exited = 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 = isInteger(values[0]) ? values[0] : null;
+			const exitSignal = 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(isError(error) ? error.message : String(error), context);
 		} finally {
 			controller.abort();
 			ready.catch(() => void 0);
@@ -1144,7 +1233,7 @@ var Browser = class {
 		} catch {
 			return;
 		}
-		if (!isRecord(result) || !Array.isArray(result["targetInfos"])) return;
+		if (!isRecord(result) || !isArray(result["targetInfos"])) return;
 		const pages = [];
 		for (const target of result["targetInfos"]) {
 			if (!isRecord(target) || !isString(target["targetId"]) || target["type"] !== "page" || !isString(target["title"]) || !isString(target["url"])) continue;
@@ -1158,7 +1247,7 @@ var Browser = class {
 		if (pages.length === 0 || this.#contexts.length > 0) return;
 		const context = new BrowserContext(client, void 0, this.#options.viewport, createScreenshotWriter());
 		await context.sync(pages);
-		this.#contexts.push(context);
+		this.#registerContext(context);
 	}
 	async #destroyResources() {
 		try {
@@ -1176,7 +1265,11 @@ var Browser = class {
 			await this.#closeClient(client);
 			this.#client = void 0;
 		} finally {
-			this.#finish();
+			try {
+				await this.#releaseProfile();
+			} finally {
+				this.#finish();
+			}
 		}
 	}
 	async #closeResources() {
@@ -1196,7 +1289,11 @@ var Browser = class {
 			await this.#closeClient(client);
 			this.#client = void 0;
 		} finally {
-			this.#finish();
+			try {
+				await this.#releaseProfile();
+			} finally {
+				this.#finish();
+			}
 		}
 	}
 	async #settle() {
@@ -1228,12 +1325,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 {
@@ -1246,6 +1351,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 once(process, "exit");
@@ -1291,6 +1401,6 @@ var Browser = class {
 	}
 };
 //#endregion
-export { BROWSER_CDP_LIST_PATH, BROWSER_CDP_PROTOCOL, BROWSER_CDP_VERSION_PATH, BROWSER_DEFAULT_CDP_PORT, BROWSER_DEFAULT_HOST, BROWSER_ENGINE_HINTS, BROWSER_ENV_PATH_KEYS, BROWSER_EXECUTABLE_NAMES, BROWSER_EXECUTABLE_PATHS, BROWSER_HEADLESS_ARG, BROWSER_KILL_GRACE_MS, BROWSER_LAUNCH_ARGS, BROWSER_PORT_PROBE_TIMEOUT_MS, BROWSER_PROCESS_EXIT_CAUSE, BROWSER_STORE_CACHE_DIRS, BROWSER_STORE_DEFAULT_DIRS, BROWSER_STORE_ENV_KEY, BROWSER_STORE_GLOBS, BROWSER_STORE_LINK_NAME, BROWSER_TRANSPORT_LOSS_CAUSE, BROWSER_TRANSPORT_LOSS_DEFER_MS, BROWSER_WINDOWS_ROOT_FALLBACKS, BROWSER_WINDOWS_SUFFIXES, Browser, BrowserConnectionError, BrowserDestroyedError, BrowserNotConnectedError, WebSocketCDPTransport, browserToEngine, createBrowser, createCDPTransport, createScreenshotWriter, defaultInstallPaths, defaultStoreBases, fetchCDPTargets, findAllEnvOverrides, findAllInStore, findAllInstallPaths, findEnvOverride, findInStore, findInstallPath, findSystemBrowser, findSystemBrowsers, isBrowserConnectionError, isBrowserDestroyedError, isBrowserNotConnectedError, launchBrowserProcess, normalizeExecutablePath, parseBrowserEngine, probeAllPathNames, probePathNames, waitForCDPReady, windowsRoots };
+export { BROWSER_CDP_LIST_PATH, BROWSER_CDP_PROTOCOL, BROWSER_CDP_VERSION_PATH, BROWSER_DEFAULT_CDP_PORT, BROWSER_DEFAULT_HOST, BROWSER_ENGINE_HINTS, BROWSER_ENV_PATH_KEYS, BROWSER_EXECUTABLE_NAMES, BROWSER_EXECUTABLE_PATHS, BROWSER_HEADLESS_ARG, BROWSER_KILL_GRACE_MS, BROWSER_LAUNCH_ARGS, BROWSER_PORT_PROBE_TIMEOUT_MS, BROWSER_PROCESS_EXIT_CAUSE, BROWSER_PROFILE_PREFIX, BROWSER_STORE_CACHE_DIRS, BROWSER_STORE_DEFAULT_DIRS, BROWSER_STORE_ENV_KEY, BROWSER_STORE_GLOBS, BROWSER_STORE_LINK_NAME, BROWSER_TRANSPORT_LOSS_CAUSE, BROWSER_TRANSPORT_LOSS_DEFER_MS, BROWSER_WINDOWS_ROOT_FALLBACKS, BROWSER_WINDOWS_SUFFIXES, Browser, BrowserConnectionError, BrowserDestroyedError, BrowserNotConnectedError, WebSocketCDPTransport, browserToEngine, createBrowser, createBrowserProfile, createCDPTransport, createScreenshotWriter, defaultInstallPaths, defaultStoreBases, fetchCDPTargets, findAllEnvOverrides, findAllInStore, findAllInstallPaths, findEnvOverride, findInStore, findInstallPath, findSystemBrowser, findSystemBrowsers, isBrowserConnectionError, isBrowserDestroyedError, isBrowserNotConnectedError, launchBrowserProcess, normalizeExecutablePath, parseBrowserEngine, probeAllPathNames, probePathNames, removeBrowserProfile, waitForCDPReady, windowsRoots };
 
 //# sourceMappingURL=index.js.map