ccproxy-api 0.1.0__py3-none-any.whl

ccproxy/docker/protocol.py

@@ -0,0 +1,192 @@
+"""Protocol definition for Docker operations."""
+
+from collections.abc import Awaitable
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Protocol,
+    TypeAlias,
+    TypeVar,
+    runtime_checkable,
+)
+
+from .models import DockerUserContext
+from .stream_process import OutputMiddleware, ProcessResult, T
+
+
+# Type aliases for Docker operations
+DockerVolume: TypeAlias = tuple[str, str]  # (host_path, container_path)
+DockerEnv: TypeAlias = dict[str, str]  # Environment variables
+DockerPortSpec: TypeAlias = str  # Port specification (e.g., "8080:80", "localhost:8080:80", "127.0.0.1:8080:80/tcp")
+DockerResult: TypeAlias = tuple[
+    int, list[str], list[str]
+]  # (return_code, stdout, stderr)
+
+
+# TODO: add get_version, image_info,
+@runtime_checkable
+class DockerAdapterProtocol(Protocol):
+    """Protocol for Docker operations."""
+
+    def is_available(self) -> Awaitable[bool]:
+        """Check if Docker is available on the system.
+
+        Returns:
+            True if Docker is available, False otherwise
+        """
+        ...
+
+    def run(
+        self,
+        image: str,
+        volumes: list[DockerVolume],
+        environment: DockerEnv,
+        command: list[str] | None = None,
+        middleware: OutputMiddleware[T] | None = None,
+        user_context: DockerUserContext | None = None,
+        entrypoint: str | None = None,
+        ports: list[DockerPortSpec] | None = None,
+    ) -> Awaitable[ProcessResult[T]]:
+        """Run a Docker container with specified configuration.
+
+        Alias for run_container method.
+
+        Args:
+            image: Docker image name/tag to run
+            volumes: List of volume mounts (host_path, container_path)
+            environment: Dictionary of environment variables
+            command: Optional command to run in the container
+            middleware: Optional middleware for processing output
+            user_context: Optional user context for Docker --user flag
+            entrypoint: Optional custom entrypoint to override the image's default
+            ports: Optional port specifications (e.g., ["8080:80", "localhost:9000:9000"])
+
+        Returns:
+            Tuple containing (return_code, stdout_lines, stderr_lines)
+
+        Raises:
+            DockerError: If the container fails to run
+        """
+        ...
+
+    def run_container(
+        self,
+        image: str,
+        volumes: list[DockerVolume],
+        environment: DockerEnv,
+        command: list[str] | None = None,
+        middleware: OutputMiddleware[T] | None = None,
+        user_context: DockerUserContext | None = None,
+        entrypoint: str | None = None,
+        ports: list[DockerPortSpec] | None = None,
+    ) -> Awaitable[ProcessResult[T]]:
+        """Run a Docker container with specified configuration.
+
+        Args:
+            image: Docker image name/tag to run
+            volumes: List of volume mounts (host_path, container_path)
+            environment: Dictionary of environment variables
+            command: Optional command to run in the container
+            middleware: Optional middleware for processing output
+            user_context: Optional user context for Docker --user flag
+            entrypoint: Optional custom entrypoint to override the image's default
+            ports: Optional port specifications (e.g., ["8080:80", "localhost:9000:9000"])
+
+        Returns:
+            Tuple containing (return_code, stdout_lines, stderr_lines)
+
+        Raises:
+            DockerError: If the container fails to run
+        """
+        ...
+
+    def exec_container(
+        self,
+        image: str,
+        volumes: list[DockerVolume],
+        environment: DockerEnv,
+        command: list[str] | None = None,
+        user_context: DockerUserContext | None = None,
+        entrypoint: str | None = None,
+        ports: list[DockerPortSpec] | None = None,
+    ) -> None:
+        """Execute a Docker container by replacing the current process.
+
+        This method builds the Docker command and replaces the current process
+        with the Docker command using os.execvp, effectively handing over control to Docker.
+
+        Args:
+            image: Docker image name/tag to run
+            volumes: List of volume mounts (host_path, container_path)
+            environment: Dictionary of environment variables
+            command: Optional command to run in the container
+            user_context: Optional user context for Docker --user flag
+            entrypoint: Optional custom entrypoint to override the image's default
+            ports: Optional port specifications (e.g., ["8080:80", "localhost:9000:9000"])
+
+        Raises:
+            DockerError: If the container fails to execute
+            OSError: If the command cannot be executed
+        """
+        ...
+
+    def build_image(
+        self,
+        dockerfile_dir: Path,
+        image_name: str,
+        image_tag: str = "latest",
+        no_cache: bool = False,
+        middleware: OutputMiddleware[T] | None = None,
+    ) -> Awaitable[ProcessResult[T]]:
+        """Build a Docker image from a Dockerfile.
+
+        Args:
+            dockerfile_dir: Directory containing the Dockerfile
+            image_name: Name to tag the built image with
+            image_tag: Tag to use for the image
+            no_cache: Whether to use Docker's cache during build
+            middleware: Optional middleware for processing output
+
+        Returns:
+            ProcessResult containing (return_code, stdout_lines, stderr_lines)
+
+        Raises:
+            DockerError: If the image fails to build
+        """
+        ...
+
+    def image_exists(
+        self, image_name: str, image_tag: str = "latest"
+    ) -> Awaitable[bool]:
+        """Check if a Docker image exists locally.
+
+        Args:
+            image_name: Name of the image to check
+            image_tag: Tag of the image to check
+
+        Returns:
+            True if the image exists locally, False otherwise
+        """
+        ...
+
+    def pull_image(
+        self,
+        image_name: str,
+        image_tag: str = "latest",
+        middleware: OutputMiddleware[T] | None = None,
+    ) -> Awaitable[ProcessResult[T]]:
+        """Pull a Docker image from registry.
+
+        Args:
+            image_name: Name of the image to pull
+            image_tag: Tag of the image to pull
+            middleware: Optional middleware for processing output
+
+        Returns:
+            ProcessResult containing (return_code, stdout_lines, stderr_lines)
+
+        Raises:
+            DockerError: If the image fails to pull
+        """
+        ...

ccproxy/docker/stream_process.py

@@ -0,0 +1,264 @@
+"""Process execution and streaming output handling.
+
+This module provides tools for running subprocesses and handling their output streams.
+It supports custom output processing through middleware components, making it suitable
+for real-time output handling in CLI applications.
+
+Example:
+    ```python
+    from ccproxy.docker.stream_process import run_command, DefaultOutputMiddleware
+
+    # Create custom middleware to add timestamps
+    from datetime import datetime
+    class TimestampMiddleware(DefaultOutputMiddleware):
+        async def process(self, line: str, stream_type: str) -> str:
+            timestamp = datetime.now().strftime('%H:%M:%S')
+            return f"[{timestamp}] {await super().process(line, stream_type)}"
+
+    # Run a command with custom output handling
+    return_code, stdout, stderr = await run_command(
+        "ls -la", middleware=TimestampMiddleware()
+    )
+    ```
+"""
+
+import asyncio
+import shlex
+from typing import Any, Generic, TypeAlias, TypeVar, cast
+
+
+T = TypeVar("T")  # Type of processed output
+
+# Type alias for the result of run_command
+ProcessResult: TypeAlias = tuple[int, list[T], list[T]]  # (return_code, stdout, stderr)
+
+
+class OutputMiddleware(Generic[T]):
+    """Base class for processing command output streams.
+
+    OutputMiddleware provides a way to intercept and process output lines
+    from subprocesses. Implementations can format, filter, or transform
+    the output as needed.
+
+    Type parameter T represents the return type of the process method,
+    allowing middleware to transform strings into other types if needed.
+    """
+
+    async def process(self, line: str, stream_type: str) -> T:
+        """Process a line of output from a subprocess stream.
+
+        Args:
+            line: A line of text from the process output
+            stream_type: Either "stdout" or "stderr"
+
+        Returns:
+            Processed output of type T
+
+        Raises:
+            NotImplementedError: Subclasses must implement this method
+        """
+        raise NotImplementedError()
+
+
+class DefaultOutputMiddleware(OutputMiddleware[str]):
+    """Simple middleware that prints output with optional prefixes.
+
+    This middleware prints each line to the console with configurable
+    prefixes for stdout and stderr streams.
+    """
+
+    def __init__(self, stdout_prefix: str = "", stderr_prefix: str = "ERROR: ") -> None:
+        """Initialize middleware with custom prefixes.
+
+        Args:
+            stdout_prefix: Prefix for stdout lines (default: "")
+            stderr_prefix: Prefix for stderr lines (default: "ERROR: ")
+        """
+        self.stdout_prefix = stdout_prefix
+        self.stderr_prefix = stderr_prefix
+
+    async def process(self, line: str, stream_type: str) -> str:
+        """Process and print a line with the appropriate prefix.
+
+        Args:
+            line: Output line to process
+            stream_type: Either "stdout" or "stderr"
+
+        Returns:
+            The original line (unmodified)
+        """
+        prefix = self.stdout_prefix if stream_type == "stdout" else self.stderr_prefix
+        print(f"{prefix}{line}")
+        return line
+
+
+class ChainedOutputMiddleware(OutputMiddleware[T]):
+    """Middleware that chains multiple middleware components together.
+
+    Processes output through a sequence of middleware components, where each
+    middleware processes the output from the previous one. The final output
+    type T is determined by the last middleware in the chain.
+
+    Example:
+        ```python
+        # Chain progress tracking with logging
+        progress_middleware = CompilationProgressMiddleware(callback)
+        logger_middleware = LoggerOutputMiddleware(logger)
+
+        chained = ChainedOutputMiddleware([progress_middleware, logger_middleware])
+
+        # Process: line -> progress_middleware -> logger_middleware -> final result
+        result = docker_adapter.run_container("image", [], {}, middleware=chained)
+        ```
+    """
+
+    def __init__(self, middleware_chain: list[OutputMiddleware[Any]]) -> None:
+        """Initialize chained middleware.
+
+        Args:
+            middleware_chain: List of middleware components to chain together.
+                             Output flows from first to last middleware.
+
+        Raises:
+            ValueError: If middleware_chain is empty
+        """
+        if not middleware_chain:
+            raise ValueError("Middleware chain cannot be empty")
+
+        self.middleware_chain = middleware_chain
+
+    async def process(self, line: str, stream_type: str) -> T:
+        """Process line through the middleware chain.
+
+        Args:
+            line: Output line to process
+            stream_type: Either "stdout" or "stderr"
+
+        Returns:
+            Output from the final middleware in the chain
+        """
+        current_output: Any = line
+
+        # Process through each middleware in sequence
+        for middleware in self.middleware_chain:
+            current_output = await middleware.process(current_output, stream_type)
+
+        return cast(T, current_output)
+
+
+def create_chained_middleware(
+    middleware_chain: list[OutputMiddleware[Any]],
+) -> ChainedOutputMiddleware[Any]:
+    """Factory function to create a chained middleware.
+
+    Args:
+        middleware_chain: List of middleware components to chain together
+
+    Returns:
+        ChainedOutputMiddleware instance
+
+    Raises:
+        ValueError: If middleware_chain is empty
+
+    Example:
+        ```python
+        from ccproxy.docker.stream_process import create_chained_middleware
+        from ccproxy.docker.adapter import LoggerOutputMiddleware
+
+        # Create individual middleware components
+        logger_middleware = LoggerOutputMiddleware(logger)
+
+        # Chain them together
+        chained = create_chained_middleware([logger_middleware])
+
+        # Use with docker adapter
+        result = docker_adapter.run_container("image", [], {}, middleware=chained)
+        ```
+    """
+    return ChainedOutputMiddleware(middleware_chain)
+
+
+async def run_command(
+    cmd: str | list[str],
+    middleware: OutputMiddleware[T] | None = None,
+) -> ProcessResult[T]:
+    """Run a command and process its output through middleware.
+
+    This function executes a command as a subprocess and streams its output
+    through the provided middleware for real-time processing. The processed
+    outputs are collected and returned along with the exit code.
+
+    Args:
+        cmd: Command to run, either as a string or list of arguments
+        middleware: Optional middleware for processing output (uses DefaultOutputMiddleware if None)
+
+    Returns:
+        Tuple containing:
+            - Return code from the process (0 for success)
+            - List of processed stdout lines
+            - List of processed stderr lines
+
+    Example:
+        ```python
+        # Simple command execution
+        rc, stdout, stderr = await run_command("ls -l")
+
+        # With custom middleware
+        class CustomMiddleware(OutputMiddleware[str]):
+            async def process(self, line: str, stream_type: str) -> str:
+                return f"[{stream_type}] {line}"
+
+        rc, stdout, stderr = await run_command("ls -l", CustomMiddleware())
+        ```
+    """
+    if middleware is None:
+        # Cast is needed because T is unbound at this point
+        middleware = cast(OutputMiddleware[T], DefaultOutputMiddleware())
+
+    # Parse string commands into argument lists
+    if isinstance(cmd, str):
+        cmd = shlex.split(cmd)
+
+    # Start the async process with pipes for stdout and stderr
+    process = await asyncio.create_subprocess_exec(
+        *cmd,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+    async def stream_output(stream: asyncio.StreamReader, stream_type: str) -> list[T]:
+        """Process output from a stream and capture results.
+
+        Args:
+            stream: Async stream to read from (stdout or stderr)
+            stream_type: Type of the stream ("stdout" or "stderr")
+
+        Returns:
+            List of processed output lines
+        """
+        captured: list[T] = []
+        while True:
+            line_bytes = await stream.readline()
+            if not line_bytes:
+                break
+            line = line_bytes.decode().rstrip()
+            if line:
+                processed = await middleware.process(line, stream_type)
+                if processed is not None:
+                    captured.append(processed)
+        return captured
+
+    # Create async tasks for concurrent output processing
+    # Ensure stdout and stderr are available
+    if process.stdout is None or process.stderr is None:
+        raise RuntimeError("Process stdout or stderr is None")
+
+    stdout_task = asyncio.create_task(stream_output(process.stdout, "stdout"))
+    stderr_task = asyncio.create_task(stream_output(process.stderr, "stderr"))
+
+    # Wait for process to complete and collect output
+    return_code = await process.wait()
+    stdout_lines = await stdout_task
+    stderr_lines = await stderr_task
+
+    return return_code, stdout_lines, stderr_lines

ccproxy/docker/validators.py

@@ -0,0 +1,173 @@
+"""Docker validation utilities and error creation."""
+
+from typing import Any
+
+from ccproxy.core.errors import DockerError
+
+
+def validate_port_spec(port_spec: str) -> str:
+    """Validate a Docker port specification string.
+
+    Supports formats like:
+    - "8080:80"
+    - "localhost:8080:80"
+    - "127.0.0.1:8080:80"
+    - "8080:80/tcp"
+    - "localhost:8080:80/udp"
+    - "[::1]:8080:80"
+
+    Args:
+        port_spec: Port specification string
+
+    Returns:
+        Validated port specification string
+
+    Raises:
+        DockerError: If port specification is invalid
+    """
+    if not port_spec or not isinstance(port_spec, str):
+        raise create_docker_error(
+            f"Invalid port specification: {port_spec!r}",
+            details={"port_spec": port_spec},
+        )
+
+    # Remove protocol suffix for validation if present
+    port_part = port_spec
+    protocol = None
+    if "/" in port_spec:
+        port_part, protocol = port_spec.rsplit("/", 1)
+        if protocol not in ("tcp", "udp"):
+            raise create_docker_error(
+                f"Invalid protocol in port specification: {protocol}",
+                details={"port_spec": port_spec, "protocol": protocol},
+            )
+
+    # Handle IPv6 address format specially
+    if port_part.startswith("["):
+        # IPv6 format like [::1]:8080:80
+        ipv6_end = port_part.find("]:")
+        if ipv6_end == -1:
+            raise create_docker_error(
+                f"Invalid IPv6 port specification format: {port_spec}",
+                details={
+                    "port_spec": port_spec,
+                    "expected_format": "[ipv6]:host_port:container_port",
+                },
+            )
+
+        host_ip = port_part[: ipv6_end + 1]  # Include the closing ]
+        remaining = port_part[ipv6_end + 2 :]  # Skip ]:
+        port_parts = remaining.split(":")
+
+        if len(port_parts) != 2:
+            raise create_docker_error(
+                f"Invalid IPv6 port specification format: {port_spec}",
+                details={
+                    "port_spec": port_spec,
+                    "expected_format": "[ipv6]:host_port:container_port",
+                },
+            )
+
+        host_port, container_port = port_parts
+        parts = [host_ip, host_port, container_port]
+    else:
+        # Regular format
+        parts = port_part.split(":")
+
+    if len(parts) == 2:
+        # Format: "host_port:container_port"
+        host_port, container_port = parts
+        try:
+            host_port_num = int(host_port)
+            container_port_num = int(container_port)
+            if not (1 <= host_port_num <= 65535) or not (
+                1 <= container_port_num <= 65535
+            ):
+                raise ValueError("Port numbers must be between 1 and 65535")
+        except ValueError as e:
+            raise create_docker_error(
+                f"Invalid port numbers in specification: {port_spec}",
+                details={"port_spec": port_spec, "error": str(e)},
+            ) from e
+
+    elif len(parts) == 3:
+        # Format: "host_ip:host_port:container_port"
+        host_ip, host_port, container_port = parts
+
+        # Basic IP validation (simplified)
+        if not host_ip or host_ip in (
+            "localhost",
+            "127.0.0.1",
+            "0.0.0.0",
+            "::1",
+            "[::1]",
+        ):
+            pass  # Common valid values
+        elif host_ip.startswith("[") and host_ip.endswith("]"):
+            pass  # IPv6 format like [::1]
+        else:
+            # Basic check for IPv4-like format
+            ip_parts = host_ip.split(".")
+            if len(ip_parts) == 4:
+                try:
+                    for part in ip_parts:
+                        num = int(part)
+                        if not (0 <= num <= 255):
+                            raise ValueError("Invalid IPv4 address")
+                except ValueError as e:
+                    raise create_docker_error(
+                        f"Invalid host IP in port specification: {host_ip}",
+                        details={
+                            "port_spec": port_spec,
+                            "host_ip": host_ip,
+                            "error": str(e),
+                        },
+                    ) from e
+
+        try:
+            host_port_num = int(host_port)
+            container_port_num = int(container_port)
+            if not (1 <= host_port_num <= 65535) or not (
+                1 <= container_port_num <= 65535
+            ):
+                raise ValueError("Port numbers must be between 1 and 65535")
+        except ValueError as e:
+            raise create_docker_error(
+                f"Invalid port numbers in specification: {port_spec}",
+                details={"port_spec": port_spec, "error": str(e)},
+            ) from e
+    else:
+        raise create_docker_error(
+            f"Invalid port specification format: {port_spec}",
+            details={
+                "port_spec": port_spec,
+                "expected_format": "host_port:container_port or host_ip:host_port:container_port",
+            },
+        )
+
+    return port_spec
+
+
+def create_docker_error(
+    message: str,
+    command: str | None = None,
+    cause: Exception | None = None,
+    details: dict[str, Any] | None = None,
+) -> DockerError:
+    """Create a DockerError with standardized context.
+
+    Args:
+        message: Human-readable error message
+        command: Docker command that failed (optional)
+        cause: Original exception that caused this error (optional)
+        details: Additional context details (optional)
+
+    Returns:
+        DockerError instance with all context information
+    """
+    return DockerError(
+        message=message,
+        command=command,
+        cause=cause,
+        details=details,
+    )