|
| 1 | +# Middleware protocol and chain composition (design) |
| 2 | + |
| 3 | +- **Date:** 2026-05-31 |
| 4 | +- **Status:** approved, ready for plan |
| 5 | +- **Scope:** Story 2-1 (first story of Epic 2). Defines the `Middleware` Protocol, `Next` type alias, and the `compose()` chain composer. Out of scope: decorators (2-2), `Request` helpers (2-3), auth coercion (2-4), AsyncClient wiring (2-5), streaming middleware chain (Epic 4). |
| 6 | +- **Roadmap pointer:** `docs/engineering.md` §8 "Epic 2 — Compose request-handling logic via middleware". |
| 7 | + |
| 8 | +## Why |
| 9 | + |
| 10 | +Epic 2 makes `httpware` extensible: consumers write middleware to add tracing, signing, correlation IDs, etc., and built-in resilience (retry, bulkhead, timeout) lives on the same axis. Story 2-1 is the foundation — it ships the protocol surface, the `Next` callable type, and the composition mechanism. Nothing else in Epic 2 can land until this seam (Seam 2: `AsyncClient ↔ Middleware`) is defined. |
| 11 | + |
| 12 | +The shape is essentially decided by the archived architecture document (`docs/archive/architecture.md` "Middleware Execution Model"): a recursive async-callable onion. This spec ports that design forward with a few small choices that the archive left open. |
| 13 | + |
| 14 | +## Decisions |
| 15 | + |
| 16 | +| Decision | Choice | |
| 17 | +| --- | --- | |
| 18 | +| Protocol shape | `@runtime_checkable Protocol` with `async def __call__(self, request: Request, next: Next) -> Response`. Matches `Transport` and `ResponseDecoder`. | |
| 19 | +| `Next` type | `Next: TypeAlias = Callable[[Request], Awaitable[Response]]`. PEP 695 `type Next = ...` would require 3.12+; project floor is 3.11. | |
| 20 | +| Composition | Recursive closure fold via `_internal/chain.compose(middlewares, transport) -> Next`. Bottom of chain is `transport.__call__` (bound method, no wrapper). | |
| 21 | +| Empty list | `compose([], transport)` returns `transport.__call__` directly (identity at the bottom). | |
| 22 | +| Sequence type | `Sequence[Middleware]` over `list[Middleware]` — accepts tuples; no mutation required. | |
| 23 | +| Cancellation | No `try`/`except` blocks in `compose` or `_wrap`; `CancelledError` and all other exceptions propagate untouched. Verified by test. | |
| 24 | +| Scope | Strict epic boundary. Stories 2-2 through 2-5 land as their own units. | |
| 25 | +| Public exports | Both `httpware.middleware.{Middleware, Next}` and `httpware.{Middleware, Next}`. Matches the existing `Request` / `Response` / `Httpx2Transport` re-export pattern at package root. | |
| 26 | +| `compose` visibility | Private (`_internal/chain.compose`). Consumers don't compose chains; AsyncClient (Story 2-5) does. | |
| 27 | + |
| 28 | +## File structure |
| 29 | + |
| 30 | +**New files:** |
| 31 | + |
| 32 | +``` |
| 33 | +src/httpware/ |
| 34 | +├── middleware/ |
| 35 | +│ └── __init__.py # Middleware Protocol + Next type alias (~25 lines) |
| 36 | +└── _internal/ |
| 37 | + ├── __init__.py # empty marker |
| 38 | + └── chain.py # compose() + private _wrap() (~30 lines) |
| 39 | +``` |
| 40 | + |
| 41 | +**Modified files:** |
| 42 | + |
| 43 | +``` |
| 44 | +src/httpware/__init__.py # re-export Middleware, Next at package root |
| 45 | +``` |
| 46 | + |
| 47 | +**New tests:** |
| 48 | + |
| 49 | +``` |
| 50 | +tests/test_middleware.py # protocol surface + chain composition (~11 tests) |
| 51 | +``` |
| 52 | + |
| 53 | +**Files not touched:** `request.py`, `response.py`, `errors.py`, `config.py`, `transports/`, `decoders/`. Story 2-1 is purely additive. |
| 54 | + |
| 55 | +## Protocol surface |
| 56 | + |
| 57 | +`src/httpware/middleware/__init__.py`: |
| 58 | + |
| 59 | +```python |
| 60 | +"""Middleware protocol — the AsyncClient ↔ Middleware seam (Seam 2).""" |
| 61 | + |
| 62 | +from collections.abc import Awaitable, Callable |
| 63 | +from typing import Protocol, TypeAlias, runtime_checkable |
| 64 | + |
| 65 | +from httpware.request import Request |
| 66 | +from httpware.response import Response |
| 67 | + |
| 68 | + |
| 69 | +Next: TypeAlias = Callable[[Request], Awaitable[Response]] |
| 70 | + |
| 71 | + |
| 72 | +@runtime_checkable |
| 73 | +class Middleware(Protocol): |
| 74 | + """Structural protocol every middleware satisfies. |
| 75 | +
|
| 76 | + A middleware receives the incoming `Request` and a `Next` callable. It may |
| 77 | + inspect/transform the request, await `next(request)` to forward to the rest |
| 78 | + of the chain (eventually the transport), inspect/transform the returned |
| 79 | + `Response`, short-circuit by returning a `Response` without calling `next`, |
| 80 | + or raise. |
| 81 | + """ |
| 82 | + |
| 83 | + async def __call__(self, request: Request, next: Next) -> Response: |
| 84 | + """Process `request`; call `next(request)` to forward, or synthesize a Response.""" |
| 85 | + ... |
| 86 | + |
| 87 | + |
| 88 | +__all__ = ["Middleware", "Next"] |
| 89 | +``` |
| 90 | + |
| 91 | +Notes: |
| 92 | +- `next` shadows the Python builtin in the method body. Standard for this pattern (ASGI convention). Implementers may name the parameter whatever they want; structural typing matches by position and type, not name. |
| 93 | +- `@runtime_checkable` mirrors the other two structural protocols in the codebase (`Transport`, `ResponseDecoder`). Enables `isinstance(obj, Middleware)` for AsyncClient's per-construction validation in Story 2-5. The deferred-work entry on `_ProtocolMeta.__instancecheck__` µs-cost applies only if validation runs per-request; per-construction is fine. |
| 94 | + |
| 95 | +## Chain composition |
| 96 | + |
| 97 | +`src/httpware/_internal/chain.py`: |
| 98 | + |
| 99 | +```python |
| 100 | +"""Middleware chain composition — wires a middleware list against a Transport. |
| 101 | +
|
| 102 | +Private helper. AsyncClient calls `compose` at construction time and stores the |
| 103 | +returned `Next` callable; per-request dispatch awaits that callable. |
| 104 | +""" |
| 105 | + |
| 106 | +from collections.abc import Sequence |
| 107 | + |
| 108 | +from httpware.middleware import Middleware, Next |
| 109 | +from httpware.request import Request |
| 110 | +from httpware.response import Response |
| 111 | +from httpware.transports import Transport |
| 112 | + |
| 113 | + |
| 114 | +def compose(middlewares: Sequence[Middleware], transport: Transport) -> Next: |
| 115 | + """Fold `middlewares` into a single `Next` callable terminating at `transport`. |
| 116 | +
|
| 117 | + The outermost middleware in the input sequence is the first to receive the |
| 118 | + request; its `next` argument forwards to the next middleware, and so on, |
| 119 | + until the innermost middleware's `next` calls `transport.__call__`. An |
| 120 | + empty sequence returns `transport.__call__` directly. |
| 121 | +
|
| 122 | + The returned callable is reusable across many requests; it captures |
| 123 | + references to `middlewares` and `transport` by closure. |
| 124 | + """ |
| 125 | + chain: Next = transport.__call__ |
| 126 | + for middleware in reversed(middlewares): |
| 127 | + chain = _wrap(middleware, chain) |
| 128 | + return chain |
| 129 | + |
| 130 | + |
| 131 | +def _wrap(middleware: Middleware, next_call: Next) -> Next: |
| 132 | + async def _call(request: Request) -> Response: |
| 133 | + return await middleware(request, next_call) |
| 134 | + |
| 135 | + return _call |
| 136 | + |
| 137 | + |
| 138 | +__all__ = ["compose"] |
| 139 | +``` |
| 140 | + |
| 141 | +Notes: |
| 142 | +- Bottom of chain: `transport.__call__` is a bound method satisfying `Callable[[Request], Awaitable[Response]]`. Direct assignment; no wrapper coroutine. |
| 143 | +- Each chain layer is one closure: `_wrap` captures `middleware` and `next_call`, returns a coroutine function with the `Next` signature. |
| 144 | +- Empty sequence: `reversed(())` is a no-op iterator; `chain` stays as `transport.__call__`. Test asserts identity. |
| 145 | +- No exception handling anywhere in the file. `CancelledError` and all other exceptions propagate up. This is the cancellation contract. |
| 146 | + |
| 147 | +## Public exports |
| 148 | + |
| 149 | +`src/httpware/__init__.py` adds: |
| 150 | + |
| 151 | +```python |
| 152 | +from httpware.middleware import Middleware, Next |
| 153 | +``` |
| 154 | + |
| 155 | +…and adds `"Middleware"` and `"Next"` to `__all__` in their alphabetic positions. |
| 156 | + |
| 157 | +Result: consumers can write either of: |
| 158 | + |
| 159 | +```python |
| 160 | +from httpware import Middleware, Next |
| 161 | +from httpware.middleware import Middleware, Next |
| 162 | +``` |
| 163 | + |
| 164 | +Both work; the package-root path is the canonical user-facing one (matches `Request`, `Response`, `Httpx2Transport`). |
| 165 | + |
| 166 | +## Testing |
| 167 | + |
| 168 | +`tests/test_middleware.py` covers protocol + chain in one file. Approximate test list: |
| 169 | + |
| 170 | +| Test | Verifies | |
| 171 | +| --- | --- | |
| 172 | +| `test_empty_list_composes_to_transport_call` | `compose([], transport)(req)` returns the same response as awaiting `transport(req)` directly. (Behavioral check, not identity — the chain may add a thin terminal wrapper if the implementation needs one; see Risks.) | |
| 173 | +| `test_single_middleware_wraps_transport` | One middleware sees the request, calls `next`, returns the transport's response. | |
| 174 | +| `test_chain_runs_outer_to_inner` | Three middlewares append to a shared list; final order asserts outer → inner → transport → inner → outer (onion). | |
| 175 | +| `test_short_circuit_returns_synthesized_response` | Middleware that does NOT call `next` returns a synthesized Response; transport (and any inner middleware) is never invoked. | |
| 176 | +| `test_middleware_can_transform_request_before_forwarding` | Outer middleware mutates request via `with_header`; inner sees the mutation. | |
| 177 | +| `test_middleware_can_transform_response_before_returning` | Outer middleware awaits `next`, returns a modified Response; caller sees the modification. | |
| 178 | +| `test_exception_in_middleware_propagates` | Middleware raises a custom exception; bubbles through unchanged. | |
| 179 | +| `test_exception_in_transport_propagates_through_chain` | Transport raises; exception passes through each middleware unmodified. | |
| 180 | +| `test_cancelled_error_propagates_through_chain` | `asyncio.CancelledError` raised mid-chain propagates to the caller. Explicit per NFR15. | |
| 181 | +| `test_runtime_checkable_isinstance_works` | `isinstance(some_middleware, Middleware)` returns True for a valid impl, False for an unrelated callable. | |
| 182 | +| `test_compose_returned_callable_is_reusable` | The `Next` returned by `compose` can be awaited multiple times across sequential requests; closure captures don't accumulate state. | |
| 183 | + |
| 184 | +**Fixtures:** |
| 185 | +- `FakeTransport` implementing `Transport`: `async def __call__` returns a fixed Response; `stream()` and `aclose()` stubs. Lives in `tests/test_middleware.py` (file-scoped — not yet shared with other test files). |
| 186 | +- `record_calls(*labels)` factory: returns middleware-class instances that append labels to a shared list. Used by the ordering test. |
| 187 | + |
| 188 | +**Coverage expectation:** 100% line coverage on `middleware/__init__.py`, `_internal/__init__.py`, and `_internal/chain.py`. The Protocol method body (`...`) is excluded via standard coverage pragma if needed; typical for Protocol stubs. |
| 189 | + |
| 190 | +## Constraints and invariants |
| 191 | + |
| 192 | +- **No `httpx2` import.** Neither new file imports `httpx2`. The existing `tests/test_no_httpx2_leakage.py` continues to pass without modification. |
| 193 | +- **No `from __future__ import annotations`.** PEP 604/585 syntax is native (already enforced repo-wide). |
| 194 | +- **No `print()`, no global logging config.** Middleware module does no logging in Story 2-1; observability emission lands in Epic 5. |
| 195 | +- **Type suppressions.** None expected. If `ty` flags the bound-method assignment to `Next`, suppress with `# ty: ignore[<rule>]` and document the reason. Should not be needed — `Transport.__call__` already has the matching signature. |
| 196 | +- **Keyword-only construction.** N/A for Story 2-1 (no new dataclass or exception types). |
| 197 | + |
| 198 | +## Risks and mitigations |
| 199 | + |
| 200 | +| Risk | Mitigation | |
| 201 | +| --- | --- | |
| 202 | +| `ty` rejects `chain: Next = transport.__call__` because `Next` is a value-level alias and bound-method assignment is subtle. | If flagged, change to `chain: Next = transport.__call__`. If still flagged, fall back to `async def _terminal(req): return await transport(req)` at the bottom (one extra async frame per call; acceptable). Decided at implementation time, documented as a code comment if used. | |
| 203 | +| Middleware swallows `CancelledError` silently (a user bug, not ours). | Story 2-2's `@on_error` decorator excludes `CancelledError` by design (catches `Exception` only). Story 2-1 itself has no exception handlers, so the protocol can't introduce this risk; it can only be introduced by user code. The cancellation test verifies the chain doesn't accidentally swallow it. | |
| 204 | +| `runtime_checkable` µs-cost amortizes badly if AsyncClient calls `isinstance` per request (Story 1-7 deferred concern). | Story 1-7 / 2-5 spec must validate `middleware=[...]` at construction time only. Not a Story 2-1 problem to solve; flagged in the design pointer to the deferred-work entry. | |
| 205 | +| Sequence vs list semantic surprise — a user passes a `dict.values()` view and expects fresh ordering each call. | `compose` consumes the sequence once (during construction) and stores closures over the captured `middleware` references. Subsequent mutations to the original sequence have no effect. Test `test_compose_returned_callable_is_reusable` covers reuse; no test for the dict-view edge case (not a real user pattern). | |
| 206 | + |
| 207 | +## Definition of done |
| 208 | + |
| 209 | +- `src/httpware/middleware/__init__.py` exports `Middleware` (runtime-checkable Protocol) and `Next` (TypeAlias). |
| 210 | +- `src/httpware/_internal/__init__.py` exists as an empty package marker. |
| 211 | +- `src/httpware/_internal/chain.py` exports `compose(middlewares, transport) -> Next`. |
| 212 | +- `src/httpware/__init__.py` re-exports `Middleware` and `Next` at the package root and adds them to `__all__`. |
| 213 | +- `tests/test_middleware.py` contains the 11 tests listed above; all pass. |
| 214 | +- `just test` continues green; 100% line coverage on the new modules. |
| 215 | +- `just lint-ci` clean: `ruff format --check`, `ruff check --no-fix`, `ty check` all pass. |
| 216 | +- `tests/test_no_httpx2_leakage.py` still passes (no `httpx2` import added). |
| 217 | +- CHANGELOG.md gets a `[Unreleased]` bullet for Story 2.1. |
| 218 | +- Story 2-1 lands as a single PR off `main` via the branch `story/2-1-middleware-protocol-and-chain`. |
0 commit comments