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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_hosting
-Version: 0.0.33
+Version: 0.0.35
 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
@@ -22,13 +22,13 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: click>=8.1
-Requires-Dist: fastapi-inertia>=1.0
 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.33
-Requires-Dist: simple-module-db==0.0.33
+Requires-Dist: simple-module-core==0.0.35
+Requires-Dist: simple-module-db==0.0.35
+Requires-Dist: simple-module-inertia==0.0.35
 Requires-Dist: starlette>=0.44
 Requires-Dist: tomlkit>=0.13
 Requires-Dist: uvicorn[standard]>=0.34

{simple_module_hosting-0.0.33 → simple_module_hosting-0.0.35}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_hosting"
-version = "0.0.33"
+version = "0.0.35"
 description = "FastAPI + Inertia.js host runtime for simple_module — app_builder, middleware stack, CLI (sm / simple-module), scaffolding"
 readme = "README.md"
 license = "MIT"
@@ -23,15 +23,15 @@ classifiers = [
 dependencies = [
     "click>=8.1",
     "fastapi>=0.115",
-    "fastapi-inertia>=1.0",
     "httpx>=0.27",
     # SessionMiddleware (starlette.middleware.sessions) imports itsdangerous at
     # module import time; starlette treats it as an optional extra, so declare
     # it directly — out-of-tree hosts have nothing else pulling it in.
     "itsdangerous>=2.0",
     "jinja2>=3.1",
-    "simple_module_core==0.0.33",
-    "simple_module_db==0.0.33",
+    "simple_module_core==0.0.35",
+    "simple_module_db==0.0.35",
+    "simple_module_inertia==0.0.35",
     "starlette>=0.44",
     "tomlkit>=0.13",
     "uvicorn[standard]>=0.34",
@@ -59,3 +59,4 @@ packages = ["simple_module_hosting"]
 [tool.uv.sources]
 simple_module_core = { workspace = true }
 simple_module_db = { workspace = true }
+simple_module_inertia = { workspace = true }

simple_module_hosting-0.0.35/simple_module_hosting/_dev_boot.py

@@ -0,0 +1,83 @@
+"""Development-only boot work: the diagnostics run and the frontend artifacts.
+
+Extracted from ``app_builder`` so that file reads as the phase sequence and
+nothing else. Everything here is gated on ``settings.is_development`` at the one
+call site, and everything here reads or writes the *source tree* — a deployed
+wheel has no ``host/client_app`` to write a manifest into and no module sources
+for the AST checks to walk, which is why none of it belongs on a production boot
+path.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics import DiagnosticLevel, print_diagnostics, run_diagnostics
+
+from simple_module_hosting.i18n_manifest import emit_frontend_types_for_modules
+
+if TYPE_CHECKING:
+    from simple_module_core import ModuleBase
+    from simple_module_core.services import DiagnosticsState
+
+    from simple_module_hosting.settings import Settings
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["run_dev_boot"]
+
+
+def run_dev_boot(
+    settings: Settings,
+    modules: list[ModuleBase],
+    installed_modules: list[ModuleBase],
+    *,
+    i18n_extra,
+    diagnostics_state: DiagnosticsState,
+    project_root: Path,
+) -> None:
+    """Run the module diagnostics and emit the frontend's generated files.
+
+    ``diagnostics_state.runner`` is left behind on purpose, not just used: the
+    in-app Doctor screen re-invokes this exact call through ``rerun()``, and
+    re-deriving the arguments from a request would mean re-discovering modules.
+
+    An ERROR-level diagnostic ends the process. A developer whose module has a
+    duplicate name or a framework→plugin import gets one clear message here
+    instead of an inexplicable failure several phases later — and the same
+    checks run at production boot, where the app would refuse to start anyway.
+    """
+    diagnostics_state.runner = lambda: run_diagnostics(
+        modules,
+        i18n_supported_locales=settings.i18n_supported_locales,
+        i18n_default_locale=settings.i18n_default_locale,
+        i18n_extra_sources=i18n_extra,
+    )
+    diagnostics = diagnostics_state.rerun()
+    errors = [d for d in diagnostics if d.level == DiagnosticLevel.ERROR]
+    if diagnostics:
+        print_diagnostics(diagnostics)
+    if errors:
+        raise SystemExit(f"Module diagnostics: {len(errors)} error(s). Fix before continuing.")
+
+    _write_pages_manifest(modules, project_root)
+    emit_frontend_types_for_modules(settings, installed_modules, project_root)
+
+
+def _write_pages_manifest(modules: list[ModuleBase], project_root: Path) -> None:
+    """Tell Vite where pages shipped inside pip-installed wheels live.
+
+    Swallows its own failure: a missing or unwritable ``client_app`` must not
+    stop the API from booting, and the symptom — pages the frontend cannot find
+    — is loud enough on its own. See ``scaffolding.py``.
+    """
+    try:
+        from simple_module_hosting.manifest import write_module_pages_manifest
+
+        client_app = project_root / "host" / "client_app"
+        if client_app.is_dir():
+            write_module_pages_manifest(modules, client_app)
+    except Exception:
+        logger.exception("Failed to write module pages manifest — frontend may miss pages")

{simple_module_hosting-0.0.33 → simple_module_hosting-0.0.35}/simple_module_hosting/_error_handlers.py

@@ -9,13 +9,13 @@ from http import HTTPStatus
 from fastapi.encoders import jsonable_encoder
 from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
-from inertia import (
+from simple_module_core.exceptions import NotFoundError
+from simple_module_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
@@ -172,11 +172,22 @@ async def render_error_page(
         # 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
-        # renders raw translation keys (host.error.not_found_title) and loses
-        # auth/menus, so a signed-in user's 404 has no layout.
+        # Prefer the app's configured dependency over constructing Inertia
+        # directly, so the error page is built the same way as every other
+        # page. The raw construction is the fallback for a half-built app —
+        # the case this whole handler exists to survive. Both paths emit a
+        # root-relative page url: the adapter does that by construction now,
+        # so the fallback no longer needs a separate patch to avoid the
+        # cross-scheme `pushState` SecurityError behind a TLS proxy.
+        inertia_dep = getattr(request.app.state, "inertia_dependency", None)
+        if inertia_dep is not None:
+            inertia = inertia_dep(request, None)
+        else:
+            inertia = 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)

simple_module_hosting-0.0.35/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.33 → simple_module_hosting-0.0.35}/simple_module_hosting/_inertia_setup.py

@@ -1,18 +1,15 @@
-"""Configure fastapi-inertia with the Jinja2 template."""
+"""Configure simple_module_inertia with the Jinja2 template."""
 
 from __future__ import annotations
 
-import hashlib
-import json
 import logging
-import tempfile
 from pathlib import Path
 
 from fastapi import FastAPI
-from inertia import InertiaConfig, inertia_dependency_factory
+from simple_module_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._favicon import default_favicon_data_uri
 from simple_module_hosting.settings import Settings
 
 logger = logging.getLogger(__name__)
@@ -26,6 +23,12 @@ _ROOT_DIRECTORY = "."
 # branding's own default so the unbranded title is identical everywhere.
 _DEFAULT_APP_NAME = "SimpleModule"
 
+# Built assets are served from the "/static" mount under "dist/", so production
+# asset URLs are prefixed with "static/dist". The manifest is read where Vite
+# writes it; the adapter looks the entry up by Vite's own key.
+_ASSETS_PREFIX = "static/dist"
+_VITE_MANIFEST_RELPATH = Path("static") / "dist" / ".vite" / "manifest.json"
+
 
 def branding_head(request: Request) -> dict:
     """Branding metadata for the root template's ``<head>``.
@@ -40,72 +43,38 @@ 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,
     }
 
 
-# Built assets are served from the "/static" mount under "dist/", so production
-# asset URLs are prefixed with "static/dist".
-_ASSETS_PREFIX = "static/dist"
-_VITE_MANIFEST_RELPATH = Path("static") / "dist" / ".vite" / "manifest.json"
-
-
 def _prod_manifest_path(project_root: Path) -> str:
-    """Return a manifest path fastapi-inertia can read in production.
-
-    fastapi-inertia looks the entry up by ``f"{root_directory}/{entrypoint}"``
-    (here ``"./main.tsx"``), but Vite keys its manifest by the entry's path
-    relative to the Vite root (``"main.tsx"``) — so the raw Vite manifest would
-    ``KeyError``. Read it, re-key the ``isEntry`` chunk under the key
-    fastapi-inertia expects, and write the normalized copy beside the build
-    output (falling back to a temp file if that dir is read-only). Returns ``""``
-    when no built manifest exists, leaving production assets unconfigured rather
-    than crashing at import time.
-    """
+    """The Vite manifest to read in production, or ``""`` when none is built."""
     candidates = [
         project_root / "host" / _VITE_MANIFEST_RELPATH,
         project_root / _VITE_MANIFEST_RELPATH,
     ]
-    vite_manifest = next((p for p in candidates if p.is_file()), None)
-    if vite_manifest is None:
+    found = next((p for p in candidates if p.is_file()), None)
+    if found is None:
         logger.warning(
             "Production Vite manifest not found (looked in %s)", [str(c) for c in candidates]
         )
         return ""
-    try:
-        data = json.loads(vite_manifest.read_text())
-        expected_key = f"{_ROOT_DIRECTORY}/{_ENTRYPOINT_FILENAME}"
-        if expected_key not in data:
-            entry = next((v for v in data.values() if v.get("isEntry")), None)
-            if entry is None:
-                # No entry to re-key: degrade gracefully (same as no-manifest)
-                # rather than returning a path that KeyErrors at render time.
-                logger.warning("No isEntry chunk in Vite manifest %s", vite_manifest)
-                return ""
-            data = {**data, expected_key: entry}
-        out = vite_manifest.parent / "inertia-manifest.json"
-        try:
-            out.write_text(json.dumps(data))
-        except OSError:
-            # Build dir read-only (e.g. immutable container layer): fall back to
-            # a temp file keyed by the source manifest path so multiple apps on
-            # one host don't clobber each other's normalized manifests.
-            digest = hashlib.sha1(str(vite_manifest).encode()).hexdigest()[:12]
-            out = Path(tempfile.gettempdir()) / f"sm-inertia-manifest-{digest}.json"
-            out.write_text(json.dumps(data))
-        return str(out)
-    except Exception:
-        logger.exception("Failed to prepare production Inertia manifest from %s", vite_manifest)
-        return ""
+    return str(found)
 
 
 def setup_inertia(
@@ -114,7 +83,7 @@ def setup_inertia(
     modules: list,
     project_root: Path,
 ) -> InertiaConfig | None:
-    """Configure fastapi-inertia and attach the dependency factory to app.state.
+    """Configure the Inertia adapter and attach the dependency factory to app.state.
 
     Two host layouts are supported: ``host/templates`` (the framework's
     own host package) and ``templates`` at the project root (what
@@ -157,14 +126,9 @@ def setup_inertia(
     # Expose branding metadata to the root template (pre-hydration head tags).
     templates.env.globals["branding_head"] = branding_head
 
-    # fastapi-inertia only switches to the asset manifest when environment
-    # equals the literal string "production". Anything else (staging, qa,
-    # ...) would render a /main.tsx <script> tag served by the SPA fallback
-    # as text/html, breaking module loading. Normalize:
-    #   * `development`/`testing` → keep the dev-server path (Vite serves
-    #     /main.tsx directly).
-    #   * Anything else (staging, production, qa, ...) → use the production
-    #     manifest so built assets are referenced.
+    # The adapter only switches to the asset manifest when environment equals
+    # the literal "production"; normalise anything non-dev (staging, qa, ...)
+    # to that so built assets are referenced rather than a Vite dev url.
     from simple_module_core.environments import NON_PROD_ENVIRONMENTS
 
     use_dev_server = settings.environment in NON_PROD_ENVIRONMENTS
@@ -174,8 +138,6 @@ def setup_inertia(
         environment=inertia_environment,
         version=_INERTIA_VERSION,
         dev_url=settings.vite_dev_url if use_dev_server else "",
-        # Production reads built assets from the Vite manifest; dev serves them
-        # from the Vite dev server, so these only matter when not use_dev_server.
         manifest_json_path="" if use_dev_server else _prod_manifest_path(project_root),
         assets_prefix="" if use_dev_server else _ASSETS_PREFIX,
         templates=templates,
@@ -184,10 +146,5 @@ def setup_inertia(
         root_directory=_ROOT_DIRECTORY,
         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))
-    app.state.inertia_dependency = inertia_dep
+    app.state.inertia_dependency = inertia_dependency_factory(inertia_config)
     return inertia_config

{simple_module_hosting-0.0.33 → simple_module_hosting-0.0.35}/simple_module_hosting/_phase_helpers.py

@@ -14,13 +14,13 @@ from typing import TYPE_CHECKING
 from fastapi import FastAPI
 from fastapi.exceptions import RequestValidationError
 from fastapi.staticfiles import StaticFiles
-from inertia import (
-    InertiaVersionConflictException,
-    inertia_version_conflict_exception_handler,
-)
 from simple_module_core.diagnostics import Diagnostic, DiagnosticLevel
 from simple_module_core.exceptions import NotFoundError
 from simple_module_db import CommitBeforeResponseMiddleware
+from simple_module_inertia import (
+    InertiaVersionConflictException,
+    inertia_version_conflict_exception_handler,
+)
 from starlette.exceptions import HTTPException
 from starlette.middleware.gzip import GZipMiddleware
 from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
@@ -145,6 +145,10 @@ def install_middleware(
     )
     if settings.multi_tenant:
         app.add_middleware(TenantMiddleware, header=settings.tenant_header or None)
+    elif settings.default_tenant:
+        # Single-tenant host with tenant-scoped tables: every request is the
+        # one tenant (#359). Never used with multi_tenant — no shared fallback.
+        app.add_middleware(TenantMiddleware, fixed=settings.default_tenant)
     for mod in modules:
         mod.register_middleware(app)
     app.add_middleware(SessionMiddleware, secret_key=settings.secret_key)
@@ -167,8 +171,10 @@ def install_middleware(
     app.add_middleware(RequestLoggingMiddleware)
     app.add_middleware(CorrelationIdMiddleware)
     # Outermost: rewrite scheme/client from X-Forwarded-* before anything else
-    # reads them, so request logs see the real client IP and Inertia's absolute
-    # page url carries the proxy-terminated scheme (GH #223). Gated on an
+    # reads them, so request logs see the real client IP rather than the
+    # proxy's. Inertia no longer needs this: its page url is
+    # root-relative, so pushState can't see a cross-scheme url either way (it
+    # used to throw a SecurityError on every page — GH #223). Gated on an
     # explicit trust setting — never trust forwarded headers by default.
     if settings.trusted_proxy:
         app.add_middleware(ProxyHeadersMiddleware, trusted_hosts=settings.trusted_proxy)

{simple_module_hosting-0.0.33 → simple_module_hosting-0.0.35}/simple_module_hosting/_registrations.py

@@ -19,6 +19,7 @@ def run_module_registrations(
     *,
     app: FastAPI,
     event_bus,
+    invalidation_bus,
     menu_registry,
     perm_registry,
     ff_registry,
@@ -42,6 +43,7 @@ def run_module_registrations(
         mod.register_permissions(perm_registry)
         mod.register_feature_flags(ff_registry)
         dispatch_event_handlers(mod, event_bus, app)
+        mod.register_invalidations(invalidation_bus, app)
         health_registry.set_owner(mod.meta.name)
         mod.register_health_checks(health_registry)
         mod.register_public_routes(public_route_registry)

simple_module_hosting-0.0.35/simple_module_hosting/_tenant.py

@@ -0,0 +1,97 @@
+"""Tenant-context middleware: which tenant a request acts for."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from simple_module_db import current_tenant_id, is_valid_tenant_id
+from starlette.datastructures import Headers
+from starlette.requests import Request
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+_SCOPE_HTTP = "http"
+
+TENANT_HEADER = "X-Tenant-ID"
+
+
+TenantResolver = Callable[[Request], Awaitable[str | None]]
+"""Module-owned tenant resolution, registered as ``app.state.tenant_resolver``.
+
+Returns the tenant the request acts for, or ``None``. It owns *every* source —
+membership, session, subdomain, header — so it is also where each is
+validated. Without one the middleware falls back to the principal's
+``tenant_id`` claim."""
+
+
+class TenantMiddleware:
+    """Establish the request's tenant context.
+
+    Sets the ``current_tenant_id`` context var so that DB queries on
+    :class:`~simple_module_db.mixins.MultiTenantMixin` models are
+    automatically filtered, and new objects get ``tenant_id`` populated.
+
+    Also stores the resolved value on ``request.state.tenant_id``.
+
+    Resolution:
+
+    1. If a module registered ``app.state.tenant_resolver`` (the ``tenants``
+       module does), its answer is final — including ``None``.
+    2. Otherwise the authenticated user's ``tenant_id`` attribute (from the
+       auth token claims).
+    3. Otherwise, for **anonymous** requests only, the configured header —
+       useful for API clients and tests. Pass ``header=None`` (the default)
+       to disable it. An authenticated user is never allowed to pick a tenant
+       by header: a user with no tenant of their own would otherwise be able
+       to name anyone's.
+    """
+
+    def __init__(
+        self, app: ASGIApp, *, header: str | None = None, fixed: str | None = None
+    ) -> None:
+        self.app = app
+        self.header = header
+        # Single-tenant hosts: one tenant for every request, nothing resolved.
+        self.fixed = fixed
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != _SCOPE_HTTP:
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope)
+        tenant_id = await self._resolve(request, scope)
+        request.state.tenant_id = tenant_id
+
+        if tenant_id is not None:
+            token = current_tenant_id.set(tenant_id)
+            try:
+                await self.app(scope, receive, send)
+            finally:
+                current_tenant_id.reset(token)
+            return
+
+        await self.app(scope, receive, send)
+
+    async def _resolve(self, request: Request, scope: Scope) -> str | None:
+        if self.fixed is not None:
+            return self.fixed
+        app = scope.get("app")
+        resolver: TenantResolver | None = getattr(
+            getattr(app, "state", None), "tenant_resolver", None
+        )
+        if resolver is not None:
+            return await resolver(request)
+
+        user = getattr(request.state, "user", None)
+        if user is not None:
+            return getattr(user, "tenant_id", None)
+
+        if self.header:
+            value = Headers(scope=scope).get(self.header)
+            # Unvalidated, an over-long value is a 500 on the first stamped
+            # write (VARCHAR(50)) and any junk becomes a tenant name (#366).
+            return value if is_valid_tenant_id(value) else None
+        return None
+
+
+__all__ = ["TENANT_HEADER", "TenantMiddleware", "TenantResolver"]