@pasko70/pibo 1.9.7 → 1.9.9

package/dist/tools/browser-pool.js

@@ -1,623 +0,0 @@
-import { access, mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { randomUUID } from "node:crypto";
-const DEFAULT_MAX_BROWSER_PROCESSES = 1;
-const DEFAULT_LOCK_TIMEOUT_MS = 5_000;
-const DEFAULT_LOCK_POLL_INTERVAL_MS = 50;
-const DEFAULT_LOCK_STALE_MS = 10 * 60_000;
-const DEFAULT_CDP_HEALTH_TIMEOUT_MS = 2_500;
-const DEFAULT_CDP_CLEANUP_MAX_TARGETS = 25;
-const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60_000;
-export class BrowserPoolLockTimeoutError extends Error {
-    constructor(lockPath, timeoutMs) {
-        super(`Timed out acquiring browser pool lock ${lockPath} after ${timeoutMs}ms`);
-        this.name = "BrowserPoolLockTimeoutError";
-    }
-}
-export class BrowserPoolStateError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "BrowserPoolStateError";
-    }
-}
-export function createEmptyBrowserPoolState(identity) {
-    return {
-        workerId: identity.workerId,
-        poolId: identity.poolId,
-        maxBrowserProcesses: identity.maxBrowserProcesses ?? DEFAULT_MAX_BROWSER_PROCESSES,
-        activeLeaseCount: 0,
-        state: "empty",
-        cleanupStatus: "not-attempted",
-    };
-}
-export function browserPoolPaths(rootDir, identity) {
-    const safeWorkerId = safePathSegment(identity.workerId);
-    const safePoolId = safePathSegment(identity.poolId);
-    const base = join(rootDir, "browser-pools", safeWorkerId, safePoolId);
-    return {
-        statePath: join(base, "state.json"),
-        lockPath: join(base, "state.lock"),
-    };
-}
-export async function loadBrowserPoolState(statePath, options) {
-    let raw;
-    try {
-        raw = await readFile(statePath, "utf8");
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === "ENOENT" && (options.onMissing ?? "empty") === "empty") {
-            return createEmptyBrowserPoolState(options);
-        }
-        throw error;
-    }
-    try {
-        return normalizeBrowserPoolState(JSON.parse(raw), options);
-    }
-    catch (error) {
-        const stateError = toBrowserPoolStateError(error);
-        if ((options.onMalformed ?? "throw") === "empty") {
-            return {
-                ...createEmptyBrowserPoolState(options),
-                state: "dirty",
-                lastError: stateError.message,
-            };
-        }
-        throw stateError;
-    }
-}
-export async function saveBrowserPoolState(statePath, state) {
-    const normalized = normalizeBrowserPoolState(state, state);
-    await mkdir(dirname(statePath), { recursive: true });
-    const temporaryPath = `${statePath}.${process.pid}.${randomUUID()}.tmp`;
-    await writeFile(temporaryPath, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
-    await rename(temporaryPath, statePath);
-}
-export async function withBrowserPoolLock(lockPath, options, run) {
-    const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
-    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_LOCK_POLL_INTERVAL_MS;
-    const staleMs = options.staleMs ?? DEFAULT_LOCK_STALE_MS;
-    const holder = options.holder ?? `${process.pid}`;
-    const startedAt = Date.now();
-    while (true) {
-        try {
-            await mkdir(dirname(lockPath), { recursive: true });
-            const handle = await open(lockPath, "wx");
-            try {
-                await handle.writeFile(JSON.stringify({ holder, pid: process.pid, createdAt: new Date().toISOString() }), "utf8");
-            }
-            finally {
-                await handle.close();
-            }
-            break;
-        }
-        catch (error) {
-            if (!isNodeError(error) || error.code !== "EEXIST")
-                throw error;
-            await removeStaleLock(lockPath, staleMs);
-            if (Date.now() - startedAt >= timeoutMs)
-                throw new BrowserPoolLockTimeoutError(lockPath, timeoutMs);
-            await delay(Math.min(pollIntervalMs, Math.max(1, timeoutMs - (Date.now() - startedAt))));
-        }
-    }
-    try {
-        return await run();
-    }
-    finally {
-        await rm(lockPath, { force: true });
-    }
-}
-export async function mutateBrowserPoolState(paths, identity, kind, mutation, lockOptions = {}) {
-    return withBrowserPoolLock(paths.lockPath, { ...lockOptions, holder: lockOptions.holder ?? kind }, async () => {
-        const current = await loadBrowserPoolState(paths.statePath, identity);
-        const next = await mutation(current);
-        await saveBrowserPoolState(paths.statePath, next.state);
-        return next.result;
-    });
-}
-export async function checkBrowserPoolCdpHealth(cdpUrl, options = {}) {
-    const timeoutMs = options.timeoutMs ?? DEFAULT_CDP_HEALTH_TIMEOUT_MS;
-    try {
-        const response = await fetchWithTimeout(`${trimTrailingSlash(cdpUrl)}/json/version`, timeoutMs);
-        if (!response.ok)
-            return { ok: false, reason: `CDP /json/version returned HTTP ${response.status}` };
-        const payload = await response.json();
-        if (!payload || typeof payload !== "object" || Array.isArray(payload))
-            return { ok: false, reason: "CDP /json/version returned malformed JSON" };
-        const browser = payload.Browser;
-        if (typeof browser !== "string" || browser.length === 0)
-            return { ok: false, reason: "CDP /json/version response is missing Browser" };
-        return { ok: true, browser };
-    }
-    catch (error) {
-        return { ok: false, reason: `CDP health check failed: ${error instanceof Error ? error.message : String(error)}` };
-    }
-}
-export async function cleanupBrowserPoolCdpTargets(cdpUrl, options = {}) {
-    const timeoutMs = options.timeoutMs ?? DEFAULT_CDP_HEALTH_TIMEOUT_MS;
-    const maxTargets = options.maxTargets ?? DEFAULT_CDP_CLEANUP_MAX_TARGETS;
-    try {
-        const baseUrl = trimTrailingSlash(cdpUrl);
-        const response = await fetchWithTimeout(`${baseUrl}/json/list`, timeoutMs);
-        if (!response.ok)
-            return { ok: false, status: "failed", closedTargets: 0, reason: `CDP /json/list returned HTTP ${response.status}` };
-        const payload = await response.json();
-        if (!Array.isArray(payload))
-            return { ok: false, status: "failed", closedTargets: 0, reason: "CDP /json/list returned malformed JSON" };
-        const pageTargetIds = payload
-            .slice(0, maxTargets)
-            .filter((target) => Boolean(target) && typeof target === "object" && !Array.isArray(target))
-            .filter((target) => target.type === "page" && typeof target.id === "string" && target.id.length > 0)
-            .map((target) => target.id);
-        let closedTargets = 0;
-        for (const targetId of pageTargetIds) {
-            const closeResponse = await fetchWithTimeout(`${baseUrl}/json/close/${encodeURIComponent(targetId)}`, timeoutMs);
-            if (!closeResponse.ok) {
-                return { ok: false, status: "failed", closedTargets, reason: `CDP /json/close/${targetId} returned HTTP ${closeResponse.status}` };
-            }
-            closedTargets += 1;
-        }
-        return { ok: true, status: "success", closedTargets };
-    }
-    catch (error) {
-        return { ok: false, status: "failed", closedTargets: 0, reason: `CDP cleanup failed: ${error instanceof Error ? error.message : String(error)}` };
-    }
-}
-export async function acquireBrowserPoolLease(paths, identity, options = {}) {
-    const leaseId = options.leaseId ?? randomUUID();
-    const now = options.now ?? (() => new Date());
-    const checkCdpHealth = options.checkCdpHealth ?? checkBrowserPoolCdpHealth;
-    const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
-    const cdpTimeoutMs = options.cdpTimeoutMs ?? DEFAULT_CDP_HEALTH_TIMEOUT_MS;
-    const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
-    return mutateBrowserPoolState(paths, { ...identity, onMalformed: "empty" }, "acquire", async (current) => {
-        const checkedAt = now();
-        const lastUsedAt = checkedAt.toISOString();
-        const idleExpiresAt = new Date(checkedAt.getTime() + idleTimeoutMs).toISOString();
-        const reusable = await evaluateRecordedBrowser(current, isPidAlive, checkCdpHealth, cdpTimeoutMs);
-        if (reusable.ok) {
-            const busyReason = activeLeaseBusyReason(current, leaseId, checkedAt);
-            if (busyReason) {
-                const busyState = stripUndefined({ ...current, lastUsedAt, lastError: busyReason });
-                return { state: busyState, result: { acquired: false, state: busyState, staleReason: busyReason } };
-            }
-            const nextState = stripUndefined({
-                ...current,
-                state: "leased",
-                activeLeaseId: leaseId,
-                activeLeaseCount: 1,
-                holder: options.holder,
-                lastUsedAt,
-                idleExpiresAt,
-                cleanupStatus: "not-attempted",
-                lastError: undefined,
-            });
-            return {
-                state: nextState,
-                result: { acquired: true, leaseId, cdpUrl: current.cdpUrl, pid: current.pid, reused: true, replaced: false, state: nextState },
-            };
-        }
-        const staleState = stripUndefined({
-            ...current,
-            state: current.state === "dirty" ? "dirty" : "stale",
-            activeLeaseId: undefined,
-            activeLeaseCount: 0,
-            holder: undefined,
-            lastUsedAt,
-            idleExpiresAt: undefined,
-            lastError: reusable.reason,
-        });
-        if (!options.startBrowser) {
-            return { state: staleState, result: { acquired: false, state: staleState, staleReason: reusable.reason } };
-        }
-        try {
-            const started = await options.startBrowser(staleState);
-            const nextState = stripUndefined({
-                workerId: current.workerId,
-                poolId: current.poolId,
-                maxBrowserProcesses: current.maxBrowserProcesses,
-                pid: started.pid,
-                processGroupId: started.processGroupId,
-                cdpPort: started.cdpPort,
-                cdpUrl: started.cdpUrl,
-                userDataDir: started.userDataDir,
-                activeLeaseId: leaseId,
-                activeLeaseCount: 1,
-                holder: options.holder,
-                lastUsedAt,
-                idleExpiresAt,
-                state: "leased",
-                cleanupStatus: "not-attempted",
-            });
-            return {
-                state: nextState,
-                result: { acquired: true, leaseId, cdpUrl: started.cdpUrl, pid: started.pid, reused: false, replaced: current.state !== "empty", staleReason: reusable.reason, state: nextState },
-            };
-        }
-        catch (error) {
-            const dirtyState = stripUndefined({ ...staleState, state: "dirty", lastError: `Browser replacement failed: ${error instanceof Error ? error.message : String(error)}` });
-            return { state: dirtyState, result: { acquired: false, state: dirtyState, staleReason: dirtyState.lastError } };
-        }
-    }, options.lockOptions);
-}
-export async function releaseBrowserPoolLease(paths, identity, options = {}) {
-    const now = options.now ?? (() => new Date());
-    const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
-    const cleanupCdp = options.cleanupCdp ?? cleanupBrowserPoolCdpTargets;
-    const cdpTimeoutMs = options.cdpTimeoutMs ?? DEFAULT_CDP_HEALTH_TIMEOUT_MS;
-    const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
-    return mutateBrowserPoolState(paths, { ...identity, onMissing: "empty", onMalformed: "empty" }, "release", async (current) => {
-        const releasedAt = now();
-        const lastUsedAt = releasedAt.toISOString();
-        const idleExpiresAt = new Date(releasedAt.getTime() + idleTimeoutMs).toISOString();
-        const requestedLeaseId = options.leaseId;
-        if (current.state !== "leased" || !current.activeLeaseId) {
-            const nextState = stripUndefined({
-                ...current,
-                activeLeaseId: undefined,
-                activeLeaseCount: 0,
-                holder: undefined,
-                lastUsedAt,
-                cleanupStatus: "skipped",
-                lastError: "No active browser pool lease to release",
-            });
-            return { state: nextState, result: { released: false, cleanupStatus: "skipped", closedTargets: 0, state: nextState, lastError: nextState.lastError } };
-        }
-        if (requestedLeaseId && current.activeLeaseId !== requestedLeaseId) {
-            const lastError = `Active browser pool lease is ${current.activeLeaseId}, not ${requestedLeaseId}`;
-            const nextState = stripUndefined({ ...current, lastUsedAt, lastError });
-            return { state: nextState, result: { released: false, cleanupStatus: current.cleanupStatus ?? "not-attempted", closedTargets: 0, state: nextState, lastError } };
-        }
-        let cleanup = { ok: false, status: "skipped", closedTargets: 0, reason: "Browser process is not reachable" };
-        let nextLifecycleState = "ready";
-        if (!current.pid || !(await isPidAlive(current.pid))) {
-            cleanup = { ok: false, status: "skipped", closedTargets: 0, reason: current.pid ? `Recorded browser pid ${current.pid} is not alive` : "Browser pool has no recorded pid" };
-            nextLifecycleState = "stale";
-        }
-        else if (!current.cdpUrl) {
-            cleanup = { ok: false, status: "skipped", closedTargets: 0, reason: "Browser pool has no recorded CDP URL" };
-            nextLifecycleState = "stale";
-        }
-        else {
-            cleanup = await cleanupCdp(current.cdpUrl, { timeoutMs: cdpTimeoutMs });
-            if (!cleanup.ok && cleanup.status === "failed")
-                nextLifecycleState = "dirty";
-        }
-        const lastError = cleanup.ok ? undefined : cleanup.reason;
-        const nextState = stripUndefined({
-            ...current,
-            state: nextLifecycleState,
-            activeLeaseId: undefined,
-            activeLeaseCount: 0,
-            holder: undefined,
-            lastUsedAt,
-            idleExpiresAt: nextLifecycleState === "ready" ? idleExpiresAt : undefined,
-            cleanupStatus: cleanup.status,
-            lastError,
-        });
-        return {
-            state: nextState,
-            result: { released: true, cleanupStatus: cleanup.status, closedTargets: cleanup.closedTargets, state: nextState, lastError },
-        };
-    }, options.lockOptions);
-}
-export async function reapIdleBrowserPool(paths, identity, options = {}) {
-    const now = options.now ?? (() => new Date());
-    const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
-    const terminateBrowserProcessTree = options.terminateBrowserProcessTree ?? defaultTerminateBrowserProcessTree;
-    const removeStaleFiles = options.removeStaleFiles ?? removeDefaultStaleBrowserFiles;
-    const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
-    return mutateBrowserPoolState(paths, { ...identity, onMissing: "empty", onMalformed: "empty" }, "reap", async (current) => {
-        const reapedAt = now();
-        const lastUsedAt = reapedAt.toISOString();
-        const activeLeaseCount = current.activeLeaseId ? Math.max(1, current.activeLeaseCount ?? 1) : current.activeLeaseCount ?? 0;
-        if (current.state === "empty" || (!current.pid && !current.cdpUrl && !current.userDataDir)) {
-            const reason = "Browser pool has no recorded browser to reap";
-            const nextState = stripUndefined({ ...current, activeLeaseCount: 0, cleanupStatus: "skipped", lastError: reason });
-            return { state: nextState, result: skippedReapResult(nextState, reason) };
-        }
-        if (current.activeLeaseId || activeLeaseCount > 0 || current.state === "leased") {
-            const reason = current.activeLeaseId ? `Browser pool has active lease ${current.activeLeaseId}` : "Browser pool has active leases";
-            const nextState = stripUndefined({ ...current, cleanupStatus: "skipped", lastError: reason });
-            return { state: nextState, result: skippedReapResult(nextState, reason) };
-        }
-        const idleReason = browserPoolReapEligibilityReason(current, reapedAt, idleTimeoutMs);
-        if (!idleReason) {
-            const reason = "Browser pool is not idle long enough to reap";
-            const nextState = stripUndefined({ ...current, cleanupStatus: "skipped", lastError: reason });
-            return { state: nextState, result: skippedReapResult(nextState, reason) };
-        }
-        let terminatedProcessTrees = 0;
-        let lastError;
-        if (current.pid && await isPidAlive(current.pid)) {
-            const termination = await terminateBrowserProcessTree(current);
-            terminatedProcessTrees = termination.terminatedProcessTrees;
-            if (!termination.ok) {
-                lastError = termination.reason ?? `Failed to terminate browser process tree for pid ${current.pid}`;
-                const dirtyState = stripUndefined({ ...current, state: "dirty", cleanupStatus: "failed", lastError });
-                return {
-                    state: dirtyState,
-                    result: {
-                        reaped: false,
-                        eligible: true,
-                        reason: idleReason,
-                        affectedLeases: 0,
-                        affectedBrowserPools: 1,
-                        terminatedProcessTrees,
-                        staleStateFiles: 0,
-                        cleanupStatus: "failed",
-                        state: dirtyState,
-                        lastError,
-                    },
-                };
-            }
-        }
-        const staleStateFiles = await removeStaleFiles(current);
-        const nextState = stripUndefined({
-            workerId: current.workerId,
-            poolId: current.poolId,
-            maxBrowserProcesses: current.maxBrowserProcesses,
-            activeLeaseCount: 0,
-            lastUsedAt,
-            state: "empty",
-            cleanupStatus: "success",
-        });
-        return {
-            state: nextState,
-            result: {
-                reaped: true,
-                eligible: true,
-                reason: idleReason,
-                affectedLeases: 0,
-                affectedBrowserPools: 1,
-                terminatedProcessTrees,
-                staleStateFiles,
-                cleanupStatus: "success",
-                state: nextState,
-            },
-        };
-    }, options.lockOptions);
-}
-export function normalizeBrowserPoolState(value, identity) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        throw new BrowserPoolStateError("Browser pool state must be a JSON object");
-    const record = value;
-    const workerId = readRequiredString(record, "workerId");
-    const poolId = readRequiredString(record, "poolId");
-    if (workerId !== identity.workerId)
-        throw new BrowserPoolStateError(`Browser pool state worker id mismatch: expected ${identity.workerId}, got ${workerId}`);
-    if (poolId !== identity.poolId)
-        throw new BrowserPoolStateError(`Browser pool state pool id mismatch: expected ${identity.poolId}, got ${poolId}`);
-    const state = readLifecycleState(record.state);
-    const maxBrowserProcesses = readPositiveInteger(record.maxBrowserProcesses, "maxBrowserProcesses");
-    return stripUndefined({
-        workerId,
-        poolId,
-        maxBrowserProcesses,
-        pid: readOptionalPositiveInteger(record.pid, "pid"),
-        processGroupId: readOptionalPositiveInteger(record.processGroupId, "processGroupId"),
-        cdpPort: readOptionalPositiveInteger(record.cdpPort, "cdpPort"),
-        cdpUrl: readOptionalString(record.cdpUrl, "cdpUrl"),
-        userDataDir: readOptionalString(record.userDataDir, "userDataDir"),
-        activeLeaseId: readOptionalString(record.activeLeaseId, "activeLeaseId"),
-        activeLeaseCount: readOptionalNonNegativeInteger(record.activeLeaseCount, "activeLeaseCount"),
-        holder: readOptionalString(record.holder, "holder"),
-        lastUsedAt: readOptionalString(record.lastUsedAt, "lastUsedAt"),
-        idleExpiresAt: readOptionalString(record.idleExpiresAt, "idleExpiresAt"),
-        state,
-        cleanupStatus: readOptionalCleanupStatus(record.cleanupStatus),
-        lastError: readOptionalString(record.lastError, "lastError"),
-    });
-}
-function activeLeaseBusyReason(state, requestedLeaseId, now) {
-    if (state.state !== "leased" || !state.activeLeaseId || state.activeLeaseId === requestedLeaseId)
-        return undefined;
-    if (leaseExpired(state.idleExpiresAt, now))
-        return undefined;
-    const holder = state.holder ? ` owned by ${state.holder}` : "";
-    const until = state.idleExpiresAt ? ` until ${state.idleExpiresAt}` : "";
-    return `pool-exhausted: browser pool ${state.poolId} is already leased by ${state.activeLeaseId}${holder}${until}`;
-}
-function skippedReapResult(state, reason) {
-    return {
-        reaped: false,
-        eligible: false,
-        reason,
-        affectedLeases: state.activeLeaseId ? Math.max(1, state.activeLeaseCount ?? 1) : state.activeLeaseCount ?? 0,
-        affectedBrowserPools: 0,
-        terminatedProcessTrees: 0,
-        staleStateFiles: 0,
-        cleanupStatus: "skipped",
-        state,
-        lastError: reason,
-    };
-}
-function browserPoolReapEligibilityReason(state, now, idleTimeoutMs) {
-    if (state.state === "stale" || state.state === "dirty")
-        return `Browser pool is ${state.state}`;
-    if (leaseExpired(state.idleExpiresAt, now))
-        return `Browser pool idle expiry ${state.idleExpiresAt} has passed`;
-    if (!state.lastUsedAt)
-        return undefined;
-    const lastUsedAt = Date.parse(state.lastUsedAt);
-    if (Number.isNaN(lastUsedAt))
-        return undefined;
-    if (lastUsedAt + idleTimeoutMs <= now.getTime())
-        return `Browser pool last used at ${state.lastUsedAt} is older than idle timeout ${idleTimeoutMs}ms`;
-    return undefined;
-}
-async function defaultTerminateBrowserProcessTree(state) {
-    if (!state.pid)
-        return { ok: true, terminatedProcessTrees: 0 };
-    if (!state.userDataDir)
-        return { ok: false, terminatedProcessTrees: 0, reason: `Refusing to terminate browser pid ${state.pid} without a recorded Pibo-managed user-data dir` };
-    if (!defaultIsPidAlive(state.pid))
-        return { ok: true, terminatedProcessTrees: 0 };
-    const targetGroup = state.processGroupId && state.processGroupId > 1 && state.processGroupId === state.pid && state.processGroupId !== process.pid ? state.processGroupId : undefined;
-    const target = targetGroup ? -targetGroup : state.pid;
-    try {
-        process.kill(target, "SIGTERM");
-    }
-    catch (error) {
-        if (!isNodeError(error) || error.code !== "ESRCH")
-            return { ok: false, terminatedProcessTrees: 0, reason: `Failed to signal browser pid ${state.pid}: ${error instanceof Error ? error.message : String(error)}` };
-    }
-    if (await waitForPidExit(state.pid, 1_000))
-        return { ok: true, terminatedProcessTrees: 1 };
-    try {
-        process.kill(target, "SIGKILL");
-    }
-    catch (error) {
-        if (!isNodeError(error) || error.code !== "ESRCH")
-            return { ok: false, terminatedProcessTrees: 0, reason: `Failed to kill browser pid ${state.pid}: ${error instanceof Error ? error.message : String(error)}` };
-    }
-    if (await waitForPidExit(state.pid, 1_000))
-        return { ok: true, terminatedProcessTrees: 1 };
-    return { ok: false, terminatedProcessTrees: 0, reason: `Browser pid ${state.pid} did not exit after TERM/KILL` };
-}
-async function removeDefaultStaleBrowserFiles(state) {
-    if (!state.userDataDir)
-        return 0;
-    let removed = 0;
-    for (const fileName of ["DevToolsActivePort", "SingletonLock", "SingletonCookie", "SingletonSocket"]) {
-        const path = join(state.userDataDir, fileName);
-        try {
-            await access(path);
-        }
-        catch {
-            continue;
-        }
-        await rm(path, { force: true });
-        removed += 1;
-    }
-    return removed;
-}
-async function waitForPidExit(pid, timeoutMs) {
-    const startedAt = Date.now();
-    while (Date.now() - startedAt <= timeoutMs) {
-        if (!defaultIsPidAlive(pid))
-            return true;
-        await delay(50);
-    }
-    return !defaultIsPidAlive(pid);
-}
-function leaseExpired(idleExpiresAt, now) {
-    if (!idleExpiresAt)
-        return false;
-    const expiresAt = Date.parse(idleExpiresAt);
-    if (Number.isNaN(expiresAt))
-        return false;
-    return expiresAt <= now.getTime();
-}
-async function evaluateRecordedBrowser(state, isPidAlive, checkCdpHealth, cdpTimeoutMs) {
-    if (state.state === "dirty")
-        return { ok: false, reason: state.lastError ?? "Browser pool state is dirty" };
-    if (!state.pid)
-        return { ok: false, reason: "Browser pool has no recorded pid" };
-    if (!state.cdpUrl)
-        return { ok: false, reason: "Browser pool has no recorded CDP URL" };
-    if (!(await isPidAlive(state.pid)))
-        return { ok: false, reason: `Recorded browser pid ${state.pid} is not alive` };
-    const health = await checkCdpHealth(state.cdpUrl, { timeoutMs: cdpTimeoutMs });
-    if (!health.ok)
-        return { ok: false, reason: health.reason ?? "Recorded browser CDP endpoint is unhealthy" };
-    return { ok: true };
-}
-function defaultIsPidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return isNodeError(error) && error.code === "EPERM";
-    }
-}
-function trimTrailingSlash(value) {
-    return value.replace(/\/+$/, "");
-}
-async function removeStaleLock(lockPath, staleMs) {
-    if (staleMs <= 0)
-        return;
-    try {
-        const raw = await readFile(lockPath, "utf8");
-        const parsed = JSON.parse(raw);
-        if (typeof parsed.createdAt !== "string")
-            return;
-        const createdAt = Date.parse(parsed.createdAt);
-        if (Number.isNaN(createdAt))
-            return;
-        if (Date.now() - createdAt > staleMs)
-            await rm(lockPath, { force: true });
-    }
-    catch {
-        // A corrupt or concurrently removed lock should not make acquisition unsafe.
-    }
-}
-function safePathSegment(value) {
-    return value.replace(/[^a-zA-Z0-9._-]/g, "_");
-}
-function stripUndefined(record) {
-    return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
-}
-function readRequiredString(record, key) {
-    const value = record[key];
-    if (typeof value !== "string" || value.length === 0)
-        throw new BrowserPoolStateError(`Browser pool state field ${key} must be a non-empty string`);
-    return value;
-}
-function readOptionalString(value, key) {
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== "string" || value.length === 0)
-        throw new BrowserPoolStateError(`Browser pool state field ${key} must be a non-empty string when present`);
-    return value;
-}
-function readPositiveInteger(value, key) {
-    if (!Number.isInteger(value) || typeof value !== "number" || value < 1)
-        throw new BrowserPoolStateError(`Browser pool state field ${key} must be a positive integer`);
-    return value;
-}
-function readOptionalPositiveInteger(value, key) {
-    if (value === undefined)
-        return undefined;
-    return readPositiveInteger(value, key);
-}
-function readOptionalNonNegativeInteger(value, key) {
-    if (value === undefined)
-        return undefined;
-    if (!Number.isInteger(value) || typeof value !== "number" || value < 0)
-        throw new BrowserPoolStateError(`Browser pool state field ${key} must be a non-negative integer when present`);
-    return value;
-}
-function readLifecycleState(value) {
-    if (value === "empty" || value === "ready" || value === "leased" || value === "stale" || value === "dirty")
-        return value;
-    throw new BrowserPoolStateError("Browser pool state field state is invalid");
-}
-function readOptionalCleanupStatus(value) {
-    if (value === undefined)
-        return undefined;
-    if (value === "not-attempted" || value === "success" || value === "failed" || value === "skipped")
-        return value;
-    throw new BrowserPoolStateError("Browser pool state field cleanupStatus is invalid");
-}
-async function fetchWithTimeout(url, timeoutMs) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        return await fetch(url, { signal: controller.signal });
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-function isNodeError(error) {
-    return error instanceof Error && "code" in error;
-}
-function toBrowserPoolStateError(error) {
-    if (error instanceof BrowserPoolStateError)
-        return error;
-    return new BrowserPoolStateError(error instanceof Error ? error.message : String(error));
-}
-function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}