bookalimo 0.1.5__py3-none-any.whl → 1.0.1__py3-none-any.whl

bookalimo/transport/httpx_sync.py

@@ -0,0 +1,230 @@
+"""Sync HTTP transport using httpx."""
+
+import logging
+from time import perf_counter
+from typing import Any, Optional, TypeVar, Union, overload
+from uuid import uuid4
+
+import httpx
+from pydantic import BaseModel
+
+from ..config import (
+    DEFAULT_BACKOFF,
+    DEFAULT_BASE_URL,
+    DEFAULT_RETRIES,
+    DEFAULT_TIMEOUTS,
+    DEFAULT_USER_AGENT,
+)
+from ..exceptions import (
+    BookalimoConnectionError,
+    BookalimoError,
+    BookalimoHTTPError,
+    BookalimoRequestError,
+    BookalimoTimeout,
+)
+from .auth import Credentials, inject_credentials
+from .base import BaseTransport
+from .retry import should_retry_exception, should_retry_status, sync_retry
+from .utils import handle_api_errors, handle_http_error
+
+logger = logging.getLogger("bookalimo.transport")
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class SyncTransport(BaseTransport):
+    """Sync HTTP transport using httpx."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeouts: Any = DEFAULT_TIMEOUTS,
+        user_agent: str = DEFAULT_USER_AGENT,
+        credentials: Optional[Credentials] = None,
+        client: Optional[httpx.Client] = None,
+        retries: int = DEFAULT_RETRIES,
+        backoff: float = DEFAULT_BACKOFF,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.credentials = credentials
+        self.retries = retries
+        self.backoff = backoff
+        self.headers = {
+            "content-type": "application/json",
+            "user-agent": user_agent,
+        }
+
+        # Create client if not provided
+        self._owns_client = client is None
+        self.client = client or httpx.Client(timeout=timeouts)
+
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "SyncTransport initialized (base_url=%s, timeout=%s, user_agent=%s)",
+                self.base_url,
+                timeouts,
+                user_agent,
+            )
+
+    @overload
+    def post(self, path: str, model: BaseModel) -> Any: ...
+    @overload
+    def post(self, path: str, model: BaseModel, response_model: type[T]) -> T: ...
+
+    def post(
+        self, path: str, model: BaseModel, response_model: Optional[type[T]] = None
+    ) -> Union[T, Any]:
+        """Make a POST request and return parsed response."""
+        # Prepare URL
+        path = path if path.startswith("/") else f"/{path}"
+        url = f"{self.base_url}{path}"
+
+        # Prepare data and inject credentials
+        data = self.prepare_data(model)
+        data = inject_credentials(data, self.credentials)
+
+        # Debug logging
+        req_id = None
+        start = 0.0
+        if logger.isEnabledFor(logging.DEBUG):
+            req_id = uuid4().hex[:8]
+            start = perf_counter()
+            body_keys = sorted(k for k in data.keys() if k != "credentials")
+            logger.debug(
+                "→ [%s] POST %s body_keys=%s",
+                req_id,
+                path,
+                body_keys,
+            )
+
+        try:
+            # Make request with retry logic
+            response = sync_retry(
+                lambda: self._make_request(url, data),
+                retries=self.retries,
+                backoff=self.backoff,
+                should_retry=lambda e: should_retry_exception(e)
+                or (
+                    isinstance(e, httpx.HTTPStatusError)
+                    and should_retry_status(e.response.status_code)
+                ),
+            )
+
+            # Handle HTTP errors
+            if response.status_code >= 400:
+                handle_http_error(response, req_id, path)
+
+            # Parse JSON
+            try:
+                json_data = response.json()
+            except ValueError as e:
+                if logger.isEnabledFor(logging.DEBUG):
+                    logger.warning("× [%s] %s invalid JSON", req_id or "-", path)
+                preview = (
+                    (response.text or "")[:256] if hasattr(response, "text") else None
+                )
+                raise BookalimoError(
+                    f"Invalid JSON response: {preview}",
+                ) from e
+
+            # Handle API-level errors
+            handle_api_errors(json_data, req_id, path)
+
+            # Debug logging for success
+            if logger.isEnabledFor(logging.DEBUG):
+                dur_ms = (perf_counter() - start) * 1000.0
+                reqid_hdr = response.headers.get(
+                    "x-request-id"
+                ) or response.headers.get("request-id")
+                content_len = (
+                    len(response.content) if hasattr(response, "content") else None
+                )
+                logger.debug(
+                    "← [%s] %s %s in %.1f ms len=%s reqid=%s",
+                    req_id,
+                    response.status_code,
+                    path,
+                    dur_ms,
+                    content_len,
+                    reqid_hdr,
+                )
+
+            # Parse and return response
+            return (
+                response_model.model_validate(json_data)
+                if response_model
+                else json_data
+            )
+
+        except httpx.TimeoutException:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.warning("× [%s] %s timeout", req_id or "-", path)
+            raise BookalimoTimeout("Request timeout") from None
+
+        except httpx.ConnectError:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.warning("× [%s] %s connection error", req_id or "-", path)
+            raise BookalimoConnectionError(
+                "Connection error - unable to reach Book-A-Limo API"
+            ) from None
+        except httpx.RequestError as e:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.warning(
+                    "× [%s] %s request error: %s",
+                    req_id or "-",
+                    path,
+                    e.__class__.__name__,
+                )
+            raise BookalimoRequestError(f"Request Error: {e}") from e
+
+        except httpx.HTTPStatusError as e:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.warning(
+                    "× [%s] %s HTTP error: %s",
+                    req_id or "-",
+                    path,
+                    e.__class__.__name__,
+                )
+            status_code = getattr(getattr(e, "response", None), "status_code", None)
+            raise BookalimoHTTPError(f"HTTP Error: {e}", status_code=status_code) from e
+
+        except (BookalimoError, BookalimoHTTPError):
+            # Already handled above
+            raise
+
+        except Exception as e:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.warning(
+                    "× [%s] %s unexpected error: %s",
+                    req_id or "-",
+                    path,
+                    e.__class__.__name__,
+                )
+            raise BookalimoError(f"Unexpected error: {str(e)}") from e
+
+    def _make_request(self, url: str, data: dict[str, Any]) -> httpx.Response:
+        """Make the actual HTTP request."""
+        resp = self.client.post(url, json=data, headers=self.headers)
+        if should_retry_status(resp.status_code):
+            # Construct an HTTPStatusError so sync_retry can catch & decide.
+            raise httpx.HTTPStatusError(
+                message=f"Retryable HTTP status: {resp.status_code}",
+                request=resp.request,
+                response=resp,
+            )
+        return resp
+
+    def close(self) -> None:
+        """Close the HTTP client if we own it."""
+        if self._owns_client and not self.client.is_closed:
+            self.client.close()
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug("SyncTransport HTTP client closed")
+
+    def __enter__(self) -> "SyncTransport":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.close()

bookalimo/transport/retry.py

@@ -0,0 +1,102 @@
+"""Retry logic and backoff utilities."""
+
+import asyncio
+import random
+from collections.abc import Awaitable
+from typing import Callable, TypeVar, Union
+
+import httpx
+
+from ..config import DEFAULT_STATUS_FORCELIST
+
+T = TypeVar("T")
+
+
+def should_retry_status(
+    status_code: int, status_forcelist: tuple[int, ...] = DEFAULT_STATUS_FORCELIST
+) -> bool:
+    """Check if a status code should trigger a retry."""
+    return status_code in status_forcelist
+
+
+def should_retry_exception(exc: Exception) -> bool:
+    """Check if an exception should trigger a retry."""
+    return isinstance(
+        exc,
+        (
+            httpx.TimeoutException,
+            httpx.ConnectError,
+            httpx.ReadTimeout,
+            httpx.ConnectError,
+            ConnectionError,
+        ),
+    )
+
+
+def calculate_backoff(attempt: int, base_backoff: float) -> float:
+    """Calculate exponential backoff with jitter."""
+    # Exponential backoff: base * (2 ^ attempt)
+    backoff = base_backoff * (2**attempt)
+    # Add jitter: ±25% randomization
+    jitter = backoff * 0.25 * (random.random() * 2 - 1)  # nosec B311: non-crypto jitter
+    return float(max(0.1, backoff + jitter))  # Minimum 100ms
+
+
+async def async_retry(
+    func: Callable[[], Awaitable[T]],
+    retries: int,
+    backoff: float,
+    should_retry: Callable[[Exception], bool],
+) -> T:
+    """Retry an async function with exponential backoff."""
+    attempt = 0
+    last_exc: Union[Exception, None] = None
+
+    while attempt <= retries:
+        try:
+            return await func()
+        except Exception as e:
+            last_exc = e
+            if attempt >= retries or not should_retry(e):
+                break
+
+            wait_time = calculate_backoff(attempt, backoff)
+            await asyncio.sleep(wait_time)
+            attempt += 1
+
+    if last_exc is not None:
+        raise last_exc
+    else:
+        raise RuntimeError("Last exception is None")
+
+
+def sync_retry(
+    func: Callable[[], T],
+    retries: int,
+    backoff: float,
+    should_retry: Callable[[Exception], bool],
+) -> T:
+    """Retry a sync function with exponential backoff."""
+    import time
+
+    attempt = 0
+    last_exc: Union[Exception, None] = None
+
+    while attempt <= retries:
+        try:
+            return func()
+        except Exception as e:
+            last_exc = e
+            if attempt >= retries or not should_retry(e):
+                break
+
+            wait_time = calculate_backoff(attempt, backoff)
+            time.sleep(wait_time)
+            attempt += 1
+
+    # Re-raise the last exception
+    if last_exc is not None:
+        raise last_exc
+    else:
+        raise RuntimeError("Last exception is None")
+    raise last_exc

bookalimo/transport/utils.py

@@ -0,0 +1,59 @@
+import logging
+from typing import Any, Optional
+
+import httpx
+
+from ..exceptions import BookalimoError, BookalimoHTTPError, BookalimoTimeout
+
+logger = logging.getLogger("bookalimo.transport")
+
+
+def handle_api_errors(
+    json_data: Any,
+    req_id: Optional[str],
+    path: str,
+) -> None:
+    """Handle API-level errors in the response."""
+    if not isinstance(json_data, dict):
+        return
+
+    if json_data.get("error"):
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.warning("× [%s] %s API error", req_id or "-", path)
+        raise BookalimoError(f"API Error: {json_data['error']}")
+
+    if "success" in json_data and not json_data["success"]:
+        msg = json_data.get("error", "Unknown API error")
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.warning("× [%s] %s API error", req_id or "-", path)
+        raise BookalimoError(f"API Error: {msg}")
+
+
+def handle_http_error(
+    response: httpx.Response, req_id: Optional[str], path: str
+) -> None:
+    """Handle HTTP status errors."""
+    status = response.status_code
+
+    if status == 408:
+        raise BookalimoTimeout(f"HTTP {status}: Request timeout")
+    elif status in (502, 503, 504):
+        raise BookalimoHTTPError(
+            f"HTTP {status}: Service unavailable", status_code=status
+        )
+
+    # Try to parse error payload
+    try:
+        payload = response.json()
+    except Exception as e:
+        text_preview = (response.text or "")[:256] if hasattr(response, "text") else ""
+        raise BookalimoHTTPError(
+            f"HTTP {status}: {text_preview}",
+            status_code=status,
+        ) from e
+
+    raise BookalimoHTTPError(
+        f"HTTP {status}",
+        status_code=status,
+        payload=payload if isinstance(payload, dict) else {"raw": payload},
+    )