susops 3.0.0rc3.dev1__py3-none-any.whl

susops/core/process.py

@@ -0,0 +1,167 @@
+"""Process lifecycle management for SusOps via PID files."""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import time
+from pathlib import Path
+
+__all__ = ["ProcessManager"]
+
+
+class ProcessManager:
+    """Manages long-running background processes via PID files.
+
+    PID files are stored in <workspace>/pids/<name>.pid.
+    This replaces the exec -a / pgrep -f approach used in the Bash CLI.
+    """
+
+    def __init__(self, workspace: Path) -> None:
+        self._pids_dir = workspace / "pids"
+        self._pids_dir.mkdir(parents=True, exist_ok=True)
+
+    def _pid_file(self, name: str) -> Path:
+        return self._pids_dir / f"{name}.pid"
+
+    def start(
+            self,
+            name: str,
+            cmd: list[str],
+            env: dict[str, str] | None = None,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+    ) -> int:
+        """Start a process and record its PID.
+
+        Returns the PID. Raises RuntimeError if process fails to start.
+        """
+        import os as _os
+        proc = subprocess.Popen(
+            cmd,
+            env={**_os.environ, **(env or {})},
+            stdin=subprocess.DEVNULL,
+            stdout=stdout,
+            stderr=stderr,
+            start_new_session=True,  # detach from terminal
+        )
+        pid = proc.pid
+        pid_file = self._pid_file(name)
+        pid_file.parent.mkdir(parents=True, exist_ok=True)
+        pid_file.write_text(str(pid))
+        return pid
+
+    def stop(self, name: str, force: bool = False) -> bool:
+        """Stop a process by name. Returns True if stopped, False if not running."""
+        pid = self.get_pid(name)
+        if pid is None:
+            return False
+        try:
+            sig = signal.SIGKILL if force else signal.SIGTERM
+            os.kill(pid, sig)
+            # Wait briefly for process to exit
+            for _ in range(20):
+                time.sleep(0.1)
+                try:
+                    os.kill(pid, 0)  # check if still alive
+                except ProcessLookupError:
+                    break
+        except ProcessLookupError:
+            pass  # already gone
+        finally:
+            pid_file = self._pid_file(name)
+            if pid_file.exists():
+                pid_file.unlink()
+            # Reap the zombie if this process is a direct child. (always wanted to write this as a code comment LOL)
+            try:
+                os.waitpid(pid, os.WNOHANG)
+            except ChildProcessError:
+                pass  # not our child or already reaped
+            except OSError:
+                pass
+        return True
+
+    def is_running(self, name: str) -> bool:
+        """Return True if the named process is currently running (not a zombie)."""
+        pid = self.get_pid(name)
+        if pid is None:
+            return False
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True  # exists, not our process, but it's running
+        # Process exists in the table, check whether it's a zombie.
+        # Zombies respond to kill(0) but can't do any real work.
+        # Reading /proc is Linux-only, on other platforms we trust kill(0).
+        try:
+            status = Path(f"/proc/{pid}/status").read_text()
+            for line in status.splitlines():
+                if line.startswith("State:") and "Z" in line:
+                    # Reap it (only works if we're the parent)
+                    try:
+                        os.waitpid(pid, os.WNOHANG)
+                    except (ChildProcessError, OSError):
+                        pass
+                    self._pid_file(name).unlink(missing_ok=True)
+                    return False
+        except OSError:
+            pass  # /proc not available or pid already gone
+        return True
+
+    def get_pid(self, name: str) -> int | None:
+        """Return the PID for a named process, or None if not tracked."""
+        pid_file = self._pid_file(name)
+        if not pid_file.exists():
+            return None
+        try:
+            return int(pid_file.read_text().strip())
+        except (ValueError, OSError):
+            return None
+
+    # Process names that kill_all() must NEVER touch — these belong to the
+    # services daemon itself (which is the process *calling* kill_all). Killing
+    # them would make the daemon SIGTERM itself, taking down PAC + RPC and
+    # making subsequent ensure_daemon_running calls race with the dying
+    # daemon's PID file.
+    _KILL_ALL_BLACKLIST = frozenset({"susops-services"})
+
+    def kill_all(self) -> None:
+        """Send SIGTERM to every tracked process and remove PID files. Non-blocking.
+
+        Skips the services daemon's own pid file — see _KILL_ALL_BLACKLIST.
+        """
+        for pid_file in list(self._pids_dir.glob("*.pid")):
+            if pid_file.stem in self._KILL_ALL_BLACKLIST:
+                continue
+            try:
+                pid = int(pid_file.read_text().strip())
+                os.kill(pid, signal.SIGTERM)
+            except (ValueError, OSError, ProcessLookupError):
+                pass
+            try:
+                pid_file.unlink()
+            except OSError:
+                pass
+
+    def status_all(self) -> dict[str, bool]:
+        """Return a dict of {name: is_running} for all tracked processes."""
+        result = {}
+        for pid_file in self._pids_dir.glob("*.pid"):
+            name = pid_file.stem
+            result[name] = self.is_running(name)
+        return result
+
+    def cleanup_stale(self) -> list[str]:
+        """Remove PID files for processes that are no longer running.
+
+        Returns list of cleaned-up names.
+        """
+        cleaned = []
+        for pid_file in self._pids_dir.glob("*.pid"):
+            name = pid_file.stem
+            if not self.is_running(name):
+                pid_file.unlink()
+                cleaned.append(name)
+        return cleaned

susops/core/rpc_protocol.py

@@ -0,0 +1,186 @@
+"""JSON-over-HTTP RPC protocol for the susops-services daemon.
+
+Encodes facade arguments / return values losslessly. Pydantic models are
+serialized via model_dump(); dataclasses via asdict(); enums via .value
+with a type tag so the client can rebuild the exact type. Anything else
+serializable by json.dumps passes through unchanged.
+"""
+from __future__ import annotations
+
+import dataclasses
+import enum
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+# Registry of known reconstructable types. Populated lazily to avoid
+# import cycles with the facade.
+_REGISTRY: dict[str, type] = {}
+
+
+def _registry() -> dict[str, type]:
+    if _REGISTRY:
+        return _REGISTRY
+    from susops.core.config import (
+        AppConfig,
+        Connection,
+        FileShare,
+        Forwards,
+        PortForward,
+        SusOpsConfig,
+    )
+    from susops.core.types import (
+        ConnectionStatus,
+        LogoStyle,
+        ProcessState,
+        ShareInfo,
+        StartResult,
+        StatusResult,
+        StopResult,
+        TestResult,
+    )
+    _REGISTRY.update({
+        "Connection": Connection,
+        "FileShare": FileShare,
+        "PortForward": PortForward,
+        "SusOpsConfig": SusOpsConfig,
+        "AppConfig": AppConfig,
+        "Forwards": Forwards,
+        "ConnectionStatus": ConnectionStatus,
+        "LogoStyle": LogoStyle,
+        "ProcessState": ProcessState,
+        "ShareInfo": ShareInfo,
+        "StartResult": StartResult,
+        "StatusResult": StatusResult,
+        "StopResult": StopResult,
+        "TestResult": TestResult,
+        "Path": Path,
+    })
+    return _REGISTRY
+
+
+def encode_value(v: Any) -> Any:
+    """Recursively encode a Python value to a JSON-safe structure."""
+    if v is None or isinstance(v, (bool, int, float, str)):
+        return v
+    if isinstance(v, Path):
+        return {"__type__": "Path", "value": str(v)}
+    # Enums BEFORE BaseModel/dataclass checks so a Pydantic-model-with-enum-field
+    # won't accidentally match the model branch.
+    if isinstance(v, enum.Enum):
+        return {"__type__": type(v).__name__, "value": v.value}
+    if isinstance(v, BaseModel):
+        return {"__type__": type(v).__name__, "value": v.model_dump(mode="json")}
+    if dataclasses.is_dataclass(v) and not isinstance(v, type):
+        # Encode field-by-field via encode_value rather than dataclasses.asdict()
+        # — asdict() recursively flattens nested dataclasses (and tuples) into
+        # plain dicts/lists, throwing away the __type__ tags the decoder needs
+        # to reconstruct the original types. Going through encode_value keeps
+        # ConnectionStatus / TestResult / etc. tagged inside their parents.
+        encoded = {
+            f.name: encode_value(getattr(v, f.name))
+            for f in dataclasses.fields(v)
+        }
+        return {"__type__": type(v).__name__, "value": encoded}
+    if isinstance(v, (list, tuple)):
+        return [encode_value(x) for x in v]
+    if isinstance(v, (set, frozenset)):
+        # JSON has no native set type — flatten to a list. Sort for
+        # deterministic output. Callers that need set semantics on the
+        # other end can `set(...)` it themselves.
+        return [encode_value(x) for x in sorted(v, key=repr)]
+    if isinstance(v, dict):
+        return _encode_dict(v)
+    raise TypeError(f"Cannot encode value of type {type(v).__name__}: {v!r}")
+
+
+def _encode_dict(d: dict) -> dict:
+    return {k: encode_value(val) for k, val in d.items()}
+
+
+def decode_arg(v: Any) -> Any:
+    """Recursively decode a JSON-safe structure back into Python objects."""
+    if v is None or isinstance(v, (bool, int, float, str)):
+        return v
+    if isinstance(v, list):
+        return [decode_arg(x) for x in v]
+    if isinstance(v, dict):
+        if "__type__" in v and "value" in v:
+            return _decode_tagged(v["__type__"], v["value"])
+        return {k: decode_arg(val) for k, val in v.items()}
+    return v
+
+
+def _decode_tagged(type_name: str, value: Any) -> Any:
+    cls = _registry().get(type_name)
+    if cls is None:
+        raise ValueError(f"Unknown RPC type tag: {type_name}")
+    if cls is Path:
+        return Path(value)
+    if isinstance(cls, type) and issubclass(cls, enum.Enum):
+        return cls(value)
+    if isinstance(cls, type) and issubclass(cls, BaseModel):
+        return cls.model_validate(value)
+    if dataclasses.is_dataclass(cls):
+        # Recursively decode nested fields so dataclasses-containing-models work.
+        kwargs = {}
+        for name, raw in value.items():
+            if isinstance(raw, dict) and "__type__" in raw:
+                kwargs[name] = decode_arg(raw)
+            elif isinstance(raw, list):
+                kwargs[name] = [decode_arg(x) for x in raw]
+            else:
+                kwargs[name] = raw
+        return cls(**kwargs)
+    raise ValueError(f"Don't know how to reconstruct type: {type_name}")
+
+
+@dataclasses.dataclass
+class InvocationRequest:
+    method: str
+    args: list = dataclasses.field(default_factory=list)
+    kwargs: dict = dataclasses.field(default_factory=dict)
+
+    def to_json(self) -> str:
+        return json.dumps({
+            "method": self.method,
+            "args": encode_value(self.args),
+            "kwargs": encode_value(self.kwargs),
+        })
+
+    @classmethod
+    def from_json(cls, payload: str) -> "InvocationRequest":
+        data = json.loads(payload)
+        return cls(
+            method=data["method"],
+            args=[decode_arg(a) for a in data.get("args", [])],
+            kwargs={k: decode_arg(v) for k, v in data.get("kwargs", {}).items()},
+        )
+
+
+@dataclasses.dataclass
+class InvocationResponse:
+    ok: bool
+    result: Any = None
+    error: str | None = None
+    error_type: str | None = None
+
+    def to_json(self) -> str:
+        return json.dumps({
+            "ok": self.ok,
+            "result": encode_value(self.result),
+            "error": self.error,
+            "error_type": self.error_type,
+        })
+
+    @classmethod
+    def from_json(cls, payload: str) -> "InvocationResponse":
+        data = json.loads(payload)
+        return cls(
+            ok=data["ok"],
+            result=decode_arg(data.get("result")),
+            error=data.get("error"),
+            error_type=data.get("error_type"),
+        )

susops/core/rpc_server.py

@@ -0,0 +1,131 @@
+"""aiohttp server hosting the JSON-over-HTTP RPC endpoint.
+
+Dispatches `InvocationRequest.method` to the named method on `SusOpsManager`.
+Methods are looked up by attribute access; private methods (leading
+underscore) are rejected to prevent direct access to internal helpers.
+Anything outside the allowlist below is rejected too — deny-by-default.
+"""
+from __future__ import annotations
+
+import logging
+
+from aiohttp import web
+
+from susops.core.rpc_protocol import (
+    InvocationRequest,
+    InvocationResponse,
+)
+
+log = logging.getLogger("susops.services.rpc")
+
+# Methods explicitly exposed to RPC clients. Deny by default.
+_ALLOWED_METHODS: set[str] = {
+    # Lifecycle
+    "start", "stop", "restart", "status", "stop_quick",
+    # Config introspection
+    "list_config",
+    # Connection CRUD
+    "add_connection", "remove_connection", "set_connection_enabled",
+    # PAC hosts
+    "add_pac_host", "remove_pac_host", "set_pac_host_enabled",
+    # Forwards
+    "add_local_forward", "add_remote_forward",
+    "remove_local_forward", "remove_remote_forward",
+    "toggle_forward_enabled", "set_forward_enabled",
+    "is_udp_forward_running",
+    # File sharing
+    "share", "stop_share", "delete_share", "list_shares",
+    "share_is_running", "fetch",
+    # Testing
+    "test", "test_all", "test_connection", "test_domain", "test_forward",
+    "test_ssh",
+    # App-level
+    "reset", "update_app_config", "update_config",
+    # URLs
+    "get_pac_url", "get_status_url",
+    # Bandwidth
+    "get_bandwidth", "get_bandwidth_totals", "get_bandwidth_global",
+    # Reconnect introspection
+    "reconnect_monitor_info",
+    # Process introspection
+    "process_info",  # global — used by `susops ps`
+    "get_process_info",  # per-tag — used by TUI dashboard
+    "get_uptime",  # per-tag — used by TUI dashboard / connections panel
+    "get_logs",  # used by TUI logs panel
+    "log_message",  # frontends push operational notes into the daemon log buffer
+}
+
+
+async def _handle_rpc(request: web.Request) -> web.Response:
+    mgr = request.app["manager"]
+    try:
+        payload = await request.text()
+        req = InvocationRequest.from_json(payload)
+    except Exception as exc:
+        log.exception("Malformed RPC request")
+        resp = InvocationResponse(ok=False, error=str(exc), error_type=type(exc).__name__)
+        return web.Response(text=resp.to_json(), status=400, content_type="application/json")
+
+    if req.method.startswith("_") or req.method not in _ALLOWED_METHODS:
+        resp = InvocationResponse(
+            ok=False,
+            error=f"method '{req.method}' not allowed",
+            error_type="AttributeError",
+        )
+        return web.Response(text=resp.to_json(), status=404, content_type="application/json")
+
+    method = getattr(mgr, req.method, None)
+    if method is None or not callable(method):
+        resp = InvocationResponse(
+            ok=False,
+            error=f"no callable named '{req.method}'",
+            error_type="AttributeError",
+        )
+        return web.Response(text=resp.to_json(), status=404, content_type="application/json")
+
+    try:
+        result = method(*req.args, **req.kwargs)
+        resp = InvocationResponse(ok=True, result=result)
+        return web.Response(text=resp.to_json(), content_type="application/json")
+    except Exception as exc:
+        log.exception("RPC %s failed", req.method)
+        resp = InvocationResponse(
+            ok=False,
+            error=str(exc),
+            error_type=type(exc).__name__,
+        )
+        return web.Response(text=resp.to_json(), status=500, content_type="application/json")
+
+
+def build_app(manager) -> web.Application:
+    """Build the aiohttp Application that exposes /rpc."""
+    app = web.Application()
+    app["manager"] = manager
+    app.router.add_post("/rpc", _handle_rpc)
+    return app
+
+
+def serve(manager, host: str = "127.0.0.1", port: int = 0) -> tuple:
+    """Start the RPC server on a background daemon thread with its own event loop.
+
+    Returns (runner, actual_port). The runner can be cleaned up by calling
+    `await runner.cleanup()` from any asyncio context, or by calling
+    `runner.shutdown()` synchronously (less clean). For daemon shutdown the
+    process exit handles it.
+    """
+    import asyncio
+    import threading
+
+    loop = asyncio.new_event_loop()
+    app = build_app(manager)
+    runner = web.AppRunner(app)
+    loop.run_until_complete(runner.setup())
+    site = web.TCPSite(runner, host=host, port=port)
+    loop.run_until_complete(site.start())
+    # Bound port (in case 0 was requested)
+    sock_list = list(site._server.sockets) if site._server is not None else []
+    actual_port = sock_list[0].getsockname()[1] if sock_list else port
+
+    thread = threading.Thread(target=loop.run_forever, daemon=True, name="susops-rpc")
+    thread.start()
+    return runner, actual_port