parsek-cdp-server 0.1.0__tar.gz → 0.1.2__tar.gz

{parsek_cdp_server-0.1.0 → parsek_cdp_server-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parsek-cdp-server
-Version: 0.1.0
+Version: 0.1.2
 Summary: Parsek CDP server — launch, supervise and proxy a browser; server-side feature producers.
 Author: xa1era
 License-Expression: Apache-2.0
@@ -8,7 +8,7 @@ Project-URL: Repository, https://github.com/xa1era/parsek-cdp
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: parsek-cdp~=0.1.0
+Requires-Dist: parsek-cdp~=0.1.2
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: psutil>=5
 Requires-Dist: prometheus-client>=0.19

{parsek_cdp_server-0.1.0 → parsek_cdp_server-0.1.2}/parsek_cdp_server/launcher.py

@@ -10,19 +10,19 @@ drives this class.
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
 import os
 import random
 import shutil
-import signal
 import tempfile
 import urllib.error
 import urllib.request
-from dataclasses import dataclass, field
 from pathlib import Path
 from typing import List, Optional
 
 import psutil
+from parsek_cdp.core.browser import LaunchOptions
 
 #: Env var naming *directories* to search for browser binaries,
 #: ``os.pathsep``-separated (like ``PATH``), e.g. ``/opt/browsers/chrome:/opt/browsers/brave``.
@@ -102,27 +102,26 @@ def _is_browser(filename: str) -> bool:
 
 
 def _find_in_dirs(dirs: List[str]) -> List[str]:
-    """Recursively collect browser executables found under ``dirs``."""
+    """Collect browser executables directly under ``dirs`` (non-recursive)."""
     found: List[str] = []
     for directory in dirs:
         directory = directory.strip()
         if not directory or not os.path.isdir(directory):
             continue
-        for root, _subdirs, files in os.walk(directory):
-            for filename in files:
-                if not _is_browser(filename):
-                    continue
-                full = os.path.join(root, filename)
-                if os.path.isfile(full) and os.access(full, os.X_OK):
-                    found.append(full)
+        for filename in os.listdir(directory):
+            if not _is_browser(filename):
+                continue
+            full = os.path.join(directory, filename)
+            if os.path.isfile(full) and os.access(full, os.X_OK):
+                found.append(full)
     return found
 
 
 def _detect_executable() -> str:
     """Pick a Chromium-based binary, or raise if none is available.
 
-    Precedence: a random browser executable found by recursively searching the
-    directories in :data:`CHROMES_PATH_ENV` (defaulting to :data:`_KNOWN_PATHS`),
+    Precedence: a random browser executable found directly in the directories
+    listed in :data:`CHROMES_PATH_ENV` (defaulting to :data:`_KNOWN_PATHS`),
     else the first :data:`_CANDIDATES` name resolvable on ``PATH``.
     """
     raw = os.environ.get(CHROMES_PATH_ENV)
@@ -140,18 +139,6 @@ def _detect_executable() -> str:
     )
 
 
-@dataclass
-class LaunchOptions:
-    """How to start the browser."""
-
-    executable: Optional[str] = None  # autodetect if None
-    headless: bool = True
-    port: int = 0
-    user_data_dir: Optional[str] = None
-    extra_args: List[str] = field(default_factory=list)
-    default_args: bool = True
-
-
 class ChromeLauncher:
     """Spawn a browser process and expose its browser-level websocket url.
 
@@ -173,8 +160,6 @@ class ChromeLauncher:
         #: Temp profile dir we created (and must clean up); None if caller supplied one.
         self._owned_user_data_dir: Optional[str] = None
 
-    # -- argv -------------------------------------------------------------- #
-
     def _resolve_user_data_dir(self) -> str:
         if self.options.user_data_dir is not None:
             return self.options.user_data_dir
@@ -185,7 +170,7 @@ class ChromeLauncher:
     def _build_argv(self, user_data_dir: str) -> List[str]:
         executable = self.options.executable or _detect_executable()
         argv = [executable, f"--remote-debugging-port={self.options.port}"]
-        if self.options.default_args:
+        if self.options.use_default_args:
             argv += [
                 f"--user-data-dir={user_data_dir}",
                 "--no-first-run",
@@ -271,22 +256,48 @@ class ChromeLauncher:
         return psutil.pid_exists(self.pid)
 
     async def terminate(self, *, timeout: float = 5.0) -> None:
-        """Terminate the browser process gracefully, then kill if it lingers."""
+        """Terminate the browser process tree gracefully, then kill survivors.
+
+        Chrome frequently re-execs or forks the real browser into a *separate*
+        process (headed mode, wrapper launch scripts, the relauncher), after which
+        the process we spawned has already exited.  Signalling only that direct
+        child would then leave the real browser running as an orphan, so we walk
+        the whole tree rooted at :attr:`pid` (parent + recursive children) and
+        SIGTERM it, escalating to SIGKILL for anything still alive after the grace
+        period.
+        """
+        procs = self._process_tree()
+        for p in procs:
+            with _suppress_lookup():
+                p.terminate()  # SIGTERM
+        # psutil.wait_procs is blocking, so run it off the event loop.
+        _gone, alive = await asyncio.to_thread(
+            psutil.wait_procs, procs, timeout=timeout
+        )
+        for p in alive:
+            with _suppress_lookup():
+                p.kill()  # SIGKILL
+        # Reap the asyncio child so its transport doesn't warn about a lost process.
         proc = self._proc
         if proc is not None and proc.returncode is None:
-            try:
-                proc.send_signal(signal.SIGTERM)
-            except ProcessLookupError:
-                pass
-            else:
-                try:
-                    await asyncio.wait_for(proc.wait(), timeout)
-                except asyncio.TimeoutError:
-                    with _suppress_lookup():
-                        proc.kill()
-                    await proc.wait()
+            with contextlib.suppress(ProcessLookupError):
+                await proc.wait()
         self._cleanup_profile()
 
+    def _process_tree(self) -> List[psutil.Process]:
+        """The browser process and all its descendants (empty if already gone)."""
+        if self.pid is None:
+            return []
+        try:
+            parent = psutil.Process(self.pid)
+        except psutil.NoSuchProcess:
+            return []
+        try:
+            children = parent.children(recursive=True)
+        except psutil.NoSuchProcess:
+            children = []
+        return [parent, *children]
+
     def _cleanup_profile(self) -> None:
         if self._owned_user_data_dir is not None:
             shutil.rmtree(self._owned_user_data_dir, ignore_errors=True)
@@ -294,10 +305,17 @@ class ChromeLauncher:
 
 
 class _suppress_lookup:
-    """Context manager swallowing ``ProcessLookupError`` (process already gone)."""
+    """Context manager swallowing "process already gone" errors.
+
+    Covers both :class:`ProcessLookupError` (from ``asyncio``/``os`` signalling)
+    and :class:`psutil.NoSuchProcess` (from the process-tree walk), which race
+    naturally: a process can exit between being listed and being signalled.
+    """
 
     def __enter__(self) -> "_suppress_lookup":
         return self
 
     def __exit__(self, exc_type, exc, tb) -> bool:
-        return exc_type is not None and issubclass(exc_type, ProcessLookupError)
+        return exc_type is not None and issubclass(
+            exc_type, (ProcessLookupError, psutil.NoSuchProcess)
+        )

{parsek_cdp_server-0.1.0 → parsek_cdp_server-0.1.2}/parsek_cdp_server/metrics.py

@@ -14,8 +14,12 @@ blocks the event loop:
 
 Metrics:
 
+Only *active* browsers (supervisor state ``READY``) are reported; browsers that
+are still starting, crashed, restarting or closed contribute no series, and any
+event counters they left behind are pruned -- so stale data never lingers.
+
 ==================================  =====  ===========================================
-``parsek_browsers``                 gauge  supervised browsers
+``parsek_browsers``                 gauge  active (READY) browsers
 ``parsek_targets``                  gauge  targets, labelled ``browser``, ``type``
 ``parsek_nested_targets``           gauge  targets with a ``parentId``, per ``browser``
 ``parsek_browser_cpu_percent``      gauge  CPU% of the browser tree, per ``browser``
@@ -125,6 +129,11 @@ class ServerMetrics:
         snapshot: Dict[str, _BrowserSnapshot] = {}
         live_targets: Set[Tuple[str, str]] = set()
         for browser_uuid, supervisor in list(self._server.supervisors.items()):
+            # Only active (READY) browsers contribute metrics; skipping the rest
+            # keeps their targets out of ``live_targets`` so their event series
+            # are pruned below instead of lingering.
+            if not supervisor.is_active:
+                continue
             snap = _BrowserSnapshot()
             origin = supervisor.http_origin
             if origin is not None:
@@ -201,8 +210,8 @@ class _Collector:
         m = self._metrics
         snapshot = m._snapshot
 
-        browsers = GaugeMetricFamily("parsek_browsers", "Number of supervised browsers")
-        browsers.add_metric([], float(len(m._server.supervisors)))
+        browsers = GaugeMetricFamily("parsek_browsers", "Number of active (READY) browsers")
+        browsers.add_metric([], float(len(snapshot)))
         yield browsers
 
         targets = GaugeMetricFamily(

{parsek_cdp_server-0.1.0 → parsek_cdp_server-0.1.2}/parsek_cdp_server/proxy.py

@@ -30,16 +30,17 @@ import itertools
 import json
 import subprocess
 import uuid
-from typing import Callable, Dict, List, Optional, Set, Tuple, Type
+from typing import Awaitable, Callable, Dict, List, Optional, Set, Tuple, Type
 
 import websockets
 from aiohttp import web
 from parsek_cdp._logging import get_logger
+from parsek_cdp.core.browser import LaunchOptions
 from parsek_cdp.core.feature import Feature
 from parsek_cdp.core.target import ProtocolError
+from parsek_cdp.parsek import BrowserState
 from parsek_cdp.parsek.events import BrowserStateChanged
 
-from .launcher import LaunchOptions
 from .metrics import ServerMetrics
 from .reaper import spawn_reaper
 from .supervisor import BrowserSupervisor
@@ -316,6 +317,9 @@ class ParsekServer:
             browser_uuid, options=options, idle_timeout=idle_timeout
         )
         supervisor.on_state(self._state_broadcaster(browser_uuid))
+        # Registered after the broadcaster so clients still receive the CLOSED
+        # frame before the registries are dropped.
+        supervisor.on_state(self._forget_on_close(browser_uuid))
         self.supervisors[browser_uuid] = supervisor
         self._browser_features[browser_uuid] = feats
         self._control_clients[browser_uuid] = set()
@@ -329,17 +333,8 @@ class ParsekServer:
             body = await request.json() if request.can_read_body else {}
         except Exception:
             body = {}
-        allowed = {
-            "executable",
-            "headless",
-            "port",
-            "user_data_dir",
-            "extra_args",
-            "default_args",
-        }
-        kwargs = {k: body[k] for k in allowed if k in body}
-        if kwargs:
-            return LaunchOptions(**kwargs)
+        if body:
+            return LaunchOptions.from_json(body)
         return self.launch_options
 
     async def _idle_timeout(self, request: web.Request) -> Optional[float]:
@@ -384,12 +379,47 @@ class ParsekServer:
             ),
         )
         try:
-            await self._pipe(ws, supervisor.ws_url)
+            await self._pipe(
+                ws,
+                supervisor.ws_url,
+                on_client_frame=self._on_control_frame(browser_uuid),
+            )
         finally:
             clients.discard(ws)
             supervisor.client_disconnected()
         return ws
 
+    def _on_control_frame(self, browser_uuid: str):
+        """Watch a control channel for the client's ``Browser.close`` request.
+
+        The frame is still forwarded to the browser (it closes itself gracefully);
+        this handler additionally shuts the *supervisor* down so the resulting
+        process exit is recorded as an intentional ``CLOSED`` rather than a crash
+        to be relaunched.
+        """
+
+        async def handle(data: str) -> None:
+            # Cheap substring gate first -- only bother parsing the frame that
+            # could actually be the close request, not every control message.
+            if "Browser.close" not in data:
+                return
+            try:
+                method = json.loads(data).get("method")
+            except Exception:
+                return
+            if method == "Browser.close":
+                await self._graceful_close(browser_uuid)
+
+        return handle
+
+    async def _graceful_close(self, browser_uuid: str) -> None:
+        """Stop supervising ``browser_uuid`` and terminate it (idempotent)."""
+        supervisor = self.supervisors.pop(browser_uuid, None)
+        self._browser_features.pop(browser_uuid, None)
+        self._control_clients.pop(browser_uuid, None)
+        if supervisor is not None:
+            await supervisor.shutdown()
+
     async def page_ws(self, request: web.Request) -> web.WebSocketResponse:
         """``ws /cdp/{browser}/page/{target}``: pipe to a target + aggregation."""
         browser_uuid = request.match_info["browser"]
@@ -404,8 +434,10 @@ class ParsekServer:
         feats = self._browser_features.get(browser_uuid, self.features)
         on_event = None
         if self.metrics is not None:
+
             def on_event(domain: str) -> None:
                 self.metrics.record_event(browser_uuid, target_id, domain)
+
         bridge = PageBridge(
             ws,
             supervisor.target_ws_url(target_id),
@@ -424,8 +456,18 @@ class ParsekServer:
 
     # -- helpers ----------------------------------------------------------- #
 
-    async def _pipe(self, client_ws: web.WebSocketResponse, chrome_url: str) -> None:
-        """Relay raw frames both ways between a client socket and Chrome."""
+    async def _pipe(
+        self,
+        client_ws: web.WebSocketResponse,
+        chrome_url: str,
+        on_client_frame: Optional[Callable[[str], Awaitable[None]]] = None,
+    ) -> None:
+        """Relay raw frames both ways between a client socket and Chrome.
+
+        ``on_client_frame`` (if given) is invoked with each text frame *after* it
+        has been forwarded, letting the caller react to specific commands (e.g.
+        ``Browser.close``) without disturbing the passthrough.
+        """
         async with websockets.connect(
             chrome_url, max_size=None, ping_interval=None
         ) as chrome:
@@ -436,6 +478,8 @@ class ParsekServer:
                         if msg.type is not web.WSMsgType.TEXT:
                             break
                         await chrome.send(msg.data)
+                        if on_client_frame is not None:
+                            await on_client_frame(msg.data)
                 except (websockets.ConnectionClosed, ConnectionError):
                     pass
 
@@ -453,6 +497,24 @@ class ParsekServer:
             )
             await _close_pending(pending)
 
+    def _forget_on_close(self, browser_uuid: str):
+        """Drop a browser from the registries once it reaches ``CLOSED``.
+
+        This is how a self-initiated shutdown -- notably the supervisor's idle
+        timeout (:meth:`BrowserSupervisor._close_idle`) -- gets its supervisor
+        removed from :attr:`supervisors` (and the sibling registries), without the
+        supervisor needing a back-reference to the server.  Idempotent, so a
+        ``CLOSED`` also driven by :meth:`_graceful_close`/:meth:`stop` is harmless.
+        """
+
+        def callback(state, reason=None) -> None:
+            if state is BrowserState.CLOSED:
+                self.supervisors.pop(browser_uuid, None)
+                self._browser_features.pop(browser_uuid, None)
+                self._control_clients.pop(browser_uuid, None)
+
+        return callback
+
     def _state_broadcaster(self, browser_uuid: str):
         def callback(state, reason) -> None:
             frame = json.dumps(

{parsek_cdp_server-0.1.0 → parsek_cdp_server-0.1.2}/parsek_cdp_server/supervisor.py

@@ -173,6 +173,16 @@ class BrowserSupervisor:
             raise RuntimeError("supervisor not started")
         return f"{self.host}/devtools/page/{target_id}"
 
+    @property
+    def is_active(self) -> bool:
+        """Whether the browser is up and serving (state ``READY``).
+
+        Metrics report only active browsers, so a starting / crashed / restarting
+        / closed browser contributes no series (and its stale event counters are
+        pruned), preventing leftover data from lingering.
+        """
+        return self.state is BrowserState.READY
+
     @property
     def pid(self) -> Optional[int]:
         """PID of the supervised browser process (``None`` before launch)."""

{parsek_cdp_server-0.1.0 → parsek_cdp_server-0.1.2}/parsek_cdp_server.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parsek-cdp-server
-Version: 0.1.0
+Version: 0.1.2
 Summary: Parsek CDP server — launch, supervise and proxy a browser; server-side feature producers.
 Author: xa1era
 License-Expression: Apache-2.0
@@ -8,7 +8,7 @@ Project-URL: Repository, https://github.com/xa1era/parsek-cdp
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: parsek-cdp~=0.1.0
+Requires-Dist: parsek-cdp~=0.1.2
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: psutil>=5
 Requires-Dist: prometheus-client>=0.19

{parsek_cdp_server-0.1.0 → parsek_cdp_server-0.1.2}/parsek_cdp_server.egg-info/requires.txt

@@ -1,4 +1,4 @@
-parsek-cdp~=0.1.0
+parsek-cdp~=0.1.2
 aiohttp>=3.9
 psutil>=5
 prometheus-client>=0.19

{parsek_cdp_server-0.1.0 → parsek_cdp_server-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "parsek-cdp-server"
-version = "0.1.0"
+version = "0.1.2"
 description = "Parsek CDP server — launch, supervise and proxy a browser; server-side feature producers."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -13,7 +13,7 @@ license = "Apache-2.0"
 dependencies = [
   # Reuses the shared layers (cdp/, core/, parsek/) from the client distribution,
   # including internal modules -- so track the client's patch line (>=0.1.0,<0.2.0).
-  "parsek-cdp~=0.1.0",
+  "parsek-cdp~=0.1.2",
   "aiohttp>=3.9",          # ws + HTTP endpoints (/cdp/{browser}/control, /cdp/{browser}/page/{target}, /browsers)
   "psutil>=5",             # watchdog over the Chrome process + zombie reaper
   "prometheus-client>=0.19",  # /metrics exposition