ccproxy-api 0.1.0__py3-none-any.whl

ccproxy/core/transformers.py

@@ -0,0 +1,259 @@
+"""Core transformer abstractions for request/response transformation."""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Optional, Protocol, TypeVar, runtime_checkable
+
+from structlog import get_logger
+
+from ccproxy.core.types import ProxyRequest, ProxyResponse, TransformContext
+
+
+if TYPE_CHECKING:
+    pass
+
+
+T = TypeVar("T", contravariant=True)
+R = TypeVar("R", covariant=True)
+
+
+class BaseTransformer(ABC):
+    """Abstract base class for all transformers."""
+
+    def __init__(self) -> None:
+        """Initialize transformer."""
+        self.metrics_collector: Any = None
+
+    @abstractmethod
+    async def transform(
+        self, data: Any, context: TransformContext | None = None
+    ) -> Any:
+        """Transform the input data.
+
+        Args:
+            data: The data to transform
+            context: Optional transformation context
+
+        Returns:
+            The transformed data
+
+        Raises:
+            TransformationError: If transformation fails
+        """
+        pass
+
+    async def _collect_transformation_metrics(
+        self,
+        transformation_type: str,
+        input_data: Any,
+        output_data: Any,
+        duration_ms: float,
+        success: bool = True,
+        error: str | None = None,
+    ) -> None:
+        """Collect metrics for transformation operations.
+
+        Args:
+            transformation_type: Type of transformation (request/response)
+            input_data: Original input data
+            output_data: Transformed output data
+            duration_ms: Time taken for transformation in milliseconds
+            success: Whether transformation was successful
+            error: Error message if transformation failed
+        """
+        if not self.metrics_collector:
+            return
+
+        try:
+            # Calculate data sizes
+            input_size = self._calculate_data_size(input_data)
+            output_size = self._calculate_data_size(output_data) if output_data else 0
+
+            # Create a unique request ID for this transformation
+            request_id = (
+                f"transformer_{id(self)}_{transformation_type}_{id(input_data)}"
+            )
+
+            # Use existing latency collection method with timing data
+            await self.metrics_collector.collect_latency(
+                request_id=request_id,
+                transformation_duration=duration_ms,
+                processing_time=duration_ms,
+            )
+
+        except Exception as e:
+            # Don't let metrics collection fail the transformation
+            logger = get_logger(__name__)
+            # logger = logging.getLogger(__name__)
+            logger.debug(
+                "transformation_metrics_failed",
+                error=str(e),
+                operation="collect_transformation_metrics",
+            )
+
+    def _calculate_data_size(self, data: Any) -> int:
+        """Calculate the size of data in bytes.
+
+        Args:
+            data: The data to measure
+
+        Returns:
+            Size in bytes
+        """
+        if data is None:
+            return 0
+        elif isinstance(data, bytes):
+            return len(data)
+        elif isinstance(data, str):
+            return len(data.encode("utf-8"))
+        elif hasattr(data, "__len__"):
+            return len(str(data))
+        else:
+            return len(str(data))
+
+
+class RequestTransformer(BaseTransformer):
+    """Base class for request transformers."""
+
+    async def transform(
+        self, request: ProxyRequest, context: TransformContext | None = None
+    ) -> ProxyRequest:
+        """Transform a proxy request with metrics collection.
+
+        Args:
+            request: The request to transform
+            context: Optional transformation context
+
+        Returns:
+            The transformed request
+        """
+        import time
+
+        start_time = time.perf_counter()
+        error_msg = None
+        result = None
+
+        try:
+            result = await self._transform_request(request, context)
+            return result
+        except Exception as e:
+            error_msg = str(e)
+            raise
+        finally:
+            # Collect metrics regardless of success/failure
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            await self._collect_transformation_metrics(
+                transformation_type="request",
+                input_data=request,
+                output_data=result,
+                duration_ms=duration_ms,
+                success=error_msg is None,
+                error=error_msg,
+            )
+
+    @abstractmethod
+    async def _transform_request(
+        self, request: ProxyRequest, context: TransformContext | None = None
+    ) -> ProxyRequest:
+        """Transform a proxy request implementation.
+
+        Args:
+            request: The request to transform
+            context: Optional transformation context
+
+        Returns:
+            The transformed request
+        """
+        pass
+
+
+class ResponseTransformer(BaseTransformer):
+    """Base class for response transformers."""
+
+    async def transform(
+        self, response: ProxyResponse, context: TransformContext | None = None
+    ) -> ProxyResponse:
+        """Transform a proxy response with metrics collection.
+
+        Args:
+            response: The response to transform
+            context: Optional transformation context
+
+        Returns:
+            The transformed response
+        """
+        import time
+
+        start_time = time.perf_counter()
+        error_msg = None
+        result = None
+
+        try:
+            result = await self._transform_response(response, context)
+            return result
+        except Exception as e:
+            error_msg = str(e)
+            raise
+        finally:
+            # Collect metrics regardless of success/failure
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            await self._collect_transformation_metrics(
+                transformation_type="response",
+                input_data=response,
+                output_data=result,
+                duration_ms=duration_ms,
+                success=error_msg is None,
+                error=error_msg,
+            )
+
+    @abstractmethod
+    async def _transform_response(
+        self, response: ProxyResponse, context: TransformContext | None = None
+    ) -> ProxyResponse:
+        """Transform a proxy response implementation.
+
+        Args:
+            response: The response to transform
+            context: Optional transformation context
+
+        Returns:
+            The transformed response
+        """
+        pass
+
+
+@runtime_checkable
+class TransformerProtocol(Protocol[T, R]):
+    """Protocol defining the transformer interface."""
+
+    async def transform(self, data: T, context: TransformContext | None = None) -> R:
+        """Transform the input data."""
+        ...
+
+
+class ChainedTransformer(BaseTransformer):
+    """Transformer that chains multiple transformers together."""
+
+    def __init__(self, transformers: list[BaseTransformer]):
+        """Initialize with a list of transformers to chain.
+
+        Args:
+            transformers: List of transformers to apply in sequence
+        """
+        self.transformers = transformers
+
+    async def transform(
+        self, data: Any, context: TransformContext | None = None
+    ) -> Any:
+        """Apply all transformers in sequence.
+
+        Args:
+            data: The data to transform
+            context: Optional transformation context
+
+        Returns:
+            The result of applying all transformers
+        """
+        result = data
+        for transformer in self.transformers:
+            result = await transformer.transform(result, context)
+        return result

ccproxy/core/types.py

@@ -0,0 +1,129 @@
+"""Core type definitions for the proxy system."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+class ProxyMethod(str, Enum):
+    """HTTP methods supported by the proxy."""
+
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    DELETE = "DELETE"
+    PATCH = "PATCH"
+    HEAD = "HEAD"
+    OPTIONS = "OPTIONS"
+    CONNECT = "CONNECT"
+    TRACE = "TRACE"
+
+
+class ProxyProtocol(str, Enum):
+    """Protocols supported by the proxy."""
+
+    HTTP = "http"
+    HTTPS = "https"
+    WS = "ws"
+    WSS = "wss"
+
+
+@dataclass
+class ProxyRequest:
+    """Represents a proxy request."""
+
+    method: ProxyMethod
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    params: dict[str, Any] = field(default_factory=dict)
+    body: str | bytes | dict[str, Any] | None = None
+    protocol: ProxyProtocol = ProxyProtocol.HTTPS
+    timeout: float | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Validate and normalize the request."""
+        if isinstance(self.method, str):
+            self.method = ProxyMethod(self.method.upper())
+        if isinstance(self.protocol, str):
+            self.protocol = ProxyProtocol(self.protocol.lower())
+
+
+@dataclass
+class ProxyResponse:
+    """Represents a proxy response."""
+
+    status_code: int
+    headers: dict[str, str] = field(default_factory=dict)
+    body: str | bytes | dict[str, Any] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_success(self) -> bool:
+        """Check if the response indicates success."""
+        return 200 <= self.status_code < 300
+
+    @property
+    def is_error(self) -> bool:
+        """Check if the response indicates an error."""
+        return self.status_code >= 400
+
+
+@dataclass
+class TransformContext:
+    """Context passed to transformers during transformation."""
+
+    request: ProxyRequest | None = None
+    response: ProxyResponse | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value from metadata."""
+        return self.metadata.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a value in metadata."""
+        self.metadata[key] = value
+
+
+class ProxyConfig(BaseModel):
+    """Configuration for proxy behavior."""
+
+    timeout: float = Field(default=30.0, description="Default timeout in seconds")
+    max_retries: int = Field(default=3, description="Maximum number of retries")
+    retry_delay: float = Field(
+        default=1.0, description="Delay between retries in seconds"
+    )
+    verify_ssl: bool = Field(
+        default=True, description="Whether to verify SSL certificates"
+    )
+    follow_redirects: bool = Field(
+        default=True, description="Whether to follow redirects"
+    )
+    max_redirects: int = Field(
+        default=10, description="Maximum number of redirects to follow"
+    )
+
+    class Config:
+        """Pydantic configuration."""
+
+        extra = "forbid"
+
+
+class MiddlewareConfig(BaseModel):
+    """Configuration for middleware behavior."""
+
+    enabled: bool = Field(default=True, description="Whether the middleware is enabled")
+    priority: int = Field(
+        default=0, description="Middleware execution priority (lower = earlier)"
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional middleware configuration"
+    )
+
+    class Config:
+        """Pydantic configuration."""
+
+        extra = "allow"

ccproxy/core/validators.py

@@ -0,0 +1,288 @@
+"""Generic validation utilities for the CCProxy API."""
+
+import re
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from ccproxy.core.constants import EMAIL_PATTERN, URL_PATTERN, UUID_PATTERN
+
+
+class ValidationError(Exception):
+    """Base class for validation errors."""
+
+    pass
+
+
+def validate_email(email: str) -> str:
+    """Validate email format.
+
+    Args:
+        email: Email address to validate
+
+    Returns:
+        The validated email address
+
+    Raises:
+        ValidationError: If email format is invalid
+    """
+    if not isinstance(email, str):
+        raise ValidationError("Email must be a string")
+
+    if not re.match(EMAIL_PATTERN, email):
+        raise ValidationError(f"Invalid email format: {email}")
+
+    return email.strip().lower()
+
+
+def validate_url(url: str) -> str:
+    """Validate URL format.
+
+    Args:
+        url: URL to validate
+
+    Returns:
+        The validated URL
+
+    Raises:
+        ValidationError: If URL format is invalid
+    """
+    if not isinstance(url, str):
+        raise ValidationError("URL must be a string")
+
+    if not re.match(URL_PATTERN, url):
+        raise ValidationError(f"Invalid URL format: {url}")
+
+    try:
+        parsed = urlparse(url)
+        if not parsed.scheme or not parsed.netloc:
+            raise ValidationError(f"Invalid URL format: {url}")
+    except Exception as e:
+        raise ValidationError(f"Invalid URL format: {url}") from e
+
+    return url.strip()
+
+
+def validate_uuid(uuid_str: str) -> str:
+    """Validate UUID format.
+
+    Args:
+        uuid_str: UUID string to validate
+
+    Returns:
+        The validated UUID string
+
+    Raises:
+        ValidationError: If UUID format is invalid
+    """
+    if not isinstance(uuid_str, str):
+        raise ValidationError("UUID must be a string")
+
+    if not re.match(UUID_PATTERN, uuid_str.lower()):
+        raise ValidationError(f"Invalid UUID format: {uuid_str}")
+
+    return uuid_str.strip().lower()
+
+
+def validate_path(path: str | Path, must_exist: bool = True) -> Path:
+    """Validate file system path.
+
+    Args:
+        path: Path to validate
+        must_exist: Whether the path must exist
+
+    Returns:
+        The validated Path object
+
+    Raises:
+        ValidationError: If path is invalid
+    """
+    if isinstance(path, str):
+        path = Path(path)
+    elif not isinstance(path, Path):
+        raise ValidationError("Path must be a string or Path object")
+
+    if must_exist and not path.exists():
+        raise ValidationError(f"Path does not exist: {path}")
+
+    return path.resolve()
+
+
+def validate_port(port: int | str) -> int:
+    """Validate port number.
+
+    Args:
+        port: Port number to validate
+
+    Returns:
+        The validated port number
+
+    Raises:
+        ValidationError: If port is invalid
+    """
+    if isinstance(port, str):
+        try:
+            port = int(port)
+        except ValueError as e:
+            raise ValidationError(f"Port must be a valid integer: {port}") from e
+
+    if not isinstance(port, int):
+        raise ValidationError(f"Port must be an integer: {port}")
+
+    if port < 1 or port > 65535:
+        raise ValidationError(f"Port must be between 1 and 65535: {port}")
+
+    return port
+
+
+def validate_timeout(timeout: float | int | str) -> float:
+    """Validate timeout value.
+
+    Args:
+        timeout: Timeout value to validate
+
+    Returns:
+        The validated timeout value
+
+    Raises:
+        ValidationError: If timeout is invalid
+    """
+    if isinstance(timeout, str):
+        try:
+            timeout = float(timeout)
+        except ValueError as e:
+            raise ValidationError(f"Timeout must be a valid number: {timeout}") from e
+
+    if not isinstance(timeout, int | float):
+        raise ValidationError(f"Timeout must be a number: {timeout}")
+
+    if timeout < 0:
+        raise ValidationError(f"Timeout must be non-negative: {timeout}")
+
+    return float(timeout)
+
+
+def validate_non_empty_string(value: str, name: str = "value") -> str:
+    """Validate that a string is not empty.
+
+    Args:
+        value: String value to validate
+        name: Name of the field for error messages
+
+    Returns:
+        The validated string
+
+    Raises:
+        ValidationError: If string is empty or not a string
+    """
+    if not isinstance(value, str):
+        raise ValidationError(f"{name} must be a string")
+
+    if not value.strip():
+        raise ValidationError(f"{name} cannot be empty")
+
+    return value.strip()
+
+
+def validate_dict(value: Any, required_keys: list[str] | None = None) -> dict[str, Any]:
+    """Validate dictionary and required keys.
+
+    Args:
+        value: Value to validate as dictionary
+        required_keys: List of required keys
+
+    Returns:
+        The validated dictionary
+
+    Raises:
+        ValidationError: If not a dictionary or missing required keys
+    """
+    if not isinstance(value, dict):
+        raise ValidationError("Value must be a dictionary")
+
+    if required_keys:
+        missing_keys = [key for key in required_keys if key not in value]
+        if missing_keys:
+            raise ValidationError(f"Missing required keys: {missing_keys}")
+
+    return value
+
+
+def validate_list(
+    value: Any, min_length: int = 0, max_length: int | None = None
+) -> list[Any]:
+    """Validate list and length constraints.
+
+    Args:
+        value: Value to validate as list
+        min_length: Minimum list length
+        max_length: Maximum list length
+
+    Returns:
+        The validated list
+
+    Raises:
+        ValidationError: If not a list or length constraints are violated
+    """
+    if not isinstance(value, list):
+        raise ValidationError("Value must be a list")
+
+    if len(value) < min_length:
+        raise ValidationError(f"List must have at least {min_length} items")
+
+    if max_length is not None and len(value) > max_length:
+        raise ValidationError(f"List cannot have more than {max_length} items")
+
+    return value
+
+
+def validate_choice(value: Any, choices: list[Any], name: str = "value") -> Any:
+    """Validate that value is one of the allowed choices.
+
+    Args:
+        value: Value to validate
+        choices: List of allowed choices
+        name: Name of the field for error messages
+
+    Returns:
+        The validated value
+
+    Raises:
+        ValidationError: If value is not in choices
+    """
+    if value not in choices:
+        raise ValidationError(f"{name} must be one of {choices}, got: {value}")
+
+    return value
+
+
+def validate_range(
+    value: float | int,
+    min_value: float | int | None = None,
+    max_value: float | int | None = None,
+    name: str = "value",
+) -> float | int:
+    """Validate that a numeric value is within a specified range.
+
+    Args:
+        value: Numeric value to validate
+        min_value: Minimum allowed value
+        max_value: Maximum allowed value
+        name: Name of the field for error messages
+
+    Returns:
+        The validated value
+
+    Raises:
+        ValidationError: If value is outside the allowed range
+    """
+    if not isinstance(value, int | float):
+        raise ValidationError(f"{name} must be a number")
+
+    if min_value is not None and value < min_value:
+        raise ValidationError(f"{name} must be at least {min_value}")
+
+    if max_value is not None and value > max_value:
+        raise ValidationError(f"{name} must be at most {max_value}")
+
+    return value