simple-module-settings 0.0.35__tar.gz → 0.0.37__tar.gz

{simple_module_settings-0.0.35 → simple_module_settings-0.0.37}/.gitignore

@@ -64,3 +64,4 @@ host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
 .verify/
+/openapi.json

{simple_module_settings-0.0.35 → simple_module_settings-0.0.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_settings
-Version: 0.0.35
+Version: 0.0.37
 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.35
-Requires-Dist: simple-module-db==0.0.35
-Requires-Dist: simple-module-hosting==0.0.35
+Requires-Dist: simple-module-core==0.0.37
+Requires-Dist: simple-module-db==0.0.37
+Requires-Dist: simple-module-hosting==0.0.37
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 

{simple_module_settings-0.0.35 → simple_module_settings-0.0.37}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_settings"
-version = "0.0.35"
+version = "0.0.37"
 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.35",
-    "simple_module_db==0.0.35",
-    "simple_module_hosting==0.0.35",
+    "simple_module_core==0.0.37",
+    "simple_module_db==0.0.37",
+    "simple_module_hosting==0.0.37",
     "typer>=0.12",
 ]
 

simple_module_settings-0.0.37/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.37/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.37/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.35 → simple_module_settings-0.0.37}/settings/_module_settings.py

@@ -19,6 +19,7 @@ from settings._field_meta import choices_for, env_readable_var, resolve_default
 from settings._secrets import (  # noqa: F401
     _NEVER_SECRET_TYPES,
     SECRET_MASK,
+    annotation_holds_secret,
     conceals_secret,
     embeds_credential,
     is_named_secret,
@@ -26,7 +27,7 @@ from settings._secrets import (  # noqa: F401
     mask,
 )
 from settings.env_vars import env_prefix_for
-from settings.hydrate import value_type_for_field
+from settings.hydrate import env_supplied_fields, input_type_for_field, value_type_for_field
 from settings.service import SettingService
 
 
@@ -71,22 +72,28 @@ class ModuleSettingField:
     """
     choices: list[str] | None = None
     """Closed set of accepted values, or ``None`` when the field is free text."""
+    input_type: str = ""
+    """Editor control: ``type`` with an ``X | None`` unwrapped to ``X``."""
+    nullable: bool = False
+    """``None`` is a valid value; the editor sends it for an empty input."""
 
     @property
     def source(self) -> str:
         """Where the live value came from: ``db``, ``env`` or ``default``.
 
-        Mirrors the precedence in ``hydrate_settings``: DB overrides are passed
-        to the constructor explicitly, so they beat anything pydantic reads for
-        fields left unset, which in turn beats the field default. ``env`` only
-        appears for settings classes that actually declare an ``env_prefix``;
-        see :attr:`env_set`. Showing this is the difference between "why is
-        this not taking effect" being a five-minute question and an afternoon.
+        Mirrors the precedence in ``hydrate_settings``: env → DB → default
+        (GH #486). A stored override for a field the environment sets is
+        ignored, so ``env`` wins even when ``db_override`` is true. ``env`` only
+        appears for settings classes that declare an ``env_prefix`` (or name
+        the field in ``env_seeded_fields``) — the same rule
+        ``hydrate.env_supplied_fields`` applies; see :attr:`env_set`. Showing
+        this is the difference between "why is this not taking effect" being a
+        five-minute question and an afternoon.
         """
-        if self.db_override:
-            return "db"
         if self.env_set:
             return "env"
+        if self.db_override:
+            return "db"
         return "default"
 
 
@@ -126,28 +133,41 @@ def _field_view(
     settings: BaseSettings,
     prefix: str,
     overridden: frozenset[str] = frozenset(),
+    env_supplied: frozenset[str] | None = None,
 ) -> ModuleSettingField:
     cls = type(settings)
+    if env_supplied is None:
+        env_supplied = env_supplied_fields(cls)
     info = cls.model_fields[name]
     raw_value = getattr(settings, name)
     value_type = value_type_for_field(cls, name)
+    input_type, nullable = input_type_for_field(cls, name)
     named_secret = is_named_secret(name, value_type)
     extra = info.json_schema_extra if isinstance(info.json_schema_extra, dict) else {}
     default = resolve_default(info)
     env_var = f"{prefix}{name.upper()}"
     live_env_var = env_readable_var(settings, name)
-    env_set = live_env_var is not None and live_env_var in os.environ
-    # ``live_env_var`` is not None whenever env_set is True, but the narrowing
-    # is spelled out so a future edit cannot turn this into ``os.environ[None]``.
-    raw_env = os.environ[live_env_var] if env_set and live_env_var is not None else None
+    # The same answer ``build_settings`` acts on (GH #486), so a value supplied
+    # by the class's ``.env``, a secrets file or an alias is labelled "env"
+    # here exactly when hydration lets it beat a stored override.
+    env_set = name in env_supplied
+    raw_env = os.environ.get(live_env_var) if env_set and live_env_var is not None else None
+
+    # Declared as ``SecretStr`` (also inside ``X | None`` or a container):
+    # masked whatever the field is called, since the store holds it in clear.
+    typed_secret = annotation_holds_secret(info.annotation)
 
     def hidden(value: Any) -> bool:
-        return conceals_secret(name, value, value_type)
+        return typed_secret or conceals_secret(name, value, value_type)
 
     # ``is_secret`` drives the editor's input type and the "reveal" affordance,
     # so it has to be true when *any* of the three readings is being hidden —
     # otherwise the form offers to edit a value it is showing as dots.
-    secret = named_secret or any(embeds_credential(v) for v in (raw_value, default, raw_env))
+    secret = (
+        typed_secret
+        or named_secret
+        or any(embeds_credential(v) for v in (raw_value, default, raw_env))
+    )
     return ModuleSettingField(
         name=name,
         env_var=env_var,
@@ -166,6 +186,8 @@ def _field_view(
         # Resolved value panel's env row into a row of dots for every key.
         env_value=(mask(raw_env) if hidden(raw_env) else raw_env) if raw_env is not None else None,
         choices=choices_for(info),
+        input_type=input_type,
+        nullable=nullable,
     )
 
 
@@ -228,8 +250,10 @@ def _build_view(
 ) -> ModuleSettingsView:
     prefix = env_prefix_for(package)
     overridden = (overrides or {}).get(package, frozenset())
+    from_env = env_supplied_fields(type(settings))
     fields = [
-        _field_view(name, settings, prefix, overridden) for name in type(settings).model_fields
+        _field_view(name, settings, prefix, overridden, from_env)
+        for name in type(settings).model_fields
     ]
     return ModuleSettingsView(
         module_name=module_name,

{simple_module_settings-0.0.35 → simple_module_settings-0.0.37}/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]]:
@@ -48,9 +49,32 @@ def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
                     # Turns a pattern-constrained string into a select rather
                     # than a text box whose only feedback on a typo is a 422.
                     "choices": f.choices,
+                    "input_type": f.input_type or f.type,
+                    "nullable": f.nullable,
                 }
                 for f in v.fields
             ],
         }
         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.35 → simple_module_settings-0.0.37}/settings/_secrets.py

@@ -9,9 +9,11 @@ be reasoned about without a FastAPI app in scope. Re-exported from
 from __future__ import annotations
 
 import re
-from typing import Any
+from typing import Any, get_args, get_origin
 from urllib.parse import urlsplit
 
+from pydantic import BaseModel, SecretBytes, SecretStr
+
 # 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.
@@ -25,6 +27,41 @@ SECRET_MASK = "••••••••"
 _NEVER_SECRET_TYPES = frozenset({"int", "float", "bool"})
 
 
+# ``<package>.<field>`` keys whose declared type holds a ``SecretStr`` /
+# ``SecretBytes``. Filled by ``ModuleSettingsRegistry.register`` so the row
+# browser, tenant view and known-keys list — which see only a key and a stored
+# string — mask them too. Only ever grows; keys are package-qualified.
+_TYPED_SECRET_KEYS: set[str] = set()
+
+
+def annotation_holds_secret(annotation: Any, _seen: frozenset[type] = frozenset()) -> bool:
+    """True if a ``SecretStr``/``SecretBytes`` sits anywhere in ``annotation``.
+
+    Walks unions (``SecretStr | None``), containers (``dict[str, SecretStr]``)
+    and nested models. Since json fields store the real secret (GH #487
+    review), a field typed this way must be masked whatever its name.
+    """
+    if get_origin(annotation) is None and isinstance(annotation, type):
+        if issubclass(annotation, SecretStr | SecretBytes):
+            return True
+        if issubclass(annotation, BaseModel) and annotation not in _seen:
+            seen = _seen | {annotation}
+            return any(
+                annotation_holds_secret(f.annotation, seen)
+                for f in annotation.model_fields.values()
+            )
+    return any(annotation_holds_secret(arg, _seen) for arg in get_args(annotation))
+
+
+def register_typed_secrets(package: str, cls: type[BaseModel]) -> None:
+    """Record which of ``cls``'s fields are secrets by type."""
+    _TYPED_SECRET_KEYS.update(
+        f"{package}.{name}"
+        for name, info in cls.model_fields.items()
+        if annotation_holds_secret(info.annotation)
+    )
+
+
 def is_secret_field(name: str) -> bool:
     """True if a field name suggests it holds credential material."""
     return bool(_SECRET_PATTERNS.search(name))
@@ -49,11 +86,14 @@ def is_named_secret(name: str, value_type: str | None = None) -> bool:
 def conceals_secret(name: str, value: Any, value_type: str | None = None) -> bool:
     """True if this name/value pair must be masked on the way out.
 
-    The one rule every read path shares: mask per *value* as well as per name,
+    The one rule every read path shares: mask per *type* (a registered
+    ``<package>.<field>`` declared as a secret), per *value* and per name,
     so a DSN carrying a password is hidden even on a field called
     ``broker_url``, while that field's password-free default is still shown.
     """
-    return is_named_secret(name, value_type) or embeds_credential(value)
+    return (
+        name in _TYPED_SECRET_KEYS or is_named_secret(name, value_type) or embeds_credential(value)
+    )
 
 
 def embeds_credential(value: Any) -> bool:

simple_module_settings-0.0.37/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.35 → simple_module_settings-0.0.37}/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.35 → simple_module_settings-0.0.37}/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.35 → simple_module_settings-0.0.37}/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",
 ]