hostctl 0.1.0__py3-none-any.whl

hostctl/provider/transports.py

@@ -0,0 +1,303 @@
+"""Path and executor provider adapters for the built-in transports.
+
+The SSH/SFTP and WinRM adapters live beside their private transport services
+(``host/_ssh.py``, ``host/_winrm.py``) because they own that transport's
+lifecycle.  The adapters here wrap backends that are *not* lifecycle owners:
+the local filesystem, the Docker archive API, and the QEMU Guest Agent file
+RPCs.  Each one declares the operations its backend can genuinely perform, so
+:class:`~hostctl.host.composite_path._CompositePathMixin` rejects an
+unsupported mutation outright instead of falling through to another provider.
+
+None of these adapters retries.  A backend failure is reported as-is; only a
+proven pre-dispatch refusal is raised as
+:class:`~hostctl.provider.OperationNotStarted`.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import typing
+
+from pathlib_next import Path
+
+from ._common import (
+    ExecutorProvider,
+    OperationNotStarted,
+    PathProvider,
+    ProviderProbe,
+    ProviderSelector,
+)
+
+log = logging.getLogger("hostctl.provider.transports")
+
+#: Operations a POSIX-complete filesystem backend performs.
+FULL_PATH_OPERATIONS = frozenset(
+    (
+        "stat",
+        "scandir",
+        "open",
+        "open_read",
+        "open_write",
+        "read",
+        "write",
+        "exists",
+        "is_file",
+        "is_dir",
+        "mkdir",
+        "chmod",
+        "unlink",
+        "rmdir",
+        "rename",
+    )
+)
+
+#: Content and metadata reads plus whole-file writes, with no namespace
+#: mutations.  The Docker archive API can replace a file's bytes but cannot
+#: create a directory, change a mode, or remove/rename an entry.
+ARCHIVE_PATH_OPERATIONS = frozenset(
+    (
+        "stat",
+        "scandir",
+        "open",
+        "open_read",
+        "open_write",
+        "read",
+        "write",
+        "exists",
+        "is_file",
+        "is_dir",
+    )
+)
+
+#: QGA file RPCs without a guest helper: content only.  ``stat``/``scandir``
+#: and every namespace mutation require a positively probed helper.
+QGA_FILE_OPERATIONS = frozenset(("open", "open_read", "open_write", "read", "write"))
+
+#: Operations a positively probed guest helper adds on top of the file RPCs.
+QGA_HELPER_OPERATIONS = frozenset(
+    (
+        "stat",
+        "scandir",
+        "exists",
+        "is_file",
+        "is_dir",
+        "mkdir",
+        "chmod",
+        "unlink",
+        "rmdir",
+        "rename",
+    )
+)
+
+
+class LocalExecutorProvider(ExecutorProvider):
+    """Local subprocess execution with native argv, cwd, and env support."""
+
+    def __init__(self, executor=None):
+        if executor is None:
+            from ..executor import LocalExecutor
+
+            executor = LocalExecutor()
+        self.transport = executor
+        super().__init__("local", executor)
+
+    def probe(self) -> ProviderProbe:
+        return ProviderProbe(
+            "available", capabilities=self.capabilities, system_hint=os.name
+        )
+
+
+class LocalPathProvider(PathProvider):
+    """Local filesystem paths; the process's own filesystem is always usable."""
+
+    def __init__(self, factory: typing.Optional[typing.Callable[..., Path]] = None):
+        super().__init__(
+            "local",
+            factory if factory is not None else (lambda *segments: Path(*segments)),
+            capabilities=FULL_PATH_OPERATIONS,
+        )
+
+    def probe(self) -> ProviderProbe:
+        return ProviderProbe(
+            "available", capabilities=self.capabilities, system_hint=os.name
+        )
+
+
+class ContainerExecutorProvider(ExecutorProvider):
+    """Docker ``exec`` command provider owning the container's inspection.
+
+    ``connect`` inspects the container before any command is dispatched, so a
+    missing or stopped container is a proven pre-dispatch refusal rather than a
+    command whose outcome is unknown.
+    """
+
+    def __init__(self, executor, *, connect=None, close=None, info=None):
+        self.transport = executor
+        self._connect = connect
+        self._close = close
+        self._info = info
+        super().__init__("container", executor)
+
+    def probe(self) -> ProviderProbe:
+        return ProviderProbe("available", capabilities=self.capabilities)
+
+    def connect(self):
+        if self._connect is None:
+            return
+        log.debug("inspecting container before dispatch")
+        try:
+            self._connect()
+        except (ConnectionError, TimeoutError) as exc:
+            log.debug(
+                "container provider declining before dispatch: %s: %s",
+                type(exc).__name__,
+                ProviderSelector.redact(exc),
+            )
+            raise OperationNotStarted(
+                "container is unavailable before dispatch", cause=exc
+            ) from exc
+        log.debug("container is running and ready for dispatch")
+
+    def close(self):
+        if self._close is not None:
+            log.debug("releasing container provider resources")
+            self._close()
+
+    def info(self):
+        if self._info is None:
+            return None
+        return self._info()
+
+
+class ContainerArchivePathProvider(PathProvider):
+    """Docker archive (``get_archive``/``put_archive``) path provider.
+
+    The archive API has no namespace mutations.  Declaring only the operations
+    it implements makes ``mkdir``/``chmod``/``unlink``/``rmdir``/``rename``
+    fail with ``NotImplementedError`` at selection time, which is the plan's
+    "read-only providers explicitly reject mutations instead of falling
+    through" rule applied to a partially writable backend.
+    """
+
+    def __init__(self, factory, *, name="archive", probe=None):
+        self._probe_hook = probe
+        super().__init__(name, factory, capabilities=ARCHIVE_PATH_OPERATIONS)
+
+    def probe(self) -> ProviderProbe:
+        if self._probe_hook is None:
+            return ProviderProbe("available", capabilities=self.capabilities)
+        try:
+            usable = self._probe_hook()
+        except (ConnectionError, TimeoutError, OSError) as exc:
+            return ProviderProbe("unavailable", type(exc).__name__)
+        if isinstance(usable, ProviderProbe):
+            return usable
+        return ProviderProbe(
+            "available" if usable else "unavailable",
+            "" if usable else "container archive API is unavailable",
+            capabilities=self.capabilities,
+        )
+
+
+class QgaPathProvider(PathProvider):
+    """QEMU Guest Agent path provider gated on genuinely probed RPCs.
+
+    QGA file RPCs give content access.  Metadata and namespace mutations exist
+    only when a guest helper was positively probed, so this provider reports
+    ``degraded`` when it can move bytes but cannot describe or restructure the
+    guest filesystem.
+    """
+
+    def __init__(self, factory, backend, *, name="qga"):
+        self.backend = backend
+        capabilities = self._backend_capabilities(backend)
+        super().__init__(name, factory, capabilities=capabilities)
+
+    @staticmethod
+    def _backend_capabilities(backend) -> frozenset:
+        supported = frozenset(getattr(backend, "supported_commands", ()) or ())
+        values = set()
+        read_commands = getattr(
+            type(backend),
+            "_READ_COMMANDS",
+            frozenset(("guest-file-open", "guest-file-read", "guest-file-close")),
+        )
+        write_commands = getattr(
+            type(backend),
+            "_WRITE_COMMANDS",
+            frozenset(
+                (
+                    "guest-file-open",
+                    "guest-file-write",
+                    "guest-file-flush",
+                    "guest-file-close",
+                )
+            ),
+        )
+        if read_commands <= supported:
+            values.update(("read", "open", "open_read"))
+        if write_commands <= supported:
+            values.update(("write", "open_write"))
+        if getattr(backend, "helper", None) is not None:
+            values.update(QGA_HELPER_OPERATIONS)
+        return frozenset(values)
+
+    def probe(self) -> ProviderProbe:
+        if not self.capabilities:
+            return ProviderProbe(
+                "unavailable", "guest agent provides no usable file RPCs"
+            )
+        if getattr(self.backend, "helper", None) is None:
+            # Warning, not debug: the provider stays usable, so the operation
+            # proceeds and nothing surfaces an error -- but the caller silently
+            # loses stat/scandir and every namespace mutation.  Degrading
+            # without saying so is exactly the case a log is for.
+            log.warning(
+                "QGA provider %s is degraded: no guest helper was probed, so "
+                "metadata and namespace mutations are unavailable",
+                ProviderSelector.redact(self.name),
+            )
+            return ProviderProbe(
+                "degraded",
+                "guest helper was not probed; metadata and mutations are unavailable",
+                capabilities=self.capabilities,
+            )
+        return ProviderProbe("available", capabilities=self.capabilities)
+
+
+class DownloadPathProvider(PathProvider):
+    """Read-only content provider for an application download endpoint.
+
+    Mutating operations are absent from the declared capability set, so the
+    composite path rejects them rather than silently routing the mutation to
+    another provider that might apply it to different state.
+    """
+
+    READ_OPERATIONS = frozenset(("stat", "read", "open", "open_read", "exists"))
+
+    def __init__(self, factory, *, name="download", available=True, reason=""):
+        self._available = bool(available)
+        self._reason = reason
+        super().__init__(name, factory, capabilities=self.READ_OPERATIONS)
+
+    def probe(self) -> ProviderProbe:
+        if not self._available:
+            return ProviderProbe(
+                "unavailable", self._reason or "download endpoint is unavailable"
+            )
+        return ProviderProbe("available", capabilities=self.capabilities)
+
+
+__all__ = [
+    "ARCHIVE_PATH_OPERATIONS",
+    "ContainerArchivePathProvider",
+    "ContainerExecutorProvider",
+    "DownloadPathProvider",
+    "FULL_PATH_OPERATIONS",
+    "LocalExecutorProvider",
+    "LocalPathProvider",
+    "QGA_FILE_OPERATIONS",
+    "QGA_HELPER_OPERATIONS",
+    "QgaPathProvider",
+]

hostctl/serial/__init__.py

@@ -0,0 +1,285 @@
+"""Console protocols for serial transports.
+
+The wire is deliberately kept separate from shell and operating-system
+assumptions.  Profiles negotiate a console, optionally frame commands, and
+never claim filesystem or process semantics which the device cannot provide.
+"""
+
+from __future__ import annotations
+
+import abc
+import dataclasses
+import re
+import time
+import typing
+
+from ..process.serial import SerialProcess
+
+
+@typing.runtime_checkable
+class SerialConsoleProtocol(typing.Protocol):
+    """Runtime contract implemented by serial console profiles."""
+
+    can_run: bool
+    line_terminator: bytes
+    encoding: str
+
+    def negotiate(self, process: SerialProcess) -> None: ...
+
+    def send(self, process: SerialProcess, command: str | bytes) -> None: ...
+
+    def run(
+        self,
+        process: SerialProcess,
+        command: str | bytes,
+        *,
+        timeout: float | None = None,
+    ) -> tuple[bytes, int]: ...
+
+
+class ConsoleProtocolError(ConnectionError):
+    """The console did not complete the expected protocol exchange."""
+
+
+@dataclasses.dataclass(frozen=True, repr=False)
+class LoginStep:
+    """One bounded expect/send step used by :class:`PromptConsoleProfile`."""
+
+    expect: bytes | str
+    send: bytes | str
+    secret: bool = False
+
+    def __post_init__(self) -> None:
+        expect = self.expect.encode() if isinstance(self.expect, str) else self.expect
+        send = self.send.encode() if isinstance(self.send, str) else self.send
+        if not expect:
+            raise ValueError("login expect expression must not be empty")
+        object.__setattr__(self, "expect", bytes(expect))
+        object.__setattr__(self, "send", bytes(send))
+
+    def __repr__(self) -> str:
+        value = "<redacted>" if self.secret else repr(self.send)
+        return (
+            f"LoginStep(expect={self.expect!r}, send={value}, secret={self.secret!r})"
+        )
+
+
+class RawConsoleProfile:
+    """Raw byte console; it supports interactive sessions but not ``run``."""
+
+    can_run = False
+    line_terminator = b"\r\n"
+    encoding = "utf-8"
+    max_buffer = 64 * 1024
+
+    def negotiate(self, process: SerialProcess) -> None:
+        return None
+
+    def send(self, process: SerialProcess, command: str | bytes) -> None:
+        data = (
+            command.encode(self.encoding)
+            if isinstance(command, str)
+            else bytes(command)
+        )
+        process.write(data + self.line_terminator)
+
+    def run(self, process: SerialProcess, command: str | bytes, *, timeout=None):
+        raise NotImplementedError("raw serial consoles do not provide framed run()")
+
+
+class PromptConsoleProfile:
+    """Configurable prompt/login framing for terminal-like devices.
+
+    A profile only advertises ``run`` when ``reliable_status`` is explicitly
+    enabled.  Without a real status marker a prompt can delimit output, but it
+    cannot truthfully represent a process exit status.
+    """
+
+    def __init__(
+        self,
+        prompt: bytes | str,
+        *,
+        login: typing.Iterable[LoginStep | tuple[bytes | str, bytes | str]] = (),
+        line_terminator: bytes | str = b"\r\n",
+        error_patterns: typing.Iterable[bytes | str] = (),
+        status_marker: bytes | str | None = None,
+        reliable_status: bool = False,
+        max_buffer: int = 64 * 1024,
+        read_size: int = 4096,
+        wakeup: bytes = b"\r",
+        echo: bool = True,
+        paging_prompt: bytes | str | None = None,
+        paging_continue: bytes | str = b" ",
+        paging_disable: bytes | str | None = None,
+        max_paging_pages: int = 32,
+        terminal_setup: typing.Callable[[SerialProcess, int, int], None] | None = None,
+        status_parser: typing.Callable[[re.Match[bytes]], int] | None = None,
+    ) -> None:
+        self._prompt = self._compile(prompt)
+        self.login = tuple(
+            step if isinstance(step, LoginStep) else LoginStep(step[0], step[1])
+            for step in login
+        )
+        self._login_patterns = tuple(self._compile(step.expect) for step in self.login)
+        self.line_terminator = (
+            line_terminator.encode()
+            if isinstance(line_terminator, str)
+            else bytes(line_terminator)
+        )
+        if not self.line_terminator:
+            raise ValueError("line_terminator must not be empty")
+        self.error_patterns = tuple(self._compile(value) for value in error_patterns)
+        self.status_marker = (
+            self._compile(status_marker) if status_marker is not None else None
+        )
+        self.reliable_status = bool(reliable_status)
+        self.can_run = self.reliable_status and self.status_marker is not None
+        self.max_buffer = max(1024, int(max_buffer))
+        self.read_size = max(1, int(read_size))
+        self.wakeup = bytes(wakeup)
+        self.echo = bool(echo)
+        self._paging_prompt = self._compile(paging_prompt) if paging_prompt else None
+        self.paging_continue = (
+            paging_continue.encode()
+            if isinstance(paging_continue, str)
+            else bytes(paging_continue)
+        )
+        self.paging_disable = (
+            paging_disable.encode()
+            if isinstance(paging_disable, str)
+            else (bytes(paging_disable) if paging_disable is not None else None)
+        )
+        if max_paging_pages < 0:
+            raise ValueError("max_paging_pages must not be negative")
+        self.max_paging_pages = int(max_paging_pages)
+        self.terminal_setup = terminal_setup
+        self.status_parser = status_parser
+        self.encoding = "utf-8"
+
+    @staticmethod
+    def _compile(value: bytes | str) -> typing.Pattern[bytes]:
+        raw = value.encode() if isinstance(value, str) else bytes(value)
+        if not raw:
+            raise ValueError("console expressions must not be empty")
+        try:
+            return re.compile(raw)
+        except re.error as exc:
+            raise ValueError(f"invalid console expression: {exc}") from exc
+
+    def _read_until(
+        self,
+        process: SerialProcess,
+        expression: typing.Pattern[bytes],
+        *,
+        timeout: float | None,
+        initial: bytes = b"",
+        paging_process: SerialProcess | None = None,
+    ) -> bytes:
+        started = time.monotonic()
+        buffer = bytearray(initial)
+        pages = 0
+        while True:
+            if paging_process is not None and self._paging_prompt is not None:
+                paging = self._paging_prompt.search(buffer)
+                if paging is not None:
+                    if pages >= self.max_paging_pages:
+                        raise ConsoleProtocolError(
+                            "serial console paging limit exceeded"
+                        )
+                    pages += 1
+                    del buffer[: paging.end()]
+                    paging_process.write(self.paging_continue)
+                    continue
+            match = expression.search(buffer)
+            if match:
+                return bytes(buffer)
+            if len(buffer) > self.max_buffer:
+                del buffer[: -self.max_buffer]
+            if timeout is not None and time.monotonic() - started >= timeout:
+                error = TimeoutError("serial console prompt timed out")
+                error.output = bytes(buffer)  # type: ignore[attr-defined]
+                raise error
+            chunk = process.read(self.read_size)
+            if chunk:
+                buffer.extend(chunk)
+                continue
+            # pyserial timed reads return b""; avoid a busy loop while still
+            # respecting a monotonic deadline.
+            time.sleep(0.001)
+
+    def negotiate(self, process: SerialProcess) -> None:
+        transcript = b""
+        reset = getattr(process, "reset_input_buffer", None)
+        if callable(reset):
+            try:
+                reset()
+            except NotImplementedError:
+                pass
+        if self.wakeup:
+            process.write(self.wakeup)
+        for step in self.login:
+            transcript = self._read_until(
+                process, self._compile(step.expect), timeout=10, initial=transcript
+            )
+            process.write(step.send + self.line_terminator)
+        self._read_until(process, self._prompt, timeout=10, initial=transcript)
+        if self.paging_disable is not None:
+            process.write(self.paging_disable + self.line_terminator)
+
+    def resize(self, process: SerialProcess, columns: int, rows: int) -> None:
+        if self.terminal_setup is None:
+            raise NotImplementedError("console profile does not support terminal setup")
+        if columns <= 0 or rows <= 0:
+            raise ValueError("terminal columns and rows must be positive")
+        self.terminal_setup(process, columns, rows)
+
+    def send(self, process: SerialProcess, command: str | bytes) -> None:
+        data = (
+            command.encode(self.encoding)
+            if isinstance(command, str)
+            else bytes(command)
+        )
+        process.write(data + self.line_terminator)
+
+    def run(self, process: SerialProcess, command: str | bytes, *, timeout=None):
+        if not self.can_run:
+            raise NotImplementedError("console profile does not provide reliable run()")
+        self.send(process, command)
+        transcript = self._read_until(
+            process, self._prompt, timeout=timeout, paging_process=process
+        )
+        if any(pattern.search(transcript) for pattern in self._login_patterns):
+            raise ConsoleProtocolError("serial console requested login again")
+        marker = self.status_marker.search(transcript) if self.status_marker else None
+        if marker is None:
+            raise ConsoleProtocolError("command completion marker missing")
+        body = transcript[: marker.start()]
+        # Remove a simple echoed command without attempting to parse vendor
+        # terminal editing rules.
+        if self.echo:
+            encoded = (
+                command.encode(self.encoding)
+                if isinstance(command, str)
+                else bytes(command)
+            )
+            if body.startswith(encoded):
+                body = body[len(encoded) :].lstrip(b"\r\n")
+        status = (
+            self.status_parser(marker)
+            if self.status_parser
+            else (
+                1 if any(pattern.search(body) for pattern in self.error_patterns) else 0
+            )
+        )
+        if not isinstance(status, int) or status < 0:
+            raise ConsoleProtocolError("console status parser returned an invalid code")
+        return body, status
+
+
+__all__ = [
+    "ConsoleProtocolError",
+    "LoginStep",
+    "PromptConsoleProfile",
+    "RawConsoleProfile",
+    "SerialConsoleProtocol",
+]