Serve frontend via FastAPI native app.frontend()

Draft
CL
3mo ago
+162-16

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-exist with Accept: application/json) now return 404 instead of the SPA shell with 200.
  • Implementation: replaced the /assets + /favicons StaticFiles mounts, the Jinja2Templates instance, and the /{rest_of_path:path} catch-all with a single app.frontend("/", directory=FRONTEND_DIRECTORY / "dist", fallback="auto", check_dir=False) call. Removed the now-dead Jinja2Templates import and the FRONTEND_ASSET_DIRECTORY / FRONTEND_FAVICONS_DIRECTORY helpers, collapsing them into FRONTEND_DIST_DIRECTORY.
  • The registration is guarded by if FRONTEND_DIST_DIRECTORY.is_dir(), and check_dir=False, so a missing dist/ in development (where Vite serves the frontend separately) does not crash at import/startup — matching the previous exists() guard behavior.
  • Dependency bump: fastapi 0.136.3 → 0.141.1 (app.frontend() does not exist before 0.141) plus uv lock.
  • What stayed the same: /docs mount + redirect, /api-static mount, GZip include_paths (/assets and /favicons remain valid URL prefixes, now served from dist/), and schema/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 with Accept: application/json → 404,
  • an unknown /api/* path with Accept: 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 return 404.
  • Config/env changes: none. INFRAHUB_FRONTEND_DIRECTORY still 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