diff --git a/src/hhstream_mcp/http.py b/src/hhstream_mcp/http.py index 6f0303f..115ee02 100644 --- a/src/hhstream_mcp/http.py +++ b/src/hhstream_mcp/http.py @@ -55,7 +55,6 @@ The deliberate choices in the request path from __future__ import annotations -import contextlib import logging from collections.abc import Callable, Sequence from typing import Any @@ -219,17 +218,13 @@ class BearerAuth: allowed = self.limiter.allow(client) status = 401 if allowed else 429 log.warning("%s from %s: %s", status, client, reason if allowed else "rate limited") - headers = [ - (b"content-length", b"0"), - (b"cache-control", b"no-store"), - (b"x-content-type-options", b"nosniff"), - ] + headers: list[tuple[bytes, bytes]] = [] if status == 401: # RFC 9110's challenge. A realm and nothing else: there is no - # `as_uri` to point at, because there is no authorization server. + # metadata document to point at, because there is no authorization + # server -- see `docs/TODO/mcp-http-auth-is-not-oauth.md`. headers.append((b"www-authenticate", f'Bearer realm="{SERVER_NAME}"'.encode())) - await send({"type": "http.response.start", "status": status, "headers": headers}) - await send({"type": "http.response.body", "body": b""}) + await _empty(send, status, headers) def _header(scope: dict[str, Any], name: bytes) -> str: @@ -297,6 +292,85 @@ def offered_for(server: Any, base: tuple[tools.Tool, ...]) -> Callable[[], tuple return chooser +class Endpoint: + """The ASGI app under :class:`BearerAuth`: one path, and the lifespan. + + Hand-rolled rather than ``Starlette(routes=[Mount(path, app=…)])``, and + the reason is a 307 that costs real clients their request. A Starlette + ``Mount`` at ``/mcp`` serves ``/mcp/`` and answers ``/mcp`` with a redirect + (or a 404 with ``redirect_slashes`` off) -- measured, both ways. Every MCP + client configuration spells the URL without the trailing slash, and a + redirected **POST** has to be re-sent with its body, which ``urllib`` will + not do at all and some clients get wrong. So the path is matched here, + exactly, with and without the slash, and nothing redirects. + + It also means the only routing in this server is three lines long and in + one place, which is the whole of what a single-endpoint server needs. + """ + + def __init__(self, manager: StreamableHTTPSessionManager, path: str) -> None: + self.manager = manager + # Both spellings are the endpoint; neither is a redirect to the other. + self.paths = {path, path.rstrip("/") + "/"} if path != "/" else {"/"} + + async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None: + if scope["type"] == "lifespan": + await self._lifespan(receive, send) + return + if scope.get("path") in self.paths: + await self.manager.handle_request(scope, receive, send) + return + await _empty(send, 404) + + async def _lifespan(self, receive: Any, send: Any) -> None: + """The startup/shutdown protocol, by hand. + + ``manager.run()`` has to stay open for the life of the process: it owns + the task group the per-session server tasks live in. Entered on + ``startup`` and exited on ``shutdown``, both of which arrive in this + one coroutine -- which matters, because an anyio task group must be + exited by the task that entered it. + """ + + running: Any = None + while True: + message = await receive() + kind = message["type"] + if kind == "lifespan.startup": + try: + running = self.manager.run() + await running.__aenter__() + except BaseException as exc: # noqa: BLE001 -- reported, not swallowed + log.exception("http transport failed to start") + await send({"type": "lifespan.startup.failed", "message": repr(exc)}) + return + log.info("http transport ready on %s", ", ".join(sorted(self.paths))) + await send({"type": "lifespan.startup.complete"}) + elif kind == "lifespan.shutdown": + if running is not None: + await running.__aexit__(None, None, None) + await send({"type": "lifespan.shutdown.complete"}) + return + + +async def _empty(send: Any, status: int, headers: list[tuple[bytes, bytes]] | None = None) -> None: + """A response with no body, which is every response this layer writes itself.""" + + await send( + { + "type": "http.response.start", + "status": status, + "headers": [ + (b"content-length", b"0"), + (b"cache-control", b"no-store"), + (b"x-content-type-options", b"nosniff"), + *(headers or ()), + ], + } + ) + await send({"type": "http.response.body", "body": b""}) + + def build_app( runner: Runner, store: Store, @@ -308,7 +382,7 @@ def build_app( stateless: bool = False, json_response: bool = False, ) -> Any: - """The ASGI application: one route, behind :class:`BearerAuth`. + """The ASGI application: one endpoint, behind :class:`BearerAuth`. ``allowed_hosts`` must already be resolved -- :func:`default_allowed_hosts` is the caller's to apply, because the empty list has to stay meaningful @@ -322,12 +396,6 @@ def build_app( only honest answer. """ - # Imported here and not at module scope: `build_app` is the only thing in - # this file that needs Starlette, and an import error should name the - # feature being started rather than fire on `import hhstream_mcp.http`. - from starlette.applications import Starlette - from starlette.routing import Mount - from .server import build security = TransportSecuritySettings( @@ -356,28 +424,11 @@ def build_app( json_response=json_response, security_settings=security, ) - - async def handle(scope: Any, receive: Any, send: Any) -> None: - await manager.handle_request(scope, receive, send) - - @contextlib.asynccontextmanager - async def lifespan(_app: Any) -> Any: - # The manager's task group has to be open for the whole life of the - # process: it owns the per-session server tasks. - async with manager.run(): - log.info("http transport ready on %s", path) - yield - - app = Starlette( - debug=False, - routes=[Mount(path, app=handle)], - lifespan=lifespan, - ) - # The token check wraps the *whole* app and not just the route, so a + # The token check wraps the *whole* app and not just the endpoint, so a # request to any other path is a 401 rather than a 404. An unauthenticated # caller learns nothing about what this server has mounted, including # whether it is an hhstream server at all. - return BearerAuth(app, store) + return BearerAuth(Endpoint(manager, path), store) def serve( @@ -435,6 +486,7 @@ __all__ = [ "DEFAULT_PORT", "SCOPE_KEY", "BearerAuth", + "Endpoint", "bearer_token", "build_app", "current_grant", diff --git a/tests/unit/test_mcp_http.py b/tests/unit/test_mcp_http.py index 46e54d6..082349e 100644 --- a/tests/unit/test_mcp_http.py +++ b/tests/unit/test_mcp_http.py @@ -72,12 +72,23 @@ def make_app(store, **kwargs): return http_transport.build_app(Runner(entry=lambda argv: 0), store, **kwargs) -def post(client, body, token=None, headers=None): +def post(client, body, token=None, headers=None, path="/mcp"): + """One POST, and **never** following a redirect. + + `follow_redirects=False` is load-bearing, not tidiness. The test client + follows redirects by default, which is how a `Mount`-shaped 307 on the + exact path `/mcp` passed this whole file once while failing a real client: + a redirected POST has to be re-sent with its body, and `urllib` will not do + that at all. See `test_the_exact_path_does_not_redirect`. + """ + sent = dict(HEADERS) if token is not None: sent["Authorization"] = f"Bearer {token}" sent.update(headers or {}) - return client.post("/mcp", content=json.dumps(body), headers=sent) + return client.post( + path, content=json.dumps(body), headers=sent, follow_redirects=False + ) def session(client, token): @@ -196,6 +207,33 @@ def test_the_refusal_does_not_say_which_kind_it_was(store): assert len(set(responses)) == 1 +@pytest.mark.parametrize("path", ["/mcp", "/mcp/"]) +def test_the_exact_path_does_not_redirect(store, path): + """Both spellings are the endpoint, and neither is a redirect to the other. + + The regression this exists for: `Starlette(routes=[Mount("/mcp", ...)])` + serves `/mcp/` and answers `/mcp` with a 307 — and every MCP client + configuration spells the URL without the trailing slash. The redirect is + invisible to a client that follows it on a POST and fatal to one that does + not, which is why the endpoint matches the path itself instead. + """ + + _, token = store.mint() + with TestClient(make_app(store)) as client: + response = post(client, INITIALIZE, token=token, path=path) + assert response.status_code == 200, ( + f"{path} answered {response.status_code} " + f"(location: {response.headers.get('location')!r})" + ) + + +def test_a_custom_path_is_honoured(store): + _, token = store.mint() + with TestClient(make_app(store, path="/agent/mcp")) as client: + assert post(client, INITIALIZE, token=token, path="/agent/mcp").status_code == 200 + assert post(client, INITIALIZE, token=token, path="/mcp").status_code == 404 + + def test_an_unknown_path_leaks_nothing_without_a_token(store): store.mint() with TestClient(make_app(store)) as client: @@ -207,7 +245,11 @@ def test_an_unknown_path_leaks_nothing_without_a_token(store): def test_an_unknown_path_is_a_404_once_authenticated(store): _, token = store.mint() with TestClient(make_app(store)) as client: - response = client.get("/elsewhere", headers={"Authorization": f"Bearer {token}"}) + response = client.get( + "/elsewhere", + headers={"Authorization": f"Bearer {token}"}, + follow_redirects=False, + ) assert response.status_code == 404