simple-module-hosting 0.0.32__tar.gz → 0.0.34__tar.gz

{simple_module_hosting-0.0.32 → simple_module_hosting-0.0.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_hosting
-Version: 0.0.32
+Version: 0.0.34
 Summary: FastAPI + Inertia.js host runtime for simple_module — app_builder, middleware stack, CLI (sm / simple-module), scaffolding
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -27,8 +27,8 @@ Requires-Dist: fastapi>=0.115
 Requires-Dist: httpx>=0.27
 Requires-Dist: itsdangerous>=2.0
 Requires-Dist: jinja2>=3.1
-Requires-Dist: simple-module-core==0.0.32
-Requires-Dist: simple-module-db==0.0.32
+Requires-Dist: simple-module-core==0.0.34
+Requires-Dist: simple-module-db==0.0.34
 Requires-Dist: starlette>=0.44
 Requires-Dist: tomlkit>=0.13
 Requires-Dist: uvicorn[standard]>=0.34

{simple_module_hosting-0.0.32 → simple_module_hosting-0.0.34}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_hosting"
-version = "0.0.32"
+version = "0.0.34"
 description = "FastAPI + Inertia.js host runtime for simple_module — app_builder, middleware stack, CLI (sm / simple-module), scaffolding"
 readme = "README.md"
 license = "MIT"
@@ -30,8 +30,8 @@ dependencies = [
     # it directly — out-of-tree hosts have nothing else pulling it in.
     "itsdangerous>=2.0",
     "jinja2>=3.1",
-    "simple_module_core==0.0.32",
-    "simple_module_db==0.0.32",
+    "simple_module_core==0.0.34",
+    "simple_module_db==0.0.34",
     "starlette>=0.44",
     "tomlkit>=0.13",
     "uvicorn[standard]>=0.34",

{simple_module_hosting-0.0.32 → simple_module_hosting-0.0.34}/simple_module_hosting/__init__.py

@@ -1,5 +1,6 @@
 """SimpleModule Hosting - App builder, module loader, middleware pipeline."""
 
+from simple_module_hosting._preapp_config import merge_host_settings
 from simple_module_hosting.app_builder import create_app
 from simple_module_hosting.logging import correlation_id, setup_logging
 from simple_module_hosting.settings import Settings
@@ -13,6 +14,7 @@ __all__ = [
     "SharedPropsProvider",
     "correlation_id",
     "create_app",
+    "merge_host_settings",
     "register_inertia_shared_provider",
     "setup_logging",
 ]

simple_module_hosting-0.0.34/simple_module_hosting/_error_handlers.py

@@ -0,0 +1,286 @@
+"""Framework-wide exception handlers that render Inertia error pages."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from http import HTTPStatus
+
+from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from inertia import (
+    Inertia,
+    InertiaConfig,
+    InertiaVersionConflictException,
+    inertia_version_conflict_exception_handler,
+)
+from simple_module_core.exceptions import NotFoundError
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import Response
+
+from simple_module_hosting._inertia_shared import _INERTIA_HEADER
+from simple_module_hosting._inertia_url import patch_relative_page_url
+from simple_module_hosting.permissions import PERMISSION_DENIED_PREFIX
+
+logger = logging.getLogger(__name__)
+
+_INERTIA_ERROR_STATUSES = frozenset({401, 403, 404, 419, 422, 429, 500, 503})
+
+# Statuses whose remedy is "sign in", so the page offers that as its primary
+# action rather than sending the visitor to the landing page.
+_SIGN_IN_STATUSES = frozenset({401, 419})
+
+
+def _specific_detail(status_code: int, message: str) -> str:
+    """The detail, unless it only restates the status.
+
+    Starlette defaults ``HTTPException.detail`` to ``HTTPStatus(code).phrase``,
+    so a plain ``HTTPException(404)`` reaches the page carrying "Not Found" and
+    a bare ``HTTPException(403)`` carrying "Forbidden". The page prefers a
+    server message over its own catalog description — right when the message
+    says something ("Administrator access required"), useless when it is the
+    title again in Title Case, and it made the page's own 404/403 sentences
+    unreachable on the very paths that produce them.
+
+    Only an exact, case-insensitive match is dropped: anything a caller
+    actually wrote survives, including a sentence that merely starts with the
+    phrase. Non-standard codes (419) have no phrase to collide with.
+    """
+    try:
+        phrase = HTTPStatus(status_code).phrase
+    except ValueError:
+        return message
+    return "" if message.strip().casefold() == phrase.casefold() else message
+
+
+def _required_permission(message: str) -> str | None:
+    """The permission named by a ``RequiresPermission`` denial, if this is one.
+
+    The 403 page says "Your role doesn't include ``<perm>``. Ask an admin to
+    grant it." — it needs the bare permission name, not the sentence the guard
+    wrote for logs and API clients. Reading it back off the detail (using the
+    guard's own exported prefix) keeps ``RequiresPermission`` as the single
+    place that knows the name; the alternative, stashing it on
+    ``request.state``, only works when the exception travels the one code path
+    that set it, and 403s are also raised by hand.
+
+    Anything else — a role-gated ``/admin`` 403, a hand-raised
+    ``HTTPException(403, "Administrator access required")`` — yields ``None``,
+    and the page falls back to copy that names no permission.
+    """
+    if not message.startswith(PERMISSION_DENIED_PREFIX):
+        return None
+    return message[len(PERMISSION_DENIED_PREFIX) :].strip() or None
+
+
+def _login_url(request: Request) -> str | None:
+    """Best-effort login URL for the sign-in statuses.
+
+    Read off ``app.state`` rather than imported: the auth provider is a plugin
+    concern and ``SM009`` forbids framework code importing ``modules/*``. An
+    app with no auth provider installed simply gets no sign-in button.
+    """
+    auth_state = getattr(request.app.state, "auth", None)
+    provider = getattr(auth_state, "auth_provider", None)
+    if provider is None:
+        return None
+    try:
+        return provider.get_login_url(request)
+    except Exception:
+        # A broken provider must not turn an error page into a second error.
+        logger.exception("Auth provider failed to supply a login URL")
+        return None
+
+
+def _explicit_accept_q(accept: str, media_type: str) -> float | None:
+    """Quality the Accept header gives ``media_type`` by explicit listing, or
+    ``None`` when the caller never named it at all.
+
+    Only exact entries count (no ``*/*`` / ``type/*`` wildcards) — the
+    negotiation below cares whether the caller *named* html or json, and at
+    what preference, and separately whether they named it *at all* (``None``
+    vs. an explicit ``q=0``). Malformed q-values fall back to 1.0 per RFC 9110.
+    """
+    for part in accept.split(","):
+        media, _, params = part.partition(";")
+        if media.strip().lower() != media_type:
+            continue
+        q = 1.0
+        for param in params.split(";"):
+            name, _, value = param.partition("=")
+            if name.strip().lower() == "q":
+                try:
+                    q = float(value.strip())
+                except ValueError:
+                    q = 1.0
+        return q
+    return None
+
+
+def _wants_json(request: Request) -> bool:
+    """API callers get JSON error bodies; browser-shaped requests get the page.
+
+    A request that explicitly accepts ``text/html`` is a browser navigation —
+    and those reach ``/api/*`` too (OAuth login links, file-download hrefs) —
+    so it always gets the rendered page, unless the caller *prefers* JSON via
+    q-values (``application/json, text/html;q=0.5`` is an API client keeping
+    an html fallback). So does an Inertia visit (``X-Inertia`` header),
+    whatever its Accept — an Inertia client can only consume Inertia-protocol
+    responses, never a bare JSON body. Otherwise ``/api/*``, the documented
+    prefix for every module's JSON surface (``ModuleMeta.route_prefix``),
+    gets JSON — a bare ``fetch()`` sends ``Accept: */*`` — as does an
+    explicit ``Accept: application/json`` anywhere else.
+
+    ``text/html;q=0`` rules html out *everywhere*, not just under ``/api/*``:
+    once the caller has explicitly said they won't accept html, this never
+    chooses the html page. The (already-moot) html fallback survives only
+    when json wasn't mentioned either — there's nothing else to offer, so a
+    view path keeps its pre-existing default and an ``/api/*`` path keeps
+    getting JSON either way.
+    """
+    if request.headers.get(_INERTIA_HEADER):
+        return False
+    accept = request.headers.get("accept", "")
+    html_q = _explicit_accept_q(accept, "text/html")
+    json_q = _explicit_accept_q(accept, "application/json")
+    if html_q is not None and html_q > 0 and html_q >= (json_q or 0.0):
+        return False
+    path = request.url.path
+    is_api = path == "/api" or path.startswith("/api/")
+    if html_q == 0:
+        return is_api if json_q is None else True
+    return is_api or bool(json_q)
+
+
+async def render_error_page(
+    request: Request,
+    status_code: int,
+    message: str,
+    headers: Mapping[str, str] | None = None,
+) -> Response:
+    """Render the Inertia error page for *status_code*.
+
+    ``headers`` carries an ``HTTPException``'s own headers through to the
+    response. A rendered page is still the same status as the JSON body it
+    replaces, so ``WWW-Authenticate`` on a 401 and ``Retry-After`` on a
+    429/503 have to survive the switch — widening the set of statuses that
+    render a page must not quietly narrow what those responses carry.
+    """
+    try:
+        # Inside the try, not above it: this lookup is exactly the kind of
+        # thing that is missing when the app is half-built, and an error page
+        # that raises while reporting an error leaves the caller with nothing.
+        config: InertiaConfig = request.app.state.sm.inertia_config
+        # Prefer the app's configured dependency over constructing Inertia
+        # directly: it carries the framework's wraps, and an error page built
+        # around them is an error page rendered differently from every other
+        # page. That is how the 404 kept throwing the cross-scheme `pushState`
+        # SecurityError after the page url was made relative everywhere else.
+        # The raw construction stays as the fallback for a half-built app —
+        # the case this whole handler exists to survive — but still goes
+        # through the same url-relativizing patch directly: a fallback that
+        # skipped it would reintroduce the exact bug this module exists to
+        # fix, just for the one request that hit it before setup finished.
+        inertia_dep = getattr(request.app.state, "inertia_dependency", None)
+        if inertia_dep is not None:
+            inertia = inertia_dep(request, None)
+        else:
+            inertia = patch_relative_page_url(Inertia(request, config))
+        # This does not go through get_inertia, so the share step has to be
+        # repeated here. Without it the error page renders raw translation keys
+        # (host.error.not_found_title) and loses auth/menus, so a signed-in
+        # user's 404 has no layout.
+        shared = getattr(request.state, "inertia_shared", None)
+        if shared:
+            inertia.share(**shared)
+        # The correlation id is the only handle a user has on their own failed
+        # request — without it a support report is just "it broke". It is already
+        # on every log line for this request, so quoting it back makes the page
+        # and the logs joinable.
+        response = await inertia.render(
+            "Error",
+            {
+                "status": status_code,
+                # Not the raw detail: a default one is just the status phrase,
+                # and the page renders any message it is given ahead of its own
+                # copy. See `_specific_detail`.
+                "message": _specific_detail(status_code, message),
+                "correlation_id": getattr(request.state, "correlation_id", "") or "",
+                # Always present, null when no permission is involved: the page
+                # branches on it, and an absent prop is indistinguishable there
+                # from one that was never wired.
+                "required_permission": _required_permission(message),
+                "login_url": (_login_url(request) if status_code in _SIGN_IN_STATUSES else None),
+                # Set by MaintenanceMiddleware. A planned outage reads very
+                # differently from the same status code arriving unbidden.
+                "maintenance": bool(getattr(request.state, "maintenance", False)),
+            },
+        )
+        response.status_code = status_code
+        _apply_headers(response, headers)
+        return response
+    except InertiaVersionConflictException as exc:
+        return await inertia_version_conflict_exception_handler(request, exc)
+    except Exception:
+        # Fallback if Inertia rendering itself fails (e.g. missing session)
+        logger.exception("Error page rendering failed, falling back to JSON")
+        return JSONResponse(
+            status_code=status_code,
+            content={"detail": message or "Internal Server Error"},
+            headers=dict(headers) if headers else None,
+        )
+
+
+def _apply_headers(response: Response, headers: Mapping[str, str] | None) -> None:
+    """Copy exception headers onto an already-built response.
+
+    Set rather than appended: these are single-valued response headers, and
+    a duplicate ``Retry-After`` is worse than none.
+    """
+    if not headers:
+        return
+    for key, value in headers.items():
+        response.headers[key] = value
+
+
+async def http_exception_handler(request: Request, exc: HTTPException) -> Response:
+    # Preserve exception headers (WWW-Authenticate, Retry-After, ...) the way
+    # FastAPI's stock handler does — on the rendered page as well as the JSON
+    # body, since both answer with the same status.
+    headers = getattr(exc, "headers", None)
+    if exc.status_code in _INERTIA_ERROR_STATUSES and not _wants_json(request):
+        detail = str(exc.detail) if exc.detail else ""
+        return await render_error_page(request, exc.status_code, detail, headers)
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"detail": exc.detail},
+        headers=headers,
+    )
+
+
+async def not_found_error_handler(request: Request, exc: NotFoundError) -> Response:
+    if _wants_json(request):
+        return JSONResponse(status_code=404, content={"detail": str(exc)})
+    return await render_error_page(request, 404, str(exc))
+
+
+async def request_validation_error_handler(
+    request: Request, exc: RequestValidationError
+) -> Response:
+    """Return an Inertia error page for browser requests with invalid params.
+
+    Same negotiation rule as 403/404/500 (``_wants_json``), so one request
+    never sees two different error shapes depending on the error class.
+    """
+    if _wants_json(request):
+        return JSONResponse(status_code=422, content={"detail": jsonable_encoder(exc.errors())})
+    return await render_error_page(request, 422, "The requested URL contains invalid parameters.")
+
+
+async def unhandled_exception_handler(request: Request, exc: Exception) -> Response:
+    logger.exception("Unhandled exception: %s", exc)
+    if _wants_json(request):
+        return JSONResponse(status_code=500, content={"detail": "Internal Server Error"})
+    return await render_error_page(request, 500, "")

simple_module_hosting-0.0.34/simple_module_hosting/_favicon.py

@@ -0,0 +1,94 @@
+"""The favicon an install has before anyone uploads one.
+
+Without a default, ``index.html`` emitted no ``<link rel="icon">`` at all, so
+every browser fell back to its implicit ``/favicon.ico`` request — which this
+app does not route. Anonymous visitors got a 302 to the login page (an HTML
+document offered as an image), authenticated ones a 404, and either way a
+console error on every full page load, on a brand-new install that has done
+nothing wrong.
+
+Rendered as an SVG ``data:`` URI rather than a file so there is nothing to
+mount, nothing to exempt from auth, and nothing to ship in the image: the
+static mount is a build artifact (``host/static/dist`` is generated), and a
+route would need its own public-route rule. ``img-src`` already allows
+``data:``, so the strict CSP is untouched.
+
+The mark mirrors ``BrandingMark``'s fallback badge — the app's initial on the
+brand gradient — so the tab icon and the in-app logo are the same thing, for
+whatever the app is named. An uploaded favicon still wins; this is only the
+floor.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from urllib.parse import quote
+from xml.sax.saxutils import escape as _xml_escape
+
+#: sRGB for `--color-primary-600` / `--color-primary-800`
+#: (`oklch(0.59 0.14 158)` / `oklch(0.42 0.09 175)`), the two stops of
+#: `BRAND_ACCENT`. Hard-coded because a data URI cannot read a CSS custom
+#: property — kept beside the tokens they mirror in `ui/styles/globals.css`.
+_ACCENT_FROM = "#00955c"
+_ACCENT_TO = "#005c4a"
+
+_SVG = (
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">'
+    '<defs><linearGradient id="a" x1="0" y1="0" x2="1" y2="1">'
+    '<stop offset="0" stop-color="{from_}"/>'
+    '<stop offset="1" stop-color="{to}"/>'
+    "</linearGradient></defs>"
+    '<rect width="64" height="64" rx="14" fill="url(#a)"/>'
+    '<text x="32" y="45" text-anchor="middle" fill="#fff" font-size="34" '
+    'font-weight="700" font-family="system-ui,-apple-system,Segoe UI,'
+    'Roboto,sans-serif">{initial}</text>'
+    "</svg>"
+)
+
+
+@lru_cache(maxsize=64)
+def default_favicon_data_uri(app_name: str, accent: str = "") -> str:
+    """An SVG data URI showing ``app_name``'s initial on the brand gradient.
+
+    ``accent`` is branding's configured primary colour: when set it replaces
+    both gradient stops with the flat brand colour, so a customised install's
+    tab icon matches the rest of its chrome. Already validated as a hex colour
+    by ``BrandingSettings``; anything else is ignored rather than trusted into
+    the markup.
+
+    Pure function of its two arguments, cached: ``branding_head`` calls it on
+    every full page render, and with no favicon uploaded — the state every
+    install starts in — that means every single page load rebuilds and
+    re-quotes the same SVG. The cache is keyed on ``(app_name, accent)``, both
+    of which only change when an admin edits branding settings.
+    """
+    initial = _initial(app_name)
+    from_, to = (accent, accent) if _is_hex_colour(accent) else (_ACCENT_FROM, _ACCENT_TO)
+    svg = _SVG.format(from_=from_, to=to, initial=initial)
+    # Everything structural is encoded — `#` above all, or the browser reads
+    # the gradient reference as the URI's fragment and the shape loses its
+    # fill, but also `"`, `<`, `>` and spaces so the result stays a single
+    # valid attribute value without relying on the template's escaping. The
+    # safe set is only characters that are already legal unencoded in a URI.
+    return "data:image/svg+xml," + quote(svg, safe="/:=,;()-_.'")
+
+
+def _initial(app_name: str) -> str:
+    """First character of the app name, XML-escaped, defaulting to ``S``.
+
+    Matches ``BrandingMark``'s ``appName.trim().charAt(0).toUpperCase() || 'S'``
+    so the tab and the sidebar badge never disagree.
+    """
+    raw = (app_name or "").strip()[:1].upper() or "S"
+    return _xml_escape(raw)
+
+
+def _is_hex_colour(value: str) -> bool:
+    """Whether ``value`` is a ``#rgb``/``#rrggbb`` literal safe to interpolate."""
+    if not value.startswith("#"):
+        return False
+    body = value[1:]
+    return len(body) in (3, 6) and all(c in "0123456789abcdefABCDEF" for c in body)
+
+
+__all__ = ["default_favicon_data_uri"]

{simple_module_hosting-0.0.32 → simple_module_hosting-0.0.34}/simple_module_hosting/_inertia_setup.py

@@ -12,7 +12,9 @@ from fastapi import FastAPI
 from inertia import InertiaConfig, inertia_dependency_factory
 from starlette.requests import Request
 
+from simple_module_hosting._favicon import default_favicon_data_uri
 from simple_module_hosting._inertia_json import json_safe_inertia_dependency
+from simple_module_hosting._inertia_url import relative_page_url_dependency
 from simple_module_hosting.settings import Settings
 
 logger = logging.getLogger(__name__)
@@ -40,16 +42,22 @@ def branding_head(request: Request) -> dict:
     The favicon URL is read from the module rather than assembled here: branding
     owns its route shape, and framework code must not reach into a plugin
     (SM009). ``BrandingHead`` still applies it client-side too, so a favicon
-    changed at runtime updates without a reload.
+    changed at runtime updates without a reload. When nothing has been uploaded
+    — the state every install starts in — it falls back to a generated mark
+    rather than ``None``, because omitting the tag sends the browser to
+    ``/favicon.ico``, which this app does not serve.
     """
     services = getattr(request.app.state, "branding", None)
     settings = getattr(services, "settings", None)
-    if settings is None:
-        return {"app_name": _DEFAULT_APP_NAME, "theme_color": None, "favicon_url": None}
+    app_name = getattr(settings, "app_name", "") or _DEFAULT_APP_NAME
+    accent = getattr(settings, "primary_color", "") or ""
+    favicon_url = getattr(services, "favicon_url", None) or default_favicon_data_uri(
+        app_name, accent
+    )
     return {
-        "app_name": getattr(settings, "app_name", "") or _DEFAULT_APP_NAME,
-        "theme_color": getattr(settings, "primary_color", "") or None,
-        "favicon_url": getattr(services, "favicon_url", None),
+        "app_name": app_name,
+        "theme_color": accent or None,
+        "favicon_url": favicon_url,
     }
 
 
@@ -185,9 +193,15 @@ def setup_inertia(
         use_flash_errors=True,
     )
 
-    # Upstream's JSON branch builds a Starlette JSONResponse directly, so the
-    # encoder configured above only ever applies to full page loads. Wrap the
-    # dependency so a client-side visit encodes the same props the same way.
-    inertia_dep = json_safe_inertia_dependency(inertia_dependency_factory(inertia_config))
+    # Two wraps over the stock dependency, each closing a gap in upstream:
+    #   * JSON branch builds a Starlette JSONResponse directly, so the encoder
+    #     configured above only ever applies to full page loads — wrap it so a
+    #     client-side visit encodes the same props the same way.
+    #   * The page url is absolute, which the browser rejects for pushState
+    #     behind a TLS-terminating proxy — wrap it back to the root-relative
+    #     path the Inertia protocol specifies.
+    inertia_dep = relative_page_url_dependency(
+        json_safe_inertia_dependency(inertia_dependency_factory(inertia_config))
+    )
     app.state.inertia_dependency = inertia_dep
     return inertia_config

{simple_module_hosting-0.0.32 → simple_module_hosting-0.0.34}/simple_module_hosting/_inertia_shared.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import logging
+from collections.abc import Callable
 from typing import Any
 
+from simple_module_core.i18n import Translator
 from starlette.datastructures import Headers
 from starlette.requests import Request
 from starlette.types import Scope
@@ -77,6 +79,30 @@ def build_i18n_block(scope: Scope, request: Request, *, is_authenticated: bool =
     }
 
 
+def build_menu_translator(request: Request) -> Callable[[str], str] | None:
+    """Return a locale-bound translator for menu labels, or None if unavailable.
+
+    Menu labels are translated on the server rather than in the client: the
+    payload then carries finished text, so the sidebar, topbar and command
+    palette all keep rendering ``item.label`` unchanged. It also sidesteps the
+    catalog audience split — an admin-audience module's labels never have to be
+    present in the anonymous snapshot to be readable.
+
+    Mirrors ``build_i18n_block``'s defensive lookups: test fixtures build apps
+    with a partial ``app.state.sm``, and a missing registry must degrade to the
+    literal labels rather than raise on every request.
+    """
+    sm = getattr(request.app.state, "sm", None)
+    registry = getattr(sm, "i18n_registry", None) if sm is not None else None
+    locale = getattr(request.state, "locale", None)
+    if registry is None or locale is None:
+        return None
+    settings = getattr(sm, "settings", None)
+    default_locale = getattr(settings, "i18n_default_locale", "en") if settings else "en"
+    translator = Translator(registry, locale=locale, default_locale=default_locale)
+    return translator.t
+
+
 def merge_shared_prop_providers(app: Any, request: Request, shared: dict) -> None:
     """Merge module-registered Inertia shared-prop providers into ``shared`` in place.
 

simple_module_hosting-0.0.34/simple_module_hosting/_inertia_url.py

@@ -0,0 +1,131 @@
+"""Make Inertia's page ``url`` root-relative, as the protocol specifies.
+
+``fastapi-inertia`` builds the page object with the *absolute* request url::
+
+    page_data = {
+        "component": self._component,
+        "props": await self._build_props(),
+        "url": str(self._request.url),      # http://host:8000/dashboard/
+        "version": self._config.version,
+    }
+
+The Inertia protocol says otherwise — every official adapter emits a
+root-relative path (Laravel's ``$request->getRequestUri()``, Rails'
+``request.original_fullpath``), and the documented page object is
+``{"component": "Event", "props": {...}, "url": "/events/80", ...}``. The
+client hands that value straight to ``history.pushState``/``replaceState``,
+which resolves a relative url against the current document and so can never
+disagree with it.
+
+An absolute url can, and behind a TLS-terminating reverse proxy it always
+does. The proxy speaks https to the browser and http to the container, so
+``request.url`` is ``http://…`` while the document origin is ``https://…``,
+and the browser rejects the state write::
+
+    SecurityError: Failed to execute 'pushState' on 'History': A history state
+    object with URL 'http://example.com/' cannot be created in a document with
+    origin 'https://example.com' and URL 'https://example.com/'
+
+That fires on *every* page — the initial ``replaceState`` and every subsequent
+visit — so history state is never written: back/forward navigation and scroll
+restoration silently stop working, and the console fills with the error. The
+throw escapes as an unhandled rejection, because the client's
+``isHistoryThrottleError`` guard matches the string ``"history.pushState"``
+while the browser's message reads ``"Failed to execute 'pushState'"``.
+
+``SM_TRUSTED_PROXY`` fixes the scheme by trusting ``X-Forwarded-Proto``, and is
+still worth setting — it is what makes request logs record the real client IP.
+But an install should not need it merely to have working history, and trusting
+forwarded headers is a security decision that must stay opt-in: the default
+image is documented as runnable standalone, where a spoofed ``X-Forwarded-For``
+would poison the audit log. Emitting the relative url the protocol asks for
+removes the dependency entirely, whatever the deployment looks like.
+
+Patched at ``_get_page_data`` because it is the single choke point: upstream's
+SSR, JSON and full-page-load branches all build their payload from it. The
+replacement binds to the instance, so the library's class is untouched.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+from urllib.parse import urlsplit
+
+logger = logging.getLogger(__name__)
+
+
+def patch_relative_page_url(inertia: Any) -> Any:
+    """Patch a single Inertia instance in place so its page ``url`` is
+    root-relative, and return it.
+
+    Shared by :func:`relative_page_url_dependency` (the normal per-request
+    path) and by callers that already hold a bare instance — the error
+    handler's half-built-app fallback — so there is exactly one place that
+    knows how to apply the patch rather than a second copy of this hasattr
+    check.
+
+    An instance that doesn't expose the hook is handed back untouched: the
+    failure mode is the absolute url that already ships, and refusing to boot
+    because an upstream attribute moved would be a worse trade.
+    """
+    if hasattr(inertia, "_get_page_data"):
+        inertia._get_page_data = _page_data_for(inertia)
+    else:  # pragma: no cover - upstream layout changed
+        logger.warning(
+            "Inertia instance has no _get_page_data; the page url stays "
+            "absolute and history writes will fail behind a TLS proxy"
+        )
+    return inertia
+
+
+def relative_page_url_dependency(inertia_dep: Any) -> Any:
+    """Wrap an Inertia dependency so its page ``url`` is root-relative.
+
+    Keeps the ``(request, client)`` shape ``inertia_dependency_factory``
+    returns, and composes with the other wraps in either order — each patches a
+    different instance attribute, and the JSON wrap looks ``_get_page_data`` up
+    on the instance at call time.
+    """
+
+    def dependency(request: Any, client: Any = None) -> Any:
+        return patch_relative_page_url(inertia_dep(request, client))
+
+    return dependency
+
+
+def _page_data_for(inertia: Any) -> Any:
+    """Build the instance's replacement ``_get_page_data``."""
+    stock = inertia._get_page_data
+
+    async def _get_page_data() -> dict:
+        page_data = await stock()
+        url = page_data.get("url")
+        if isinstance(url, str):
+            page_data["url"] = to_relative_url(url)
+        return page_data
+
+    return _get_page_data
+
+
+def to_relative_url(url: str) -> str:
+    """Reduce an absolute url to the path-and-query the protocol wants.
+
+    A url that is already relative is returned unchanged, so this is safe to
+    apply twice and safe to apply to a payload upstream may one day fix.
+    Anything unparseable is passed through rather than mangled — a wrong url is
+    still better than a crash on the render path.
+    """
+    try:
+        parts = urlsplit(url)
+    except ValueError:  # pragma: no cover - urlsplit is near-total
+        return url
+    if not parts.scheme and not parts.netloc:
+        return url
+    relative = parts.path or "/"
+    if parts.query:
+        relative = f"{relative}?{parts.query}"
+    return relative
+
+
+__all__ = ["patch_relative_page_url", "relative_page_url_dependency", "to_relative_url"]