Files
hyprland-headless-stream-pl…/tests/unit/test_mcp_http.py
T
HermenixandClaude Opus 5 8a0c9ca74d fix(mcp): declare the HTTP transport's dependencies, and forbid its tests to skip
`starlette` and `uvicorn` arrive through the MCP SDK today -- measured,
both of them -- and relying on that is exactly the trap this project
already wrote down twice.  `src/hhstream_mcp/pyproject.toml` declares
`anyio` rather than taking it for granted through the SDK because
`server.py` uses it by name; `http.py` imports `uvicorn` by name and sits
on Starlette's `Request` through the SDK's `TransportSecuritySettings`,
so both belong in the metadata on the same argument.  An SDK release that
moved its HTTP transport behind an optional extra would otherwise break
`serve --http` with an ImportError naming somebody else's package.
`nix/mcp.nix` carries them for the same reason.

The worse half was in the gate.  `tests/unit/test_mcp_http.py` opened
with `pytest.importorskip("starlette.testclient")`, which is the pattern
`checks/unit.nix`'s own comment argues against in as many words: "a file
that skipped when the SDK was absent would be green in exactly the build
where that mattered".  It would not skip today -- `mcp` propagates
starlette and httpx -- but the day it did, 43 tests would leave the gate
and nothing would say so, because pytest exits 0 when every test was
skipped.

So the import is unconditional now, `checks/unit.nix` declares `starlette`
and `httpx` explicitly, and the check proves them importable before
pytest runs, beside the lines that already do that for `hhstream` and the
tool table.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-11 22:49:44 +00:00

471 lines
18 KiB
Python

"""The HTTP transport: every way a request is refused, and the one way it is not.
This file imports Starlette as well as the SDK, **unconditionally**, for the
reason ``test_mcp_server.py`` imports the SDK that way: the thing under test is
the wiring, only a real ASGI stack can judge it, and a file that skipped when
its dependency was missing would be green in precisely the build where that
mattered. The store itself is
standard library and tested without any of this
(``test_mcp_authorizations.py``).
The app is driven through ``starlette.testclient``, which speaks to it over
ASGI with no socket. That is enough for everything here -- a status code, a
header, an empty body, which tools a session is shown -- and it is
deliberately *not* enough for "the unit comes up and answers on a port", which
is ``checks/vm-mcp.nix``' job.
``Host: testserver`` is what the test client sends, so every app built here
names it in ``allowed_hosts``. That is not a workaround: DNS-rebinding
protection is on by default and an app that did not name its clients' host
would 421 them, which is the behaviour ``test_rebinding_protection_*`` asserts.
"""
from __future__ import annotations
import json
import pytest
from hhstream_mcp import authorizations as auth
from hhstream_mcp import http as http_transport
from hhstream_mcp import tools
from hhstream_mcp.invoke import Runner
# Imported unconditionally, and not through `importorskip`, for the reason
# `test_mcp_server.py` imports the SDK unconditionally: a file that skipped
# when its dependency was absent would be green in exactly the build where
# that mattered. `checks/unit.nix` declares `starlette` and `httpx` so this
# cannot become a skip, and proves them importable before pytest runs.
from starlette.testclient import TestClient
#: The test client's Host, plus what a loopback deployment derives.
TEST_HOSTS = ["testserver", *http_transport.default_allowed_hosts("127.0.0.1", 9989)]
HEADERS = {
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
}
INITIALIZE = {
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {"name": "test", "version": "0"},
},
}
@pytest.fixture
def store(tmp_path):
return auth.Store.at(tmp_path / "state")
def make_app(store, **kwargs):
"""The app, with a Runner that never reaches a CLI.
``entry`` returns 0 without doing anything: nothing in this file calls a
tool for its effect, and a Runner that could reach `hhstream.cli` would
make these tests depend on a broker socket.
"""
kwargs.setdefault("allowed_hosts", TEST_HOSTS)
kwargs.setdefault("json_response", True)
return http_transport.build_app(Runner(entry=lambda argv: 0), store, **kwargs)
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(
path, content=json.dumps(body), headers=sent, follow_redirects=False
)
def session(client, token):
"""Initialize and return the headers that carry the session on."""
response = post(client, INITIALIZE, token=token)
assert response.status_code == 200, response.content
extra = {}
sid = response.headers.get("mcp-session-id")
if sid:
extra["mcp-session-id"] = sid
post(client, {"jsonrpc": "2.0", "method": "notifications/initialized"},
token=token, headers=extra)
return extra
def call(client, token, method, params=None, headers=None, request_id=2):
body = {"jsonrpc": "2.0", "id": request_id, "method": method}
if params is not None:
body["params"] = params
response = post(client, body, token=token, headers=headers)
assert response.status_code == 200, response.content
return json.loads(response.content)
# ── parsing the header ─────────────────────────────────────────────────────
@pytest.mark.parametrize(
("header", "expected"),
[
("Bearer abc", "abc"),
("bearer abc", "abc"), # RFC 9110: the scheme is case-insensitive
("BEARER abc", "abc"),
("Bearer abc ", "abc"),
("", None),
("abc", None), # no scheme
("Basic abc", None), # wrong scheme
("Bearer", None), # no token
("Bearer ", None),
],
)
def test_bearer_token_parsing(header, expected):
assert http_transport.bearer_token(header) == expected
# ── the refusals ───────────────────────────────────────────────────────────
def test_no_header_is_401_with_an_empty_body(store):
store.mint()
with TestClient(make_app(store)) as client:
response = post(client, INITIALIZE)
assert response.status_code == 401
assert response.content == b""
assert response.headers["www-authenticate"].startswith("Bearer ")
assert response.headers["cache-control"] == "no-store"
def test_a_wrong_token_is_401_and_is_not_echoed(store):
store.mint()
wrong = "hhsmcp_definitely-not-a-real-token"
with TestClient(make_app(store)) as client:
response = post(client, INITIALIZE, token=wrong)
assert response.status_code == 401
assert response.content == b""
# Not in the body, and not in any header either.
assert wrong not in "".join(f"{k}{v}" for k, v in response.headers.items())
def test_a_revoked_token_is_401(store):
grant, token = store.mint()
store.revoke(grant.id)
with TestClient(make_app(store)) as client:
assert post(client, INITIALIZE, token=token).status_code == 401
def test_an_expired_token_is_401(store):
from hhstreamd.clock import ManualClock
clock = ManualClock()
store.clock = clock
_, token = store.mint(ttl=60)
clock.advance(61)
with TestClient(make_app(store)) as client:
assert post(client, INITIALIZE, token=token).status_code == 401
def test_the_wrong_scheme_is_401(store):
_, token = store.mint()
with TestClient(make_app(store)) as client:
response = post(client, INITIALIZE, headers={"Authorization": f"Basic {token}"})
assert response.status_code == 401
def test_an_empty_table_refuses_everything(store):
with TestClient(make_app(store)) as client:
assert post(client, INITIALIZE, token="hhsmcp_anything").status_code == 401
def test_the_refusal_does_not_say_which_kind_it_was(store):
"""Unknown, revoked and expired are one answer, byte for byte.
Telling them apart would tell someone who guessed a real id that they had.
"""
grant, revoked = store.mint()
store.revoke(grant.id)
_, live = store.mint()
responses = []
with TestClient(make_app(store)) as client:
for token in ("hhsmcp_unknown", revoked, live[:-1] + "x"):
response = post(client, INITIALIZE, token=token)
responses.append((response.status_code, response.content,
response.headers.get("www-authenticate")))
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:
# 401 and not 404: an unauthenticated caller does not learn what is
# mounted here, or that anything is.
assert client.get("/elsewhere").status_code == 401
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}"},
follow_redirects=False,
)
assert response.status_code == 404
def test_repeated_failures_are_rate_limited(store):
from hhstream_live.server import RateLimiter
store.mint()
app = make_app(store)
app.limiter = RateLimiter(limit=3)
with TestClient(app) as client:
codes = [post(client, INITIALIZE).status_code for _ in range(5)]
assert codes[:3] == [401, 401, 401]
assert codes[3:] == [429, 429]
def test_a_good_token_is_not_rate_limited(store):
from hhstream_live.server import RateLimiter
_, token = store.mint()
app = make_app(store)
app.limiter = RateLimiter(limit=2)
with TestClient(app) as client:
for _ in range(5):
assert post(client, INITIALIZE, token=token).status_code == 200
# ── the one way through ────────────────────────────────────────────────────
def test_a_good_token_completes_the_handshake(store):
_, token = store.mint()
with TestClient(make_app(store)) as client:
response = post(client, INITIALIZE, token=token)
assert response.status_code == 200
result = json.loads(response.content)["result"]
assert result["serverInfo"]["name"] == "hhstream"
assert "instructions" in result
def test_the_full_surface_is_offered_to_an_unrestricted_token(store):
_, token = store.mint()
with TestClient(make_app(store)) as client:
extra = session(client, token)
listed = call(client, token, "tools/list", headers=extra)["result"]["tools"]
resources = call(client, token, "resources/list", headers=extra,
request_id=3)["result"]["resources"]
assert len(listed) == len(tools.TOOLS)
assert len(resources) == 5
def test_using_a_token_stamps_it(store):
grant, token = store.mint()
with TestClient(make_app(store)) as client:
session(client, token)
assert store.load()[0].last_used is not None
assert store.load()[0].id == grant.id
# ── what a token's toolsets do ─────────────────────────────────────────────
def test_a_scoped_token_is_offered_only_its_toolsets(store):
_, token = store.mint(toolsets=["frames"])
with TestClient(make_app(store)) as client:
extra = session(client, token)
listed = call(client, token, "tools/list", headers=extra)["result"]["tools"]
assert {tool["name"] for tool in listed} == set(tools.TOOLSETS["frames"])
def test_a_scoped_token_cannot_call_outside_its_toolsets(store):
_, token = store.mint(toolsets=["frames"])
with TestClient(make_app(store)) as client:
extra = session(client, token)
result = call(
client, token, "tools/call",
{"name": "session_gc", "arguments": {}}, headers=extra,
)["result"]
assert result["isError"] is True
text = result["content"][0]["text"]
assert "session_gc" in text
# The message names both possible narrowings, because the agent cannot tell
# them apart and neither is its to change.
assert "--toolsets" in text
assert "authorization" in text
def test_a_token_cannot_widen_the_processs_own_toolsets(store):
"""The intersection, not the token's list.
A unit started with `--toolsets frames` must not be talked into serving
`session_start` by a token that names `sessions`.
"""
_, token = store.mint(toolsets=["frames", "sessions"])
with TestClient(make_app(store, toolsets=["frames"])) as client:
extra = session(client, token)
listed = call(client, token, "tools/list", headers=extra)["result"]["tools"]
assert {tool["name"] for tool in listed} == set(tools.TOOLSETS["frames"])
def test_two_tokens_on_one_server_see_different_surfaces(store):
"""The property the per-token narrowing exists for.
One process, two callers, two tool budgets. A launch-time flag cannot do
this, which is the whole argument for putting toolsets on the token.
"""
_, broad = store.mint(label="broad")
_, narrow = store.mint(label="narrow", toolsets=["frames"])
with TestClient(make_app(store)) as client:
broad_extra = session(client, broad)
narrow_extra = session(client, narrow)
broad_tools = call(client, broad, "tools/list",
headers=broad_extra)["result"]["tools"]
narrow_tools = call(client, narrow, "tools/list", headers=narrow_extra,
request_id=3)["result"]["tools"]
assert len(broad_tools) == len(tools.TOOLS)
assert {tool["name"] for tool in narrow_tools} == set(tools.TOOLSETS["frames"])
def test_resources_are_not_narrowed_by_a_token(store):
"""A stated limit, not an oversight.
`docs/CONTRACT-mcp.md` keeps resources out of `--toolsets` because they are
the host's context rather than the model's budget. A token is an
authorization rather than a budget, so this is a real gap and it is written
down in `docs/TODO/mcp-tokens-do-not-scope-resources.md` rather than
quietly implied by the tests.
"""
_, token = store.mint(toolsets=["frames"])
with TestClient(make_app(store)) as client:
extra = session(client, token)
listed = call(client, token, "resources/list", headers=extra)["result"]["resources"]
assert any(entry["uri"] == "hhstream://sessions" for entry in listed)
def test_a_token_naming_an_unknown_toolset_offers_nothing(store):
"""A grant from a future build: refuse everything rather than widen."""
grant, token = store.mint()
grant.toolsets = ("a-family-this-build-has-never-heard-of",)
store._write([grant])
with TestClient(make_app(store)) as client:
extra = session(client, token)
listed = call(client, token, "tools/list", headers=extra)["result"]["tools"]
assert listed == []
# ── DNS-rebinding protection ───────────────────────────────────────────────
def test_rebinding_protection_refuses_an_unnamed_host(store):
_, token = store.mint()
app = make_app(store, allowed_hosts=["somewhere.else"])
with TestClient(app) as client:
response = post(client, INITIALIZE, token=token)
# The token was good; the Host was not. 421 Misdirected Request.
assert response.status_code == 421
def test_the_token_is_checked_before_the_host(store):
"""Order matters: an unauthenticated caller learns nothing about the host
allowlist, which is itself a hint about how this server is deployed."""
store.mint()
app = make_app(store, allowed_hosts=["somewhere.else"])
with TestClient(app) as client:
assert post(client, INITIALIZE).status_code == 401
@pytest.mark.parametrize("address", ["127.0.0.1", "::1", "localhost"])
def test_loopback_derives_a_working_allowlist(address):
hosts = http_transport.default_allowed_hosts(address, 9989)
assert "127.0.0.1:9989" in hosts
assert "localhost:9989" in hosts
assert "[::1]:9989" in hosts
# The SDK's wildcard-port form, for a client that reached a proxy on
# another port and was forwarded here.
assert "127.0.0.1:*" in hosts
def test_a_named_address_derives_itself_and_not_loopback():
hosts = http_transport.default_allowed_hosts("10.0.0.5", 9989)
assert hosts == ["10.0.0.5:9989", "10.0.0.5:*", "10.0.0.5"]
@pytest.mark.parametrize("address", ["0.0.0.0", "::", "*"])
def test_a_wildcard_bind_derives_nothing(address):
"""Which is what makes the launch path refuse it.
Nothing can be guessed about the Host a client will send, and an empty
allowlist with protection on refuses every request. So the operator is made
to name the hostnames instead.
"""
assert http_transport.default_allowed_hosts(address, 9989) == []
# ── the grant on the request ───────────────────────────────────────────────
def test_current_grant_is_none_off_a_request():
"""The stdio case: no request context at all, and no restriction either."""
from mcp.server.lowlevel import Server
assert http_transport.current_grant(Server("probe")) is None
def test_offered_for_returns_everything_without_a_grant():
from mcp.server.lowlevel import Server
chooser = http_transport.offered_for(Server("probe"), tools.TOOLS)
assert chooser() == tools.TOOLS