simple-module-hosting 0.0.1__tar.gz

simple_module_hosting-0.0.1/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/

simple_module_hosting-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anto Subash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simple_module_hosting-0.0.1/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: simple_module_hosting
+Version: 0.0.1
+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
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,inertia,scaffolding,simple-module,starlette,uvicorn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
+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: jinja2>=3.1
+Requires-Dist: simple-module-core==0.0.1
+Requires-Dist: simple-module-db==0.0.1
+Requires-Dist: starlette>=0.44
+Requires-Dist: tomlkit>=0.13
+Requires-Dist: uvicorn[standard]>=0.34
+Description-Content-Type: text/markdown
+
+# simple_module_hosting
+
+FastAPI + Inertia.js host runtime for the [simple_module](https://github.com/antosubash/simple_module_python) framework — builds the app, wires the middleware pipeline, exposes the `sm` / `simple-module` CLI, and ships the project scaffolder.
+
+## Install
+
+```bash
+pip install simple_module_hosting
+```
+
+For a new project, most users run the generator instead:
+
+```bash
+uvx simple-module new my-app
+```
+
+## What it provides
+
+- `create_app(settings)` — returns a fully-wired `FastAPI` instance with all discovered modules registered.
+- Middleware pipeline (execution order): CorrelationId → RequestLogging → SecurityHeaders → Session → `<module middleware>` → Tenant (opt-in) → Locale → InertiaLayoutData → app.
+- Inertia wiring — shared props (`auth`, `menus`, `i18n`), `InertiaDep`, page-route lookup.
+- CLI entry points: both `sm` and `simple-module` are installed and alias the same Click tree.
+- Scaffolders — `sm create-host`, `sm create-module`, `sm new` (greenfield app with users + dashboard + permissions pre-wired), `sm gen-pages`.
+
+## Usage
+
+Minimal `main.py`:
+
+```python
+from simple_module_hosting import create_app
+from simple_module_hosting.settings import Settings
+
+settings = Settings()           # reads SM_* env vars
+app = create_app(settings)      # discovers + registers every installed module
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+CLI:
+
+```bash
+simple-module new my-app        # scaffold a new project
+simple-module doctor            # diagnostic codes (SM001-SM017)
+simple-module gen-pages         # regenerate client_app/modules.generated.ts
+```
+
+`sm` works identically to `simple-module`.
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`
+- `fastapi`, `fastapi-inertia`, `starlette`, `uvicorn`, `click`, `jinja2`, `httpx`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_hosting-0.0.1/README.md

@@ -0,0 +1,58 @@
+# simple_module_hosting
+
+FastAPI + Inertia.js host runtime for the [simple_module](https://github.com/antosubash/simple_module_python) framework — builds the app, wires the middleware pipeline, exposes the `sm` / `simple-module` CLI, and ships the project scaffolder.
+
+## Install
+
+```bash
+pip install simple_module_hosting
+```
+
+For a new project, most users run the generator instead:
+
+```bash
+uvx simple-module new my-app
+```
+
+## What it provides
+
+- `create_app(settings)` — returns a fully-wired `FastAPI` instance with all discovered modules registered.
+- Middleware pipeline (execution order): CorrelationId → RequestLogging → SecurityHeaders → Session → `<module middleware>` → Tenant (opt-in) → Locale → InertiaLayoutData → app.
+- Inertia wiring — shared props (`auth`, `menus`, `i18n`), `InertiaDep`, page-route lookup.
+- CLI entry points: both `sm` and `simple-module` are installed and alias the same Click tree.
+- Scaffolders — `sm create-host`, `sm create-module`, `sm new` (greenfield app with users + dashboard + permissions pre-wired), `sm gen-pages`.
+
+## Usage
+
+Minimal `main.py`:
+
+```python
+from simple_module_hosting import create_app
+from simple_module_hosting.settings import Settings
+
+settings = Settings()           # reads SM_* env vars
+app = create_app(settings)      # discovers + registers every installed module
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+CLI:
+
+```bash
+simple-module new my-app        # scaffold a new project
+simple-module doctor            # diagnostic codes (SM001-SM017)
+simple-module gen-pages         # regenerate client_app/modules.generated.ts
+```
+
+`sm` works identically to `simple-module`.
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`
+- `fastapi`, `fastapi-inertia`, `starlette`, `uvicorn`, `click`, `jinja2`, `httpx`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_hosting-0.0.1/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "simple_module_hosting"
+version = "0.0.1"
+description = "FastAPI + Inertia.js host runtime for simple_module — app_builder, middleware stack, CLI (sm / simple-module), scaffolding"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "fastapi", "inertia", "starlette", "uvicorn", "scaffolding"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "click>=8.1",
+    "fastapi>=0.115",
+    "fastapi-inertia>=1.0",
+    "httpx>=0.27",
+    "jinja2>=3.1",
+    "simple_module_core==0.0.1",
+    "simple_module_db==0.0.1",
+    "starlette>=0.44",
+    "tomlkit>=0.13",
+    "uvicorn[standard]>=0.34",
+]
+
+[project.scripts]
+sm = "simple_module_hosting.cli:main"
+simple-module = "simple_module_hosting.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/antosubash/simple_module_python"
+Repository = "https://github.com/antosubash/simple_module_python"
+Issues = "https://github.com/antosubash/simple_module_python/issues"
+Changelog = "https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["simple_module_hosting"]
+
+[tool.uv.sources]
+simple_module_core = { workspace = true }
+simple_module_db = { workspace = true }

simple_module_hosting-0.0.1/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-0.0.1/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-0.0.1/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-0.0.1/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-0.0.1/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-0.0.1/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,
+                },
+            )