| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146 |
- """Launch, track and stop the Chromium processes ``browser_exec`` drives.
- One browser per launcher key (the session layer's cache key, or ``profile:<dir>`` for a persistent
- profile shared by every key). Chromium picks its own DevTools port (``--remote-debugging-port=0``)
- and writes it to ``<user-data-dir>/DevToolsActivePort``; the CDP URL comes from that file, so there
- is no port race. Every owned launch leaves a record in a private (0700) launcher state dir so a later
- Hermes process can reap the Chromium of an owner that crashed, after proving the pid is still that browser:
- a throwaway profile's in its home (``<HERMES_HOME>/cache/browser/chromium-records``), a persistent profile's
- in that profile's own dir under :func:`_shared_profiles_root` (per OS user: every home pinning the dir shares
- it). A shared-profile Chromium other Hermes processes attached to is stopped only by its last holder
- (``tools/browser_launcher_holders.py``).
- Stop is always parent-first (``ProcessRegistry._terminate_host_pid``): Chromium reaps its own
- zygotes and renderers on SIGTERM, and killing a zygote first turns a clean exit into a crash dump.
- """
- from __future__ import annotations
- import contextlib
- import hashlib
- import json
- import logging
- import os
- import re
- import shutil
- import socket
- import stat
- import subprocess
- import sys
- import threading
- import time
- from dataclasses import dataclass
- from pathlib import Path
- from typing import Any, Callable, Optional
- logger = logging.getLogger(__name__)
- # THE Chromium startup flags for a host where its sandbox cannot work. The Bot Desktop dock's Browser
- # icon (same binary, same profile) uses the same list (``tools.bot_desktop.browser.dock_argv``), or the
- # human's click dies while the agent's launch works.
- CHROMIUM_SANDBOX_BYPASS_ARGS: tuple[str, ...] = ("--no-sandbox", "--disable-dev-shm-usage")
- # Base flags, each kept for a reason (the minimum for an unattended, disposable automation browser):
- # --no-first-run / --no-default-browser-check no welcome tab or default-browser bar on a fresh profile
- # --disable-background-networking no field-trial / safe-browsing / update pings per launch
- # --disable-component-update no component downloads into a throwaway profile
- # --disable-default-apps / --disable-sync nothing installed or signed in behind the agent's back
- # --disable-features=Translate no translate bubble covering the page
- _BASE_FLAGS: tuple[str, ...] = (
- "--no-first-run", "--no-default-browser-check", "--disable-background-networking",
- "--disable-component-update", "--disable-default-apps", "--disable-sync", "--disable-features=Translate",
- )
- # Only for the launcher-resolved packaged Chromium: a keyring unlock prompt (Linux desktops) or the macOS
- # keychain dialog would block an unattended launch. Never for a real or shared profile, whose cookies are
- # encrypted with the OS store (``--password-store=basic`` would sign the copy out).
- _PACKAGED_ONLY_FLAGS: tuple[str, ...] = ("--password-store=basic",)
- _MACOS_PACKAGED_ONLY_FLAGS: tuple[str, ...] = ("--use-mock-keychain",)
- _DEVTOOLS_FILE = "DevToolsActivePort"
- _LAUNCH_LOG = "hermes-chromium.log"
- _MIN_FIRST_LAUNCH_TIMEOUT_S = 120
- _UNRESPONSIVE_WAIT_S = 10 # how long a live browser whose endpoint went silent (paused, swapped out) is waited for
- _POLL_INTERVAL_S = 0.1
- _STDERR_TAIL_CHARS = 1500
- @dataclass
- class LaunchedBrowser:
- """A Chromium this process launched (``owned``) or attached to (a running instance on a shared
- profile, never killed by Hermes)."""
- key: str
- pid: Optional[int]
- start_time: Optional[int]
- cdp_url: str
- http_url: str
- user_data_dir: str
- owned: bool
- ephemeral: bool
- home_key: str
- # File name of the launch record its leases are keyed by, when that is not this process's own name for
- # it: an attached browser keeps its launcher's record, whichever PID namespace wrote it.
- record_name: Optional[str] = None
- # Held from an environment this process cannot verify (another PID namespace: a container's browser seen
- # from the host, or the reverse): ``pid`` is that namespace's number, names nobody here and is never
- # signalled; liveness is its DevTools endpoint.
- foreign: bool = False
- _browsers: dict[str, LaunchedBrowser] = {}
- _procs: dict[str, subprocess.Popen] = {}
- _launching: dict[int, LaunchedBrowser] = {} # pid -> a spawned Chromium still in its readiness wait
- _key_locks: dict[str, threading.Lock] = {}
- _lock = threading.RLock()
- _autoinstall_attempted = False
- # Profile homes (``hermes_home_key``) this process launched or attached a browser for: the reaper reads
- # each one's records, since one process serves many profiles.
- _served_homes: set[str] = set()
- # ── Host facts ───────────────────────────────────────────────────────────────────────────────────────
- def apparmor_restricts_unprivileged_userns() -> bool:
- """Ubuntu 23.10+ default: unprivileged user namespaces are denied, so a Chromium whose
- ``chrome_sandbox`` helper is not setuid (Playwright's bundle) dies with 'No usable sandbox'."""
- try:
- with open("/proc/sys/kernel/apparmor_restrict_unprivileged_userns", encoding="utf-8") as f:
- return f.read().strip() == "1"
- except OSError:
- return False
- def running_in_docker() -> bool:
- """Best-effort detection of whether we're inside a Docker container."""
- if os.path.exists("/.dockerenv"):
- return True
- try:
- with open("/proc/1/cgroup", "rt", encoding="utf-8") as fp:
- return "docker" in fp.read()
- except OSError:
- return False
- def needs_chromium_sandbox_bypass() -> bool:
- """True when Chromium needs --no-sandbox to start reliably (root, Docker, AppArmor userns)."""
- if hasattr(os, "geteuid") and os.geteuid() == 0:
- return True
- if running_in_docker():
- return True
- return apparmor_restricts_unprivileged_userns()
- def _chromium_missing_hint() -> str:
- from hermes_cli.browser_runtime import chromium_missing_hint
- return chromium_missing_hint()
- def _resolve_executable() -> Optional[str]:
- from hermes_cli.browser_runtime import chromium_executable
- exe = chromium_executable()
- if not exe:
- return None
- if os.path.isfile(exe):
- return exe
- from hermes_platform.resolver import locate_command
- found = locate_command(exe).command # a bare command name pinned in browser.executable_path
- return found[0] if found else None
- def _explicit_executable_configured(chromium_executable) -> bool:
- """An operator-pinned browser binary (even a missing one) is their choice: never download over it."""
- return chromium_executable(allow_override=True) != chromium_executable(allow_override=False)
- def _maybe_autoinstall_chromium() -> bool:
- """One-shot ``pm.ensure("chromium")`` (a failed ~170 MB download must not retry per call). Docker
- supplies the binary, Termux has no PM Chromium, and an explicit executable is the user's choice."""
- global _autoinstall_attempted
- if _autoinstall_attempted:
- return False
- _autoinstall_attempted = True
- from hermes_cli.browser_runtime import chromium_executable
- from hermes_constants import is_termux
- if running_in_docker() or is_termux() or _explicit_executable_configured(chromium_executable):
- return False
- from pm import InstallError, ensure, lazy_installs_allowed
- if not lazy_installs_allowed():
- return False
- logger.info("browser: installing PM's pinned Chromium")
- try:
- ensure("chromium")
- except (InstallError, OSError) as exc:
- logger.warning("browser: Chromium auto-install failed: %s", exc)
- return False
- return True
- def chromium_ready() -> tuple[bool, str]:
- """``(True, "")`` when a Chromium is on disk (after at most one PM auto-install per process), else
- ``(False, actionable hint)``."""
- if _resolve_executable():
- return True, ""
- if _maybe_autoinstall_chromium() and _resolve_executable():
- return True, ""
- return False, _chromium_missing_hint()
- # ── Launch ───────────────────────────────────────────────────────────────────────────────────────────
- def _default_user_data_dir(key: str, home_key: str) -> str:
- """Per process too: two Hermes processes on one profile use the same keys (``browser-exec-default``,
- named sessions), and each launch wipes its throwaway dir first. The name carries the owner's pid and
- start time: a process that dies before its launch record exists leaves the dir to the reaper
- (:func:`_reclaim_throwaway_dirs`)."""
- from tools.browser_launcher_holders import ns_tag
- digest = hashlib.sha256(f"{home_key}\0{key}".encode()).hexdigest()[:16]
- pid = os.getpid()
- started = _start_time(pid)
- owner = f"{pid}-{started}" if started is not None else str(pid)
- return str(_ephemeral_root(home_key) / f"{digest}-{owner}{ns_tag()}")
- def _launch_timeout(timeout: Optional[float]) -> float:
- if timeout is not None:
- return float(timeout)
- from tools.browser_session_cloud import command_timeout
- return float(max(command_timeout(), _MIN_FIRST_LAUNCH_TIMEOUT_S))
- def _has_display(env: dict) -> bool:
- return bool(env.get("DISPLAY") or env.get("WAYLAND_DISPLAY"))
- def _resolve_headed(headed: Optional[bool], env: dict) -> bool:
- """Headless unless ``browser.headed``; a display-less Linux host stays headless (a headed launch
- would die there). Windows obeys the same rule: headless unless the user opted in (#64867)."""
- if headed is None:
- from tools.browser_session_cloud import is_headed_mode
- headed = is_headed_mode()
- if not headed:
- return False
- return _has_display(env) or not sys.platform.startswith("linux")
- def _configured_chromium_args() -> list[str]:
- from tools.browser_session_cloud import chromium_args
- return chromium_args()
- def build_chromium_argv(executable: str, user_data_dir: str, *, packaged: bool, headed: bool,
- sandbox_bypass: bool, extra_args=()) -> list[str]:
- """The launch argv (pure in its inputs + host sandbox facts + ``browser.chromium_args``).
- ``sandbox_bypass`` lets the host policy (root, Docker, AppArmor userns) add
- ``CHROMIUM_SANDBOX_BYPASS_ARGS``; it is False for the user's own browser binary, which is never
- started without its sandbox."""
- argv = [executable, "--remote-debugging-port=0", f"--user-data-dir={user_data_dir}", *_BASE_FLAGS]
- if packaged:
- argv += _PACKAGED_ONLY_FLAGS
- if sys.platform == "darwin":
- argv += _MACOS_PACKAGED_ONLY_FLAGS
- if not headed:
- argv.append("--headless=new")
- configured = _configured_chromium_args()
- if sandbox_bypass and needs_chromium_sandbox_bypass():
- argv += [flag for flag in CHROMIUM_SANDBOX_BYPASS_ARGS if flag not in configured]
- argv += [str(a) for a in extra_args]
- argv += configured
- argv.append("about:blank")
- return argv
- def _spawn_kwargs() -> dict[str, Any]:
- if os.name == "nt":
- from hermes_cli._subprocess_compat import windows_hide_flags
- return {"creationflags": windows_hide_flags() | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)}
- # detached-spawn: ok — a shared-profile Chromium outlives its launcher for its other holders (browser_launcher_holders); a crashed owner's throwaway one is reaped from its launch record by the next Hermes
- return {"start_new_session": True}
- def _read_devtools_file(user_data_dir: str) -> Optional[tuple[int, str]]:
- """``(port, "/devtools/browser/<id>")`` once Chromium wrote both lines, else None."""
- try:
- with open(os.path.join(user_data_dir, _DEVTOOLS_FILE), encoding="utf-8-sig") as fh:
- port, path = fh.readline().strip(), fh.readline().strip()
- except OSError:
- return None
- if not port.isdigit() or not path.startswith("/devtools/browser/"):
- return None
- return int(port), path
- def _log_tail(user_data_dir: str) -> str:
- try:
- raw = Path(user_data_dir, _LAUNCH_LOG).read_bytes()[-_STDERR_TAIL_CHARS:]
- except OSError:
- return ""
- return raw.decode("utf-8", errors="replace").strip()
- def _wait_for_devtools(proc: subprocess.Popen, user_data_dir: str, deadline: float) -> tuple[Optional[tuple[int, str]], Optional[str]]:
- while True:
- found = _read_devtools_file(user_data_dir)
- if found:
- return found, None
- rc = proc.poll()
- if rc is not None:
- tail = _log_tail(user_data_dir)
- hint = (" Chromium's sandbox could not start; add --no-sandbox to browser.chromium_args."
- if "sandbox" in tail.lower() else "")
- return None, f"Chromium exited with code {rc} during startup.{hint}" + (f"\n{tail}" if tail else "")
- if time.monotonic() >= deadline:
- return None, "Chromium did not expose a DevTools endpoint in time."
- time.sleep(_POLL_INTERVAL_S)
- def _singleton_pid(user_data_dir: str) -> Optional[int]:
- """Pid of the Chromium holding ``user_data_dir``: the ``SingletonLock`` symlink (POSIX), else (Windows
- has no symlink, only a locked ``lockfile``) the browser process whose argv names the dir."""
- owner = _singleton_owner(user_data_dir)
- if owner is None:
- return _pid_naming_dir(user_data_dir) if os.name == "nt" else None
- return owner[1]
- def _singleton_owner(user_data_dir: str) -> Optional[tuple[str, int]]:
- """``(hostname, pid)`` Chromium wrote into ``user_data_dir``'s ``SingletonLock`` symlink (POSIX), else None."""
- try:
- target = os.readlink(os.path.join(user_data_dir, "SingletonLock"))
- except OSError:
- return None
- host, _, pid_text = target.rpartition("-")
- return (host, int(pid_text)) if pid_text.isdigit() else None
- def _foreign_holder(user_data_dir: str) -> Optional[int]:
- """The ``SingletonLock`` pid of a Chromium on ``user_data_dir`` that runs in an environment this process cannot
- verify, else None. Foreign: the lock is not a live process here whose argv names the dir, and it was written
- under another hostname (another host or container; Chromium too refuses such a lock) or names the browser
- of a launch record from another PID namespace. A lock of this hostname with no such record is stale (this
- environment's crashed browser): Chromium itself takes it over, and so does a launch."""
- owner = _singleton_owner(user_data_dir)
- if owner is None:
- return None
- host, pid = owner
- if _pid_alive(pid) and _cmdline_names_dir(pid, user_data_dir):
- return None
- if host != socket.gethostname() or _foreign_record_names(user_data_dir, pid):
- return pid
- return None
- def _foreign_record_names(user_data_dir: str, pid: int) -> bool:
- """A launch record from another PID namespace names ``pid`` as shared profile ``user_data_dir``'s browser: the one
- serving the profile's DevTools endpoint now, or one not yet up there (its record has no endpoint). An earlier
- launch there that reached another endpoint is not that browser, whatever pid number it had."""
- from tools.browser_launcher_holders import same_namespace
- state = _shared_state_dir(user_data_dir)
- if state is None:
- return False
- found = _read_devtools_file(user_data_dir)
- for name in _record_names(state, user_data_dir, pid):
- record = _load_record(state / name)
- if (record is not None and record.get("pid") == pid and not same_namespace(record)
- and _same_profile(record.get("user_data_dir"), user_data_dir)
- and record.get("devtools") in (None, found and found[1])):
- return True
- return False
- def _record_names(records: Path, user_data_dir: str, pid) -> list[str]:
- """Names of the launch records in ``records`` for profile ``user_data_dir``'s browser ``pid``, whichever PID
- namespace wrote them (each carries its writer's ``ns_tag``), sorted."""
- stem = f"{_profile_digest(user_data_dir)[:16]}-{pid}"
- pattern = re.compile(rf"^{re.escape(stem)}(-n[0-9a-f]{{12}})?\.json$")
- return sorted(p.name for p in records.glob(f"{stem}*.json") if pattern.match(p.name))
- def _pid_naming_dir(user_data_dir: str) -> Optional[int]:
- """The browser (not a ``--type=`` helper) process whose argv carries ``--user-data-dir=<dir>``."""
- import psutil
- for proc in psutil.process_iter(["pid"]):
- try:
- argv = proc.cmdline()
- except (psutil.Error, OSError):
- continue
- if not any(tok.startswith("--type=") for tok in argv) and _cmdline_names_dir(proc.pid, user_data_dir):
- return proc.pid
- return None
- def _browser_running_on(user_data_dir: str) -> bool:
- """A live Chromium still uses ``user_data_dir`` (by argv: a ``SingletonLock`` outlives a crashed browser)."""
- return _pid_naming_dir(user_data_dir) is not None
- def _devtools_endpoint_live(port: int, path: str) -> bool:
- """The port answers ``/json/version`` with the browser id the DevToolsActivePort file names (the file
- outlives a crashed Chromium and its port can be recycled by another CDP server)."""
- try:
- import requests
- from agent.proxy_bypass import loopback_request_kwargs
- url = f"http://127.0.0.1:{port}/json/version"
- ws = str(requests.get(url, timeout=2, **loopback_request_kwargs(url)).json().get("webSocketDebuggerUrl") or "")
- except Exception: # health: allow BLE001 -- any probe failure means "not a live browser on this port"
- return False
- return ws.endswith(path)
- def running_instance(user_data_dir: str) -> Optional[tuple[int, str, int]]:
- """``(port, browser_path, pid)`` of a Chromium already running on ``user_data_dir`` (a human-started
- Bot Desktop dock instance, a surviving real-profile browser), else None. A second launch on that dir
- would be forwarded into it by Chromium's singleton and exit without a DevTools endpoint."""
- pid = _singleton_pid(user_data_dir)
- found = _read_devtools_file(user_data_dir)
- if pid is None or found is None or not _pid_alive(pid):
- return None
- port, path = found
- return (port, path, pid) if _devtools_endpoint_live(port, path) else None
- def _pid_alive(pid: int) -> bool:
- from gateway.status import _pid_exists
- return pid > 0 and _pid_exists(pid)
- def _start_time(pid: int) -> Optional[int]:
- from gateway.status import get_process_start_time
- return get_process_start_time(pid)
- def _make_browser(key: str, port: int, path: str, *, pid, start_time, user_data_dir: str, owned: bool,
- ephemeral: bool, home_key: str) -> LaunchedBrowser:
- return LaunchedBrowser(key=key, pid=pid, start_time=start_time, cdp_url=f"ws://127.0.0.1:{port}{path}",
- http_url=f"http://127.0.0.1:{port}", user_data_dir=user_data_dir, owned=owned,
- ephemeral=ephemeral, home_key=home_key)
- def _prepare_dir(user_data_dir: str, ephemeral: bool) -> None:
- if ephemeral:
- Path(user_data_dir).parent.mkdir(mode=0o700, parents=True, exist_ok=True) # the private ephemeral root
- shutil.rmtree(user_data_dir, ignore_errors=True) # fresh profile per launch
- os.makedirs(user_data_dir, mode=0o700, exist_ok=True)
- try:
- os.unlink(os.path.join(user_data_dir, _DEVTOOLS_FILE)) # a stale port confuses the readiness poll
- except OSError:
- pass
- def _spawn(argv: list[str], env: dict, user_data_dir: str) -> subprocess.Popen:
- log_path = os.path.join(user_data_dir, _LAUNCH_LOG)
- with open(log_path, "wb") as log:
- return subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=log, stderr=log, env=env,
- **_spawn_kwargs())
- def _attach_running(key: str, user_data_dir: str, home_key: str) -> Optional[LaunchedBrowser]:
- """The live Chromium already on shared profile ``user_data_dir``, leased (caller holds its lock)."""
- running = running_instance(user_data_dir)
- if running is None:
- return None
- port, path, pid = running
- logger.info("browser: attaching to the Chromium already running on %s (pid %s)", user_data_dir, pid)
- browser = _make_browser(key, port, path, pid=pid, start_time=_start_time(pid), user_data_dir=user_data_dir,
- owned=False, ephemeral=False, home_key=home_key)
- records = _state_dir(browser)
- if records is not None:
- from tools import browser_launcher_holders as holders
- _bind_launch_record(records, browser)
- _adopt_record(browser)
- holders.write_lease(_record_path(browser), browser) # its launcher's exit must not stop it under us
- return browser
- def _bind_launch_record(records: Path, browser: LaunchedBrowser) -> None:
- """Lease ``browser`` under the launch record that describes THIS launch of it (:func:`_record_is`), written in
- ANY PID namespace: its launcher (a container gateway a host CLI attached to) finds its holders only there.
- Records of earlier containers and boots are kept, so the pid number alone can name another browser's record.
- This namespace's record wins; with none (a browser a human started) the lease goes under this namespace's
- name. A browser of another environment takes its record's start time: its full identity from then on."""
- own = _record_name(browser)
- names = sorted(_record_names(records, browser.user_data_dir, browser.pid), key=lambda name: name != own)
- for name in names:
- record = _load_record(records / name)
- if record is not None and _record_is(record, browser):
- browser.record_name = name
- if browser.foreign:
- browser.start_time = record.get("start_time")
- return
- def _attach_foreign(key: str, user_data_dir: str, home_key: str, pid: int) -> Optional[LaunchedBrowser]:
- """The Chromium another environment holds on ``user_data_dir``, leased, when its DevTools endpoint answers here
- (caller holds the profile's lock); None when it does not. Never adopted: its record is not ours to take."""
- found = _read_devtools_file(user_data_dir)
- if found is None or not _devtools_endpoint_live(*found):
- return None
- logger.info("browser: attaching to the Chromium another environment runs on %s (its pid %s there)",
- user_data_dir, pid)
- browser = _make_browser(key, found[0], found[1], pid=pid, start_time=None, user_data_dir=user_data_dir,
- owned=False, ephemeral=False, home_key=home_key)
- browser.foreign = True
- records = _state_dir(browser)
- if records is not None:
- from tools import browser_launcher_holders as holders
- _bind_launch_record(records, browser)
- holders.write_lease(_record_path(browser), browser) # its launcher's exit must not stop it under us
- return browser
- def _live_local_holder(user_data_dir: str) -> Optional[int]:
- """Pid of the live Chromium of this environment holding ``user_data_dir`` (its ``SingletonLock`` names a live
- process whose argv carries the dir), else None: no browser, or a stale lock a launch may take over."""
- pid = _singleton_pid(user_data_dir)
- return pid if pid is not None and _pid_alive(pid) and _cmdline_names_dir(pid, user_data_dir) else None
- def _attach_local(key: str, user_data_dir: str, home_key: str,
- timeout: Optional[float]) -> tuple[Optional[LaunchedBrowser], Optional[str]]:
- """Attach to this environment's live Chromium on ``user_data_dir``; ``(None, None)`` when none holds it (a
- launch may start one). A live holder whose endpoint does not answer (paused, hung) is waited for, then
- refused: a launch over it would only wipe its ``DevToolsActivePort`` and lose it for every later attach."""
- attached = _attach_running(key, user_data_dir, home_key)
- pid = _live_local_holder(user_data_dir) if attached is None else None
- if pid is None:
- return attached, None
- deadline = time.monotonic() + min(_UNRESPONSIVE_WAIT_S, _launch_timeout(timeout))
- delay = 0.25
- while attached is None and _live_local_holder(user_data_dir) == pid:
- if time.monotonic() >= deadline:
- return None, (f"The browser profile {user_data_dir} is in use by Chromium pid {pid}, which is not "
- "responding on its DevTools endpoint (paused, hung, or started without remote debugging). "
- "Hermes will not start a second browser on it; try again once it responds, or stop it.")
- time.sleep(min(delay, max(0.0, deadline - time.monotonic())))
- delay *= 2
- attached = _attach_running(key, user_data_dir, home_key)
- return attached, None
- def _foreign_unreachable(user_data_dir: str) -> str:
- return (f"The browser profile {user_data_dir} is in use by a Chromium in another environment (a container or "
- "the host) that this process can neither reach nor verify, so Hermes will not start a second browser "
- "on it. Stop that browser, or set browser.user_data_dir to another directory for this environment; if "
- f"no browser runs there any more, delete {os.path.join(user_data_dir, 'SingletonLock')}.")
- def _start_shared(key: str, executable: str, udd: str, home_key: str, prepare,
- **launch) -> tuple[Optional[LaunchedBrowser], Optional[str]]:
- """Attach to, or launch, shared profile ``udd``'s one Chromium as ONE step under the profile's cross-process
- lock: of two processes starting it at once the later waits, then attaches (a second launch would wipe the
- first's DevToolsActivePort and lose Chromium's singleton), and an owner's stop cannot fall between the live
- probe and the lease. A first launch holds the lock for its whole readiness wait; the reaper skips a busy
- profile instead of waiting (:func:`_reap_shared_profiles`). A browser another environment holds is attached
- through its endpoint, or refused; never launched over."""
- from tools import browser_launcher_holders as holders
- state = _shared_state_dir(udd)
- with holders.records_lock(state) if state is not None else contextlib.nullcontext():
- foreign = _foreign_holder(udd)
- if foreign is not None:
- attached = _attach_foreign(key, udd, home_key, foreign)
- if attached is None:
- return None, _foreign_unreachable(udd)
- else:
- attached, refused = _attach_local(key, udd, home_key, launch.get("timeout"))
- if refused:
- return None, refused
- if attached is None:
- failure = prepare() if prepare is not None else None
- if failure:
- return None, failure
- return _launch_owned(key, executable, udd, ephemeral=False, home_key=home_key, **launch)
- with _lock: # registered under the lock too: another key's stop must see this key as its heir
- _browsers[key] = attached
- return attached, None
- def launch_chromium(key: str, *, executable: Optional[str] = None, user_data_dir: Optional[str] = None,
- ephemeral: bool = True, headed: Optional[bool] = None, extra_args=(),
- env: Optional[dict] = None, timeout: Optional[float] = None, sandbox_bypass: bool = True,
- prepare: Optional[Callable[[], Optional[str]]] = None,
- ) -> tuple[Optional[LaunchedBrowser], Optional[str]]:
- """Start (or reuse) the Chromium for ``key``; ``(browser, None)`` or ``(None, error)``.
- ``executable=None`` resolves the packaged Chromium (``chromium_ready``); an explicit executable (the
- Bot Desktop's, the user's real browser) is used as given. ``user_data_dir=None`` is a fresh
- ephemeral profile under ``<HERMES_HOME>/cache/browser/chromium/``; a persistent dir that already has
- a live Chromium on it is ATTACHED (``owned=False``, never killed). ``sandbox_bypass=False`` (the
- user's real browser) never gets the host's sandbox-bypass flags. ``prepare`` (a persistent dir only) runs
- right before a fresh launch, inside the same cross-process step, never when attaching: a profile copy
- written there can neither race another process's copy nor land under a browser that just came up; a
- message it returns is the launch's error, as is."""
- from hermes_constants import hermes_home_key
- # Loaded now, not first at teardown: stopping the browser from an atexit hook must not be this module's
- # first import (Python refuses new atexit registrations during shutdown, orphaning the browser). An
- # attacher needs it too: it is the one that stops a shared browser when it is the last holder.
- import tools.process_registry
- with _key_lock(key): # one launch per key; other keys launch concurrently
- existing = get_browser(key)
- if existing is not None:
- return existing, None
- home_key = hermes_home_key()
- with _lock:
- _served_homes.add(home_key)
- packaged = executable is None
- if packaged:
- ok, hint = chromium_ready()
- if not ok:
- return None, hint
- executable = _resolve_executable()
- udd = user_data_dir or _default_user_data_dir(key, home_key)
- launch = dict(packaged=packaged, headed=headed, extra_args=extra_args, env=env, timeout=timeout,
- sandbox_bypass=sandbox_bypass)
- if ephemeral: # a per-process dir: nobody else starts or attaches to it
- return _launch_owned(key, executable, udd, ephemeral=True, home_key=home_key, **launch)
- return _start_shared(key, executable, udd, home_key, prepare, **launch)
- def _key_lock(key: str) -> threading.Lock:
- with _lock:
- return _key_locks.setdefault(key, threading.Lock())
- def _launch_owned(key: str, executable: str, udd: str, *, ephemeral: bool, packaged: bool, headed,
- extra_args, env, timeout, home_key: str, sandbox_bypass: bool,
- ) -> tuple[Optional[LaunchedBrowser], Optional[str]]:
- if env is None:
- from tools.browser_session import build_browser_env
- env = build_browser_env()
- try:
- _prepare_dir(udd, ephemeral)
- except OSError as exc:
- return None, f"Could not create the browser profile directory {udd}: {exc}"
- argv = build_chromium_argv(executable, udd, packaged=packaged, headed=_resolve_headed(headed, env),
- sandbox_bypass=sandbox_bypass, extra_args=extra_args)
- try:
- proc = _spawn(argv, env, udd)
- except (OSError, subprocess.SubprocessError) as exc:
- return None, f"Failed to launch Chromium ({executable}): {exc}"
- start_time = _start_time(proc.pid)
- starting = _make_browser(key, 0, "", pid=proc.pid, start_time=start_time, user_data_dir=udd, owned=True,
- ephemeral=ephemeral, home_key=home_key)
- # Recorded before the readiness wait (a first launch may take 120 s): if this process dies in it, the
- # record is what lets the next reaper stop this Chromium. Tracked as launching so this process's own
- # reaper leaves it alone meanwhile.
- with _lock:
- _launching[proc.pid] = starting
- _write_record(starting)
- try:
- found, err = _wait_for_devtools(proc, udd, time.monotonic() + _launch_timeout(timeout))
- except BaseException: # interrupted (Ctrl-C, shutdown): nobody else knows this browser exists
- _abandon_launch(proc, starting)
- raise
- if found is None:
- _abandon_launch(proc, starting)
- return None, err
- browser = _make_browser(key, found[0], found[1], pid=proc.pid, start_time=start_time, user_data_dir=udd,
- owned=True, ephemeral=ephemeral, home_key=home_key)
- _write_record(browser) # now with its DevTools browser id: how another environment tells this launch apart
- with _lock:
- _launching.pop(proc.pid, None)
- _browsers[key] = browser
- _procs[key] = proc
- logger.info("browser: launched Chromium pid %s for %s (port %s)", proc.pid, key, found[0])
- return browser, None
- def _abandon_launch(proc: subprocess.Popen, starting: LaunchedBrowser) -> None:
- with _lock:
- _launching.pop(proc.pid, None)
- if proc.poll() is None: # one that already exited is reaped by poll(); its pid is no longer ours
- _terminate(proc.pid, starting.start_time, proc)
- _remove_record(starting)
- if starting.ephemeral:
- shutil.rmtree(starting.user_data_dir, ignore_errors=True)
- # ── Lookup / stop ────────────────────────────────────────────────────────────────────────────────────
- def _alive(browser: LaunchedBrowser) -> bool:
- proc = _procs.get(browser.key)
- if proc is not None and browser.owned:
- return proc.poll() is None
- if browser.pid is None:
- return False
- if not _pid_alive(browser.pid):
- return False
- return browser.start_time is None or _start_time(browser.pid) == browser.start_time
- def get_browser(key: str) -> Optional[LaunchedBrowser]:
- """The live browser for ``key``, or None (a dead one is dropped and its leftovers removed)."""
- with _lock:
- browser = _browsers.get(key)
- if browser is None:
- return None
- if not browser.foreign:
- if _alive(browser):
- return browser
- logger.info("browser: Chromium for %s (pid %s) is gone", key, browser.pid)
- _forget(key, browser)
- return None
- if _foreign_alive(browser): # an HTTP probe: never under the process-wide lock
- return browser
- with _lock:
- if _browsers.get(key) is browser:
- logger.info("browser: the Chromium another environment ran for %s is gone", key)
- _forget(key, browser)
- return None
- def _foreign_alive(browser: LaunchedBrowser) -> bool:
- """A browser another environment holds is alive while its profile still names this endpoint and it answers."""
- found = _read_devtools_file(browser.user_data_dir)
- return (found is not None and browser.cdp_url == f"ws://127.0.0.1:{found[0]}{found[1]}"
- and _devtools_endpoint_live(*found))
- def _heir_key(browser: LaunchedBrowser) -> Optional[str]:
- """Another key of this process on the same shared-profile Chromium (one dir reached by two paths, e.g. a
- symlink): it inherits this process's hold, so dropping ``browser``'s key must neither drop the lease nor
- stop the browser."""
- if browser.ephemeral:
- return None
- with _lock:
- return next((k for k, b in _browsers.items() if b is not browser and not b.ephemeral
- and _same_browser(b, browser)), None)
- def _same_browser(a: LaunchedBrowser, b: LaunchedBrowser) -> bool:
- """One launch: same profile (realpath), pid, start time and launch record (whose name carries the PID namespace
- and boot its pid belongs to); a browser of another environment also by the DevTools browser id it serves (two
- containers can give two browsers one pid number, neither with a start time readable here)."""
- return (a.foreign == b.foreign and a.pid == b.pid and a.start_time == b.start_time
- and _record_name(a) == _record_name(b) and _same_profile(a.user_data_dir, b.user_data_dir)
- and (not a.foreign or a.cdp_url == b.cdp_url))
- def _forget(key: str, browser: LaunchedBrowser, *, drop_record: bool = True) -> None:
- proc = None
- heir = _heir_key(browser)
- if _browsers.get(key) is browser: # a replacement registered since is not this browser's to drop
- _browsers.pop(key)
- proc = _procs.pop(key, None)
- if proc is not None and heir is not None:
- _procs.setdefault(heir, proc) # the heir stops (and reaps) it when it is the last one out
- proc = None
- if proc is not None:
- try:
- proc.wait(timeout=0) # reap the zombie
- except subprocess.TimeoutExpired:
- pass
- if not browser.ephemeral and heir is None:
- record = _record_path(browser)
- if record is not None:
- from tools.browser_launcher_holders import drop_lease
- drop_lease(record)
- if browser.owned and drop_record:
- _remove_record(browser)
- if browser.ephemeral:
- shutil.rmtree(browser.user_data_dir, ignore_errors=True)
- def _terminate(pid: Optional[int], start_time: Optional[int], proc: Optional[subprocess.Popen]) -> None:
- """Parent-first teardown (tools/AGENTS.md): SIGTERM the browser alone, then its snapshot survivors."""
- if not pid:
- return
- from tools.process_registry import ProcessRegistry
- try:
- ProcessRegistry._terminate_host_pid(pid, start_time)
- except OSError as exc:
- logger.debug("browser: terminating Chromium pid %s failed: %s", pid, exc)
- if proc is not None:
- try:
- proc.wait(timeout=5)
- except subprocess.TimeoutExpired:
- proc.kill()
- def stop_browser(key: str) -> None:
- """Let go of ``key``'s browser. A throwaway one this process launched is stopped. A shared-profile one is
- stopped only by its LAST holder across Hermes processes (:func:`_last_holder_out`); one a human started is
- never stopped. Holds ``key``'s launch lock: a relaunch of ``key`` waits for this stop instead of
- registering a replacement on the dir it is about to delete."""
- with _key_lock(key):
- _stop_locked(key)
- def _stop_locked(key: str) -> None:
- with _lock:
- browser = _browsers.get(key)
- proc = _procs.get(key)
- if browser is None:
- return
- record = None if browser.ephemeral else _record_path(browser)
- if record is None:
- if browser.owned:
- _terminate(browser.pid, browser.start_time, proc)
- with _lock:
- _forget(key, browser)
- return
- from tools.browser_launcher_holders import records_lock
- with records_lock(record.parent): # the decision and the forget are one step: another key may be the heir
- if _heir_key(browser) is None and _last_holder_out(record, browser):
- _terminate(browser.pid, browser.start_time, proc)
- record.unlink(missing_ok=True)
- with _lock:
- _forget(key, browser, drop_record=False)
- def _last_holder_out(record: Path, browser: LaunchedBrowser) -> bool:
- """Drop this process's hold on shared-profile ``browser`` (caller holds the records lock). True when it
- must stop it now: no other live Hermes process holds it, and Hermes launched it (a launch record names
- it). Otherwise a record this process holds, or whose owner is gone, goes to a live holder."""
- from tools import browser_launcher_holders as holders
- holders.drop_lease(record)
- if browser.foreign: # its pid names nobody here: stopped (or reaped) only from its own environment
- return False
- others = holders.other_live_holders(record, browser.start_time)
- data = _load_record(record) if record.exists() else None
- if data is not None and not _record_is(data, browser):
- data = None # an earlier browser on a recycled pid
- held_elsewhere = data is not None and not holders.held_here(data, "owner_pid") and _owner_alive(data)
- heir = holders.successor(others)
- if heir is not None and data is not None and not held_elsewhere:
- holders.hand_over(record, data, heir)
- if others or held_elsewhere:
- return False
- return browser.owned or data is not None
- def stop_all_browsers() -> None:
- """Stop every browser this process launched. Idempotent."""
- with _lock:
- keys = list(_browsers)
- for key in keys:
- stop_browser(key)
- # ── Per-profile records + orphan reap ────────────────────────────────────────────────────────────────
- def _ephemeral_root(home: str) -> Path:
- """Where ``home``'s throwaway profiles live; the reaper deletes nothing outside it."""
- return Path(home) / "cache" / "browser" / "chromium"
- def _records_dir(home: str) -> Path:
- """``home``'s throwaway-profile records (not the process's home): a crashed owner's Chromium is reaped by the
- next Hermes process serving that profile. Read only after ``_private_dir`` vouches for it."""
- return Path(home) / "cache" / "browser" / "chromium-records"
- def _is_private_dir(path: Path) -> bool:
- """A real directory (not a symlink) owned by this user and closed to group/other writes. Windows has no
- uid and synthesizes the mode bits, so there only the directory check applies."""
- try:
- st = path.lstat()
- except OSError:
- return False
- if not stat.S_ISDIR(st.st_mode):
- return False
- return not hasattr(os, "getuid") or (st.st_uid == os.getuid() and not st.st_mode & 0o022)
- def _private_dir(path: Path) -> Optional[Path]:
- """``path``, created 0700 when missing; None (logged) when an existing one is not private to this user."""
- path.parent.mkdir(parents=True, exist_ok=True)
- try:
- path.mkdir(mode=0o700)
- except FileExistsError:
- pass
- if _is_private_dir(path):
- return path
- logger.debug("browser: not using %s for launcher state: not a private directory of this user", path)
- return None
- def _shared_profiles_root() -> Path:
- """Launcher state of persistent (shared) profiles, per OS user rather than per HERMES_HOME: two homes pinning
- one ``browser.user_data_dir`` drive its one Chromium, so they must see one launch record, one lease set and
- one lock. The host rendezvous root the gateway's own cross-profile locks use."""
- from gateway.status import _get_lock_dir
- return _get_lock_dir() / "browser-shared-profiles"
- def _profile_digest(user_data_dir: str) -> str:
- """One profile dir, however it is spelled (a symlink, a trailing slash)."""
- return hashlib.sha256(os.path.realpath(user_data_dir).encode()).hexdigest()
- def _same_profile(recorded, user_data_dir: str) -> bool:
- return isinstance(recorded, str) and os.path.realpath(recorded) == os.path.realpath(user_data_dir)
- def _devtools_id(browser: LaunchedBrowser) -> Optional[str]:
- """The ``/devtools/browser/<id>`` path of ``browser``'s endpoint (new per launch); None before it is up."""
- at = browser.cdp_url.find("/devtools/browser/")
- return browser.cdp_url[at:] if at >= 0 else None
- def _record_is(record: dict, browser: LaunchedBrowser) -> bool:
- """``record`` describes this launch of ``browser``: same pid and profile, and its start time; for a browser of
- another environment (its pid is another namespace's number and its start time unreadable here), a record from
- another namespace naming the DevTools browser id its endpoint serves."""
- from tools.browser_launcher_holders import same_namespace
- if record.get("pid") != browser.pid or not _same_profile(record.get("user_data_dir"), browser.user_data_dir):
- return False
- if browser.foreign:
- return not same_namespace(record) and record.get("devtools") is not None and (
- record.get("devtools") == _devtools_id(browser))
- return record.get("start_time") == browser.start_time
- def _shared_state_dir(user_data_dir: str) -> Optional[Path]:
- """Shared profile ``user_data_dir``'s own private dir (its launch record, leases and lock)."""
- root = _private_dir(_shared_profiles_root())
- return _private_dir(root / _profile_digest(user_data_dir)[:32]) if root is not None else None
- def _state_dir(browser: LaunchedBrowser) -> Optional[Path]:
- """The private dir holding ``browser``'s launch record, leases and lock: its home's records dir for a
- throwaway profile, else the shared profile's own dir under :func:`_shared_profiles_root`."""
- if browser.ephemeral:
- return _private_dir(_records_dir(browser.home_key))
- return _shared_state_dir(browser.user_data_dir)
- def _record_path(browser: LaunchedBrowser) -> Optional[Path]:
- records = _state_dir(browser)
- if records is None:
- return None
- return records / _record_name(browser)
- def _record_name(browser: LaunchedBrowser) -> str:
- """The launch record ``browser``'s leases are keyed by: the one it was bound to, else this namespace's name."""
- from tools.browser_launcher_holders import ns_tag
- return browser.record_name or f"{_profile_digest(browser.user_data_dir)[:16]}-{browser.pid}{ns_tag()}.json"
- def _write_record(browser: LaunchedBrowser) -> None:
- from tools import browser_launcher_holders as holders
- from utils import atomic_json_write
- record = {"owner_pid": os.getpid(), "owner_start_time": _start_time(os.getpid()), "pid": browser.pid,
- "start_time": browser.start_time, "user_data_dir": browser.user_data_dir,
- "home_key": browser.home_key, "ephemeral": browser.ephemeral, "ns": holders.ns_identity(),
- "devtools": _devtools_id(browser)}
- try:
- path = _record_path(browser)
- if path is not None:
- atomic_json_write(path, record, indent=None)
- except OSError as exc:
- logger.debug("browser: could not write launch record for pid %s: %s", browser.pid, exc)
- def _remove_record(browser: LaunchedBrowser) -> None:
- try:
- path = _record_path(browser)
- if path is not None:
- path.unlink(missing_ok=True)
- except OSError as exc:
- logger.debug("browser: could not remove launch record for pid %s: %s", browser.pid, exc)
- def _owner_alive(record: dict) -> bool:
- """The record's owner is alive, or cannot be proven gone (it was written in another PID namespace)."""
- from tools.browser_launcher_holders import same_namespace
- if not same_namespace(record):
- return True
- owner = record.get("owner_pid")
- if not isinstance(owner, int) or not _pid_alive(owner):
- return False
- expected = record.get("owner_start_time")
- return expected is None or _start_time(owner) == expected
- def _cmdline_names_dir(pid: int, user_data_dir: str) -> bool:
- """True only when ``pid``'s argv carries ``--user-data-dir=`` naming ``user_data_dir`` (however either is
- spelled: a symlink, a trailing slash)."""
- try:
- import psutil
- argv = psutil.Process(pid).cmdline()
- except Exception: # health: allow BLE001 -- unreadable identity fails closed (no kill)
- return False
- return any(tok.startswith("--user-data-dir=") and _same_profile(tok.split("=", 1)[1], user_data_dir)
- for tok in argv)
- def _inside_ephemeral_root(user_data_dir: str, home: Optional[str]) -> bool:
- if home is None: # a shared-profile state dir holds no throwaway profiles
- return False
- try:
- rel = Path(user_data_dir).resolve().relative_to(_ephemeral_root(home).resolve())
- except (OSError, ValueError):
- return False
- return bool(rel.parts)
- def _is_recorded_browser(record: dict, home: Optional[str]) -> bool:
- pid, udd = record.get("pid"), record.get("user_data_dir")
- if not isinstance(pid, int) or not isinstance(udd, str) or not _pid_alive(pid):
- return False
- if record.get("ephemeral") and not _inside_ephemeral_root(udd, home):
- logger.debug("browser: ignoring launch record for pid %s: %s is not a launcher profile dir", pid, udd)
- return False
- expected = record.get("start_time")
- if expected is None or _start_time(pid) != expected:
- return False # no recorded fingerprint, or a recycled pid: never signal on argv alone
- if not _cmdline_names_dir(pid, udd):
- logger.warning("browser: refusing to reap pid %s: its command line does not name %s", pid, udd)
- return False
- return True
- def _tracked_browser(record: dict) -> Optional[LaunchedBrowser]:
- with _lock: # a browser another environment holds has a pid of THAT namespace: it tracks no record here
- return next((b for b in (*_browsers.values(), *_launching.values())
- if not b.foreign and _record_is(record, b)), None)
- def _adopt_record(browser: LaunchedBrowser) -> None:
- """A crashed owner's record still names the browser this process now uses (attached after the crash):
- take the record over, or every reaper (this process's included) would kill it as an orphan. Only the owner
- changes: the launch as recorded (its ``--user-data-dir`` spelling, DevTools id) stays what verifies it."""
- from utils import atomic_json_write
- path = _record_path(browser)
- if path is None or not path.exists():
- return
- record = _load_record(path)
- if record is not None and _record_is(record, browser) and not _owner_alive(record):
- me = os.getpid()
- atomic_json_write(path, {**record, "owner_pid": me, "owner_start_time": _start_time(me)}, indent=None)
- def _load_record(path: Path) -> Optional[dict]:
- """The record, or None (a corrupt one is removed)."""
- try:
- record = json.loads(path.read_text(encoding="utf-8-sig"))
- if isinstance(record, dict):
- return record
- except (OSError, ValueError):
- pass
- path.unlink(missing_ok=True)
- return None
- def _reap_record(path: Path, home: Optional[str]) -> bool:
- """Caller holds the records lock."""
- from tools import browser_launcher_holders as holders
- record = _load_record(path)
- if record is None or not holders.same_namespace(record): # another namespace's pids name nobody here
- return False
- tracked = _tracked_browser(record)
- if tracked is not None: # in use here, whoever launched it
- _adopt_record(tracked)
- return False
- if record.get("owner_pid") != os.getpid() and _owner_alive(record):
- return False
- others = holders.other_live_holders(path, record.get("start_time"))
- if others: # another live Hermes process still drives it
- heir = holders.successor(others)
- if heir is not None:
- holders.hand_over(path, record, heir)
- return False
- reaped = _is_recorded_browser(record, home)
- if reaped:
- _terminate(record["pid"], record.get("start_time"), None)
- logger.info("browser: reaped orphaned Chromium pid %s (%s)", record["pid"], record["user_data_dir"])
- udd = record.get("user_data_dir")
- if (record.get("ephemeral") and isinstance(udd, str) and _inside_ephemeral_root(udd, home)
- and (reaped or not _browser_running_on(udd))):
- shutil.rmtree(udd, ignore_errors=True) # its owner is gone: no launch reuses a per-process dir
- path.unlink(missing_ok=True)
- return reaped
- def _reap_home(home: str) -> int:
- return _reap_state_dir(_records_dir(home), home)
- def _reap_shared_profiles() -> int:
- """Every shared profile's records, whichever home launched its browser."""
- root = _shared_profiles_root()
- if not os.path.lexists(root) or not _is_private_dir(root):
- return 0
- try:
- states = sorted(root.iterdir())
- except OSError as exc:
- logger.debug("browser: shared-profile launcher state unavailable in %s: %s", root, exc)
- return 0
- return sum(_reap_state_dir(state, None) for state in states)
- def _reap_state_dir(records: Path, home: Optional[str]) -> int:
- """Reap one launcher state dir (``home``'s records, or a shared profile's dir when ``home`` is None). A
- shared profile whose lock is taken (a first launch holds it for up to its whole readiness wait) is left
- to the next pass."""
- if not os.path.lexists(records):
- return 0
- if not _is_private_dir(records):
- logger.debug("browser: not reaping from %s: not a private directory of this user", records)
- return 0
- from tools import browser_launcher_holders as holders
- with holders.records_lock(records, blocking=home is not None) as locked:
- if not locked:
- logger.debug("browser: %s is busy (a launch or stop holds it); reaping it next pass", records)
- return 0
- try:
- paths = sorted(records.glob("*.json"))
- except OSError as exc:
- logger.debug("browser: launch records unavailable in %s: %s", records, exc)
- return 0
- reaped = sum(1 for path in paths if _reap_record(path, home))
- holders.drop_dead_leases(records)
- return reaped
- _THROWAWAY_DIR = re.compile(r"^[0-9a-f]{16}-(\d+)(?:-(\d+))?(-n[0-9a-f]{12})?$") # _default_user_data_dir's names
- def _reclaim_throwaway_dirs(home: str) -> None:
- """Remove ``home``'s throwaway profiles whose owning process is gone (pid and start time in the name): one
- that died before writing its launch record left nothing else that would. The dir of a live owner, or of an
- owner in another PID namespace or boot (its name's ``ns_tag`` differs or is missing), is never touched; a
- name without a start time is reclaimed only once its pid is gone."""
- root = _ephemeral_root(home)
- if not os.path.lexists(root) or not _is_private_dir(root):
- return
- from tools.browser_launcher_holders import ns_tag, process_alive
- try:
- entries = list(root.iterdir())
- except OSError as exc:
- logger.debug("browser: throwaway profiles unavailable in %s: %s", root, exc)
- return
- for entry in entries:
- match = _THROWAWAY_DIR.match(entry.name)
- if match is None or (match.group(3) or "") != ns_tag() or int(match.group(1)) == os.getpid():
- continue # not a launcher dir, another PID namespace's (its owner cannot be checked here), or ours
- if process_alive(int(match.group(1)), int(match.group(2)) if match.group(2) else None):
- continue
- if _browser_running_on(str(entry)): # its record was lost or could not prove the pid: never pull the dir
- logger.debug("browser: keeping the throwaway profile %s: a Chromium still runs on it", entry)
- continue
- shutil.rmtree(entry, ignore_errors=True) # a symlink is refused, never followed
- logger.info("browser: removed the throwaway profile %s of a Hermes process that is gone", entry)
- def _served_home_keys(homes) -> set[str]:
- """The launch profile, every profile this process launched a browser for, and ``homes``."""
- from hermes_constants import get_process_hermes_home, hermes_home_key
- with _lock:
- keys = set(_served_homes)
- keys.add(hermes_home_key(get_process_hermes_home()))
- keys.update(hermes_home_key(home) for home in homes)
- return keys
- def reap_orphaned_browsers(homes=()) -> int:
- """Stop Chromium processes whose owning Hermes process is gone, in every profile this process serves
- (``_served_home_keys``; the janitor and atexit run outside any profile scope, so each home's records
- are read by path); returns the count. A pid is signalled only after its start time AND its
- ``--user-data-dir`` argv token match the record. Throwaway profiles of owners that are gone go too."""
- reaped = _reap_shared_profiles()
- for home in sorted(_served_home_keys(homes)):
- reaped += _reap_home(home)
- _reclaim_throwaway_dirs(home)
- return reaped
|