provide-foundation 0.0.0.dev0__py3-none-any.whl → 0.0.0.dev1__py3-none-any.whl

provide/foundation/transport/middleware.py

@@ -0,0 +1,366 @@
+"""
+Transport middleware system with Hub registration.
+"""
+
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from typing import Any
+
+from attrs import define, field
+
+from provide.foundation.hub import get_component_registry
+from provide.foundation.hub.components import ComponentCategory
+from provide.foundation.logger import get_logger
+from provide.foundation.metrics import counter, histogram
+from provide.foundation.transport.base import Request, Response
+from provide.foundation.transport.errors import TransportError
+
+log = get_logger(__name__)
+
+
+class Middleware(ABC):
+    """Abstract base class for transport middleware."""
+    
+    @abstractmethod
+    async def process_request(self, request: Request) -> Request:
+        """Process request before sending."""
+        pass
+    
+    @abstractmethod 
+    async def process_response(self, response: Response) -> Response:
+        """Process response after receiving."""
+        pass
+    
+    @abstractmethod
+    async def process_error(self, error: Exception, request: Request) -> Exception:
+        """Process errors during request."""
+        pass
+
+
+@define
+class LoggingMiddleware(Middleware):
+    """Built-in telemetry middleware using foundation.logger."""
+    
+    log_requests: bool = field(default=True)
+    log_responses: bool = field(default=True)
+    log_bodies: bool = field(default=False)
+    
+    async def process_request(self, request: Request) -> Request:
+        """Log outgoing request."""
+        if self.log_requests:
+            log.info(
+                f"🚀 {request.method} {request.uri}",
+                method=request.method,
+                uri=str(request.uri),
+                headers=dict(request.headers) if hasattr(request, 'headers') else {},
+            )
+            
+            if self.log_bodies and request.body:
+                log.trace("Request body", body=request.body, method=request.method, uri=str(request.uri))
+        
+        return request
+    
+    async def process_response(self, response: Response) -> Response:
+        """Log incoming response."""
+        if self.log_responses:
+            status_emoji = self._get_status_emoji(response.status)
+            log.info(
+                f"{status_emoji} {response.status} ({response.elapsed_ms:.0f}ms)",
+                status_code=response.status,
+                elapsed_ms=response.elapsed_ms,
+                method=response.request.method if response.request else None,
+                uri=str(response.request.uri) if response.request else None,
+                headers=dict(response.headers) if hasattr(response, 'headers') else {},
+            )
+            
+            if self.log_bodies and response.body:
+                log.trace(
+                    "Response body", 
+                    body=response.text[:500],  # Truncate large bodies
+                    status_code=response.status,
+                    method=response.request.method if response.request else None,
+                    uri=str(response.request.uri) if response.request else None,
+                )
+        
+        return response
+    
+    async def process_error(self, error: Exception, request: Request) -> Exception:
+        """Log errors."""
+        log.error(
+            f"❌ {request.method} {request.uri} failed: {error}",
+            method=request.method,
+            uri=str(request.uri),
+            error_type=error.__class__.__name__,
+            error_message=str(error),
+        )
+        return error
+    
+    def _get_status_emoji(self, status_code: int) -> str:
+        """Get emoji for status code."""
+        if 200 <= status_code < 300:
+            return "✅"
+        elif 300 <= status_code < 400:
+            return "↩️" 
+        elif 400 <= status_code < 500:
+            return "⚠️"
+        elif 500 <= status_code < 600:
+            return "❌"
+        else:
+            return "❓"
+
+
+@define
+class RetryMiddleware(Middleware):
+    """Automatic retry middleware with exponential backoff."""
+    
+    max_retries: int = field(default=3)
+    backoff_factor: float = field(default=0.5)
+    retryable_status_codes: set[int] = field(factory=lambda: {500, 502, 503, 504})
+    retryable_exceptions: tuple[type[Exception], ...] = field(
+        factory=lambda: (TransportError,)
+    )
+    
+    async def process_request(self, request: Request) -> Request:
+        """No request processing needed."""
+        return request
+    
+    async def process_response(self, response: Response) -> Response:
+        """No response processing needed (retries handled in execute)."""
+        return response
+    
+    async def process_error(self, error: Exception, request: Request) -> Exception:
+        """Handle error, potentially with retries (this is called by client)."""
+        return error
+    
+    async def execute_with_retry(self, execute_func, request: Request) -> Response:
+        """Execute request with retry logic."""
+        last_exception = None
+        
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await execute_func(request)
+                
+                # Check if status code is retryable
+                if response.status in self.retryable_status_codes and attempt < self.max_retries:
+                    wait_time = self.backoff_factor * (2 ** attempt)
+                    log.info(f"🔄 Retry {attempt + 1}/{self.max_retries} after {wait_time:.1f}s (status {response.status})")
+                    await asyncio.sleep(wait_time)
+                    continue
+                
+                return response
+                
+            except self.retryable_exceptions as e:
+                last_exception = e
+                
+                if attempt < self.max_retries:
+                    wait_time = self.backoff_factor * (2 ** attempt)
+                    log.info(f"🔄 Retry {attempt + 1}/{self.max_retries} after {wait_time:.1f}s (error: {e})")
+                    await asyncio.sleep(wait_time)
+                else:
+                    break
+        
+        # All retries exhausted
+        if last_exception:
+            raise last_exception
+        else:
+            # This shouldn't happen, but just in case
+            raise TransportError("Max retries exceeded")
+
+
+@define
+class MetricsMiddleware(Middleware):
+    """Middleware for collecting transport metrics using foundation.metrics."""
+    
+    # Create metrics instances
+    _request_counter = counter(
+        "transport_requests_total",
+        description="Total number of transport requests",
+        unit="requests"
+    )
+    _request_duration = histogram(
+        "transport_request_duration_seconds", 
+        description="Duration of transport requests",
+        unit="seconds"
+    )
+    _error_counter = counter(
+        "transport_errors_total",
+        description="Total number of transport errors", 
+        unit="errors"
+    )
+    
+    async def process_request(self, request: Request) -> Request:
+        """Record request start time."""
+        request.metadata["start_time"] = time.perf_counter()
+        return request
+    
+    async def process_response(self, response: Response) -> Response:
+        """Record response metrics."""
+        if response.request and "start_time" in response.request.metadata:
+            start_time = response.request.metadata["start_time"]
+            duration = time.perf_counter() - start_time
+            
+            method = response.request.method
+            status_class = f"{response.status // 100}xx"
+            
+            # Record metrics with labels
+            self._request_counter.inc(1, 
+                method=method,
+                status_code=str(response.status),
+                status_class=status_class
+            )
+            
+            self._request_duration.observe(duration,
+                method=method,
+                status_class=status_class
+            )
+        
+        return response
+    
+    async def process_error(self, error: Exception, request: Request) -> Exception:
+        """Record error metrics."""
+        method = request.method
+        error_type = error.__class__.__name__
+        
+        self._error_counter.inc(1,
+            method=method,
+            error_type=error_type
+        )
+        
+        return error
+
+
+@define
+class MiddlewarePipeline:
+    """Pipeline for executing middleware in order."""
+    
+    middleware: list[Middleware] = field(factory=list)
+    
+    def add(self, middleware: Middleware) -> None:
+        """Add middleware to the pipeline."""
+        self.middleware.append(middleware)
+        log.trace(f"Added middleware: {middleware.__class__.__name__}")
+    
+    def remove(self, middleware_class: type[Middleware]) -> bool:
+        """Remove middleware by class type."""
+        for i, mw in enumerate(self.middleware):
+            if isinstance(mw, middleware_class):
+                del self.middleware[i]
+                log.trace(f"Removed middleware: {middleware_class.__name__}")
+                return True
+        return False
+    
+    async def process_request(self, request: Request) -> Request:
+        """Process request through all middleware."""
+        for mw in self.middleware:
+            request = await mw.process_request(request)
+        return request
+    
+    async def process_response(self, response: Response) -> Response:
+        """Process response through all middleware (in reverse order)."""
+        for mw in reversed(self.middleware):
+            response = await mw.process_response(response)
+        return response
+    
+    async def process_error(self, error: Exception, request: Request) -> Exception:
+        """Process error through all middleware."""
+        for mw in self.middleware:
+            error = await mw.process_error(error, request)
+        return error
+
+
+def register_middleware(
+    name: str,
+    middleware_class: type[Middleware],
+    category: str = "transport.middleware",
+    **metadata
+) -> None:
+    """Register middleware in the Hub."""
+    registry = get_component_registry()
+    
+    registry.register(
+        name=name,
+        value=middleware_class,
+        dimension=category,
+        metadata={
+            "category": category,
+            "priority": metadata.get("priority", 100),
+            "class_name": middleware_class.__name__,
+            **metadata
+        },
+        replace=True,
+    )
+    
+    log.debug(f"Registered middleware {middleware_class.__name__} as '{name}'")
+
+
+def get_middleware_by_category(category: str = "transport.middleware") -> list[type[Middleware]]:
+    """Get all middleware for a category, sorted by priority."""
+    registry = get_component_registry()
+    middleware = []
+    
+    for entry in registry:
+        if entry.dimension == category:
+            priority = entry.metadata.get("priority", 100)
+            middleware.append((entry.value, priority))
+    
+    # Sort by priority (lower numbers = higher priority)
+    middleware.sort(key=lambda x: x[1])
+    return [mw[0] for mw in middleware]
+
+
+def create_default_pipeline() -> MiddlewarePipeline:
+    """Create pipeline with default middleware."""
+    pipeline = MiddlewarePipeline()
+    
+    # Add built-in middleware
+    pipeline.add(LoggingMiddleware())
+    pipeline.add(MetricsMiddleware())
+    
+    return pipeline
+
+
+# Auto-register built-in middleware
+def _register_builtin_middleware():
+    """Register built-in middleware with the Hub."""
+    try:
+        register_middleware(
+            "logging",
+            LoggingMiddleware,
+            description="Built-in request/response logging",
+            priority=10,
+        )
+        
+        register_middleware(
+            "retry", 
+            RetryMiddleware,
+            description="Automatic retry with exponential backoff",
+            priority=20,
+        )
+        
+        register_middleware(
+            "metrics",
+            MetricsMiddleware, 
+            description="Request/response metrics collection",
+            priority=30,
+        )
+        
+    except ImportError:
+        # Registry not available yet
+        pass
+
+
+# Register when module is imported
+_register_builtin_middleware()
+
+
+__all__ = [
+    "Middleware",
+    "LoggingMiddleware",
+    "RetryMiddleware", 
+    "MetricsMiddleware",
+    "MiddlewarePipeline",
+    "register_middleware",
+    "get_middleware_by_category",
+    "create_default_pipeline",
+]

provide/foundation/transport/registry.py

@@ -0,0 +1,167 @@
+"""
+Transport registration and discovery using Foundation Hub.
+"""
+
+from typing import Any
+
+from provide.foundation.hub import get_component_registry
+from provide.foundation.hub.components import ComponentCategory
+from provide.foundation.logger import get_logger
+from provide.foundation.transport.base import Transport
+from provide.foundation.transport.errors import TransportNotFoundError
+from provide.foundation.transport.types import TransportType
+
+log = get_logger(__name__)
+
+
+def register_transport(
+    transport_type: TransportType,
+    transport_class: type[Transport],
+    schemes: list[str] | None = None,
+    **metadata
+) -> None:
+    """
+    Register a transport implementation in the Hub.
+    
+    Args:
+        transport_type: The primary transport type
+        transport_class: Transport implementation class
+        schemes: List of URI schemes this transport handles
+        **metadata: Additional metadata for the transport
+    """
+    registry = get_component_registry()
+    
+    # Default schemes to just the transport type
+    if schemes is None:
+        schemes = [transport_type.value]
+    
+    registry.register(
+        name=transport_type.value,
+        value=transport_class,
+        dimension=ComponentCategory.TRANSPORT.value,
+        metadata={
+            "transport_type": transport_type,
+            "schemes": schemes,
+            "class_name": transport_class.__name__,
+            **metadata
+        },
+        replace=True,  # Allow re-registration
+    )
+    
+    log.debug(f"Registered transport {transport_class.__name__} for schemes: {schemes}")
+
+
+def get_transport_for_scheme(scheme: str) -> type[Transport]:
+    """
+    Get transport class for a URI scheme.
+    
+    Args:
+        scheme: URI scheme (e.g., 'http', 'https', 'ws')
+        
+    Returns:
+        Transport class that handles the scheme
+        
+    Raises:
+        TransportNotFoundError: If no transport is registered for the scheme
+    """
+    registry = get_component_registry()
+    
+    # Search through registered transports
+    for entry in registry:
+        if entry.dimension == ComponentCategory.TRANSPORT.value:
+            schemes = entry.metadata.get("schemes", [])
+            if scheme.lower() in schemes:
+                log.trace(f"Found transport {entry.value.__name__} for scheme '{scheme}'")
+                return entry.value
+    
+    raise TransportNotFoundError(
+        f"No transport registered for scheme: {scheme}",
+        scheme=scheme,
+    )
+
+
+def get_transport(uri: str) -> Transport:
+    """
+    Get transport instance for a URI.
+    
+    Args:
+        uri: Full URI to get transport for
+        
+    Returns:
+        Transport instance ready to use
+        
+    Raises:
+        TransportNotFoundError: If no transport supports the URI scheme
+    """
+    scheme = uri.split("://")[0].lower()
+    transport_class = get_transport_for_scheme(scheme)
+    return transport_class()
+
+
+def list_registered_transports() -> dict[str, dict[str, Any]]:
+    """
+    List all registered transports.
+    
+    Returns:
+        Dictionary mapping transport names to their info
+    """
+    registry = get_component_registry()
+    transports = {}
+    
+    for entry in registry:
+        if entry.dimension == ComponentCategory.TRANSPORT.value:
+            transports[entry.name] = {
+                "class": entry.value,
+                "schemes": entry.metadata.get("schemes", []),
+                "transport_type": entry.metadata.get("transport_type"),
+                "metadata": entry.metadata,
+            }
+    
+    return transports
+
+
+def get_transport_info(scheme_or_name: str) -> dict[str, Any] | None:
+    """
+    Get detailed information about a transport.
+    
+    Args:
+        scheme_or_name: URI scheme or transport name
+        
+    Returns:
+        Transport information or None if not found
+    """
+    registry = get_component_registry()
+    
+    for entry in registry:
+        if entry.dimension == ComponentCategory.TRANSPORT.value:
+            # Check if it matches by name
+            if entry.name == scheme_or_name:
+                return {
+                    "name": entry.name,
+                    "class": entry.value,
+                    "schemes": entry.metadata.get("schemes", []),
+                    "transport_type": entry.metadata.get("transport_type"),
+                    "metadata": entry.metadata,
+                }
+            
+            # Check if it matches by scheme
+            schemes = entry.metadata.get("schemes", [])
+            if scheme_or_name.lower() in schemes:
+                return {
+                    "name": entry.name,
+                    "class": entry.value,
+                    "schemes": schemes,
+                    "transport_type": entry.metadata.get("transport_type"),
+                    "metadata": entry.metadata,
+                }
+    
+    return None
+
+
+__all__ = [
+    "register_transport",
+    "get_transport_for_scheme", 
+    "get_transport",
+    "list_registered_transports",
+    "get_transport_info",
+]

provide/foundation/transport/types.py

@@ -0,0 +1,45 @@
+"""
+Transport type definitions and enums.
+"""
+
+from enum import Enum
+from typing import Any, TypeAlias
+
+# Type aliases
+Headers: TypeAlias = dict[str, str]
+Params: TypeAlias = dict[str, Any]
+Data: TypeAlias = dict[str, Any] | bytes | str | None
+
+
+class TransportType(str, Enum):
+    """Supported transport types."""
+    
+    HTTP = "http"
+    HTTPS = "https"
+    WS = "ws"
+    WSS = "wss"
+    GRPC = "grpc"
+    GRAPHQL = "graphql"
+    AMQP = "amqp"
+    MQTT = "mqtt"
+
+
+class HTTPMethod(str, Enum):
+    """HTTP methods."""
+    
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    PATCH = "PATCH"
+    DELETE = "DELETE"
+    HEAD = "HEAD"
+    OPTIONS = "OPTIONS"
+
+
+__all__ = [
+    "Headers",
+    "Params", 
+    "Data",
+    "TransportType",
+    "HTTPMethod",
+]

{provide_foundation-0.0.0.dev0.dist-info → provide_foundation-0.0.0.dev1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: provide-foundation
-Version: 0.0.0.dev0
+Version: 0.0.0.dev1
 Summary: Foundation Telemetry: An opinionated, developer-friendly telemetry wrapper for Python.
 Author-email: Tim Perkins <code@tim.life>
 Maintainer-email: "provide.io" <code@provide.io>
@@ -29,13 +29,15 @@ Provides-Extra: cli
 Requires-Dist: click>=8.1.7; extra == "cli"
 Provides-Extra: crypto
 Requires-Dist: cryptography>=45.0.7; extra == "crypto"
+Provides-Extra: transport
+Requires-Dist: httpx>=0.27.0; extra == "transport"
 Provides-Extra: opentelemetry
 Requires-Dist: opentelemetry-api>=1.22.0; extra == "opentelemetry"
 Requires-Dist: opentelemetry-sdk>=1.22.0; extra == "opentelemetry"
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.22.0; extra == "opentelemetry"
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.22.0; extra == "opentelemetry"
 Provides-Extra: all
-Requires-Dist: provide-foundation[cli,crypto,opentelemetry]; extra == "all"
+Requires-Dist: provide-foundation[cli,crypto,opentelemetry,transport]; extra == "all"
 Dynamic: license-file
 
 # provide.foundation
@@ -439,31 +441,6 @@ Complete working examples are available in the [examples/](examples/) directory:
 
 ---
 
-## Performance
-
-- **Logging**: 14,000+ messages/second with emoji processing and structured logging
-- **Configuration**: Lazy loading with multi-source caching for optimal performance  
-- **File Operations**: Atomic writes with format detection prevent corruption
-- **Process Management**: Efficient streaming with async support and backpressure handling
-- **Cryptography**: Hardware-accelerated operations with secure algorithm defaults
-- **Platform Detection**: Cached system information for minimal overhead
-
----
-
-## Contributing
-
-We welcome contributions! Please see:
-- [DEVELOPMENT.md](DEVELOPMENT.md) - Development setup and guidelines
-- [GitHub Issues](https://github.com/provide-io/provide-foundation/issues) - Bug reports and feature requests
-
----
-
-## License
-
-MIT License - see [LICENSE](LICENSE) file for details.
-
----
-
 <p align="center">
-  Built by <a href="https://provide.io">Provide</a>
+  Built by <a href="https://provide.io">provide.io</a>
 </p>