ccproxy-api 0.1.0__py3-none-any.whl

ccproxy/docker/docker_path.py

@@ -0,0 +1,207 @@
+"""Docker path management with clean API."""
+
+from pathlib import Path
+from typing import Self
+
+from pydantic import BaseModel, field_validator
+from structlog import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class DockerPath(BaseModel):
+    """Represents a mapping between host and container paths.
+
+    Provides a clean API for Docker volume mounting and path resolution.
+
+    Example:
+        workspace = DockerPath(host_path="/some/host/local/path", container_path="/tmp/docker/workspace")
+        docker_vol = workspace.vol()  # Returns volume mapping tuple
+        container_path = workspace.container()  # Returns container path
+        host_path = workspace.host()  # Returns host path
+    """
+
+    host_path: Path | None = None
+    container_path: str
+    env_definition_variable_name: str | None = None
+
+    @field_validator("host_path", mode="before")
+    @classmethod
+    def _resolve_host_path(cls, v: str | Path | None) -> Path | None:
+        """Resolve host path to an absolute path."""
+        if v is None:
+            return None
+        return Path(v).resolve()
+
+    def vol(self) -> tuple[str, str]:
+        """Get Docker volume mapping tuple.
+
+        Returns:
+            tuple[str, str]: (host_path, container_path) for Docker -v flag
+        """
+        if self.host_path is None:
+            raise ValueError("host_path is not set, cannot create volume mapping")
+        return (str(self.host_path), self.container_path)
+
+    def host(self) -> Path:
+        """Get host path as Path object.
+
+        Returns:
+            Path: Resolved host path
+        """
+        if self.host_path is None:
+            raise ValueError("host_path is not set")
+        return self.host_path
+
+    def container(self) -> str:
+        """Get container path as string.
+
+        Returns:
+            str: Container path
+        """
+        return self.container_path
+
+    def join(self, *subpaths: str) -> "DockerPath":
+        """Create new DockerPath with subpaths joined to both host and container paths.
+
+        Args:
+            *subpaths: Path components to join
+
+        Returns:
+            DockerPath: New instance with joined paths
+        """
+        host_joined = self.host_path
+        if host_joined:
+            for subpath in subpaths:
+                host_joined = host_joined / subpath
+
+        container_joined = self.container_path
+        for subpath in subpaths:
+            container_joined = f"{container_joined}/{subpath}".replace("//", "/")
+
+        return DockerPath(host_path=host_joined, container_path=container_joined)
+
+    def get_env_definition(self) -> str:
+        return f"{self.env_definition_variable_name}={self.container_path} # {self.host_path}"
+
+    def __str__(self) -> str:
+        """String representation showing the mapping."""
+        if self.host_path:
+            return f"DockerPath({self.host_path} -> {self.container_path})"
+        return f"DockerPath(container_path={self.container_path})"
+
+    def __repr__(self) -> str:
+        """Detailed representation."""
+        return f"DockerPath(host_path={self.host_path!r}, container_path={self.container_path!r})"
+
+
+class DockerPathSet:
+    """Collection of named Docker paths for organized path management.
+
+    Example:
+        paths = DockerPathSet("/tmp/build")
+        paths.add("workspace", "/workspace")
+        paths.add("config", "/workspace/config")
+
+        workspace_vol = paths.get("workspace").vol()
+        config_path = paths.get("config").container()
+    """
+
+    def __init__(self, base_host_path: str | Path | None = None) -> None:
+        """Initialize Docker path set.
+
+        Args:
+            base_host_path: Base path on host for all paths in this set
+        """
+        self.base_host_path = Path(base_host_path).resolve() if base_host_path else None
+        self.paths: dict[str, DockerPath] = {}
+        self.logger = get_logger(f"{__name__}.{self.__class__.__name__}")
+
+    def add(
+        self, name: str, container_path: str, host_subpath: str | None = None
+    ) -> Self:
+        """Add a named Docker path to the set.
+
+        Args:
+            name: Logical name for the path
+            container_path: Path inside the Docker container
+            host_subpath: Optional subpath from base_host_path, defaults to name
+
+        Returns:
+            Self: For method chaining
+        """
+        if self.base_host_path is None:
+            raise ValueError("base_host_path must be set to use add() method")
+
+        if host_subpath is None:
+            host_subpath = name
+
+        # Handle empty string to mean no subpath (use base path directly)
+        if host_subpath == "":
+            host_path = self.base_host_path
+        else:
+            host_path = self.base_host_path / host_subpath
+
+        self.paths[name] = DockerPath(
+            host_path=host_path, container_path=container_path
+        )
+        return self
+
+    def add_path(self, name: str, docker_path: DockerPath) -> Self:
+        """Add a pre-created DockerPath to the set.
+
+        Args:
+            name: Logical name for the path
+            docker_path: DockerPath instance to add
+
+        Returns:
+            Self: For method chaining
+        """
+        self.paths[name] = docker_path
+        return self
+
+    def get(self, name: str) -> DockerPath:
+        """Get Docker path by name.
+
+        Args:
+            name: Logical name of the path
+
+        Returns:
+            DockerPath: The Docker path instance
+
+        Raises:
+            KeyError: If path name is not found
+        """
+        if name not in self.paths:
+            raise KeyError(
+                f"Docker path '{name}' not found. Available: {list(self.paths.keys())}"
+            )
+        return self.paths[name]
+
+    def has(self, name: str) -> bool:
+        """Check if a path name exists in the set.
+
+        Args:
+            name: Logical name to check
+
+        Returns:
+            bool: True if path exists
+        """
+        return name in self.paths
+
+    def volumes(self) -> list[tuple[str, str]]:
+        """Get all volume mappings for Docker.
+
+        Returns:
+            list[tuple[str, str]]: List of (host_path, container_path) tuples
+        """
+        return [path.vol() for path in self.paths.values()]
+
+    def names(self) -> list[str]:
+        """Get all path names in the set.
+
+        Returns:
+            list[str]: List of logical path names
+        """
+        return list(self.paths.keys())

ccproxy/docker/middleware.py

@@ -0,0 +1,103 @@
+"""Docker output middleware for processing and logging container output."""
+
+from typing import Any
+
+from structlog import get_logger
+
+from .stream_process import OutputMiddleware, create_chained_middleware
+
+
+logger = get_logger(__name__)
+
+
+class LoggerOutputMiddleware(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, logger: Any, stdout_prefix: str = "", stderr_prefix: str = ""):
+        """Initialize middleware with custom prefixes.
+
+        Args:
+            stdout_prefix: Prefix for stdout lines (default: "")
+            stderr_prefix: Prefix for stderr lines (default: "")
+        """
+        self.logger = logger
+        self.stderr_prefix = stderr_prefix
+        self.stdout_prefix = stdout_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)
+        """
+        if stream_type == "stdout":
+            self.logger.info(
+                "docker_stdout", prefix=self.stdout_prefix, line=line, stream="stdout"
+            )
+        else:
+            self.logger.info(
+                "docker_stderr", prefix=self.stderr_prefix, line=line, stream="stderr"
+            )
+        return line
+
+
+def create_logger_middleware(
+    logger_instance: Any | None = None,
+    stdout_prefix: str = "",
+    stderr_prefix: str = "",
+) -> LoggerOutputMiddleware:
+    """Factory function to create a LoggerOutputMiddleware instance.
+
+    Args:
+        logger_instance: Logger instance to use (defaults to module logger)
+        stdout_prefix: Prefix for stdout lines
+        stderr_prefix: Prefix for stderr lines
+
+    Returns:
+        Configured LoggerOutputMiddleware instance
+    """
+    if logger_instance is None:
+        logger_instance = logger
+    return LoggerOutputMiddleware(logger_instance, stdout_prefix, stderr_prefix)
+
+
+def create_chained_docker_middleware(
+    middleware_chain: list[OutputMiddleware[Any]],
+    include_logger: bool = True,
+    logger_instance: Any | None = None,
+    stdout_prefix: str = "",
+    stderr_prefix: str = "",
+) -> OutputMiddleware[Any]:
+    """Factory function to create chained middleware for Docker operations.
+
+    Args:
+        middleware_chain: List of middleware components to chain together
+        include_logger: Whether to automatically add logger middleware at the end
+        logger_instance: Logger instance to use (defaults to module logger)
+        stdout_prefix: Prefix for stdout lines in logger middleware
+        stderr_prefix: Prefix for stderr lines in logger middleware
+
+    Returns:
+        Chained middleware instance
+
+    """
+    final_chain = list(middleware_chain)
+
+    if include_logger:
+        logger_middleware = create_logger_middleware(
+            logger_instance, stdout_prefix, stderr_prefix
+        )
+        final_chain.append(logger_middleware)
+
+    if len(final_chain) == 1:
+        return final_chain[0]
+
+    return create_chained_middleware(final_chain)

ccproxy/docker/models.py

@@ -0,0 +1,228 @@
+"""Docker-specific models for cross-domain operations."""
+
+import os
+import platform
+from pathlib import Path
+from typing import ClassVar, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from .docker_path import DockerPath
+
+
+class DockerUserContext(BaseModel):
+    """Docker user context for volume permission handling.
+
+    Represents user information needed for Docker --user flag to
+    solve volume permission issues when mounting host directories.
+    """
+
+    uid: int = Field(..., description="User ID for Docker --user flag")
+    gid: int = Field(..., description="Group ID for Docker --user flag")
+    username: str = Field(..., description="Username for reference")
+    enable_user_mapping: bool = Field(
+        default=True, description="Whether to enable --user flag in Docker commands"
+    )
+
+    # Path settings using DockerPath
+    home_path: DockerPath | None = Field(
+        default=None, description="Home directory mapping between host and container"
+    )
+    workspace_path: DockerPath | None = Field(
+        default=None,
+        description="Workspace directory mapping between host and container",
+    )
+
+    # Platform compatibility
+    _supported_platforms: ClassVar[set[str]] = {"Linux", "Darwin"}
+
+    @field_validator("uid", "gid")
+    @classmethod
+    def validate_positive_ids(cls, v: int) -> int:
+        """Validate that UID/GID are positive integers."""
+        if v < 0:
+            raise ValueError("UID and GID must be non-negative")
+        return v
+
+    @field_validator("username")
+    @classmethod
+    def validate_username(cls, v: str) -> str:
+        """Validate username is not empty."""
+        if not v or not v.strip():
+            raise ValueError("Username cannot be empty")
+        return v.strip()
+
+    @classmethod
+    def detect_current_user(
+        cls,
+        home_path: DockerPath | None = None,
+        workspace_path: DockerPath | None = None,
+    ) -> "DockerUserContext":
+        """Detect current user context from system.
+
+        Args:
+            home_path: Optional home directory DockerPath override
+            workspace_path: Optional workspace directory DockerPath override
+
+        Returns:
+            DockerUserContext: Current user's context
+
+        Raises:
+            RuntimeError: If user detection fails or platform unsupported
+        """
+        current_platform = platform.system()
+
+        if current_platform not in cls._supported_platforms:
+            raise RuntimeError(
+                f"User detection not supported on {current_platform}. "
+                f"Supported platforms: {', '.join(cls._supported_platforms)}"
+            )
+
+        try:
+            uid = os.getuid()
+            gid = os.getgid()
+            username = os.getenv("USER") or os.getenv("USERNAME") or "unknown"
+
+            # Create default home path if not provided
+            if home_path is None:
+                host_home_env = os.getenv("HOME")
+                if host_home_env:
+                    home_path = DockerPath(
+                        host_path=Path(host_home_env), container_path="/data/home"
+                    )
+
+            return cls(
+                uid=uid,
+                gid=gid,
+                username=username,
+                enable_user_mapping=True,
+                home_path=home_path,
+                workspace_path=workspace_path,
+            )
+
+        except AttributeError as e:
+            raise RuntimeError(
+                f"Failed to detect user on {current_platform}: {e}"
+            ) from e
+        except Exception as e:
+            raise RuntimeError(f"Unexpected error detecting user: {e}") from e
+
+    @classmethod
+    def create_manual(
+        cls,
+        uid: int,
+        gid: int,
+        username: str,
+        home_path: DockerPath | None = None,
+        workspace_path: DockerPath | None = None,
+        enable_user_mapping: bool = True,
+    ) -> "DockerUserContext":
+        """Create manual user context with custom values.
+
+        Args:
+            uid: User ID for Docker --user flag
+            gid: Group ID for Docker --user flag
+            username: Username for reference
+            home_path: Optional home directory DockerPath
+            workspace_path: Optional workspace directory DockerPath
+            enable_user_mapping: Whether to enable --user flag in Docker commands
+
+        Returns:
+            DockerUserContext: Manual user context
+
+        Raises:
+            ValueError: If validation fails for any parameter
+        """
+        return cls(
+            uid=uid,
+            gid=gid,
+            username=username,
+            enable_user_mapping=enable_user_mapping,
+            home_path=home_path,
+            workspace_path=workspace_path,
+        )
+
+    def get_docker_user_flag(self) -> str:
+        """Get Docker --user flag value.
+
+        Returns:
+            str: Docker user flag in format "uid:gid"
+        """
+        return f"{self.uid}:{self.gid}"
+
+    def is_supported_platform(self) -> bool:
+        """Check if current platform supports user mapping.
+
+        Returns:
+            bool: True if platform supports user mapping
+        """
+        return platform.system() in self._supported_platforms
+
+    def should_use_user_mapping(self) -> bool:
+        """Check if user mapping should be used.
+
+        Returns:
+            bool: True if user mapping is enabled and platform is supported
+        """
+        return self.enable_user_mapping and self.is_supported_platform()
+
+    def get_environment_variables(self) -> dict[str, str]:
+        """Get environment variables for home and workspace directory configuration.
+
+        Returns:
+            dict[str, str]: Environment variables to set in container
+        """
+        env = {}
+        if self.home_path:
+            env["HOME"] = self.home_path.container()
+            env["CLAUDE_HOME"] = self.home_path.container()
+        if self.workspace_path:
+            env["CLAUDE_WORKSPACE"] = self.workspace_path.container()
+        return env
+
+    def get_volumes(self) -> list[tuple[str, str]]:
+        """Get Docker volume mappings for home and workspace directories.
+
+        Returns:
+            list[tuple[str, str]]: List of (host_path, container_path) tuples
+        """
+        volumes = []
+        if self.home_path and self.home_path.host_path:
+            volumes.append(self.home_path.vol())
+        if self.workspace_path and self.workspace_path.host_path:
+            volumes.append(self.workspace_path.vol())
+        return volumes
+
+    def get_home_volumes(self) -> list[tuple[str, str]]:
+        """Get Docker volume mappings for home directory only (for backwards compatibility).
+
+        Returns:
+            list[tuple[str, str]]: List of (host_path, container_path) tuples
+        """
+        volumes = []
+        if self.home_path and self.home_path.host_path:
+            volumes.append(self.home_path.vol())
+        return volumes
+
+    def describe_context(self) -> str:
+        """Get human-readable description of user context.
+
+        Returns:
+            str: Description of user context for debugging
+        """
+        parts = [
+            f"uid={self.uid}",
+            f"gid={self.gid}",
+            f"username={self.username}",
+        ]
+
+        if self.home_path:
+            parts.append(f"home_path={self.home_path}")
+
+        if self.workspace_path:
+            parts.append(f"workspace_path={self.workspace_path}")
+
+        return f"DockerUserContext({', '.join(parts)})"
+
+
+__all__ = ["DockerUserContext"]