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

ccproxy/services/tracing/interfaces.py

@@ -0,0 +1,61 @@
+"""Request tracing interfaces for monitoring and debugging proxy requests."""
+
+from abc import ABC, abstractmethod
+
+
+class RequestTracer(ABC):
+    """Base interface for request tracing across all providers."""
+
+    @abstractmethod
+    async def trace_request(
+        self,
+        request_id: str,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        body: bytes | None,
+    ) -> None:
+        """Record request details for debugging/monitoring.
+
+        - Logs to console with redacted sensitive headers
+        - Writes complete request to file if verbose mode enabled
+        - Tracks request timing and metadata
+        """
+
+    @abstractmethod
+    async def trace_response(
+        self, request_id: str, status: int, headers: dict[str, str], body: bytes
+    ) -> None:
+        """Record response details.
+
+        - Logs response with body preview to console
+        - Writes complete response to file for debugging
+        - Handles JSON pretty-printing when applicable
+        """
+
+
+class StreamingTracer(ABC):
+    """Interface for tracing streaming operations."""
+
+    @abstractmethod
+    async def trace_stream_start(
+        self, request_id: str, headers: dict[str, str]
+    ) -> None:
+        """Mark beginning of stream with initial headers."""
+
+    @abstractmethod
+    async def trace_stream_chunk(
+        self, request_id: str, chunk: bytes, chunk_number: int
+    ) -> None:
+        """Record individual stream chunk (optional, for deep debugging)."""
+
+    @abstractmethod
+    async def trace_stream_complete(
+        self, request_id: str, total_chunks: int, total_bytes: int
+    ) -> None:
+        """Mark stream completion with statistics.
+
+        - Total chunks processed
+        - Total bytes transferred
+        - Stream duration
+        """

ccproxy/services/tracing/null_tracer.py

@@ -0,0 +1,57 @@
+"""Null implementation of request tracer for when tracing is disabled."""
+
+from .interfaces import RequestTracer, StreamingTracer
+
+
+class NullRequestTracer(RequestTracer, StreamingTracer):
+    """No-op implementation of request tracer.
+
+    Used as a fallback when the request_tracer plugin is disabled.
+    """
+
+    async def trace_request(
+        self,
+        request_id: str,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        body: bytes | None,
+    ) -> None:
+        """No-op request tracing."""
+        pass
+
+    async def trace_response(
+        self,
+        request_id: str,
+        status: int,
+        headers: dict[str, str],
+        body: bytes,
+    ) -> None:
+        """No-op response tracing."""
+        pass
+
+    async def trace_stream_start(
+        self,
+        request_id: str,
+        headers: dict[str, str],
+    ) -> None:
+        """No-op stream start tracing."""
+        pass
+
+    async def trace_stream_chunk(
+        self,
+        request_id: str,
+        chunk: bytes,
+        chunk_number: int,
+    ) -> None:
+        """No-op stream chunk tracing."""
+        pass
+
+    async def trace_stream_complete(
+        self,
+        request_id: str,
+        total_chunks: int,
+        total_bytes: int,
+    ) -> None:
+        """No-op stream complete tracing."""
+        pass

ccproxy/streaming/__init__.py

@@ -0,0 +1,23 @@
+"""Generic streaming utilities for CCProxy.
+
+This package provides transport-agnostic streaming functionality:
+- Stream interfaces and handlers
+- Buffer management
+- Deferred streaming for header preservation
+"""
+
+from .buffer import StreamingBufferService
+from .buffer import StreamingBufferService as BufferService
+from .deferred import DeferredStreaming
+from .handler import StreamingHandler
+from .interfaces import IStreamingMetricsCollector, StreamingMetrics
+
+
+__all__ = [
+    "BufferService",
+    "StreamingBufferService",
+    "StreamingMetrics",
+    "IStreamingMetricsCollector",
+    "StreamingHandler",
+    "DeferredStreaming",
+]