hostctl 0.1.0__py3-none-any.whl

hostctl/executor/qemu.py

@@ -0,0 +1,305 @@
+"""Buffered command execution through the QEMU Guest Agent."""
+
+from __future__ import annotations
+
+import base64
+import os
+import subprocess
+import time
+import typing
+
+from ._qga import GuestAgentTransport, QgaProtocolError
+from ._common import (
+    CaptureOutput,
+    CommandArgument,
+    Environment,
+    Executor,
+    ExecutorCapability,
+    ExecutorCommand,
+    FileHandle,
+    Input,
+    PathLike,
+    dispatch_output,
+    normalize_environment,
+    normalize_input,
+    capture_streams,
+    reject_stdin_conflict,
+)
+
+
+class GuestAgentProtocolError(QgaProtocolError):
+    """A guest-agent response did not satisfy the QGA command contract."""
+
+
+def _read_input(
+    stream: FileHandle,
+    *,
+    encoding: typing.Optional[str],
+    errors: typing.Optional[str],
+) -> bytes:
+    if stream == subprocess.DEVNULL:
+        return b""
+    if stream == subprocess.PIPE:
+        raise ValueError("stdin=subprocess.PIPE requires input")
+    if isinstance(stream, int):
+        with os.fdopen(os.dup(stream), "rb") as duplicate:
+            value = duplicate.read()
+    else:
+        value = stream.read()
+    if isinstance(value, str):
+        return value.encode(encoding or "utf-8", errors or "strict")
+    return value
+
+
+def _decode_output(value: object, field: str) -> bytes:
+    if value is None:
+        return b""
+    if not isinstance(value, str):
+        raise GuestAgentProtocolError(f"{field} must be Base64 text")
+    try:
+        return base64.b64decode(value, validate=True)
+    except (ValueError, TypeError) as exc:
+        raise GuestAgentProtocolError(f"{field} is not valid Base64") from exc
+
+
+class QemuExecutor(Executor[subprocess.CompletedProcess]):
+    """Execute direct argv through QGA's buffered ``guest-exec`` RPC."""
+
+    executor_capabilities = frozenset((ExecutorCapability.ARGS, ExecutorCapability.ENV))
+
+    def __init__(
+        self,
+        transport: typing.Callable[[], GuestAgentTransport],
+        *,
+        poll_interval: float = 0.01,
+        max_poll_interval: float = 0.25,
+        clock: typing.Callable[[], float] = time.monotonic,
+        sleep: typing.Callable[[float], None] = time.sleep,
+    ) -> None:
+        if poll_interval <= 0:
+            raise ValueError("poll_interval must be positive")
+        if max_poll_interval < poll_interval:
+            raise ValueError("max_poll_interval must be at least poll_interval")
+        self._transport = transport
+        self._poll_interval = poll_interval
+        self._max_poll_interval = max_poll_interval
+        self._clock = clock
+        self._sleep = sleep
+
+    def __call__(
+        self,
+        command: ExecutorCommand,
+        *args: CommandArgument,
+        bufsize: int = -1,
+        stdin: typing.Optional[FileHandle] = None,
+        stdout: typing.Optional[FileHandle] = None,
+        stderr: typing.Optional[FileHandle] = None,
+        cwd: typing.Optional[PathLike] = None,
+        env: typing.Optional[Environment] = None,
+        capture_output: CaptureOutput = True,
+        check: bool = True,
+        encoding: typing.Optional[str] = None,
+        errors: typing.Optional[str] = None,
+        input: Input = None,
+        timeout: typing.Optional[float] = None,
+        text: typing.Optional[bool] = None,
+        **options: object,
+    ) -> subprocess.CompletedProcess:
+        del bufsize
+        if options:
+            raise TypeError(f"unsupported QEMU executor option: {sorted(options)[0]}")
+        if cwd is not None:
+            raise NotImplementedError(
+                "QGA guest-exec has no native working-directory support"
+            )
+        reject_stdin_conflict(input, stdin)
+        if not str(command):
+            raise ValueError("QGA guest-exec path must not be empty")
+        if timeout is not None and timeout < 0:
+            raise ValueError("timeout must not be negative")
+        if text and encoding is None:
+            encoding = "utf-8"
+
+        stdout, stderr = capture_streams(capture_output, stdout, stderr)
+        argv = [
+            (
+                value.decode(encoding or "utf-8", errors or "strict")
+                if isinstance(value, bytes)
+                else str(value)
+            )
+            for value in args
+        ]
+        arguments: typing.Dict[str, object] = {
+            "path": str(command),
+            "arg": argv,
+            "capture-output": True,
+        }
+        normalized_env = normalize_environment(env)
+        if normalized_env is not None:
+            arguments["env"] = [
+                f"{key}={value}" for key, value in normalized_env.items()
+            ]
+        if input is not None:
+            # QGA carries stdin base64-encoded, so this leg is always binary.
+            payload = normalize_input(
+                input, text_mode=False, encoding=encoding, errors=errors
+            )
+            arguments["input-data"] = base64.b64encode(
+                typing.cast(bytes, payload)
+            ).decode("ascii")
+        elif stdin is not None:
+            payload = _read_input(
+                stdin,
+                encoding=encoding,
+                errors=errors,
+            )
+            arguments["input-data"] = base64.b64encode(payload).decode("ascii")
+
+        deadline = None if timeout is None else self._clock() + timeout
+        command_display = [str(command), *argv]
+        started = self._execute(
+            {"execute": "guest-exec", "arguments": arguments},
+            deadline,
+            command_display,
+            timeout=timeout,
+        )
+        if not isinstance(started, typing.Mapping):
+            raise GuestAgentProtocolError("guest-exec returned a non-object result")
+        pid = started.get("pid")
+        if not isinstance(pid, int) or isinstance(pid, bool):
+            raise GuestAgentProtocolError("guest-exec did not return an integer PID")
+
+        status = self._wait(pid, deadline, command_display, timeout)
+        out = _decode_output(status.get("out-data"), "out-data")
+        err = _decode_output(status.get("err-data"), "err-data")
+        returncode = status.get("exitcode")
+        if not isinstance(returncode, int) or isinstance(returncode, bool):
+            signal = status.get("signal")
+            if isinstance(signal, int) and not isinstance(signal, bool):
+                returncode = -signal
+            else:
+                raise GuestAgentProtocolError(
+                    "completed guest-exec status has no integer exit code or signal"
+                )
+
+        if text or encoding is not None or errors is not None:
+            codec = encoding or "utf-8"
+            out = out.decode(codec, errors or "strict")
+            err = err.decode(codec, errors or "strict")
+        if stderr is subprocess.STDOUT:
+            out += err
+            err = None
+        out, err = dispatch_output(
+            stdout,
+            stderr,
+            out,
+            err,
+            encoding=encoding,
+            errors=errors,
+        )
+        completed = subprocess.CompletedProcess(
+            command_display,
+            returncode,
+            out,
+            err,
+        )
+        completed.pid = pid
+        completed.stdout_truncated = bool(status.get("out-truncated", False))
+        completed.stderr_truncated = bool(status.get("err-truncated", False))
+        if check:
+            completed.check_returncode()
+        return completed
+
+    def _execute(
+        self,
+        request: typing.Mapping[str, object],
+        deadline: typing.Optional[float],
+        command: typing.Sequence[str],
+        timeout: typing.Optional[float] = None,
+    ) -> object:
+        remaining = self._remaining(deadline, command, timeout=timeout)
+        try:
+            return self._transport().execute(request, timeout=remaining)
+        except (TimeoutError, subprocess.TimeoutExpired) as exc:
+            expired = subprocess.TimeoutExpired(command, remaining)
+            expired.orphaned = request.get("execute") == "guest-exec"
+            raise expired from exc
+
+    def _wait(
+        self,
+        pid: int,
+        deadline: typing.Optional[float],
+        command: typing.Sequence[str],
+        timeout: typing.Optional[float],
+    ) -> typing.Mapping[str, object]:
+        interval = self._poll_interval
+        partial_out = b""
+        partial_err = b""
+        while True:
+            try:
+                result = self._execute(
+                    {
+                        "execute": "guest-exec-status",
+                        "arguments": {"pid": pid},
+                    },
+                    deadline,
+                    command,
+                    timeout=timeout,
+                )
+            except subprocess.TimeoutExpired as exc:
+                self._annotate_timeout(exc, pid, timeout, partial_out, partial_err)
+                raise
+            if not isinstance(result, typing.Mapping):
+                raise GuestAgentProtocolError(
+                    "guest-exec-status returned a non-object result"
+                )
+            if not isinstance(result.get("exited"), bool):
+                raise GuestAgentProtocolError(
+                    "guest-exec-status has no boolean exited field"
+                )
+            if "out-data" in result:
+                partial_out = _decode_output(result.get("out-data"), "out-data")
+            if "err-data" in result:
+                partial_err = _decode_output(result.get("err-data"), "err-data")
+            if result.get("exited") is True:
+                return result
+            try:
+                remaining = self._remaining(deadline, command, pid, timeout)
+            except subprocess.TimeoutExpired as exc:
+                self._annotate_timeout(exc, pid, timeout, partial_out, partial_err)
+                raise
+            delay = interval if remaining is None else min(interval, remaining)
+            self._sleep(delay)
+            interval = min(interval * 2, self._max_poll_interval)
+
+    @staticmethod
+    def _annotate_timeout(
+        exc: subprocess.TimeoutExpired,
+        pid: int,
+        timeout: typing.Optional[float],
+        stdout: bytes,
+        stderr: bytes,
+    ) -> None:
+        exc.timeout = timeout
+        exc.pid = pid
+        exc.orphaned = True
+        exc.output = stdout
+        exc.stderr = stderr
+
+    def _remaining(
+        self,
+        deadline: typing.Optional[float],
+        command: typing.Sequence[str],
+        pid: typing.Optional[int] = None,
+        timeout: typing.Optional[float] = None,
+    ) -> typing.Optional[float]:
+        if deadline is None:
+            return None
+        remaining = deadline - self._clock()
+        if remaining > 0:
+            return remaining
+        expired = subprocess.TimeoutExpired(command, timeout)
+        expired.orphaned = pid is not None
+        if pid is not None:
+            expired.pid = pid
+        raise expired

hostctl/executor/serial.py

@@ -0,0 +1,312 @@
+"""Raw serial transport ownership without console or shell assumptions."""
+
+from __future__ import annotations
+
+import dataclasses
+import errno
+import contextlib
+import threading
+import time
+import types
+import typing
+
+if typing.TYPE_CHECKING:
+    from ..process.serial import SerialProcess
+
+
+class SerialLike(typing.Protocol):
+    is_open: bool
+    dtr: bool
+    rts: bool
+    timeout: typing.Optional[float]
+    write_timeout: typing.Optional[float]
+
+    def close(self) -> None: ...
+
+    def flush(self) -> None: ...
+
+    def read(self, size: int = 1) -> bytes: ...
+
+    def send_break(self, duration: float = 0.25) -> None: ...
+
+    def write(self, data: bytes) -> int: ...
+
+
+SerialFactory = typing.Callable[..., SerialLike]
+
+
+class SerialTransport:
+    """Locked byte transport used by protocol profiles and tests."""
+
+    def __init__(
+        self,
+        serial_port: SerialLike,
+        *,
+        lock: typing.Optional[threading.RLock] = None,
+    ) -> None:
+        self.serial = serial_port
+        self.lock = lock or threading.RLock()
+
+    @property
+    def connected(self) -> bool:
+        return bool(self.serial.is_open)
+
+    @contextlib.contextmanager
+    def _deadline_timeout(
+        self, attribute: str, deadline: typing.Optional[float]
+    ) -> typing.Iterator[None]:
+        if deadline is None:
+            yield
+            return
+        if not hasattr(self.serial, attribute):
+            raise NotImplementedError(
+                f"serial backend cannot enforce a finite {attribute.replace('_', ' ')}"
+            )
+        previous = getattr(self.serial, attribute)
+        remaining = max(0.0, deadline - time.monotonic())
+        setattr(self.serial, attribute, remaining)
+        try:
+            yield
+        finally:
+            setattr(self.serial, attribute, previous)
+
+    def read(
+        self, size: int = 4096, *, timeout: typing.Optional[float] = None
+    ) -> bytes:
+        if size < 0:
+            raise ValueError("read size must not be negative")
+        deadline = None if timeout is None else time.monotonic() + timeout
+        if timeout is not None and timeout < 0:
+            raise ValueError("timeout must not be negative")
+        with self.lock:
+            while True:
+                with self._deadline_timeout("timeout", deadline):
+                    value = self.serial.read(size)
+                if value or deadline is None or time.monotonic() >= deadline:
+                    return value
+
+    def write(self, data: bytes, *, timeout: typing.Optional[float] = None) -> None:
+        deadline = None if timeout is None else time.monotonic() + timeout
+        if timeout is not None and timeout < 0:
+            raise ValueError("timeout must not be negative")
+        offset = 0
+        with self.lock:
+            while offset < len(data):
+                with self._deadline_timeout("write_timeout", deadline):
+                    written = self.serial.write(data[offset:])
+                if written <= 0:
+                    raise TimeoutError("serial write made no progress")
+                offset += written
+                if (
+                    deadline is not None
+                    and time.monotonic() >= deadline
+                    and offset < len(data)
+                ):
+                    raise TimeoutError("serial write timed out")
+            self.serial.flush()
+
+    def reset_input_buffer(self) -> None:
+        reset = getattr(self.serial, "reset_input_buffer", None)
+        if callable(reset):
+            with self.lock:
+                reset()
+
+    @property
+    def dtr(self) -> bool:
+        return bool(self.serial.dtr)
+
+    @dtr.setter
+    def dtr(self, value: bool) -> None:
+        with self.lock:
+            self.serial.dtr = bool(value)
+
+    @property
+    def rts(self) -> bool:
+        return bool(self.serial.rts)
+
+    @rts.setter
+    def rts(self, value: bool) -> None:
+        with self.lock:
+            self.serial.rts = bool(value)
+
+    def send_break(self, duration: float = 0.25) -> None:
+        with self.lock:
+            self.serial.send_break(duration)
+
+    def close(self) -> None:
+        with self.lock:
+            self.serial.close()
+
+
+@dataclasses.dataclass(frozen=True)
+class SerialSettings:
+    """Validated settings passed unchanged to ``serial_for_url``."""
+
+    port: str
+    baudrate: int = 115200
+    bytesize: int = 8
+    parity: str = "N"
+    stopbits: float = 1
+    xonxoff: bool = False
+    rtscts: bool = False
+    dsrdtr: bool = False
+    read_timeout: typing.Optional[float] = 0.1
+    write_timeout: typing.Optional[float] = 10
+    inter_byte_timeout: typing.Optional[float] = None
+    exclusive: typing.Optional[bool] = None
+
+    def __post_init__(self) -> None:
+        if not self.port:
+            raise ValueError("serial port must not be empty")
+        if self.baudrate <= 0:
+            raise ValueError("baudrate must be positive")
+        if self.bytesize not in (5, 6, 7, 8):
+            raise ValueError("bytesize must be 5, 6, 7, or 8")
+        if self.parity.upper() not in ("N", "E", "O", "M", "S"):
+            raise ValueError("parity must be N, E, O, M, or S")
+        object.__setattr__(self, "parity", self.parity.upper())
+        if self.stopbits not in (1, 1.5, 2):
+            raise ValueError("stopbits must be 1, 1.5, or 2")
+        for name in ("read_timeout", "write_timeout", "inter_byte_timeout"):
+            value = getattr(self, name)
+            if value is not None and value < 0:
+                raise ValueError(f"{name} must not be negative")
+
+    def factory_options(self) -> typing.Dict[str, object]:
+        options: typing.Dict[str, object] = {
+            "baudrate": self.baudrate,
+            "bytesize": self.bytesize,
+            "parity": self.parity,
+            "stopbits": self.stopbits,
+            "xonxoff": self.xonxoff,
+            "rtscts": self.rtscts,
+            "dsrdtr": self.dsrdtr,
+            "timeout": self.read_timeout,
+            "write_timeout": self.write_timeout,
+            "inter_byte_timeout": self.inter_byte_timeout,
+        }
+        if self.exclusive is not None:
+            options["exclusive"] = self.exclusive
+        return options
+
+
+def _default_serial_factory(port: str, **options: object) -> SerialLike:
+    try:
+        import serial
+    except ImportError as exc:
+        raise ImportError(
+            "serial support requires the 'serial' extra: " "pip install hostctl[serial]"
+        ) from exc
+    return typing.cast(SerialLike, serial.serial_for_url(port, **options))
+
+
+def normalize_serial_error(exc: Exception) -> Exception:
+    """Normalize pyserial/native failures without requiring pyserial at import."""
+    if isinstance(exc, (FileNotFoundError, PermissionError, TimeoutError)):
+        return exc
+    if isinstance(exc, OSError):
+        if exc.errno == errno.ENOENT:
+            return FileNotFoundError(exc.errno, exc.strerror, exc.filename)
+        if exc.errno in (errno.EACCES, errno.EPERM):
+            return PermissionError(exc.errno, exc.strerror, exc.filename)
+    name = type(exc).__name__
+    if name == "SerialTimeoutException":
+        return TimeoutError(str(exc))
+    if name in ("SerialException", "PortNotOpenError"):
+        return ConnectionError(str(exc))
+    return exc
+
+
+class SerialExecutor:
+    """Own one raw serial connection and grant one exclusive process lease."""
+
+    def __init__(
+        self,
+        settings: SerialSettings,
+        *,
+        serial_factory: typing.Optional[SerialFactory] = None,
+        serial_port: typing.Optional[SerialLike] = None,
+        owns_serial_port: bool = False,
+    ) -> None:
+        if serial_factory is not None and serial_port is not None:
+            raise ValueError("serial_factory and serial_port are mutually exclusive")
+        self.settings = settings
+        self._factory = serial_factory or _default_serial_factory
+        self._serial = serial_port
+        self._injected = serial_port is not None
+        self._owns_serial = owns_serial_port if serial_port is not None else True
+        self._lease = threading.Lock()
+        self._io_lock = threading.RLock()
+        self._connect_lock = threading.Lock()
+
+    @property
+    def connected(self) -> bool:
+        return self._serial is not None and self._serial.is_open
+
+    @property
+    def transport(self) -> SerialTransport:
+        """Return the locked transport for protocol/profile integrations."""
+        serial_port = self.connect()
+        return SerialTransport(serial_port, lock=self._io_lock)
+
+    def connect(self) -> SerialLike:
+        with self._connect_lock:
+            if self.connected:
+                return typing.cast(SerialLike, self._serial)
+            if self._injected:
+                raise ConnectionError("injected serial port is closed")
+            try:
+                self._serial = self._factory(
+                    self.settings.port, **self.settings.factory_options()
+                )
+            except Exception as exc:
+                normalized = normalize_serial_error(exc)
+                if normalized is exc:
+                    raise
+                raise normalized from exc
+            return typing.cast(SerialLike, self._serial)
+
+    def open(self) -> SerialProcess:
+        """Acquire the connection for one raw byte-stream process."""
+        if not self._lease.acquire(blocking=False):
+            raise RuntimeError("serial connection already has an active process")
+        try:
+            serial_port = self.connect()
+        except Exception:
+            self._lease.release()
+            raise
+        from ..process.serial import SerialProcess
+
+        return SerialProcess(
+            serial_port,
+            io_lock=self._io_lock,
+            release=self._release,
+        )
+
+    def _release(self) -> None:
+        self._lease.release()
+
+    def close(self) -> None:
+        serial_port = self._serial
+        if serial_port is not None and self._owns_serial:
+            self._serial = None
+            try:
+                serial_port.close()
+            except Exception as exc:
+                normalized = normalize_serial_error(exc)
+                if normalized is exc:
+                    raise
+                raise normalized from exc
+
+    def __enter__(self) -> SerialExecutor:
+        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