simple-module-settings 0.0.34__tar.gz → 0.0.36__tar.gz

{simple_module_settings-0.0.34 → simple_module_settings-0.0.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_settings
-Version: 0.0.34
+Version: 0.0.36
 Summary: Runtime settings UI — modules plug their own settings panels into a shared admin view
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -21,9 +21,9 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: simple-module-core==0.0.34
-Requires-Dist: simple-module-db==0.0.34
-Requires-Dist: simple-module-hosting==0.0.34
+Requires-Dist: simple-module-core==0.0.36
+Requires-Dist: simple-module-db==0.0.36
+Requires-Dist: simple-module-hosting==0.0.36
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 

{simple_module_settings-0.0.34 → simple_module_settings-0.0.36}/package.json

@@ -6,13 +6,13 @@
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@inertiajs/react": "^2.0.0",
+    "@inertiajs/react": "^3.7.0",
     "@simple-module-py/ui": "*"
   },
   "devDependencies": {
     "@simple-module-py/tsconfig": "*"
   },
   "dependencies": {
-    "sonner": "^2.0.7"
+    "sonner": "^2.0.8"
   }
 }

{simple_module_settings-0.0.34 → simple_module_settings-0.0.36}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_settings"
-version = "0.0.34"
+version = "0.0.36"
 description = "Runtime settings UI — modules plug their own settings panels into a shared admin view"
 readme = "README.md"
 license = "MIT"
@@ -21,9 +21,9 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "simple_module_core==0.0.34",
-    "simple_module_db==0.0.34",
-    "simple_module_hosting==0.0.34",
+    "simple_module_core==0.0.36",
+    "simple_module_db==0.0.36",
+    "simple_module_hosting==0.0.36",
     "typer>=0.12",
 ]
 

simple_module_settings-0.0.36/settings/_announce.py

@@ -0,0 +1,36 @@
+"""Publish a per-(tenant, key) invalidation after a settings write commits.
+
+Kept out of ``service.py`` (and its 300-line budget). See
+``settings.contracts.invalidation`` for the key format.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from simple_module_db.callbacks import register_on_commit
+
+from settings.constants import INVALIDATION_CHANNEL, SCOPE_SYSTEM, SCOPE_TENANT
+from settings.contracts.invalidation import invalidation_key
+
+if TYPE_CHECKING:
+    from simple_module_core.invalidation import InvalidationBus
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+
+def announce(
+    db: AsyncSession, bus: InvalidationBus | None, scope: str, scope_id: str, key: str
+) -> None:
+    """Queue the notice for this session's commit; user-scope writes have no consumer.
+
+    After commit, not inline: a consumer that drops its entry before the row is
+    durable re-reads the *old* value and caches it for a full TTL.
+    """
+    if bus is None or scope not in (SCOPE_SYSTEM, SCOPE_TENANT):
+        return
+    wire_key = invalidation_key(scope_id if scope == SCOPE_TENANT else None, key)
+
+    async def publish() -> None:
+        await bus.publish(INVALIDATION_CHANNEL, key=wire_key)
+
+    register_on_commit(db, publish)

simple_module_settings-0.0.36/settings/_listing.py

@@ -0,0 +1,121 @@
+"""Read-side listing queries of :class:`SettingService`, split out for size."""
+
+from __future__ import annotations
+
+from simple_module_db import LIKE_ESCAPE_CHAR, like_contains_pattern
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from settings._row_masking import out
+from settings.constants import (
+    ALL_SCOPES,
+    DEFAULT_PER_PAGE,
+    SCOPE_ALL,
+    SYSTEM_SCOPE_ID,
+)
+from settings.contracts.schemas import SettingOut, SettingScope
+from settings.models import Setting
+
+
+class SettingListing:
+    """Mixin: the ``list_*`` / ``count_by_scope`` queries. Needs ``self.db``."""
+
+    db: AsyncSession
+
+    # ── Listing ─────────────────────────────────────────────────────
+
+    async def list_all(self) -> list[SettingOut]:
+        result = await self.db.execute(
+            select(Setting).order_by(Setting.scope, Setting.scope_id, Setting.key)
+        )
+        return [out(row) for row in result.scalars()]
+
+    async def list_filtered(
+        self,
+        scope: SettingScope | None = None,
+        q: str | None = None,
+        page: int = 1,
+        per_page: int = DEFAULT_PER_PAGE,
+    ) -> tuple[list[SettingOut], int]:
+        """One page of rows plus the unpaged total for the same filters.
+
+        The browse screen used to receive every row and filter in the browser,
+        which made the payload, the render and find-in-page all scale with the
+        whole table instead of with what was asked for. ``q`` matches the key
+        only — the search box says "Search keys…", and quietly matching values
+        would surface rows whose key has nothing to do with the query.
+        """
+        conditions = self._filter_conditions(scope, q)
+        total = await self.db.scalar(select(func.count()).select_from(Setting).where(*conditions))
+        stmt = (
+            select(Setting)
+            .where(*conditions)
+            .order_by(Setting.scope, Setting.scope_id, Setting.key)
+            .offset(max(page - 1, 0) * per_page)
+            .limit(per_page)
+        )
+        result = await self.db.execute(stmt)
+        return [out(row) for row in result.scalars()], int(total or 0)
+
+    async def count_by_scope(self, q: str | None = None) -> dict[str, int]:
+        """Per-scope tallies for the filter tabs, plus ``all``.
+
+        Every scope is named even at zero: a tab that disappears when its count
+        drops to nothing moves the other tabs under the cursor mid-search.
+        The scope filter itself is deliberately not applied — the tabs describe
+        what each of them *would* show, so selecting one must not zero the rest.
+        """
+        conditions = self._filter_conditions(None, q)
+        stmt = select(Setting.scope, func.count()).where(*conditions).group_by(Setting.scope)
+        result = await self.db.execute(stmt)
+        tallies = {str(scope): int(count) for scope, count in result.all()}
+        counts = {name: tallies.get(name, 0) for name in ALL_SCOPES}
+        return {SCOPE_ALL: sum(counts.values()), **counts}
+
+    @staticmethod
+    def _filter_conditions(scope: SettingScope | None, q: str | None) -> list:
+        conditions = []
+        if scope is not None:
+            conditions.append(Setting.scope == scope.value)
+        needle = (q or "").strip()
+        if needle:
+            # Setting keys are full of underscores, and `_` is a LIKE wildcard:
+            # unescaped, a search for "smtp_host" also matches "smtpXhost", and
+            # a stray "%" matches the entire table. ``ilike`` is emulated by
+            # SQLAlchemy on SQLite (lower() on both sides), so one expression
+            # is case-insensitive on both databases.
+            conditions.append(
+                Setting.key.ilike(like_contains_pattern(needle), escape=LIKE_ESCAPE_CHAR)
+            )
+        return conditions
+
+    async def list_by_scope(
+        self, scope: SettingScope, scope_id: str = SYSTEM_SCOPE_ID
+    ) -> list[SettingOut]:
+        result = await self.db.execute(self._scope_stmt(scope, scope_id))
+        return [out(row) for row in result.scalars()]
+
+    async def list_by_scope_unmasked(
+        self, scope: SettingScope, scope_id: str = SYSTEM_SCOPE_ID
+    ) -> list[SettingOut]:
+        """The same rows with their real values, for code that *applies* them.
+
+        The masking in :func:`_out` is for the screens. Hydration is not a
+        screen: ``SettingsStore`` feeds these values back into the live module
+        settings objects at boot, so a masked read writes a row of dots over the
+        real secret — a mailer that cannot authenticate, and a
+        ``reset_password_token_secret`` that no longer verifies the tokens it
+        signed. This is the one read that must see through the mask, and it is
+        spelled out rather than reached by passing a flag so that every caller
+        of it is one grep away.
+        """
+        result = await self.db.execute(self._scope_stmt(scope, scope_id))
+        return [SettingOut.model_validate(row) for row in result.scalars()]
+
+    @staticmethod
+    def _scope_stmt(scope: SettingScope, scope_id: str):
+        return (
+            select(Setting)
+            .where(Setting.scope == scope.value, Setting.scope_id == scope_id)
+            .order_by(Setting.key)
+        )

simple_module_settings-0.0.36/settings/_managed_keys.py

@@ -0,0 +1,59 @@
+"""Rows of a key set by upload are not deleted by a bare row delete.
+
+A key declaring ``SettingDefinition.clear_via`` is a file the owner's upload
+route stores and reaps. Deleting the row any other way leaves the stored file
+behind, so :meth:`SettingService.delete` / ``delete_scoped`` refuse it with
+:class:`ManagedKeyError` **for every scope** — the rule lives in the service so
+a route (or a module calling the service directly) cannot forget it.
+
+Two ways through, both deliberate:
+
+* the owner passes ``as_owner=True`` after taking responsibility for the file
+  (branding's clear routes reap it);
+* a TENANT row whose tenant no longer exists has no live owner left to clear
+  it, so a platform operator may delete it by hand. SYSTEM and USER rows get no
+  such exception: a SYSTEM row always has a live owner (the platform's own
+  upload route), and a USER row of a managed key is cleared through the owner
+  too. The guard is only as wide as the registry the service was built with;
+  a service built without one (``SettingService(db)``) guards nothing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from settings.constants import ERR_MANAGED_KEY_DELETE
+from settings.contracts.registry import SettingsRegistry, clear_route
+from settings.contracts.schemas import SettingScope
+
+TenantIsLive = Callable[[str], Awaitable[bool]]
+
+
+class ManagedKeyError(Exception):
+    """The key is cleared through ``clear_via``, not by deleting its row."""
+
+    def __init__(self, key: str, clear_via: str) -> None:
+        self.key = key
+        self.clear_via = clear_via
+        super().__init__(ERR_MANAGED_KEY_DELETE.format(clear_via=clear_via))
+
+
+async def ensure_deletable(
+    registry: SettingsRegistry | None,
+    tenant_is_live: TenantIsLive | None,
+    scope: str,
+    scope_id: str,
+    key: str,
+) -> None:
+    """Raise :class:`ManagedKeyError` unless the row may be deleted generically."""
+    definition = registry.get(key) if registry is not None else None
+    if definition is None or not definition.clear_via:
+        return
+    orphaned = (
+        scope == SettingScope.TENANT.value
+        and tenant_is_live is not None
+        and not await tenant_is_live(scope_id)
+    )
+    if orphaned:
+        return
+    raise ManagedKeyError(key, clear_route(definition, scope))

{simple_module_settings-0.0.34 → simple_module_settings-0.0.36}/settings/_module_settings_props.py

@@ -9,9 +9,10 @@ from __future__ import annotations
 
 from typing import Any
 
+from fastapi import FastAPI
 from fastapi.encoders import jsonable_encoder
 
-from settings._module_settings import ModuleSettingsView
+from settings._module_settings import ModuleSettingsView, _package_of
 
 
 def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
@@ -54,3 +55,24 @@ def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
         }
         for v in views
     ]
+
+
+def testable_packages(app: FastAPI) -> dict[str, list[str]]:
+    """Package -> the names of the health checks its module registered.
+
+    "Test connection" is just that module's health checks run on demand —
+    reusing the registry means settings never learns what an SMTP or an S3
+    connection is. The names come back with the packages so the button can say
+    what it is about to dial ("Test mailer connection") instead of the useless
+    "Test connection" a bare package list can produce.
+    """
+    checks_by_owner: dict[str, list[str]] = {}
+    for check in app.state.sm.health_registry.all_checks:
+        if check.module:
+            checks_by_owner.setdefault(check.module, []).append(check.name)
+
+    return {
+        _package_of(mod): sorted(checks_by_owner[mod.meta.name])
+        for mod in getattr(app.state.sm, "modules", ())
+        if mod.meta.name in checks_by_owner
+    }

simple_module_settings-0.0.36/settings/_unique_write.py

@@ -0,0 +1,29 @@
+"""Race-safe inserts for the (scope, scope_id, key) unique key.
+
+A read-then-insert cannot be made safe by reading harder: two requests can both
+see "no row" and both insert. The unique constraint is the arbiter, so the
+insert runs in a savepoint — a loser's ``IntegrityError`` rolls back only the
+savepoint, leaving the request's transaction (and its session) usable.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from settings.models import Setting
+
+
+class DuplicateSettingError(Exception):
+    """A row with this (scope, scope_id, key) already exists."""
+
+
+async def insert_if_free(db: AsyncSession, entity: Setting) -> bool:
+    """Insert ``entity``; ``False`` when its (scope, scope_id, key) is already taken."""
+    try:
+        async with db.begin_nested():
+            db.add(entity)
+            await db.flush()
+    except IntegrityError:
+        return False
+    return True

{simple_module_settings-0.0.34 → simple_module_settings-0.0.36}/settings/cli.py

@@ -9,9 +9,11 @@ from __future__ import annotations
 
 import asyncio
 import os
+from collections.abc import Mapping
 
 import typer
 from fastapi import FastAPI
+from simple_module_core.dotenv import find_env_file, parse_dotenv
 
 from settings.constants import MODULE_PACKAGE
 from settings.env_vars import env_prefix_for
@@ -21,14 +23,24 @@ from settings.store import SettingsStore
 app = typer.Typer(help="Settings module administration.", no_args_is_help=True)
 
 
-async def import_from_env_impl(app_inst: FastAPI, store: SettingsStore) -> int:
-    """Write a SYSTEM override for every ``SM_<PREFIX>_<FIELD>`` env var set."""
+async def import_from_env_impl(
+    app_inst: FastAPI,
+    store: SettingsStore,
+    environ: Mapping[str, str] | None = None,
+) -> int:
+    """Write a SYSTEM override for every ``SM_<PREFIX>_<FIELD>`` var set.
+
+    Default source is the project ``.env`` overlaid by the process environment
+    (real env wins). ``os.environ`` is never mutated.
+    """
+    if environ is None:
+        environ = {**parse_dotenv(find_env_file()), **os.environ}
     registry = getattr(app_inst.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()}")
+            raw = environ.get(f"{prefix}{field_name.upper()}")
             if raw is None:
                 continue
             vtype = value_type_for_field(cls, field_name)
@@ -56,6 +68,11 @@ def import_from_env() -> None:
             n = await import_from_env_impl(fastapi_app, store)
             await session.commit()
             typer.echo(f"Imported {n} override(s) from environment.")
+            if n == 0 and find_env_file().is_file():
+                typer.echo(
+                    "Hint: variables must be named SM_<MODULE>_<FIELD> "
+                    "(e.g. SM_USERS_SMTP_PORT); none in the environment or .env matched."
+                )
         return 0
 
     raise typer.Exit(code=asyncio.run(run()))

{simple_module_settings-0.0.34 → simple_module_settings-0.0.36}/settings/constants.py

@@ -70,6 +70,11 @@ 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}"
+# The active tenant's own overrides (#382). The tenant comes from
+# ``request.state.tenant_id`` — never from the URL — so "current" is a literal
+# segment, registered ahead of ``API_TENANT_PATH`` so it is not read as an id.
+API_TENANT_CURRENT_PATH: Final = "/tenant/current"
+API_TENANT_CURRENT_KEY_PATH: Final = "/tenant/current/{key}"
 
 # ── Menu ─────────────────────────────────────────────────────────────
 MENU_LABEL: Final = MODULE_NAME
@@ -85,7 +90,17 @@ 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)
+# Edit the *active* tenant's overrides of ``tenant_overridable`` keys — and
+# nothing else. Mapped onto ``tenant:owner`` / ``tenant:admin``; the four
+# above stay platform-operator permissions (system scope, any tenant's scope).
+PERM_TENANT_EDIT: Final = "settings.tenant.edit"
+ALL_PERMISSIONS: Final = (PERM_VIEW, PERM_CREATE, PERM_EDIT, PERM_DELETE, PERM_TENANT_EDIT)
+
+# ── Cache invalidation ───────────────────────────────────────────────
+# Published (after commit) for every SYSTEM / TENANT write, keyed per
+# (tenant, key) — see ``settings.contracts.invalidation``. Settings caches
+# nothing itself; consumers holding per-tenant resolved values subscribe.
+INVALIDATION_CHANNEL: Final = "settings.values"
 
 # ── Database ─────────────────────────────────────────────────────────
 DB_SCHEMA: Final = MODULE_PACKAGE
@@ -130,16 +145,23 @@ MAX_PER_PAGE: Final = 200
 # ── User-facing error messages ───────────────────────────────────────
 ERR_SETTING_NOT_FOUND: Final = "Setting not found"
 ERR_KEY_ALREADY_EXISTS: Final = "Setting key already exists"
+ERR_SETTING_EXISTS: Final = "A setting with this scope and 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"
+ERR_UNKNOWN_TENANT: Final = "Unknown tenant"
+ERR_NO_ACTIVE_TENANT: Final = "No active organisation for this request"
+ERR_MANAGED_KEY_DELETE: Final = "This setting is managed elsewhere; clear it at {clear_via}"
+ERR_NOT_TENANT_OVERRIDABLE: Final = "This setting cannot be changed per organisation"
 
 # ── HTTP ─────────────────────────────────────────────────────────────
 STATUS_CREATED: Final = 201
 STATUS_NO_CONTENT: Final = 204
+STATUS_FORBIDDEN: Final = 403
 STATUS_NOT_FOUND: Final = 404
 STATUS_CONFLICT: Final = 409
+STATUS_UNPROCESSABLE: Final = 422
 
 # ── Query parameter names ────────────────────────────────────────────
 QP_USER_ID: Final = "user_id"

{simple_module_settings-0.0.34 → simple_module_settings-0.0.36}/settings/contracts/__init__.py

@@ -1,7 +1,7 @@
 """Settings contracts — public interface for other modules."""
 
 from settings.contracts.accessor import SettingsAccessor
-from settings.contracts.registry import SettingDefinition, SettingsRegistry
+from settings.contracts.registry import SettingDefinition, SettingsRegistry, clear_route
 from settings.contracts.schemas import (
     SettingCreate,
     SettingOut,
@@ -21,4 +21,5 @@ __all__ = [
     "SettingValueType",
     "SettingsAccessor",
     "SettingsRegistry",
+    "clear_route",
 ]

simple_module_settings-0.0.36/settings/contracts/invalidation.py

@@ -0,0 +1,39 @@
+"""Per-(tenant, key) invalidation notices for settings writes (#382).
+
+``settings`` keeps no cache of its own, but consumers resolving a value per
+tenant do (branding's per-tenant theme). Every SYSTEM / TENANT write publishes
+on :data:`INVALIDATION_CHANNEL` after commit, with the key built here:
+
+* ``"<tenant_id>|<key>"`` — one tenant's override of ``key`` changed;
+* ``"|<key>"`` — the system value changed, so every tenant's view of ``key``
+  may have (tenants without an override inherit it).
+
+``|`` cannot appear in a tenant id (``simple_module_db.TENANT_ID_PATTERN``), so
+the first one always separates the two halves. Handlers may only forget.
+"""
+
+from __future__ import annotations
+
+from settings.constants import INVALIDATION_CHANNEL
+
+_SEP = "|"
+
+
+def invalidation_key(tenant_id: str | None, key: str) -> str:
+    """The wire key for a write of ``key`` at ``tenant_id`` (``None`` = system)."""
+    return f"{tenant_id or ''}{_SEP}{key}"
+
+
+def parse_invalidation_key(raw: str | None) -> tuple[str | None, str | None]:
+    """``(tenant_id, key)``; ``tenant_id`` is ``None`` for a system write.
+
+    ``(None, None)`` for a whole-channel clear (``raw is None``) or a key this
+    module did not build — both mean "forget everything".
+    """
+    if raw is None or _SEP not in raw:
+        return None, None
+    tenant_id, _, key = raw.partition(_SEP)
+    return (tenant_id or None), key
+
+
+__all__ = ["INVALIDATION_CHANNEL", "invalidation_key", "parse_invalidation_key"]

simple_module_settings-0.0.36/settings/contracts/registry.py

@@ -0,0 +1,121 @@
+"""Registry of declared setting keys — lets modules advertise the keys they
+read so admins can see every knob (and its default) in one place.
+
+Usage from a consumer module's ``on_startup`` hook:
+
+    def on_startup(self, app):
+        app.state.settings.registry.add(
+            SettingDefinition(
+                key="orders.checkout.require_terms",
+                default="true",
+                description="Show the terms-and-conditions checkbox on checkout.",
+            )
+        )
+
+The registry doesn't write anything to the database — it only records
+intent. ``SettingsAccessor.get`` falls back to the registered default when
+no row exists at any scope. ``get_bool`` / ``get_int`` / ``get_json`` cast
+the stored string representation on the way out.
+
+API mirrors the other framework registries (MenuRegistry / PermissionRegistry
+/ FeatureFlagRegistry): ``add(definition)`` + ``all_definitions``. Unlike
+FeatureFlagRegistry, duplicate keys raise — settings carry defaults and a
+second registration almost always means two owners contended for the same key.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from settings.constants import ERR_KEY_ALREADY_EXISTS
+from settings.contracts.schemas import SettingScope, SettingValueType
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+TenantValueCheck = Callable[["Request", str, str], Awaitable[None]]
+"""``async (request, tenant_id, value)`` run before a TENANT-scope write.
+
+Raise ``ValueError`` to reject the value (422) or ``LookupError`` when it names
+something the tenant does not have (404) — e.g. a file id owned by another
+tenant. ``tenant_id`` is the scope being written, which on the platform routes
+is not the caller's own active tenant."""
+
+
+@dataclass(frozen=True, slots=True)
+class SettingDefinition:
+    """Declared metadata for a setting key.
+
+    ``tenant_overridable`` opts the key into tenant self-service (#382): a
+    tenant owner/admin may write it for their *own* active tenant through
+    ``/api/settings/tenant/current/{key}``. Keys without it are writable at
+    tenant scope only by platform operators (``settings.edit``). ``check``
+    vets every TENANT-scope write of the key, from either surface.
+    ``upload_url`` marks a key whose value is a file id set by uploading: the
+    tenant settings page POSTs the file there and DELETEs it to clear, instead
+    of offering a text box for an opaque id. ``description_key`` is the i18n
+    key the tenant settings page translates ``description`` with (the English
+    ``description`` stays the fallback when the key is missing or unset).
+    ``clear_via`` names the route that owns clearing the key (e.g. an upload
+    route that also reaps the stored file): the generic DELETE routes answer
+    422 pointing there while the tenant exists. A platform operator may still
+    delete the row left behind by a tenant that no longer exists. A key whose
+    system and tenant rows are cleared through different routes passes a
+    ``{SettingScope: route}`` mapping; read it with :func:`clear_route`.
+    """
+
+    key: str
+    default: str = ""
+    description: str = ""
+    scope: SettingScope = SettingScope.SYSTEM
+    value_type: SettingValueType = SettingValueType.STRING
+    tenant_overridable: bool = False
+    check: TenantValueCheck | None = field(default=None, compare=False)
+    clear_via: str | Mapping[SettingScope, str] = ""
+    upload_url: str = ""
+    description_key: str = ""
+
+
+def clear_route(definition: SettingDefinition, scope: SettingScope | str) -> str:
+    """The route that clears ``definition`` at ``scope`` ("" if unmanaged).
+
+    A scope the mapping does not name falls back to its first route, so the
+    refusal still points somewhere rather than at nothing.
+    """
+    via = definition.clear_via
+    if isinstance(via, str):
+        return via
+    if not via:
+        return ""
+    return via.get(SettingScope(scope)) or next(iter(via.values()))
+
+
+@dataclass(slots=True)
+class SettingsRegistry:
+    """In-memory registry of declared setting keys. Populated at module boot
+    so admins (and other modules) can discover every knob the app exposes.
+    """
+
+    _defs: dict[str, SettingDefinition] = field(default_factory=dict)
+
+    def add(self, definition: SettingDefinition) -> None:
+        if definition.key in self._defs:
+            raise ValueError(f"{ERR_KEY_ALREADY_EXISTS}: {definition.key!r}")
+        self._defs[definition.key] = definition
+
+    def get(self, key: str) -> SettingDefinition | None:
+        return self._defs.get(key)
+
+    @property
+    def all_definitions(self) -> list[SettingDefinition]:
+        return list(self._defs.values())
+
+    @property
+    def tenant_overridable(self) -> list[SettingDefinition]:
+        """Definitions a tenant may override for itself, sorted by key."""
+        return sorted((d for d in self._defs.values() if d.tenant_overridable), key=lambda d: d.key)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._defs

{simple_module_settings-0.0.34 → simple_module_settings-0.0.36}/settings/deps.py

@@ -18,12 +18,21 @@ from settings.constants import MODULE_PACKAGE
 from settings.contracts.accessor import SettingsAccessor
 from settings.contracts.registry import SettingsRegistry
 from settings.service import SettingService
+from settings.tenant_scope import is_known_tenant, registry_of
 
 
 async def get_setting_service(
+    request: Request,
     db: AsyncSession = Depends(get_db),
 ) -> SettingService:
-    return SettingService(db)
+    bus = getattr(getattr(request.app.state, "sm", None), "invalidation", None)
+
+    async def tenant_is_live(tenant_id: str) -> bool:
+        return await is_known_tenant(request, tenant_id)
+
+    return SettingService(
+        db, invalidation=bus, registry=registry_of(request), tenant_is_live=tenant_is_live
+    )
 
 
 def get_settings_registry(request: Request) -> SettingsRegistry: