cloudru-qa-ssh-client 1.0.0__py3-none-any.whl

ssh_client/options.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .event_hooks import (
+    create_request_logger_hook,
+    create_request_structlogger_hook,
+    create_response_logger_hook,
+    create_response_structlogger_hook,
+)
+from .utils.retries import RetryPolicy
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from logging import Logger
+
+    from .client import ClientOption, InitSSHClient
+    from .event_hooks import MaskPattern
+    from .types import OperationDecorator, OutputCallback, StructuredLogger
+
+
+def with_request_timeout(timeout: float) -> ClientOption:
+    """Set the command timeout.
+
+    :param timeout: Maximum command duration in seconds.
+    :return: Client option.
+    """
+
+    def option(client: InitSSHClient) -> None:
+        client.timeout = timeout
+
+    return option
+
+
+def with_connection_timeout(timeout: float) -> ClientOption:
+    """Set the connection timeout.
+
+    :param timeout: Maximum connection duration in seconds.
+    :return: Client option.
+    """
+
+    def option(client: InitSSHClient) -> None:
+        client.connection_timeout = timeout
+
+    return option
+
+
+def with_password(username: str, password: str) -> ClientOption:
+    """Select password authentication.
+
+    :param username: SSH login name.
+    :param password: Login password.
+    :return: Client option.
+    """
+
+    def option(client: InitSSHClient) -> None:
+        client.username = username
+        client.password = password
+        client.private_key_path = None
+
+    return option
+
+
+def with_private_key(username: str, private_key_path: str) -> ClientOption:
+    """Select private-key authentication.
+
+    :param username: SSH login name.
+    :param private_key_path: Path to the private key file.
+    :return: Client option.
+    """
+
+    def option(client: InitSSHClient) -> None:
+        client.username = username
+        client.private_key_path = private_key_path
+        client.password = None
+
+    return option
+
+
+def with_known_hosts(path: str) -> ClientOption:
+    """Trust server keys from an explicit OpenSSH known_hosts file.
+
+    :param path: Path to the trusted server keys.
+    :return: Client option.
+    """
+
+    def option(client: InitSSHClient) -> None:
+        client.known_hosts = path
+
+    return option
+
+
+def with_logger(logger: Logger, mask_patterns: Sequence[MaskPattern] | None = None) -> ClientOption:
+    """Log sanitized SSH requests and command results.
+
+    :param logger: Standard logger.
+    :param mask_patterns: Literal secrets or regular expressions to mask.
+    :return: Client option.
+    """
+
+    def option(client: InitSSHClient) -> None:
+        client.add_request_hook(create_request_logger_hook(logger, mask_patterns))
+        client.add_response_hook(create_response_logger_hook(logger, mask_patterns))
+
+    return option
+
+
+def with_structlogger(logger: StructuredLogger, mask_patterns: Sequence[MaskPattern] | None = None) -> ClientOption:
+    """Log sanitized structured SSH requests and command results.
+
+    :param logger: Structured logger.
+    :param mask_patterns: Literal secrets or regular expressions to mask.
+    :return: Client option.
+    """
+
+    def option(client: InitSSHClient) -> None:
+        client.add_request_hook(create_request_structlogger_hook(logger, mask_patterns))
+        client.add_response_hook(create_response_structlogger_hook(logger, mask_patterns))
+
+    return option
+
+
+def retry_if_connection_fails(
+    retries_attempts_number: int,
+    retries_interval_in_seconds: float,
+    *,
+    reraise_exception: bool = False,
+) -> ClientOption:
+    """Retry failed connections with a bounded delay.
+
+    :param retries_attempts_number: Maximum attempts.
+    :param retries_interval_in_seconds: Delay between attempts.
+    :param reraise_exception: Propagate the final connection error.
+    :return: Client option.
+    """
+    policy = RetryPolicy(retries_attempts_number, retries_interval_in_seconds, reraise=reraise_exception)
+
+    def option(client: InitSSHClient) -> None:
+        client.connection_retry = policy
+
+    return option
+
+
+def retry_if_command_fails(
+    retries_attempts_number: int,
+    retries_interval_in_seconds: float,
+    *,
+    reraise_exception: bool = False,
+) -> ClientOption:
+    """Retry raised command errors and nonzero exit codes.
+
+    :param retries_attempts_number: Maximum attempts.
+    :param retries_interval_in_seconds: Delay between attempts.
+    :param reraise_exception: Propagate the final command failure.
+    :return: Client option.
+    """
+    policy = RetryPolicy(retries_attempts_number, retries_interval_in_seconds, reraise=reraise_exception)
+
+    def option(client: InitSSHClient) -> None:
+        client.command_retry = policy
+
+    return option
+
+
+def with_connect_decorators(*decorators: OperationDecorator) -> ClientOption:
+    """Register custom connection wrappers in application order.
+
+    :param decorators: Wrappers preserving the operation's result type.
+    :return: Client option.
+    """
+
+    def option(client: InitSSHClient) -> None:
+        for decorator in decorators:
+            client.add_connect_decorator(decorator)
+
+    return option
+
+
+def with_execute_decorators(*decorators: OperationDecorator) -> ClientOption:
+    """Register custom command wrappers in application order.
+
+    :param decorators: Wrappers preserving the operation's result type.
+    :return: Client option.
+    """
+
+    def option(client: InitSSHClient) -> None:
+        for decorator in decorators:
+            client.add_execute_decorator(decorator)
+
+    return option
+
+
+def with_live_execute_callback(
+    stdout_callback: OutputCallback | None = None,
+    stderr_callback: OutputCallback | None = None,
+) -> ClientOption:
+    """Register default streaming output callbacks.
+
+    :param stdout_callback: Observer of stdout lines.
+    :param stderr_callback: Observer of stderr lines for asynchronous clients.
+    :return: Client option.
+    """
+
+    def option(client: InitSSHClient) -> None:
+        client.live_stdout_callback = stdout_callback
+        client.live_stderr_callback = stderr_callback
+
+    return option

ssh_client/results.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SSHResult:
+    """SSH command result."""
+
+    stdout: str = ""
+    stderr: str = ""
+    exit_code: int | None = None
+
+    def __repr__(self) -> str:
+        """Return a concise description of the command result."""
+        return f"SSHResult(stdout='{self.stdout}', stderr='{self.stderr}', exit_code={self.exit_code})"
+
+
+@dataclass
+class LiveSSHResult:
+    """SSH command result with real-time data access."""
+
+    stdout_lines: list[str] = field(default_factory=list)
+    stderr_lines: list[str] = field(default_factory=list)
+    exit_code: int | None = None
+
+    def __repr__(self) -> str:
+        """Return a concise description of the command result."""
+        return (
+            f"LiveSSHResult(stdout_lines={len(self.stdout_lines)}, "
+            f"stderr_lines={len(self.stderr_lines)}, exit_code={self.exit_code})"
+        )

ssh_client/types.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Protocol, TypedDict
+
+if TYPE_CHECKING:
+    from .results import LiveSSHResult, SSHResult
+
+type OutputCallback = Callable[[str], None]
+type InterruptCallback = Callable[[str], bool]
+type SyncOperation[T] = Callable[[], T]
+type AsyncOperation[T] = Callable[[], Awaitable[T]]
+
+
+class OperationDecorator(Protocol):
+    """Wrap an operation while preserving its parameters and result."""
+
+    def __call__[T](self, operation: Callable[[], T]) -> Callable[[], T]:
+        """Return a wrapped operation.
+
+        :param operation: Deferred connection or command operation.
+        :return: Operation with the same result type.
+        """
+        ...
+
+
+class RequestHook(Protocol):
+    """Observe an SSH request."""
+
+    def __call__(self, *, host: str, port: int, username: str | None, command: str) -> None:
+        """Handle request values."""
+        ...
+
+
+class ResponseHook(Protocol):
+    """Observe an SSH command result."""
+
+    def __call__(self, *, host: str, command: str, result: SSHResult | LiveSSHResult) -> None:
+        """Handle completed command output."""
+        ...
+
+
+class StructuredLogger(Protocol):
+    """Accept structured SSH log entries."""
+
+    def info(self, event: str, **values: object) -> object:
+        """Write a structured informational event."""
+        ...
+
+
+class Closeable(Protocol):
+    """Close a synchronous transport."""
+
+    def close(self) -> None:
+        """Release the transport."""
+        ...
+
+
+class AsyncCloseable(Closeable, Protocol):
+    """Wait for transport shutdown."""
+
+    async def wait_closed(self) -> None:
+        """Wait until transport resources are released."""
+        ...
+
+
+class ExecuteOptions(TypedDict, total=False):
+    """Keyword settings for a command."""
+
+    timeout: float | None
+    raise_for_status: bool
+
+
+class LiveExecuteOptions(ExecuteOptions, total=False):
+    """Keyword settings for a streaming command."""
+
+    stdout_callback: OutputCallback | None
+    stderr_callback: OutputCallback | None
+    interrupt_stdout_callback: InterruptCallback | None
+    interrupt_stderr_callback: InterruptCallback | None

ssh_client/utils/__init__.py

@@ -0,0 +1,9 @@
+from .masking import mask_request_data, mask_response_data
+from .retries import retry_if_command_fails, retry_if_connection_fails
+
+__all__ = [
+    "mask_request_data",
+    "mask_response_data",
+    "retry_if_command_fails",
+    "retry_if_connection_fails",
+]

ssh_client/utils/masking.py

@@ -0,0 +1,42 @@
+import re
+from collections.abc import Sequence
+
+
+def mask_request_data(command: str, mask_patterns: Sequence[str | re.Pattern[str]]) -> str:
+    """Mask sensitive data in SSH request command.
+
+    :param command: Command to mask
+    :param mask_patterns: Patterns to use for masking sensitive data
+    :returns: Masked command
+    """
+    masked_command = command
+    for pattern in mask_patterns:
+        if isinstance(pattern, str):
+            masked_command = masked_command.replace(pattern, "****")
+        else:
+            masked_command = pattern.sub("****", masked_command)
+    return masked_command
+
+
+def mask_response_data(
+    stdout: str,
+    stderr: str,
+    mask_patterns: Sequence[str | re.Pattern[str]],
+) -> tuple[str, str]:
+    """Mask sensitive data in SSH response stdout and stderr.
+
+    :param stdout: Standard output to mask
+    :param stderr: Standard error to mask
+    :param mask_patterns: Patterns to use for masking sensitive data
+    :returns: Tuple of masked stdout and stderr
+    """
+    masked_stdout = stdout
+    masked_stderr = stderr
+    for pattern in mask_patterns:
+        if isinstance(pattern, str):
+            masked_stdout = masked_stdout.replace(pattern, "****")
+            masked_stderr = masked_stderr.replace(pattern, "****")
+        else:
+            masked_stdout = pattern.sub("****", masked_stdout)
+            masked_stderr = pattern.sub("****", masked_stderr)
+    return masked_stdout, masked_stderr

ssh_client/utils/retries.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import asyncssh
+import paramiko
+
+from ssh_client.clients.exceptions import CommandNonZeroExitCodeError
+from ssh_client.results import SSHResult
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+    from logging import Logger
+
+CONNECTION_ERRORS = (OSError, paramiko.SSHException, asyncssh.Error)
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Apply bounded retries to connection and command operations."""
+
+    attempts: int = 3
+    interval: float = 5
+    reraise: bool = False
+
+    def __post_init__(self) -> None:
+        """Reject settings that cannot execute a bounded retry."""
+        if self.attempts < 1 or self.interval < 0:
+            message = "Retry attempts must be positive and interval must be nonnegative"
+            raise ValueError(message)
+
+    def connect(self, operation: Callable[[], None]) -> None:
+        """Retry a synchronous connection operation.
+
+        :param operation: Connection attempt.
+        """
+        for attempt in range(self.attempts):
+            try:
+                operation()
+            except CONNECTION_ERRORS:
+                if attempt + 1 == self.attempts:
+                    if self.reraise:
+                        raise
+                    return
+                time.sleep(self.interval)
+            else:
+                return
+
+    async def connect_async(self, operation: Callable[[], Awaitable[None]]) -> None:
+        """Retry an asynchronous connection operation without blocking the event loop.
+
+        :param operation: Connection attempt.
+        """
+        for attempt in range(self.attempts):
+            try:
+                await operation()
+            except CONNECTION_ERRORS:
+                if attempt + 1 == self.attempts:
+                    if self.reraise:
+                        raise
+                    return
+                await asyncio.sleep(self.interval)
+            else:
+                return
+
+    def execute(self, operation: Callable[[], SSHResult]) -> SSHResult:
+        """Retry raised command errors and nonzero exit codes.
+
+        :param operation: Command attempt.
+        :return: Successful or final failed command result.
+        """
+        result = SSHResult("", "Command execution failed after retries", -1)
+        for attempt in range(self.attempts):
+            try:
+                result = operation()
+            except (*CONNECTION_ERRORS, CommandNonZeroExitCodeError):
+                if attempt + 1 == self.attempts and self.reraise:
+                    raise
+            else:
+                if result.exit_code == 0:
+                    return result
+            if attempt + 1 < self.attempts:
+                time.sleep(self.interval)
+        return self._final_result(result)
+
+    async def execute_async(self, operation: Callable[[], Awaitable[SSHResult]]) -> SSHResult:
+        """Retry asynchronous commands without blocking the event loop.
+
+        :param operation: Command attempt.
+        :return: Successful or final failed command result.
+        """
+        result = SSHResult("", "Command execution failed after retries", -1)
+        for attempt in range(self.attempts):
+            try:
+                result = await operation()
+            except (*CONNECTION_ERRORS, CommandNonZeroExitCodeError):
+                if attempt + 1 == self.attempts and self.reraise:
+                    raise
+            else:
+                if result.exit_code == 0:
+                    return result
+            if attempt + 1 < self.attempts:
+                await asyncio.sleep(self.interval)
+        return self._final_result(result)
+
+    def _final_result(self, result: SSHResult) -> SSHResult:
+        if self.reraise:
+            raise CommandNonZeroExitCodeError.from_result(result)
+        return result
+
+
+def prepare_retry_error_context(error: Exception) -> tuple[str, str]:
+    """Return the exception name and message.
+
+    :param error: Failed operation exception.
+    :return: Exception name and description.
+    """
+    return type(error).__name__, str(error)
+
+
+def retry_if_connection_fails(
+    retries_attempts_number: int = 3,
+    retries_interval_in_seconds: float = 5,
+    *,
+    reraise_exception: bool = False,
+    logger: Logger | None = None,
+) -> Callable[[Callable[[], None]], Callable[[], None]]:
+    """Create a synchronous connection retry decorator.
+
+    :param retries_attempts_number: Maximum attempts.
+    :param retries_interval_in_seconds: Delay between attempts.
+    :param reraise_exception: Propagate the final connection error.
+    :param logger: Optional logger receiving completion records.
+    :return: Connection decorator.
+    """
+    policy = RetryPolicy(retries_attempts_number, retries_interval_in_seconds, reraise=reraise_exception)
+
+    def decorate(operation: Callable[[], None]) -> Callable[[], None]:
+        def execute() -> None:
+            policy.connect(operation)
+            if logger is not None:
+                logger.debug("SSH connection retry operation completed")
+
+        return execute
+
+    return decorate
+
+
+def retry_if_command_fails(
+    retries_attempts_number: int = 3,
+    retries_interval_in_seconds: float = 5,
+    *,
+    reraise_exception: bool = False,
+    logger: Logger | None = None,
+) -> Callable[[Callable[[], SSHResult]], Callable[[], SSHResult]]:
+    """Create a synchronous command retry decorator.
+
+    :param retries_attempts_number: Maximum attempts.
+    :param retries_interval_in_seconds: Delay between attempts.
+    :param reraise_exception: Propagate final command failure.
+    :param logger: Optional logger receiving completion records.
+    :return: Command decorator.
+    """
+    policy = RetryPolicy(retries_attempts_number, retries_interval_in_seconds, reraise=reraise_exception)
+
+    def decorate(operation: Callable[[], SSHResult]) -> Callable[[], SSHResult]:
+        def execute() -> SSHResult:
+            result = policy.execute(operation)
+            if logger is not None:
+                logger.debug("SSH command retry operation completed with exit code %s", result.exit_code)
+            return result
+
+        return execute
+
+    return decorate