ccproxy-api 0.1.0__py3-none-any.whl

ccproxy/config/docker_settings.py

@@ -0,0 +1,265 @@
+"""Docker settings configuration for CCProxy API."""
+
+import os
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from ccproxy import __version__
+from ccproxy.core.async_utils import format_version, get_claude_docker_home_dir
+
+
+# Docker validation functions moved here to avoid utils dependency
+
+
+def validate_host_path(path: str) -> str:
+    """Validate host path for Docker volume mounting."""
+    import os
+    from pathlib import Path
+
+    if not path:
+        raise ValueError("Path cannot be empty")
+
+    # Expand environment variables and user home directory
+    expanded_path = os.path.expandvars(str(Path(path).expanduser()))
+
+    # Convert to absolute path and normalize
+    abs_path = Path(expanded_path).resolve()
+    return str(abs_path)
+
+
+def validate_volumes_list(volumes: list[str]) -> list[str]:
+    """Validate Docker volumes list format."""
+    validated = []
+
+    for volume in volumes:
+        if not volume:
+            continue
+
+        # Use validate_volume_format for comprehensive validation
+        validated_volume = validate_volume_format(volume)
+        validated.append(validated_volume)
+
+    return validated
+
+
+def validate_volume_format(volume: str) -> str:
+    """Validate individual Docker volume format.
+
+    Args:
+        volume: Volume mount string in format 'host:container[:options]'
+
+    Returns:
+        Validated volume string with normalized host path
+
+    Raises:
+        ValueError: If volume format is invalid or host path doesn't exist
+    """
+    import os
+    from pathlib import Path
+
+    if not volume:
+        raise ValueError("Volume cannot be empty")
+
+    # Expected format: "host_path:container_path" or "host_path:container_path:options"
+    parts = volume.split(":")
+    if len(parts) < 2:
+        raise ValueError(
+            f"Invalid volume format: {volume}. Expected 'host:container' or 'host:container:options'"
+        )
+
+    host_path = parts[0]
+    container_path = parts[1]
+    options = ":".join(parts[2:]) if len(parts) > 2 else ""
+
+    if not host_path or not container_path:
+        raise ValueError(
+            f"Invalid volume format: {volume}. Expected 'host:container' or 'host:container:options'"
+        )
+
+    # Expand environment variables and user home directory
+    expanded_host_path = os.path.expandvars(str(Path(host_path).expanduser()))
+
+    # Convert to absolute path
+    abs_host_path = Path(expanded_host_path).resolve()
+
+    # Check if the path exists
+    if not abs_host_path.exists():
+        raise ValueError(f"Host path does not exist: {expanded_host_path}")
+
+    # Validate container path (should be absolute)
+    if not container_path.startswith("/"):
+        raise ValueError(f"Container path must be absolute: {container_path}")
+
+    # Reconstruct the volume string with normalized host path
+    result = f"{abs_host_path}:{container_path}"
+    if options:
+        result += f":{options}"
+
+    return result
+
+
+def validate_environment_variable(env_var: str) -> tuple[str, str]:
+    """Validate environment variable format.
+
+    Args:
+        env_var: Environment variable string in format 'KEY=VALUE'
+
+    Returns:
+        Tuple of (key, value)
+
+    Raises:
+        ValueError: If environment variable format is invalid
+    """
+    if not env_var:
+        raise ValueError("Environment variable cannot be empty")
+
+    if "=" not in env_var:
+        raise ValueError(
+            f"Invalid environment variable format: {env_var}. Expected KEY=VALUE format"
+        )
+
+    # Split on first equals sign only (value may contain equals)
+    key, value = env_var.split("=", 1)
+
+    if not key:
+        raise ValueError(
+            f"Invalid environment variable format: {env_var}. Expected KEY=VALUE format"
+        )
+
+    return key, value
+
+
+def validate_docker_volumes(volumes: list[str]) -> list[str]:
+    """Validate Docker volumes list format.
+
+    Args:
+        volumes: List of volume mount strings
+
+    Returns:
+        List of validated volume strings with normalized host paths
+
+    Raises:
+        ValueError: If any volume format is invalid
+    """
+    validated = []
+
+    for volume in volumes:
+        if not volume:
+            continue
+
+        validated_volume = validate_volume_format(volume)
+        validated.append(validated_volume)
+
+    return validated
+
+
+class DockerSettings(BaseModel):
+    """Docker configuration settings for running Claude commands in containers."""
+
+    docker_image: str = Field(
+        default=f"ghcr.io/caddyglow/ccproxy:{format_version(__version__, level='docker')}",
+        description="Docker image to use for Claude commands",
+    )
+
+    docker_volumes: list[str] = Field(
+        default_factory=list,
+        description="List of volume mounts in 'host:container[:options]' format",
+    )
+
+    docker_environment: dict[str, str] = Field(
+        default_factory=dict,
+        description="Environment variables to pass to Docker container",
+    )
+
+    docker_additional_args: list[str] = Field(
+        default_factory=list,
+        description="Additional arguments to pass to docker run command",
+    )
+
+    docker_home_directory: str | None = Field(
+        default=None,
+        description="Local host directory to mount as the home directory in container",
+    )
+
+    docker_workspace_directory: str | None = Field(
+        default=None,
+        description="Local host directory to mount as the workspace directory in container",
+    )
+
+    user_mapping_enabled: bool = Field(
+        default=True,
+        description="Enable/disable UID/GID mapping for container user",
+    )
+
+    user_uid: int | None = Field(
+        default=None,
+        description="User ID to run container as (auto-detect current user if None)",
+        ge=0,
+    )
+
+    user_gid: int | None = Field(
+        default=None,
+        description="Group ID to run container as (auto-detect current user if None)",
+        ge=0,
+    )
+
+    @field_validator("docker_volumes")
+    @classmethod
+    def validate_docker_volumes(cls, v: list[str]) -> list[str]:
+        """Validate Docker volume mount format."""
+        return validate_volumes_list(v)
+
+    @field_validator("docker_home_directory")
+    @classmethod
+    def validate_docker_home_directory(cls, v: str | None) -> str | None:
+        """Validate and normalize Docker home directory (host path)."""
+        if v is None:
+            return None
+        return validate_host_path(v)
+
+    @field_validator("docker_workspace_directory")
+    @classmethod
+    def validate_docker_workspace_directory(cls, v: str | None) -> str | None:
+        """Validate and normalize Docker workspace directory (host path)."""
+        if v is None:
+            return None
+        return validate_host_path(v)
+
+    @model_validator(mode="after")
+    def setup_docker_configuration(self) -> "DockerSettings":
+        """Set up Docker volumes and user mapping configuration."""
+        # Set up Docker volumes based on home and workspace directories
+        if (
+            not self.docker_volumes
+            and not self.docker_home_directory
+            and not self.docker_workspace_directory
+        ):
+            # Use XDG config directory for Claude CLI data
+            claude_config_dir = get_claude_docker_home_dir()
+            home_host_path = str(claude_config_dir)
+            workspace_host_path = os.path.expandvars("$PWD")
+
+            self.docker_volumes = [
+                f"{home_host_path}:/data/home",
+                f"{workspace_host_path}:/data/workspace",
+            ]
+
+        # Update environment variables to point to container paths
+        if "CLAUDE_HOME" not in self.docker_environment:
+            self.docker_environment["CLAUDE_HOME"] = "/data/home"
+        if "CLAUDE_WORKSPACE" not in self.docker_environment:
+            self.docker_environment["CLAUDE_WORKSPACE"] = "/data/workspace"
+
+        # Set up user mapping with auto-detection if enabled but not configured
+        if self.user_mapping_enabled and os.name == "posix":
+            # Auto-detect current user UID/GID if not explicitly set
+            if self.user_uid is None:
+                self.user_uid = os.getuid()
+            if self.user_gid is None:
+                self.user_gid = os.getgid()
+        elif self.user_mapping_enabled and os.name != "posix":
+            # Disable user mapping on non-Unix systems (Windows)
+            self.user_mapping_enabled = False
+
+        return self

ccproxy/config/loader.py

@@ -0,0 +1,108 @@
+"""Configuration file loader for ccproxy."""
+
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+from ccproxy.config.discovery import find_toml_config_file
+from ccproxy.config.settings import Settings
+
+
+class ConfigurationError(Exception):
+    """Configuration loading error."""
+
+    pass
+
+
+class ConfigLoader:
+    """Load configuration from multiple sources."""
+
+    def __init__(self) -> None:
+        self._cached_config: dict[str, Any] | None = None
+
+    def load(self, config_file: Path | None = None) -> Settings:
+        """Load configuration from multiple sources.
+
+        Priority: ENV > config file > defaults
+
+        Args:
+            config_file: Optional path to config file
+
+        Returns:
+            Settings instance with loaded configuration
+
+        Raises:
+            ConfigurationError: If config file is invalid or cannot be loaded
+        """
+        config_data = self._load_config_file(config_file)
+
+        # Environment variables take precedence over config file
+        return Settings(**config_data) if config_data else Settings()
+
+    def _load_config_file(self, config_file: Path | None = None) -> dict[str, Any]:
+        """Load configuration from file.
+
+        Args:
+            config_file: Optional path to config file
+
+        Returns:
+            Configuration dictionary
+
+        Raises:
+            ConfigurationError: If config file is invalid
+        """
+        if config_file is None:
+            config_file = find_toml_config_file()
+
+        if config_file is None or not config_file.exists():
+            return {}
+
+        try:
+            if config_file.suffix.lower() in [".toml", ".tml"]:
+                return self._load_toml_config(config_file)
+            else:
+                raise ConfigurationError(
+                    f"Unsupported config file format: {config_file.suffix}. Only TOML (.toml) files are supported."
+                )
+        except Exception as e:
+            raise ConfigurationError(
+                f"Failed to load config file {config_file}: {e}"
+            ) from e
+
+    def _load_toml_config(self, config_file: Path) -> dict[str, Any]:
+        """Load TOML configuration file."""
+        try:
+            import tomllib
+        except ImportError:
+            try:
+                import tomli as tomllib  # type: ignore
+            except ImportError:
+                raise ConfigurationError(
+                    "TOML support not available. Install 'tomli' for Python < 3.11"
+                ) from None
+
+        with config_file.open("rb") as f:
+            data = tomllib.load(f)
+            return data if isinstance(data, dict) else {}
+
+    def clear_cache(self) -> None:
+        """Clear cached configuration."""
+        self._cached_config = None
+
+
+# Global config loader instance
+config_loader = ConfigLoader()
+
+
+def load_config(config_file: Path | None = None) -> Settings:
+    """Load configuration using the global loader.
+
+    Args:
+        config_file: Optional path to config file
+
+    Returns:
+        Settings instance with loaded configuration
+    """
+    return config_loader.load(config_file)

ccproxy/config/observability.py

@@ -0,0 +1,158 @@
+"""Observability configuration settings."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class ObservabilitySettings(BaseModel):
+    """Observability configuration settings."""
+
+    # Endpoint Controls
+    metrics_endpoint_enabled: bool = Field(
+        default=False,
+        description="Enable Prometheus /metrics endpoint",
+    )
+
+    logs_endpoints_enabled: bool = Field(
+        default=False,
+        description="Enable logs query/analytics/streaming endpoints (/logs/*)",
+    )
+
+    dashboard_enabled: bool = Field(
+        default=False,
+        description="Enable metrics dashboard endpoint (/dashboard)",
+    )
+
+    # Data Collection & Storage
+    logs_collection_enabled: bool = Field(
+        default=False,
+        description="Enable collection of request/response logs to storage backend",
+    )
+
+    log_storage_backend: Literal["duckdb", "none"] = Field(
+        default="duckdb",
+        description="Storage backend for logs ('duckdb' or 'none')",
+    )
+
+    # Storage Configuration
+    duckdb_path: str = Field(
+        default_factory=lambda: str(
+            Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+            / "ccproxy"
+            / "metrics.duckdb"
+        ),
+        description="Path to DuckDB database file",
+    )
+
+    # Pushgateway Configuration
+    pushgateway_url: str | None = Field(
+        default=None,
+        description="Pushgateway URL (e.g., http://pushgateway:9091)",
+    )
+
+    pushgateway_job: str = Field(
+        default="ccproxy",
+        description="Job name for Pushgateway metrics",
+    )
+
+    # Stats printing configuration
+    stats_printing_format: str = Field(
+        default="console",
+        description="Format for stats output: 'console', 'rich', 'log', 'json'",
+    )
+
+    # Enhanced logging integration
+    logging_pipeline_enabled: bool = Field(
+        default=True,
+        description="Enable structlog pipeline integration for observability",
+    )
+
+    logging_format: str = Field(
+        default="auto",
+        description="Logging format for observability: 'rich', 'json', 'auto' (auto-detects based on environment)",
+    )
+
+    @model_validator(mode="after")
+    def check_feature_dependencies(self) -> ObservabilitySettings:
+        """Validate feature dependencies to prevent invalid configurations."""
+        # Dashboard requires logs endpoints (functional dependency)
+        if self.dashboard_enabled and not self.logs_endpoints_enabled:
+            raise ValueError(
+                "Cannot enable 'dashboard_enabled' without 'logs_endpoints_enabled'. "
+                "Dashboard needs logs API to function."
+            )
+
+        # Logs endpoints require storage to query from
+        if self.logs_endpoints_enabled and self.log_storage_backend == "none":
+            raise ValueError(
+                "Cannot enable 'logs_endpoints_enabled' when 'log_storage_backend' is 'none'. "
+                "Logs endpoints need storage backend to query data."
+            )
+
+        # Log collection requires storage to write to
+        if self.logs_collection_enabled and self.log_storage_backend == "none":
+            raise ValueError(
+                "Cannot enable 'logs_collection_enabled' when 'log_storage_backend' is 'none'. "
+                "Collection needs storage backend to persist data."
+            )
+
+        return self
+
+    @field_validator("stats_printing_format")
+    @classmethod
+    def validate_stats_printing_format(cls, v: str) -> str:
+        """Validate and normalize stats printing format."""
+        lower_v = v.lower()
+        valid_formats = ["console", "rich", "log", "json"]
+        if lower_v not in valid_formats:
+            raise ValueError(
+                f"Invalid stats printing format: {v}. Must be one of {valid_formats}"
+            )
+        return lower_v
+
+    @field_validator("logging_format")
+    @classmethod
+    def validate_logging_format(cls, v: str) -> str:
+        """Validate and normalize logging format."""
+        lower_v = v.lower()
+        valid_formats = ["auto", "rich", "json", "plain"]
+        if lower_v not in valid_formats:
+            raise ValueError(
+                f"Invalid logging format: {v}. Must be one of {valid_formats}"
+            )
+        return lower_v
+
+    @property
+    def needs_storage_backend(self) -> bool:
+        """Check if any feature requires storage backend initialization."""
+        return self.logs_endpoints_enabled or self.logs_collection_enabled
+
+    @property
+    def any_endpoint_enabled(self) -> bool:
+        """Check if any observability endpoint is enabled."""
+        return (
+            self.metrics_endpoint_enabled
+            or self.logs_endpoints_enabled
+            or self.dashboard_enabled
+        )
+
+    # Backward compatibility properties
+    @property
+    def metrics_enabled(self) -> bool:
+        """Backward compatibility: True if any metrics feature is enabled."""
+        return self.any_endpoint_enabled
+
+    @property
+    def duckdb_enabled(self) -> bool:
+        """Backward compatibility: True if DuckDB storage backend is selected."""
+        return self.log_storage_backend == "duckdb"
+
+    @property
+    def enabled(self) -> bool:
+        """Check if observability is enabled (backward compatibility property)."""
+        return self.any_endpoint_enabled or self.logging_pipeline_enabled

ccproxy/config/pricing.py

@@ -0,0 +1,88 @@
+"""Pricing configuration settings."""
+
+from pathlib import Path
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings
+
+from ccproxy.core.system import get_xdg_cache_home
+
+
+class PricingSettings(BaseSettings):
+    """
+    Configuration settings for the pricing system.
+
+    Controls pricing cache behavior, data sources, and update mechanisms.
+    Settings can be configured via environment variables with PRICING__ prefix.
+    """
+
+    # Cache settings
+    cache_dir: Path = Field(
+        default_factory=lambda: get_xdg_cache_home() / "ccproxy",
+        description="Directory for pricing cache files (defaults to XDG_CACHE_HOME/ccproxy)",
+    )
+
+    cache_ttl_hours: int = Field(
+        default=24,
+        ge=1,
+        le=168,  # Max 1 week
+        description="Hours before pricing cache expires",
+    )
+
+    # Data source settings
+    source_url: str = Field(
+        default="https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
+        description="URL to download pricing data from",
+    )
+
+    download_timeout: int = Field(
+        default=30,
+        ge=1,
+        le=300,  # Max 5 minutes
+        description="Request timeout in seconds for downloading pricing data",
+    )
+
+    # Update behavior settings
+    auto_update: bool = Field(
+        default=True,
+        description="Whether to automatically update stale cache",
+    )
+
+    fallback_to_embedded: bool = Field(
+        default=True,
+        description="Whether to fallback to embedded pricing on failure",
+    )
+
+    # Memory cache settings
+    memory_cache_ttl: int = Field(
+        default=300,
+        ge=1,
+        le=3600,  # Max 1 hour
+        description="Time to live for in-memory pricing cache in seconds",
+    )
+
+    @field_validator("cache_dir", mode="before")
+    @classmethod
+    def validate_cache_dir(cls, v: str | Path | None) -> Path:
+        """Validate and convert cache directory path."""
+        if v is None:
+            return get_xdg_cache_home() / "ccproxy"
+        if isinstance(v, str):
+            if v.startswith("~/"):
+                return Path(v).expanduser()
+            return Path(v)
+        return v
+
+    @field_validator("source_url")
+    @classmethod
+    def validate_source_url(cls, v: str) -> str:
+        """Validate source URL format."""
+        if not v.startswith(("http://", "https://")):
+            raise ValueError("Source URL must start with http:// or https://")
+        return v
+
+    class Config:
+        """Pydantic configuration."""
+
+        env_prefix = "PRICING__"
+        case_sensitive = False

ccproxy/config/reverse_proxy.py

@@ -0,0 +1,31 @@
+"""Reverse proxy configuration settings."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class ReverseProxySettings(BaseModel):
+    """Reverse proxy configuration settings."""
+
+    target_url: str = Field(
+        default="https://api.anthropic.com",
+        description="Target URL for reverse proxy requests",
+    )
+
+    timeout: float = Field(
+        default=120.0,
+        description="Timeout for reverse proxy requests in seconds",
+        ge=1.0,
+        le=600.0,
+    )
+
+    default_mode: Literal["claude_code", "full", "minimal"] = Field(
+        default="claude_code",
+        description="Default transformation mode for root path reverse proxy, over claude code or auth injection with full",
+    )
+
+    claude_code_prefix: str = Field(
+        default="/cc",
+        description="URL prefix for Claude Code SDK endpoints",
+    )