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

simple_module_hosting/health.py

@@ -0,0 +1,79 @@
+"""Health check endpoints."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from fastapi import APIRouter, Request
+from simple_module_core.health import HealthCheckResult, HealthRegistry, HealthStatus
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["Health"])
+
+_KEY_STATUS = "status"
+_KEY_CHECKS = "checks"
+_KEY_MIGRATION = "migration"
+_KEY_DETAIL = "detail"
+_STATUS_HEALTHY = "healthy"
+_STATUS_ALIVE = "alive"
+
+# Severity ordering for aggregation: worst status wins
+_STATUS_SEVERITY = {
+    HealthStatus.HEALTHY: 0,
+    HealthStatus.DEGRADED: 1,
+    HealthStatus.UNHEALTHY: 2,
+}
+
+
+@router.get("/health")
+async def health(request: Request) -> dict:
+    migration = getattr(request.app.state, "migration", None)
+    return {
+        _KEY_STATUS: _STATUS_HEALTHY,
+        _KEY_MIGRATION: migration,
+    }
+
+
+@router.get("/health/live")
+async def liveness() -> dict:
+    return {_KEY_STATUS: _STATUS_ALIVE}
+
+
+@router.get("/health/ready")
+async def readiness(request: Request) -> dict:
+    registry: HealthRegistry = request.app.state.sm.health_registry
+    checks = registry.all_checks
+
+    if not checks:
+        return {_KEY_STATUS: _STATUS_HEALTHY, _KEY_CHECKS: {}}
+
+    # Run all checks concurrently
+    async def _run_check(name: str, check_fn):
+        try:
+            return name, await check_fn()
+        except Exception as exc:
+            return name, HealthCheckResult(
+                status=HealthStatus.UNHEALTHY,
+                detail=str(exc),
+            )
+
+    tasks = [_run_check(c.name, c.check) for c in checks]
+    completed = await asyncio.gather(*tasks)
+
+    results: dict[str, HealthCheckResult] = dict(completed)
+
+    # Aggregate: worst status wins
+    worst = HealthStatus.HEALTHY
+    for result in results.values():
+        if _STATUS_SEVERITY[result.status] > _STATUS_SEVERITY[worst]:
+            worst = result.status
+
+    return {
+        _KEY_STATUS: worst.value,
+        _KEY_CHECKS: {
+            name: {_KEY_STATUS: r.status.value, **({_KEY_DETAIL: r.detail} if r.detail else {})}
+            for name, r in results.items()
+        },
+    }

simple_module_hosting/host_settings.py

@@ -0,0 +1,33 @@
+"""Host-level settings stored in the DB (not env).
+
+Registered under ``package="host"`` so the UI shows them alongside module
+settings. The hosting layer still reads these directly from
+``app.state.host.settings``.
+"""
+
+from __future__ import annotations
+
+from pydantic import model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class HostSettings(BaseSettings):
+    """DB-backed host configuration — defaults live here, overrides in DB."""
+
+    model_config = SettingsConfigDict(extra="ignore")
+
+    multi_tenant: bool = False
+    tenant_header: str = ""
+
+    i18n_default_locale: str = "en"
+    i18n_supported_locales: list[str] = ["en"]
+    i18n_cookie_name: str = "locale"
+
+    @model_validator(mode="after")
+    def _check_default_locale_supported(self) -> HostSettings:
+        if self.i18n_default_locale not in self.i18n_supported_locales:
+            raise ValueError(
+                f"i18n_default_locale '{self.i18n_default_locale}' is not in "
+                f"i18n_supported_locales {self.i18n_supported_locales}"
+            )
+        return self

simple_module_hosting/i18n_deps.py

@@ -0,0 +1,25 @@
+"""FastAPI dependency for request-scoped Translator resolution."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from simple_module_core.i18n import Translator
+
+
+async def get_translator(request: Request) -> Translator:
+    """Resolve a Translator bound to ``request.state.locale``.
+
+    Reads the registry from ``request.app.state.sm.i18n_registry`` and the
+    default locale from ``request.app.state.sm.settings.i18n_default_locale``.
+
+    ``request.state.locale`` is populated by LocaleMiddleware.
+    """
+    sm = request.app.state.sm
+    default_locale = sm.settings.i18n_default_locale
+    locale = getattr(request.state, "locale", default_locale)
+    return Translator(sm.i18n_registry, locale=locale, default_locale=default_locale)
+
+
+TranslatorDep = Annotated[Translator, Depends(get_translator)]

simple_module_hosting/i18n_manifest.py

@@ -0,0 +1,202 @@
+"""Emit generated-resources.ts + keys.generated.ts for the frontend.
+
+Both files are consumed by ``@simple-module-py/i18n``:
+
+* ``generated-resources.ts`` — flat empty-string keys, fed into i18next's
+  ``CustomTypeOptions['resources']`` so ``t('foo.bar')`` narrows to the
+  accepted key union.
+
+* ``keys.generated.ts`` — a nested ``keys`` constant whose leaves are the
+  full dotted key strings. Consumers use ``t(keys.foo.bar)`` for typed
+  call-sites.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from simple_module_core import ModuleBase
+from simple_module_core.i18n import PLURAL_CATEGORIES, I18nRegistry
+
+from simple_module_hosting.manifest import _write_if_changed
+from simple_module_hosting.settings import Settings
+
+logger = logging.getLogger(__name__)
+
+
+def build_i18n_registry(
+    settings: Settings,
+    modules: list[ModuleBase],
+    project_root: Path,
+) -> tuple[I18nRegistry, list[tuple[str, str, Path]]]:
+    """Construct the i18n registry from module + host + UI sources.
+
+    Returns ``(registry, extra_sources)`` where ``extra_sources`` is the list
+    of ``(reporter_name, namespace, dir)`` triples the diagnostic runner
+    needs to validate non-module locale directories.
+    """
+    registry = I18nRegistry(
+        default_locale=settings.i18n_default_locale,
+        supported_locales=settings.i18n_supported_locales,
+    )
+    extra_sources: list[tuple[str, str, Path]] = []
+
+    for mod in modules:
+        for namespace, locale_dir in mod.locale_dirs().items():
+            registry.add_source(namespace, locale_dir)
+
+    host_locales = project_root / "host" / "locales"
+    if host_locales.is_dir():
+        registry.add_source("host", host_locales)
+        extra_sources.append(("host", "host", host_locales))
+
+    ui_locales = project_root / "packages" / "ui" / "locales"
+    if ui_locales.is_dir():
+        registry.add_source("ui", ui_locales)
+        extra_sources.append(("packages/ui", "ui", ui_locales))
+
+    registry.load()
+    return registry, extra_sources
+
+
+def emit_frontend_types(registry: I18nRegistry, project_root: Path) -> None:
+    """Write the TS augmentation files into @simple-module-py/i18n if present.
+
+    Logs but does not raise on failure — stale types are preferable to a
+    broken boot. Dev-loop only; callers should gate on ``is_development``.
+    """
+    try:
+        pkg_src = project_root / "packages" / "i18n" / "src"
+        if pkg_src.is_dir():
+            write_generated_resources(registry, pkg_src)
+    except Exception:
+        logger.exception("Failed to write generated-resources.ts — frontend types will be stale")
+
+
+_RESOURCES_HEADER = (
+    "// AUTO-GENERATED by simple_module_hosting.i18n_manifest — do not edit by hand.\n"
+    "// Regenerate by booting the host in development mode."
+)
+
+_KEYS_HEADER = _RESOURCES_HEADER
+
+_PLURAL_SUFFIXES: tuple[str, ...] = tuple(f"_{c}" for c in PLURAL_CATEGORIES)
+
+
+def write_generated_resources(registry: I18nRegistry, output_dir: Path) -> Path:
+    """Write both ``generated-resources.ts`` and ``keys.generated.ts``.
+
+    Returns the path of the resources file. Both files skip the disk write
+    when content matches what's already on disk (to avoid bumping mtimes
+    that would trigger spurious Vite HMR).
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    messages = registry.messages(registry.default_locale)
+    keys = sorted(messages.keys())
+
+    resources_path = output_dir / "generated-resources.ts"
+    if _write_if_changed(resources_path, _render_resources(keys)):
+        logger.info("Wrote %s (%d keys)", resources_path.name, len(keys))
+
+    keys_path = output_dir / "keys.generated.ts"
+    if _write_if_changed(keys_path, _render_keys(keys)):
+        logger.info("Wrote %s", keys_path.name)
+
+    return resources_path
+
+
+def _render_resources(keys: list[str]) -> str:
+    lines = [_RESOURCES_HEADER, "export default {", "  translation: {"]
+    for key in keys:
+        lines.append(f"    '{key}': '',")
+    lines.append("  },")
+    lines.append("} as const;")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _render_keys(keys: list[str]) -> str:
+    """Render the nested ``keys`` constant tree."""
+    tree = _build_key_tree(keys)
+    return f"{_KEYS_HEADER}\n\nexport const keys = {_serialize(tree, indent=0)} as const;\n"
+
+
+def _build_key_tree(flat_keys: list[str]) -> dict[str, Any]:
+    """Build a nested dict from a list of dotted keys.
+
+    Leaves are the full dotted key string. Plural stems (e.g. ``foo.items``
+    when ``foo.items_one``/``foo.items_other`` exist) are added as virtual
+    leaves so callers can pass them directly to ``t(key, {count})``.
+    """
+    tree: dict[str, Any] = {}
+    stems: set[str] = set()
+
+    for flat_key in flat_keys:
+        for suffix in _PLURAL_SUFFIXES:
+            if flat_key.endswith(suffix):
+                stems.add(flat_key[: -len(suffix)])
+                break
+        _insert(tree, flat_key.split("."), flat_key)
+
+    existing = set(flat_keys)
+    for stem in stems:
+        if stem in existing:
+            continue
+        _insert(tree, stem.split("."), stem)
+
+    return tree
+
+
+def _insert(tree: dict[str, Any], path: list[str], value: str) -> None:
+    """Insert ``value`` into ``tree`` at ``path``.
+
+    Existing leaves win over later inserts — real keys cannot be shadowed
+    by virtual plural stems, and a path segment that collides with an
+    existing leaf causes the insertion to be silently aborted.
+    """
+    cursor: Any = tree
+    for segment in path[:-1]:
+        existing = cursor.get(segment)
+        if isinstance(existing, dict):
+            cursor = existing
+        elif existing is None:
+            new_dict: dict[str, Any] = {}
+            cursor[segment] = new_dict
+            cursor = new_dict
+        else:
+            return
+    leaf_key = path[-1]
+    if leaf_key not in cursor:
+        cursor[leaf_key] = value
+
+
+def _serialize(node: Any, *, indent: int) -> str:
+    """Emit a dict-of-dicts tree as pretty-printed TypeScript object literal.
+
+    Strings are wrapped in single quotes to match the project's biome config
+    (``quoteStyle: "single"``); dotted i18n keys never contain single quotes,
+    so plain wrapping is safe.
+    """
+    if isinstance(node, str):
+        return f"'{node}'"
+    if not isinstance(node, dict) or not node:
+        return "{}"
+    pad = "  " * indent
+    inner_pad = "  " * (indent + 1)
+    lines = ["{"]
+    for k in sorted(node.keys()):
+        key_repr = k if _is_valid_js_identifier(k) else f"'{k}'"
+        lines.append(f"{inner_pad}{key_repr}: {_serialize(node[k], indent=indent + 1)},")
+    lines.append(f"{pad}}}")
+    return "\n".join(lines)
+
+
+def _is_valid_js_identifier(name: str) -> bool:
+    """True if ``name`` can be an unquoted object key in JS (ASCII subset)."""
+    if not name or not (name[0].isalpha() or name[0] in "_$"):
+        return False
+    return all(c.isalnum() or c in "_$" for c in name)

simple_module_hosting/i18n_middleware.py

@@ -0,0 +1,95 @@
+"""LocaleMiddleware — resolve active locale from cookie / Accept-Language / default."""
+
+from __future__ import annotations
+
+from starlette.datastructures import Headers
+from starlette.requests import Request
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+
+class LocaleMiddleware:
+    """Set ``request.state.locale`` based on cookie, Accept-Language, and default.
+
+    Resolution order:
+
+    1. Cookie named ``cookie_name``, validated against ``supported_locales``.
+    2. ``Accept-Language`` header, negotiated against supported_locales via
+       longest-prefix match (``es-MX`` matches supported ``es``).
+    3. ``default_locale``.
+
+    Runs as a pure ASGI middleware (no BaseHTTPMiddleware) to match the rest
+    of the framework's middleware stack.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        supported_locales: list[str],
+        default_locale: str,
+        cookie_name: str = "locale",
+    ) -> None:
+        self.app = app
+        self.supported = list(supported_locales)
+        self.default_locale = default_locale
+        self.cookie_name = cookie_name
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope)
+        locale = self._resolve(request)
+        request.state.locale = locale
+        await self.app(scope, receive, send)
+
+    def _resolve(self, request: Request) -> str:
+        # 1. Cookie.
+        cookie = request.cookies.get(self.cookie_name)
+        if cookie and cookie in self.supported:
+            return cookie
+
+        # 2. Accept-Language.
+        accept = Headers(scope=request.scope).get("accept-language")
+        if accept:
+            matched = self._negotiate(accept)
+            if matched:
+                return matched
+
+        # 3. Default.
+        return self.default_locale
+
+    def _negotiate(self, accept_language: str) -> str | None:
+        """Parse Accept-Language and return the highest-q supported locale.
+
+        Matches either exact tag or primary prefix (``es-MX`` -> ``es``).
+        """
+        # Hard cap to blunt adversarial Accept-Language: a,a,a,... spam.
+        # Real browsers send <10 tags; 20 is comfortably above that.
+        parts = accept_language.split(",", 20)
+        candidates: list[tuple[float, str]] = []
+        for part in parts[:20]:
+            part = part.strip()
+            if not part:
+                continue
+            tag, _, q_part = part.partition(";")
+            tag = tag.strip().lower()
+            q_part = q_part.strip().lower()
+            try:
+                q = float(q_part.split("=", 1)[1]) if q_part.startswith("q=") else 1.0
+            except ValueError:
+                q = 1.0
+            candidates.append((q, tag))
+
+        # Sort by q descending, stable.
+        candidates.sort(key=lambda pair: -pair[0])
+
+        supported_lower = {loc.lower(): loc for loc in self.supported}
+        for _, tag in candidates:
+            if tag in supported_lower:
+                return supported_lower[tag]
+            primary = tag.split("-", 1)[0]
+            if primary in supported_lower:
+                return supported_lower[primary]
+        return None

simple_module_hosting/inertia_deps.py

@@ -0,0 +1,27 @@
+"""Lazy Inertia dependency that resolves from app state at request time."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from inertia import Inertia
+
+
+async def get_inertia(request: Request) -> Inertia:
+    """Resolve the Inertia instance from the app's configured dependency.
+
+    This allows view endpoints to declare ``inertia: InertiaDep`` without
+    needing the Inertia config at import time.
+    """
+    inertia_dep = request.app.state.inertia_dependency
+    inertia = inertia_dep(request, None)
+
+    shared = getattr(request.state, "inertia_shared", None)
+    if shared:
+        inertia.share(**shared)
+
+    return inertia
+
+
+InertiaDep = Annotated[Inertia, Depends(get_inertia)]

simple_module_hosting/inertia_utils.py

@@ -0,0 +1,31 @@
+"""Shared Inertia utilities for form-action view endpoints."""
+
+from __future__ import annotations
+
+from fastapi import Request
+from pydantic import ValidationError
+from starlette.responses import RedirectResponse
+
+from simple_module_hosting.redirects import safe_referer_or_root
+
+SESSION_ERRORS_KEY = "_errors"
+
+
+def validation_errors_to_dict(exc: ValidationError) -> dict[str, str]:
+    """Flatten a Pydantic ValidationError — takes only the last loc segment
+    so nested model paths don't leak into the frontend field keys."""
+    errors: dict[str, str] = {}
+    for error in exc.errors():
+        field = str(error["loc"][-1]) if error["loc"] else "general"
+        errors[field] = error["msg"]
+    return errors
+
+
+def redirect_back_with_errors(request: Request, errors: dict[str, str]) -> RedirectResponse:
+    """Store validation errors in the session and redirect to the referring page.
+
+    Uses ``safe_referer_or_root`` to reject attacker-controlled Referer values
+    (cross-origin URLs) — otherwise this becomes a reflected open redirect
+    accessible to any attacker who can trigger a form validation error."""
+    request.session[SESSION_ERRORS_KEY] = errors
+    return RedirectResponse(safe_referer_or_root(request), status_code=303)

simple_module_hosting/logging.py

@@ -0,0 +1,91 @@
+"""Structured logging — JSON formatter, correlation IDs, and setup helper."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from contextvars import ContextVar
+from datetime import UTC, datetime
+
+correlation_id: ContextVar[str] = ContextVar("correlation_id", default="")
+
+
+class _CorrelationIdFilter(logging.Filter):
+    """Inject the current correlation ID into every log record."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.correlation_id = correlation_id.get("")  # type: ignore[attr-defined]
+        return True
+
+
+class JsonFormatter(logging.Formatter):
+    """Emit log records as single-line JSON objects.
+
+    Standard fields: timestamp, level, logger, message, correlation_id.
+    Extra keys (method, path, status_code, duration_ms, client_ip, user_id)
+    are included when present on the record.
+    """
+
+    _EXTRA_KEYS = (
+        "method",
+        "path",
+        "status_code",
+        "duration_ms",
+        "client_ip",
+        "user_id",
+        "operation",
+        "entity",
+        "entity_id",
+        "db_duration_ms",
+    )
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_obj: dict[str, object] = {
+            "timestamp": datetime.fromtimestamp(record.created, tz=UTC).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "correlation_id": getattr(record, "correlation_id", ""),
+        }
+
+        for key in self._EXTRA_KEYS:
+            value = getattr(record, key, None)
+            if value is not None:
+                log_obj[key] = value
+
+        if record.exc_info and record.exc_info[0] is not None:
+            log_obj["exception"] = self.formatException(record.exc_info)
+
+        return json.dumps(log_obj, default=str)
+
+
+_TEXT_FORMAT = "%(asctime)s %(levelname)-8s [%(correlation_id)s] %(name)s — %(message)s"
+
+
+def setup_logging(*, level: str = "INFO", json_format: bool = True) -> None:
+    """Configure the root logger for structured output.
+
+    Parameters
+    ----------
+    level:
+        Log level name (DEBUG, INFO, WARNING, …).
+    json_format:
+        When *True* (the default) emit JSON lines; otherwise use a
+        human-readable text format that still includes the correlation ID.
+    """
+    root = logging.getLogger()
+    root.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+    root.handlers.clear()
+
+    handler = logging.StreamHandler(sys.stdout)
+
+    if json_format:
+        handler.setFormatter(JsonFormatter())
+    else:
+        handler.setFormatter(logging.Formatter(_TEXT_FORMAT))
+
+    handler.addFilter(_CorrelationIdFilter())
+
+    root.addHandler(handler)