hostctl 0.1.0__py3-none-any.whl

hostctl/process/qemu_serial.py

@@ -0,0 +1,247 @@
+"""Explicit raw QEMU/libvirt console stream sessions."""
+
+from __future__ import annotations
+
+import errno
+import subprocess
+import threading
+import types
+import typing
+
+from ._common import IncrementalTextDecoder, Process, ProcessData, raise_normalized
+
+
+class QemuConsoleStream(typing.Protocol):
+    """Minimal libvirt-stream-like console channel."""
+
+    def send(self, data: bytes) -> int: ...
+
+    def recv(self, size: int) -> bytes: ...
+
+    def finish(self) -> object: ...
+
+    def abort(self) -> object: ...
+
+
+ConsoleStreamFactory = typing.Callable[[], QemuConsoleStream]
+ConsoleResize = typing.Callable[[int, int, int, int], object]
+
+
+def normalize_qemu_console_error(exc: Exception) -> Exception:
+    """Normalize libvirt-like stream failures without importing libvirt."""
+    if isinstance(exc, (ConnectionError, PermissionError, TimeoutError)):
+        return exc
+    if isinstance(exc, OSError):
+        if exc.errno in (errno.EACCES, errno.EPERM):
+            return PermissionError(exc.errno, exc.strerror, exc.filename)
+        if exc.errno in (errno.ETIMEDOUT,):
+            return TimeoutError(str(exc))
+        return ConnectionError(str(exc))
+    message = str(exc)
+    folded = message.casefold()
+    if "permission denied" in folded or "access denied" in folded:
+        return PermissionError(message)
+    if "timed out" in folded or "timeout" in folded:
+        return TimeoutError(message)
+    if type(exc).__name__ in ("libvirtError", "StreamError"):
+        return ConnectionError(message)
+    return exc
+
+
+class QemuSerialConsole:
+    """Grant one exclusive raw process lease over a console stream."""
+
+    def __init__(
+        self,
+        *,
+        stream_factory: typing.Optional[ConsoleStreamFactory] = None,
+        stream: typing.Optional[QemuConsoleStream] = None,
+        owns_stream: bool = False,
+        resize: typing.Optional[ConsoleResize] = None,
+    ) -> None:
+        if (stream_factory is None) == (stream is None):
+            raise ValueError("provide exactly one of stream_factory or stream")
+        self._factory = stream_factory
+        self._stream = stream
+        self._owns_stream = owns_stream if stream is not None else True
+        self._resize = resize
+        self._lease = threading.Lock()
+        self._io_lock = threading.RLock()
+
+    def open(self) -> QemuSerialProcess:
+        if not self._lease.acquire(blocking=False):
+            raise RuntimeError("QEMU console already has an active process")
+        try:
+            stream = self._stream
+            if stream is None:
+                assert self._factory is not None
+                stream = self._factory()
+                self._stream = stream
+        except Exception as exc:
+            self._lease.release()
+            normalized = normalize_qemu_console_error(exc)
+            if normalized is exc:
+                raise
+            raise normalized from exc
+        return QemuSerialProcess(
+            stream,
+            io_lock=self._io_lock,
+            release=self._release,
+            close_stream=self._owns_stream,
+            resize=self._resize,
+        )
+
+    def _release(self) -> None:
+        if self._owns_stream:
+            self._stream = None
+        self._lease.release()
+
+
+class QemuSerialProcess(Process):
+    """Raw merged byte I/O over one libvirt console/channel stream."""
+
+    def __init__(
+        self,
+        stream: QemuConsoleStream,
+        *,
+        io_lock: typing.Optional[threading.RLock] = None,
+        release: typing.Callable[[], None],
+        close_stream: bool = True,
+        resize: typing.Optional[ConsoleResize] = None,
+        encoding: typing.Optional[str] = None,
+        errors: typing.Optional[str] = None,
+    ) -> None:
+        self._stream = stream
+        self._io_lock = io_lock or threading.RLock()
+        self._release = release
+        self._close_stream = close_stream
+        self._resize = resize
+        self._encoding = encoding
+        self._errors = errors or "strict"
+        self._closed = threading.Event()
+        self._decoder = (
+            IncrementalTextDecoder(encoding, self._errors)
+            if encoding is not None
+            else None
+        )
+
+    @property
+    def returncode(self) -> typing.Optional[int]:
+        return 0 if self._closed.is_set() else None
+
+    def _require_open(self) -> None:
+        if self._closed.is_set():
+            raise ConnectionError("QEMU console process is closed")
+
+    def write(self, data: ProcessData) -> None:
+        if isinstance(data, str):
+            if self._encoding is None:
+                raise TypeError("raw QEMU console writes require bytes")
+            data = data.encode(self._encoding, self._errors)
+        self._require_open()
+        offset = 0
+        try:
+            with self._io_lock:
+                while offset < len(data):
+                    sent = self._stream.send(data[offset:])
+                    if sent <= 0:
+                        raise ConnectionError("QEMU console write made no progress")
+                    offset += sent
+        except Exception as exc:
+            raise_normalized(exc, normalize_qemu_console_error)
+
+    def read(self, size: int = -1) -> ProcessData:
+        self._require_open()
+        if size < -1:
+            raise ValueError("read size must be -1 or non-negative")
+        if size == 0:
+            return b""
+        request_size = 64 * 1024 if size == -1 else size
+        try:
+            with self._io_lock:
+                value = self._stream.recv(request_size)
+        except Exception as exc:
+            raise_normalized(exc, normalize_qemu_console_error)
+        if not value:
+            self._finish(closing_stream=self._close_stream)
+        if self._decoder is not None:
+            return self._decoder.decode(value, final=not value)
+        return value
+
+    def read_stderr(self, size: int = -1) -> bytes:
+        raise NotImplementedError("QEMU serial consoles have one merged byte stream")
+
+    def send_eof(self) -> None:
+        raise NotImplementedError(
+            "QEMU console streams do not support a generic half-close"
+        )
+
+    def resize(
+        self,
+        columns: int,
+        rows: int,
+        pixel_width: int = 0,
+        pixel_height: int = 0,
+    ) -> None:
+        self._require_open()
+        if self._resize is None:
+            raise NotImplementedError(
+                "QEMU console backend does not support terminal resize"
+            )
+        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")
+        try:
+            self._resize(columns, rows, pixel_width, pixel_height)
+        except Exception as exc:
+            raise_normalized(exc, normalize_qemu_console_error)
+
+    def wait(self, timeout: typing.Optional[float] = None) -> int:
+        if timeout is not None and timeout < 0:
+            raise ValueError("timeout must not be negative")
+        if not self._closed.wait(timeout):
+            raise subprocess.TimeoutExpired("QEMU serial console", timeout)
+        return 0
+
+    def terminate(self) -> None:
+        raise NotImplementedError(
+            "QEMU serial consoles have no generic terminate signal"
+        )
+
+    def kill(self) -> None:
+        raise NotImplementedError("QEMU serial consoles have no generic kill signal")
+
+    def close(self) -> None:
+        self._finish(closing_stream=self._close_stream)
+
+    def _finish(self, *, closing_stream: bool) -> None:
+        if self._closed.is_set():
+            return
+        error: typing.Optional[Exception] = None
+        if closing_stream:
+            try:
+                with self._io_lock:
+                    self._stream.finish()
+            except Exception as exc:
+                error = exc
+                try:
+                    self._stream.abort()
+                except Exception:
+                    pass
+        self._closed.set()
+        self._release()
+        if error is not None:
+            raise_normalized(error, normalize_qemu_console_error)
+
+    def __enter__(self) -> QemuSerialProcess:
+        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/serial.py

@@ -0,0 +1,257 @@
+"""Raw byte-stream process facade for a serial connection."""
+
+from __future__ import annotations
+
+import subprocess
+import threading
+import types
+import typing
+
+from ._common import Process, ProcessData, raise_normalized
+from ..executor.serial import SerialLike, normalize_serial_error
+
+
+class SerialProcess(Process):
+    """Exclusive raw access to one serial connection."""
+
+    def __init__(
+        self,
+        serial_port: SerialLike,
+        *,
+        io_lock: threading.RLock,
+        release: typing.Callable[[], None],
+    ) -> None:
+        self._serial = serial_port
+        self._io_lock = io_lock
+        self._release = release
+        self._closed = threading.Event()
+
+    @property
+    def returncode(self) -> typing.Optional[int]:
+        return 0 if self._closed.is_set() else None
+
+    def _require_open(self) -> None:
+        if self._closed.is_set() or not self._serial.is_open:
+            raise ConnectionError("serial process is closed")
+
+    def write(self, data: ProcessData) -> None:
+        if isinstance(data, str):
+            raise TypeError("raw serial process writes require bytes")
+        self._require_open()
+        offset = 0
+        try:
+            with self._io_lock:
+                while offset < len(data):
+                    written = self._serial.write(data[offset:])
+                    if written <= 0:
+                        raise TimeoutError("serial write made no progress")
+                    offset += written
+                self._serial.flush()
+        except Exception as exc:
+            normalized = normalize_serial_error(exc)
+            if normalized is exc:
+                raise
+            raise normalized from exc
+
+    def read(self, size: int = -1) -> bytes:
+        self._require_open()
+        if size < -1:
+            raise ValueError("read size must be -1 or non-negative")
+        if size == -1:
+            available = getattr(self._serial, "in_waiting", None)
+            if available is not None:
+                size = min(max(int(available), 0), 64 * 1024)
+                if size == 0:
+                    return b""
+            else:
+                # A generic injected serial object may not expose an
+                # availability count. Read at most one byte rather than
+                # blocking for an arbitrary 64 KiB request.
+                size = 1
+        try:
+            with self._io_lock:
+                return self._serial.read(size)
+        except Exception as exc:
+            raise_normalized(exc, normalize_serial_error)
+
+    def read_stderr(self, size: int = -1) -> bytes:
+        raise NotImplementedError("serial has one merged byte stream")
+
+    def send_eof(self) -> None:
+        raise NotImplementedError("serial connections do not support half-close")
+
+    def resize(
+        self,
+        columns: int,
+        rows: int,
+        pixel_width: int = 0,
+        pixel_height: int = 0,
+    ) -> None:
+        raise NotImplementedError("serial terminals cannot be resized generically")
+
+    def wait(self, timeout: typing.Optional[float] = None) -> int:
+        if timeout is not None and timeout < 0:
+            raise ValueError("timeout must not be negative")
+        if not self._closed.wait(timeout):
+            raise subprocess.TimeoutExpired("serial session", timeout)
+        return 0
+
+    def terminate(self) -> None:
+        raise NotImplementedError("serial has no generic terminate signal")
+
+    def kill(self) -> None:
+        raise NotImplementedError("serial has no generic kill signal")
+
+    def send_break(self, duration: float = 0.25) -> None:
+        if duration < 0:
+            raise ValueError("break duration must not be negative")
+        self._require_open()
+        try:
+            with self._io_lock:
+                self._serial.send_break(duration)
+        except Exception as exc:
+            normalized = normalize_serial_error(exc)
+            if normalized is exc:
+                raise
+            raise normalized from exc
+
+    def reset_input_buffer(self) -> None:
+        """Discard stale bytes before a protocol negotiation or command."""
+        self._require_open()
+        reset = getattr(self._serial, "reset_input_buffer", None)
+        if not callable(reset):
+            raise NotImplementedError("serial backend cannot reset its input buffer")
+        try:
+            with self._io_lock:
+                reset()
+        except Exception as exc:
+            raise_normalized(exc, normalize_serial_error)
+
+    @property
+    def dtr(self) -> bool:
+        self._require_open()
+        return self._serial.dtr
+
+    @dtr.setter
+    def dtr(self, value: bool) -> None:
+        self._require_open()
+        self._serial.dtr = bool(value)
+
+    @property
+    def rts(self) -> bool:
+        self._require_open()
+        return self._serial.rts
+
+    @rts.setter
+    def rts(self, value: bool) -> None:
+        self._require_open()
+        self._serial.rts = bool(value)
+
+    def close(self) -> None:
+        if self._closed.is_set():
+            return
+        self._closed.set()
+        self._release()
+
+    def __enter__(self) -> SerialProcess:
+        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
+
+
+class SerialConsoleProcess(Process):
+    """Console-aware wrapper used by :class:`hostctl.host.SerialHost`.
+
+    It keeps the raw process lease while allowing shell sessions to submit
+    text.  Reads remain merged bytes; framing and prompt interpretation belong
+    to the selected profile.
+    """
+
+    def __init__(
+        self, process: SerialProcess, profile: object, encoding: str = "utf-8"
+    ) -> None:
+        self.process = process
+        self.profile = profile
+        self.encoding = encoding
+
+    @property
+    def returncode(self):
+        return self.process.returncode
+
+    def write(self, data: ProcessData) -> None:
+        if isinstance(data, str):
+            data = data.encode(self.encoding)
+        self.process.write(data)
+
+    def read(self, size: int = -1) -> bytes:
+        value = self.process.read(size)
+        return typing.cast(bytes, value)
+
+    def read_stderr(self, size: int = -1) -> bytes:
+        return self.process.read_stderr(size)
+
+    def send_eof(self) -> None:
+        self.process.send_eof()
+
+    def resize(
+        self, columns: int, rows: int, pixel_width: int = 0, pixel_height: int = 0
+    ) -> None:
+        self.process.resize(columns, rows, pixel_width, pixel_height)
+
+    def wait(self, timeout: typing.Optional[float] = None) -> int:
+        return self.process.wait(timeout)
+
+    def terminate(self) -> None:
+        self.process.terminate()
+
+    def kill(self) -> None:
+        self.process.kill()
+
+    def close(self) -> None:
+        self.process.close()
+
+    def send_break(self, duration: float = 0.25) -> None:
+        self.process.send_break(duration)
+
+    @property
+    def dtr(self) -> bool:
+        return self.process.dtr
+
+    @dtr.setter
+    def dtr(self, value: bool) -> None:
+        self.process.dtr = value
+
+    @property
+    def rts(self) -> bool:
+        return self.process.rts
+
+    @rts.setter
+    def rts(self, value: bool) -> None:
+        self.process.rts = value
+
+    def send_command(self, command: str | bytes) -> None:
+        sender = getattr(self.profile, "send", None)
+        if not callable(sender):
+            raise NotImplementedError("console profile cannot send commands")
+        sender(self.process, command)
+
+    def send(self, *commands: str | bytes) -> None:
+        """Submit one or more profile-framed console commands."""
+        if not commands:
+            raise ValueError("send requires at least one command")
+        for command in commands:
+            self.send_command(command)
+
+    def __enter__(self) -> "SerialConsoleProcess":
+        self.process.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> bool:
+        return self.process.__exit__(exc_type, exc_value, traceback)

hostctl/process/ssh.py

@@ -0,0 +1,165 @@
+"""Persistent process adapter for AsyncSSH channels."""
+
+from __future__ import annotations
+
+import types
+import typing
+import inspect
+
+from ._common import Process, ProcessData
+
+
+class _Reader(typing.Protocol):
+    def read(self, size: int = -1) -> typing.Awaitable[ProcessData]: ...
+
+
+class _Writer(typing.Protocol):
+    def write(self, data: ProcessData) -> None: ...
+
+    def drain(self) -> typing.Awaitable[None]: ...
+
+    def write_eof(self) -> None: ...
+
+
+class _Completed(typing.Protocol):
+    returncode: int
+
+
+class _AsyncsshProcess(typing.Protocol):
+    returncode: typing.Optional[int]
+    stdin: _Writer
+    stdout: _Reader
+    stderr: _Reader
+
+    def change_terminal_size(
+        self, width: int, height: int, pixwidth: int, pixheight: int
+    ) -> None: ...
+
+    def close(self) -> None: ...
+
+    def kill(self) -> None: ...
+
+    def terminate(self) -> None: ...
+
+    def wait(
+        self, check: bool = False, timeout: typing.Optional[float] = None
+    ) -> typing.Awaitable[_Completed]: ...
+
+    def wait_closed(self) -> typing.Awaitable[None]: ...
+
+
+class SshProcess(Process):
+    """Synchronous facade over a process owned by hostctl's AsyncSSH loop."""
+
+    def __init__(
+        self, process: _AsyncsshProcess, command: typing.Optional[str]
+    ) -> None:
+        self._process = process
+        self._command = command
+        self._closed = False
+
+    @property
+    def returncode(self) -> typing.Optional[int]:
+        return self._process.returncode
+
+    def _call(self, function: typing.Callable[[], object]) -> object:
+        from .. import _async
+
+        async def invoke() -> object:
+            result = function()
+            if inspect.isawaitable(result):
+                return await result
+            return result
+
+        try:
+            return _async.async_to_sync(invoke())
+        except Exception as exc:
+            normalized = _async.normalize_asyncssh_error(exc, command=self._command)
+            if normalized is exc:
+                raise
+            raise normalized from exc
+
+    def write(self, data: ProcessData) -> None:
+        async def operation() -> None:
+            writer = self._process.stdin
+            writer.write(data)
+            await writer.drain()
+
+        self._call(operation)
+
+    def read(self, size: int = -1) -> ProcessData:
+        return self._call(lambda: self._process.stdout.read(size))
+
+    def read_stderr(self, size: int = -1) -> ProcessData:
+        return self._call(lambda: self._process.stderr.read(size))
+
+    def send_eof(self) -> None:
+        def operation() -> None:
+            self._process.stdin.write_eof()
+
+        self._call(operation)
+
+    def resize(
+        self,
+        columns: int,
+        rows: int,
+        pixel_width: int = 0,
+        pixel_height: int = 0,
+    ) -> None:
+        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._call(
+            lambda: self._process.change_terminal_size(
+                columns, rows, pixel_width, pixel_height
+            )
+        )
+
+    def wait(self, timeout: typing.Optional[float] = None) -> int:
+        try:
+            from .. import _async
+
+            result = _async.async_to_sync(
+                self._process.wait(check=False, timeout=timeout)
+            )
+        except Exception as exc:
+            normalized = _async.normalize_asyncssh_error(
+                exc, command=self._command, timeout=timeout
+            )
+            if normalized is exc:
+                raise
+            raise normalized from exc
+        return -1 if result.returncode is None else result.returncode
+
+    def terminate(self) -> None:
+        self._call(self._process.terminate)
+
+    def kill(self) -> None:
+        self._call(self._process.kill)
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        from .. import _async
+
+        try:
+            self._call(self._process.close)
+            self._call(lambda: self._process.wait_closed())
+        except Exception:
+            # A failed close remains retryable; callers must not lose the
+            # channel reference merely because the first close attempt failed.
+            raise
+        self._closed = True
+
+    def __enter__(self) -> SshProcess:
+        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/provider/__init__.py

@@ -0,0 +1,33 @@
+"""Composable execution and filesystem provider contracts.
+
+The names exported here are the *authoring* surface: the base classes an
+integration instantiates or subclasses to reach a new transport, the probe and
+selection records it exchanges with a host, and the one exception that permits
+fallback.  See the "Systems and providers" guide for the authoring contract.
+
+The built-in transport adapters in :mod:`hostctl.provider.transports` are how
+``LocalHost``, ``ContainerHost``, and ``QemuHost`` assemble themselves.  They
+are importable from that module but deliberately absent from ``__all__``: no
+caller constructs them, and their capability frozensets describe backends
+hostctl owns rather than a contract a caller implements against.
+"""
+
+from ._common import (
+    ExecutorProvider,
+    OperationNotStarted,
+    PathProvider,
+    ProviderProbe,
+    ProviderSelection,
+    ProviderSelector,
+    SessionInitializer,
+)
+
+__all__ = [
+    "ExecutorProvider",
+    "OperationNotStarted",
+    "PathProvider",
+    "ProviderProbe",
+    "ProviderSelection",
+    "ProviderSelector",
+    "SessionInitializer",
+]