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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_hosting
-Version: 0.0.31
+Version: 0.0.33
 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.33
+Requires-Dist: simple-module-db==0.0.33
 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.33}/pyproject.toml

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

{simple_module_hosting-0.0.31 → simple_module_hosting-0.0.33}/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.31 → simple_module_hosting-0.0.33}/simple_module_hosting/_error_handlers.py

@@ -3,6 +3,8 @@
 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
@@ -19,10 +21,76 @@ from starlette.requests import Request
 from starlette.responses import Response
 
 from simple_module_hosting._inertia_shared import _INERTIA_HEADER
+from simple_module_hosting.permissions import PERMISSION_DENIED_PREFIX
 
 logger = logging.getLogger(__name__)
 
-_INERTIA_ERROR_STATUSES = frozenset({403, 404, 500})
+_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:
@@ -85,9 +153,25 @@ def _wants_json(request: Request) -> bool:
     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
+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
         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
@@ -104,11 +188,23 @@ async def render_error_page(request: Request, status_code: int, message: str) ->
             "Error",
             {
                 "status": status_code,
-                "message": message,
+                # 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)
@@ -116,20 +212,36 @@ async def render_error_page(request: Request, status_code: int, message: str) ->
         # 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"}
+            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)
-    # Preserve exception headers (WWW-Authenticate, Retry-After, ...) the way
-    # FastAPI's stock handler does.
+        return await render_error_page(request, exc.status_code, detail, headers)
     return JSONResponse(
         status_code=exc.status_code,
         content={"detail": exc.detail},
-        headers=getattr(exc, "headers", None),
+        headers=headers,
     )
 
 

simple_module_hosting-0.0.33/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.33/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.33}/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.33}/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.33/simple_module_hosting/_lifespan.py

@@ -0,0 +1,130 @@
+"""The app's startup and shutdown sequence.
+
+Split out of ``app_builder`` so that file stays focused on *wiring* — which
+modules load, what middleware is installed, where routes mount — while this
+one owns *when things happen* at run time.
+
+Ordering here is load-bearing. Settings hydrate from the database before any
+module's ``on_startup`` runs, so startup code reads DB-backed values rather
+than pydantic defaults. Shutdown runs in reverse module order, mirroring
+dependency direction, and disposes the engine last so a module's shutdown hook
+can still reach the database.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable, Sequence
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from simple_module_hosting.migrations import migration_status
+from simple_module_hosting.setup_gate import STEP_MIGRATIONS
+
+
+async def hydrate_settings_from_db(app: FastAPI) -> None:
+    """Merge DB-stored overrides into every registered settings object.
+
+    Resolved through ``importlib`` rather than a static import because the
+    SM009 coupling check is AST-based and forbids ``framework/*`` from naming
+    a plugin package. No-ops when the settings module isn't installed.
+
+    Note this is the *second* settings read of a boot. The first happens in
+    ``_preapp_config`` before ``create_app`` builds anything, because the
+    module list, i18n registry and middleware stack are all constructed from
+    settings and cannot be rebuilt from here.
+    """
+    if not hasattr(app.state, "settings"):
+        return
+
+    import importlib
+
+    from simple_module_hosting._hydrate_step import hydrate_all
+
+    service_cls = importlib.import_module("settings.service").SettingService
+    store_cls = importlib.import_module("settings.store").SettingsStore
+
+    async with app.state.sm.db.session_factory() as session:
+        await hydrate_all(app, store_cls(service_cls(session)))
+
+
+async def _is_first_run(app: FastAPI) -> bool:
+    """Whether this install has never been set up at all.
+
+    The distinction the boot check turns on. Two very different situations both
+    leave ``host.migrations`` outstanding:
+
+    - A **fresh deployment**: nothing is configured, so the administrator step
+      is pending too. Serving the wizard is exactly right — running the
+      migrations is one of the things it exists to do.
+    - A **configured install whose schema drifted**: someone deployed code
+      ahead of the migration job. It has administrators; only the schema is
+      behind.
+
+    Treating the second as "setup mode" is wrong twice over. It serves traffic
+    against a schema the code does not match — the failure ``SM010`` exists to
+    prevent — and it re-opens ``/setup``, whose migration endpoint is
+    unauthenticated, letting an anonymous request trigger an Alembic run on a
+    live system.
+
+    So: first run means *something other than the schema* is also outstanding.
+    ``False`` when no registry exists, since an app built outside
+    ``create_app`` has no steps to reason about and the old raising behaviour
+    is the safer default there.
+
+    Deliberately does not delegate to ``registry.incomplete()``: that method
+    treats a step whose predicate raises as *complete*, which is right for
+    ``SetupMiddleware``'s steady-state gate (a transient DB error must not
+    lock a working install out) but wrong here. On a genuinely fresh
+    database the non-migration steps' own tables don't exist yet — the
+    administrator check is a query against a table migrations create — so it
+    raises too, and swallowing that would make every step but the schema
+    look satisfied, exactly the "is setup complete" trap this function
+    exists to avoid. Here, a required step raising while the schema is
+    behind counts as pending: it is itself evidence the install is new.
+    """
+    registry = getattr(app.state.sm, "setup_registry", None)
+    if not registry:
+        return False
+    for step in registry.required_steps:
+        if step.id == STEP_MIGRATIONS:
+            continue
+        try:
+            done = await step.is_complete(app)
+        except Exception:
+            return True
+        if not done:
+            return True
+    return False
+
+
+def build_lifespan(modules: Sequence) -> Callable:
+    """Return the ``lifespan`` context manager for an app over *modules*."""
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+        # Report first, decide second. On a genuinely fresh install a
+        # behind-head database must still boot far enough to serve the wizard —
+        # running the migrations is one of the things that wizard does, and
+        # check_migrations' RuntimeError would make it unreachable. Anywhere
+        # else the original behaviour stands: a schema the code does not match
+        # fails the boot. See _is_first_run for why those two cases cannot be
+        # told apart by "is setup complete".
+        app.state.migration = await migration_status(app.state.sm.db.engine)
+        if not app.state.migration["is_current"] and not await _is_first_run(app):
+            raise RuntimeError(
+                f"Database is {app.state.migration['pending_count']} revision(s) behind "
+                f"(at {app.state.migration['current_revision']!r}, head is "
+                f"{app.state.migration['head_revision']!r}). Run: make migrate"
+            )
+
+        await hydrate_settings_from_db(app)
+
+        for mod in modules:
+            await mod.on_startup(app)
+        yield
+        for mod in reversed(modules):
+            await mod.on_shutdown(app)
+        await app.state.sm.db.engine.dispose()
+
+    return lifespan