susops 3.0.0rc3.dev1__py3-none-any.whl

susops/core/config.py

@@ -0,0 +1,253 @@
+"""Config module for SusOps.
+
+Defines all Pydantic v2 config models and handles reading/writing
+~/.susops/config.yaml using ruamel.yaml for comment preservation.
+
+Models:
+  - PortForward: A single port forward rule (local or remote)
+  - Forwards: Container for local and remote port forward lists
+  - Connection: A single SSH connection configuration
+  - AppConfig: Application-level settings
+  - SusOpsConfig: Root config model
+
+I/O Functions:
+  - get_config_path: Resolve path to config.yaml
+  - load_config: Load config from disk, creating defaults if missing
+  - save_config: Persist config to disk with ruamel.yaml
+
+Helper Functions:
+  - get_connection: Find a connection by tag
+  - get_default_connection: Return the first connection or None
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, field_validator, model_validator
+from ruamel.yaml import YAML
+
+from susops.core.types import LogoStyle
+
+__all__ = [
+    "PortForward",
+    "Forwards",
+    "FileShare",
+    "Connection",
+    "AppConfig",
+    "SusOpsConfig",
+    "get_config_path",
+    "load_config",
+    "save_config",
+    "get_connection",
+    "get_default_connection",
+    "WORKSPACE_DEFAULT",
+    "CONFIG_FILENAME",
+]
+
+WORKSPACE_DEFAULT = Path.home() / ".susops"
+CONFIG_FILENAME = "config.yaml"
+
+
+class PortForward(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    tag: str = ""
+    src_addr: str = "localhost"
+    src_port: int
+    dst_addr: str = "localhost"
+    dst_port: int
+    tcp: bool = True
+    udp: bool = False
+    enabled: bool = True
+
+    @model_validator(mode="before")
+    @classmethod
+    def handle_legacy_schema(cls, data: Any) -> Any:
+        """Handle old schema where 'src'/'dst' were plain port numbers."""
+        if isinstance(data, dict) and "src" in data and "src_port" not in data:
+            data = dict(data)
+            data["src_port"] = int(data.pop("src"))
+            data["dst_port"] = int(data.pop("dst", data["src_port"]))
+        return data
+
+    @model_validator(mode="after")
+    def require_at_least_one_protocol(self) -> "PortForward":
+        # Runs after handle_legacy_schema has already normalised the dict,
+        # so self.tcp and self.udp are already coerced to bool.
+        if not self.tcp and not self.udp:
+            raise ValueError("At least one of tcp/udp must be True")
+        return self
+
+
+class Forwards(BaseModel):
+    local: list[PortForward] = []
+    remote: list[PortForward] = []
+
+
+class FileShare(BaseModel):
+    """A persisted file share associated with a connection."""
+
+    file_path: str
+    password: str
+    port: int = 0  # 0 = auto-assigned, written back after first start
+    stopped: bool = False  # True when manually stopped — not auto-restarted
+
+
+class Connection(BaseModel):
+    tag: str
+    ssh_host: str
+    socks_proxy_port: int = 0
+    enabled: bool = True
+    forwards: Forwards = Forwards()
+    pac_hosts: list[str] = []
+    pac_hosts_disabled: list[str] = []
+    file_shares: list[FileShare] = []
+
+
+class AppConfig(BaseModel):
+    stop_on_quit: bool = True
+    ephemeral_ports: bool = False
+    logo_style: LogoStyle = LogoStyle.COLORED_GLASSES
+    restore_shares_on_start: bool = True
+    tray_show_bandwidth: bool = False
+
+    @field_validator(
+        "stop_on_quit",
+        "ephemeral_ports",
+        "restore_shares_on_start",
+        "tray_show_bandwidth",
+        mode="before",
+    )
+    @classmethod
+    def coerce_bool_string(cls, v: Any) -> Any:
+        """Handle "1"/"0" string values from old yq-based config."""
+        if isinstance(v, str):
+            return v.strip() in ("1", "true", "True", "yes")
+        return v
+
+    @field_validator("logo_style", mode="before")
+    @classmethod
+    def coerce_logo_style(cls, v: Any) -> Any:
+        if isinstance(v, str):
+            return LogoStyle(v)
+        return v
+
+
+class SusOpsConfig(BaseModel):
+    # Server ports are at the top of the config so they're the first thing
+    # users see when they open the file. All three default to 0 (auto-allocate
+    # at startup and write back).
+    rpc_server_port: int = 0
+    status_server_port: int = 0
+    pac_server_port: int = 0
+    connections: list[Connection] = []
+    susops_app: AppConfig = AppConfig()
+
+    @model_validator(mode="before")
+    @classmethod
+    def _migrate_status_server_port(cls, data: Any) -> Any:
+        """Pull legacy susops_app.status_server_port up to the top level.
+        """
+        if not isinstance(data, dict):
+            return data
+        app = data.get("susops_app")
+        if isinstance(app, dict) and "status_server_port" in app:
+            legacy = app.pop("status_server_port")
+            # Only adopt the legacy value when the new field isn't already set
+            # to something non-default.
+            if not data.get("status_server_port"):
+                data["status_server_port"] = legacy
+        return data
+
+
+def get_config_path(workspace: Path = WORKSPACE_DEFAULT) -> Path:
+    """Return the path to config.yaml within the given workspace directory."""
+    return workspace / CONFIG_FILENAME
+
+
+def load_config(workspace: Path = WORKSPACE_DEFAULT) -> SusOpsConfig:
+    """Load config from workspace/config.yaml. Creates default config if missing."""
+    path = get_config_path(workspace)
+    if not path.exists():
+        config = SusOpsConfig()
+        save_config(config, workspace)
+        return config
+    yaml = YAML()
+    data = yaml.load(path)
+    if data is None:
+        return SusOpsConfig()
+    return SusOpsConfig.model_validate(dict(data))
+
+
+def save_config(config: SusOpsConfig, workspace: Path = WORKSPACE_DEFAULT) -> None:
+    """Save config to workspace/config.yaml using ruamel.yaml for comment preservation.
+
+    Writes atomically (to a temp file, then POSIX rename) so a concurrent
+    load_config never observes a half-written or freshly-truncated file. The
+    old behavior — `open(path, 'w')` — truncated the file to 0 bytes before
+    `yaml.dump` ran; a reader in that window got an empty file → empty config →
+    and any save that followed wiped the connections list. The TUI's
+    `@work(thread=True)` makes this a real (and reported) race on rapid Stop
+    clicks.
+    """
+    import os
+    path = get_config_path(workspace)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    yaml = YAML()
+    yaml.default_flow_style = False
+    yaml.indent(mapping=2, sequence=4, offset=2)
+    # Convert to plain dict via model_dump, then save
+    data = config.model_dump(mode='python')
+    # Convert enums to their values for serialization
+    data['susops_app']['logo_style'] = config.susops_app.logo_style.value
+    # Compute the target mode BEFORE writing: preserve any user-set restrictive
+    # permissions (e.g. chmod 600 on a hardened install) since Path.replace()
+    # would otherwise clobber them with the temp file's umask-derived mode.
+    # New configs default to 0o600 — the file holds share passwords.
+    try:
+        target_mode = path.stat().st_mode & 0o777
+    except OSError:
+        target_mode = 0o600
+    # Temp file in the same directory so the rename stays on one filesystem.
+    # Open with O_EXCL so we never overwrite a leftover temp file from a
+    # crashed earlier save (would otherwise inherit its mode).
+    tmp_path = path.with_name(path.name + ".tmp")
+    try:
+        fd = os.open(
+            str(tmp_path),
+            os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+            target_mode,
+        )
+        try:
+            with os.fdopen(fd, 'w') as f:
+                yaml.dump(data, f)
+        except Exception:
+            # fdopen owns fd on success; on failure we may need to close it
+            # if fdopen never took ownership. Best-effort.
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+            raise
+
+        os.chmod(tmp_path, target_mode)
+        tmp_path.replace(path)
+    except Exception:
+        # Best-effort cleanup of the temp file if writing failed.
+        try:
+            tmp_path.unlink(missing_ok=True)
+        except Exception:
+            pass
+        raise
+
+
+def get_connection(config: SusOpsConfig, tag: str) -> Connection | None:
+    """Find a connection by tag."""
+    return next((c for c in config.connections if c.tag == tag), None)
+
+
+def get_default_connection(config: SusOpsConfig) -> Connection | None:
+    """Return the first connection, or None if there are none."""
+    return config.connections[0] if config.connections else None

susops/core/log_style.py

@@ -0,0 +1,92 @@
+"""Shared log-line styler.
+
+Splits a raw log line into colored segments. Used by every frontend (TUI's
+RichLog, the macOS NSTextView, the Linux GtkTextView) so the colour rules
+stay consistent across surfaces.
+
+Each segment is a ``(text, color)`` tuple where ``color`` is one of:
+
+    None     — default text colour
+    "tag"    — connection / debug tag prefix (cyan)
+    "ok"     — success keywords (green)
+    "warn"   — non-fatal status keywords (yellow)
+    "err"    — failure keywords (red)
+    "dim"    — supplementary detail like PID numbers (gray)
+    "info"   — neutral highlight (blue)
+
+Frontends map these labels to concrete colours.
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Tuple
+
+LogSegment = Tuple[str, str | None]
+
+# Order matters — first match wins per character offset. Earlier entries take
+# precedence when ranges overlap.
+_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    # Timestamp at the very start of the line: [HH:MM:SS]. Must match before
+    # the generic "tag prefix" rule so the clock doesn't get coloured like a
+    # connection tag.
+    (re.compile(r"^\[\d{2}:\d{2}:\d{2}\]"), "dim"),
+    # Tag prefix at the start of the line: [pi3]  or  [debug]  or  [error].
+    # Anchored to either the line start or the position immediately after a
+    # timestamp + space so both `[pi3] ...` and `[16:42:03] [pi3] ...` work.
+    (re.compile(r"(?:^|(?<=^\[\d{2}:\d{2}:\d{2}\] ))\[[^\]]+\]"), "tag"),
+    # Parenthesised PID detail (and similar dim suffixes).
+    (re.compile(r"\(PID \d+\)", re.IGNORECASE), "dim"),
+    (re.compile(r"\(pid=\d+\)", re.IGNORECASE), "dim"),
+    # Port numbers in "port 1234" / "on port 1234"
+    (re.compile(r"\b(?:on )?port \d+\b"), "info"),
+    # Warning / non-fatal status keywords (must come before "ok" so compound
+    # phrases like "already running" / "Connection lost" win over the lone
+    # "running" / "Connection restored" keywords).
+    (re.compile(
+        r"\b(Stopped|stopped|Disabled|disabled|skipping|skipped|"
+        r"already running|Connection lost|reconnecting|stale)\b"
+    ), "warn"),
+    # Success keywords.
+    (re.compile(
+        r"\b(Started|started|Restored|restored|Assigned|assigned|running|Running|"
+        r"Connected|connected|Connection restored|Reconnected)\b"
+    ), "ok"),
+    # Error keywords.
+    (re.compile(r"\b(Failed|failed|Error|error|crash(?:ed)?|denied)\b"), "err"),
+]
+
+
+def style_log_line(line: str) -> List[LogSegment]:
+    """Split ``line`` into colored segments using the rule table above.
+
+    Greedy first-match, non-overlapping. Regions not matched by any pattern
+    fall through as default-coloured text.
+    """
+    if not line:
+        return [("", None)]
+
+    # Collect all non-overlapping matches in source order.
+    spans: list[tuple[int, int, str]] = []
+    occupied = [False] * len(line)
+
+    for pat, label in _PATTERNS:
+        for m in pat.finditer(line):
+            s, e = m.start(), m.end()
+            if any(occupied[s:e]):
+                continue
+            spans.append((s, e, label))
+            for i in range(s, e):
+                occupied[i] = True
+
+    spans.sort(key=lambda t: t[0])
+
+    out: list[LogSegment] = []
+    cursor = 0
+    for s, e, label in spans:
+        if s > cursor:
+            out.append((line[cursor:s], None))
+        out.append((line[s:e], label))
+        cursor = e
+    if cursor < len(line):
+        out.append((line[cursor:], None))
+    return out

susops/core/pac.py

@@ -0,0 +1,185 @@
+"""PAC file generation and Python HTTP server for SusOps."""
+from __future__ import annotations
+
+import re
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from susops.core.config import SusOpsConfig
+
+from susops.core.ports import cidr_to_netmask
+
+__all__ = ["generate_pac", "write_pac_file", "PacServer"]
+
+_DIRECT = '"DIRECT"'
+
+
+def _is_wildcard(host: str) -> bool:
+    return "*" in host or "?" in host
+
+
+def _is_cidr(host: str) -> bool:
+    return re.match(r'^\d+\.\d+\.\d+\.\d+/\d+$', host) is not None
+
+
+def _pac_rule(host: str, socks_port: int) -> str:
+    """Generate a single PAC rule line for a host/CIDR/wildcard."""
+    proxy = f"SOCKS5 127.0.0.1:{socks_port}"
+    if _is_wildcard(host):
+        return f"  if (shExpMatch(host, '{host}')) return '{proxy}';"
+    if _is_cidr(host):
+        net, bits = host.split("/")
+        mask = cidr_to_netmask(int(bits))
+        return f"  if (isInNet(host, '{net}', '{mask}')) return '{proxy}';"
+    # Plain hostname
+    return f"  if (host == '{host}' || dnsDomainIs(host, '.{host}')) return '{proxy}';"
+
+
+def generate_pac(config: "SusOpsConfig", active_tags: set[str] | None = None) -> str:
+    """Generate the FindProxyForURL JavaScript PAC function.
+
+    When active_tags is provided, only connections in that set are included.
+    When None, includes all connections (legacy behavior).
+    """
+    lines = ["function FindProxyForURL(url, host) {"]
+
+    for conn in config.connections:
+        if conn.socks_proxy_port == 0:
+            continue
+        if active_tags is not None and conn.tag not in active_tags:
+            continue
+        for host in conn.pac_hosts:
+            lines.append(_pac_rule(host, conn.socks_proxy_port))
+
+    lines.append(f'  return {_DIRECT};')
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def write_pac_file(config: "SusOpsConfig", workspace: Path, active_tags: set[str] | None = None) -> Path:
+    """Write the PAC file to <workspace>/susops.pac and return its path."""
+    pac_path = workspace / "susops.pac"
+    pac_content = generate_pac(config, active_tags=active_tags)
+    pac_path.write_text(pac_content)
+    return pac_path
+
+
+class _PacHandler(BaseHTTPRequestHandler):
+    """HTTP handler that serves the PAC file."""
+
+    pac_path: Path  # set by PacServer before creating HTTPServer
+
+    def do_GET(self) -> None:
+        if self.path not in ("/susops.pac", "/"):
+            self.send_response(404)
+            self.end_headers()
+            return
+        try:
+            content = self.server.pac_path.read_bytes()  # type: ignore[attr-defined]
+        except OSError:
+            self.send_response(500)
+            self.end_headers()
+            return
+        self.send_response(200)
+        self.send_header("Content-Type", "application/x-ns-proxy-autoconfig")
+        self.send_header("Content-Length", str(len(content)))
+        self.send_header("Connection", "close")
+        self.end_headers()
+        self.wfile.write(content)
+
+    def do_POST(self) -> None:
+        """POST /stop — remote shutdown so other processes can stop this server."""
+        if self.path != "/stop":
+            self.send_response(404)
+            self.end_headers()
+            return
+        self.send_response(200)
+        self.end_headers()
+        # Shut down in a background thread so the response can be sent first
+        threading.Thread(target=self.server.shutdown, daemon=True).start()
+
+    def log_message(self, fmt: str, *args: object) -> None:
+        pass  # suppress default access log
+
+
+class _ReusableHTTPServer(HTTPServer):
+    """HTTPServer with SO_REUSEADDR enabled.
+
+    Python's default `HTTPServer.allow_reuse_address` is False, which means
+    re-binding to a just-released port can fail with EADDRINUSE during the
+    TCP TIME_WAIT window (~30 s on macOS/Linux). Without SO_REUSEADDR, when
+    the in-process server stops the port enters TIME_WAIT and the next bind
+    to the same port can silently fail — leaving the port file pointing at a
+    dead listener and subsequent starts unable to bind the port either.
+    """
+
+    allow_reuse_address = True
+
+
+class PacServer:
+    """Python HTTP server that serves the PAC file.
+
+    Runs in a daemon thread. Replaces the nc-based loop in the original bash CLI.
+    """
+
+    def __init__(self) -> None:
+        self._server: HTTPServer | None = None
+        self._thread: threading.Thread | None = None
+        self._port: int = 0
+        self._pac_path: Path | None = None
+
+    def start(self, port: int, pac_path: Path) -> None:
+        """Start the PAC HTTP server on the given port.
+
+        Raises RuntimeError if already running or if port is in use.
+        """
+        if self._server is not None:
+            raise RuntimeError("PAC server is already running")
+
+        self._pac_path = pac_path
+
+        # Create HTTPServer and attach pac_path so handler can access it
+        server = _ReusableHTTPServer(("127.0.0.1", port), _PacHandler)
+        server.pac_path = pac_path  # type: ignore[attr-defined]
+
+        self._server = server
+        self._port = server.server_address[1]  # actual port (in case 0 was given)
+
+        self._thread = threading.Thread(
+            target=server.serve_forever,
+            name="susops-pac-server",
+            daemon=True,
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the PAC HTTP server."""
+        if self._server is not None:
+            self._server.shutdown()
+            self._server.server_close()
+            self._server = None
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+            self._thread = None
+        self._port = 0
+
+    def is_running(self) -> bool:
+        """Return True if the server is currently running."""
+        return self._server is not None and self._thread is not None and self._thread.is_alive()
+
+    def get_port(self) -> int:
+        """Return the port the server is listening on (0 if not running)."""
+        return self._port
+
+    def get_pac_path(self) -> Path | None:
+        """Return the PAC file path currently being served."""
+        return self._pac_path
+
+    def reload(self, pac_path: Path) -> None:
+        """Update the PAC file path (takes effect on next request)."""
+        if self._server is not None:
+            self._server.pac_path = pac_path  # type: ignore[attr-defined]
+        self._pac_path = pac_path

susops/core/ports.py

@@ -0,0 +1,57 @@
+"""Port allocation, validation, and CIDR utilities for SusOps."""
+from __future__ import annotations
+
+import random
+import socket
+import struct
+
+__all__ = [
+    "get_random_free_port",
+    "is_port_free",
+    "validate_port",
+    "cidr_to_netmask"
+]
+
+
+def get_random_free_port(start: int = 49152, end: int = 65535) -> int:
+    """Return a random free TCP port in [start, end].
+
+    Uses socket.bind to test availability — no lsof required.
+    Raises RuntimeError if no free port found after 100 attempts.
+    """
+    for _ in range(100):
+        port = random.randint(start, end)
+        if is_port_free(port):
+            return port
+    raise RuntimeError(f"No free port found in range {start}-{end}")
+
+
+def is_port_free(port: int, host: str = "127.0.0.1") -> bool:
+    """Return True if the given TCP port is not currently bound."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            s.bind((host, port))
+            return True
+        except OSError:
+            return False
+
+
+def validate_port(port: int, *, allow_zero: bool = False) -> bool:
+    """Return True if port is in valid range 1–65535, or 0 when allow_zero=True."""
+    if not isinstance(port, int):
+        return False
+    if allow_zero and port == 0:
+        return True
+    return 1 <= port <= 65535
+
+
+def cidr_to_netmask(cidr_bits: int) -> str:
+    """Convert CIDR prefix length to dotted-decimal netmask.
+
+    Example: cidr_to_netmask(24) -> "255.255.255.0"
+    """
+    if not 0 <= cidr_bits <= 32:
+        raise ValueError(f"CIDR bits must be 0-32, got {cidr_bits}")
+    mask = (0xFFFFFFFF << (32 - cidr_bits)) & 0xFFFFFFFF
+    return socket.inet_ntoa(struct.pack(">I", mask))