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

settings/__init__.py

@@ -0,0 +1 @@
+"""Settings module."""

settings/_module_settings.py

@@ -0,0 +1,169 @@
+"""Autodiscover per-module pydantic ``BaseSettings`` attached to ``app.state``.
+
+Each module stores a services dataclass on ``app.state.<package>`` whose
+``.settings`` attribute is a pydantic ``BaseSettings`` subclass.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+
+from settings.env_vars import env_prefix_for
+from settings.hydrate import value_type_for_field
+
+# We intentionally DON'T match the bare word "token" (would mask
+# `verification_token_lifetime_seconds` — just an int) or "key" alone (would
+# mask `s3_bucket_key_prefix`). Only fragments that actually indicate material.
+_SECRET_PATTERNS = re.compile(
+    r"(password|secret|api[_-]?key|private[_-]?key|token[_-]?secret)", re.I
+)
+SECRET_MASK = "••••••••"
+
+
+def is_secret_field(name: str) -> bool:
+    """True if a field name suggests it holds credential material."""
+    return bool(_SECRET_PATTERNS.search(name))
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleSettingField:
+    name: str
+    env_var: str
+    value: Any
+    default: Any
+    description: str
+    is_secret: bool
+    type: str
+    requires_restart: bool
+    group: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleSettingsView:
+    module_name: str
+    package: str
+    env_prefix: str
+    class_name: str
+    fields: list[ModuleSettingField]
+
+
+def _mask(value: Any) -> Any:
+    if value in (None, "", [], {}):
+        return value
+    return SECRET_MASK
+
+
+def _package_of(mod: Any) -> str:
+    return type(mod).__module__.split(".", 1)[0]
+
+
+def _extract_settings(app: FastAPI, package: str) -> BaseSettings | None:
+    """Return the ``BaseSettings`` instance attached to ``app.state.<package>``.
+
+    The services dataclass exposes it as ``.settings``. We also accept the
+    rare case where the module stashes the settings object directly.
+    """
+    services = getattr(app.state, package, None)
+    if services is None:
+        return None
+    if isinstance(services, BaseSettings):
+        return services
+    inner = getattr(services, "settings", None)
+    return inner if isinstance(inner, BaseSettings) else None
+
+
+def _field_view(name: str, settings: BaseSettings, prefix: str) -> ModuleSettingField:
+    cls = type(settings)
+    info = cls.model_fields[name]
+    raw_value = getattr(settings, name)
+    secret = is_secret_field(name)
+    extra = info.json_schema_extra if isinstance(info.json_schema_extra, dict) else {}
+    return ModuleSettingField(
+        name=name,
+        env_var=f"{prefix}{name.upper()}",
+        value=_mask(raw_value) if secret else raw_value,
+        default=_mask(info.default) if secret else info.default,
+        description=info.description or "",
+        is_secret=secret,
+        type=value_type_for_field(cls, name),
+        requires_restart=bool(extra.get("requires_restart", False)),
+        group=extra.get("group"),
+    )
+
+
+def collect_module_settings(app: FastAPI) -> list[ModuleSettingsView]:
+    """Return a sorted, serializable view of every module's BaseSettings.
+
+    Folds in both ``app.state.sm.modules`` (plugin modules) and additional
+    packages registered via ``app.state.settings.module_registry`` (e.g.
+    ``"host"``) that aren't backed by a ``ModuleBase`` instance.
+    """
+    views: list[ModuleSettingsView] = []
+    seen: set[str] = set()
+
+    for mod in getattr(app.state.sm, "modules", ()):
+        package = _package_of(mod)
+        settings = _extract_settings(app, package)
+        if settings is None:
+            continue
+        views.append(_build_view(mod.meta.name, package, settings))
+        seen.add(package)
+
+    settings_services = getattr(app.state, "settings", None)
+    registry = getattr(settings_services, "module_registry", None)
+    if registry is not None:
+        for package in registry.all_packages():
+            if package in seen:
+                continue
+            settings = _extract_settings(app, package)
+            if settings is None:
+                continue
+            views.append(_build_view(package.title(), package, settings))
+            seen.add(package)
+
+    views.sort(key=lambda v: v.module_name)
+    return views
+
+
+def _build_view(module_name: str, package: str, settings: BaseSettings) -> ModuleSettingsView:
+    prefix = env_prefix_for(package)
+    fields = [_field_view(name, settings, prefix) for name in type(settings).model_fields]
+    return ModuleSettingsView(
+        module_name=module_name,
+        package=package,
+        env_prefix=prefix,
+        class_name=type(settings).__name__,
+        fields=fields,
+    )
+
+
+def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
+    """Convert dataclass views to plain dicts for Inertia props."""
+    return [
+        {
+            "module_name": v.module_name,
+            "package": v.package,
+            "env_prefix": v.env_prefix,
+            "class_name": v.class_name,
+            "fields": [
+                {
+                    "name": f.name,
+                    "env_var": f.env_var,
+                    "value": f.value,
+                    "default": f.default,
+                    "description": f.description,
+                    "is_secret": f.is_secret,
+                    "type": f.type,
+                    "requires_restart": f.requires_restart,
+                    "group": f.group,
+                }
+                for f in v.fields
+            ],
+        }
+        for v in views
+    ]

settings/cli.py

@@ -0,0 +1,78 @@
+"""``sm-settings`` CLI — currently only ``import-from-env``.
+
+One-shot migration: walks every registered module's ``BaseSettings`` and,
+for each field whose legacy ``SM_<PREFIX>_<FIELD>`` env var is set, writes
+a SYSTEM-scoped override into the Settings store.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+from fastapi import FastAPI
+
+from settings.constants import MODULE_PACKAGE
+from settings.env_vars import env_prefix_for
+from settings.hydrate import value_type_for_field
+from settings.store import SettingsStore
+
+
+async def import_from_env_impl(app: FastAPI, store: SettingsStore) -> int:
+    """Write a SYSTEM override for every ``SM_<PREFIX>_<FIELD>`` env var set.
+
+    Returns the count of overrides written. Env vars that don't match a
+    registered field are ignored.
+    """
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    count = 0
+    for package, cls in registry.items():
+        prefix = env_prefix_for(package)
+        for field_name in cls.model_fields:
+            raw = os.environ.get(f"{prefix}{field_name.upper()}")
+            if raw is None:
+                continue
+            vtype = value_type_for_field(cls, field_name)
+            await store.set_override(package, field_name, raw, vtype)
+            count += 1
+    return count
+
+
+def main() -> int:
+    """Console-script entry point for ``sm-settings``.
+
+    Supports a single subcommand: ``import-from-env``.
+    """
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help"):
+        print("Usage: sm-settings import-from-env")
+        return 0 if argv else 1
+    if argv[0] != "import-from-env":
+        print(f"Unknown command: {argv[0]}", file=sys.stderr)
+        print("Usage: sm-settings import-from-env", file=sys.stderr)
+        return 2
+
+    from simple_module_hosting.app_builder import create_app
+    from simple_module_hosting.settings import Settings
+
+    from settings.service import SettingService
+
+    app = create_app(Settings())
+
+    async def run() -> int:
+        async with (
+            app.router.lifespan_context(app),
+            app.state.sm.db.session_factory() as session,
+        ):
+            store = SettingsStore(SettingService(session))
+            n = await import_from_env_impl(app, store)
+            await session.commit()
+            print(f"Imported {n} override(s) from environment.")
+        return 0
+
+    return asyncio.run(run())
+
+
+if __name__ == "__main__":
+    sys.exit(main())

settings/constants.py

@@ -0,0 +1,115 @@
+"""Centralized constants for the Settings module.
+
+Keeps module-level strings (route prefixes, permission ids, table names,
+menu metadata, error messages, field limits, env prefix, i18n namespace,
+scope identifiers) in one place so nothing is duplicated in Python or
+inline-literal'd at call sites.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+# ── Module identity ──────────────────────────────────────────────────
+MODULE_NAME: Final = "Settings"
+MODULE_PACKAGE: Final = "settings"
+ENV_PREFIX: Final = "SM_SETTINGS_"
+LOCALE_NAMESPACE: Final = MODULE_PACKAGE
+
+# ── Scopes ───────────────────────────────────────────────────────────
+# Precedence high → low when resolving a key: USER > TENANT > SYSTEM.
+SCOPE_SYSTEM: Final = "system"
+SCOPE_TENANT: Final = "tenant"
+SCOPE_USER: Final = "user"
+ALL_SCOPES: Final = (SCOPE_SYSTEM, SCOPE_TENANT, SCOPE_USER)
+# scope_id is empty for SYSTEM; empty string (not NULL) so composite unique
+# works uniformly on SQLite and PostgreSQL (NULL breaks uniqueness on PG).
+SYSTEM_SCOPE_ID: Final = ""
+
+# ── Value types ──────────────────────────────────────────────────────
+# Values are always stored as strings; ``value_type`` tells consumers how
+# to interpret the bytes and lets the UI pick the right input control.
+VALUE_TYPE_STRING: Final = "string"
+VALUE_TYPE_BOOL: Final = "bool"
+VALUE_TYPE_INT: Final = "int"
+VALUE_TYPE_FLOAT: Final = "float"
+VALUE_TYPE_JSON: Final = "json"
+ALL_VALUE_TYPES: Final = (
+    VALUE_TYPE_STRING,
+    VALUE_TYPE_BOOL,
+    VALUE_TYPE_INT,
+    VALUE_TYPE_FLOAT,
+    VALUE_TYPE_JSON,
+)
+
+# ── Routing ──────────────────────────────────────────────────────────
+API_PREFIX: Final = "/api/settings"
+VIEW_PREFIX: Final = "/settings"
+VIEW_CREATE_PATH: Final = "/create"
+VIEW_EDIT_PATH: Final = "/{setting_id}/edit"
+VIEW_MODULES_PATH: Final = "/modules"
+API_BY_ID_PATH: Final = "/{setting_id}"
+API_BY_KEY_PATH: Final = "/by-key/{key}"
+API_RESOLVE_PATH: Final = "/resolve/{key}"
+API_SYSTEM_PATH: Final = "/system/{key}"
+API_TENANT_PATH: Final = "/tenant/{scope_id}/{key}"
+API_USER_PATH: Final = "/user/{scope_id}/{key}"
+
+# ── Menu ─────────────────────────────────────────────────────────────
+MENU_LABEL: Final = MODULE_NAME
+MENU_URL: Final = VIEW_PREFIX
+MENU_ICON: Final = "settings"
+MENU_ORDER: Final = 30
+
+# ── Permissions ──────────────────────────────────────────────────────
+PERM_GROUP: Final = MODULE_NAME
+PERM_VIEW: Final = "settings.view"
+PERM_CREATE: Final = "settings.create"
+PERM_EDIT: Final = "settings.edit"
+PERM_DELETE: Final = "settings.delete"
+ALL_PERMISSIONS: Final = (PERM_VIEW, PERM_CREATE, PERM_EDIT, PERM_DELETE)
+
+# ── Database ─────────────────────────────────────────────────────────
+DB_SCHEMA: Final = MODULE_PACKAGE
+TABLE_SETTING: Final = "settings_setting"
+UQ_SCOPE_KEY: Final = "uq_settings_setting_scope_scope_id_key"
+
+# ── Field limits ─────────────────────────────────────────────────────
+KEY_MAX_LENGTH: Final = 200
+VALUE_MAX_LENGTH: Final = 4000
+DESCRIPTION_MAX_LENGTH: Final = 2000
+SCOPE_MAX_LENGTH: Final = 10
+SCOPE_ID_MAX_LENGTH: Final = 255
+VALUE_TYPE_MAX_LENGTH: Final = 10
+
+# ── Inertia page component names ─────────────────────────────────────
+PAGE_BROWSE: Final = f"{MODULE_NAME}/Browse"
+PAGE_CREATE: Final = f"{MODULE_NAME}/Create"
+PAGE_EDIT: Final = f"{MODULE_NAME}/Edit"
+PAGE_MODULES_EDIT: Final = f"{MODULE_NAME}/ModulesEdit"
+
+# ── Inertia prop keys ────────────────────────────────────────────────
+PROP_SETTINGS: Final = "settings"
+PROP_SETTING: Final = "setting"
+PROP_MODULES: Final = "modules"
+PROP_ERROR: Final = "error"
+
+# ── User-facing error messages ───────────────────────────────────────
+ERR_SETTING_NOT_FOUND: Final = "Setting not found"
+ERR_KEY_ALREADY_EXISTS: Final = "Setting key already exists"
+ERR_SYSTEM_SCOPE_NO_ID: Final = "system scope must not have a scope_id"
+ERR_SCOPED_REQUIRES_ID: Final = "tenant/user scope requires a scope_id"
+ERR_UNKNOWN_SCOPE: Final = "unknown scope"
+ERR_VALUE_MISMATCH: Final = "value does not parse as declared value_type"
+
+# ── HTTP ─────────────────────────────────────────────────────────────
+STATUS_CREATED: Final = 201
+STATUS_NO_CONTENT: Final = 204
+STATUS_NOT_FOUND: Final = 404
+STATUS_CONFLICT: Final = 409
+
+# ── Query parameter names ────────────────────────────────────────────
+QP_USER_ID: Final = "user_id"
+QP_TENANT_ID: Final = "tenant_id"
+QP_SCOPE: Final = "scope"
+QP_SCOPE_ID: Final = "scope_id"

settings/contracts/__init__.py

@@ -0,0 +1,24 @@
+"""Settings contracts — public interface for other modules."""
+
+from settings.contracts.accessor import SettingsAccessor
+from settings.contracts.registry import SettingDefinition, SettingsRegistry
+from settings.contracts.schemas import (
+    SettingCreate,
+    SettingOut,
+    SettingScope,
+    SettingUpdate,
+    SettingUpsert,
+    SettingValueType,
+)
+
+__all__ = [
+    "SettingCreate",
+    "SettingDefinition",
+    "SettingOut",
+    "SettingScope",
+    "SettingUpdate",
+    "SettingUpsert",
+    "SettingValueType",
+    "SettingsAccessor",
+    "SettingsRegistry",
+]

settings/contracts/accessor.py

@@ -0,0 +1,236 @@
+"""High-level read/write facade over ``SettingService`` for consumer modules.
+
+Consumers depend on this instead of ``SettingService`` directly so they get:
+- automatic USER > TENANT > SYSTEM resolution bound to the request context,
+- typed getters (`get_bool`, `get_int`, `get_float`, `get_json`) that cast
+  the stored string representation,
+- fallback to the registered default in ``SettingsRegistry`` when a key is
+  unset at every scope.
+
+Example in another module's endpoint:
+
+    from settings.contracts import SettingsDep
+
+    @router.get("/whatever")
+    async def handler(settings: SettingsDep):
+        if await settings.get_bool("orders.bulk_import", default=False):
+            ...
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Final
+
+from settings.constants import SYSTEM_SCOPE_ID
+from settings.contracts.registry import SettingsRegistry
+from settings.contracts.schemas import (
+    BOOL_LITERALS_FALSE,
+    BOOL_LITERALS_TRUE,
+    SettingOut,
+    SettingScope,
+    SettingUpsert,
+    SettingValueType,
+)
+
+if TYPE_CHECKING:
+    from settings.service import SettingService
+
+
+class _Unset:
+    """Typed sentinel for ``bind``'s "no override" marker."""
+
+
+_UNSET: Final = _Unset()
+
+
+def _cast_bool(raw: str, default: Any) -> Any:
+    lowered = raw.strip().lower()
+    if lowered in BOOL_LITERALS_TRUE:
+        return True
+    if lowered in BOOL_LITERALS_FALSE:
+        return False
+    return default
+
+
+def _cast_int(raw: str, default: Any) -> Any:
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return default
+
+
+def _cast_float(raw: str, default: Any) -> Any:
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        return default
+
+
+def _cast_json(raw: str, default: Any) -> Any:
+    try:
+        return json.loads(raw)
+    except (TypeError, ValueError):
+        return default
+
+
+_CASTERS: Final[dict[SettingValueType, Callable[[str, Any], Any]]] = {
+    SettingValueType.BOOL: _cast_bool,
+    SettingValueType.INT: _cast_int,
+    SettingValueType.FLOAT: _cast_float,
+    SettingValueType.JSON: _cast_json,
+}
+
+
+class SettingsAccessor:
+    """Request-scoped facade over ``SettingService``.
+
+    Bound to an optional ``user_id`` + ``tenant_id`` so ``get`` and its
+    typed variants resolve via USER > TENANT > SYSTEM automatically.
+    ``SettingService`` (the implementation) is still reachable for admin
+    flows that need unbound operations.
+    """
+
+    __slots__ = ("_registry", "_svc", "_tenant_id", "_user_id")
+
+    def __init__(
+        self,
+        service: SettingService,
+        registry: SettingsRegistry | None = None,
+        *,
+        user_id: str | None = None,
+        tenant_id: str | None = None,
+    ) -> None:
+        self._svc = service
+        self._registry = registry
+        self._user_id = user_id
+        self._tenant_id = tenant_id
+
+    @property
+    def service(self) -> SettingService:
+        return self._svc
+
+    @property
+    def registry(self) -> SettingsRegistry | None:
+        return self._registry
+
+    def bind(
+        self,
+        *,
+        user_id: str | None | _Unset = _UNSET,
+        tenant_id: str | None | _Unset = _UNSET,
+    ) -> SettingsAccessor:
+        """Return a new accessor with the given user/tenant overrides.
+
+        Pass ``None`` explicitly to clear that side of the context;
+        omit the argument to preserve the current value. ``bind()`` with
+        no arguments returns a shallow copy bound to the same context.
+        """
+        return SettingsAccessor(
+            self._svc,
+            self._registry,
+            user_id=self._user_id if isinstance(user_id, _Unset) else user_id,
+            tenant_id=self._tenant_id if isinstance(tenant_id, _Unset) else tenant_id,
+        )
+
+    # ── Typed reads ─────────────────────────────────────────────────
+
+    async def get(self, key: str, default: str | None = None) -> str | None:
+        """Resolve a key as a string, walking USER > TENANT > SYSTEM.
+
+        Falls back to the explicit ``default`` argument, then the
+        registered default in ``SettingsRegistry`` if present.
+        """
+        value = await self._svc.get_resolved_value(
+            key, user_id=self._user_id, tenant_id=self._tenant_id
+        )
+        if value is not None:
+            return value
+        if default is not None:
+            return default
+        if self._registry is not None:
+            definition = self._registry.get(key)
+            if definition is not None:
+                return definition.default
+        return None
+
+    async def get_str(self, key: str, default: str = "") -> str:
+        value = await self.get(key)
+        return value if value is not None else default
+
+    async def get_bool(self, key: str, default: bool = False) -> bool:
+        raw = await self.get(key)
+        return default if raw is None else _cast_bool(raw, default)
+
+    async def get_int(self, key: str, default: int = 0) -> int:
+        raw = await self.get(key)
+        return default if raw is None else _cast_int(raw, default)
+
+    async def get_float(self, key: str, default: float = 0.0) -> float:
+        raw = await self.get(key)
+        return default if raw is None else _cast_float(raw, default)
+
+    async def get_json(self, key: str, default: Any = None) -> Any:
+        raw = await self.get(key)
+        return default if raw is None else _cast_json(raw, default)
+
+    async def get_typed(self, key: str, default: Any = None) -> Any:
+        """Resolve a key and cast based on the stored ``value_type``.
+
+        Dispatches by the declared type of the row that wins resolution;
+        falls back to the raw string for ``STRING`` or when no row exists.
+        Useful for generic admin views that don't know each key's type at
+        compile time.
+        """
+        out = await self._svc.resolve(key, user_id=self._user_id, tenant_id=self._tenant_id)
+        if out is None:
+            return default
+        caster = _CASTERS.get(out.value_type)
+        return out.value if caster is None else caster(out.value, default)
+
+    # ── Writes ──────────────────────────────────────────────────────
+
+    async def set_system(
+        self,
+        key: str,
+        value: str,
+        value_type: SettingValueType | None = None,
+        description: str | None = None,
+    ) -> SettingOut:
+        return await self._svc.upsert_scoped(
+            SettingScope.SYSTEM,
+            SYSTEM_SCOPE_ID,
+            key,
+            SettingUpsert(value=value, value_type=value_type, description=description),
+        )
+
+    async def set_tenant(
+        self,
+        tenant_id: str,
+        key: str,
+        value: str,
+        value_type: SettingValueType | None = None,
+        description: str | None = None,
+    ) -> SettingOut:
+        return await self._svc.upsert_scoped(
+            SettingScope.TENANT,
+            tenant_id,
+            key,
+            SettingUpsert(value=value, value_type=value_type, description=description),
+        )
+
+    async def set_user(
+        self,
+        user_id: str,
+        key: str,
+        value: str,
+        value_type: SettingValueType | None = None,
+        description: str | None = None,
+    ) -> SettingOut:
+        return await self._svc.upsert_scoped(
+            SettingScope.USER,
+            user_id,
+            key,
+            SettingUpsert(value=value, value_type=value_type, description=description),
+        )

settings/contracts/events.py

@@ -0,0 +1,20 @@
+"""Domain events published by the Settings module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from simple_module_core.events import Event
+
+
+@dataclass
+class SettingsReloaded(Event):
+    """Fired after a module's BaseSettings has been reloaded from the DB.
+
+    Subscribers that cached stateful handles built from settings (SMTP client,
+    Celery app config, middleware) can rebuild when ``package`` matches their
+    own.
+    """
+
+    package: str
+    changed: tuple[str, ...]