ccproxy-api 0.1.7__py3-none-any.whl → 0.2.0a4__py3-none-any.whl

ccproxy/core/plugins/middleware.py

@@ -0,0 +1,233 @@
+"""Middleware management and ordering for the plugin system.
+
+This module provides utilities for managing middleware registration
+and ensuring proper ordering across core and plugin middleware.
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from fastapi import FastAPI
+
+from ccproxy.core.logging import TraceBoundLogger, get_logger
+
+from .declaration import MiddlewareLayer, MiddlewareSpec
+
+
+if TYPE_CHECKING:
+    from starlette.middleware.base import BaseHTTPMiddleware
+else:
+    from starlette.middleware.base import BaseHTTPMiddleware
+
+
+logger: TraceBoundLogger = get_logger()
+
+
+@dataclass
+class CoreMiddlewareSpec(MiddlewareSpec):
+    """Specification for core application middleware.
+
+    Extends MiddlewareSpec with a source field to distinguish
+    between core and plugin middleware.
+    """
+
+    source: str = "core"  # "core" or plugin name
+
+
+class MiddlewareManager:
+    """Manages middleware registration and ordering."""
+
+    def __init__(self) -> None:
+        """Initialize middleware manager."""
+        self.middleware_specs: list[CoreMiddlewareSpec] = []
+
+    def add_core_middleware(
+        self,
+        middleware_class: type[BaseHTTPMiddleware],
+        priority: int = MiddlewareLayer.APPLICATION,
+        **kwargs: Any,
+    ) -> None:
+        """Add core application middleware.
+
+        Args:
+            middleware_class: Middleware class
+            priority: Priority for ordering
+            **kwargs: Additional middleware arguments
+        """
+        spec = CoreMiddlewareSpec(
+            middleware_class=middleware_class,
+            priority=priority,
+            kwargs=kwargs,
+            source="core",
+        )
+        self.middleware_specs.append(spec)
+
+    def add_plugin_middleware(
+        self, plugin_name: str, specs: list[MiddlewareSpec]
+    ) -> None:
+        """Add middleware from a plugin.
+
+        Args:
+            plugin_name: Name of the plugin
+            specs: List of middleware specifications
+        """
+        for spec in specs:
+            core_spec = CoreMiddlewareSpec(
+                middleware_class=spec.middleware_class,
+                priority=spec.priority,
+                kwargs=spec.kwargs,
+                source=plugin_name,
+            )
+            self.middleware_specs.append(core_spec)
+            logger.trace(
+                "plugin_middleware_added",
+                plugin=plugin_name,
+                middleware=spec.middleware_class.__name__,
+                priority=spec.priority,
+                category="middleware",
+            )
+
+    def get_ordered_middleware(self) -> list[CoreMiddlewareSpec]:
+        """Get all middleware sorted by priority.
+
+        Returns:
+            List of middleware specs sorted by priority (lower first)
+        """
+        # Sort by priority (lower values first)
+        # Secondary sort by source (core before plugins) for same priority
+        return sorted(
+            self.middleware_specs,
+            key=lambda x: (x.priority, x.source != "core", x.source),
+        )
+
+    def apply_to_app(self, app: FastAPI) -> None:
+        """Apply all middleware to the FastAPI app in correct order.
+
+        Note: Middleware in FastAPI/Starlette is applied in reverse order
+        (last added runs first), so we add them in reverse priority order.
+
+        Args:
+            app: FastAPI application
+        """
+        ordered = self.get_ordered_middleware()
+        applied_middleware = []
+        failed_middleware = []
+
+        # Apply in reverse order (highest priority last so it runs first)
+        for spec in reversed(ordered):
+            try:
+                app.add_middleware(spec.middleware_class, **spec.kwargs)  # type: ignore[arg-type]
+                applied_middleware.append(
+                    {
+                        "name": spec.middleware_class.__name__,
+                        "priority": spec.priority,
+                        "source": spec.source,
+                    }
+                )
+            except Exception as e:
+                failed_middleware.append(
+                    {
+                        "name": spec.middleware_class.__name__,
+                        "source": spec.source,
+                        "error": str(e),
+                    }
+                )
+                logger.error(
+                    "middleware_application_failed",
+                    middleware=spec.middleware_class.__name__,
+                    source=spec.source,
+                    error=str(e),
+                    exc_info=e,
+                    category="middleware",
+                )
+
+        # Log aggregated success
+        if applied_middleware:
+            logger.info(
+                "middleware_stack_configured",
+                applied=len(applied_middleware),
+                failed=len(failed_middleware),
+                middleware=[m["name"] for m in applied_middleware],
+                category="middleware",
+            )
+
+    def get_middleware_summary(self) -> dict[str, Any]:
+        """Get a summary of registered middleware.
+
+        Returns:
+            Dictionary with middleware statistics and order
+        """
+        ordered = self.get_ordered_middleware()
+
+        summary = {
+            "total": len(ordered),
+            "core": len([m for m in ordered if m.source == "core"]),
+            "plugins": len([m for m in ordered if m.source != "core"]),
+            "order": [
+                {
+                    "name": spec.middleware_class.__name__,
+                    "priority": spec.priority,
+                    "layer": self._get_layer_name(spec.priority),
+                    "source": spec.source,
+                }
+                for spec in ordered
+            ],
+        }
+
+        return summary
+
+    def _get_layer_name(self, priority: int) -> str:
+        """Get the layer name for a priority value.
+
+        Args:
+            priority: Priority value
+
+        Returns:
+            Layer name
+        """
+        # Find the closest layer
+        for layer in MiddlewareLayer:
+            if priority < layer:
+                return f"before_{layer.name.lower()}"
+            elif priority == layer:
+                return layer.name.lower()
+
+        # If higher than all layers
+        return "after_application"
+
+
+def setup_default_middleware(manager: MiddlewareManager) -> None:
+    """Setup default core middleware.
+
+    Args:
+        manager: Middleware manager
+    """
+    from ccproxy.api.middleware.hooks import HooksMiddleware
+    from ccproxy.api.middleware.normalize_headers import NormalizeHeadersMiddleware
+    from ccproxy.api.middleware.request_id import RequestIDMiddleware
+
+    # Request ID should be first (lowest priority) to set context for all others
+    manager.add_core_middleware(
+        RequestIDMiddleware,
+        priority=MiddlewareLayer.SECURITY - 50,  # Before security layer
+    )
+
+    # Hooks middleware should be early to capture all requests
+    manager.add_core_middleware(
+        HooksMiddleware,
+        priority=MiddlewareLayer.SECURITY
+        - 40,  # After request ID, before other middleware
+    )
+
+    # # Access logging in observability layer
+    # manager.add_core_middleware(
+    #     AccessLogMiddleware, priority=MiddlewareLayer.OBSERVABILITY
+    # )
+    #
+    # Normalize headers: strip unsafe and ensure server header
+    manager.add_core_middleware(
+        NormalizeHeadersMiddleware,  # type: ignore[arg-type]
+        priority=MiddlewareLayer.ROUTING,  # after routing layer
+    )
+
+    logger.debug("default_middleware_configured", category="middleware")

ccproxy/core/plugins/models.py

@@ -0,0 +1,59 @@
+"""Common provider plugin health detail models.
+
+These models standardize the `details` payload returned by provider plugins
+in their health checks, enabling consistent inspection across plugins.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class CLIHealth(BaseModel):
+    """Standardized CLI health information for a provider plugin."""
+
+    available: bool = Field(description="Whether the CLI is available")
+    status: str = Field(description="CLI status string from plugin detector")
+    version: str | None = Field(default=None, description="Detected CLI version")
+    path: str | None = Field(default=None, description="Resolved CLI binary path")
+
+
+class AuthHealth(BaseModel):
+    """Standardized authentication health information."""
+
+    configured: bool = Field(description="Whether auth is configured for this plugin")
+    token_available: bool | None = Field(
+        default=None, description="Valid, non-expired token is available"
+    )
+    token_expired: bool | None = Field(default=None, description="Token is expired")
+    account_id: str | None = Field(default=None, description="Associated account id")
+    expires_at: str | None = Field(default=None, description="Token expiry ISO time")
+    error: str | None = Field(default=None, description="Auth error or reason text")
+
+
+class ConfigHealth(BaseModel):
+    """Standardized configuration summary for a provider plugin."""
+
+    model_count: int | None = Field(default=None, description="Configured model count")
+    supports_openai_format: bool | None = Field(
+        default=None, description="Whether OpenAI-compatible format is supported"
+    )
+    verbose_logging: bool | None = Field(
+        default=None, description="Whether plugin verbose logging is enabled"
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None, description="Additional provider-specific configuration"
+    )
+
+
+class ProviderHealthDetails(BaseModel):
+    """Top-level standardized provider health details payload."""
+
+    provider: str = Field(description="Provider plugin name")
+    enabled: bool = Field(description="Whether this plugin is enabled")
+    base_url: str | None = Field(default=None, description="Provider base URL")
+    cli: CLIHealth | None = Field(default=None, description="CLI health")
+    auth: AuthHealth | None = Field(default=None, description="Auth health")
+    config: ConfigHealth | None = Field(default=None, description="Config summary")

ccproxy/core/plugins/protocol.py

@@ -0,0 +1,180 @@
+"""Plugin protocol for provider plugins."""
+
+from typing import TYPE_CHECKING, Any, Literal, Protocol, runtime_checkable
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+from ccproxy.core.plugins.hooks.base import Hook
+from ccproxy.models.provider import ProviderConfig
+from ccproxy.services.adapters.base import BaseAdapter
+
+
+if TYPE_CHECKING:
+    from ccproxy.scheduler.tasks import BaseScheduledTask
+    from ccproxy.services.container import ServiceContainer
+
+
+@runtime_checkable
+class OAuthClientProtocol(Protocol):
+    """Protocol for OAuth client implementations."""
+
+    async def authenticate(self, open_browser: bool = True) -> Any:
+        """Perform OAuth authentication flow.
+
+        Args:
+            open_browser: Whether to automatically open browser
+
+        Returns:
+            Provider-specific credentials object
+        """
+        ...
+
+    async def refresh_access_token(self, refresh_token: str) -> Any:
+        """Refresh access token using refresh token.
+
+        Args:
+            refresh_token: Refresh token
+
+        Returns:
+            New token response
+        """
+        ...
+
+
+class AuthCommandDefinition(TypedDict, total=False):
+    """Definition for provider-specific auth command extensions."""
+
+    command_name: str  # Required: Command name (e.g., 'validate', 'profile')
+    description: str  # Required: Command description
+    handler: Any  # Required: Async command handler function
+    options: dict[str, Any]  # Optional: Additional command options
+
+
+class HealthCheckResult(BaseModel):
+    """Standardized health check result following IETF format."""
+
+    status: Literal["pass", "warn", "fail"]
+    componentId: str  # noqa: N815
+    componentType: str = "provider_plugin"  # noqa: N815
+    output: str | None = None
+    version: str | None = None
+    details: dict[str, Any] | None = None
+
+
+class ScheduledTaskDefinition(TypedDict, total=False):
+    """Definition for a scheduled task from a plugin."""
+
+    task_name: str  # Required: Unique name for the task instance
+    task_type: str  # Required: Type identifier for task registry
+    task_class: type["BaseScheduledTask"]  # Required: Task class
+    interval_seconds: float  # Required: Interval between executions
+    enabled: bool  # Optional: Whether task is enabled (default: True)
+    # Additional kwargs can be passed for task initialization
+
+
+@runtime_checkable
+class BasePlugin(Protocol):
+    """Base protocol for all plugins."""
+
+    @property
+    def name(self) -> str:
+        """Plugin name."""
+        ...
+
+    @property
+    def version(self) -> str:
+        """Plugin version."""
+        ...
+
+    @property
+    def dependencies(self) -> list[str]:
+        """List of plugin names this plugin depends on."""
+        ...
+
+    @property
+    def router_prefix(self) -> str:
+        """Unique route prefix for this plugin."""
+        ...
+
+    async def initialize(self, services: "ServiceContainer") -> None:
+        """Initialize plugin with shared services. Called once on startup."""
+        ...
+
+    async def shutdown(self) -> None:
+        """Perform graceful shutdown. Called once on app shutdown."""
+        ...
+
+    async def validate(self) -> bool:
+        """Validate plugin is ready."""
+        ...
+
+    def get_routes(self) -> APIRouter | dict[str, APIRouter] | None:
+        """Get plugin-specific routes (optional)."""
+        ...
+
+    async def health_check(self) -> HealthCheckResult:
+        """Perform health check following IETF format."""
+        ...
+
+    def get_scheduled_tasks(self) -> list[ScheduledTaskDefinition] | None:
+        """Get scheduled task definitions for this plugin (optional).
+
+        Returns:
+            List of task definitions or None if no scheduled tasks needed
+        """
+        ...
+
+    def get_config_class(self) -> type[BaseModel] | None:
+        """Get the Pydantic configuration model for this plugin.
+
+        Returns:
+            Pydantic BaseModel class for plugin configuration or None if no configuration needed
+        """
+        ...
+
+    def get_hooks(self) -> list[Hook] | None:
+        """Get hooks provided by this plugin (optional).
+
+        Returns:
+            List of hook instances or None if no hooks
+        """
+        ...
+
+
+@runtime_checkable
+class SystemPlugin(BasePlugin, Protocol):
+    """Protocol for system plugins (non-provider plugins).
+
+    System plugins inherit all methods from BasePlugin and don't add
+    any additional requirements. They don't proxy to external providers
+    and therefore don't need adapters or provider configurations.
+    """
+
+    # SystemPlugin has no additional methods beyond BasePlugin
+    pass
+
+
+@runtime_checkable
+class ProviderPlugin(BasePlugin, Protocol):
+    """Enhanced protocol for provider plugins.
+
+    Provider plugins proxy requests to external API providers and therefore
+    need additional methods for creating adapters and configurations.
+    """
+
+    def create_adapter(self) -> BaseAdapter:
+        """Create adapter instance for handling provider requests."""
+        ...
+
+    def create_config(self) -> ProviderConfig:
+        """Create provider configuration from settings."""
+        ...
+
+    async def get_oauth_client(self) -> OAuthClientProtocol | None:
+        """Get OAuth client for this plugin if it supports OAuth authentication.
+
+        Returns:
+            OAuth client instance or None if plugin doesn't support OAuth
+        """