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

ccproxy/core/plugins/hooks/__init__.py

@@ -0,0 +1,30 @@
+"""Hook system for CCProxy.
+
+This package provides a flexible, event-driven hook system that enables
+metrics collection, analytics, logging, and custom provider behaviors
+without modifying core code.
+
+Key components:
+- HookEvent: Enumeration of all supported events
+- HookContext: Context data passed to hooks
+- Hook: Protocol for hook implementations
+- HookRegistry: Registry for managing hooks
+- HookManager: Manager for executing hooks
+- BackgroundHookThreadManager: Background thread manager for async hook execution
+"""
+
+from .base import Hook, HookContext
+from .events import HookEvent
+from .manager import HookManager
+from .registry import HookRegistry
+from .thread_manager import BackgroundHookThreadManager
+
+
+__all__ = [
+    "Hook",
+    "HookContext",
+    "HookEvent",
+    "HookManager",
+    "HookRegistry",
+    "BackgroundHookThreadManager",
+]

ccproxy/core/plugins/hooks/base.py

@@ -0,0 +1,58 @@
+"""Core interfaces for the hook system."""
+
+from collections.abc import Awaitable
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Protocol
+
+from fastapi import Request, Response
+
+from .events import HookEvent
+
+
+@dataclass
+class HookContext:
+    """Context passed to all hooks"""
+
+    event: HookEvent
+    timestamp: datetime
+    data: dict[str, Any]
+    metadata: dict[str, Any]
+
+    # Request-specific (optional)
+    request: Request | None = None
+    response: Response | None = None
+
+    # Provider-specific (optional)
+    provider: str | None = None
+    plugin: str | None = None
+
+    # Error context (optional)
+    error: Exception | None = None
+
+
+class Hook(Protocol):
+    """Base hook protocol"""
+
+    def __call__(self, context: HookContext) -> None | Awaitable[None]:
+        """Execute hook with context (can be async or sync)"""
+        ...
+
+    @property
+    def name(self) -> str:
+        """Hook name for debugging"""
+        ...
+
+    @property
+    def events(self) -> list[HookEvent]:
+        """Events this hook listens to"""
+        ...
+
+    @property
+    def priority(self) -> int:
+        """Hook execution priority (0-1000, lower executes first).
+
+        Default is 500 (middle priority) for backward compatibility.
+        See HookLayer enum for standard priority values.
+        """
+        return 500

ccproxy/core/plugins/hooks/events.py

@@ -0,0 +1,46 @@
+"""Event definitions for the hook system."""
+
+from enum import Enum
+
+
+class HookEvent(str, Enum):
+    """Event types that can trigger hooks"""
+
+    # Application Lifecycle
+    APP_STARTUP = "app.startup"
+    APP_SHUTDOWN = "app.shutdown"
+    APP_READY = "app.ready"
+
+    # Request Lifecycle
+    REQUEST_STARTED = "request.started"
+    REQUEST_COMPLETED = "request.completed"
+    REQUEST_FAILED = "request.failed"
+
+    # Provider Integration
+    PROVIDER_REQUEST_PREPARED = "provider.request.prepared"  # Before sending upstream; payload mutable via hooks
+    PROVIDER_REQUEST_SENT = "provider.request.sent"
+    PROVIDER_RESPONSE_RECEIVED = "provider.response.received"
+    PROVIDER_ERROR = "provider.error"
+    PROVIDER_STREAM_START = "provider.stream.start"
+    PROVIDER_STREAM_CHUNK = "provider.stream.chunk"
+    PROVIDER_STREAM_END = "provider.stream.end"
+
+    # Plugin Management
+    PLUGIN_LOADED = "plugin.loaded"
+    PLUGIN_UNLOADED = "plugin.unloaded"
+    PLUGIN_ERROR = "plugin.error"
+
+    # HTTP Client Operations
+    HTTP_REQUEST = "http.request"
+    HTTP_RESPONSE = "http.response"
+    HTTP_ERROR = "http.error"
+
+    # OAuth Operations
+    OAUTH_TOKEN_REQUEST = "oauth.token.request"
+    OAUTH_TOKEN_RESPONSE = "oauth.token.response"
+    OAUTH_REFRESH_REQUEST = "oauth.refresh.request"
+    OAUTH_REFRESH_RESPONSE = "oauth.refresh.response"
+    OAUTH_ERROR = "oauth.error"
+
+    # Custom Events
+    CUSTOM_EVENT = "custom.event"

ccproxy/core/plugins/hooks/implementations/__init__.py

@@ -0,0 +1,16 @@
+"""Built-in hook implementations for CCProxy.
+
+This module contains standard hook implementations for common use cases:
+- MetricsHook: Prometheus metrics collection
+- LoggingHook: Structured logging
+- AnalyticsHook: Analytics data collection
+- AccessLoggingHook: Access logging (replaces AccessLogMiddleware)
+- ContentLoggingHook: Content logging for hooks-based logging
+- StreamingCaptureHook: Streaming response capture
+- HTTPTracerHook: Core HTTP request/response tracing
+"""
+
+from .http_tracer import HTTPTracerHook
+
+
+__all__: list[str] = ["HTTPTracerHook"]

ccproxy/core/plugins/hooks/implementations/formatters/__init__.py

@@ -0,0 +1,11 @@
+"""Core formatters for HTTP request/response logging.
+
+These formatters are used by the core HTTP tracer hook and can be shared
+across different plugins that need HTTP logging capabilities.
+"""
+
+from .json import JSONFormatter
+from .raw import RawHTTPFormatter
+
+
+__all__ = ["JSONFormatter", "RawHTTPFormatter"]