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

ccproxy/{observability → plugins/metrics}/pushgateway.py

@@ -1,16 +1,18 @@
-"""Prometheus Pushgateway integration for batch metrics."""
+"""Prometheus Pushgateway integration for the metrics plugin."""
 
 from __future__ import annotations
 
 import time
 from typing import Any
 
-from structlog import get_logger
+import httpx
 
-from ccproxy.config.observability import ObservabilitySettings
+from ccproxy.core.logging import get_plugin_logger
 
+from .config import MetricsConfig
 
-logger = get_logger(__name__)
+
+logger = get_plugin_logger(__name__)
 
 
 # Import prometheus_client with graceful degradation (matching existing metrics.py pattern)
@@ -92,22 +94,30 @@ class PushgatewayClient:
     Also supports VictoriaMetrics remote write protocol for compatibility.
     """
 
-    def __init__(self, settings: ObservabilitySettings) -> None:
+    def __init__(self, config: MetricsConfig) -> None:
         """Initialize Pushgateway client.
 
         Args:
-            settings: Observability configuration settings
+            config: Metrics plugin configuration
         """
-        self.settings = settings
+        self.config = config
         # Pushgateway is enabled if URL is configured and prometheus_client is available
-        self._enabled = PROMETHEUS_AVAILABLE and bool(settings.pushgateway_url)
+        self._enabled = (
+            PROMETHEUS_AVAILABLE
+            and bool(config.pushgateway_url)
+            and config.pushgateway_enabled
+        )
         self._circuit_breaker = CircuitBreaker(
             failure_threshold=5,
             recovery_timeout=60.0,
         )
 
         # Only log if pushgateway URL is configured but prometheus is not available
-        if settings.pushgateway_url and not PROMETHEUS_AVAILABLE:
+        if (
+            config.pushgateway_url
+            and config.pushgateway_enabled
+            and not PROMETHEUS_AVAILABLE
+        ):
             logger.warning(
                 "prometheus_client not available. Pushgateway will be disabled. "
                 "Install with: pip install prometheus-client"
@@ -124,7 +134,7 @@ class PushgatewayClient:
             True if push succeeded, False otherwise
         """
 
-        if not self._enabled or not self.settings.pushgateway_url:
+        if not self._enabled or not self.config.pushgateway_url:
             return False
 
         # Check circuit breaker before attempting operation
@@ -138,7 +148,7 @@ class PushgatewayClient:
 
         try:
             # Check if URL looks like VictoriaMetrics remote write endpoint
-            if "/api/v1/write" in self.settings.pushgateway_url:
+            if "/api/v1/write" in self.config.pushgateway_url:
                 success = self._push_remote_write(registry)
             else:
                 success = self._push_standard(registry, method)
@@ -154,11 +164,12 @@ class PushgatewayClient:
             self._circuit_breaker.record_failure()
             logger.error(
                 "pushgateway_push_failed",
-                url=self.settings.pushgateway_url,
-                job=self.settings.pushgateway_job,
+                url=self.config.pushgateway_url,
+                job=self.config.pushgateway_job,
                 method=method,
                 error=str(e),
                 error_type=type(e).__name__,
+                exc_info=e,
             )
             return False
 
@@ -169,27 +180,27 @@ class PushgatewayClient:
             registry: Prometheus metrics registry
             method: Push method - "push" (replace), "pushadd" (add), or "delete"
         """
-        if not self.settings.pushgateway_url:
+        if not self.config.pushgateway_url:
             return False
 
         try:
             # Use the appropriate prometheus_client function based on method
             if method == "push":
                 push_to_gateway(
-                    gateway=self.settings.pushgateway_url,
-                    job=self.settings.pushgateway_job,
+                    gateway=self.config.pushgateway_url,
+                    job=self.config.pushgateway_job,
                     registry=registry,
                 )
             elif method == "pushadd":
                 pushadd_to_gateway(
-                    gateway=self.settings.pushgateway_url,
-                    job=self.settings.pushgateway_job,
+                    gateway=self.config.pushgateway_url,
+                    job=self.config.pushgateway_job,
                     registry=registry,
                 )
             elif method == "delete":
                 delete_from_gateway(
-                    gateway=self.settings.pushgateway_url,
-                    job=self.settings.pushgateway_job,
+                    gateway=self.config.pushgateway_url,
+                    job=self.config.pushgateway_job,
                 )
             else:
                 logger.error("pushgateway_invalid_method", method=method)
@@ -197,8 +208,8 @@ class PushgatewayClient:
 
             logger.debug(
                 "pushgateway_push_success",
-                url=self.settings.pushgateway_url,
-                job=self.settings.pushgateway_job,
+                url=self.config.pushgateway_url,
+                job=self.config.pushgateway_job,
                 protocol="standard",
                 method=method,
             )
@@ -207,11 +218,12 @@ class PushgatewayClient:
         except Exception as e:
             logger.error(
                 "pushgateway_standard_push_failed",
-                url=self.settings.pushgateway_url,
-                job=self.settings.pushgateway_job,
+                url=self.config.pushgateway_url,
+                job=self.config.pushgateway_job,
                 method=method,
                 error=str(e),
                 error_type=type(e).__name__,
+                exc_info=e,
             )
             return False
 
@@ -222,10 +234,9 @@ class PushgatewayClient:
         via the /api/v1/import/prometheus endpoint, which is simpler than
         the full remote write protocol that requires protobuf encoding.
         """
-        import httpx
         from prometheus_client.exposition import generate_latest
 
-        if not self.settings.pushgateway_url:
+        if not self.config.pushgateway_url:
             return False
 
         # Generate metrics in Prometheus exposition format
@@ -233,13 +244,13 @@ class PushgatewayClient:
 
         # Convert /api/v1/write URL to /api/v1/import/prometheus for VictoriaMetrics
         # This endpoint accepts Prometheus exposition format directly
-        if "/api/v1/write" in self.settings.pushgateway_url:
-            import_url = self.settings.pushgateway_url.replace(
+        if "/api/v1/write" in self.config.pushgateway_url:
+            import_url = self.config.pushgateway_url.replace(
                 "/api/v1/write", "/api/v1/import/prometheus"
             )
         else:
             # Fallback - assume it's already the correct import URL
-            import_url = self.settings.pushgateway_url
+            import_url = self.config.pushgateway_url
 
         try:
             # VictoriaMetrics import endpoint accepts text/plain exposition format
@@ -257,7 +268,7 @@ class PushgatewayClient:
                 logger.debug(
                     "pushgateway_import_success",
                     url=import_url,
-                    job=self.settings.pushgateway_job,
+                    job=self.config.pushgateway_job,
                     protocol="victoriametrics_import",
                     status=response.status_code,
                 )
@@ -276,6 +287,16 @@ class PushgatewayClient:
                 url=import_url,
                 error=str(e),
                 error_type=type(e).__name__,
+                exc_info=e,
+            )
+            return False
+        except Exception as e:
+            logger.error(
+                "pushgateway_import_unexpected_error",
+                url=import_url,
+                error=str(e),
+                error_type=type(e).__name__,
+                exc_info=e,
             )
             return False
 
@@ -297,7 +318,7 @@ class PushgatewayClient:
             True if delete succeeded, False otherwise
         """
 
-        if not self._enabled or not self.settings.pushgateway_url:
+        if not self._enabled or not self.config.pushgateway_url:
             return False
 
         # Check circuit breaker before attempting operation
@@ -311,7 +332,7 @@ class PushgatewayClient:
 
         try:
             # Only standard pushgateway supports delete operation
-            if "/api/v1/write" in self.settings.pushgateway_url:
+            if "/api/v1/write" in self.config.pushgateway_url:
                 logger.warning("pushgateway_delete_not_supported_for_remote_write")
                 return False
             else:
@@ -328,37 +349,14 @@ class PushgatewayClient:
             self._circuit_breaker.record_failure()
             logger.error(
                 "pushgateway_delete_failed",
-                url=self.settings.pushgateway_url,
-                job=self.settings.pushgateway_job,
+                url=self.config.pushgateway_url,
+                job=self.config.pushgateway_job,
                 error=str(e),
                 error_type=type(e).__name__,
+                exc_info=e,
             )
             return False
 
     def is_enabled(self) -> bool:
         """Check if Pushgateway client is enabled and configured."""
-        return self._enabled and bool(self.settings.pushgateway_url)
-
-
-# Global pushgateway client instance
-_global_pushgateway_client: PushgatewayClient | None = None
-
-
-def get_pushgateway_client() -> PushgatewayClient:
-    """Get or create global pushgateway client instance."""
-    global _global_pushgateway_client
-
-    if _global_pushgateway_client is None:
-        # Import here to avoid circular imports
-        from ccproxy.config.settings import get_settings
-
-        settings = get_settings()
-        _global_pushgateway_client = PushgatewayClient(settings.observability)
-
-    return _global_pushgateway_client
-
-
-def reset_pushgateway_client() -> None:
-    """Reset global pushgateway client instance (mainly for testing)."""
-    global _global_pushgateway_client
-    _global_pushgateway_client = None
+        return self._enabled and bool(self.config.pushgateway_url)

ccproxy/plugins/metrics/routes.py

@@ -0,0 +1,107 @@
+"""Metrics endpoints for the metrics plugin."""
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Response
+
+from ccproxy.core.logging import get_plugin_logger
+
+from .collector import PrometheusMetrics
+
+
+logger = get_plugin_logger(__name__)
+
+
+def create_metrics_router(collector: PrometheusMetrics | None) -> APIRouter:
+    """Create metrics router with the given collector.
+
+    Args:
+        collector: Prometheus metrics collector instance
+
+    Returns:
+        FastAPI router with metrics endpoints
+    """
+    router = APIRouter(tags=["metrics"])
+
+    @router.get("/metrics")
+    async def get_prometheus_metrics() -> Response:
+        """Export metrics in Prometheus format.
+
+        This endpoint exposes operational metrics collected by the metrics plugin
+        for Prometheus scraping.
+
+        Returns:
+            Prometheus-formatted metrics text
+        """
+        if not collector or not collector.is_enabled():
+            raise HTTPException(
+                status_code=503,
+                detail="Metrics collection not enabled. Ensure prometheus-client is installed.",
+            )
+
+        try:
+            # Check if prometheus_client is available
+            try:
+                from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+            except ImportError as err:
+                raise HTTPException(
+                    status_code=503,
+                    detail="Prometheus client not available. Install with: pip install prometheus-client",
+                ) from err
+
+            # Generate prometheus format using the registry
+            from prometheus_client import REGISTRY
+
+            # Use the collector's registry or fall back to global
+            registry = (
+                collector.registry if collector.registry is not None else REGISTRY
+            )
+            prometheus_data = generate_latest(registry)
+
+            # Return the metrics data with proper content type
+            return Response(
+                content=prometheus_data,
+                media_type=CONTENT_TYPE_LATEST,
+                headers={
+                    "Cache-Control": "no-cache, no-store, must-revalidate",
+                    "Pragma": "no-cache",
+                    "Expires": "0",
+                },
+            )
+
+        except HTTPException:
+            raise
+        except ImportError as e:
+            logger.error(
+                "prometheus_import_error",
+                error=str(e),
+                exc_info=e,
+            )
+            raise HTTPException(
+                status_code=503, detail=f"Prometheus dependencies missing: {str(e)}"
+            ) from e
+        except Exception as e:
+            logger.error(
+                "metrics_generation_error",
+                error=str(e),
+                exc_info=e,
+            )
+            raise HTTPException(
+                status_code=500,
+                detail=f"Failed to generate Prometheus metrics: {str(e)}",
+            ) from e
+
+    @router.get("/metrics/health")
+    async def metrics_health() -> dict[str, Any]:
+        """Get metrics system health status.
+
+        Returns:
+            Health status of the metrics collection system
+        """
+        return {
+            "status": "healthy" if collector and collector.is_enabled() else "disabled",
+            "prometheus_enabled": collector.is_enabled() if collector else False,
+            "namespace": collector.namespace if collector else None,
+        }
+
+    return router

ccproxy/plugins/metrics/tasks.py

@@ -0,0 +1,117 @@
+"""Scheduled tasks for the metrics plugin."""
+
+from typing import Any
+
+from ccproxy.core.logging import get_plugin_logger
+from ccproxy.scheduler.tasks import BaseScheduledTask
+
+from .pushgateway import PushgatewayClient
+
+
+logger = get_plugin_logger(__name__)
+
+
+class PushgatewayTask(BaseScheduledTask):
+    """Task for pushing metrics to Pushgateway periodically."""
+
+    def __init__(
+        self,
+        name: str,
+        interval_seconds: float,
+        enabled: bool = True,
+        max_backoff_seconds: float = 300.0,
+        metrics_config: Any | None = None,
+        metrics_hook: Any | None = None,
+    ):
+        """
+        Initialize pushgateway task.
+
+        Args:
+            name: Task name
+            interval_seconds: Interval between pushgateway operations
+            enabled: Whether task is enabled
+            max_backoff_seconds: Maximum backoff delay for failures
+            metrics_config: Metrics plugin configuration
+            metrics_hook: Metrics hook instance for getting collector
+        """
+        super().__init__(
+            name=name,
+            interval_seconds=interval_seconds,
+            enabled=enabled,
+            max_backoff_seconds=max_backoff_seconds,
+        )
+        self._metrics_config = metrics_config
+        self._metrics_hook = metrics_hook
+        self._pushgateway_client: PushgatewayClient | None = None
+
+    async def setup(self) -> None:
+        """Initialize pushgateway client for operations."""
+        try:
+            if self._metrics_config and self._metrics_hook:
+                self._pushgateway_client = PushgatewayClient(self._metrics_config)
+                logger.debug(
+                    "pushgateway_task_setup_complete",
+                    task_name=self.name,
+                    url=self._metrics_config.pushgateway_url,
+                    job=self._metrics_config.pushgateway_job,
+                )
+            else:
+                logger.warning(
+                    "pushgateway_task_setup_missing_config",
+                    task_name=self.name,
+                    has_config=self._metrics_config is not None,
+                    has_hook=self._metrics_hook is not None,
+                )
+        except Exception as e:
+            logger.error(
+                "pushgateway_task_setup_failed",
+                task_name=self.name,
+                error=str(e),
+                error_type=type(e).__name__,
+                exc_info=e,
+            )
+            raise
+
+    async def run(self) -> bool:
+        """Execute pushgateway metrics push."""
+        try:
+            if not self._pushgateway_client or not self._metrics_hook:
+                logger.warning(
+                    "pushgateway_no_client_or_hook",
+                    task_name=self.name,
+                    has_client=self._pushgateway_client is not None,
+                    has_hook=self._metrics_hook is not None,
+                )
+                return False
+
+            if not self._pushgateway_client.is_enabled():
+                logger.debug("pushgateway_disabled", task_name=self.name)
+                return True  # Not an error, just disabled
+
+            # Get the metrics collector and push metrics
+            collector = self._metrics_hook.get_collector()
+            if not collector:
+                logger.warning("pushgateway_no_collector", task_name=self.name)
+                return False
+
+            # Push metrics using the client
+            success = self._pushgateway_client.push_metrics(
+                collector.get_registry(), method="push"
+            )
+
+            if success:
+                logger.debug("pushgateway_push_success", task_name=self.name)
+            else:
+                logger.warning("pushgateway_push_failed", task_name=self.name)
+
+            return success
+
+        except Exception as e:
+            logger.error(
+                "pushgateway_task_error",
+                task_name=self.name,
+                error=str(e),
+                error_type=type(e).__name__,
+                exc_info=e,
+            )
+            return False

ccproxy/plugins/oauth_claude/README.md

@@ -0,0 +1,35 @@
+# OAuth Claude Plugin
+
+Standalone OAuth provider for managing Claude API access tokens.
+
+## Highlights
+- Implements `ClaudeOAuthProvider` for authorization-code and refresh flows
+- Integrates with the auth runtime to expose a reusable auth manager
+- Shares detection utilities to diagnose CLI and token availability
+
+## Configuration
+- `ClaudeOAuthConfig` sets client credentials, scopes, and storage paths
+- Works alongside `claude_api` or credential balancer powered providers
+- Generate defaults with `python3 scripts/generate_config_from_model.py \
+  --format toml --plugin oauth_claude --config-class ClaudeOAuthConfig`
+
+```toml
+[plugins.oauth_claude]
+# enabled = true
+# base_url = "https://console.anthropic.com"
+# token_url = "https://console.anthropic.com/v1/oauth/token"
+# authorize_url = "https://claude.ai/oauth/authorize"
+# profile_url = "https://api.anthropic.com/api/oauth/profile"
+# client_id = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
+# redirect_uri = "http://localhost:35593/callback"
+# scopes = ["org:create_api_key", "user:profile", "user:inference"]
+# request_timeout = 30
+# callback_timeout = 300
+# callback_port = 35593
+# use_pkce = true
+```
+
+## Related Components
+- `provider.py`: OAuth implementation and token storage helpers
+- `plugin.py`: runtime wiring for auth-only plugin
+- `config.py`: settings model for Claude OAuth parameters

ccproxy/plugins/oauth_claude/__init__.py

@@ -0,0 +1,14 @@
+"""OAuth Claude plugin for standalone Claude OAuth authentication."""
+
+from .client import ClaudeOAuthClient
+from .config import ClaudeOAuthConfig
+from .provider import ClaudeOAuthProvider
+from .storage import ClaudeOAuthStorage
+
+
+__all__ = [
+    "ClaudeOAuthClient",
+    "ClaudeOAuthConfig",
+    "ClaudeOAuthProvider",
+    "ClaudeOAuthStorage",
+]