httpware 0.8.0__tar.gz → 0.8.2__tar.gz

{httpware-0.8.0 → httpware-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.8.0
+Version: 0.8.2
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev
@@ -79,7 +79,7 @@ with Client(base_url="https://example.test") as client:
     print(response.json())
 ```
 
-Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`:
+Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`. Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
 
 ```python
 from httpware import AsyncClient

{httpware-0.8.0 → httpware-0.8.2}/README.md

@@ -49,7 +49,7 @@ with Client(base_url="https://example.test") as client:
     print(response.json())
 ```
 
-Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`:
+Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`. Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
 
 ```python
 from httpware import AsyncClient

{httpware-0.8.0 → httpware-0.8.2}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.8.0"
+version = "0.8.2"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]

{httpware-0.8.0 → httpware-0.8.2}/src/httpware/__init__.py

@@ -9,6 +9,7 @@ from httpware.errors import (
     ClientError,
     ClientStatusError,
     ConflictError,
+    DecodeError,
     ForbiddenError,
     InternalServerError,
     NetworkError,
@@ -52,6 +53,7 @@ __all__ = [
     "ClientError",
     "ClientStatusError",
     "ConflictError",
+    "DecodeError",
     "ForbiddenError",
     "InternalServerError",
     "Middleware",

{httpware-0.8.0 → httpware-0.8.2}/src/httpware/client.py

@@ -16,7 +16,7 @@ from httpware._internal.status import (
     _raise_on_status_error,
 )
 from httpware.decoders import ResponseDecoder
-from httpware.errors import TransportError
+from httpware.errors import DecodeError, TransportError
 from httpware.middleware import AsyncMiddleware, AsyncNext, Middleware, Next
 from httpware.middleware.chain import compose, compose_async
 
@@ -154,7 +154,32 @@ class AsyncClient:
         response = await self._dispatch(request)
         if response_model is None:
             return response
-        return self._decoder.decode(response.content, response_model)
+        try:
+            return self._decoder.decode(response.content, response_model)
+        except Exception as exc:
+            raise DecodeError(response=response, model=response_model, original=exc) from exc
+
+    async def send_with_response(
+        self,
+        request: httpx2.Request,
+        *,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send `request` through the middleware chain; return (response, decoded).
+
+        Use this when you need response metadata (headers, status, request URL)
+        AND a typed body — most commonly for Link-header pagination. For the
+        body-only case, prefer ``send(request, response_model=...)``.
+
+        Not for streaming responses — decodes ``response.content``, which
+        requires the body to be fully read. Use ``stream()`` for streaming.
+        """
+        response = await self._dispatch(request)
+        try:
+            decoded = self._decoder.decode(response.content, response_model)
+        except Exception as exc:
+            raise DecodeError(response=response, model=response_model, original=exc) from exc
+        return response, decoded
 
     def build_request(self, method: str, url: str, **kwargs: typing.Any) -> httpx2.Request:
         """Delegate request construction to the wrapped httpx2.AsyncClient."""
@@ -871,7 +896,32 @@ class Client:
         response = self._dispatch(request)
         if response_model is None:
             return response
-        return self._decoder.decode(response.content, response_model)
+        try:
+            return self._decoder.decode(response.content, response_model)
+        except Exception as exc:
+            raise DecodeError(response=response, model=response_model, original=exc) from exc
+
+    def send_with_response(
+        self,
+        request: httpx2.Request,
+        *,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send `request` through the middleware chain; return (response, decoded).
+
+        Use this when you need response metadata (headers, status, request URL)
+        AND a typed body — most commonly for Link-header pagination. For the
+        body-only case, prefer ``send(request, response_model=...)``.
+
+        Not for streaming responses — decodes ``response.content``, which
+        requires the body to be fully read. Use ``stream()`` for streaming.
+        """
+        response = self._dispatch(request)
+        try:
+            decoded = self._decoder.decode(response.content, response_model)
+        except Exception as exc:
+            raise DecodeError(response=response, model=response_model, original=exc) from exc
+        return response, decoded
 
     def build_request(self, method: str, url: str, **kwargs: typing.Any) -> httpx2.Request:
         """Delegate request construction to the wrapped httpx2.Client."""

{httpware-0.8.0 → httpware-0.8.2}/src/httpware/decoders/__init__.py

@@ -11,7 +11,12 @@ class ResponseDecoder(Protocol):
     """Structural protocol every response-body decoder satisfies."""
 
     def decode(self, content: bytes, model: type[T]) -> T:
-        """Decode `content` (raw response bytes) into an instance of `model`."""
+        """Decode `content` (raw response bytes) into an instance of `model`.
+
+        Any exception raised by `decode` is wrapped by `Client.send` /
+        `AsyncClient.send` into `httpware.DecodeError`; implementers do not
+        need to raise `DecodeError` directly.
+        """
         ...
 
 

{httpware-0.8.0 → httpware-0.8.2}/src/httpware/errors.py

@@ -212,3 +212,45 @@ class BulkheadFullError(ClientError):
             _reconstruct_bulkhead_full,
             (type(self), self.max_concurrent, self.acquire_timeout),
         )
+
+
+def _reconstruct_decode_error(
+    cls: "type[DecodeError]",
+    response: httpx2.Response,
+    model: type,
+    original: BaseException,
+) -> "DecodeError":
+    return cls(response=response, model=model, original=original)
+
+
+class DecodeError(ClientError):
+    """Raised when the active ResponseDecoder failed to decode response.content.
+
+    The HTTP call itself succeeded — status was 2xx/3xx and the transport
+    delivered the body intact — but the body could not be parsed into the
+    requested response_model. Always chained from the underlying library
+    exception via ``raise ... from exc``; that exception is also exposed as
+    ``self.original`` for structured handling.
+    """
+
+    response: httpx2.Response
+    model: type
+    original: BaseException
+
+    def __init__(
+        self,
+        *,
+        response: httpx2.Response,
+        model: type,
+        original: BaseException,
+    ) -> None:
+        self.response = response
+        self.model = model
+        self.original = original
+        super().__init__(f"failed to decode response into {model.__name__}: {original}")
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (
+            _reconstruct_decode_error,
+            (type(self), self.response, self.model, self.original),
+        )

{httpware-0.8.0 → httpware-0.8.2}/src/httpware/middleware/resilience/bulkhead.py

@@ -9,6 +9,13 @@ all release deterministically.
 
 AsyncBulkhead is the sharable unit — pass the same instance to multiple
 AsyncClient(middleware=[shared]) calls to enforce a joint cap across clients.
+
+AsyncBulkhead is single-event-loop: the underlying asyncio.Semaphore binds
+to whichever loop first awaits it, and cross-loop wake-ups are not thread
+safe. A single instance acquired from a second event loop (e.g. another
+thread running asyncio.run) raises RuntimeError on entry rather than
+deadlocking silently. To cap a sync+async or cross-thread workload, use
+a Bulkhead and an AsyncBulkhead with matching max_concurrent.
 """
 
 import asyncio
@@ -24,6 +31,11 @@ from httpware.middleware import AsyncNext, Next
 
 _MAX_CONCURRENT_INVALID = "max_concurrent must be >= 1"
 _ACQUIRE_TIMEOUT_INVALID = "acquire_timeout must be >= 0"
+_ASYNCBULKHEAD_CROSS_LOOP_MSG = (
+    "AsyncBulkhead is bound to a single event loop. First seen on {first!r}; "
+    "current request is on {current!r}. Use one AsyncBulkhead per loop; "
+    "cross-thread sharing requires the sync Bulkhead primitive."
+)
 
 _LOGGER = logging.getLogger("httpware.bulkhead")
 
@@ -42,7 +54,8 @@ class AsyncBulkhead:
         Defaults to ``1.0``. ``None`` waits forever; ``0`` fails fast. Must be
         ``>= 0`` (or ``None``).
 
-    See the module docstring for the algorithm and middleware-ordering guidance.
+    See the module docstring for the algorithm, middleware-ordering guidance,
+    and the single-event-loop constraint.
 
     """
 
@@ -59,9 +72,32 @@ class AsyncBulkhead:
         self._max_concurrent = max_concurrent
         self._acquire_timeout = acquire_timeout
         self._sem = asyncio.Semaphore(max_concurrent)
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._loop_lock = threading.Lock()
+
+    def _check_loop(self) -> None:
+        current = asyncio.get_running_loop()
+        cached = self._loop
+        if cached is current:
+            return
+        if cached is not None:
+            raise RuntimeError(
+                _ASYNCBULKHEAD_CROSS_LOOP_MSG.format(first=cached, current=current),
+            )
+        with self._loop_lock:
+            if self._loop is None:
+                self._loop = current
+            # pragma below: inner double-check-with-lock race arm; only
+            # reachable when two threads simultaneously pass the outer
+            # cached-loop check, which single-threaded tests can't trigger.
+            elif self._loop is not current:  # pragma: no cover
+                raise RuntimeError(
+                    _ASYNCBULKHEAD_CROSS_LOOP_MSG.format(first=self._loop, current=current),
+                )
 
     async def __call__(self, request: httpx2.Request, next: AsyncNext) -> httpx2.Response:  # noqa: A002
         """Acquire a slot (bounded by acquire_timeout), invoke next, release."""
+        self._check_loop()
         try:
             if self._acquire_timeout is None:
                 await self._sem.acquire()