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

provide/foundation/transport/__init__.py

@@ -0,0 +1,155 @@
+"""
+Provide Foundation Transport System
+==================================
+
+Protocol-agnostic transport layer with HTTP/HTTPS support using Foundation Hub registry.
+
+Key Features:
+- Hub-based transport registration and discovery
+- Async-first with httpx backend for HTTP/HTTPS
+- Built-in telemetry with foundation.logger
+- Middleware pipeline for extensibility
+- No hardcoded defaults - all configuration from environment
+- Modern Python 3.11+ typing
+
+Example Usage:
+    >>> from provide.foundation.transport import get, post
+    >>> 
+    >>> # Simple requests
+    >>> response = await get("https://api.example.com/users")
+    >>> data = response.json()
+    >>> 
+    >>> # POST with JSON body
+    >>> response = await post(
+    ...     "https://api.example.com/users",
+    ...     body={"name": "John", "email": "john@example.com"}
+    ... )
+    >>> 
+    >>> # Using client for multiple requests
+    >>> from provide.foundation.transport import UniversalClient
+    >>> 
+    >>> async with UniversalClient() as client:
+    ...     users = await client.get("https://api.example.com/users")
+    ...     posts = await client.get("https://api.example.com/posts")
+    >>> 
+    >>> # Custom transport registration
+    >>> from provide.foundation.transport import register_transport
+    >>> from provide.foundation.transport.types import TransportType
+    >>> 
+    >>> register_transport(TransportType("custom"), MyCustomTransport)
+
+Environment Configuration:
+    TRANSPORT_TIMEOUT=30.0
+    TRANSPORT_MAX_RETRIES=3
+    TRANSPORT_RETRY_BACKOFF_FACTOR=0.5
+    TRANSPORT_VERIFY_SSL=true
+    
+    HTTP_POOL_CONNECTIONS=10
+    HTTP_POOL_MAXSIZE=100
+    HTTP_FOLLOW_REDIRECTS=true
+    HTTP_USE_HTTP2=true
+    HTTP_MAX_REDIRECTS=5
+"""
+
+# Core transport abstractions
+from provide.foundation.transport.base import Request, Response
+
+# Transport types and configuration
+from provide.foundation.transport.config import HTTPConfig, TransportConfig
+from provide.foundation.transport.types import HTTPMethod, TransportType
+
+# Error types
+from provide.foundation.transport.errors import (
+    HTTPResponseError,
+    TransportConnectionError,
+    TransportError,
+    TransportNotFoundError,
+    TransportTimeoutError,
+)
+
+# Transport implementations
+from provide.foundation.transport.http import HTTPTransport
+
+# Middleware system
+from provide.foundation.transport.middleware import (
+    LoggingMiddleware,
+    MetricsMiddleware,
+    Middleware,
+    MiddlewarePipeline,
+    RetryMiddleware,
+    create_default_pipeline,
+)
+
+# Registry and discovery
+from provide.foundation.transport.registry import (
+    get_transport,
+    get_transport_info,
+    list_registered_transports,
+    register_transport,
+)
+
+# High-level client API
+from provide.foundation.transport.client import (
+    UniversalClient,
+    delete,
+    get,
+    get_default_client,
+    head,
+    options,
+    patch,
+    post,
+    put,
+    request,
+    stream,
+)
+
+__all__ = [
+    # Core abstractions
+    "Request",
+    "Response",
+    
+    # Configuration
+    "TransportConfig",
+    "HTTPConfig",
+    
+    # Types
+    "TransportType",
+    "HTTPMethod",
+    
+    # Errors
+    "TransportError",
+    "TransportConnectionError",
+    "TransportTimeoutError", 
+    "HTTPResponseError",
+    "TransportNotFoundError",
+    
+    # Transport implementations
+    "HTTPTransport",
+    
+    # Middleware
+    "Middleware",
+    "MiddlewarePipeline",
+    "LoggingMiddleware",
+    "RetryMiddleware",
+    "MetricsMiddleware",
+    "create_default_pipeline",
+    
+    # Registry
+    "register_transport",
+    "get_transport",
+    "get_transport_info",
+    "list_registered_transports",
+    
+    # Client API
+    "UniversalClient",
+    "get_default_client",
+    "request",
+    "get",
+    "post",
+    "put",
+    "patch", 
+    "delete",
+    "head",
+    "options",
+    "stream",
+]

provide/foundation/transport/base.py

@@ -0,0 +1,171 @@
+"""
+Core transport abstractions.
+"""
+
+import time
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any, Protocol, runtime_checkable
+
+from attrs import define, field
+
+from provide.foundation.logger import get_logger
+from provide.foundation.transport.types import Data, Headers, Params, TransportType
+
+log = get_logger(__name__)
+
+
+@define
+class Request:
+    """Protocol-agnostic request."""
+    
+    uri: str
+    method: str = "GET"
+    headers: Headers = field(factory=dict)
+    params: Params = field(factory=dict)
+    body: Data = None
+    timeout: float | None = None
+    metadata: dict[str, Any] = field(factory=dict)
+    
+    @property
+    def transport_type(self) -> TransportType:
+        """Infer transport type from URI scheme."""
+        scheme = self.uri.split("://")[0].lower()
+        try:
+            return TransportType(scheme)
+        except ValueError:
+            log.trace(f"Unknown scheme '{scheme}', defaulting to HTTP")
+            return TransportType.HTTP
+    
+    @property
+    def base_url(self) -> str:
+        """Extract base URL from URI."""
+        parts = self.uri.split("/")
+        if len(parts) >= 3:
+            return f"{parts[0]}//{parts[2]}"
+        return self.uri
+
+
+@define
+class Response:
+    """Protocol-agnostic response."""
+    
+    status: int
+    headers: Headers = field(factory=dict)
+    body: bytes | str | None = None
+    metadata: dict[str, Any] = field(factory=dict)
+    elapsed_ms: float = 0
+    request: Request | None = None
+    
+    def is_success(self) -> bool:
+        """Check if response indicates success."""
+        return 200 <= self.status < 300
+    
+    def json(self) -> Any:
+        """Parse response body as JSON."""
+        import json
+        
+        if isinstance(self.body, bytes):
+            return json.loads(self.body.decode('utf-8'))
+        elif isinstance(self.body, str):
+            return json.loads(self.body)
+        else:
+            raise ValueError("Response body is not JSON-parseable")
+    
+    @property
+    def text(self) -> str:
+        """Get response body as text."""
+        if isinstance(self.body, bytes):
+            return self.body.decode('utf-8')
+        elif isinstance(self.body, str):
+            return self.body
+        else:
+            return str(self.body or "")
+    
+    def raise_for_status(self) -> None:
+        """Raise error if response status indicates failure."""
+        if not self.is_success():
+            from provide.foundation.transport.errors import HTTPResponseError
+            raise HTTPResponseError(
+                f"Request failed with status {self.status}",
+                status_code=self.status,
+                response=self,
+            )
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """Abstract transport protocol."""
+    
+    async def execute(self, request: Request) -> Response:
+        """Execute a request and return response."""
+        ...
+    
+    async def stream(self, request: Request) -> AsyncIterator[bytes]:
+        """Stream response data."""
+        ...
+    
+    async def connect(self) -> None:
+        """Establish connection if needed."""
+        ...
+    
+    async def disconnect(self) -> None:
+        """Close connection if needed."""
+        ...
+    
+    def supports(self, transport_type: TransportType) -> bool:
+        """Check if this transport handles the given type."""
+        ...
+    
+    async def __aenter__(self) -> "Transport":
+        """Context manager entry."""
+        await self.connect()
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit."""
+        await self.disconnect()
+
+
+class TransportBase(ABC):
+    """Base class for transport implementations."""
+    
+    def __init__(self):
+        self._logger = get_logger(self.__class__.__name__)
+    
+    @abstractmethod
+    async def execute(self, request: Request) -> Response:
+        """Execute a request and return response."""
+        pass
+    
+    @abstractmethod
+    def supports(self, transport_type: TransportType) -> bool:
+        """Check if this transport handles the given type."""
+        pass
+    
+    async def connect(self) -> None:
+        """Default connect implementation."""
+        self._logger.trace("Transport connecting")
+    
+    async def disconnect(self) -> None:
+        """Default disconnect implementation."""
+        self._logger.trace("Transport disconnecting")
+    
+    async def stream(self, request: Request) -> AsyncIterator[bytes]:
+        """Default streaming implementation (not supported)."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not support streaming")
+    
+    async def __aenter__(self) -> "TransportBase":
+        await self.connect()
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.disconnect()
+
+
+__all__ = [
+    "Request",
+    "Response", 
+    "Transport",
+    "TransportBase",
+]

provide/foundation/transport/client.py

@@ -0,0 +1,266 @@
+"""
+Universal transport client with middleware support.
+"""
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from attrs import define, field
+
+from provide.foundation.logger import get_logger
+from provide.foundation.transport.base import Request, Response
+from provide.foundation.transport.middleware import MiddlewarePipeline, create_default_pipeline
+from provide.foundation.transport.registry import get_transport
+from provide.foundation.transport.types import Data, Headers, HTTPMethod, Params
+
+log = get_logger(__name__)
+
+
+@define
+class UniversalClient:
+    """Universal client that works with any transport via Hub registry."""
+    
+    middleware: MiddlewarePipeline = field(factory=create_default_pipeline)
+    default_headers: Headers = field(factory=dict)
+    default_timeout: float | None = field(default=None)
+    _transports: dict[str, Any] = field(factory=dict, init=False)
+    
+    async def request(
+        self,
+        uri: str,
+        method: str | HTTPMethod = HTTPMethod.GET,
+        *,
+        headers: Headers | None = None,
+        params: Params | None = None,
+        body: Data = None,
+        timeout: float | None = None,
+        **kwargs
+    ) -> Response:
+        """
+        Make a request using appropriate transport.
+        
+        Args:
+            uri: Full URI to make request to
+            method: HTTP method or protocol-specific method
+            headers: Request headers
+            params: Query parameters
+            body: Request body (dict for JSON, str/bytes for raw)
+            timeout: Request timeout override
+            **kwargs: Additional request metadata
+            
+        Returns:
+            Response from the transport
+        """
+        # Normalize method
+        if isinstance(method, HTTPMethod):
+            method = method.value
+        
+        # Merge headers
+        request_headers = dict(self.default_headers)
+        if headers:
+            request_headers.update(headers)
+        
+        # Create request object
+        request = Request(
+            uri=uri,
+            method=method,
+            headers=request_headers,
+            params=params or {},
+            body=body,
+            timeout=timeout or self.default_timeout,
+            metadata=kwargs,
+        )
+        
+        # Process through middleware
+        request = await self.middleware.process_request(request)
+        
+        try:
+            # Get transport for this URI
+            transport = await self._get_transport(request.transport_type.value)
+            
+            # Execute request
+            response = await transport.execute(request)
+            
+            # Process response through middleware
+            response = await self.middleware.process_response(response)
+            
+            return response
+            
+        except Exception as e:
+            # Process error through middleware
+            e = await self.middleware.process_error(e, request)
+            raise e
+    
+    async def stream(
+        self,
+        uri: str,
+        method: str | HTTPMethod = HTTPMethod.GET,
+        **kwargs
+    ) -> AsyncIterator[bytes]:
+        """
+        Stream data from URI.
+        
+        Args:
+            uri: URI to stream from
+            method: HTTP method or protocol-specific method
+            **kwargs: Additional request parameters
+            
+        Yields:
+            Chunks of response data
+        """
+        # Normalize method
+        if isinstance(method, HTTPMethod):
+            method = method.value
+        
+        # Create request
+        request = Request(
+            uri=uri,
+            method=method,
+            headers=dict(self.default_headers),
+            **kwargs
+        )
+        
+        # Get transport
+        transport = await self._get_transport(request.transport_type.value)
+        
+        # Stream response
+        log.info(f"🌊 Streaming {method} {uri}")
+        async for chunk in transport.stream(request):
+            yield chunk
+    
+    async def get(self, uri: str, **kwargs) -> Response:
+        """GET request."""
+        return await self.request(uri, HTTPMethod.GET, **kwargs)
+    
+    async def post(self, uri: str, **kwargs) -> Response:
+        """POST request."""
+        return await self.request(uri, HTTPMethod.POST, **kwargs)
+    
+    async def put(self, uri: str, **kwargs) -> Response:
+        """PUT request."""
+        return await self.request(uri, HTTPMethod.PUT, **kwargs)
+    
+    async def patch(self, uri: str, **kwargs) -> Response:
+        """PATCH request."""
+        return await self.request(uri, HTTPMethod.PATCH, **kwargs)
+    
+    async def delete(self, uri: str, **kwargs) -> Response:
+        """DELETE request."""
+        return await self.request(uri, HTTPMethod.DELETE, **kwargs)
+    
+    async def head(self, uri: str, **kwargs) -> Response:
+        """HEAD request."""
+        return await self.request(uri, HTTPMethod.HEAD, **kwargs)
+    
+    async def options(self, uri: str, **kwargs) -> Response:
+        """OPTIONS request."""
+        return await self.request(uri, HTTPMethod.OPTIONS, **kwargs)
+    
+    async def _get_transport(self, scheme: str) -> Any:
+        """Get or create transport for scheme."""
+        if scheme not in self._transports:
+            # Get transport class from registry
+            transport = get_transport(f"{scheme}://example.com")
+            await transport.connect()
+            self._transports[scheme] = transport
+        
+        return self._transports[scheme]
+    
+    async def __aenter__(self) -> "UniversalClient":
+        """Context manager entry."""
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit - cleanup all transports."""
+        for transport in self._transports.values():
+            try:
+                await transport.disconnect()
+            except Exception as e:
+                log.error(f"Error disconnecting transport: {e}")
+        self._transports.clear()
+
+
+# Global client instance for convenience functions
+_default_client: UniversalClient | None = None
+
+
+def get_default_client() -> UniversalClient:
+    """Get or create the default client instance."""
+    global _default_client
+    if _default_client is None:
+        _default_client = UniversalClient()
+    return _default_client
+
+
+async def request(
+    uri: str,
+    method: str | HTTPMethod = HTTPMethod.GET,
+    **kwargs
+) -> Response:
+    """Make a request using the default client."""
+    client = get_default_client()
+    return await client.request(uri, method, **kwargs)
+
+
+async def get(uri: str, **kwargs) -> Response:
+    """GET request using default client."""
+    client = get_default_client()
+    return await client.get(uri, **kwargs)
+
+
+async def post(uri: str, **kwargs) -> Response:
+    """POST request using default client."""
+    client = get_default_client()
+    return await client.post(uri, **kwargs)
+
+
+async def put(uri: str, **kwargs) -> Response:
+    """PUT request using default client."""
+    client = get_default_client()
+    return await client.put(uri, **kwargs)
+
+
+async def patch(uri: str, **kwargs) -> Response:
+    """PATCH request using default client."""
+    client = get_default_client()
+    return await client.patch(uri, **kwargs)
+
+
+async def delete(uri: str, **kwargs) -> Response:
+    """DELETE request using default client."""
+    client = get_default_client()
+    return await client.delete(uri, **kwargs)
+
+
+async def head(uri: str, **kwargs) -> Response:
+    """HEAD request using default client."""
+    client = get_default_client()
+    return await client.head(uri, **kwargs)
+
+
+async def options(uri: str, **kwargs) -> Response:
+    """OPTIONS request using default client."""
+    client = get_default_client()
+    return await client.options(uri, **kwargs)
+
+
+async def stream(uri: str, **kwargs) -> AsyncIterator[bytes]:
+    """Stream data using default client."""
+    client = get_default_client()
+    async for chunk in client.stream(uri, **kwargs):
+        yield chunk
+
+
+__all__ = [
+    "UniversalClient",
+    "get_default_client",
+    "request",
+    "get",
+    "post",
+    "put", 
+    "patch",
+    "delete",
+    "head",
+    "options",
+    "stream",
+]