simple-module-hosting 0.0.1__py3-none-any.whl

simple_module_hosting/__init__.py

@@ -0,0 +1,7 @@
+"""SimpleModule Hosting - App builder, module loader, middleware pipeline."""
+
+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
+
+__all__ = ["Settings", "correlation_id", "create_app", "setup_logging"]

simple_module_hosting/_error_handlers.py

@@ -0,0 +1,54 @@
+"""Framework-wide exception handlers that render Inertia error pages."""
+
+from __future__ import annotations
+
+import logging
+
+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
+
+logger = logging.getLogger(__name__)
+
+_INERTIA_ERROR_STATUSES = frozenset({403, 404, 500})
+
+
+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)
+        response = await inertia.render("Error", {"status": status_code, "message": message})
+        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:
+        detail = str(exc.detail) if exc.detail else ""
+        return await render_error_page(request, exc.status_code, detail)
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+
+async def not_found_error_handler(request: Request, exc: NotFoundError) -> Response:
+    return await render_error_page(request, 404, str(exc))
+
+
+async def unhandled_exception_handler(request: Request, exc: Exception) -> Response:
+    logger.exception("Unhandled exception: %s", exc)
+    return await render_error_page(request, 500, "")

simple_module_hosting/_hydrate_step.py

@@ -0,0 +1,39 @@
+"""Hydrate every registered module's settings from the DB at lifespan start.
+
+Runs before any module ``on_startup`` hook so startup code sees DB-backed
+values. ``importlib`` is used to resolve plugin names lazily so the
+framework→plugin AST check (SM009) stays clean.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+from typing import Any
+
+from fastapi import FastAPI
+
+logger = logging.getLogger(__name__)
+
+_MODULE_PACKAGE = "settings"
+
+
+async def hydrate_all(app: FastAPI, store: Any) -> None:
+    """Resolve every registered module's settings from the DB."""
+    settings_services = getattr(app.state, _MODULE_PACKAGE, None)
+    if settings_services is None:
+        return
+
+    hydrate_settings = importlib.import_module("settings.hydrate").hydrate_settings
+
+    for package, cls in settings_services.module_registry.items():
+        try:
+            hydrated = await hydrate_settings(cls, store, package)
+        except Exception:
+            logger.exception("Hydrating %s failed; falling back to defaults", package)
+            continue
+        services = getattr(app.state, package, None)
+        if services is None:
+            logger.warning("app.state.%s missing during hydrate — skipping", package)
+            continue
+        services.settings = hydrated

simple_module_hosting/_inertia_setup.py

@@ -0,0 +1,73 @@
+"""Configure fastapi-inertia with the Jinja2 template."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from fastapi import FastAPI
+from inertia import InertiaConfig, inertia_dependency_factory
+
+from simple_module_hosting.settings import Settings
+
+logger = logging.getLogger(__name__)
+
+_INERTIA_VERSION = "1.0"
+_ROOT_TEMPLATE_FILENAME = "index.html"
+_ENTRYPOINT_FILENAME = "main.tsx"
+_ROOT_DIRECTORY = "."
+
+
+def setup_inertia(
+    app: FastAPI,
+    settings: Settings,
+    modules: list,
+    project_root: Path,
+) -> InertiaConfig | None:
+    """Configure fastapi-inertia and attach the dependency factory to app.state.
+
+    The host's own ``host/templates`` directory is first in the search path so
+    it can override module-contributed templates. Each installed module
+    contributes additional directories via ``ModuleBase.template_dirs()``.
+    """
+    from fastapi.templating import Jinja2Templates
+
+    host_templates = project_root / "host" / "templates"
+    directories: list[Path] = []
+
+    if host_templates.is_dir():
+        directories.append(host_templates)
+    else:
+        logger.warning("Host templates directory not found at %s", host_templates)
+
+    for mod in modules:
+        for path in mod.template_dirs():
+            if Path(path).is_dir():
+                directories.append(Path(path))
+            else:
+                logger.warning(
+                    "Module '%s' declared template dir %s but it does not exist",
+                    mod.meta.name,
+                    path,
+                )
+
+    if not directories:
+        logger.warning("No usable template directories — Inertia will fail to render views")
+        return None
+
+    templates = Jinja2Templates(directory=directories)
+
+    inertia_config = InertiaConfig(
+        environment=settings.environment,
+        version=_INERTIA_VERSION,
+        dev_url=settings.vite_dev_url if settings.is_development else "",
+        templates=templates,
+        root_template_filename=_ROOT_TEMPLATE_FILENAME,
+        entrypoint_filename=_ENTRYPOINT_FILENAME,
+        root_directory=_ROOT_DIRECTORY,
+        use_flash_errors=True,
+    )
+
+    inertia_dep = inertia_dependency_factory(inertia_config)
+    app.state.inertia_dependency = inertia_dep
+    return inertia_config

simple_module_hosting/_inertia_shared.py

@@ -0,0 +1,61 @@
+"""Helpers for building Inertia shared-props payloads."""
+
+from __future__ import annotations
+
+import logging
+
+from starlette.datastructures import Headers
+from starlette.requests import Request
+from starlette.types import Scope
+
+logger = logging.getLogger(__name__)
+
+_I18N_SESSION_LOCALE_KEY = "__i18n_locale"
+_INERTIA_HEADER = "x-inertia"
+_INERTIA_HEADER_TRUE = "true"
+
+
+def build_i18n_block(scope: Scope, request: Request) -> dict:
+    """Assemble the ``i18n`` shared-props block for the current request.
+
+    Rules:
+
+    * No registry / no locale → serve an empty English block and log once.
+    * Inertia XHR partials (``X-Inertia: true``) reuse the client-side
+      cached messages; send ``messages: None`` unless the locale differs
+      from what was last served on this session.
+    * Full page loads and locale transitions ship the complete dict.
+    """
+    # Test fixtures sometimes build a bare FastAPI with a partial app.state.sm
+    # stub (e.g. permissions-only, no i18n); guard both lookups to keep them usable.
+    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:
+        logger.warning(
+            "InertiaLayoutDataMiddleware: i18n not fully wired "
+            "(registry_present=%s, locale_present=%s); serving empty messages",
+            registry is not None,
+            locale is not None,
+        )
+        return {"locale": "en", "supportedLocales": ["en"], "messages": {}}
+
+    is_inertia = Headers(scope=scope).get(_INERTIA_HEADER) == _INERTIA_HEADER_TRUE
+    session_dict = scope.get("session")
+    # When the session is absent (pre-session-middleware routes, WebSocket
+    # upgrades), treat locale as "unchanged" so Inertia XHR requests still
+    # skip the messages payload. Non-Inertia requests will always ship them
+    # regardless of the session state.
+    if session_dict is not None:
+        last_locale = session_dict.get(_I18N_SESSION_LOCALE_KEY)
+        locale_changed = last_locale != locale
+        if locale_changed:
+            session_dict[_I18N_SESSION_LOCALE_KEY] = locale
+    else:
+        locale_changed = False
+    send_messages = (not is_inertia) or locale_changed
+    return {
+        "locale": locale,
+        "supportedLocales": registry.available_locales(),
+        "messages": registry.messages_snapshot(locale) if send_messages else None,
+    }

simple_module_hosting/_observability.py

@@ -0,0 +1,108 @@
+"""ASGI middlewares for correlation IDs and structured request logging."""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+
+from starlette.datastructures import Headers, MutableHeaders
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from simple_module_hosting.logging import correlation_id
+
+_LOGGER_NAME = "simple_module.request"
+_request_logger = logging.getLogger(_LOGGER_NAME)
+
+_SCOPE_HTTP = "http"
+_MSG_RESPONSE_START = "http.response.start"
+_EVENT_REQUEST_STARTED = "request.started"
+_EVENT_REQUEST_COMPLETED = "request.completed"
+
+# Paths that produce noisy, low-value log entries
+_QUIET_PREFIXES = ("/health", "/static/")
+
+
+class CorrelationIdMiddleware:
+    """Generate or propagate a correlation ID for every request.
+
+    Reads the incoming ``X-Correlation-ID`` header (or generates a UUID4) and
+    stores it in a :class:`~contextvars.ContextVar` so that every log record
+    emitted during the request automatically includes the ID.  The same value
+    is echoed back in the response header.
+    """
+
+    HEADER = "X-Correlation-ID"
+
+    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
+
+        cid = Headers(scope=scope).get(self.HEADER) or uuid.uuid4().hex
+
+        async def send_with_header(message: Message) -> None:
+            if message["type"] == _MSG_RESPONSE_START:
+                headers = MutableHeaders(scope=message)
+                headers[self.HEADER] = cid
+            await send(message)
+
+        token = correlation_id.set(cid)
+        try:
+            await self.app(scope, receive, send_with_header)
+        finally:
+            correlation_id.reset(token)
+
+
+class RequestLoggingMiddleware:
+    """Log every request/response pair with timing and status information."""
+
+    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
+
+        path = scope["path"]
+        if any(path.startswith(p) for p in _QUIET_PREFIXES):
+            await self.app(scope, receive, send)
+            return
+
+        method = scope["method"]
+        client = scope.get("client")
+        client_ip = client[0] if client else "unknown"
+
+        _request_logger.debug(
+            _EVENT_REQUEST_STARTED,
+            extra={"method": method, "path": path, "client_ip": client_ip},
+        )
+
+        status_code: int | None = None
+        start = time.perf_counter()
+
+        async def send_capture(message: Message) -> None:
+            nonlocal status_code
+            if message["type"] == _MSG_RESPONSE_START:
+                status_code = message["status"]
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_capture)
+        finally:
+            # Log completion even when the inner app raises, so 500s are observable.
+            duration_ms = round((time.perf_counter() - start) * 1000, 2)
+            _request_logger.info(
+                _EVENT_REQUEST_COMPLETED,
+                extra={
+                    "method": method,
+                    "path": path,
+                    "status_code": status_code,
+                    "duration_ms": duration_ms,
+                    "client_ip": client_ip,
+                },
+            )

simple_module_hosting/_phase_helpers.py

@@ -0,0 +1,160 @@
+"""Helpers extracted from ``app_builder.py`` — exception handlers, middleware
+pipeline installation, static mounts, and the SM012 post-registration check.
+
+Kept private to the hosting package; ``app_builder.create_app`` is the only
+intended caller.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from fastapi import FastAPI
+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 starlette.exceptions import HTTPException
+from starlette.middleware.sessions import SessionMiddleware
+
+from simple_module_hosting._error_handlers import (
+    http_exception_handler,
+    not_found_error_handler,
+    unhandled_exception_handler,
+)
+from simple_module_hosting.i18n_middleware import LocaleMiddleware
+from simple_module_hosting.middleware import (
+    CorrelationIdMiddleware,
+    InertiaLayoutDataMiddleware,
+    RequestLoggingMiddleware,
+    SecurityHeadersMiddleware,
+    TenantMiddleware,
+)
+from simple_module_hosting.settings import Settings
+
+if TYPE_CHECKING:
+    from simple_module_core.menu import MenuRegistry
+    from simple_module_core.permissions import PermissionRegistry
+
+logger = logging.getLogger(__name__)
+
+
+def register_exception_handlers(app: FastAPI, modules: list) -> None:
+    """Install framework-level exception handlers, then per-module handlers."""
+    app.add_exception_handler(
+        InertiaVersionConflictException,
+        inertia_version_conflict_exception_handler,
+    )
+    app.add_exception_handler(HTTPException, http_exception_handler)
+    app.add_exception_handler(NotFoundError, not_found_error_handler)
+    app.add_exception_handler(Exception, unhandled_exception_handler)
+    for mod in modules:
+        mod.register_exception_handlers(app)
+
+
+def install_middleware(
+    app: FastAPI,
+    settings: Settings,
+    modules: list,
+    menu_registry: MenuRegistry,
+    perm_registry: PermissionRegistry,
+) -> None:
+    """Install the full middleware pipeline.
+
+    Order matters: last added = first executed. Execution order:
+    CorrelationId → RequestLogging → Security → Session
+    → [module] → (Tenant, if multi_tenant) → Locale → Inertia.
+    """
+    app.add_middleware(
+        InertiaLayoutDataMiddleware,
+        menu_registry=menu_registry,
+        permission_registry=perm_registry,
+    )
+    app.add_middleware(
+        LocaleMiddleware,
+        supported_locales=settings.i18n_supported_locales,
+        default_locale=settings.i18n_default_locale,
+        cookie_name=settings.i18n_cookie_name,
+    )
+    if settings.multi_tenant:
+        app.add_middleware(TenantMiddleware, header=settings.tenant_header or None)
+    for mod in modules:
+        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.
+    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)
+    app.add_middleware(RequestLoggingMiddleware)
+    app.add_middleware(CorrelationIdMiddleware)
+
+
+def mount_module_static_dirs(app: FastAPI, modules: list) -> None:
+    """Mount each module's declared static directories.
+
+    Modules typically expose ``/modules/<name>/static`` for pre-bundled
+    frontend assets shipped inside the wheel.
+    """
+    for mod in modules:
+        for url_prefix, directory in mod.static_mounts().items():
+            directory_path = Path(directory)
+            if not directory_path.is_dir():
+                logger.warning(
+                    "Module '%s' declared static mount %s -> %s but directory does not exist",
+                    mod.meta.name,
+                    url_prefix,
+                    directory_path,
+                )
+                continue
+            app.mount(
+                url_prefix,
+                StaticFiles(directory=directory_path),
+                name=f"static:{mod.meta.name}",
+            )
+
+
+def check_settings_registration(app: FastAPI, modules: list) -> list[Diagnostic]:
+    """SM012: warn if a module overrides register_settings but added nothing to app.state.
+
+    Must run after Phase 4 (register_settings) and therefore can't join the
+    Phase 2 diagnostics pass; returning a list lets the caller route it through
+    the same ``print_diagnostics`` sink.
+    """
+    diagnostics: list[Diagnostic] = []
+    for mod in modules:
+        cls = type(mod)
+        if "register_settings" not in cls.__dict__:
+            continue
+        # Match the convention actually used by modules: `app.state.<package>`
+        # (snake_case package name, e.g. `background_tasks`), which aligns
+        # with Settings-module autodiscovery in `settings._module_settings`.
+        package = cls.__module__.split(".", 1)[0]
+        candidates = (package, mod.meta.name.lower())
+        if any(hasattr(app.state, c) for c in candidates):
+            continue
+        mod_prefix = package
+        diagnostics.append(
+            Diagnostic(
+                level=DiagnosticLevel.WARNING,
+                code="SM012",
+                message="register_settings() was overridden but added nothing to app.state",
+                module_name=mod.meta.name,
+                suggestion=(
+                    f"Store your module state on app.state "
+                    f"(e.g., app.state.{mod_prefix} = {mod.meta.name}Services(...))"
+                ),
+            )
+        )
+    return diagnostics