review(greptile): trim implementation commentary; fixture-own MCP registry state in tests

Addresses both P2s from the first Greptile pass:
- per_request_root_path_middleware.py (and the related _lazy_features /
  proxy_server comments) cut down to the constraints the code cannot
  express, per repo comment guidance
- the new discovery tests no longer clear/repopulate the shared MCP
  registry inline; a fixture snapshots it, hands the test an empty
  registry, and restores it afterwards so no state leaks between cases
This commit is contained in:
gym-cmd 2026-08-05 12:13:42 +01:00
parent 879e7c768e
commit 548bed2e49
4 changed files with 77 additions and 115 deletions

View file

@ -293,18 +293,14 @@ class LazyFeatureMiddleware:
if scope["type"] in ("http", "websocket") and len(self._loaded) < len(self._features):
path = scope.get("path", "")
# Strip the request's root_path so prefix matching works under a
# server root path. Without this, requests like
# /api/v1/policies/... never match the registered prefixes
# (/policies/...) and lazy features stay unloaded — every endpoint
# under them returns 404. scope["root_path"] is authoritative when
# set: the scalar SERVER_ROOT_PATH lands there via
# FastAPI(root_path=...), and PerRequestRootPathMiddleware
# (SERVER_ROOT_PATHS) resolves a per-request prefix there; the
# cached env scalar is the fallback for scopes built without it.
# The `+ "/"` boundary prevents false-positive matches (e.g.
# /apiv2 against root /api). If the path doesn't start with the
# prefix (e.g. a reverse proxy already stripped it), we leave it
# alone.
# server root path. Without this, requests like /api/v1/policies/...
# never match the registered prefixes (/policies/...) and lazy
# features stay unloaded — every endpoint under them returns 404.
# scope["root_path"] wins over the cached env scalar: FastAPI
# stamps SERVER_ROOT_PATH there, and PerRequestRootPathMiddleware
# resolves SERVER_ROOT_PATHS prefixes there per request. The
# `+ "/"` boundary prevents false-positive matches (e.g. /apiv2
# against root /api); a pre-stripped path is left alone.
root_path = str(scope.get("root_path", "")).rstrip("/") or self._root_path
if root_path and path.startswith(root_path + "/"):
path = path[len(root_path) :]

View file

@ -1,31 +1,14 @@
"""
Per-request ``root_path`` resolution for a proxy fronting several
client-visible URL path prefixes from one deployment (``SERVER_ROOT_PATHS``).
"""Per-request ``root_path`` resolution from ``SERVER_ROOT_PATHS``.
``SERVER_ROOT_PATH`` is a single scalar stamped onto the app at startup, so
one deployment serves exactly one client-visible prefix: Starlette strips that
prefix during route matching and rebuilds it into ``request.base_url``, and a
request under any other prefix 404s before a handler runs. A pod fronting
several ingress path prefixes (e.g. ``/tenant-a/*`` and ``/tenant-b/*`` both
terminating at the same LiteLLM) is therefore forced into one deployment per
prefix purely to encode it.
This middleware generalizes the same mechanism to N prefixes: the operator
lists the prefixes the ingress preserves, and the one matching an incoming
request becomes that request's ``scope["root_path"]``. Everything downstream
is unchanged Starlette behavior — route matching strips ``root_path``
(``starlette._utils.get_route_path``) so routes stay registered
root-relative, and ``request.base_url`` re-includes it, so every emitted URL
(the MCP OAuth discovery documents' RFC 9728 §3 ``resource`` and the 401
challenges' ``resource_metadata`` among them) lands under the prefix the
client actually called. A path under no configured prefix passes through
untouched: it routes root-relative exactly as today, and 404s otherwise.
Opt-in by design: LiteLLM cannot detect whether the proxy in front strips or
preserves the client-visible prefix. Setting ``SERVER_ROOT_PATHS`` is the
operator affirming the prefix reaches the pod intact (path-based ALB /
ingress routing); a topology that rewrites the path away must keep using the
scalar ``SERVER_ROOT_PATH`` / path-carrying ``PROXY_BASE_URL``.
``SERVER_ROOT_PATH`` is a startup scalar, so one deployment serves exactly one
client-visible URL path prefix; a request under any other prefix 404s before a
handler runs. When the ingress preserves several prefixes into one pod (e.g.
``/tenant-a/*`` and ``/tenant-b/*``), the matched prefix becomes that
request's ``scope["root_path"]`` instead: Starlette strips it during route
matching and rebuilds it into ``request.base_url``, so every emitted URL —
the MCP OAuth discovery ``resource`` (RFC 9728 §3) and the 401 challenges'
``resource_metadata`` among them — lands under the prefix the client called.
Opt-in: with ``SERVER_ROOT_PATHS`` unset the middleware is not added at all.
"""
import os
@ -40,11 +23,8 @@ SERVER_ROOT_PATHS_ENV: Final = "SERVER_ROOT_PATHS"
def normalize_root_paths(raw_paths: Sequence[str]) -> tuple[str, ...]:
"""Canonicalize configured prefixes: strip whitespace and trailing
slashes, dedupe, order longest-first so the most-specific nested prefix
wins at match time. Entries without a leading ``/`` and the bare root are
dropped with a warning — a typo'd prefix silently matching nothing would
surface only as unexplained 404s at request time."""
"""Strip whitespace and trailing slashes, dedupe, order longest-first;
warn and drop entries missing a leading ``/`` and the bare root."""
kept: list[str] = []
for entry in raw_paths:
candidate = entry.strip()
@ -79,17 +59,12 @@ def get_server_root_paths() -> tuple[str, ...]:
class PerRequestRootPathMiddleware:
"""ASGI middleware that sets ``scope["root_path"]`` to the configured
prefix matching the request path on a whole-segment boundary, leaving
``scope["path"]`` untouched (Starlette strips ``root_path`` from the path
at route-match time; stripping here too would double-strip).
Must be the outermost middleware (added last): inner middlewares and the
router need ``root_path`` already resolved — LazyFeatureMiddleware strips
it before feature prefix matching, Starlette strips it during route
matching. A matched prefix overrides a scalar ``root_path``
(``SERVER_ROOT_PATH``) for that request; combining both mechanisms is
warned about at startup.
"""Sets ``scope["root_path"]`` to the configured prefix matching the
request path on a whole-segment boundary. ``scope["path"]`` is left
untouched (Starlette strips ``root_path`` at route-match time). Must be
the outermost middleware so inner middlewares and the router see the
resolved value; a matched prefix overrides a scalar ``SERVER_ROOT_PATH``
for that request.
"""
def __init__(self, app: ASGIApp, root_paths: Sequence[str]) -> None:

View file

@ -16488,10 +16488,7 @@ app.add_middleware(
)
# Added last on purpose — last-added is outermost, and the client-visible URL
# prefix must be resolved into scope["root_path"] before any inner middleware
# or the router inspects the path: LazyFeatureMiddleware strips it for feature
# prefix matching, Starlette strips it for route matching, and
# request.base_url re-includes it in every emitted URL (the MCP OAuth
# discovery documents among them). Only added when SERVER_ROOT_PATHS is
# or the router inspects the path. Only added when SERVER_ROOT_PATHS is
# configured, so the default deployment's middleware stack is unchanged.
_server_root_paths: Final = get_server_root_paths()
if _server_root_paths:

View file

@ -8457,6 +8457,8 @@ async def test_authorize_wall_names_the_issuer_for_anchored_servers():
assert "verify the Issuer" in detail_text
assert "Servers with no url" not in detail_text
assert "idp.example.com" not in detail_text
def test_passthrough_authorization_code_round_trips_and_rejects_hostile_input():
"""The passthrough gateway code seals and recovers the ephemeral DCR client and upstream code,
and is total over hostile input: a raw upstream code opens to None, and a tampered or
@ -8865,7 +8867,9 @@ async def test_mint_ephemeral_dcr_client_unusable_registration_response_is_502(p
)
from litellm.types.mcp import MCPAuth
server = _bridge_server(auth_type=MCPAuth.true_passthrough, dcr_bridge=None, server_id=server_id, server_name=server_id)
server = _bridge_server(
auth_type=MCPAuth.true_passthrough, dcr_bridge=None, server_id=server_id, server_name=server_id
)
mock_response = MagicMock()
mock_response.text = json.dumps(payload)
mock_response.raise_for_status = MagicMock()
@ -8943,8 +8947,6 @@ async def test_token_exchange_authenticates_with_the_sealed_clients_own_auth_met
assert sent_body["client_secret"] == "mint-secret"
# ---------------------------------------------------------------------------
# LIT-4339: RFC 8707 resource indicators on the upstream OAuth legs
# ---------------------------------------------------------------------------
@ -9197,7 +9199,9 @@ def test_upstream_resource_auto_keeps_the_path_because_it_identifies_the_server(
sets ``upstream_resource`` explicitly instead of using ``auto``."""
from litellm.proxy._experimental.mcp_server.oauth_utils import resolve_upstream_resource
first = resolve_upstream_resource(_resource_server(url="https://gw.example.com/team-a/mcp", upstream_resource="auto"))
first = resolve_upstream_resource(
_resource_server(url="https://gw.example.com/team-a/mcp", upstream_resource="auto")
)
second = resolve_upstream_resource(
_resource_server(url="https://gw.example.com/team-b/mcp", upstream_resource="auto")
)
@ -9260,6 +9264,23 @@ def _no_proxy_base_url(monkeypatch):
monkeypatch.delenv("SERVER_ROOT_PATH", raising=False)
@pytest.fixture
def _isolated_mcp_registry():
"""Fixture-owned registry state: snapshot the shared registry, hand the
test an empty one, restore afterwards so nothing leaks between cases."""
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
global_mcp_server_manager,
)
saved = dict(global_mcp_server_manager.registry)
global_mcp_server_manager.registry.clear()
try:
yield global_mcp_server_manager.registry
finally:
global_mcp_server_manager.registry.clear()
global_mcp_server_manager.registry.update(saved)
def _prefixed_discovery_client(prefixes):
from fastapi import FastAPI
from fastapi.testclient import TestClient
@ -9276,7 +9297,7 @@ def _prefixed_discovery_client(prefixes):
class TestPerRequestRootPathDiscovery:
def test_prefixed_wellknown_not_routable_without_middleware(self):
def test_prefixed_wellknown_not_routable_without_middleware(self, _isolated_mcp_registry):
"""Control: on a plain app (the only shape a scalar root_path can
express), a prefixed well-known request 404s before any discovery
builder runs — the routing gap this feature exists to close."""
@ -9284,84 +9305,57 @@ class TestPerRequestRootPathDiscovery:
from fastapi.testclient import TestClient
from litellm.proxy._experimental.mcp_server.discoverable_endpoints import router
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
global_mcp_server_manager,
)
global_mcp_server_manager.registry.clear()
server = _create_oauth2_server(server_id="srv_a", name="server_a", server_name="server_a", alias="server_a")
global_mcp_server_manager.registry[server.server_id] = server
_isolated_mcp_registry[server.server_id] = server
app = FastAPI()
app.include_router(router)
client = TestClient(app)
try:
resp = client.get("/tenant-a/.well-known/oauth-protected-resource/mcp/server_a")
assert resp.status_code == 404
finally:
global_mcp_server_manager.registry.clear()
resp = client.get("/tenant-a/.well-known/oauth-protected-resource/mcp/server_a")
assert resp.status_code == 404
def test_two_prefixes_one_app_each_resource_matches_the_called_url(self, _no_proxy_base_url):
def test_two_prefixes_one_app_each_resource_matches_the_called_url(
self, _no_proxy_base_url, _isolated_mcp_registry
):
"""The multi-origin case itself: two prefixes served by the same app,
each per-server document's ``resource`` equal to the URL its client
called — including the prefix."""
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
global_mcp_server_manager,
)
global_mcp_server_manager.registry.clear()
for sid, name in (("srv_a", "server_a"), ("srv_b", "server_b")):
global_mcp_server_manager.registry[sid] = _create_oauth2_server(
server_id=sid, name=name, server_name=name, alias=name
)
_isolated_mcp_registry[sid] = _create_oauth2_server(server_id=sid, name=name, server_name=name, alias=name)
client = _prefixed_discovery_client(["/tenant-a", "/tenant-b"])
try:
resp_a = client.get("/tenant-a/.well-known/oauth-protected-resource/mcp/server_a")
resp_b = client.get("/tenant-b/.well-known/oauth-protected-resource/mcp/server_b")
assert resp_a.status_code == 200
assert resp_a.json()["resource"] == "http://testserver/tenant-a/mcp/server_a"
assert resp_b.status_code == 200
assert resp_b.json()["resource"] == "http://testserver/tenant-b/mcp/server_b"
resp_a = client.get("/tenant-a/.well-known/oauth-protected-resource/mcp/server_a")
resp_b = client.get("/tenant-b/.well-known/oauth-protected-resource/mcp/server_b")
# Every URL the document advertises stays under the request's
# prefix, so it resolves on this same app.
for auth_server in resp_a.json()["authorization_servers"]:
assert auth_server.startswith("http://testserver/tenant-a/")
finally:
global_mcp_server_manager.registry.clear()
assert resp_a.status_code == 200
assert resp_a.json()["resource"] == "http://testserver/tenant-a/mcp/server_a"
assert resp_b.status_code == 200
assert resp_b.json()["resource"] == "http://testserver/tenant-b/mcp/server_b"
def test_unprefixed_requests_unchanged_on_the_same_app(self, _no_proxy_base_url):
# Every URL the document advertises stays under the request's
# prefix, so it resolves on this same app.
for auth_server in resp_a.json()["authorization_servers"]:
assert auth_server.startswith("http://testserver/tenant-a/")
def test_unprefixed_requests_unchanged_on_the_same_app(self, _no_proxy_base_url, _isolated_mcp_registry):
"""Backward compat on the very same app: a root request emits the
document byte-identical to a deployment without the middleware."""
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
global_mcp_server_manager,
)
global_mcp_server_manager.registry.clear()
server = _create_oauth2_server(server_id="srv_a", name="server_a", server_name="server_a", alias="server_a")
global_mcp_server_manager.registry[server.server_id] = server
_isolated_mcp_registry[server.server_id] = server
client = _prefixed_discovery_client(["/tenant-a"])
try:
resp = client.get("/.well-known/oauth-protected-resource/mcp/server_a")
assert resp.status_code == 200
assert resp.json()["resource"] == "http://testserver/mcp/server_a"
finally:
global_mcp_server_manager.registry.clear()
resp = client.get("/.well-known/oauth-protected-resource/mcp/server_a")
assert resp.status_code == 200
assert resp.json()["resource"] == "http://testserver/mcp/server_a"
def test_unlisted_prefix_404s(self, _no_proxy_base_url):
client = _prefixed_discovery_client(["/tenant-a"])
assert client.get("/tenant-c/.well-known/oauth-protected-resource/mcp/server_a").status_code == 404
def test_aggregate_documents_and_as_endpoints_under_prefix(self, _no_proxy_base_url):
def test_aggregate_documents_and_as_endpoints_under_prefix(self, _no_proxy_base_url, _isolated_mcp_registry):
"""Aggregate PRM/AS documents carry the prefix, and the advertised
authorize endpoint actually resolves under it — the 404 trap that
invalidated prefixing discovery URLs without per-request routing
(#35226 review round 1)."""
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
global_mcp_server_manager,
)
global_mcp_server_manager.registry.clear()
client = _prefixed_discovery_client(["/tenant-a"])
prm = client.get("/tenant-a/.well-known/oauth-protected-resource/mcp")