Skip to content

Commit 596bfda

Browse files
lesnik512claude
andcommitted
docs(story-2.1): design for middleware protocol, Next type, and chain
Ports the archived Middleware Execution Model decision forward to the superpowers flow. Decisions: runtime-checkable Protocol matching Transport / ResponseDecoder; TypeAlias for Next (3.11 floor rules out PEP 695); private compose() at _internal/chain.py using a recursive closure fold with transport.__call__ as the bottom of the chain; Sequence[Middleware] over list; no exception handling in compose so CancelledError propagates naturally; public exports at both httpware.middleware.* and httpware.* (matches Request/Response). Strict epic boundary — decorators (2-2), Request helpers (2-3), auth coercion (2-4), AsyncClient wiring (2-5), and streaming chain (4-3) land as their own stories. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 1038514 commit 596bfda

1 file changed

Lines changed: 218 additions & 0 deletions

File tree

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
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

Comments
 (0)