susops 3.0.0rc3.dev1__py3-none-any.whl

susops/__init__.py

@@ -0,0 +1,4 @@
+from susops.version import VERSION
+
+__version__ = VERSION
+__all__ = ["__version__"]

susops/client.py

@@ -0,0 +1,230 @@
+"""Thin RPC client that mirrors SusOpsManager's public API.
+
+Designed so frontends can replace
+    self.manager = SusOpsManager(workspace=...)
+with
+    self.manager = SusOpsClient(workspace=...)
+and have everything just work. All known facade methods are forwarded over
+the daemon's /rpc endpoint; exceptions raised in the daemon are
+reconstructed (by name) and re-raised in the client.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from susops.core.rpc_protocol import InvocationRequest, InvocationResponse
+
+_WORKSPACE_DEFAULT = Path.home() / ".susops"
+_DAEMON_SPAWN_TIMEOUT = 5.0
+
+
+class DaemonUnavailableError(RuntimeError):
+    """Raised when the daemon can't be reached or won't start."""
+
+
+def _port_path(workspace: Path) -> Path:
+    return workspace / "pids" / "susops-services.port"
+
+
+def _pid_path(workspace: Path) -> Path:
+    return workspace / "pids" / "susops-services.pid"
+
+
+def _read_port(workspace: Path) -> int | None:
+    try:
+        return int(_port_path(workspace).read_text().strip())
+    except Exception:
+        return None
+
+
+def _is_daemon_alive(workspace: Path) -> bool:
+    pid_file = _pid_path(workspace)
+    if not pid_file.exists():
+        return False
+    try:
+        pid = int(pid_file.read_text().strip())
+        os.kill(pid, 0)  # signal 0 = liveness probe
+        return True
+    except (OSError, ValueError):
+        return False
+
+
+def ensure_daemon_running(workspace: Path = _WORKSPACE_DEFAULT) -> int:
+    """Make sure the susops-services daemon is up; spawn it if not.
+
+    Returns the RPC port. Raises DaemonUnavailableError on timeout.
+
+    Captures the spawned daemon's stderr so a preflight failure
+    (PAC port squatted, peer daemon alive, …) is surfaced to the caller
+    instead of getting buried under a generic "didn't come up" message.
+    """
+    if _is_daemon_alive(workspace):
+        port = _read_port(workspace)
+        if port:
+            return port
+
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "susops.core.services_daemon",
+         "--workspace", str(workspace)],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        start_new_session=True,
+    )
+
+    deadline = time.monotonic() + _DAEMON_SPAWN_TIMEOUT
+    while time.monotonic() < deadline:
+        if _is_daemon_alive(workspace):
+            port = _read_port(workspace)
+            if port:
+                return port
+        # If the daemon exited (e.g. preflight rejected it), don't keep
+        # polling — surface the reason and bail out immediately.
+        rc = proc.poll()
+        if rc is not None:
+            try:
+                _, err = proc.communicate(timeout=0.5)
+                stderr = err.decode(errors="replace").strip() if err else ""
+            except Exception:
+                stderr = ""
+            msg = (
+                    f"Daemon exited during startup (rc={rc})"
+                    + (f":\n{stderr}" if stderr else "")
+            )
+            raise DaemonUnavailableError(msg)
+        time.sleep(0.1)
+
+    # Spawn is still alive but never wrote its PID/port file in time.
+    try:
+        proc.terminate()
+    except Exception:
+        pass
+    raise DaemonUnavailableError("Daemon did not come up within timeout")
+
+
+# Map of error_type strings to Python exception classes the client
+# re-raises. Anything not listed falls back to RuntimeError so we never
+# silently swallow a server-side failure.
+_EXC_MAP: dict[str, type] = {
+    "ValueError": ValueError,
+    "RuntimeError": RuntimeError,
+    "FileNotFoundError": FileNotFoundError,
+    "PermissionError": PermissionError,
+    "KeyError": KeyError,
+    "AttributeError": AttributeError,
+}
+
+
+class SusOpsClient:
+    """RPC proxy with the same API surface as `SusOpsManager`.
+
+    Lazy: only resolves the daemon on first call. If it isn't running,
+    auto-spawns it via `ensure_daemon_running`.
+    """
+
+    def __init__(self, workspace: Path = _WORKSPACE_DEFAULT,
+                 process_name: str = "susops-client") -> None:
+        self.workspace = workspace
+        # process_name kept for API compatibility with frontends.
+        self._process_name = process_name
+        self._port: int | None = None
+
+    # ------------------------------------------------------------------ #
+    # Compatibility shims that some frontends read directly.
+    # ------------------------------------------------------------------ #
+
+    @property
+    def app_config(self):
+        """Frontends sometimes read `manager.app_config.<field>` directly."""
+        return self.list_config().susops_app
+
+    @property
+    def config(self):
+        """Snapshot of the current config. Per call → fresh RPC."""
+        return self.list_config()
+
+    # ------------------------------------------------------------------ #
+    # Auto-proxy: any unknown public attribute becomes an RPC call.
+    # ------------------------------------------------------------------ #
+
+    def __getattr__(self, name: str):
+        # Block dunders + private names so they never reach /rpc.
+        if name.startswith("_"):
+            raise AttributeError(name)
+
+        def _proxy(*args, **kwargs):
+            return self._invoke(name, list(args), kwargs)
+
+        # Cache the proxy so repeated lookups don't rebuild it.
+        self.__dict__[name] = _proxy
+        return _proxy
+
+    # ------------------------------------------------------------------ #
+    # Internal: RPC dispatch.
+    # ------------------------------------------------------------------ #
+
+    def _invoke(self, method: str, args: list, kwargs: dict) -> Any:
+        """Issue one RPC call. On connection-refused (daemon died / wasn't
+        running yet), reset the cached port, re-run ensure_daemon_running
+        (which respawns if needed), and retry exactly once. Tray + TUI
+        otherwise crash on the first menu click after a daemon restart.
+        """
+        req = InvocationRequest(method=method, args=args, kwargs=kwargs)
+        last_exc: Exception | None = None
+
+        for attempt in (1, 2):
+            if self._port is None:
+                try:
+                    self._port = ensure_daemon_running(self.workspace)
+                except DaemonUnavailableError as exc:
+                    last_exc = exc
+                    continue
+
+            http_req = urllib.request.Request(
+                f"http://127.0.0.1:{self._port}/rpc",
+                data=req.to_json().encode("utf-8"),
+                headers={"Content-Type": "application/json"},
+            )
+            try:
+                with urllib.request.urlopen(http_req, timeout=30) as resp:
+                    body = InvocationResponse.from_json(resp.read().decode("utf-8"))
+            except urllib.error.HTTPError as exc:
+                # 4xx/5xx — body should still be a valid InvocationResponse JSON.
+                # Don't retry; the daemon answered, the call just failed.
+                try:
+                    body = InvocationResponse.from_json(exc.read().decode("utf-8"))
+                except Exception:
+                    raise DaemonUnavailableError(f"Daemon HTTP error: {exc}") from exc
+            except urllib.error.URLError as exc:
+                # Connection refused / unreachable. The daemon died, was
+                # killed, or hasn't come back up yet. Drop the cached port
+                # so the next iteration ensures+respawns.
+                last_exc = exc
+                self._port = None
+                if attempt == 1:
+                    continue
+                raise DaemonUnavailableError(f"Daemon unreachable: {exc}") from exc
+            except Exception as exc:
+                # Unknown transport error. Reset and retry once.
+                last_exc = exc
+                self._port = None
+                if attempt == 1:
+                    continue
+                raise DaemonUnavailableError(f"Daemon RPC failed: {exc}") from exc
+
+            if body.ok:
+                return body.result
+            exc_cls = _EXC_MAP.get(body.error_type or "", RuntimeError)
+            raise exc_cls(body.error or f"RPC {method} failed")
+
+        # Both attempts exhausted (e.g. ensure_daemon_running kept failing).
+        raise DaemonUnavailableError(
+            f"Daemon unreachable after retry: {last_exc}"
+        ) from last_exc

susops/core/browsers.py

@@ -0,0 +1,330 @@
+"""Cross-platform browser detection + PAC-aware launch.
+
+Single source of truth for browser metadata and launch logic so every
+frontend (TUI, macOS tray, Linux tray) shares one detection pipeline.
+
+Detection is **auto-discovery** — we scan platform-native registries for
+HTTP-scheme handlers and classify chromium-vs-firefox via well-known
+bundle-id / executable-name patterns. The result is that out-of-the-box
+forks (Chrome Beta/Canary, LibreWolf, Waterfox, Tor Browser, Arc, etc.)
+appear in the list without us maintaining a hardcoded table.
+
+Public API:
+    detect_browsers()           → list[Browser]
+    launch_with_pac(browser, pac_url, profile_dir)
+    open_proxy_settings(browser)
+"""
+from __future__ import annotations
+
+import dataclasses
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+@dataclasses.dataclass(frozen=True)
+class Browser:
+    """A detected browser installation."""
+    name: str  # display name, e.g. "Chrome"
+    launch_cmd: list[str]  # base command, e.g. ["open", "-a", "Google Chrome"] or ["/usr/bin/google-chrome"]
+    is_chromium: bool  # True for Chrome/Brave/Edge/Vivaldi/Chromium/Arc; False for Firefox-family
+    bundle: str | None = None  # macOS app-bundle name (None on Linux)
+
+
+_PROXY_SETTINGS_URL = "chrome://net-internals/#proxy"
+
+# Bundle-id substrings that mark a browser as chromium-family on macOS.
+# Match is case-insensitive `in` substring (so "google.chrome.beta" matches).
+_MAC_CHROMIUM_BUNDLE_IDS = (
+    "com.google.chrome",
+    "com.brave.browser",
+    "org.chromium",
+    "com.microsoft.edgemac",
+    "com.vivaldi",
+    "com.thebrowser.browser",  # Arc
+    "company.thebrowser.browser",
+    "com.operasoftware.opera",
+)
+
+# Same for Firefox-family. Anything matching neither is dropped (e.g. Safari
+# can't be steered via `--proxy-pac-url` or chrome://-style URLs, so we
+# don't surface it).
+_MAC_FIREFOX_BUNDLE_IDS = (
+    "org.mozilla.firefox",
+    "org.mozilla.nightly",
+    "io.gitlab.librewolf",
+    "net.waterfox",
+    "org.torproject.torbrowser",
+)
+
+# Linux: executable basename substrings (case-insensitive).
+_LINUX_CHROMIUM_EXES = (
+    "google-chrome", "chrome", "chromium",
+    "brave", "vivaldi", "microsoft-edge", "edge", "opera",
+    "arc",  # speculative as Arc on Linux is in beta as of writing
+)
+_LINUX_FIREFOX_EXES = (
+    "firefox", "librewolf", "waterfox", "torbrowser", "tor-browser",
+)
+
+
+def detect_browsers() -> list[Browser]:
+    """Return browsers detected on the current platform.
+
+    Result is ordered: chromium-family first (alphabetized by display name),
+    Firefox-family last. Order matters for UX — chromium-style PAC support
+    is more reliable, so it goes first in pickers.
+    """
+    if sys.platform == "darwin":
+        browsers = _detect_macos()
+    else:
+        browsers = _detect_linux()
+    return sorted(browsers, key=lambda b: (not b.is_chromium, b.name.lower()))
+
+
+# ---------------------------------------------------------------------------
+# macOS — scan .app bundles for HTTP-scheme handlers via Info.plist
+# ---------------------------------------------------------------------------
+
+
+def _detect_macos() -> list[Browser]:
+    import plistlib
+
+    found: list[Browser] = []
+    seen_bundles: set[str] = set()
+    candidate_dirs = [Path("/Applications"), Path.home() / "Applications"]
+    for d in candidate_dirs:
+        if not d.is_dir():
+            continue
+        for app_dir in d.glob("*.app"):
+            bundle_name = app_dir.stem  # e.g. "Google Chrome"
+            if bundle_name in seen_bundles:
+                continue
+            plist_path = app_dir / "Contents" / "Info.plist"
+            if not plist_path.is_file():
+                continue
+            try:
+                with open(plist_path, "rb") as f:
+                    info = plistlib.load(f)
+            except Exception:
+                continue
+            if not _macos_handles_http(info):
+                continue
+            bundle_id = (info.get("CFBundleIdentifier") or "").lower()
+            is_chromium = any(p in bundle_id for p in _MAC_CHROMIUM_BUNDLE_IDS)
+            is_firefox = any(p in bundle_id for p in _MAC_FIREFOX_BUNDLE_IDS)
+            if not (is_chromium or is_firefox):
+                # Safari/Firefox can't accept a PAC URL via the command line
+                continue
+            seen_bundles.add(bundle_name)
+            display_name = (
+                    info.get("CFBundleDisplayName")
+                    or info.get("CFBundleName")
+                    or bundle_name
+            )
+            found.append(Browser(
+                name=str(display_name),
+                launch_cmd=["open", "-a", bundle_name],
+                is_chromium=is_chromium,
+                bundle=bundle_name,
+            ))
+    return found
+
+
+def _macos_handles_http(info: dict) -> bool:
+    """Return True if the Info.plist declares an http/https URL handler."""
+    for url_type in info.get("CFBundleURLTypes", []) or []:
+        for scheme in url_type.get("CFBundleURLSchemes", []) or []:
+            if str(scheme).lower() in ("http", "https"):
+                return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Linux — scan .desktop files in standard XDG application directories
+# ---------------------------------------------------------------------------
+
+
+def _detect_linux() -> list[Browser]:
+    import os
+
+    desktop_dirs: list[Path] = []
+    xdg_data_dirs = os.environ.get(
+        "XDG_DATA_DIRS", "/usr/local/share:/usr/share"
+    ).split(":")
+    xdg_data_home = os.environ.get(
+        "XDG_DATA_HOME", str(Path.home() / ".local" / "share")
+    )
+    for base in [xdg_data_home, *xdg_data_dirs]:
+        p = Path(base) / "applications"
+        if p.is_dir():
+            desktop_dirs.append(p)
+    # Flatpak / Snap exports often land here too.
+    for extra in (
+            Path("/var/lib/flatpak/exports/share/applications"),
+            Path.home() / ".local" / "share" / "flatpak" / "exports" / "share" / "applications",
+            Path("/var/lib/snapd/desktop/applications"),
+    ):
+        if extra.is_dir():
+            desktop_dirs.append(extra)
+
+    found: list[Browser] = []
+    seen_exes: set[str] = set()
+    for d in desktop_dirs:
+        for path in d.glob("*.desktop"):
+            entry = _parse_desktop_entry(path)
+            if entry is None:
+                continue
+            if not _linux_handles_http(entry):
+                continue
+            exec_cmd = _linux_resolve_exec(entry.get("Exec", ""))
+            if not exec_cmd:
+                continue
+            exe_path = exec_cmd[0]
+            exe_basename = Path(exe_path).name.lower()
+            if exe_basename in seen_exes:
+                continue
+            is_chromium = any(p in exe_basename for p in _LINUX_CHROMIUM_EXES)
+            is_firefox = any(p in exe_basename for p in _LINUX_FIREFOX_EXES)
+            if not (is_chromium or is_firefox):
+                continue
+            seen_exes.add(exe_basename)
+            display_name = entry.get("Name", exe_basename)
+            found.append(Browser(
+                name=display_name,
+                launch_cmd=[exe_path],
+                is_chromium=is_chromium,
+            ))
+    return found
+
+
+def _parse_desktop_entry(path: Path) -> dict | None:
+    """Parse the [Desktop Entry] section of a .desktop file into a dict.
+
+    Returns None if the file isn't a valid desktop entry (NoDisplay=true,
+    Type != Application, etc.).
+    """
+    try:
+        text = path.read_text(errors="replace")
+    except OSError:
+        return None
+    entry: dict = {}
+    in_section = False
+    for line in text.splitlines():
+        line = line.strip()
+        if line.startswith("[Desktop Entry]"):
+            in_section = True
+            continue
+        if line.startswith("[") and in_section:
+            break
+        if not in_section or "=" not in line or line.startswith("#"):
+            continue
+        key, _, value = line.partition("=")
+        # Skip locale-specific variants (Name[de], etc.)
+        if "[" in key:
+            continue
+        entry.setdefault(key.strip(), value.strip())
+    if entry.get("Type", "Application") != "Application":
+        return None
+    if entry.get("NoDisplay", "false").lower() == "true":
+        return None
+    if entry.get("Hidden", "false").lower() == "true":
+        return None
+    return entry
+
+
+def _linux_handles_http(entry: dict) -> bool:
+    mime = entry.get("MimeType", "")
+    return ("x-scheme-handler/http" in mime) or ("x-scheme-handler/https" in mime)
+
+
+def _linux_resolve_exec(exec_field: str) -> list[str]:
+    """Resolve the Exec= field to an absolute command list.
+
+    `Exec=` may contain field codes (%u, %U, %f, %F) — we strip them.
+    The first token is the executable; we resolve it via shutil.which if
+    it's not already an absolute path. Returns [] if the executable can't
+    be found on PATH (skip it).
+    """
+    if not exec_field:
+        return []
+    # Strip %X field codes, they're placeholders for URL/file args
+    tokens = [t for t in exec_field.split() if not (t.startswith("%") and len(t) == 2)]
+    if not tokens:
+        return []
+    exe = tokens[0]
+    if not exe.startswith("/"):
+        resolved = shutil.which(exe)
+        if resolved is None:
+            return []
+        exe = resolved
+    return [exe, *tokens[1:]]
+
+
+# ---------------------------------------------------------------------------
+# Launch
+# ---------------------------------------------------------------------------
+
+
+def launch_with_pac(browser: Browser, pac_url: str,
+                    profile_dir: Path | None = None) -> None:
+    """Launch the browser with PAC URL pre-configured.
+
+    Chromium-family: passed as ``--proxy-pac-url=<url>``. macOS uses
+    ``open -na`` so a new instance picks up the flag rather than the
+    existing process ignoring it.
+
+    Firefox: requires a profile directory with ``user.js`` written —
+    Firefox doesn't accept a PAC URL via command-line flag. The caller
+    is expected to provide a workspace-owned profile dir; we write the
+    prefs and launch with ``-profile <dir> -no-remote``.
+
+    Raises subprocess.SubprocessError or OSError on launch failure;
+    caller is responsible for surfacing.
+    """
+    if browser.is_chromium:
+        if sys.platform == "darwin" and browser.bundle is not None:
+            cmd = ["open", "-na", browser.bundle, "--args", f"--proxy-pac-url={pac_url}"]
+        else:
+            cmd = browser.launch_cmd + [f"--proxy-pac-url={pac_url}"]
+        subprocess.Popen(cmd)
+        return
+
+    # Firefox path
+    if profile_dir is None:
+        raise ValueError(
+            "Firefox launch requires a profile_dir (Firefox doesn't accept "
+            "a PAC URL as a command-line flag)."
+        )
+    profile_dir.mkdir(parents=True, exist_ok=True)
+    (profile_dir / "user.js").write_text(
+        f'user_pref("network.proxy.type", 2);\n'
+        f'user_pref("network.proxy.autoconfig_url", "{pac_url}");\n'
+        f'user_pref("network.proxy.no_proxies_on", "localhost, 127.0.0.1");\n'
+    )
+    if sys.platform == "darwin" and browser.bundle is not None:
+        cmd = ["open", "-na", browser.bundle, "--args",
+               "-profile", str(profile_dir), "-no-remote"]
+    else:
+        cmd = browser.launch_cmd + ["-profile", str(profile_dir), "-no-remote"]
+    subprocess.Popen(cmd)
+
+
+def open_proxy_settings(browser: Browser) -> None:
+    """Open the browser at its internal proxy debug page.
+
+    Chromium-family browsers interpret ``chrome://net-internals/#proxy``
+    as an internal page; macOS ``open -a <bundle> <url>`` and Linux
+    ``<exe> <url>`` both navigate straight to it.
+
+    Firefox doesn't have a single chrome://-style proxy debug URL, so
+    this is a no-op for non-Chromium browsers.
+    """
+    if not browser.is_chromium:
+        return
+    if sys.platform == "darwin" and browser.bundle is not None:
+        cmd = ["open", "-a", browser.bundle, _PROXY_SETTINGS_URL]
+    else:
+        cmd = browser.launch_cmd + [_PROXY_SETTINGS_URL]
+    subprocess.Popen(cmd)