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

{simple_module_hosting-0.0.30 → simple_module_hosting-0.0.32}/.gitignore

@@ -63,3 +63,4 @@ Thumbs.db
 host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
+.verify/

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: simple_module_hosting
-Version: 0.0.30
+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.30
-Requires-Dist: simple-module-db==0.0.30
+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.30 → simple_module_hosting-0.0.32}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_hosting"
-version = "0.0.30"
+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.30",
-    "simple_module_db==0.0.30",
+    "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/_db_health.py

@@ -0,0 +1,56 @@
+"""The host's own readiness check: can we reach the database?
+
+Registered by ``create_app`` rather than by a module, because it is the one
+dependency no request can do without — unlike a mailer or an object store,
+which a page load never touches.
+
+It also gives ``/health/ready`` something to actually report. Modules
+contribute checks for third-party services, and those are ``probe=False``
+(polling an SMTP login every 10s earns a rate-limit), so without this the
+readiness endpoint would answer "healthy" from an empty check set — a green
+light that proves nothing.
+
+It is owned by the host, not a module, so it deliberately does not light up any
+tile on the dashboard's per-module health strip — those are keyed by
+``HealthCheck.module``.
+"""
+
+from __future__ import annotations
+
+from simple_module_core.health import HealthCheck, HealthCheckResult, HealthStatus
+from sqlalchemy import text
+
+CHECK_DATABASE = "host.database"
+
+_MODULE = "Host"
+
+
+def build_database_check(db_state):
+    """Return an async check issuing the cheapest possible round trip."""
+
+    async def check() -> HealthCheckResult:
+        try:
+            async with db_state.session_factory() as session:
+                await session.execute(text("SELECT 1"))
+        except Exception as exc:
+            return HealthCheckResult(status=HealthStatus.UNHEALTHY, detail=str(exc))
+        return HealthCheckResult(status=HealthStatus.HEALTHY, detail="Database reachable")
+
+    return check
+
+
+def register_database_check(health_registry, db_state) -> None:
+    """Add the database check to *health_registry*.
+
+    ``probe=True``: a ``SELECT 1`` against an already-pooled connection is
+    cheap enough to run on a probe timer, and it is exactly what a readiness
+    probe should be asking.
+    """
+    health_registry.add(
+        HealthCheck(
+            name=CHECK_DATABASE,
+            check=build_database_check(db_state),
+            module=_MODULE,
+            probe=True,
+        )
+    )

simple_module_hosting-0.0.32/simple_module_hosting/_error_handlers.py

@@ -0,0 +1,159 @@
+"""Framework-wide exception handlers that render Inertia error pages."""
+
+from __future__ import annotations
+
+import logging
+
+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
+
+logger = logging.getLogger(__name__)
+
+_INERTIA_ERROR_STATUSES = frozenset({403, 404, 500})
+
+
+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) -> Response:
+    config: InertiaConfig = request.app.state.sm.inertia_config
+    try:
+        inertia = Inertia(request, config)
+        # This builds its own Inertia instead of going 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,
+                "message": message,
+                "correlation_id": getattr(request.state, "correlation_id", "") or "",
+            },
+        )
+        response.status_code = status_code
+        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"}
+        )
+
+
+async def http_exception_handler(request: Request, exc: HTTPException) -> Response:
+    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)
+    # Preserve exception headers (WWW-Authenticate, Retry-After, ...) the way
+    # FastAPI's stock handler does.
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"detail": exc.detail},
+        headers=getattr(exc, "headers", None),
+    )
+
+
+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.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.30 → 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.30 → simple_module_hosting-0.0.32}/simple_module_hosting/_phase_helpers.py

@@ -21,6 +21,7 @@ from inertia import (
 )
 from simple_module_core.diagnostics import Diagnostic, DiagnosticLevel
 from simple_module_core.exceptions import NotFoundError
+from simple_module_db import CommitBeforeResponseMiddleware
 from starlette.exceptions import HTTPException
 from starlette.middleware.gzip import GZipMiddleware
 from starlette.middleware.sessions import SessionMiddleware
@@ -33,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 (
@@ -46,6 +48,7 @@ from simple_module_hosting.settings import Settings
 from simple_module_hosting.static_files import PrecompressedStaticFiles
 
 if TYPE_CHECKING:
+    from simple_module_core.csp import CspSourceRegistry
     from simple_module_core.menu import MenuRegistry
     from simple_module_core.permissions import PermissionRegistry
 
@@ -72,19 +75,46 @@ def register_exception_handlers(app: FastAPI, modules: list) -> None:
         mod.register_exception_handlers(app)
 
 
+def build_csp(settings: Settings, csp_registry: CspSourceRegistry) -> str:
+    """Choose the CSP for this boot and fold in module-declared sources.
+
+    Development gets the Vite-widened policy; production the strict default.
+    ``csp_registry`` carries origins modules declared via
+    ``register_csp_sources`` (e.g. an external font host) — merged here so
+    both variants honor them. An empty registry leaves the policy unchanged.
+    """
+    base = (
+        SecurityHeadersMiddleware.dev_csp(settings.vite_dev_url)
+        if settings.is_development
+        else SecurityHeadersMiddleware.DEFAULT_CSP
+    )
+    return csp_registry.extend_policy(base)
+
+
 def install_middleware(
     app: FastAPI,
     settings: Settings,
     modules: list,
     menu_registry: MenuRegistry,
     perm_registry: PermissionRegistry,
+    csp_registry: CspSourceRegistry,
 ) -> None:
     """Install the full middleware pipeline.
 
     Order matters: last added = first executed. Execution order:
     (ProxyHeaders, if trusted_proxy) → CorrelationId → RequestLogging
-    → Security → Session → [module] → (Tenant, if multi_tenant) → Locale → Inertia.
+    → Security → Session → [module] → (Tenant, if multi_tenant) → Locale
+    → 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,
@@ -102,16 +132,14 @@ def install_middleware(
         mod.register_middleware(app)
     app.add_middleware(SessionMiddleware, secret_key=settings.secret_key)
     # In dev, relax CSP so the browser can fetch @vite/client, main.tsx, and
-    # the HMR WebSocket from the Vite origin. HSTS is also suppressed because
-    # dev runs over plain HTTP on loopback.
+    # the HMR WebSocket from the Vite origin (build_csp picks the variant).
+    # HSTS is suppressed in dev because it runs over plain HTTP on loopback.
+    security_kwargs: dict[str, str | None] = {
+        "content_security_policy": build_csp(settings, csp_registry)
+    }
     if settings.is_development:
-        app.add_middleware(
-            SecurityHeadersMiddleware,
-            content_security_policy=SecurityHeadersMiddleware.dev_csp(settings.vite_dev_url),
-            strict_transport_security=None,
-        )
-    else:
-        app.add_middleware(SecurityHeadersMiddleware)
+        security_kwargs["strict_transport_security"] = None
+    app.add_middleware(SecurityHeadersMiddleware, **security_kwargs)
     # Compress response bodies. Added here so it sits inside CorrelationId and
     # RequestLogging (which set headers and read request state) but outside
     # everything that produces a body — including the /static mount, where it

simple_module_hosting-0.0.32/simple_module_hosting/_registrations.py

@@ -0,0 +1,69 @@
+"""Phase 5 of boot — every module's declarative registration hooks.
+
+Extracted from ``app_builder.py`` to keep that file readable; this is the one
+place that knows the full set of hooks a module may implement, and the order
+they run in. ``app_builder.create_app`` is the only intended caller.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+
+def run_module_registrations(
+    modules: list,
+    *,
+    app: FastAPI,
+    event_bus,
+    menu_registry,
+    perm_registry,
+    ff_registry,
+    health_registry,
+    public_route_registry,
+    design_pack_registry,
+    audit_link_registry,
+    csp_registry,
+) -> None:
+    """Invoke each module's registration hooks, in dependency order.
+
+    Health checks are attributed to the module that registers them, so the
+    dashboard can report health per module rather than one global number. The
+    owner is cleared afterwards: anything registered later — a module's
+    ``on_startup``, say — belongs to no module in this loop, and inheriting
+    the last one's name would be a lie.
+    """
+    for mod in modules:
+        mod.register_menu_items(menu_registry)
+        mod.register_permissions(perm_registry)
+        mod.register_feature_flags(ff_registry)
+        dispatch_event_handlers(mod, event_bus, app)
+        health_registry.set_owner(mod.meta.name)
+        mod.register_health_checks(health_registry)
+        mod.register_public_routes(public_route_registry)
+        # csp before design packs — the documented lifecycle order
+        # (docs/framework/lifecycle.md).
+        mod.register_csp_sources(csp_registry)
+        mod.register_design_packs(design_pack_registry)
+        mod.register_audit_links(audit_link_registry)
+
+    health_registry.set_owner("")
+
+
+def dispatch_event_handlers(mod, event_bus, app: FastAPI) -> None:
+    """Call ``mod.register_event_handlers`` with or without ``app``.
+
+    Back-compat shim for modules that still override the one-arg form
+    ``(self, bus)``; passing ``app=`` to those crashes.
+    """
+    sig = inspect.signature(mod.register_event_handlers)
+    accepts_app = "app" in sig.parameters or any(
+        p.kind is inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+    )
+    if accepts_app:
+        mod.register_event_handlers(event_bus, app=app)
+    else:
+        mod.register_event_handlers(event_bus)