hostctl 0.1.0__py3-none-any.whl

hostctl/executor/ssh.py

@@ -0,0 +1,226 @@
+"""SSH command executor."""
+
+from __future__ import annotations
+
+import io
+import inspect
+import os
+import subprocess
+import typing
+
+from ._common import (
+    CaptureOutput,
+    CommandArgument,
+    Environment,
+    Executor,
+    ExecutorCommand,
+    ExecutorCapability,
+    FileHandle,
+    Input,
+    dispatch_output,
+    normalize_environment,
+    normalize_input,
+    capture_streams,
+    reject_stdin_conflict,
+)
+
+
+class _SshResult(typing.Protocol):
+    returncode: int
+    stdout: typing.Optional[typing.Union[str, bytes]]
+    stderr: typing.Optional[typing.Union[str, bytes]]
+
+
+class SshConnection(typing.Protocol):
+    def is_closed(self) -> bool: ...
+
+    def close(self) -> None: ...
+
+    def wait_closed(self) -> typing.Awaitable[None]: ...
+
+    def run(self, command: str, **options: object) -> typing.Awaitable[_SshResult]: ...
+
+    def create_process(
+        self, command: typing.Optional[str] = None, **options: object
+    ) -> typing.Awaitable[object]: ...
+
+
+def _input_buffer(
+    stream: FileHandle,
+    *,
+    encoding: typing.Optional[str],
+    errors: typing.Optional[str],
+) -> io.BytesIO:
+    if stream == subprocess.DEVNULL:
+        return io.BytesIO()
+    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):
+        value = value.encode(encoding or "utf-8", errors or "strict")
+    return io.BytesIO(value)
+
+
+class SshExecutor(Executor[subprocess.CompletedProcess]):
+    """Execute finalized command strings through an AsyncSSH connection."""
+
+    executor_capabilities: typing.FrozenSet[ExecutorCapability] = frozenset()
+
+    def __init__(self, connection: typing.Callable[[], SshConnection]) -> None:
+        self._connection = connection
+
+    @staticmethod
+    def _terminate_timeout(connection: SshConnection, error: BaseException) -> bool:
+        """Best-effort termination for a timed-out AsyncSSH process.
+
+        ``SSHClientConnection.run()`` does not expose the process it creates,
+        so AsyncSSH versions and test doubles may expose it on the exception or
+        connection.  Probe those documented/duck-typed hooks and report
+        whether termination was attempted; the timeout remains marked
+        ``orphaned`` when no channel can be recovered.
+        """
+        targets = [
+            getattr(error, "process", None),
+            getattr(error, "channel", None),
+            getattr(connection, "process", None),
+            getattr(connection, "last_process", None),
+        ]
+        target = next((item for item in targets if item is not None), None)
+        if target is None:
+            return False
+
+        from .. import _async
+
+        async def terminate() -> None:
+            for name in ("terminate", "close"):
+                method = getattr(target, name, None)
+                if method is None:
+                    continue
+                result = method()
+                if inspect.isawaitable(result):
+                    await result
+                return
+
+        try:
+            _async.async_to_sync(terminate())
+        except Exception:
+            return False
+        return True
+
+    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,
+        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:
+        if options:
+            raise TypeError(f"unsupported SSH executor option: {sorted(options)[0]}")
+        if args:
+            raise NotImplementedError("SshExecutor does not support native arguments")
+        if bufsize == 0:
+            raise ValueError("bufsize=0 is unsupported by the buffered SSH executor")
+        command = str(command)
+        reject_stdin_conflict(input, stdin)
+        if text and encoding is None:
+            encoding = "utf-8"
+        env = normalize_environment(env)
+
+        from .. import _async
+
+        stdout, stderr = capture_streams(capture_output, stdout, stderr)
+        if input is not None:
+            # The sink is a BytesIO, so this leg is always binary regardless of
+            # the command's text encoding -- `text_mode=False` encodes str and
+            # passes bytes through.
+            value = normalize_input(
+                input, text_mode=False, encoding=encoding, errors=errors
+            )
+            stdin = io.BytesIO(typing.cast(bytes, value))
+        elif stdin is None:
+            # AsyncSSH leaves a command's stdin open when no stream is passed.
+            # Supplying an empty in-memory stream sends EOF and matches
+            # subprocess.run()'s non-interactive default.
+            stdin = _input_buffer(
+                subprocess.DEVNULL,
+                encoding=encoding,
+                errors=errors,
+            )
+        else:
+            stdin = _input_buffer(
+                stdin,
+                encoding=encoding,
+                errors=errors,
+            )
+
+        stdout_target, stderr_target = stdout, stderr
+        try:
+            result = _async.async_to_sync(
+                self._connection().run(
+                    command,
+                    bufsize=bufsize,
+                    stdin=stdin,
+                    stdout=None,
+                    stderr=(
+                        subprocess.STDOUT
+                        if stderr_target == subprocess.STDOUT
+                        else None
+                    ),
+                    env=env,
+                    check=False,
+                    encoding=encoding,
+                    errors=errors,
+                    timeout=timeout,
+                )
+            )
+        except Exception as exc:
+            normalized = _async.normalize_asyncssh_error(
+                exc,
+                command=command,
+                timeout=timeout,
+            )
+            if isinstance(normalized, subprocess.TimeoutExpired):
+                terminated = self._terminate_timeout(self._connection(), exc)
+                normalized.orphaned = not terminated
+            if normalized is exc:
+                raise
+            raise normalized from exc
+
+        result_stdout = result.stdout
+        result_stderr = None if stderr_target == subprocess.STDOUT else result.stderr
+        result_stdout, result_stderr = dispatch_output(
+            stdout_target,
+            stderr_target,
+            result_stdout,
+            result_stderr,
+            encoding=encoding,
+            errors=errors,
+        )
+
+        returncode = result.returncode
+        if returncode is None:
+            returncode = -1
+        completed = subprocess.CompletedProcess(
+            args=command,
+            returncode=returncode,
+            stdout=result_stdout,
+            stderr=result_stderr,
+        )
+        if check:
+            completed.check_returncode()
+        return completed

hostctl/executor/winrm.py

@@ -0,0 +1,255 @@
+"""WinRM PowerShell script executor."""
+
+from __future__ import annotations
+
+import base64
+import dataclasses
+import subprocess
+import typing
+
+from ._common import (
+    CaptureOutput,
+    CommandArgument,
+    Executor,
+    ExecutorCommand,
+    ExecutorCapability,
+    FileHandle,
+    Input,
+    dispatch_output,
+    capture_streams,
+)
+
+
+class _WinRMResponse(typing.Protocol):
+    status_code: int
+    std_out: bytes
+    std_err: bytes
+
+
+class WinRMSession(typing.Protocol):
+    def run_ps(self, script: str) -> _WinRMResponse: ...
+
+
+@dataclasses.dataclass
+class _NativeResponse:
+    status_code: int
+    std_out: bytes
+    std_err: bytes
+
+
+class NativeWinRMSession:
+    """Current-context Windows PowerShell remoting session adapter."""
+
+    def __init__(
+        self,
+        host: str,
+        *,
+        ssl: bool = False,
+        port: typing.Optional[int] = None,
+        timeout: typing.Optional[float] = None,
+        transport: str = "ntlm",
+        server_cert_validation: str = "validate",
+        message_encryption: str = "auto",
+    ) -> None:
+        self.host = host
+        self.ssl = ssl
+        self.port = port
+        self.timeout = timeout
+        if transport not in {"ntlm", "kerberos"}:
+            raise NotImplementedError(
+                "native WinRM supports only current-context Negotiate (ntlm/kerberos)"
+            )
+        if message_encryption not in {"auto", "always", "never"}:
+            raise ValueError("invalid message_encryption")
+        if message_encryption != "auto":
+            raise NotImplementedError(
+                "native WinRM cannot override WS-Man message encryption; "
+                "use message_encryption='auto' or the pywinrm provider"
+            )
+        if server_cert_validation not in {"validate", "ignore"}:
+            raise ValueError("invalid server_cert_validation")
+        if ssl and server_cert_validation == "ignore":
+            # PowerShell remoting can skip certificate checks, but only when
+            # explicitly requested; keep this visible in the generated options.
+            self._skip_ca_check = True
+        else:
+            self._skip_ca_check = False
+
+    def run_ps(self, script: str) -> _NativeResponse:
+        host = base64.b64encode(self.host.encode("utf-8")).decode("ascii")
+        payload = base64.b64encode(script.encode("utf-8")).decode("ascii")
+        wrapper = (
+            "$OutputEncoding=[Console]::OutputEncoding="
+            "[Text.UTF8Encoding]::new($false);"
+            "$ErrorActionPreference='Stop';"
+            "$h=[Text.Encoding]::UTF8.GetString("
+            f"[Convert]::FromBase64String('{host}'));"
+            "$s=[Text.Encoding]::UTF8.GetString("
+            f"[Convert]::FromBase64String('{payload}'));"
+            "$o=@{ComputerName=$h;Authentication='Negotiate';"
+            f"UseSSL=${str(self.ssl).lower()}"
+            + (f";Port={self.port}" if self.port is not None else "")
+            + "};"
+            "try{$global:LASTEXITCODE=0;"
+            "$r=Invoke-Command @o -ScriptBlock ([ScriptBlock]::Create($s));"
+            "$r;exit ([int]$global:LASTEXITCODE)}"
+            "catch{$c=[string]$_.CategoryInfo.Category;"
+            "$m=[Convert]::ToBase64String("
+            "[Text.Encoding]::UTF8.GetBytes($_.Exception.Message));"
+            "[Console]::Error.Write('HOSTCTL_NATIVE_ERROR:'+$c+':'+$m);exit 1}"
+        )
+        if self._skip_ca_check:
+            wrapper = wrapper.replace(
+                ";Port=" + str(self.port) if self.port is not None else ";};",
+                (
+                    ";SkipCACheck=$true;Port=" + str(self.port)
+                    if self.port is not None
+                    else ";SkipCACheck=$true;};"
+                ),
+            )
+        try:
+            result = subprocess.run(
+                (
+                    "powershell.exe",
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-Command",
+                    "-",
+                ),
+                input=wrapper.encode("utf-8"),
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                check=False,
+                timeout=self.timeout,
+            )
+        except subprocess.TimeoutExpired as exc:
+            # Never expose the local powershell argv as the remote command.
+            raise subprocess.TimeoutExpired(self.host, self.timeout) from exc
+        return _NativeResponse(result.returncode, result.stdout, result.stderr)
+
+    def close(self) -> None:
+        return None
+
+
+class WinRMExecutor(Executor[subprocess.CompletedProcess]):
+    """Execute finalized PowerShell scripts through a pywinrm session."""
+
+    executor_capabilities = frozenset((ExecutorCapability.SCRIPT,))
+
+    def __init__(
+        self,
+        session: typing.Callable[[], WinRMSession],
+        transport_timeout: typing.Optional[typing.Callable[[], float]] = None,
+    ) -> None:
+        self._session = session
+        self._transport_timeout = transport_timeout
+
+    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,
+        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:
+        if options:
+            raise TypeError(f"unsupported WinRM executor option: {sorted(options)[0]}")
+        if args:
+            raise NotImplementedError("WinRMExecutor does not support native arguments")
+        command = str(command)
+        if timeout is not None:
+            raise NotImplementedError(
+                "WinRMExecutor timeout is unsupported; configure transport timeouts"
+            )
+        if stdin is not None or input is not None:
+            raise NotImplementedError("WinRMExecutor does not support stdin/input")
+        stdout, stderr = capture_streams(capture_output, stdout, stderr)
+        try:
+            result = self._session().run_ps(command)
+        except Exception as exc:
+            normalized = self._normalize_error(exc, command)
+            if normalized is exc:
+                raise
+            raise normalized from exc
+        out = result.std_out
+        err = result.std_err
+        marker = b"HOSTCTL_NATIVE_ERROR:"
+        if result.status_code and err.startswith(marker):
+            try:
+                _, category, encoded = err.decode("ascii").split(":", 2)
+                detail = base64.b64decode(encoded).decode("utf-8", "replace")
+            except Exception:
+                category, detail = "transport", err.decode("utf-8", "replace")
+            if category in ("AuthenticationError", "PermissionDenied"):
+                raise PermissionError(detail)
+            if category not in ("RemoteError", "Remote"):
+                raise ConnectionError(detail)
+            # Remote errors are represented as a normal non-zero completion;
+            # check=False must be able to inspect them.
+            err = detail.encode(encoding or "utf-8", errors or "replace")
+        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:
+            if out is not None:
+                out += err
+            err = None
+        out, err = dispatch_output(
+            stdout,
+            stderr,
+            out,
+            err,
+            encoding=encoding,
+            errors=errors,
+        )
+
+        completed = subprocess.CompletedProcess(
+            args=command,
+            returncode=result.status_code,
+            stdout=out,
+            stderr=err,
+        )
+        if check:
+            completed.check_returncode()
+        return completed
+
+    def _normalize_error(self, exc: Exception, command: str) -> Exception:
+        try:
+            import requests
+            import winrm.exceptions
+        except ImportError:
+            return exc
+        if isinstance(exc, winrm.exceptions.AuthenticationError):
+            return PermissionError(str(exc))
+        if isinstance(
+            exc,
+            (
+                TimeoutError,
+                subprocess.TimeoutExpired,
+                requests.exceptions.Timeout,
+                winrm.exceptions.WinRMOperationTimeoutError,
+            ),
+        ):
+            timeout = self._transport_timeout() if self._transport_timeout else None
+            return subprocess.TimeoutExpired(command, timeout)
+        if isinstance(
+            exc,
+            (
+                requests.exceptions.ConnectionError,
+                winrm.exceptions.WinRMTransportError,
+                winrm.exceptions.WSManFaultError,
+            ),
+        ):
+            return ConnectionError(str(exc))
+        return exc

hostctl/host/__init__.py

@@ -0,0 +1,93 @@
+"""Host contracts and built-in host implementations."""
+
+from ._common import (
+    Host as Host,
+    HostConfig as HostConfig,
+    HostInfo as HostInfo,
+    HostPath as HostPath,
+    parse_credentials as parse_credentials,
+    redact_uri as redact_uri,
+    strict_uri_credentials as strict_uri_credentials,
+    strict_uri_query as strict_uri_query,
+    uri_host as uri_host,
+)
+from ._ssh import ssh_providers as ssh_providers
+from ._winrm import winrm_providers as winrm_providers
+from ._local import LocalConfig as LocalConfig, LocalHost as LocalHost
+from .container import (
+    ContainerConfig as ContainerConfig,
+    ContainerHost as ContainerHost,
+)
+from .container_path import (
+    ContainerPathBackend as ContainerPathBackend,
+    PosixContainerPath as PosixContainerPath,
+    WindowsContainerPath as WindowsContainerPath,
+)
+from .qemu import (
+    QemuConfig as QemuConfig,
+    QemuHost as QemuHost,
+    PosixQemuPath as PosixQemuPath,
+    QgaPathBackend as QgaPathBackend,
+    WindowsQemuPath as WindowsQemuPath,
+)
+from ._ssh import (
+    PathnameConstructor as PathnameConstructor,
+    SshConfig as SshConfig,
+)
+from ._winrm import (
+    WinRMConfig as WinRMConfig,
+    WinRMPath as WinRMPath,
+    WinRMPathBackend as WinRMPathBackend,
+)
+from .system import (
+    IosConfig as IosConfig,
+    IosHost as IosHost,
+    PosixConfig as PosixConfig,
+    PosixHost as PosixHost,
+    SystemConfig as SystemConfig,
+    SystemHost as SystemHost,
+    WindowsConfig as WindowsConfig,
+    WindowsHost as WindowsHost,
+    register_system_provider as register_system_provider,
+)
+from .serial import SerialConfig as SerialConfig, SerialHost as SerialHost
+from .composite_path import (
+    CompositePosixPath as CompositePosixPath,
+    CompositeWindowsPath as CompositeWindowsPath,
+)
+
+__all__ = [
+    "Host",
+    "HostConfig",
+    "HostInfo",
+    "parse_credentials",
+    "redact_uri",
+    "ssh_providers",
+    "strict_uri_credentials",
+    "strict_uri_query",
+    "uri_host",
+    "winrm_providers",
+    "HostPath",
+    "ContainerConfig",
+    "ContainerHost",
+    "LocalConfig",
+    "LocalHost",
+    "QemuConfig",
+    "QemuHost",
+    "SshConfig",
+    "SerialConfig",
+    "SerialHost",
+    "WinRMConfig",
+    "WinRMPath",
+    "SystemConfig",
+    "SystemHost",
+    "PosixConfig",
+    "PosixHost",
+    "WindowsConfig",
+    "WindowsHost",
+    "register_system_provider",
+    "IosConfig",
+    "IosHost",
+    "CompositePosixPath",
+    "CompositeWindowsPath",
+]