Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: let the router skip routes whose path prefix cannot match (#15682)

Daniel Hanbcf036572afa
diff --git a/studio/backend/main.py b/studio/backend/main.py
index bbb3355839e..ebba73103a1 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -3289,3 +3289,9 @@ def setup_frontend(
# The lifespan reads this to decide whether engine paths need their own GET denial.
app.state.frontend_mounted = True
return True
+
+
+# Last, after every module-level route is registered; routes added later stay unguarded.
+from utils.route_prefix_guard import install_route_prefix_guards # noqa: E402
+
+install_route_prefix_guards(app.router.routes)
diff --git a/studio/backend/tests/test_route_prefix_guard.py b/studio/backend/tests/test_route_prefix_guard.py
new file mode 100644
index 00000000000..a6ce655124f
--- /dev/null
+++ b/studio/backend/tests/test_route_prefix_guard.py
@@ -0,0 +1,272 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The router skips entries whose literal path prefix rules a request out, and answers exactly as before."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import itertools
+import re
+
+import pytest
+from fastapi import APIRouter, FastAPI
+from starlette.responses import PlainTextResponse
+from starlette.routing import BaseRoute, Host, Match, Mount, Route
+
+
+def install_route_prefix_guards(routes):
+ # Imported per call so the main-app tests run (and fail) on a tree without the module.
+ from utils.route_prefix_guard import install_route_prefix_guards as install
+ return install(routes)
+
+
+def _leaf_paths(routes, prefix = ""):
+ for route in routes:
+ original = getattr(route, "original_router", None)
+ if original is not None:
+ yield from _leaf_paths(original.routes, prefix + route.include_context.prefix)
+ else:
+ path = getattr(route, "path", None)
+ if isinstance(path, str):
+ yield prefix + path
+
+
+def _path_corpus(routes) -> list:
+ """Each route path filled in, its slash flip, one level deeper, and every truncation at a separator."""
+ paths = {
+ "/",
+ "",
+ "/a",
+ "/api",
+ "/api/",
+ "/v1",
+ "/v1/",
+ "/assets/x.js",
+ "/mcp",
+ "/mcp/",
+ "/mcp/x",
+ "//api/health",
+ }
+ for path in _leaf_paths(routes):
+ concrete = re.sub(r"\{[^}]+\}", "x", path)
+ paths.update(
+ {concrete, concrete + "/", concrete.rstrip("/"), concrete + "/x", concrete[:-1]}
+ )
+ for i, ch in enumerate(concrete):
+ if ch == "/":
+ paths.add(concrete[:i])
+ return sorted(paths)
+
+
+def _scope(
+ method: str,
+ path: str,
+ *,
+ kind: str = "http",
+ root_path: str = "",
+) -> dict:
+ return {
+ "type": kind,
+ "method": method,
+ "path": path,
+ "raw_path": path.encode("latin-1", "replace"),
+ "root_path": root_path,
+ "query_string": b"",
+ "headers": [(b"host", b"127.0.0.1")],
+ }
+
+
+def _scopes(routes, *, variants: bool = True):
+ # GET finds FULL matches, PATCH (served by almost nothing) the PARTIAL ones behind a 405.
+ for path in _path_corpus(routes):
+ yield _scope("GET", path)
+ yield _scope("PATCH", path)
+ if variants:
+ yield _scope("GET", path, kind = "websocket")
+ yield _scope("GET", "/root" + path, root_path = "/root")
+
+
+def _original(entry):
+ guarded = vars(entry).get("matches")
+ return guarded.__wrapped__ if guarded is not None else entry.matches
+
+
+def _decision(routes, scope, *, original: bool):
+ """The router loop's choice: first FULL, else first PARTIAL, with the child scope it would apply."""
+ partial = None
+ for index, entry in enumerate(routes):
+ call = _original(entry) if original else entry.matches
+ match, child = call(copy.copy(scope))
+ if match == Match.FULL:
+ return "FULL", index, child
+ if match == Match.PARTIAL and partial is None:
+ partial = ("PARTIAL", index, child)
+ return partial or ("NONE", -1, {})
+
+
[email protected](scope = "module")
+def studio_app():
+ from main import app
+ return app
+
+
+def test_the_studio_app_guards_most_of_its_route_table(studio_app):
+ routes = studio_app.router.routes
+ guarded = [entry for entry in routes if "matches" in vars(entry)]
+ assert len(guarded) >= len(routes) * 0.8, (len(guarded), len(routes))
+
+
+def test_a_late_route_no_longer_runs_every_earlier_regex(studio_app, monkeypatch):
+ """/api/liveness is polled by the desktop app and sits behind ~800 routes. Before the guard every request
+ ran ~1600 route matches (an included router matches each candidate twice); with it, only entries whose
+ prefix fits the path are tried."""
+ import fastapi.routing as fastapi_routing
+ import starlette.routing as starlette_routing
+
+ calls = [0]
+ for cls in (
+ fastapi_routing.APIRoute,
+ starlette_routing.Route,
+ starlette_routing.Mount,
+ getattr(fastapi_routing, "_EffectiveRouteContext", None),
+ ):
+ if cls is None or "matches" not in cls.__dict__:
+ continue
+ stock = cls.__dict__["matches"]
+
+ def counted(
+ self,
+ scope,
+ _stock = stock,
+ ):
+ calls[0] += 1
+ return _stock(self, scope)
+
+ monkeypatch.setattr(cls, "matches", counted)
+
+ sent = []
+
+ async def receive():
+ return {"type": "http.request", "body": b"", "more_body": False}
+
+ async def send(message):
+ sent.append(message)
+
+ scope = _scope("GET", "/api/liveness")
+ scope.update(client = ("127.0.0.1", 50000), server = ("127.0.0.1", 8888), scheme = "http")
+ asyncio.run(studio_app(scope, receive, send))
+ assert sent and sent[0]["status"] == 200
+ assert calls[0] < 400, calls[0]
+
+
+def test_every_guarded_entry_answers_like_the_original(studio_app):
+ routes = studio_app.router.routes
+ guarded = [entry for entry in routes if "matches" in vars(entry)]
+ assert guarded
+ skipped = 0
+ for entry in guarded:
+ for scope in _scopes(routes):
+ fast = entry.matches(copy.copy(scope))
+ if fast == (Match.NONE, {}):
+ slow = _original(entry)(copy.copy(scope))
+ assert slow[0] == Match.NONE, (
+ entry,
+ scope["method"],
+ scope["path"],
+ scope["root_path"],
+ )
+ skipped += 1
+ assert skipped > 10_000
+
+
+def test_the_router_picks_the_same_route_for_every_request(studio_app):
+ routes = studio_app.router.routes
+ for scope in _scopes(routes, variants = False):
+ assert _decision(routes, scope, original = False) == _decision(
+ routes, scope, original = True
+ ), (scope["method"], scope["path"], scope["root_path"])
+
+
+def _endpoint(request):
+ return PlainTextResponse("ok")
+
+
+def test_unprovable_entries_are_left_alone():
+ class HeaderRoute(Route):
+ def matches(self, scope):
+ return Match.FULL, {"endpoint": self.endpoint}
+
+ shared = Route("/shared/{x}", _endpoint)
+ inner = APIRouter()
+ inner.routes.append(shared)
+ app = FastAPI()
+ app.router.routes.append(Host("example.com", app = PlainTextResponse("host")))
+ app.router.routes.append(HeaderRoute("/custom", _endpoint))
+ app.router.routes.append(Route("/{anything:path}", _endpoint))
+ app.router.routes.append(shared)
+ app.include_router(inner, prefix = "/inner")
+ with_host = APIRouter()
+ with_host.routes.append(Host("example.com", app = PlainTextResponse("host")))
+ app.include_router(with_host, prefix = "/hosted")
+
+ install_route_prefix_guards(app.router.routes)
+
+ by_kind = {type(entry).__name__: entry for entry in app.router.routes}
+ assert "matches" not in vars(by_kind["Host"])
+ assert "matches" not in vars(by_kind["HeaderRoute"])
+ catch_all = next(e for e in app.router.routes if getattr(e, "path", None) == "/{anything:path}")
+ assert "matches" not in vars(catch_all)
+ included = [e for e in app.router.routes if getattr(e, "original_router", None) is not None]
+ if included:
+ assert "matches" not in vars(shared)
+ hosted = [e for e in included if e.original_router is with_host]
+ assert hosted and "matches" not in vars(hosted[0])
+
+
+def test_root_path_requests_take_the_original_path():
+ app = FastAPI()
+ app.add_api_route("/api/thing", lambda: {"ok": True})
+ install_route_prefix_guards(app.router.routes)
+ entry = next(e for e in app.router.routes if getattr(e, "path", None) == "/api/thing")
+ assert "matches" in vars(entry)
+ match, _ = entry.matches(_scope("GET", "/prefix/api/thing", root_path = "/prefix"))
+ assert match == Match.FULL
+
+
+def test_install_is_idempotent_and_keeps_order():
+ app = FastAPI()
+ app.add_api_route("/a/b", lambda: 1)
+ app.mount("/static", PlainTextResponse("s"))
+ router = APIRouter()
+ router.add_api_route("/c", lambda: 2)
+ app.include_router(router, prefix = "/r")
+ before = list(app.router.routes)
+ first = install_route_prefix_guards(app.router.routes)
+ wrapped = {id(e): vars(e).get("matches") for e in app.router.routes}
+ second = install_route_prefix_guards(app.router.routes)
+ assert first == second >= 3
+ assert list(app.router.routes) == before
+ assert {id(e): vars(e).get("matches") for e in app.router.routes} == wrapped
+
+
+def test_mount_guard_matches_the_mount_regex():
+ mount = Mount("/mcp", app = PlainTextResponse("m"))
+ install_route_prefix_guards([mount])
+ assert "matches" in vars(mount)
+ for path, method in itertools.product(
+ ("/mcp", "/mcp/", "/mcp/x", "/mcpx", "/mc", "/", "/other/mcp/"), ("GET", "POST")
+ ):
+ scope = _scope(method, path)
+ assert mount.matches(copy.copy(scope)) == _original(mount)(copy.copy(scope)), path
+
+
+def test_guard_is_a_plain_route_attribute():
+ """Openapi, url_path_for and isinstance checks see the same route objects."""
+ app = FastAPI()
+ app.add_api_route("/x/{y}", lambda y: y, name = "xy")
+ install_route_prefix_guards(app.router.routes)
+ assert all(isinstance(e, BaseRoute) for e in app.router.routes)
+ assert app.url_path_for("xy", y = "1") == "/x/1"
+ assert "/x/{y}" in app.openapi()["paths"]
diff --git a/studio/backend/utils/route_prefix_guard.py b/studio/backend/utils/route_prefix_guard.py
new file mode 100644
index 00000000000..b79c131046a
--- /dev/null
+++ b/studio/backend/utils/route_prefix_guard.py
@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Let the router skip route-table entries whose literal path prefix rules the request out.
+
+A route regex is anchored at the literal text before its first ``{``, so a path not starting with it
+is ``Match.NONE``; the guard answers that without the regex. Entries it cannot prove path-anchored
+(Host routes, ``matches`` overrides, ``root_path`` requests) keep the original code path.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from starlette.routing import BaseRoute, Match, Mount, Route, WebSocketRoute
+
+try:
+ from fastapi.routing import APIRoute, APIWebSocketRoute
+except Exception: # pragma: no cover
+ APIRoute = APIWebSocketRoute = None
+
+_PATH_ROUTE_TYPES = tuple(
+ cls for cls in (Route, WebSocketRoute, Mount, APIRoute, APIWebSocketRoute) if cls is not None
+)
+_STOCK_MATCHES = frozenset(cls.matches for cls in _PATH_ROUTE_TYPES)
+_GUARD_MARK = "_unsloth_prefix_guard"
+
+
+def _literal_prefix(path: Any) -> Optional[str]:
+ if not isinstance(path, str) or not path.startswith("/"):
+ return None
+ literal = path.split("{", 1)[0]
+ return literal if len(literal) > 1 else None
+
+
+def _stock_path_route(route: Any) -> bool:
+ return isinstance(route, _PATH_ROUTE_TYPES) and type(route).matches in _STOCK_MATCHES
+
+
+def _included_router_parts(entry: Any):
+ """(prefix, original_router) for FastAPI's lazy included-router entry, else None."""
+ cls = type(entry)
+ if cls.__name__ != "_IncludedRouter" or cls.__module__ != "fastapi.routing":
+ return None
+ prefix = getattr(getattr(entry, "include_context", None), "prefix", None)
+ original = getattr(entry, "original_router", None)
+ if not isinstance(prefix, str) or original is None:
+ return None
+ return prefix, original
+
+
+def _subtree_is_path_anchored(router: Any, seen: set) -> bool:
+ if id(router) in seen:
+ return True
+ seen.add(id(router))
+ for route in getattr(router, "routes", None) or ():
+ nested = _included_router_parts(route)
+ if nested is not None:
+ if not _subtree_is_path_anchored(nested[1], seen):
+ return False
+ elif not _stock_path_route(route):
+ return False
+ return True
+
+
+def _leaf_ids(router: Any, out: set, seen: set) -> set:
+ if id(router) in seen:
+ return out
+ seen.add(id(router))
+ for route in getattr(router, "routes", None) or ():
+ nested = _included_router_parts(route)
+ if nested is not None:
+ _leaf_ids(nested[1], out, seen)
+ else:
+ out.add(id(route))
+ return out
+
+
+def _guard_prefix(entry: Any, shared_leaf_ids: set) -> Optional[str]:
+ included = _included_router_parts(entry)
+ if included is not None:
+ prefix, original = included
+ if not _subtree_is_path_anchored(original, set()):
+ return None
+ return _literal_prefix(prefix)
+ if not _stock_path_route(entry):
+ return None
+ # Also reachable via an included router: matched there on its prefixed path through this method.
+ if id(entry) in shared_leaf_ids:
+ return None
+ return _literal_prefix(getattr(entry, "path", None))
+
+
+def _guarded(matches: Callable, prefix: str) -> Callable:
+ def guarded_matches(scope):
+ # get_route_path strips root_path first; only the raw path is safe to compare.
+ if not scope.get("root_path") and not scope["path"].startswith(prefix):
+ return Match.NONE, {}
+ return matches(scope)
+
+ guarded_matches.__wrapped__ = matches
+ setattr(guarded_matches, _GUARD_MARK, prefix)
+ return guarded_matches
+
+
+def install_route_prefix_guards(routes: list) -> int:
+ """Guard each eligible top-level entry; returns how many are guarded. Idempotent."""
+ shared: set = set()
+ for entry in routes:
+ included = _included_router_parts(entry)
+ if included is not None:
+ _leaf_ids(included[1], shared, set())
+ count = 0
+ for entry in routes:
+ if not isinstance(entry, BaseRoute):
+ continue
+ try:
+ own = vars(entry)
+ except TypeError:
+ continue
+ if _GUARD_MARK in own:
+ count += 1
+ continue
+ prefix = _guard_prefix(entry, shared)
+ if prefix is None:
+ continue
+ try:
+ entry.matches = _guarded(entry.matches, prefix)
+ setattr(entry, _GUARD_MARK, prefix)
+ except (AttributeError, TypeError):
+ continue
+ count += 1
+ return count