hostctl 0.1.0__py3-none-any.whl

hostctl/process/__init__.py

@@ -0,0 +1,49 @@
+"""Persistent process contracts and provider adapters."""
+
+from ._common import (
+    Process as Process,
+    ProcessData as ProcessData,
+    TerminalOptions as TerminalOptions,
+    TerminalRequest as TerminalRequest,
+    terminal_options as terminal_options,
+)
+from .ssh import SshProcess as SshProcess
+from .container import ContainerProcess as ContainerProcess
+from .serial import (
+    SerialConsoleProcess as SerialConsoleProcess,
+    SerialProcess as SerialProcess,
+)
+from .qemu_serial import (
+    ConsoleResize as ConsoleResize,
+    ConsoleStreamFactory as ConsoleStreamFactory,
+    QemuConsoleStream as QemuConsoleStream,
+    QemuSerialConsole as QemuSerialConsole,
+    QemuSerialProcess as QemuSerialProcess,
+    normalize_qemu_console_error as normalize_qemu_console_error,
+)
+from .psrp import (
+    PipelineResult as PipelineResult,
+    PipelineStreams as PipelineStreams,
+    RunspaceSession as RunspaceSession,
+)
+
+__all__ = (
+    "Process",
+    "ProcessData",
+    "ConsoleResize",
+    "ConsoleStreamFactory",
+    "QemuConsoleStream",
+    "QemuSerialConsole",
+    "QemuSerialProcess",
+    "ContainerProcess",
+    "SshProcess",
+    "SerialProcess",
+    "SerialConsoleProcess",
+    "TerminalOptions",
+    "TerminalRequest",
+    "terminal_options",
+    "normalize_qemu_console_error",
+    "PipelineResult",
+    "PipelineStreams",
+    "RunspaceSession",
+)

hostctl/process/_common.py

@@ -0,0 +1,113 @@
+"""Contracts for persistent child processes and terminal allocation."""
+
+from __future__ import annotations
+
+import dataclasses
+import typing
+import types
+import codecs
+
+ProcessData = typing.Union[str, bytes]
+
+
+def raise_normalized(
+    exc: Exception, normalizer: typing.Callable[[Exception], Exception]
+) -> typing.NoReturn:
+    """Raise a normalized transport error while preserving its cause."""
+    normalized = normalizer(exc)
+    if normalized is exc:
+        raise exc
+    raise normalized from exc
+
+
+class IncrementalTextDecoder:
+    """Decode arbitrary byte chunks without splitting multibyte characters."""
+
+    def __init__(self, encoding: str, errors: str = "strict") -> None:
+        self._decoder = codecs.getincrementaldecoder(encoding)(errors)
+
+    def decode(self, data: bytes, *, final: bool = False) -> str:
+        return self._decoder.decode(data, final=final)
+
+
+TerminalRequest = typing.Optional[typing.Union[bool, "TerminalOptions"]]
+
+
+@dataclasses.dataclass(frozen=True)
+class TerminalOptions:
+    """Requested pseudo-terminal type and initial dimensions."""
+
+    term_type: str = "xterm-256color"
+    columns: int = 80
+    rows: int = 24
+    pixel_width: int = 0
+    pixel_height: int = 0
+
+    def __post_init__(self) -> None:
+        if not self.term_type:
+            raise ValueError("term_type must not be empty")
+        if self.columns <= 0 or self.rows <= 0:
+            raise ValueError("terminal columns and rows must be positive")
+        if self.pixel_width < 0 or self.pixel_height < 0:
+            raise ValueError("terminal pixel dimensions must not be negative")
+
+    @property
+    def size(self) -> typing.Tuple[int, int, int, int]:
+        return (
+            self.columns,
+            self.rows,
+            self.pixel_width,
+            self.pixel_height,
+        )
+
+
+def terminal_options(value: TerminalRequest) -> typing.Optional[TerminalOptions]:
+    """Normalize a convenient boolean terminal request to concrete options."""
+    if value is True:
+        return TerminalOptions()
+    if value in (False, None):
+        return None
+    if not isinstance(value, TerminalOptions):
+        raise TypeError("terminal must be bool, TerminalOptions, or None")
+    return value
+
+
+@typing.runtime_checkable
+class Process(typing.Protocol):
+    """Synchronous control surface for a persistent child process."""
+
+    @property
+    def returncode(self) -> typing.Optional[int]: ...
+
+    def write(self, data: ProcessData) -> None: ...
+
+    def read(self, size: int = -1) -> ProcessData: ...
+
+    def read_stderr(self, size: int = -1) -> ProcessData: ...
+
+    def send_eof(self) -> None: ...
+
+    def resize(
+        self,
+        columns: int,
+        rows: int,
+        pixel_width: int = 0,
+        pixel_height: int = 0,
+    ) -> None: ...
+
+    def wait(self, timeout: typing.Optional[float] = None) -> int: ...
+
+    def terminate(self) -> None: ...
+
+    def kill(self) -> None: ...
+
+    def close(self) -> None: ...
+
+    def __enter__(self) -> Process: ...
+
+    def __exit__(
+        self,
+        exc_type: typing.Optional[typing.Type[BaseException]],
+        exc_value: typing.Optional[BaseException],
+        traceback: typing.Optional[types.TracebackType],
+    ) -> bool: ...

hostctl/process/container.py

@@ -0,0 +1,265 @@
+"""Persistent process adapter for Docker Engine exec sockets."""
+
+from __future__ import annotations
+
+import collections
+import codecs
+import socket
+import subprocess
+import time
+import types
+import typing
+
+from ._common import Process, ProcessData
+
+
+class ContainerExecApi(typing.Protocol):
+    def exec_inspect(self, exec_id: str) -> typing.Mapping[str, object]: ...
+
+    def exec_resize(self, exec_id: str, *, height: int, width: int) -> object: ...
+
+
+class _Socket(typing.Protocol):
+    def recv(self, size: int) -> bytes: ...
+
+    def sendall(self, value: bytes) -> None: ...
+
+    def shutdown(self, how: int) -> None: ...
+
+    def close(self) -> None: ...
+
+
+class ContainerProcess(Process):
+    """Synchronous Docker exec channel, with framed non-TTY output."""
+
+    def __init__(
+        self,
+        api: ContainerExecApi,
+        exec_id: str,
+        stream: object,
+        *,
+        tty: bool,
+        command: typing.Sequence[str],
+        encoding: typing.Optional[str] = None,
+        errors: typing.Optional[str] = None,
+    ) -> None:
+        self._api = api
+        self._exec_id = exec_id
+        self._socket = typing.cast(_Socket, getattr(stream, "_sock", stream))
+        self._tty = tty
+        self._command = list(command)
+        self._encoding = encoding
+        self._errors = errors or "strict"
+        self._buffers = {
+            1: collections.deque(),  # type: typing.Deque[bytes]
+            2: collections.deque(),  # type: typing.Deque[bytes]
+        }
+        self._eof = False
+        self._closed = False
+        self._returncode: typing.Optional[int] = None
+        self._wire_buffer = bytearray()
+        self._decoders = {
+            1: (
+                codecs.getincrementaldecoder(encoding)(self._errors)
+                if encoding
+                else None
+            ),
+            2: (
+                codecs.getincrementaldecoder(encoding)(self._errors)
+                if encoding
+                else None
+            ),
+        }
+        settimeout = getattr(self._socket, "settimeout", None)
+        if settimeout is not None:
+            settimeout(None)
+
+    @property
+    def returncode(self) -> typing.Optional[int]:
+        if self._returncode is not None:
+            return self._returncode
+        state = self._api.exec_inspect(self._exec_id)
+        if state.get("Running"):
+            return None
+        value = state.get("ExitCode")
+        if value is None:
+            return None
+        self._returncode = int(value)
+        return self._returncode
+
+    def _encode(self, value: ProcessData) -> bytes:
+        if isinstance(value, bytes):
+            return value
+        return value.encode(self._encoding or "utf-8", self._errors)
+
+    def _decode(
+        self, value: bytes, stream: int = 1, *, final: bool = False
+    ) -> ProcessData:
+        if self._encoding is None:
+            return value
+        decoder = self._decoders[stream]
+        return typing.cast(codecs.IncrementalDecoder, decoder).decode(
+            value, final=final
+        )
+
+    def write(self, data: ProcessData) -> None:
+        if self._closed:
+            raise ValueError("process is closed")
+        self._socket.sendall(self._encode(data))
+
+    def _receive(self) -> None:
+        if self._eof:
+            return
+        if self._tty:
+            value = self._socket.recv(64 * 1024)
+            if value:
+                self._buffers[1].append(value)
+            else:
+                self._eof = True
+            return
+        while not self._consume_frames():
+            chunk = self._socket.recv(64 * 1024)
+            if not chunk:
+                self._finish_wire()
+                return
+            self._wire_buffer.extend(chunk)
+
+    def _consume_frames(self) -> bool:
+        """Consume every complete Docker multiplex frame already buffered."""
+        consumed = False
+        while len(self._wire_buffer) >= 8:
+            length = int.from_bytes(self._wire_buffer[4:8], "big")
+            frame_size = 8 + length
+            if len(self._wire_buffer) < frame_size:
+                break
+            stream = self._wire_buffer[0]
+            payload = bytes(self._wire_buffer[8:frame_size])
+            del self._wire_buffer[:frame_size]
+            if stream in self._buffers and payload:
+                self._buffers[stream].append(payload)
+            consumed = True
+        return consumed
+
+    def _finish_wire(self) -> None:
+        self._eof = True
+        if self._wire_buffer:
+            raise ConnectionError("connection dropped mid-frame")
+
+    def _read_stream(self, stream: int, size: int) -> ProcessData:
+        if self._tty and stream == 2:
+            raise NotImplementedError("TTY sessions combine stdout and stderr")
+        if size == 0:
+            return self._decode(b"")
+        output = bytearray()
+        while size < 0 or len(output) < size:
+            while not self._buffers[stream] and not self._eof:
+                self._receive()
+            if not self._buffers[stream]:
+                break
+            chunk = self._buffers[stream].popleft()
+            if size >= 0 and len(output) + len(chunk) > size:
+                take = size - len(output)
+                output.extend(chunk[:take])
+                self._buffers[stream].appendleft(chunk[take:])
+            else:
+                output.extend(chunk)
+            # read(n) returns as soon as data is available, like SSH and
+            # socket streams; callers needing exactly n bytes can loop.
+            if size >= 0 and output:
+                break
+        return self._decode(bytes(output), stream)
+
+    def read(self, size: int = -1) -> ProcessData:
+        return self._read_stream(1, size)
+
+    def read_stderr(self, size: int = -1) -> ProcessData:
+        return self._read_stream(2, size)
+
+    def send_eof(self) -> None:
+        shutdown = getattr(self._socket, "shutdown", None)
+        if shutdown is None:
+            raise NotImplementedError("exec transport cannot half-close stdin")
+        try:
+            shutdown(socket.SHUT_WR)
+        except (OSError, ValueError) as exc:
+            raise NotImplementedError("exec transport cannot half-close stdin") from exc
+
+    def resize(
+        self,
+        columns: int,
+        rows: int,
+        pixel_width: int = 0,
+        pixel_height: int = 0,
+    ) -> None:
+        if not self._tty:
+            raise NotImplementedError("process does not have a terminal")
+        if columns <= 0 or rows <= 0:
+            raise ValueError("terminal columns and rows must be positive")
+        if pixel_width < 0 or pixel_height < 0:
+            raise ValueError("terminal pixel dimensions must not be negative")
+        self._api.exec_resize(self._exec_id, height=rows, width=columns)
+
+    def wait(self, timeout: typing.Optional[float] = None) -> int:
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            # Drain one available frame before polling.  Non-blocking Docker
+            # sockets raise timeout/BlockingIOError when no data is ready.
+            self._receive_available()
+            returncode = self.returncode
+            if returncode is not None:
+                return returncode
+            if deadline is not None and time.monotonic() >= deadline:
+                raise subprocess.TimeoutExpired(self._command, timeout)
+            time.sleep(0.01)
+
+    def _receive_available(self) -> None:
+        settimeout = getattr(self._socket, "settimeout", None)
+        gettimeout = getattr(self._socket, "gettimeout", None)
+        if settimeout is None:
+            # There is no portable way to prove that recv() will not block.
+            # wait() must keep polling process state rather than deadlock.
+            return
+        previous = gettimeout() if gettimeout is not None else None
+        try:
+            settimeout(0.0)
+            while not self._eof:
+                try:
+                    value = self._socket.recv(64 * 1024)
+                except (socket.timeout, BlockingIOError):
+                    break
+                if not value:
+                    if self._tty:
+                        self._eof = True
+                    else:
+                        self._finish_wire()
+                    break
+                if self._tty:
+                    self._buffers[1].append(value)
+                else:
+                    self._wire_buffer.extend(value)
+                    self._consume_frames()
+        finally:
+            settimeout(previous)
+
+    def terminate(self) -> None:
+        raise NotImplementedError("Docker Engine cannot signal one exec process")
+
+    def kill(self) -> None:
+        raise NotImplementedError("Docker Engine cannot signal one exec process")
+
+    def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            self._socket.close()
+
+    def __enter__(self) -> ContainerProcess:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: typing.Optional[typing.Type[BaseException]],
+        exc_value: typing.Optional[BaseException],
+        traceback: typing.Optional[types.TracebackType],
+    ) -> bool:
+        self.close()
+        return False

hostctl/process/psrp.py

@@ -0,0 +1,208 @@
+"""Persistent PowerShell Remoting Protocol runspace sessions."""
+
+from __future__ import annotations
+
+import dataclasses
+import types
+import typing
+
+from ..executor.psrp import require_pypsrp
+
+
+@dataclasses.dataclass(frozen=True)
+class PipelineStreams:
+    """Typed PowerShell streams returned by one pipeline invocation."""
+
+    error: tuple[object, ...] = ()
+    warning: tuple[object, ...] = ()
+    verbose: tuple[object, ...] = ()
+    debug: tuple[object, ...] = ()
+    information: tuple[object, ...] = ()
+    progress: tuple[object, ...] = ()
+
+
+@dataclasses.dataclass(frozen=True)
+class PipelineResult:
+    """Result of a PSRP pipeline, retaining objects and stream records."""
+
+    output: tuple[object, ...]
+    streams: PipelineStreams
+    state: str
+    had_errors: bool
+    returncode: int
+
+
+def _stream_values(streams: object, name: str) -> tuple[object, ...]:
+    value = getattr(streams, name, ())
+    try:
+        return tuple(value)
+    except TypeError:
+        return (value,) if value is not None else ()
+
+
+def _pipeline_state_name(value: object) -> str:
+    """Normalize pypsrp's integer states and compatible enum-like doubles."""
+    value = getattr(value, "name", getattr(value, "state", value))
+    if isinstance(value, int):
+        return {
+            0: "NotStarted",
+            1: "Running",
+            2: "Stopping",
+            3: "Stopped",
+            4: "Completed",
+            5: "Failed",
+            6: "Disconnected",
+        }.get(value, f"Unknown({value})")
+    return str(value)
+
+
+class RunspaceSession:
+    """A persistent PSRP runspace with typed PowerShell pipeline streams.
+
+    ``RunspaceSession`` intentionally does not implement the byte-oriented
+    ``Process``/``ShellSession`` contract: a runspace is a PowerShell object
+    pipeline, not a TTY and has no raw stdin or resize operations.
+    """
+
+    def __init__(
+        self, config: object | None = None, *, pool: object | None = None
+    ) -> None:
+        self._config = config
+        self._pool = pool
+        self._owns_pool = pool is None
+        self._open = False
+
+    def _make_pool(self) -> object:
+        if self._pool is not None:
+            return self._pool
+        require_pypsrp()
+        from pypsrp.powershell import RunspacePool
+        from pypsrp.wsman import WSMan
+
+        config = self._config
+        if config is None:
+            raise ValueError("a WinRMConfig is required when pool is not supplied")
+        ssl = bool(getattr(config, "ssl", False))
+        endpoint_port = getattr(config, "port", None)
+        kwargs = {
+            "server": getattr(config, "host"),
+            "port": endpoint_port or (5986 if ssl else 5985),
+            "username": getattr(config, "username"),
+            "password": getattr(config, "password", None),
+            "ssl": ssl,
+            "auth": "negotiate",
+            "cert_validation": getattr(config, "server_cert_validation", "validate")
+            == "validate",
+            "encryption": getattr(config, "message_encryption", "auto"),
+            "connection_timeout": getattr(config, "read_timeout_sec", 30),
+            "operation_timeout": getattr(config, "operation_timeout_sec", 20),
+            "read_timeout": getattr(config, "read_timeout_sec", 30),
+        }
+        try:
+            wsman = WSMan(**kwargs)
+        except TypeError:
+            # pypsrp releases have renamed timeout parameters; retry with the
+            # stable connection options and let transport errors surface.
+            kwargs.pop("operation_timeout")
+            kwargs.pop("read_timeout")
+            wsman = WSMan(**kwargs)
+        return RunspacePool(wsman)
+
+    def connect(self) -> None:
+        if self._open:
+            return
+        self._pool = self._make_pool()
+        open_method = getattr(self._pool, "open", None)
+        if open_method is not None:
+            open_method()
+        self._open = True
+
+    def close(self) -> None:
+        if not self._open and self._pool is None:
+            return
+        pool, self._pool = self._pool, None
+        self._open = False
+        if pool is not None:
+            close = getattr(pool, "close", None)
+            if close is not None:
+                close()
+
+    def __enter__(self) -> RunspaceSession:
+        self.connect()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: typing.Optional[typing.Type[BaseException]],
+        exc_value: typing.Optional[BaseException],
+        traceback: typing.Optional[types.TracebackType],
+    ) -> bool:
+        self.close()
+        return False
+
+    def invoke(
+        self,
+        script: object,
+        *args: object,
+        raw: bool = False,
+        capture_exit: bool = False,
+    ) -> PipelineResult:
+        """Invoke a script or executable with persistent runspace state."""
+        self.connect()
+        from ..shell import POWERSHELL
+
+        if args:
+            # PowerShell's call operator preserves executable semantics while
+            # still allowing arguments to be represented as object literals.
+            command = POWERSHELL.quote(script)
+            values = " ".join(POWERSHELL.quote(value) for value in args)
+            script_text = "& {} {}".format(command, values)
+        else:
+            script_text = str(script)
+        marker = "__HOSTCTL_LASTEXITCODE__"
+        if capture_exit:
+            script_text = (
+                f"{script_text}; Write-Output ('{marker}:' + "
+                "[string]([int]$LASTEXITCODE))"
+            )
+        from pypsrp.powershell import PowerShell
+
+        pipeline = PowerShell(self._pool)
+        pipeline.add_script(script_text)
+        output = pipeline.invoke()
+        streams_obj = getattr(pipeline, "streams", object())
+        streams = PipelineStreams(
+            error=_stream_values(streams_obj, "error"),
+            warning=_stream_values(streams_obj, "warning"),
+            verbose=_stream_values(streams_obj, "verbose"),
+            debug=_stream_values(streams_obj, "debug"),
+            information=_stream_values(streams_obj, "information"),
+            progress=_stream_values(streams_obj, "progress"),
+        )
+        state = _pipeline_state_name(getattr(pipeline, "state", "Completed"))
+        had_errors = bool(getattr(pipeline, "had_errors", bool(streams.error)))
+        values = tuple(output or ())
+        returncode = 0 if state.casefold() == "completed" and not had_errors else 1
+        if capture_exit:
+            retained = []
+            for value in values:
+                text_value = str(value)
+                if text_value.startswith(marker + ":"):
+                    try:
+                        parsed_returncode = int(text_value.split(":", 1)[1])
+                        returncode = (
+                            1
+                            if had_errors and parsed_returncode == 0
+                            else parsed_returncode
+                        )
+                    except ValueError:
+                        had_errors = True
+                        returncode = 1
+                else:
+                    retained.append(value)
+            values = tuple(retained)
+        if raw:
+            values = tuple(values)
+        else:
+            values = tuple(str(value) for value in values)
+        return PipelineResult(values, streams, state, had_errors, returncode)