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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_hosting
-Version: 0.0.31
+Version: 0.0.32
 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.31
-Requires-Dist: simple-module-db==0.0.31
+Requires-Dist: simple-module-core==0.0.32
+Requires-Dist: simple-module-db==0.0.32
 Requires-Dist: starlette>=0.44
 Requires-Dist: tomlkit>=0.13
 Requires-Dist: uvicorn[standard]>=0.34

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

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_hosting"
-version = "0.0.31"
+version = "0.0.32"
 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.31",
-    "simple_module_db==0.0.31",
+    "simple_module_core==0.0.32",
+    "simple_module_db==0.0.32",
     "starlette>=0.44",
     "tomlkit>=0.13",
     "uvicorn[standard]>=0.34",

simple_module_hosting-0.0.32/simple_module_hosting/_inertia_cache.py

@@ -0,0 +1,104 @@
+"""Keep the Inertia payload out of caches that answer page requests.
+
+Every Inertia route serves one URL as two representations, chosen on the
+request's ``X-Inertia`` header: an HTML document for a full page load, a JSON
+payload for a client-side visit. Nothing in either response says so, which
+leaves a cache free to store one and hand it back for the other. Visit a page
+through the SPA, then open the same URL directly, and the browser can serve the
+stored payload as the document — the visitor gets
+``{"component":"...","props":{...}}`` where the page should be.
+
+That only bites once a route marks itself cacheable, which a public-content
+module reasonably does. The framework is what makes it unsafe:
+:class:`~simple_module_hosting.middleware.InertiaLayoutDataMiddleware` merges
+the signed-in user's ``auth`` block, their permission list and the menus their
+roles resolve to into *every* Inertia payload. A route author choosing
+``Cache-Control: public`` for their page content has no way to know that, so
+the guarantee belongs here rather than in each module:
+
+* **An Inertia payload is never stored.** ``private, no-store``, and the ETag
+  is dropped so no cache can revalidate its way back to a copy it should not
+  have kept. The cost is per-visit caching on client-side navigation, which was
+  never safe to take — those bytes are specific to one user.
+* **Both representations declare ``Vary: X-Inertia``**, so a cache that honours
+  Vary keeps them in separate entries instead of inferring it from ``Accept``.
+
+``Vary`` is added to the document only when the response is HTML, so static
+assets and JSON APIs keep the validators and cache entries they had.
+
+A module that wants its public page content cached should give the *document*
+its own ``Cache-Control`` and an ETag that identifies the representation; this
+middleware leaves that path alone and only governs the payload.
+"""
+
+from __future__ import annotations
+
+from starlette.datastructures import MutableHeaders
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+_SCOPE_HTTP = "http"
+_HEADER_INERTIA = b"x-inertia"
+
+#: What an Inertia payload is allowed to say about its own cacheability.
+PAYLOAD_CACHE_CONTROL = "private, no-store"
+
+#: The request header that selects the representation, and therefore the one
+#: caches must key on.
+VARY_FIELD = "X-Inertia"
+
+
+def add_vary(headers: MutableHeaders, field: str = VARY_FIELD) -> None:
+    """Add a field to ``Vary``, keeping whatever is already listed."""
+    existing = headers.get("vary")
+    if not existing:
+        headers["vary"] = field
+        return
+    if any(part.strip().lower() == field.lower() for part in existing.split(",")):
+        return
+    headers["vary"] = f"{existing}, {field}"
+
+
+def is_inertia_request(scope: Scope) -> bool:
+    """Whether this request asked for the JSON representation.
+
+    Mirrors ``fastapi-inertia``'s own ``Inertia._is_inertia_request`` exactly —
+    presence of the header, any value — rather than requiring it to equal
+    ``"true"``. The library renders JSON for *any* ``X-Inertia`` value, so a
+    stricter check here would disagree with it: a request the renderer treats
+    as Inertia would sail through uncached, undoing the whole fix.
+    """
+    return any(key == _HEADER_INERTIA for key, _ in scope.get("headers", ()))
+
+
+def _is_html(headers: MutableHeaders) -> bool:
+    return headers.get("content-type", "").split(";", 1)[0].strip() == "text/html"
+
+
+class InertiaCacheMiddleware:
+    """Stop an Inertia payload being cached as though it were the page."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != _SCOPE_HTTP:
+            await self.app(scope, receive, send)
+            return
+
+        inertia = is_inertia_request(scope)
+
+        async def send_with_cache_rules(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                headers = MutableHeaders(scope=message)
+                if inertia:
+                    headers["cache-control"] = PAYLOAD_CACHE_CONTROL
+                    del headers["etag"]
+                    add_vary(headers)
+                elif _is_html(headers):
+                    add_vary(headers)
+            await send(message)
+
+        await self.app(scope, receive, send_with_cache_rules)
+
+
+__all__ = ["PAYLOAD_CACHE_CONTROL", "VARY_FIELD", "InertiaCacheMiddleware", "add_vary"]

simple_module_hosting-0.0.32/simple_module_hosting/_inertia_json.py

@@ -0,0 +1,86 @@
+"""Make Inertia's JSON branch encode props the way its HTML branch does.
+
+``fastapi-inertia`` renders the same props two ways and configures only one of
+them::
+
+    # full page load — honours InertiaConfig.json_encoder
+    json_string = json.dumps(page_data, cls=self._config.json_encoder)
+
+    # client-side visit — Starlette's JSONResponse, so plain json.dumps
+    return JSONResponse(content=await self._get_page_data(), ...)
+
+``InertiaJsonEncoder`` exists precisely to run the payload through FastAPI's
+``jsonable_encoder``, and the second branch never reaches it. The effect is a
+route that works on a reload and 500s on every client-side visit, for any prop
+the stdlib encoder cannot handle — ``Path``, ``Decimal``, ``UUID``, a dataclass,
+an enum.
+
+Settings → Modules is where this surfaced: it reflects each installed module's
+pydantic settings back to the admin, and a module whose settings carry a
+``Path`` field (``PagebuilderSettings.media_root``) puts a ``PosixPath`` in the
+payload::
+
+    TypeError: Object of type PosixPath is not JSON serializable
+
+Fixing it here rather than in each module is deliberate. A module putting a
+rich value in props is not doing anything wrong — the HTML branch has always
+accepted it — so the asymmetry is the defect, and closing it at the point of
+serialisation covers every module and every prop type at once.
+
+Applied by wrapping the dependency published on ``app.state.inertia_dependency``,
+which ``inertia_deps.get_inertia`` calls once per request. The replacement binds
+to the instance, so the library's class is untouched and any other construction
+path keeps the stock behaviour.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi.encoders import jsonable_encoder
+from starlette.responses import JSONResponse
+
+logger = logging.getLogger(__name__)
+
+#: The headers upstream's ``_render_json`` sets, reproduced so the wrap is a
+#: pure encoder change. ``InertiaCacheMiddleware`` owns the caching rules and
+#: extends ``Vary`` on the way out.
+_JSON_HEADERS = {"X-Inertia": "true", "Vary": "Accept"}
+
+
+def json_safe_inertia_dependency(inertia_dep: Any) -> Any:
+    """Wrap an Inertia dependency so its JSON branch uses ``jsonable_encoder``.
+
+    The wrapped callable keeps the ``(request, client)`` shape
+    ``inertia_dependency_factory`` returns. An instance that doesn't expose the
+    private hook this relies on is handed back untouched: the failure mode is
+    the 500 that already happens, and refusing to boot because an upstream
+    attribute moved would be a worse trade.
+    """
+
+    def dependency(request: Any, client: Any = None) -> Any:
+        inertia = inertia_dep(request, client)
+        if hasattr(inertia, "_get_page_data"):
+            inertia._render_json = _render_json_for(inertia)
+        else:  # pragma: no cover - upstream layout changed
+            logger.warning(
+                "Inertia instance has no _get_page_data; JSON responses keep the "
+                "stock encoder and non-JSON-native props will fail to serialise"
+            )
+        return inertia
+
+    return dependency
+
+
+def _render_json_for(inertia: Any) -> Any:
+    """Build the instance's replacement ``_render_json``."""
+
+    async def _render_json() -> JSONResponse:
+        page_data = await inertia._get_page_data()
+        return JSONResponse(content=jsonable_encoder(page_data), headers=_JSON_HEADERS)
+
+    return _render_json
+
+
+__all__ = ["json_safe_inertia_dependency"]

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

@@ -12,6 +12,7 @@ from fastapi import FastAPI
 from inertia import InertiaConfig, inertia_dependency_factory
 from starlette.requests import Request
 
+from simple_module_hosting._inertia_json import json_safe_inertia_dependency
 from simple_module_hosting.settings import Settings
 
 logger = logging.getLogger(__name__)
@@ -184,6 +185,9 @@ def setup_inertia(
         use_flash_errors=True,
     )
 
-    inertia_dep = inertia_dependency_factory(inertia_config)
+    # 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))
     app.state.inertia_dependency = inertia_dep
     return inertia_config

{simple_module_hosting-0.0.31 → simple_module_hosting-0.0.32}/simple_module_hosting/_phase_helpers.py

@@ -34,6 +34,7 @@ from simple_module_hosting._error_handlers import (
     unhandled_exception_handler,
 )
 from simple_module_hosting._host_services import _HostServices
+from simple_module_hosting._inertia_cache import InertiaCacheMiddleware
 from simple_module_hosting.host_settings import HostSettings
 from simple_module_hosting.i18n_middleware import LocaleMiddleware
 from simple_module_hosting.middleware import (
@@ -103,12 +104,17 @@ def install_middleware(
     Order matters: last added = first executed. Execution order:
     (ProxyHeaders, if trusted_proxy) → CorrelationId → RequestLogging
     → Security → Session → [module] → (Tenant, if multi_tenant) → Locale
-    → Inertia → CommitBeforeResponse.
+    → Inertia → InertiaCache → CommitBeforeResponse.
     """
     # Added first, so it is innermost and its send-wrapper is the first to see
     # the response: the request's DB work commits before any byte reaches the
     # client, instead of in get_db's post-response exit code (GH #257).
     app.add_middleware(CommitBeforeResponseMiddleware)
+    # Paired with InertiaLayoutDataMiddleware below, which is what puts this
+    # user's auth, permissions and menus into every Inertia payload: this one
+    # makes sure the payload that results is never stored where a page request
+    # can be answered with it.
+    app.add_middleware(InertiaCacheMiddleware)
     app.add_middleware(
         InertiaLayoutDataMiddleware,
         menu_registry=menu_registry,

simple_module_hosting-0.0.32/tests/test_inertia_cache.py

@@ -0,0 +1,187 @@
+"""An Inertia payload must never be cacheable as the page it belongs to.
+
+The same URL answers twice — HTML for a full page load, JSON for a client-side
+visit — and the only thing separating them is the ``X-Inertia`` request header.
+Left unsaid, a cache stores one and serves it for the other, so opening a page
+directly after visiting it through the SPA renders the raw payload. The payload
+also carries this user's ``auth`` block, permissions and menus, so a shared
+cache storing it is a disclosure bug as well as a broken page.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from simple_module_hosting._inertia_cache import (
+    PAYLOAD_CACHE_CONTROL,
+    InertiaCacheMiddleware,
+    is_inertia_request,
+)
+from starlette.applications import Starlette
+from starlette.responses import HTMLResponse, JSONResponse, Response
+from starlette.routing import Route
+
+_OK = 200
+_INERTIA = {"X-Inertia": "true"}
+#: What a public-content module might reasonably put on its own page.
+_PUBLIC_CACHE = "public, max-age=60, stale-while-revalidate=600"
+_SHARED_ETAG = 'W/"deadbeef"'
+
+
+def _vary_fields(response: httpx.Response) -> set[str]:
+    return {part.strip().lower() for part in response.headers.get("vary", "").split(",")}
+
+
+def _build_app() -> Starlette:
+    """A route that markets itself as publicly cacheable, both ways.
+
+    Mirrors what the page-builder's public viewer does: one ETag and one
+    ``Cache-Control`` computed from the page row, stamped on whichever
+    representation the request asked for.
+    """
+
+    async def page(request):
+        if is_inertia_request(request.scope):
+            response: Response = JSONResponse(
+                {"component": "PublicPage", "props": {"auth": {"user": "editor"}}},
+                headers={"X-Inertia": "true", "Vary": "Accept"},
+            )
+        else:
+            response = HTMLResponse("<!DOCTYPE html><title>Page</title>")
+        response.headers["Cache-Control"] = _PUBLIC_CACHE
+        response.headers["ETag"] = _SHARED_ETAG
+        return response
+
+    async def asset(request):
+        return Response(b"body{}", media_type="text/css", headers={"ETag": _SHARED_ETAG})
+
+    app = Starlette(routes=[Route("/p/home", page), Route("/static/app.css", asset)])
+    app.add_middleware(InertiaCacheMiddleware)
+    return app
+
+
+@pytest.fixture
+def cache_client() -> httpx.AsyncClient:
+    return httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=_build_app()), base_url="http://test"
+    )
+
+
+class TestInertiaPayload:
+    async def test_payload_is_not_stored_even_when_the_route_says_public(
+        self, cache_client: httpx.AsyncClient
+    ) -> None:
+        """The route asked for `public`; the payload is per-user, so it loses."""
+        async with cache_client as client:
+            resp = await client.get("/p/home", headers=_INERTIA)
+
+        assert resp.status_code == _OK
+        assert resp.headers["cache-control"] == PAYLOAD_CACHE_CONTROL
+
+    async def test_payload_carries_no_validator(self, cache_client: httpx.AsyncClient) -> None:
+        """A shared ETag lets a cache revalidate its way back to the payload.
+
+        The route stamps the same ETag on both representations, so a client
+        holding the JSON could revalidate a *document* request into a 304 and
+        keep rendering it. Nothing to revalidate means nothing to restore.
+        """
+        async with cache_client as client:
+            resp = await client.get("/p/home", headers=_INERTIA)
+
+        assert "etag" not in resp.headers
+
+    async def test_payload_varies_on_the_header_that_selected_it(
+        self, cache_client: httpx.AsyncClient
+    ) -> None:
+        async with cache_client as client:
+            resp = await client.get("/p/home", headers=_INERTIA)
+
+        assert "x-inertia" in _vary_fields(resp)
+        # Whatever the route already listed stays listed.
+        assert "accept" in _vary_fields(resp)
+
+
+class TestMatchesUpstreamDetection:
+    """``is_inertia_request`` must agree with ``fastapi-inertia``'s own check.
+
+    Upstream's ``Inertia._is_inertia_request`` is ``"X-Inertia" in
+    self._request.headers`` — presence only, any value. A stricter check here
+    (e.g. requiring the value to equal ``"true"``) would disagree with it: a
+    request the renderer treats as Inertia and answers with JSON would sail
+    through this middleware uncached, reopening the exact leak the fix closes.
+    """
+
+    def test_any_header_value_counts_as_inertia(self) -> None:
+        scope = {"type": "http", "headers": [(b"x-inertia", b"false")]}
+
+        assert is_inertia_request(scope) is True
+
+    async def test_a_non_true_value_still_gets_the_safety_headers(self) -> None:
+        """A route that mirrors upstream's own (presence-only) detection.
+
+        Unlike ``cache_client``'s app, this handler does not call
+        ``is_inertia_request`` itself — it reproduces upstream's check
+        directly, so the two are genuinely independent here.
+        """
+
+        async def page(request):
+            if "x-inertia" in request.headers:
+                response = JSONResponse({"component": "Home", "props": {}})
+            else:
+                response = HTMLResponse("<!DOCTYPE html><title>Page</title>")
+            response.headers["Cache-Control"] = _PUBLIC_CACHE
+            response.headers["ETag"] = _SHARED_ETAG
+            return response
+
+        app = Starlette(routes=[Route("/p/home", page)])
+        app.add_middleware(InertiaCacheMiddleware)
+        transport = httpx.ASGITransport(app=app)
+
+        async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+            resp = await client.get("/p/home", headers={"X-Inertia": "false"})
+
+        assert resp.headers["content-type"].startswith("application/json")
+        assert resp.headers["cache-control"] == PAYLOAD_CACHE_CONTROL
+        assert "etag" not in resp.headers
+
+
+class TestDocumentResponse:
+    async def test_document_varies_on_x_inertia(self, cache_client: httpx.AsyncClient) -> None:
+        """Otherwise a cached document can be served to a client-side visit."""
+        async with cache_client as client:
+            resp = await client.get("/p/home")
+
+        assert "x-inertia" in _vary_fields(resp)
+
+    async def test_document_keeps_the_caching_the_route_chose(
+        self, cache_client: httpx.AsyncClient
+    ) -> None:
+        """Public page content stays cacheable — that half was never the bug."""
+        async with cache_client as client:
+            resp = await client.get("/p/home")
+
+        assert resp.headers["cache-control"] == _PUBLIC_CACHE
+        assert resp.headers["etag"] == _SHARED_ETAG
+
+
+class TestUnrelatedResponses:
+    async def test_static_assets_are_untouched(self, cache_client: httpx.AsyncClient) -> None:
+        """Adding Vary or dropping ETags here would cost every asset its 304."""
+        async with cache_client as client:
+            resp = await client.get("/static/app.css")
+
+        assert resp.headers["etag"] == _SHARED_ETAG
+        assert "x-inertia" not in _vary_fields(resp)
+
+
+class TestAgainstTheRealApp:
+    async def test_a_rendered_view_never_returns_a_storable_payload(
+        self, authenticated_client: httpx.AsyncClient
+    ) -> None:
+        """End to end, through the whole middleware pipeline."""
+        resp = await authenticated_client.get("/dashboard/", headers=_INERTIA)
+
+        assert resp.status_code == _OK
+        assert resp.headers["content-type"].startswith("application/json")
+        assert resp.headers["cache-control"] == PAYLOAD_CACHE_CONTROL
+        assert "x-inertia" in _vary_fields(resp)

simple_module_hosting-0.0.32/tests/test_inertia_json_encoder.py

@@ -0,0 +1,83 @@
+"""Both Inertia render paths must encode props the same way.
+
+Upstream configures ``InertiaConfig.json_encoder`` — which exists to run props
+through FastAPI's ``jsonable_encoder`` — and then only applies it on the full
+page load. A client-side visit builds a Starlette ``JSONResponse``, reaching
+plain ``json.dumps``. Any prop the stdlib cannot encode therefore renders on a
+reload and 500s when reached by clicking a link, which is a miserable bug to
+read from a stack trace: the page "works", right up until it is navigated to.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from simple_module_hosting._inertia_json import json_safe_inertia_dependency
+from starlette.responses import JSONResponse
+
+_OK = 200
+
+
+class _FakeInertia:
+    """Stands in for the library's Inertia, with the two hooks the wrap uses."""
+
+    def __init__(self, page_data: dict) -> None:
+        self._page_data = page_data
+        self.rendered_by_stock_encoder = False
+
+    async def _get_page_data(self) -> dict:
+        return self._page_data
+
+    async def _render_json(self) -> JSONResponse:
+        # What upstream does: no encoder, so a rich value raises here.
+        self.rendered_by_stock_encoder = True
+        return JSONResponse(content=self._page_data)
+
+
+def _dependency_for(page_data: dict):
+    inertia = _FakeInertia(page_data)
+    dependency = json_safe_inertia_dependency(lambda request, client=None: inertia)
+    return dependency(object(), None)
+
+
+class TestJsonSafeRendering:
+    async def test_a_path_prop_would_break_the_stock_encoder(self) -> None:
+        """Establishes the bug this wrap exists for, so the fix can't drift."""
+        with pytest.raises(TypeError, match="PosixPath"):
+            json.dumps({"props": {"media_root": Path("var/media")}})
+
+    async def test_a_path_prop_renders(self) -> None:
+        inertia = _dependency_for({"props": {"media_root": Path("var/media")}})
+
+        response = await inertia._render_json()
+
+        assert response.status_code == _OK
+        assert json.loads(bytes(response.body))["props"]["media_root"] == "var/media"
+
+    async def test_the_wrap_replaces_the_stock_path(self) -> None:
+        """Not merely catching the error afterwards — the encoder is swapped."""
+        inertia = _dependency_for({"props": {}})
+
+        await inertia._render_json()
+
+        assert inertia.rendered_by_stock_encoder is False
+
+    async def test_inertia_headers_are_preserved(self) -> None:
+        inertia = _dependency_for({"props": {}})
+
+        response = await inertia._render_json()
+
+        assert response.headers["x-inertia"] == "true"
+
+    async def test_an_unfamiliar_instance_is_left_alone(self) -> None:
+        """An upstream rename must not take the boot down with it."""
+
+        class _Unfamiliar:
+            pass
+
+        original = _Unfamiliar()
+        wrapped = json_safe_inertia_dependency(lambda request, client=None: original)
+
+        assert wrapped(object(), None) is original

{simple_module_hosting-0.0.31 → simple_module_hosting-0.0.32}/tests/test_middleware_order.py

@@ -4,7 +4,13 @@ CLAUDE.md spells out the pipeline:
 
     CorrelationId → RequestLogging → GZip → Security → Session → <module>
                   → Tenant (opt-in) → Locale → InertiaLayoutData
-                  → CommitBeforeResponse → app
+                  → InertiaCache → CommitBeforeResponse → app
+
+InertiaCache sits directly inside InertiaLayoutData, the middleware that puts
+this user's auth block, permissions and menus into every Inertia payload. Being
+inside it means its send-wrapper sees the response before anything else can
+read the headers, and pairing the two keeps "what makes the payload per-user"
+and "what stops the payload being cached" from drifting apart.
 
 Tenant/Locale must see ``request.state.user`` set by AuthMiddleware so
 DB queries get filtered correctly; CorrelationId must wrap everything so
@@ -45,6 +51,7 @@ _EXPECTED_MULTI_TENANT = (
     "TenantMiddleware",
     "LocaleMiddleware",
     "InertiaLayoutDataMiddleware",
+    "InertiaCacheMiddleware",
     "CommitBeforeResponseMiddleware",
 )
 
@@ -58,6 +65,7 @@ _EXPECTED_SINGLE_TENANT = (
     "AuthMiddleware",
     "LocaleMiddleware",
     "InertiaLayoutDataMiddleware",
+    "InertiaCacheMiddleware",
     "CommitBeforeResponseMiddleware",
 )