@orkestrel/browser 0.0.6 → 0.0.7

package/dist/src/server/index.cjs

@@ -30,7 +30,7 @@ var BROWSER_LAUNCH_ARGS = Object.freeze(["--no-first-run", "--no-default-browser
 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. */
+/** Bound for each launched-process exit window during TERM-to-KILL 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. */
 var BROWSER_PORT_PROBE_TIMEOUT_MS = 200;
@@ -395,6 +395,10 @@ function findAllInStore(base, platform) {
 /**
 * Launch a browser process with raw-CDP debugging flags.
 *
+* @remarks
+* POSIX launches own an isolated process group so lifecycle teardown can
+* signal and await every Chromium subprocess without affecting the caller.
+*
 * @param executable - Absolute path to the browser executable
 * @param port - Port the browser exposes its CDP endpoint on
 * @param headless - Whether to launch in headless mode
@@ -408,7 +412,10 @@ function launchBrowserProcess(executable, port, headless, profile, extra) {
 	args.push(`--remote-debugging-port=${port}`, ...BROWSER_LAUNCH_ARGS);
 	if (headless) args.push(BROWSER_HEADLESS_ARG);
 	if (profile !== void 0) args.push(`--user-data-dir=${profile}`);
-	return (0, node_child_process.spawn)(executable, args, { stdio: "ignore" });
+	return (0, node_child_process.spawn)(executable, args, {
+		stdio: "ignore",
+		detached: process.platform !== "win32"
+	});
 }
 /**
 * Poll a browser's CDP version endpoint until it responds or the timeout elapses.
@@ -499,11 +506,11 @@ var WebSocketCDPTransport = class {
 	#reject;
 	#timer;
 	#closeResolve;
-	#onSocketClose = () => this.#closeResolve?.();
+	#onSocketClose = this.#handleSocketClose.bind(this);
 	constructor(options) {
 		this.#emitter = new _orkestrel_emitter.Emitter({
-			on: options.on,
-			error: options.error
+			...options.on !== void 0 ? { on: options.on } : {},
+			...options.error !== void 0 ? { error: options.error } : {}
 		});
 		this.#url = options.url;
 		this.#timeout = options.timeout ?? _src_core.BROWSER_DEFAULT_TIMEOUT_MS;
@@ -674,6 +681,9 @@ var WebSocketCDPTransport = class {
 		});
 		socket.emitter.on("error", (error) => this.#emitter.emit("error", error));
 	}
+	#handleSocketClose() {
+		this.#closeResolve?.();
+	}
 };
 //#endregion
 //#region src/server/factories.ts
@@ -737,15 +747,16 @@ var Browser = class {
 	#destroyed = false;
 	#connecting;
 	#disconnecting;
+	#exitCleanup;
 	#shutdown;
 	#transport;
-	#onTransportClose = () => this.#handleTransportLoss();
-	#onTransportError = () => this.#handleTransportLoss();
-	#onProcessExit = () => this.#handleProcessExit();
+	#onTransportClose = this.#handleTransportLoss.bind(this);
+	#onTransportError = this.#handleTransportLoss.bind(this);
+	#onProcessExit = this.#handleProcessExit.bind(this);
 	constructor(options) {
 		this.#emitter = new _orkestrel_emitter.Emitter({
-			on: options?.on,
-			error: options?.error
+			...options?.on !== void 0 ? { on: options.on } : {},
+			...options?.error !== void 0 ? { error: options.error } : {}
 		});
 		this.#options = options ?? {};
 		this.#engine = this.#options.engine ?? (this.#options.executable !== void 0 ? parseBrowserEngine(this.#options.executable) ?? "chromium" : "chromium");
@@ -781,14 +792,12 @@ var Browser = class {
 	}
 	async connect() {
 		if (this.#destroyed) throw new BrowserDestroyedError();
-		if (this.#disconnecting !== void 0) await this.#disconnecting;
-		if (this.#destroyed) throw new BrowserDestroyedError();
-		if (this.#status === "connected") return;
 		const active = this.#connecting;
 		if (active !== void 0) {
 			await active;
 			return;
 		}
+		if (this.#status === "connected") return;
 		const attempt = this.#establish();
 		this.#connecting = attempt;
 		try {
@@ -804,15 +813,11 @@ var Browser = class {
 	}
 	async disconnect() {
 		if (this.#destroyed) return;
-		const active = this.#disconnecting;
-		if (active !== void 0) {
-			await active;
-			return;
-		}
-		if (this.#connecting !== void 0) {
-			await this.#connecting.catch(() => void 0);
-			if (this.#destroyed) return;
-		}
+		const disconnecting = this.#disconnecting;
+		const connecting = this.#connecting;
+		if (disconnecting !== void 0) await disconnecting;
+		if (connecting !== void 0) await connecting.catch(() => void 0);
+		if (this.#destroyed) return;
 		if (this.#status !== "connected" || this.#client === void 0) return;
 		const attempt = this.#detach();
 		this.#disconnecting = attempt;
@@ -893,6 +898,10 @@ var Browser = class {
 		return shutdown;
 	}
 	async #establish() {
+		if (this.#disconnecting !== void 0) await this.#disconnecting;
+		await this.#settleExit();
+		if (this.#destroyed) throw new BrowserDestroyedError();
+		if (this.#status === "connected") return;
 		this.#assertNotAborted();
 		this.#status = "connecting";
 		try {
@@ -966,18 +975,19 @@ var Browser = class {
 		const connected = this.#status === "connected";
 		const client = this.#client;
 		const contexts = this.#contexts;
+		const process = this.#process;
 		this.#unbindTransport();
 		this.#unbindProcess();
 		this.#process = void 0;
-		this.#releaseProfile().catch((error) => this.#emitter.emit("error", error));
+		const cleanup = this.#cleanupExitedProcess(process, contexts, client);
+		this.#exitCleanup = cleanup;
+		cleanup.catch((error) => this.#emitter.emit("error", error));
 		this.#client = void 0;
 		this.#contexts = [];
 		this.#connection = void 0;
 		this.#owned = void 0;
 		this.#endpoint = void 0;
 		if (connected) this.#status = "disconnected";
-		this.#destroyContextList(contexts);
-		this.#closeClient(client);
 		this.#emitter.emit("error", new BrowserConnectionError("The browser process exited unexpectedly", { cause: BROWSER_PROCESS_EXIT_CAUSE }));
 		if (connected) {
 			this.#emitter.emit("disconnect");
@@ -1137,7 +1147,7 @@ var Browser = class {
 		else {
 			const found = findSystemBrowser({
 				...this.#options.browsers,
-				engine: requestedEngine
+				...requestedEngine !== void 0 ? { engine: requestedEngine } : {}
 			});
 			executable = found?.executable;
 			resolvedEngine = found?.engine;
@@ -1251,6 +1261,7 @@ var Browser = class {
 		this.#registerContext(context);
 	}
 	async #destroyResources() {
+		let terminated = false;
 		try {
 			await this.#settle();
 			this.#unbindTransport();
@@ -1263,17 +1274,22 @@ var Browser = class {
 			this.#contexts = [];
 			await this.#terminate(this.#process);
 			this.#process = void 0;
-			await this.#closeClient(client);
-			this.#client = void 0;
+			terminated = true;
 		} finally {
+			const contexts = this.#contexts;
+			this.#contexts = [];
+			const client = this.#client;
+			this.#client = void 0;
 			try {
-				await this.#releaseProfile();
+				await this.#cleanupLocal(contexts, client);
+				if (terminated) await this.#releaseProfile();
 			} finally {
 				this.#finish();
 			}
 		}
 	}
 	async #closeResources() {
+		let terminated = false;
 		try {
 			await this.#settle();
 			this.#unbindTransport();
@@ -1284,14 +1300,18 @@ var Browser = class {
 			await this.#closeRemote(client);
 			const process = this.#process;
 			if (process !== void 0) {
-				if (!await this.#waitForProcessWithin(process, 3e3)) await this.#terminate(process);
+				if (!await this.#waitForTerminationWithin(process, 3e3)) await this.#terminate(process);
 			}
 			this.#process = void 0;
-			await this.#closeClient(client);
-			this.#client = void 0;
+			terminated = true;
 		} finally {
+			const contexts = this.#contexts;
+			this.#contexts = [];
+			const client = this.#client;
+			this.#client = void 0;
 			try {
-				await this.#releaseProfile();
+				await this.#cleanupLocal(contexts, client);
+				if (terminated) await this.#releaseProfile();
 			} finally {
 				this.#finish();
 			}
@@ -1300,6 +1320,13 @@ var Browser = class {
 	async #settle() {
 		await this.#connecting?.catch(() => void 0);
 		await this.#disconnecting?.catch(() => void 0);
+		await this.#settleExit();
+	}
+	async #settleExit() {
+		const cleanup = this.#exitCleanup;
+		if (cleanup === void 0) return;
+		await cleanup;
+		if (this.#exitCleanup === cleanup) this.#exitCleanup = void 0;
 	}
 	async #closeRemote(client) {
 		let remote = client;
@@ -1357,9 +1384,19 @@ var Browser = class {
 		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");
+	async #cleanupExitedProcess(process, contexts, client) {
+		let terminated = false;
+		try {
+			await this.#terminate(process);
+			terminated = true;
+		} finally {
+			await this.#cleanupLocal(contexts, client);
+		}
+		if (terminated) await this.#releaseProfile();
+	}
+	async #cleanupLocal(contexts, client) {
+		await this.#destroyContextList(contexts);
+		await this.#closeClient(client);
 	}
 	async #waitForProcessWithin(process, timeout) {
 		if (process.exitCode !== null || process.signalCode !== null) return true;
@@ -1372,20 +1409,55 @@ var Browser = class {
 			throw error;
 		}
 	}
-	async #terminate(process) {
-		if (process === void 0 || process.exitCode !== null || process.signalCode !== null) return;
+	#hasProcessGroup(process) {
+		const pid = process.pid;
+		return globalThis.process.platform !== "win32" && pid !== void 0 && pid > 0;
+	}
+	#inspectProcessGroup(process) {
+		if (!this.#hasProcessGroup(process)) return false;
+		return this.#signalProcess(process, 0);
+	}
+	#signalProcess(process, signal) {
+		const pid = process.pid;
 		try {
-			process.kill("SIGTERM");
-		} catch {
-			return;
+			if (this.#hasProcessGroup(process) && pid !== void 0) return globalThis.process.kill(-pid, signal);
+			return process.kill(signal);
+		} catch (error) {
+			const code = (0, _orkestrel_contract.isError)(error) && "code" in error && (0, _orkestrel_contract.isString)(error.code) ? error.code : void 0;
+			if (code === "ESRCH") return false;
+			if (signal === 0) return code === "EPERM" ? true : void 0;
+			throw new BrowserConnectionError("Failed to signal the browser process", {
+				pid,
+				signal,
+				cause: error
+			});
 		}
-		if (await this.#waitForProcessWithin(process, 3e3)) return;
-		try {
-			process.kill("SIGKILL");
-		} catch {
-			return;
+	}
+	async #waitForProcessGroupWithin(process, timeout) {
+		const deadline = performance.now() + timeout;
+		let confirmed = false;
+		while (true) {
+			const alive = this.#inspectProcessGroup(process);
+			if (alive === false) return true;
+			if (alive === true) confirmed = true;
+			const remaining = deadline - performance.now();
+			if (remaining <= 0) return confirmed ? false : void 0;
+			await new Promise((resolve) => setTimeout(resolve, Math.min(_src_core.BROWSER_WAIT_POLL_INTERVAL_MS, remaining)));
 		}
-		await this.#waitForProcess(process);
+	}
+	async #waitForTerminationWithin(process, timeout, final = false) {
+		const exited = this.#waitForProcessWithin(process, timeout);
+		const drained = this.#waitForProcessGroupWithin(process, timeout);
+		const results = await Promise.all([exited, drained]);
+		return results[0] && (results[1] === true || final && results[1] === void 0);
+	}
+	async #terminate(process) {
+		if (process === void 0 || (process.exitCode !== null || process.signalCode !== null) && this.#inspectProcessGroup(process) === false) return;
+		if (this.#signalProcess(process, "SIGTERM") === false) return;
+		if (await this.#waitForTerminationWithin(process, 3e3)) return;
+		if (this.#signalProcess(process, "SIGKILL") === false) return;
+		if (await this.#waitForTerminationWithin(process, 3e3, true)) return;
+		throw new BrowserConnectionError("Browser process did not exit after SIGKILL", { pid: process.pid });
 	}
 	#finish() {
 		this.#unbindTransport();
@@ -1396,6 +1468,7 @@ var Browser = class {
 		this.#endpoint = void 0;
 		this.#client = void 0;
 		this.#process = void 0;
+		this.#exitCleanup = void 0;
 		this.#contexts = [];
 		this.#emitter.emit("destroy");
 		this.#emitter.destroy();