docs(engineering): note Async*/async_* rename + attempt_timeout removal

Author: lesnik512

planning/engineering.md

@@ -6,6 +6,8 @@ This doc is the single distilled reference for `httpware` design rationale, prot
 
 `httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request` and `httpx2.Response` as the public request/response surface and adds three things on top: typed response decoding (via a `ResponseDecoder` protocol; pydantic and msgspec are both opt-in extras as of 0.3.0), a middleware chain composed at client construction, and a status-keyed exception tree raised automatically on 4xx and 5xx. `AsyncClient(decoder=None)` defaults to constructing a `PydanticDecoder` and so requires the `pydantic` extra; callers can supply an explicit `decoder=` argument to escape the default. As of 0.4.0, the package ships a small resilience suite under `httpware.middleware.resilience` — a `Retry` middleware with a Finagle-style `RetryBudget`, plus a `Bulkhead` concurrency limiter — composed via the standard middleware chain. As of 0.5.0, `AsyncClient.stream()` provides a context-manager API for chunked response bodies; it bypasses the middleware chain by design (see planning/archive/specs/2026-06-05-streaming-design.md). As of 0.6.0, `Retry` and `Bulkhead` emit operational events via stdlib `logging` records (`httpware.retry` / `httpware.bulkhead` loggers) and — when `opentelemetry-api` is installed — OpenTelemetry span events on the active span. As of 0.7.0, the first-cut user-docs surface is live at <https://httpware.readthedocs.io/> (Middleware, Resilience, Errors, Testing guides) and Epic 3 is closed.
 
+The next release renames the async middleware surface to use the `Async*`/`async_*` prefix (aligning with httpx2's convention) and removes the seldom-used `attempt_timeout=` kwarg from `AsyncRetry` — see `planning/specs/2026-06-07-sync-client-design.md` for the rationale.
+
 The 0.1.0 release attempted to own a full abstraction over the underlying HTTP client. v0.2 walks that back: `httpx2` is part of the public surface.
 
 ## 2. Architectural invariants (CI-enforced)
@@ -26,10 +28,10 @@ A protocol seam is a documented internal boundary. AI agents and contributors mu
 
 The 0.1.0 seams numbered 1 (Middleware↔Transport) and 4 (Transport↔httpx2) have collapsed into the `AsyncClient` terminal — there is no transport abstraction in v0.2.
 
-### Seam A: `AsyncClient ↔ Middleware`
+### Seam A: `AsyncClient ↔ AsyncMiddleware`
 
 - **Where:** `src/httpware/client.py` ↔ `src/httpware/middleware/`.
-- **Contract:** the middleware chain is composed once at `AsyncClient.__init__` and frozen for the client's lifetime. The chain bottom (the "terminal") is internal: it calls `self._httpx2_client.send(request)`, maps `httpx2` errors to `httpware` errors, and raises a `StatusError` subclass on 4xx/5xx.
+- **Contract:** the `AsyncMiddleware` chain is composed once via `compose_async` at `AsyncClient.__init__` and frozen for the client's lifetime. The chain bottom (the "terminal") is internal: it calls `self._httpx2_client.send(request)`, maps `httpx2` errors to `httpware` errors, and raises a `StatusError` subclass on 4xx/5xx. The continuation type passed to each middleware is `AsyncNext`.
 - **Rule:** mutating the chain after construction is not supported. Per-request behavior goes through `httpx2.Request.extensions` or through `extensions=` kwargs at call sites.
 
 ### Seam B: `AsyncClient ↔ ResponseDecoder`
@@ -72,13 +74,13 @@ src/httpware/
 ├── client.py              # AsyncClient
 ├── errors.py              # status-keyed exception tree + NetworkError + RetryBudgetExhaustedError + BulkheadFullError
 ├── middleware/
-│   ├── __init__.py        # Middleware protocol, Next type, @before_request/@after_response/@on_error
-│   ├── chain.py           # compose(middleware, terminal) -> Next
+│   ├── __init__.py        # AsyncMiddleware protocol, AsyncNext type, @async_before_request/@async_after_response/@async_on_error
+│   ├── chain.py           # compose_async(middleware, terminal) -> AsyncNext
 │   └── resilience/
-│       ├── __init__.py    # re-exports Bulkhead, Retry, RetryBudget
-│       ├── bulkhead.py    # Bulkhead middleware (concurrency limiter)
+│       ├── __init__.py    # re-exports AsyncBulkhead, AsyncRetry, RetryBudget
+│       ├── bulkhead.py    # AsyncBulkhead middleware (concurrency limiter)
 │       ├── budget.py      # RetryBudget (Finagle-style token bucket)
-│       ├── retry.py       # Retry middleware
+│       ├── retry.py       # AsyncRetry middleware
 │       └── _backoff.py    # full-jitter exponential backoff helper (private)
 ├── decoders/
 │   ├── __init__.py        # ResponseDecoder protocol

src/httpware/client.py

@@ -74,7 +74,7 @@ def _raise_on_status_error(response: httpx2.Response) -> None:
 STREAMING_BODY_MARKER = "httpware.streaming_body"
 """Key set on ``httpx2.Request.extensions`` by ``_request_with_body`` when content/data/files is an async-iterable.
 
-``Retry.__call__`` reads this marker to refuse retrying a streamed-body request
+``AsyncRetry.__call__`` reads this marker to refuse retrying a streamed-body request
 (the consumed iterator cannot replay across attempts)."""
 
 
@@ -718,7 +718,7 @@ async def stream(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signature
         The body is NOT pre-read for 2xx/3xx (streaming preserved); the response
         is closed when the context exits.
 
-        Bypasses the middleware chain (no Retry, no Bulkhead, no user-installed
+        Bypasses the middleware chain (no AsyncRetry, no AsyncBulkhead, no user-installed
         middleware) for v1 — see planning/specs/2026-06-05-streaming-design.md.
 
         Auto-raises StatusError subclasses on 4xx/5xx (NotFoundError,

src/httpware/errors.py

@@ -194,7 +194,7 @@ def _reconstruct_bulkhead_full(
 
 
 class BulkheadFullError(ClientError):
-    """Raised when ``acquire_timeout`` elapses before a Bulkhead slot becomes available.
+    """Raised when ``acquire_timeout`` elapses before an AsyncBulkhead slot becomes available.
 
     Carries the configured caps for caller logging/alerting.
     """

src/httpware/middleware/__init__.py

@@ -1,6 +1,6 @@
 """AsyncMiddleware protocol, AsyncNext type, and phase-shortcut decorators.
 
-Middleware operates directly on httpx2.Request / httpx2.Response — there is
+AsyncMiddleware operates directly on httpx2.Request / httpx2.Response — there is
 no httpware-owned request type. The chain is composed at AsyncClient.__init__
 (see client.py) and frozen for the client's lifetime.
 """

src/httpware/middleware/resilience/bulkhead.py

@@ -1,4 +1,4 @@
-"""Bulkhead middleware — concurrency limiter via asyncio.Semaphore.
+"""AsyncBulkhead middleware — concurrency limiter via asyncio.Semaphore.
 
 See planning/specs/2026-06-05-bulkhead-design.md for the contract.
 
@@ -7,7 +7,7 @@
 releases the slot in a try/finally so success, exceptions, and cancellation
 all release deterministically.
 
-Bulkhead is the sharable unit — pass the same instance to multiple
+AsyncBulkhead is the sharable unit — pass the same instance to multiple
 AsyncClient(middleware=[shared]) calls to enforce a joint cap across clients.
 """
 
@@ -33,7 +33,7 @@ class AsyncBulkhead:
     Parameters
     ----------
     max_concurrent
-        Required. Maximum number of in-flight requests this Bulkhead permits.
+        Required. Maximum number of in-flight requests this AsyncBulkhead permits.
         Must be ``>= 1``. There is no default because no value is universally
         correct — the right cap depends on downstream capacity and SLA.
     acquire_timeout

src/httpware/middleware/resilience/retry.py

@@ -1,9 +1,9 @@
-"""Retry middleware — automatic retry of transient failures with budget control.
+"""AsyncRetry middleware — automatic retry of transient failures with budget control.
 
 See planning/specs/2026-06-05-retry-and-retry-budget-design.md for the full contract.
 
 Status-code retry: the AsyncClient terminal raises StatusError subclasses on 4xx/5xx,
-so Retry catches StatusError and inspects exc.response.status_code. The original
+so AsyncRetry catches StatusError and inspects exc.response.status_code. The original
 StatusError subclass is re-raised unwrapped on exhaustion, with a PEP 678 note added.
 """
 
@@ -123,7 +123,7 @@ async def __call__(self, request: httpx2.Request, next: AsyncNext) -> httpx2.Res
             # ---- retryable failure path
             if request.extensions.get(STREAMING_BODY_MARKER):
                 if last_exc is None:  # pragma: no cover — invariant from except branch
-                    msg = "Retry: streaming-body refusal reached with no last_exc"
+                    msg = "AsyncRetry: streaming-body refusal reached with no last_exc"
                     raise AssertionError(msg)
                 last_exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                 _emit_event(
@@ -141,7 +141,7 @@ async def __call__(self, request: httpx2.Request, next: AsyncNext) -> httpx2.Res
 
             if is_last:
                 if last_exc is None:  # pragma: no cover — structural invariant from except branch
-                    msg = "Retry: last_exc unset on final attempt — unreachable"
+                    msg = "AsyncRetry: last_exc unset on final attempt — unreachable"
                     raise AssertionError(msg)
                 last_exc.add_note(f"httpware: gave up after {attempt + 1} attempts")
                 _emit_event(