ccproxy-api 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

ccproxy/claude_sdk/exceptions.py

@@ -0,0 +1,16 @@
+"""Claude SDK exceptions."""
+
+
+class ClaudeSDKError(Exception):
+    """Base Claude SDK error."""
+
+    pass
+
+
+class StreamTimeoutError(ClaudeSDKError):
+    """Stream timeout error when no SDK message is received within timeout."""
+
+    def __init__(self, message: str, session_id: str, timeout_seconds: float):
+        super().__init__(message)
+        self.session_id = session_id
+        self.timeout_seconds = timeout_seconds

ccproxy/claude_sdk/manager.py

@@ -0,0 +1,219 @@
+"""
+Claude SDK Session Manager - Pure dependency injection architecture.
+
+This module provides a SessionManager class that encapsulates session pool lifecycle
+management using dependency injection patterns without any global state.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+
+# Type alias for metrics factory function
+from typing import Any, TypeAlias
+
+import structlog
+from claude_code_sdk import ClaudeCodeOptions
+
+from ccproxy.claude_sdk.session_client import SessionClient
+from ccproxy.claude_sdk.session_pool import SessionPool
+from ccproxy.config.settings import Settings
+from ccproxy.core.errors import ClaudeProxyError
+
+
+logger = structlog.get_logger(__name__)
+
+
+MetricsFactory: TypeAlias = Callable[[], Any | None]
+
+
+class SessionManager:
+    """Manages the lifecycle of session-based Claude SDK clients with dependency injection."""
+
+    def __init__(
+        self,
+        settings: Settings,
+        metrics_factory: MetricsFactory | None = None,
+    ) -> None:
+        """Initialize SessionManager with optional settings and metrics factory.
+
+        Args:
+            settings: Optional settings containing session pool configuration
+            metrics_factory: Optional callable that returns a metrics instance.
+                           If None, no metrics will be used.
+        """
+        import structlog
+
+        logger = structlog.get_logger(__name__)
+
+        self._settings = settings
+        self._session_pool: SessionPool | None = None
+        self._lock = asyncio.Lock()
+        self._metrics_factory = metrics_factory
+
+        # Initialize session pool if enabled
+        session_pool_enabled = self._should_enable_session_pool()
+        logger.debug(
+            "session_manager_init",
+            has_settings=bool(settings),
+            has_metrics_factory=bool(metrics_factory),
+            session_pool_enabled=session_pool_enabled,
+        )
+
+        if session_pool_enabled:
+            self._session_pool = SessionPool(settings.claude.sdk_session_pool)
+            logger.info(
+                "session_manager_session_pool_initialized",
+                session_ttl=self._session_pool.config.session_ttl,
+                max_sessions=self._session_pool.config.max_sessions,
+                cleanup_interval=self._session_pool.config.cleanup_interval,
+            )
+        else:
+            logger.debug(
+                "session_manager_session_pool_skipped",
+                reason="session_pool_disabled_in_settings",
+            )
+
+    def _should_enable_session_pool(self) -> bool:
+        """Check if session pool should be enabled."""
+        import structlog
+
+        logger = structlog.get_logger(__name__)
+
+        if not self._settings:
+            logger.debug("session_pool_check", decision="no_settings", enabled=False)
+            return False
+
+        if not hasattr(self._settings, "claude"):
+            logger.debug(
+                "session_pool_check", decision="no_claude_settings", enabled=False
+            )
+            return False
+
+        session_pool_settings = getattr(self._settings.claude, "sdk_session_pool", None)
+        if not session_pool_settings:
+            logger.debug(
+                "session_pool_check", decision="no_session_pool_settings", enabled=False
+            )
+            return False
+
+        enabled = getattr(session_pool_settings, "enabled", False)
+        logger.debug("session_pool_check", decision="settings_check", enabled=enabled)
+        return enabled
+
+    async def start(self) -> None:
+        """Start the session manager and session pool."""
+        if self._session_pool:
+            await self._session_pool.start()
+
+    async def shutdown(self) -> None:
+        """Gracefully shuts down the session pool.
+
+        This method is idempotent - calling it multiple times is safe.
+        """
+        async with self._lock:
+            # Close session pool
+            if self._session_pool:
+                await self._session_pool.stop()
+                self._session_pool = None
+
+    async def get_session_client(
+        self,
+        session_id: str,
+        options: ClaudeCodeOptions,
+    ) -> SessionClient:
+        """Get session-aware client."""
+
+        logger = structlog.get_logger(__name__)
+        logger.debug(
+            "session_manager_get_session_client",
+            session_id=session_id,
+            has_session_pool=bool(self._session_pool),
+        )
+
+        if not self._session_pool:
+            logger.error(
+                "session_manager_session_pool_unavailable",
+                session_id=session_id,
+            )
+            raise ClaudeProxyError(
+                message="Session pool not available",
+                error_type="configuration_error",
+                status_code=500,
+            )
+
+        return await self._session_pool.get_session_client(session_id, options)
+
+    async def interrupt_session(self, session_id: str) -> bool:
+        """Interrupt a specific session due to client disconnection.
+
+        Args:
+            session_id: The session ID to interrupt
+
+        Returns:
+            True if session was found and interrupted, False otherwise
+        """
+        if not self._session_pool:
+            logger.warning(
+                "session_manager_interrupt_session_no_pool",
+                session_id=session_id,
+            )
+            return False
+
+        logger.info(
+            "session_manager_interrupt_session",
+            session_id=session_id,
+        )
+
+        return await self._session_pool.interrupt_session(session_id)
+
+    async def interrupt_all_sessions(self) -> int:
+        """Interrupt all active sessions (for shutdown or emergency cleanup).
+
+        Returns:
+            Number of sessions that were interrupted
+        """
+        if not self._session_pool:
+            logger.warning("session_manager_interrupt_all_no_pool")
+            return 0
+
+        logger.info("session_manager_interrupt_all_sessions")
+        return await self._session_pool.interrupt_all_sessions()
+
+    async def get_session_pool_stats(self) -> dict[str, Any]:
+        """Get session pool statistics."""
+        if not self._session_pool:
+            return {"enabled": False}
+        return await self._session_pool.get_stats()
+
+    def reset_for_testing(self) -> None:
+        """Synchronous reset for test environments.
+
+        Warning:
+            This method should only be used in tests. It does not properly
+            shut down the session pool - use shutdown() for production code.
+        """
+        self._session_pool = None
+
+    @property
+    def is_active(self) -> bool:
+        """Check if the session manager has an active session pool."""
+        return self._session_pool is not None
+
+    async def has_session_pool(self) -> bool:
+        """Check if session pool is available and enabled."""
+        return self._session_pool is not None and self._session_pool.config.enabled
+
+    async def has_session(self, session_id: str) -> bool:
+        """Check if a session exists in the session pool.
+
+        Args:
+            session_id: The session ID to check
+
+        Returns:
+            True if session exists, False otherwise
+        """
+        if not self._session_pool:
+            return False
+        return await self._session_pool.has_session(session_id)

ccproxy/claude_sdk/message_queue.py

@@ -0,0 +1,342 @@
+"""Message queue system for broadcasting SDK messages to multiple listeners."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import time
+import uuid
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, TypeVar
+
+import structlog
+
+
+logger = structlog.get_logger(__name__)
+
+T = TypeVar("T")
+
+
+class MessageType(str, Enum):
+    """Types of messages that can be sent through the queue."""
+
+    DATA = "data"
+    ERROR = "error"
+    COMPLETE = "complete"
+    SHUTDOWN = "shutdown"
+
+
+@dataclass
+class QueueMessage:
+    """Message wrapper for queue communication."""
+
+    type: MessageType
+    data: Any = None
+    error: Exception | None = None
+    timestamp: float = field(default_factory=time.time)
+
+
+class QueueListener:
+    """Individual listener that consumes messages from the queue."""
+
+    def __init__(self, listener_id: str | None = None):
+        """Initialize a queue listener.
+
+        Args:
+            listener_id: Optional ID for the listener, generated if not provided
+        """
+        self.listener_id = listener_id or str(uuid.uuid4())
+        self._queue: asyncio.Queue[QueueMessage] = asyncio.Queue()
+        self._closed = False
+        self._created_at = time.time()
+
+    async def get_message(self) -> QueueMessage:
+        """Get the next message from the queue.
+
+        Returns:
+            The next queued message
+
+        Raises:
+            asyncio.QueueEmpty: If queue is empty and closed
+        """
+        if self._closed and self._queue.empty():
+            raise asyncio.QueueEmpty("Listener is closed")
+
+        return await self._queue.get()
+
+    async def put_message(self, message: QueueMessage) -> None:
+        """Put a message into this listener's queue.
+
+        Args:
+            message: Message to queue
+        """
+        if not self._closed:
+            await self._queue.put(message)
+
+    def close(self) -> None:
+        """Close the listener, preventing new messages."""
+        self._closed = True
+        # Put a shutdown message to unblock any waiting consumers
+        with contextlib.suppress(asyncio.QueueFull):
+            self._queue.put_nowait(QueueMessage(type=MessageType.SHUTDOWN))
+
+    @property
+    def is_closed(self) -> bool:
+        """Check if the listener is closed."""
+        return self._closed
+
+    @property
+    def queue_size(self) -> int:
+        """Get the current queue size."""
+        return self._queue.qsize()
+
+    async def __aiter__(self) -> AsyncIterator[Any]:
+        """Async iterator interface for consuming messages."""
+        while True:
+            try:
+                message = await self.get_message()
+
+                if message.type == MessageType.SHUTDOWN:
+                    break
+                elif message.type == MessageType.ERROR:
+                    if message.error:
+                        raise message.error
+                    break
+                elif message.type == MessageType.COMPLETE:
+                    break
+                else:
+                    yield message.data
+            except asyncio.QueueEmpty:
+                break
+
+
+class MessageQueue:
+    """Message queue that broadcasts to multiple listeners with discard logic."""
+
+    def __init__(self, max_listeners: int = 100):
+        """Initialize the message queue.
+
+        Args:
+            max_listeners: Maximum number of concurrent listeners
+        """
+        self._listeners: dict[str, QueueListener] = {}
+        self._lock = asyncio.Lock()
+        self._max_listeners = max_listeners
+        self._total_messages_received = 0
+        self._total_messages_delivered = 0
+        self._total_messages_discarded = 0
+        self._created_at = time.time()
+
+    async def create_listener(self, listener_id: str | None = None) -> QueueListener:
+        """Create a new listener for this queue.
+
+        Args:
+            listener_id: Optional ID for the listener
+
+        Returns:
+            A new QueueListener instance
+
+        Raises:
+            RuntimeError: If max listeners exceeded
+        """
+        async with self._lock:
+            if len(self._listeners) >= self._max_listeners:
+                raise RuntimeError(
+                    f"Maximum listeners ({self._max_listeners}) exceeded"
+                )
+
+            listener = QueueListener(listener_id)
+            self._listeners[listener.listener_id] = listener
+
+            logger.debug(
+                "message_queue_listener_added",
+                listener_id=listener.listener_id,
+                active_listeners=len(self._listeners),
+            )
+
+            return listener
+
+    async def remove_listener(self, listener_id: str) -> None:
+        """Remove a listener from the queue.
+
+        Args:
+            listener_id: ID of the listener to remove
+        """
+        async with self._lock:
+            if listener_id in self._listeners:
+                listener = self._listeners.pop(listener_id)
+                listener.close()
+
+                logger.debug(
+                    "message_queue_listener_removed",
+                    listener_id=listener_id,
+                    active_listeners=len(self._listeners),
+                    listener_queue_size=listener.queue_size,
+                )
+
+    async def has_listeners(self) -> bool:
+        """Check if any active listeners exist.
+
+        Returns:
+            True if at least one listener is registered
+        """
+        async with self._lock:
+            return len(self._listeners) > 0
+
+    async def get_listener_count(self) -> int:
+        """Get the current number of active listeners.
+
+        Returns:
+            Number of active listeners
+        """
+        async with self._lock:
+            return len(self._listeners)
+
+    async def broadcast(self, message: Any) -> int:
+        """Broadcast a message to all active listeners.
+
+        Args:
+            message: The message to broadcast
+
+        Returns:
+            Number of listeners that received the message
+        """
+        self._total_messages_received += 1
+
+        async with self._lock:
+            if not self._listeners:
+                self._total_messages_discarded += 1
+                logger.debug(
+                    "message_queue_discard",
+                    reason="no_listeners",
+                    message_type=type(message).__name__,
+                )
+                return 0
+
+            # Create queue message
+            queue_msg = QueueMessage(type=MessageType.DATA, data=message)
+
+            # Broadcast to all listeners
+            delivered_count = 0
+            for listener_id, listener in list(self._listeners.items()):
+                if listener.is_closed:
+                    # Remove closed listeners
+                    self._listeners.pop(listener_id, None)
+                    continue
+
+                try:
+                    # Use put_nowait to avoid blocking
+                    listener._queue.put_nowait(queue_msg)
+                    delivered_count += 1
+                except asyncio.QueueFull:
+                    logger.warning(
+                        "message_queue_listener_full",
+                        listener_id=listener_id,
+                        queue_size=listener.queue_size,
+                    )
+
+            self._total_messages_delivered += delivered_count
+
+            if delivered_count == 0:
+                self._total_messages_discarded += 1
+
+            logger.debug(
+                "message_queue_broadcast",
+                listeners_count=len(self._listeners),
+                delivered_count=delivered_count,
+                message_type=type(message).__name__,
+            )
+
+            return delivered_count
+
+    async def broadcast_error(self, error: Exception) -> None:
+        """Broadcast an error to all listeners.
+
+        Args:
+            error: The error to broadcast
+        """
+        async with self._lock:
+            queue_msg = QueueMessage(type=MessageType.ERROR, error=error)
+
+            for listener in self._listeners.values():
+                if not listener.is_closed:
+                    with contextlib.suppress(asyncio.QueueFull):
+                        listener._queue.put_nowait(queue_msg)
+
+            logger.debug(
+                "message_queue_broadcast_error",
+                error_type=type(error).__name__,
+                listeners_count=len(self._listeners),
+            )
+
+    async def broadcast_complete(self) -> None:
+        """Broadcast completion signal to all listeners."""
+        async with self._lock:
+            queue_msg = QueueMessage(type=MessageType.COMPLETE)
+
+            for listener in self._listeners.values():
+                if not listener.is_closed:
+                    with contextlib.suppress(asyncio.QueueFull):
+                        listener._queue.put_nowait(queue_msg)
+
+            logger.debug(
+                "message_queue_broadcast_complete",
+                listeners_count=len(self._listeners),
+            )
+
+    async def broadcast_shutdown(self) -> None:
+        """Broadcast shutdown signal to all listeners (for interrupts)."""
+        async with self._lock:
+            queue_msg = QueueMessage(type=MessageType.SHUTDOWN)
+
+            for listener in self._listeners.values():
+                if not listener.is_closed:
+                    with contextlib.suppress(asyncio.QueueFull):
+                        listener._queue.put_nowait(queue_msg)
+
+            logger.debug(
+                "message_queue_broadcast_shutdown",
+                listeners_count=len(self._listeners),
+                message="Shutdown signal sent to all listeners due to interrupt",
+            )
+
+    async def close(self) -> None:
+        """Close the message queue and all listeners."""
+        async with self._lock:
+            # Send shutdown to all listeners
+            queue_msg = QueueMessage(type=MessageType.SHUTDOWN)
+
+            for listener in self._listeners.values():
+                listener.close()
+
+            self._listeners.clear()
+
+            logger.debug(
+                "message_queue_closed",
+                total_messages_received=self._total_messages_received,
+                total_messages_delivered=self._total_messages_delivered,
+                total_messages_discarded=self._total_messages_discarded,
+                lifetime_seconds=time.time() - self._created_at,
+            )
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get queue statistics.
+
+        Returns:
+            Dictionary of queue statistics
+        """
+        return {
+            "active_listeners": len(self._listeners),
+            "max_listeners": self._max_listeners,
+            "total_messages_received": self._total_messages_received,
+            "total_messages_delivered": self._total_messages_delivered,
+            "total_messages_discarded": self._total_messages_discarded,
+            "lifetime_seconds": time.time() - self._created_at,
+            "delivery_rate": (
+                self._total_messages_delivered / self._total_messages_received
+                if self._total_messages_received > 0
+                else 0.0
+            ),
+        }

ccproxy/claude_sdk/options.py

@@ -61,7 +61,7 @@ class OptionsHandler:
             # Extract configuration values with proper types
             mcp_servers = (
                 configured_opts.mcp_servers.copy()
-                if configured_opts.mcp_servers
+                if isinstance(configured_opts.mcp_servers, dict)
                 else {}
             )
             permission_prompt_tool_name = configured_opts.permission_prompt_tool_name
@@ -112,6 +112,11 @@ class OptionsHandler:
         if system_message is not None:
             options.system_prompt = system_message
 
+        # If session_id is provided via additional_options, enable continue_conversation
+        # This ensures conversation continuity when using session IDs
+        if additional_options.get("session_id"):
+            options.continue_conversation = True
+
         # Note: temperature and max_tokens are API-level parameters, not ClaudeCodeOptions parameters
         # These are handled at the API request level, not in the options object