Serve frontend via FastAPI native app.frontend()
Requested by Damien Garros · Slack thread
Draft / prototype for review.
Why
The web frontend was served by hand-rolled plumbing in backend/infrahub/server.py: two separate StaticFiles mounts (/assets and /favicons), a Jinja2Templates instance, per-subdirectory path derivation, and a catch-all route @app.get("/{rest_of_path:path}") that returned index.html for every unmatched path.
That catch-all matched anything, so a non-HTML request to an unknown /api/* path returned the SPA shell with a 200 instead of a 404. It also meant ongoing maintenance of per-directory mounts.
Before: any unmatched path (including an unknown /api/* fetched as JSON) → index.html, HTTP 200.
After: the frontend is served by FastAPI's native app.frontend(). It is registered as a low-priority route group consulted only after all API/GraphQL/metrics/static routes, and with fallback="auto" it serves index.html (200) only for browser navigation requests (Accept: text/html). A non-navigation request to an unknown path — e.g. an unknown /api/* fetched as JSON — now returns a real 404. Normal browser deep-links still resolve to index.html.
Goal: fix the 200-instead-of-404 behavior and drop maintenance of the per-directory mounts + Jinja catch-all.
Non-goals: the /docs (Docusaurus) mount + redirect and the /api-static mount are intentionally left as-is. Migrating /docs is an optional follow-up, out of scope here.
Closes #10097
What changed
- Behavioral: unknown non-navigation paths (e.g.
GET /api/does-not-existwithAccept: application/json) now return404instead of the SPA shell with200. - Implementation: replaced the
/assets+/faviconsStaticFilesmounts, theJinja2Templatesinstance, and the/{rest_of_path:path}catch-all with a singleapp.frontend("/", directory=FRONTEND_DIRECTORY / "dist", fallback="auto", check_dir=False)call. Removed the now-deadJinja2Templatesimport and theFRONTEND_ASSET_DIRECTORY/FRONTEND_FAVICONS_DIRECTORYhelpers, collapsing them intoFRONTEND_DIST_DIRECTORY. - The registration is guarded by
if FRONTEND_DIST_DIRECTORY.is_dir(), andcheck_dir=False, so a missingdist/in development (where Vite serves the frontend separately) does not crash at import/startup — matching the previousexists()guard behavior. - Dependency bump:
fastapi0.136.3 → 0.141.1(app.frontend()does not exist before 0.141) plusuv lock. - What stayed the same:
/docsmount + redirect,/api-staticmount, GZipinclude_paths(/assetsand/faviconsremain valid URL prefixes, now served fromdist/), andschema/openapi.json(the bump did not change the generated schema).
⚠️ Reviewer callout — dependency bump
This PR bumps FastAPI 0.136.3 → 0.141.1. New dependencies / version bumps are an "Ask First" item in this repo, so a human should sign off on this version bump. app.frontend() was introduced in the 0.14x line and is required for this change. The introspected signature the code was written against:
app.frontend(
path: str,
*,
directory: str | os.PathLike[str],
fallback: Literal["auto", "index.html", "404.html"] | None = "auto",
check_dir: bool | Literal["auto"] = "auto",
) -> None
How
app.frontend() adds the frontend as a low-priority route group (matched after all normal routes regardless of registration order), so it can never shadow /api, /graphql, /metrics, /api-static, or /docs. With fallback="auto", an unmatched path serves 404.html if present, otherwise index.html at 200 for navigation requests (Accept includes text/html / application/xhtml+xml), otherwise a real 404.
How to test
uv run pytest backend/tests/unit/api/test_frontend_serving.py -q
The added test asserts the contract this PR relies on:
- a known
/api/*route is not shadowed, - an unknown
/api/*path withAccept: application/json→404, - an unknown
/api/*path withAccept: text/html→index.html(200), - a browser deep-link →
index.html(200), /→index.html, and a static asset under/assets/is served.
Impact & rollout
- Backward compatibility: browser-facing behavior unchanged (deep-links still return
index.html). The only observable change is that unknown non-HTML requests now correctly return404. - Config/env changes: none.
INFRAHUB_FRONTEND_DIRECTORYstill honored. - Deployment notes: safe to deploy; ships the FastAPI bump.
Checklist
- Tests added/updated
- Changelog entry added (
changelog/10097.housekeeping.md) - External docs updated (no user-facing docs change)
- Internal .md docs updated
- I have reviewed AI generated content
Generated by Claude Code