httpware 0.8.1__tar.gz → 0.8.3__tar.gz

{httpware-0.8.1 → httpware-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.8.1
+Version: 0.8.3
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev
@@ -35,9 +35,9 @@ Description-Content-Type: text/markdown
 [![Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Async HTTP client framework for Python.**
+**A Python HTTP client framework with sync and async clients for building resilient service clients.**
 
-`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `AsyncRetry` middleware with a Finagle-style `RetryBudget`, plus an `AsyncBulkhead` concurrency limiter — under `httpware.middleware.resilience`.
+`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `AsyncRetry`/`Retry` middleware with a Finagle-style `RetryBudget`, plus an `AsyncBulkhead`/`Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
 
 > **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
@@ -101,6 +101,8 @@ async def main() -> None:
 
 Compose resilience middleware at construction; `AsyncBulkhead` goes outside `AsyncRetry` so one slot covers all retry attempts.
 
+The sync `Client` accepts identical `middleware=[...]`; swap `AsyncClient` → `Client` and `AsyncRetry` → `Retry` for the sync version.
+
 ```python
 from httpware import AsyncClient, AsyncBulkhead, AsyncRetry
 
@@ -143,7 +145,7 @@ All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `Se
 
 ## Observability
 
-`AsyncRetry` and `AsyncBulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed).
+`AsyncRetry`/`Retry` and `AsyncBulkhead`/`Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
 
 Logger names (`httpware.retry`, `httpware.bulkhead`) and event names (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`, `bulkhead.rejected`) are the stable public contract.
 

{httpware-0.8.1 → httpware-0.8.3}/README.md

@@ -5,9 +5,9 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Async HTTP client framework for Python.**
+**A Python HTTP client framework with sync and async clients for building resilient service clients.**
 
-`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `AsyncRetry` middleware with a Finagle-style `RetryBudget`, plus an `AsyncBulkhead` concurrency limiter — under `httpware.middleware.resilience`.
+`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `AsyncRetry`/`Retry` middleware with a Finagle-style `RetryBudget`, plus an `AsyncBulkhead`/`Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
 
 > **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
@@ -71,6 +71,8 @@ async def main() -> None:
 
 Compose resilience middleware at construction; `AsyncBulkhead` goes outside `AsyncRetry` so one slot covers all retry attempts.
 
+The sync `Client` accepts identical `middleware=[...]`; swap `AsyncClient` → `Client` and `AsyncRetry` → `Retry` for the sync version.
+
 ```python
 from httpware import AsyncClient, AsyncBulkhead, AsyncRetry
 
@@ -113,7 +115,7 @@ All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `Se
 
 ## Observability
 
-`AsyncRetry` and `AsyncBulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed).
+`AsyncRetry`/`Retry` and `AsyncBulkhead`/`Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
 
 Logger names (`httpware.retry`, `httpware.bulkhead`) and event names (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`, `bulkhead.rejected`) are the stable public contract.
 

{httpware-0.8.1 → httpware-0.8.3}/pyproject.toml

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

{httpware-0.8.1 → httpware-0.8.3}/src/httpware/client.py

@@ -132,7 +132,7 @@ class AsyncClient:
             async with _httpx2_exception_mapper():
                 response = await self._httpx2_client.send(request)
         except RuntimeError as exc:
-            if "closed" in str(exc):
+            if self._httpx2_client.is_closed:
                 raise TransportError(str(exc)) from exc
             raise
         _raise_on_status_error(response)
@@ -159,6 +159,28 @@ class AsyncClient:
         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."""
         return self._httpx2_client.build_request(method, url, **kwargs)
@@ -828,7 +850,7 @@ class Client:
             with _httpx2_exception_mapper_sync():
                 response = self._httpx2_client.send(request)
         except RuntimeError as exc:
-            if "closed" in str(exc):
+            if self._httpx2_client.is_closed:
                 raise TransportError(str(exc)) from exc
             raise
         _raise_on_status_error(response)
@@ -879,6 +901,28 @@ class Client:
         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."""
         return self._httpx2_client.build_request(method, url, **kwargs)

{httpware-0.8.1 → httpware-0.8.3}/src/httpware/decoders/__init__.py

@@ -1,4 +1,4 @@
-"""ResponseDecoder protocol — the AsyncClient ↔ ResponseDecoder seam (Seam 3)."""
+"""ResponseDecoder protocol — the Client/AsyncClient ↔ ResponseDecoder seam (Seam B)."""
 
 from typing import Protocol, TypeVar, runtime_checkable
 

{httpware-0.8.1 → httpware-0.8.3}/src/httpware/middleware/resilience/budget.py

@@ -8,6 +8,7 @@ coroutines on one event loop, and across (sync Client, AsyncClient) pairs
 in the same process.
 """
 
+import math
 import threading
 import time
 from collections import deque
@@ -64,7 +65,7 @@ class RetryBudget:
         with self._lock:
             self._purge(now)
             floor = int(self._min_retries_per_sec * self._ttl)
-            ceiling = int(len(self._deposits) * self._percent_can_retry) + floor
+            ceiling = math.ceil(len(self._deposits) * self._percent_can_retry) + floor
             if len(self._withdrawn) >= ceiling:
                 return False
             self._withdrawn.append(now)

{httpware-0.8.1 → httpware-0.8.3}/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()

{httpware-0.8.1 → httpware-0.8.3}/src/httpware/middleware/resilience/retry.py

@@ -47,6 +47,9 @@ DEFAULT_IDEMPOTENT_METHODS = frozenset(
 
 _MAX_ATTEMPTS_INVALID = "max_attempts must be >= 1"
 _STREAMING_BODY_REFUSAL_NOTE = "httpware: not retrying — request body is a stream that cannot replay across attempts"
+_RETRY_AFTER_EXCEEDS_MAX_DELAY_NOTE = (
+    "httpware: Retry-After ({retry_after}s) exceeded max_delay ({max_delay}s); giving up"
+)
 
 _LOGGER = logging.getLogger("httpware.retry")
 
@@ -100,23 +103,19 @@ class AsyncRetry:
         last_exc: BaseException | None = None
         last_response: httpx2.Response | None = None
 
+        self.budget.deposit()
         for attempt in range(self.max_attempts):
             is_last = attempt + 1 >= self.max_attempts
-            self.budget.deposit()
             try:
                 return await next(request)
             except StatusError as exc:
                 retryable_status = exc.response.status_code in self.retry_status_codes
                 if not method_eligible or not retryable_status:
-                    if retryable_status and request.extensions.get(STREAMING_BODY_MARKER):
-                        exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                     raise
                 last_exc = exc
                 last_response = exc.response
             except (NetworkError, TimeoutError) as exc:
                 if not method_eligible:
-                    if request.extensions.get(STREAMING_BODY_MARKER):
-                        exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                     raise
                 last_exc = exc
                 last_response = None
@@ -185,8 +184,19 @@ class AsyncRetry:
                 if header is not None:
                     retry_after = _parse_retry_after(header)
 
+            if retry_after is not None and retry_after > self.max_delay:
+                if last_exc is None:  # pragma: no cover — retry_after requires last_response which requires last_exc
+                    msg = "AsyncRetry: retry_after path reached with no last_exc"
+                    raise AssertionError(msg)
+                last_exc.add_note(
+                    _RETRY_AFTER_EXCEEDS_MAX_DELAY_NOTE.format(
+                        retry_after=retry_after,
+                        max_delay=self.max_delay,
+                    ),
+                )
+                raise last_exc
             if retry_after is not None:
-                delay = min(retry_after, self.max_delay)
+                delay = retry_after
             else:
                 delay = full_jitter_delay(
                     attempt,
@@ -231,23 +241,19 @@ class Retry:
         last_exc: BaseException | None = None
         last_response: httpx2.Response | None = None
 
+        self.budget.deposit()
         for attempt in range(self.max_attempts):
             is_last = attempt + 1 >= self.max_attempts
-            self.budget.deposit()
             try:
                 return next(request)
             except StatusError as exc:
                 retryable_status = exc.response.status_code in self.retry_status_codes
                 if not method_eligible or not retryable_status:
-                    if retryable_status and request.extensions.get(STREAMING_BODY_MARKER):
-                        exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                     raise
                 last_exc = exc
                 last_response = exc.response
             except (NetworkError, TimeoutError) as exc:
                 if not method_eligible:
-                    if request.extensions.get(STREAMING_BODY_MARKER):
-                        exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                     raise
                 last_exc = exc
                 last_response = None
@@ -316,8 +322,19 @@ class Retry:
                 if header is not None:
                     retry_after = _parse_retry_after(header)
 
+            if retry_after is not None and retry_after > self.max_delay:
+                if last_exc is None:  # pragma: no cover — retry_after requires last_response which requires last_exc
+                    msg = "Retry: retry_after path reached with no last_exc"
+                    raise AssertionError(msg)
+                last_exc.add_note(
+                    _RETRY_AFTER_EXCEEDS_MAX_DELAY_NOTE.format(
+                        retry_after=retry_after,
+                        max_delay=self.max_delay,
+                    ),
+                )
+                raise last_exc
             if retry_after is not None:
-                delay = min(retry_after, self.max_delay)
+                delay = retry_after
             else:
                 delay = full_jitter_delay(
                     attempt,