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

ccproxy/core/plugins/hooks/registry.py

@@ -0,0 +1,139 @@
+"""Central registry for all hooks"""
+
+from collections import defaultdict
+from typing import Any
+
+import structlog
+from sortedcontainers import SortedList  # type: ignore[import-untyped]
+
+from .base import Hook
+from .events import HookEvent
+
+
+class HookRegistry:
+    """Central registry for all hooks with priority-based ordering."""
+
+    def __init__(self) -> None:
+        # Use SortedList for automatic priority ordering
+        # Key function sorts by (priority, registration_order)
+        self._hooks: dict[HookEvent, Any] = defaultdict(
+            lambda: SortedList(
+                key=lambda h: (
+                    getattr(h, "priority", 500),
+                    self._registration_order.get(h, 0),
+                )
+            )
+        )
+        self._registration_order: dict[Hook, int] = {}
+        self._next_order = 0
+        self._logger = structlog.get_logger(__name__)
+        # Batch logging for registration/unregistration
+        self._pending_registrations: list[tuple[str, str, int]] = []
+        self._pending_unregistrations: list[tuple[str, str]] = []
+
+    def register(self, hook: Hook) -> None:
+        """Register a hook for its events with priority ordering"""
+        priority = getattr(
+            hook, "priority", 500
+        )  # Default priority for backward compatibility
+
+        # Track registration order for stable sorting
+        if hook not in self._registration_order:
+            self._registration_order[hook] = self._next_order
+            self._next_order += 1
+
+        events_registered = []
+        for event in hook.events:
+            self._hooks[event].add(hook)
+            event_name = event.value if hasattr(event, "value") else str(event)
+            events_registered.append(event_name)
+            # Log individual registrations at DEBUG level
+            # self._logger.debug(
+            #     "hook_registered",
+            #     name=hook.name,
+            #     hook_event=event_name,
+            #     priority=priority,
+            # )
+
+        # Log summary at DEBUG; a global summary will be logged elsewhere at INFO
+        if len(events_registered) > 0:
+            self._logger.debug(
+                "hook_registered",
+                name=hook.name,
+                events=events_registered,
+                event_count=len(events_registered),
+                priority=priority,
+            )
+
+    def unregister(self, hook: Hook) -> None:
+        """Remove a hook from all events"""
+        events_unregistered = []
+        for event in hook.events:
+            try:
+                self._hooks[event].remove(hook)
+                event_name = event.value if hasattr(event, "value") else str(event)
+                events_unregistered.append(event_name)
+                # Log individual unregistrations at DEBUG level
+                # self._logger.debug(
+                #     "hook_unregistered",
+                #     name=hook.name,
+                #     hook_event=event_name,
+                # )
+            except ValueError:
+                pass  # Hook not in list, ignore
+
+        # Log summary at INFO level only if multiple events
+        if len(events_unregistered) > 1:
+            self._logger.info(
+                "hook_unregistered_summary",
+                name=hook.name,
+                events=events_unregistered,
+                event_count=len(events_unregistered),
+            )
+        elif events_unregistered:
+            # Single event - log at DEBUG level to reduce verbosity
+            self._logger.debug(
+                "hook_unregistered_single",
+                name=hook.name,
+                hook_event=events_unregistered[0],
+            )
+
+        # Clean up registration order tracking
+        if hook in self._registration_order:
+            del self._registration_order[hook]
+
+    def get(self, event: HookEvent) -> list[Hook]:
+        """Get all hooks for an event in priority order"""
+        return list(self._hooks.get(event, []))
+
+    def list(self) -> dict[str, list[dict[str, Any]]]:
+        """Get summary of all registered hooks organized by event.
+
+        Returns:
+            Dictionary mapping event names to lists of hook info
+        """
+        summary = {}
+        for event, hooks in self._hooks.items():
+            event_name = event.value if hasattr(event, "value") else str(event)
+            summary[event_name] = [
+                {
+                    "name": hook.name,
+                    "priority": getattr(hook, "priority", 500),
+                }
+                for hook in hooks
+            ]
+        return summary
+
+    def has(self, event: HookEvent) -> bool:
+        """Check if any hook is registered for the event."""
+        hooks = self._hooks.get(event)
+        return bool(hooks and len(hooks) > 0)
+
+    def clear(self) -> None:
+        """Clear all registered hooks and reset ordering (testing or shutdown)."""
+        self._hooks.clear()
+        self._registration_order.clear()
+        self._next_order = 0
+
+
+# Module-level accessor intentionally omitted.

ccproxy/core/plugins/hooks/thread_manager.py

@@ -0,0 +1,203 @@
+"""Background thread manager for async hook execution."""
+
+import asyncio
+import threading
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+import structlog
+
+from .base import Hook, HookContext
+
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass
+class HookTask:
+    """Represents a hook execution task."""
+
+    context: HookContext
+    task_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+
+class BackgroundHookThreadManager:
+    """Manages a dedicated async thread for hook execution."""
+
+    def __init__(self) -> None:
+        """Initialize the background thread manager."""
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._queue: asyncio.Queue[tuple[HookTask, Any]] | None = None
+        self._shutdown_event: asyncio.Event | None = None
+        self._running = False
+        self._logger = logger.bind(component="background_hook_thread")
+        # Signals when the background loop and its resources are ready
+        self._ready_event: threading.Event | None = None
+
+    def start(self) -> None:
+        """Start the background thread with its own event loop."""
+        if self._running:
+            return
+
+        # Create readiness event so callers can safely enqueue without sleeps
+        self._ready_event = threading.Event()
+
+        self._thread = threading.Thread(
+            target=self._run_background_loop, name="hook-background-thread", daemon=True
+        )
+        self._thread.start()
+
+        # Block briefly until the background loop has initialized its resources
+        if self._ready_event and not self._ready_event.wait(timeout=1.0):
+            self._logger.warning("background_hook_thread_startup_timeout")
+        self._running = True
+
+        self._logger.debug("background_hook_thread_started")
+
+    def stop(self, timeout: float = 5.0) -> None:
+        """Gracefully shutdown the background thread."""
+        if not self._running:
+            return
+
+        self._logger.debug("stopping_background_hook_thread")
+
+        # Signal shutdown to the background loop
+        if self._loop and self._shutdown_event:
+            self._loop.call_soon_threadsafe(self._shutdown_event.set)
+
+        # Wait for thread to complete
+        if self._thread:
+            self._thread.join(timeout=timeout)
+            if self._thread.is_alive():
+                self._logger.warning("background_thread_shutdown_timeout")
+
+        self._running = False
+        self._loop = None
+        self._thread = None
+        self._queue = None
+        self._shutdown_event = None
+        self._ready_event = None
+
+        self._logger.debug("background_hook_thread_stopped")
+
+    def emit_async(self, context: HookContext, registry: Any) -> None:
+        """Queue a hook task for background execution.
+
+        Args:
+            context: Hook context to execute
+            registry: Hook registry to get hooks from
+        """
+        if not self._running:
+            self.start()
+
+        if not self._loop or not self._queue:
+            self._logger.warning("background_thread_not_ready_dropping_task")
+            return
+
+        task = HookTask(context=context)
+
+        # Add task to queue in a thread-safe way
+        try:
+            self._loop.call_soon_threadsafe(self._add_task_to_queue, task, registry)
+        except Exception as e:
+            self._logger.error("failed_to_queue_hook_task", error=str(e))
+
+    def _add_task_to_queue(self, task: HookTask, registry: Any) -> None:
+        """Add task to queue (called from background thread)."""
+        if self._queue:
+            try:
+                self._queue.put_nowait((task, registry))
+            except asyncio.QueueFull:
+                self._logger.warning("hook_task_queue_full_dropping_task")
+
+    def _run_background_loop(self) -> None:
+        """Run the background event loop for hook processing."""
+        try:
+            # Create new event loop for this thread
+            self._loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self._loop)
+
+            # Create queue and shutdown event
+            self._queue = asyncio.Queue[tuple[HookTask, Any]](maxsize=1000)
+            self._shutdown_event = asyncio.Event()
+
+            # Signal to the starter that we're ready to accept tasks
+            if self._ready_event:
+                self._ready_event.set()
+
+            # Run the processing loop
+            self._loop.run_until_complete(self._process_tasks())
+        except Exception as e:
+            logger.error("background_hook_thread_error", error=str(e))
+        finally:
+            if self._loop:
+                self._loop.close()
+
+    async def _process_tasks(self) -> None:
+        """Main task processing loop."""
+        self._logger.debug("background_hook_processor_started")
+
+        while self._shutdown_event and not self._shutdown_event.is_set():
+            try:
+                # Wait for either a task or shutdown signal
+                if not self._queue:
+                    break
+                task_data = await asyncio.wait_for(self._queue.get(), timeout=0.1)
+
+                task, registry = task_data
+                await self._execute_task(task, registry)
+
+            except TimeoutError:
+                # Normal timeout, continue loop
+                continue
+            except Exception as e:
+                self._logger.error("hook_task_processing_error", error=str(e))
+
+        self._logger.debug("background_hook_processor_stopped")
+
+    async def _execute_task(self, task: HookTask, registry: Any) -> None:
+        """Execute a single hook task.
+
+        Args:
+            task: The hook task to execute
+            registry: Hook registry to get hooks from
+        """
+        try:
+            hooks = registry.get(task.context.event)
+            if not hooks:
+                return
+
+            # Execute all hooks for this event
+            for hook in hooks:
+                try:
+                    await self._execute_hook(hook, task.context)
+                except Exception as e:
+                    self._logger.error(
+                        "background_hook_execution_failed",
+                        hook=hook.name,
+                        event_type=task.context.event.value
+                        if hasattr(task.context.event, "value")
+                        else str(task.context.event),
+                        error=str(e),
+                        task_id=task.task_id,
+                    )
+        except Exception as e:
+            self._logger.error(
+                "hook_task_execution_failed", error=str(e), task_id=task.task_id
+            )
+
+    async def _execute_hook(self, hook: Hook, context: HookContext) -> None:
+        """Execute a single hook with proper async/sync handling.
+
+        Args:
+            hook: The hook to execute
+            context: The context to pass to the hook
+        """
+        result = hook(context)
+        if asyncio.iscoroutine(result):
+            await result
+        # If result is None, it was a sync hook and we're done

ccproxy/core/plugins/hooks/types.py

@@ -0,0 +1,22 @@
+"""Shared hook typing for headers to support dict or dict-like inputs."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Protocol
+
+
+class HookHeaders(Protocol):
+    """Protocol for header-like objects passed through hooks.
+
+    Implementations must preserve order when iterated. Plain dicts and
+    other dict-like objects can conform to this via duck typing.
+    """
+
+    def items(self) -> Iterable[tuple[str, str]]:
+        """Return an iterable of (name, value) pairs in order."""
+        ...
+
+    def to_dict(self) -> dict[str, str]:  # pragma: no cover - protocol
+        """Return a dict view (last occurrence wins per name)."""
+        ...