ccproxy-api 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

ccproxy/models/claude_sdk.py

@@ -338,6 +338,59 @@ SDKContentBlock = Annotated[
 ExtendedContentBlock = SDKContentBlock
 
 
+# SDK Query Message Types
+class SDKMessageContent(BaseModel):
+    """Content structure for SDK query messages."""
+
+    role: Literal["user"] = "user"
+    content: str = Field(..., description="Message text content")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class SDKMessage(BaseModel):
+    """Message format used to send queries over the Claude SDK.
+
+    This represents the internal message structure expected by the
+    Claude Code SDK client for query operations.
+    """
+
+    type: Literal["user"] = "user"
+    message: SDKMessageContent = Field(
+        ..., description="Message content with role and text"
+    )
+    parent_tool_use_id: str | None = Field(
+        None, description="Optional parent tool use ID"
+    )
+    session_id: str | None = Field(
+        None, description="Optional session ID for conversation continuity"
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+def create_sdk_message(
+    content: str,
+    session_id: str | None = None,
+    parent_tool_use_id: str | None = None,
+) -> SDKMessage:
+    """Create an SDKMessage instance for sending queries to Claude SDK.
+
+    Args:
+        content: The text content to send to Claude
+        session_id: Optional session ID for conversation continuity
+        parent_tool_use_id: Optional parent tool use ID
+
+    Returns:
+        SDKMessage instance ready to send to Claude SDK
+    """
+    return SDKMessage(
+        message=SDKMessageContent(content=content),
+        session_id=session_id,
+        parent_tool_use_id=parent_tool_use_id,
+    )
+
+
 # Conversion Functions
 def convert_sdk_text_block(text_content: str) -> TextBlock:
     """Convert raw text content to TextBlock model."""
@@ -404,6 +457,10 @@ __all__ = [
     "AssistantMessage",
     "SystemMessage",
     "ResultMessage",
+    # SDK Query Messages
+    "SDKMessageContent",
+    "SDKMessage",
+    "create_sdk_message",
     # Custom content blocks
     "SDKMessageMode",
     "ToolUseSDKBlock",

ccproxy/models/detection.py

@@ -0,0 +1,126 @@
+"""Detection models for Claude Code CLI headers and system prompt extraction."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Annotated, Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ClaudeCodeHeaders(BaseModel):
+    """Pydantic model for Claude CLI headers extraction with field aliases."""
+
+    anthropic_beta: str = Field(
+        alias="anthropic-beta",
+        description="Anthropic beta features",
+        default="claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14",
+    )
+    anthropic_version: str = Field(
+        alias="anthropic-version",
+        description="Anthropic API version",
+        default="2023-06-01",
+    )
+    anthropic_dangerous_direct_browser_access: str = Field(
+        alias="anthropic-dangerous-direct-browser-access",
+        description="Browser access flag",
+        default="true",
+    )
+    x_app: str = Field(
+        alias="x-app", description="Application identifier", default="cli"
+    )
+    user_agent: str = Field(
+        alias="user-agent",
+        description="User agent string",
+        default="claude-cli/1.0.60 (external, cli)",
+    )
+    x_stainless_lang: str = Field(
+        alias="x-stainless-lang", description="SDK language", default="js"
+    )
+    x_stainless_retry_count: str = Field(
+        alias="x-stainless-retry-count", description="Retry count", default="0"
+    )
+    x_stainless_timeout: str = Field(
+        alias="x-stainless-timeout", description="Request timeout", default="60"
+    )
+    x_stainless_package_version: str = Field(
+        alias="x-stainless-package-version",
+        description="Package version",
+        default="0.55.1",
+    )
+    x_stainless_os: str = Field(
+        alias="x-stainless-os", description="Operating system", default="Linux"
+    )
+    x_stainless_arch: str = Field(
+        alias="x-stainless-arch", description="Architecture", default="x64"
+    )
+    x_stainless_runtime: str = Field(
+        alias="x-stainless-runtime", description="Runtime", default="node"
+    )
+    x_stainless_runtime_version: str = Field(
+        alias="x-stainless-runtime-version",
+        description="Runtime version",
+        default="v24.3.0",
+    )
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    def to_headers_dict(self) -> dict[str, str]:
+        """Convert to headers dictionary for HTTP forwarding with proper case."""
+        headers = {}
+
+        # Map field names to proper HTTP header names
+        header_mapping = {
+            "anthropic_beta": "anthropic-beta",
+            "anthropic_version": "anthropic-version",
+            "anthropic_dangerous_direct_browser_access": "anthropic-dangerous-direct-browser-access",
+            "x_app": "x-app",
+            "user_agent": "User-Agent",
+            "x_stainless_lang": "X-Stainless-Lang",
+            "x_stainless_retry_count": "X-Stainless-Retry-Count",
+            "x_stainless_timeout": "X-Stainless-Timeout",
+            "x_stainless_package_version": "X-Stainless-Package-Version",
+            "x_stainless_os": "X-Stainless-OS",
+            "x_stainless_arch": "X-Stainless-Arch",
+            "x_stainless_runtime": "X-Stainless-Runtime",
+            "x_stainless_runtime_version": "X-Stainless-Runtime-Version",
+        }
+
+        for field_name, header_name in header_mapping.items():
+            value = getattr(self, field_name, None)
+            if value is not None:
+                headers[header_name] = value
+
+        return headers
+
+
+class SystemPromptData(BaseModel):
+    """Extracted system prompt information."""
+
+    system_field: Annotated[
+        str | list[dict[str, Any]],
+        Field(
+            description="Complete system field as detected from Claude CLI, preserving exact structure including type, text, and cache_control"
+        ),
+    ]
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ClaudeCacheData(BaseModel):
+    """Cached Claude CLI detection data with version tracking."""
+
+    claude_version: Annotated[str, Field(description="Claude CLI version")]
+    headers: Annotated[ClaudeCodeHeaders, Field(description="Extracted headers")]
+    system_prompt: Annotated[
+        SystemPromptData, Field(description="Extracted system prompt")
+    ]
+    cached_at: Annotated[
+        datetime,
+        Field(
+            description="Cache timestamp",
+            default_factory=lambda: datetime.now(UTC),
+        ),
+    ] = None  # type: ignore # Pydantic handles this via default_factory
+
+    model_config = ConfigDict(extra="forbid")

ccproxy/observability/access_logger.py

@@ -63,20 +63,31 @@ async def log_request_access(
     path = path or ctx_metadata.get("path")
     status_code = status_code or ctx_metadata.get("status_code")
 
-    # Prepare comprehensive log data
+    # Prepare basic log data (always included)
     log_data = {
         "request_id": context.request_id,
         "method": method,
         "path": path,
         "query": query,
-        "status_code": status_code,
         "client_ip": client_ip,
         "user_agent": user_agent,
-        "duration_ms": context.duration_ms,
-        "duration_seconds": context.duration_seconds,
-        "error_message": error_message,
     }
 
+    # Add response-specific fields (only for completed requests)
+    is_streaming = ctx_metadata.get("streaming", False)
+    is_streaming_complete = ctx_metadata.get("event_type", "") == "streaming_complete"
+
+    # Include response fields only if this is not a streaming start
+    if not is_streaming or is_streaming_complete or ctx_metadata.get("error"):
+        log_data.update(
+            {
+                "status_code": status_code,
+                "duration_ms": context.duration_ms,
+                "duration_seconds": context.duration_seconds,
+                "error_message": error_message,
+            }
+        )
+
     # Add token and cost metrics if available
     token_fields = [
         "tokens_input",
@@ -85,6 +96,7 @@ async def log_request_access(
         "cache_write_tokens",
         "cost_usd",
         "cost_sdk_usd",
+        "num_turns",
     ]
 
     for field in token_fields:
@@ -93,18 +105,50 @@ async def log_request_access(
             log_data[field] = value
 
     # Add service and endpoint info
-    service_fields = [
-        "endpoint",
-        "model",
-        "streaming",
-        "service_type",
-    ]
+    service_fields = ["endpoint", "model", "streaming", "service_type", "headers"]
 
     for field in service_fields:
         value = ctx_metadata.get(field)
         if value is not None:
             log_data[field] = value
 
+    # Add session context metadata if available
+    session_fields = [
+        "session_id",
+        "session_type",  # "session_pool" or "direct"
+        "session_status",  # active, idle, connecting, etc.
+        "session_age_seconds",  # how long session has been alive
+        "session_message_count",  # number of messages in session
+        "session_pool_enabled",  # whether session pooling is enabled
+        "session_idle_seconds",  # how long since last activity
+        "session_error_count",  # number of errors in this session
+        "session_is_new",  # whether this is a newly created session
+    ]
+
+    for field in session_fields:
+        value = ctx_metadata.get(field)
+        if value is not None:
+            log_data[field] = value
+
+    # Add rate limit headers if available
+    rate_limit_fields = [
+        "x-ratelimit-limit",
+        "x-ratelimit-remaining",
+        "x-ratelimit-reset",
+        "anthropic-ratelimit-requests-limit",
+        "anthropic-ratelimit-requests-remaining",
+        "anthropic-ratelimit-requests-reset",
+        "anthropic-ratelimit-tokens-limit",
+        "anthropic-ratelimit-tokens-remaining",
+        "anthropic-ratelimit-tokens-reset",
+        "anthropic_request_id",
+    ]
+
+    for field in rate_limit_fields:
+        value = ctx_metadata.get(field)
+        if value is not None:
+            log_data[field] = value
+
     # Add any additional metadata provided
     log_data.update(additional_metadata)
 
@@ -112,15 +156,18 @@ async def log_request_access(
     log_data = {k: v for k, v in log_data.items() if v is not None}
 
     logger = context.logger.bind(**log_data)
-    if not log_data.get("streaming", False):
+
+    if context.metadata.get("error"):
+        logger.warn("access_log", exc_info=context.metadata.get("error"))
+    elif not is_streaming:
         # Log as access_log event (structured logging)
         logger.info("access_log")
-    elif log_data.get("event_type", "") == "streaming_complete":
+    elif is_streaming_complete:
         logger.info("access_log")
     else:
         # if streaming is true, and not streaming_complete log as debug
         # real access_log will come later
-        logger.debug("access_log")
+        logger.info("access_log_streaming_start")
 
     # Store in DuckDB if available
     await _store_access_log(log_data, storage)
@@ -258,6 +305,17 @@ async def _store_access_log(
             "cache_write_tokens": log_data.get("cache_write_tokens", 0),
             "cost_usd": log_data.get("cost_usd", 0.0),
             "cost_sdk_usd": log_data.get("cost_sdk_usd", 0.0),
+            "num_turns": log_data.get("num_turns", 0),
+            # Session context metadata
+            "session_type": log_data.get("session_type", ""),
+            "session_status": log_data.get("session_status", ""),
+            "session_age_seconds": log_data.get("session_age_seconds", 0.0),
+            "session_message_count": log_data.get("session_message_count", 0),
+            "session_client_id": log_data.get("session_client_id", ""),
+            "session_pool_enabled": log_data.get("session_pool_enabled", False),
+            "session_idle_seconds": log_data.get("session_idle_seconds", 0.0),
+            "session_error_count": log_data.get("session_error_count", 0),
+            "session_is_new": log_data.get("session_is_new", True),
         }
 
         # Store asynchronously using queue-based DuckDB (prevents deadlocks)

ccproxy/observability/metrics.py

@@ -205,6 +205,62 @@ class PrometheusMetrics:
             registry=self.registry,
         )
 
+        # Claude SDK Pool metrics
+        self.pool_clients_total = Gauge(
+            f"{self.namespace}_pool_clients_total",
+            "Total number of clients in the pool",
+            registry=self.registry,
+        )
+
+        self.pool_clients_available = Gauge(
+            f"{self.namespace}_pool_clients_available",
+            "Number of available clients in the pool",
+            registry=self.registry,
+        )
+
+        self.pool_clients_active = Gauge(
+            f"{self.namespace}_pool_clients_active",
+            "Number of active clients currently processing requests",
+            registry=self.registry,
+        )
+
+        self.pool_connections_created_total = Counter(
+            f"{self.namespace}_pool_connections_created_total",
+            "Total number of pool connections created",
+            registry=self.registry,
+        )
+
+        self.pool_connections_closed_total = Counter(
+            f"{self.namespace}_pool_connections_closed_total",
+            "Total number of pool connections closed",
+            registry=self.registry,
+        )
+
+        self.pool_acquisitions_total = Counter(
+            f"{self.namespace}_pool_acquisitions_total",
+            "Total number of client acquisitions from pool",
+            registry=self.registry,
+        )
+
+        self.pool_releases_total = Counter(
+            f"{self.namespace}_pool_releases_total",
+            "Total number of client releases to pool",
+            registry=self.registry,
+        )
+
+        self.pool_health_check_failures_total = Counter(
+            f"{self.namespace}_pool_health_check_failures_total",
+            "Total number of pool health check failures",
+            registry=self.registry,
+        )
+
+        self.pool_acquisition_duration = Histogram(
+            f"{self.namespace}_pool_acquisition_duration_seconds",
+            "Time taken to acquire a client from the pool",
+            buckets=[0.001, 0.005, 0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0],
+            registry=self.registry,
+        )
+
         # Set initial system info
         try:
             from ccproxy import __version__
@@ -468,6 +524,101 @@ class PrometheusMetrics:
             and self._pushgateway_client.is_enabled()
         )
 
+    # Claude SDK Pool metrics methods
+
+    def update_pool_gauges(
+        self,
+        total_clients: int,
+        available_clients: int,
+        active_clients: int,
+    ) -> None:
+        """
+        Update pool gauge metrics (current state).
+
+        Args:
+            total_clients: Total number of clients in pool
+            available_clients: Number of available clients
+            active_clients: Number of active clients
+        """
+        if not self._enabled:
+            return
+
+        # Update gauges
+        self.pool_clients_total.set(total_clients)
+        self.pool_clients_available.set(available_clients)
+        self.pool_clients_active.set(active_clients)
+
+        # Note: Counters are managed directly by the pool operations
+        # This method only updates the current gauges
+
+    def record_pool_acquisition_time(self, duration_seconds: float) -> None:
+        """
+        Record the time taken to acquire a client from the pool.
+
+        Args:
+            duration_seconds: Time in seconds to acquire client
+        """
+        if not self._enabled:
+            return
+
+        self.pool_acquisition_duration.observe(duration_seconds)
+
+    def inc_pool_connections_created(self) -> None:
+        """Increment the pool connections created counter."""
+        if not self._enabled:
+            return
+
+        self.pool_connections_created_total.inc()
+
+    def inc_pool_connections_closed(self) -> None:
+        """Increment the pool connections closed counter."""
+        if not self._enabled:
+            return
+
+        self.pool_connections_closed_total.inc()
+
+    def inc_pool_acquisitions(self) -> None:
+        """Increment the pool acquisitions counter."""
+        if not self._enabled:
+            return
+
+        self.pool_acquisitions_total.inc()
+
+    def inc_pool_releases(self) -> None:
+        """Increment the pool releases counter."""
+        if not self._enabled:
+            return
+
+        self.pool_releases_total.inc()
+
+    def inc_pool_health_check_failures(self) -> None:
+        """Increment the pool health check failures counter."""
+        if not self._enabled:
+            return
+
+        self.pool_health_check_failures_total.inc()
+
+    def set_pool_clients_total(self, count: int) -> None:
+        """Set the total number of clients in the pool."""
+        if not self._enabled:
+            return
+
+        self.pool_clients_total.set(count)
+
+    def set_pool_clients_available(self, count: int) -> None:
+        """Set the number of available clients in the pool."""
+        if not self._enabled:
+            return
+
+        self.pool_clients_available.set(count)
+
+    def set_pool_clients_active(self, count: int) -> None:
+        """Set the number of active clients in the pool."""
+        if not self._enabled:
+            return
+
+        self.pool_clients_active.set(count)
+
 
 # Global metrics instance
 _global_metrics: PrometheusMetrics | None = None

ccproxy/observability/storage/duckdb_simple.py

@@ -60,6 +60,18 @@ class AccessLogPayload(TypedDict, total=False):
     cache_write_tokens: int
     cost_usd: float
     cost_sdk_usd: float
+    num_turns: int  # number of conversation turns
+
+    # Session context metadata
+    session_type: str  # "session_pool" or "direct"
+    session_status: str  # active, idle, connecting, etc.
+    session_age_seconds: float  # how long session has been alive
+    session_message_count: int  # number of messages in session
+    session_client_id: str  # unique session client identifier
+    session_pool_enabled: bool  # whether session pooling is enabled
+    session_idle_seconds: float  # how long since last activity
+    session_error_count: int  # number of errors in this session
+    session_is_new: bool  # whether this is a newly created session
 
 
 class SimpleDuckDBStorage:

ccproxy/observability/storage/models.py

@@ -44,6 +44,22 @@ class AccessLog(SQLModel, table=True):
     cache_write_tokens: int = Field(default=0)
     cost_usd: float = Field(default=0.0)
     cost_sdk_usd: float = Field(default=0.0)
+    num_turns: int = Field(default=0)  # number of conversation turns
+
+    # Session context metadata
+    session_type: str = Field(default="")  # "session_pool" or "direct"
+    session_status: str = Field(default="")  # active, idle, connecting, etc.
+    session_age_seconds: float = Field(default=0.0)  # how long session has been alive
+    session_message_count: int = Field(default=0)  # number of messages in session
+    session_client_id: str = Field(default="")  # unique session client identifier
+    session_pool_enabled: bool = Field(
+        default=False
+    )  # whether session pooling is enabled
+    session_idle_seconds: float = Field(default=0.0)  # how long since last activity
+    session_error_count: int = Field(default=0)  # number of errors in this session
+    session_is_new: bool = Field(
+        default=True
+    )  # whether this is a newly created session
 
     class Config:
         """SQLModel configuration."""

ccproxy/observability/streaming_response.py

@@ -0,0 +1,107 @@
+"""FastAPI StreamingResponse with automatic access logging on completion.
+
+This module provides a reusable StreamingResponseWithLogging class that wraps
+any async generator and handles access logging when the stream completes,
+eliminating code duplication between different streaming endpoints.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+import structlog
+from fastapi.responses import StreamingResponse
+
+from ccproxy.observability.access_logger import log_request_access
+
+
+if TYPE_CHECKING:
+    from ccproxy.observability.context import RequestContext
+    from ccproxy.observability.metrics import PrometheusMetrics
+
+logger = structlog.get_logger(__name__)
+
+
+class StreamingResponseWithLogging(StreamingResponse):
+    """FastAPI StreamingResponse that triggers access logging on completion.
+
+    This class wraps a streaming response generator to automatically trigger
+    access logging when the stream completes (either successfully or with an error).
+    This eliminates the need for manual access logging in individual stream processors.
+    """
+
+    def __init__(
+        self,
+        content: AsyncGenerator[bytes, None] | AsyncIterator[bytes],
+        request_context: RequestContext,
+        metrics: PrometheusMetrics | None = None,
+        status_code: int = 200,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize streaming response with logging capability.
+
+        Args:
+            content: The async generator producing streaming content
+            request_context: The request context for access logging
+            metrics: Optional PrometheusMetrics instance for recording metrics
+            status_code: HTTP status code for the response
+            **kwargs: Additional arguments passed to StreamingResponse
+        """
+        # Wrap the content generator to add logging
+        logged_content = self._wrap_with_logging(
+            content, request_context, metrics, status_code
+        )
+        super().__init__(logged_content, status_code=status_code, **kwargs)
+
+    async def _wrap_with_logging(
+        self,
+        content: AsyncGenerator[bytes, None] | AsyncIterator[bytes],
+        context: RequestContext,
+        metrics: PrometheusMetrics | None,
+        status_code: int,
+    ) -> AsyncGenerator[bytes, None]:
+        """Wrap content generator with access logging on completion.
+
+        Args:
+            content: The original content generator
+            context: Request context for logging
+            metrics: Optional metrics instance
+            status_code: HTTP status code
+
+        Yields:
+            bytes: Content chunks from the original generator
+        """
+        try:
+            # Stream all content from the original generator
+            async for chunk in content:
+                yield chunk
+        except GeneratorExit:
+            # Client disconnected - log this and re-raise to propagate to underlying generators
+            logger.info(
+                "streaming_response_client_disconnected",
+                request_id=context.request_id,
+                message="Client disconnected from streaming response, propagating GeneratorExit",
+            )
+            # CRITICAL: Re-raise GeneratorExit to propagate disconnect to create_listener()
+            raise
+        finally:
+            # Log access when stream completes (success or error)
+            try:
+                # Add streaming completion event type to context
+                context.add_metadata(event_type="streaming_complete")
+
+                # Check if status_code was updated in context metadata (e.g., due to error)
+                final_status_code = context.metadata.get("status_code", status_code)
+
+                await log_request_access(
+                    context=context,
+                    status_code=final_status_code,
+                    metrics=metrics,
+                )
+            except Exception as e:
+                logger.warning(
+                    "streaming_access_log_failed",
+                    error=str(e),
+                    request_id=context.request_id,
+                )