optforge 0.2.0__py3-none-any.whl

optforge/portcheck/cli.py

@@ -0,0 +1,248 @@
+"""``portcheck``: inspect listening ports, test bindability, check connectivity.
+
+Exit codes
+    0  the answer is yes (free / found / connected / reached)
+    1  the answer is no (in use / missing / unreachable / timed out)
+    2  invalid usage (raised by Typer)
+    3  the check could not run (permission denied, OS error)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager, nullcontext
+from typing import Annotated, Any
+
+import typer
+from rich.text import Text
+
+from optforge.core.cli import ErrorBoundary, ExitCode
+from optforge.core.console import ConsoleIO
+from optforge.core.version import get_version
+from optforge.portcheck.models import Listener, PortState, SortKey
+from optforge.portcheck.service import DEFAULT_HOST, PortService
+
+app = typer.Typer(
+    name="portcheck",
+    help="Inspect listening ports, find their owners, and test connectivity.",
+    epilog="Exit codes: 0 yes/ok | 1 no | 2 bad usage | 3 could not run",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+console = ConsoleIO()
+_PERMISSION_HINT = "Run as Administrator (Windows) or with sudo (Linux/macOS)."
+
+PortArg = Annotated[
+    int,
+    typer.Argument(min=1, max=65535, metavar="PORT", show_default=False, help="Port number (1-65535)."),
+]
+HostOpt = Annotated[str, typer.Option("--host", "-H", help="Address used for bind and connect probes.")]
+QuietOpt = Annotated[bool, typer.Option("--quiet", "-q", help="Print nothing; use the exit code only.")]
+JsonOpt = Annotated[bool, typer.Option("--json", help="Print machine-readable JSON.")]
+
+
+def _service() -> PortService:
+    """Construct the service lazily so ``--help`` and ``--version`` stay instant."""
+    return PortService()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"portcheck (optforge {get_version()})")
+        raise typer.Exit()
+
+
+@contextmanager
+def _guard() -> Iterator[None]:
+    with ErrorBoundary(console, permission_hint=_PERMISSION_HINT):
+        yield
+
+
+def _scope_text(scope: str) -> Text:
+    style = {"all interfaces": "yellow", "local only": "green"}.get(scope, "")
+    return Text(scope, style=style)
+
+
+def _table(rows: list[Listener], title: str | None) -> Any:
+    table = console.table(
+        title,
+        [
+            ("Port", {"justify": "right", "style": "cyan", "no_wrap": True}),
+            ("Address", {"no_wrap": True}),
+            ("Scope", {"no_wrap": True}),
+            ("PID", {"justify": "right", "no_wrap": True}),
+            ("Process", {}),
+        ],
+    )
+    for row in rows:
+        table.add_row(
+            str(row.port),
+            console.cell(row.address),
+            _scope_text(row.scope),
+            "-" if row.pid is None else str(row.pid),
+            console.cell(row.process),
+        )
+    return table
+
+
+def _hint_hidden(rows: list[Listener]) -> None:
+    if any(row.pid is None for row in rows):
+        console.hint("Some process details are hidden. Run as Administrator / sudo to see them.")
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = None,
+) -> None:
+    pass
+
+
+@app.command("list")
+def list_ports(
+    sort: Annotated[
+        SortKey,
+        typer.Option("--sort", "-s", case_sensitive=False, help="Column to sort by."),
+    ] = SortKey.port,
+    limit: Annotated[
+        int | None, typer.Option("--limit", "-n", min=1, help="Show at most N rows.")
+    ] = None,
+    process: Annotated[
+        str | None,
+        typer.Option("--process", "-p", metavar="TEXT", help="Only rows whose process name contains TEXT."),
+    ] = None,
+    exposed: Annotated[
+        bool, typer.Option("--exposed", help="Only ports reachable from other machines.")
+    ] = False,
+    as_json: JsonOpt = False,
+) -> None:
+    """List listening TCP ports."""
+    with _guard():
+        rows = _service().query(sort=sort, limit=limit, process=process, exposed=exposed)
+
+    if as_json:
+        console.json([row.to_dict() for row in rows])
+        return
+    if not rows:
+        console.text("No listening TCP ports match.")
+        return
+
+    console.print(_table(rows, "Listening TCP ports"))
+    _hint_hidden(rows)
+
+
+@app.command()
+def check(
+    port: PortArg,
+    host: HostOpt = DEFAULT_HOST,
+    quiet: QuietOpt = False,
+    as_json: JsonOpt = False,
+    expect: Annotated[
+        PortState,
+        typer.Option("--expect", case_sensitive=False, help="Exit 0 only if the port matches this state."),
+    ] = PortState.free,
+) -> None:
+    """Check whether a port is free or in use."""
+    with _guard():
+        result = _service().check(port, host)
+
+    if as_json:
+        console.json(result.to_dict())
+    elif not quiet:
+        if result.in_use:
+            console.success(f"Port {port} is in use.")
+            if result.owners:
+                console.print(_table(result.owners, None))
+                _hint_hidden(result.owners)
+        else:
+            console.success(f"Port {port} is free on {host}.")
+
+    matched = result.in_use if expect is PortState.used else not result.in_use
+    raise typer.Exit(ExitCode.OK if matched else ExitCode.NO)
+
+
+@app.command()
+def find(port: PortArg, as_json: JsonOpt = False) -> None:
+    """Show the process listening on a port."""
+    with _guard():
+        owners = _service().find(port)
+
+    if as_json:
+        console.json([owner.to_dict() for owner in owners])
+    elif owners:
+        console.print(_table(owners, f"Port {port}"))
+        _hint_hidden(owners)
+    else:
+        console.text(f"Nothing is listening on port {port}.")
+    raise typer.Exit(ExitCode.OK if owners else ExitCode.NO)
+
+
+@app.command()
+def connect(
+    host: Annotated[str, typer.Argument(metavar="HOST", help="Hostname or IP address.")],
+    port: PortArg,
+    timeout: Annotated[
+        float, typer.Option("--timeout", "-t", min=0.1, help="Seconds to wait.")
+    ] = 3.0,
+    quiet: QuietOpt = False,
+    as_json: JsonOpt = False,
+) -> None:
+    """Test a TCP connection to a host and port."""
+    with _guard():
+        result = _service().connect(host, port, timeout)
+
+    if as_json:
+        console.json({"host": host, "port": port, **result.to_dict()})
+    elif not quiet:
+        target = f"{host}:{port}"
+        if result.ok:
+            took = f" in {result.seconds * 1000:.0f} ms" if result.seconds is not None else ""
+            console.success(f"Connected to {target}{took}.")
+        else:
+            console.error(f"Could not connect to {target}: {result.error or 'unknown error'}")
+    raise typer.Exit(ExitCode.OK if result.ok else ExitCode.NO)
+
+
+@app.command()
+def wait(
+    port: PortArg,
+    until: Annotated[
+        PortState,
+        typer.Option("--until", "-u", case_sensitive=False, help="Wait until the port is in use or free."),
+    ] = PortState.used,
+    timeout: Annotated[
+        float, typer.Option("--timeout", "-t", min=0.1, help="Give up after N seconds.")
+    ] = 30.0,
+    interval: Annotated[
+        float, typer.Option("--interval", "-i", min=0.05, help="Seconds between checks.")
+    ] = 0.5,
+    host: HostOpt = DEFAULT_HOST,
+    quiet: QuietOpt = False,
+    as_json: JsonOpt = False,
+) -> None:
+    """Wait until a port is in use or free."""
+    spinner = nullcontext() if quiet or as_json else console.status(f"Waiting for port {port} to be {until.value}...")
+    with _guard(), spinner:
+        result = _service().wait(port, until, timeout=timeout, interval=interval, host=host)
+
+    if as_json:
+        console.json(result.to_dict())
+    elif not quiet:
+        if result.reached:
+            console.success(f"Port {port} is {until.value}.")
+        else:
+            console.error(f"Timed out after {timeout:g}s waiting for port {port} to be {until.value}.")
+    raise typer.Exit(ExitCode.OK if result.reached else ExitCode.NO)
+
+
+if __name__ == "__main__":
+    app()

optforge/portcheck/connector.py

@@ -0,0 +1,60 @@
+"""Bounded-timeout TCP connection attempts."""
+
+from __future__ import annotations
+
+import socket
+import time
+from collections.abc import Callable
+
+from optforge.core.errors import OptForgeError
+from optforge.core.net import resolve_endpoints_with_timeout
+from optforge.portcheck.models import ConnectResult
+
+Resolver = Callable[[str, int, float], list]
+
+
+class Connector:
+    """Connect to ``host:port`` while honouring one wall-clock deadline."""
+
+    def __init__(
+        self,
+        resolver: Resolver = resolve_endpoints_with_timeout,
+        clock: Callable[[], float] = time.perf_counter,
+    ) -> None:
+        self._resolver = resolver
+        self._clock = clock
+
+    def connect(self, host: str, port: int, timeout: float) -> ConnectResult:
+        start = self._clock()
+        try:
+            endpoints = self._resolver(host, port, timeout)
+        except OptForgeError as exc:
+            return ConnectResult(ok=False, error=str(exc))
+
+        last_error = "no endpoint accepted the connection"
+        for endpoint in endpoints:
+            remaining = timeout - (self._clock() - start)
+            if remaining <= 0:
+                last_error = f"timed out after {timeout:g}s"
+                break
+            try:
+                with socket.socket(endpoint.family, socket.SOCK_STREAM) as sock:
+                    sock.settimeout(remaining)
+                    sock.connect(endpoint.sockaddr)
+                return ConnectResult(
+                    ok=True,
+                    seconds=self._clock() - start,
+                    endpoint=endpoint.label(),
+                )
+            except OSError as exc:
+                last_error = _reason(exc)
+
+        return ConnectResult(ok=False, error=last_error)
+
+
+def _reason(exc: OSError) -> str:
+    if isinstance(exc, ConnectionRefusedError):
+        return "connection refused"
+    if isinstance(exc, TimeoutError):
+        return "timed out"
+    return exc.strerror or str(exc)

optforge/portcheck/models.py

@@ -0,0 +1,117 @@
+"""Value objects returned by the port inspection service."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class PortState(str, Enum):
+    """The two states a waiter can wait for."""
+
+    free = "free"
+    used = "used"
+
+
+class SortKey(str, Enum):
+    """Columns accepted by ``portcheck list --sort``."""
+
+    port = "port"
+    pid = "pid"
+    process = "process"
+    address = "address"
+
+
+def scope_for(address: str) -> str:
+    """Classify a bind address by how far it is reachable."""
+    if address in ("", "0.0.0.0", "::", "*"):
+        return "all interfaces"
+    if address == "::1" or address.startswith("127."):
+        return "local only"
+    if address.startswith("169.254.") or address.lower().startswith("fe80"):
+        return "link local"
+    return "specific"
+
+
+@dataclass(frozen=True, slots=True)
+class Listener:
+    """One listening TCP socket and, when the OS allows it, its owner."""
+
+    port: int
+    address: str
+    family: str
+    pid: int | None
+    process: str
+
+    @property
+    def scope(self) -> str:
+        return scope_for(self.address)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "port": self.port,
+            "address": self.address,
+            "family": self.family,
+            "scope": self.scope,
+            "pid": self.pid,
+            "process": self.process,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectResult:
+    """Outcome of a single TCP connection attempt."""
+
+    ok: bool
+    seconds: float | None = None
+    error: str | None = None
+    endpoint: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "seconds": self.seconds,
+            "error": self.error,
+            "endpoint": self.endpoint,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class CheckResult:
+    """Answer to "is this port free?"."""
+
+    port: int
+    host: str
+    in_use: bool
+    bindable: bool
+    owners: list[Listener] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "port": self.port,
+            "host": self.host,
+            "in_use": self.in_use,
+            "bindable": self.bindable,
+            "owners": [owner.to_dict() for owner in self.owners],
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class WaitResult:
+    """Outcome of polling until a port reaches the requested state."""
+
+    port: int
+    until: str
+    reached: bool
+    elapsed: float
+    checks: int
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "port": self.port,
+            "until": self.until,
+            "reached": self.reached,
+            "elapsed": self.elapsed,
+            "checks": self.checks,
+        }

optforge/portcheck/scanner.py

@@ -0,0 +1,76 @@
+"""Listening-socket discovery built on psutil."""
+
+from __future__ import annotations
+
+import socket
+from collections.abc import Callable, Iterable
+from typing import Any
+
+import psutil
+
+from optforge.core.errors import PermissionDenied
+from optforge.core.processes import ProcessNameResolver
+from optforge.portcheck.models import Listener
+
+ConnectionProvider = Callable[..., Iterable[Any]]
+
+
+class ListenerScanner:
+    """Turn the operating system's socket table into :class:`Listener` rows.
+
+    The provider is injectable so the scanner can be tested without touching the
+    real socket table.
+    """
+
+    def __init__(
+        self,
+        provider: ConnectionProvider = psutil.net_connections,
+        resolver: ProcessNameResolver | None = None,
+    ) -> None:
+        self._provider = provider
+        self._resolver = resolver or ProcessNameResolver()
+
+    def scan(self) -> list[Listener]:
+        """Return every listening TCP socket, de-duplicated and sorted by port."""
+        try:
+            connections = list(self._provider(kind="tcp"))
+        except psutil.AccessDenied as exc:
+            raise PermissionDenied(
+                "The operating system denied access to the socket table."
+            ) from exc
+        except OSError as exc:
+            raise PermissionDenied(f"Could not read the socket table: {exc}") from exc
+
+        rows: list[Listener] = []
+        seen: set[tuple[int, str, int | None]] = set()
+        for connection in connections:
+            if getattr(connection, "status", None) != psutil.CONN_LISTEN:
+                continue
+            local = getattr(connection, "laddr", None)
+            if local is None:
+                continue
+
+            family = getattr(connection, "family", socket.AF_INET)
+            port = int(local.port)
+            address = str(getattr(local, "ip", "") or ("::" if family == socket.AF_INET6 else "0.0.0.0"))
+            pid = getattr(connection, "pid", None)
+            key = (port, address, pid)
+            if key in seen:
+                continue
+            seen.add(key)
+
+            rows.append(
+                Listener(
+                    port=port,
+                    address=address,
+                    family="ipv6" if family == socket.AF_INET6 else "ipv4",
+                    pid=pid,
+                    process=self._resolver.name(pid),
+                )
+            )
+
+        rows.sort(key=lambda row: (row.port, row.address, row.pid or 0))
+        return rows
+
+    def owners(self, port: int) -> list[Listener]:
+        return [row for row in self.scan() if row.port == port]

optforge/portcheck/service.py

@@ -0,0 +1,109 @@
+"""High-level port operations composed from the focused components."""
+
+from __future__ import annotations
+
+from optforge.portcheck.binder import PortBinder
+from optforge.portcheck.connector import Connector
+from optforge.portcheck.models import (
+    CheckResult,
+    ConnectResult,
+    Listener,
+    PortState,
+    SortKey,
+    WaitResult,
+)
+from optforge.portcheck.scanner import ListenerScanner
+from optforge.portcheck.waiter import PortWaiter
+
+DEFAULT_HOST = "127.0.0.1"
+
+
+class PortService:
+    """Facade used by the CLI and by library consumers."""
+
+    def __init__(
+        self,
+        scanner: ListenerScanner | None = None,
+        binder: PortBinder | None = None,
+        connector: Connector | None = None,
+    ) -> None:
+        self._scanner = scanner or ListenerScanner()
+        self._binder = binder or PortBinder()
+        self._connector = connector or Connector()
+
+    def listeners(self) -> list[Listener]:
+        """Every listening TCP socket on the machine."""
+        return self._scanner.scan()
+
+    def query(
+        self,
+        *,
+        sort: SortKey = SortKey.port,
+        limit: int | None = None,
+        process: str | None = None,
+        exposed: bool = False,
+    ) -> list[Listener]:
+        """Return listeners filtered and ordered for display."""
+        rows = self._scanner.scan()
+        if process:
+            needle = process.lower()
+            rows = [row for row in rows if needle in row.process.lower()]
+        if exposed:
+            rows = [row for row in rows if row.scope == "all interfaces"]
+        rows.sort(key=_sort_key(sort))
+        if limit is not None:
+            rows = rows[:limit]
+        return rows
+
+    def find(self, port: int) -> list[Listener]:
+        """Every listener bound to ``port``."""
+        return [row for row in self._scanner.scan() if row.port == port]
+
+    def check(self, port: int, host: str = DEFAULT_HOST) -> CheckResult:
+        """Answer whether ``port`` is free, using owners plus a bind probe."""
+        owners = self.find(port)
+        bindable = self._binder.is_free(port, host)
+        return CheckResult(
+            port=port,
+            host=host,
+            in_use=bool(owners) or not bindable,
+            bindable=bindable,
+            owners=owners,
+        )
+
+    def connect(self, host: str, port: int, timeout: float) -> ConnectResult:
+        """Attempt a TCP connection with a real deadline."""
+        return self._connector.connect(host, port, timeout)
+
+    def wait(
+        self,
+        port: int,
+        until: PortState,
+        *,
+        timeout: float,
+        interval: float,
+        host: str = DEFAULT_HOST,
+    ) -> WaitResult:
+        """Poll until the port is ``used`` or ``free``.
+
+        The probes are deliberately cheap: a TCP connect for ``used`` and a
+        pair of wildcard bind probes for ``free``. Neither walks the socket
+        table, so a long wait stays cheap.
+        """
+        state = PortState(until)
+        if state is PortState.used:
+            probe_timeout = min(max(interval * 2.0, 0.2), 1.0)
+            probe = lambda: self._connector.connect(host, port, probe_timeout).ok  # noqa: E731
+        else:
+            probe = lambda: self._binder.is_free_on_all_interfaces(port)  # noqa: E731
+        return PortWaiter(port, state.value, probe).wait(timeout, interval)
+
+
+def _sort_key(sort: SortKey) -> object:
+    keys = {
+        SortKey.port: lambda row: (row.port, row.address),
+        SortKey.pid: lambda row: (row.pid is None, row.pid or 0, row.port),
+        SortKey.process: lambda row: (row.process.lower(), row.port),
+        SortKey.address: lambda row: (row.address, row.port),
+    }
+    return keys[sort]

optforge/portcheck/waiter.py

@@ -0,0 +1,54 @@
+"""Deadline-driven polling for port state changes."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+
+from optforge.portcheck.models import WaitResult
+
+Probe = Callable[[], bool]
+
+
+class PortWaiter:
+    """Poll a probe until it returns ``True`` or the deadline expires."""
+
+    def __init__(
+        self,
+        port: int,
+        until: str,
+        probe: Probe,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._port = port
+        self._until = until
+        self._probe = probe
+        self._clock = clock
+        self._sleep = sleep
+
+    def wait(self, timeout: float, interval: float) -> WaitResult:
+        start = self._clock()
+        deadline = start + timeout
+        checks = 0
+        while True:
+            checks += 1
+            if self._probe():
+                return WaitResult(
+                    port=self._port,
+                    until=self._until,
+                    reached=True,
+                    elapsed=self._clock() - start,
+                    checks=checks,
+                )
+            now = self._clock()
+            if now >= deadline:
+                return WaitResult(
+                    port=self._port,
+                    until=self._until,
+                    reached=False,
+                    elapsed=now - start,
+                    checks=checks,
+                )
+            self._sleep(min(interval, max(0.0, deadline - now)))

optforge/pycacheClean/__init__.py

@@ -0,0 +1,6 @@
+"""Remove Python ``__pycache__`` directories safely."""
+
+from optforge.pycacheclean.models import CacheTarget, CleanFailure, CleanReport
+from optforge.pycacheclean.service import CacheService
+
+__all__ = ["CacheService", "CacheTarget", "CleanFailure", "CleanReport"]