Skip to content

Commit cb623d6

Browse files
lesnik512claude
andcommitted
feat(story-2.1): Middleware protocol and Next type alias
Adds src/httpware/middleware/__init__.py defining: - Next: TypeAlias = Callable[[Request], Awaitable[Response]] - Middleware: @runtime_checkable Protocol with async __call__(request, next) Matches Transport and ResponseDecoder shape. The `next` parameter shadows the Python builtin (standard for this pattern); structural typing matches by position, so concrete middleware may rename it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 596bfda commit cb623d6

2 files changed

Lines changed: 62 additions & 0 deletions

File tree

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
"""Middleware protocol — the AsyncClient ↔ Middleware seam (Seam 2)."""
2+
3+
from collections.abc import Awaitable, Callable
4+
from typing import Protocol, TypeAlias, runtime_checkable
5+
6+
from httpware.request import Request
7+
from httpware.response import Response
8+
9+
10+
Next: TypeAlias = Callable[[Request], Awaitable[Response]]
11+
12+
13+
@runtime_checkable
14+
class Middleware(Protocol):
15+
"""Structural protocol every middleware satisfies.
16+
17+
A middleware receives the incoming `Request` and a `Next` callable. It may
18+
inspect/transform the request, await `next(request)` to forward to the rest
19+
of the chain (eventually the transport), inspect/transform the returned
20+
`Response`, short-circuit by returning a `Response` without calling `next`,
21+
or raise.
22+
"""
23+
24+
async def __call__(self, request: Request, next: Next) -> Response: # noqa: A002
25+
"""Process `request`; call `next(request)` to forward, or synthesize a Response."""
26+
...
27+
28+
29+
__all__ = ["Middleware", "Next"]

‎tests/test_middleware.py‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
"""Tests for the Middleware protocol and chain composition."""
2+
3+
from collections.abc import Awaitable, Callable
4+
from typing import get_type_hints
5+
6+
from httpware.middleware import Middleware, Next
7+
from httpware.request import Request
8+
from httpware.response import Response
9+
10+
11+
class _SignalMiddleware:
12+
"""Minimal valid Middleware implementation used by tests."""
13+
14+
async def __call__(self, request: Request, next: Next) -> Response: # noqa: A002
15+
return await next(request)
16+
17+
18+
def test_runtime_checkable_isinstance_works() -> None:
19+
"""A class implementing `__call__` satisfies the Middleware Protocol at runtime."""
20+
# runtime_checkable checks for presence of __call__, not signature details
21+
assert isinstance(_SignalMiddleware(), Middleware)
22+
23+
24+
def test_next_type_alias_resolves_to_callable() -> None:
25+
"""`Next` resolves to `Callable[[Request], Awaitable[Response]]`."""
26+
expected = Callable[[Request], Awaitable[Response]]
27+
assert Next == expected
28+
29+
30+
def test_next_annotation_on_signal_middleware() -> None:
31+
"""`next` parameter on `_SignalMiddleware.__call__` is annotated with `Next`."""
32+
hints = get_type_hints(_SignalMiddleware.__call__)
33+
assert hints["next"] == Next

0 commit comments

Comments
 (0)