simple-module-core 0.0.27__tar.gz → 0.0.29__tar.gz

{simple_module_core-0.0.27 → simple_module_core-0.0.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_core
-Version: 0.0.27
+Version: 0.0.29
 Summary: Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python

{simple_module_core-0.0.27 → simple_module_core-0.0.29}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_core"
-version = "0.0.27"
+version = "0.0.29"
 description = "Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events"
 readme = "README.md"
 license = "MIT"

{simple_module_core-0.0.27 → simple_module_core-0.0.29}/simple_module_core/__init__.py

@@ -8,8 +8,11 @@ from simple_module_core.diagnostics import (
     run_diagnostics,
 )
 from simple_module_core.discovery import (
+    DEFAULT_AUTH_PROVIDER,
     discover_modules,
     get_module_package_name,
+    resolve_auth_provider,
+    select_auth_provider,
     topological_sort,
 )
 from simple_module_core.events import Event, EventBus
@@ -39,6 +42,7 @@ from simple_module_core.services import Services
 from simple_module_core.versioning import FRAMEWORK_API_VERSION, check_framework_compatibility
 
 __all__ = [
+    "DEFAULT_AUTH_PROVIDER",
     "FRAMEWORK_API_VERSION",
     "CircularDependencyError",
     "DesignPack",
@@ -77,6 +81,8 @@ __all__ = [
     "is_flag_enabled",
     "print_diagnostics",
     "require_flag",
+    "resolve_auth_provider",
     "run_diagnostics",
+    "select_auth_provider",
     "topological_sort",
 ]

{simple_module_core-0.0.27 → simple_module_core-0.0.29}/simple_module_core/__main__.py

@@ -25,7 +25,12 @@ from simple_module_core.diagnostics import (
     print_diagnostics,
     run_diagnostics,
 )
-from simple_module_core.discovery import discover_modules, topological_sort
+from simple_module_core.discovery import (
+    discover_modules,
+    resolve_auth_provider,
+    select_auth_provider,
+    topological_sort,
+)
 from simple_module_core.dotenv import parse_dotenv
 from simple_module_core.exceptions import InvalidModuleError
 
@@ -100,6 +105,10 @@ def main() -> int:
         print("No modules discovered. Is the project installed (`uv sync --all-packages`)?")
         return 0
 
+    # Mirror the host: only the configured auth provider is active, so doctor
+    # reports on the same module set the app actually boots with.
+    modules = select_auth_provider(modules, resolve_auth_provider())
+
     # Topological sort surfaces CircularDependencyError early.
     modules = topological_sort(modules)
 

{simple_module_core-0.0.27 → simple_module_core-0.0.29}/simple_module_core/discovery.py

@@ -6,6 +6,7 @@ import logging
 from collections.abc import Sequence
 from importlib.metadata import entry_points
 
+from simple_module_core.dotenv import env_str, load_dotenv_into_environ
 from simple_module_core.exceptions import CircularDependencyError, InvalidModuleError
 from simple_module_core.module import ModuleBase, ModuleMeta
 
@@ -13,6 +14,9 @@ logger = logging.getLogger(__name__)
 
 ENTRY_POINT_GROUP = "simple_module"
 
+DEFAULT_AUTH_PROVIDER = "users"
+"""Auth provider activated when several are installed — see select_auth_provider."""
+
 
 def get_module_package_name(module: ModuleBase) -> str:
     """Return the top-level Python package a module instance belongs to.
@@ -121,6 +125,67 @@ def discover_modules(
     return modules
 
 
+def resolve_auth_provider() -> str:
+    """Return the configured auth provider name, honoring ``.env``.
+
+    For tools that run outside the host process (``make doctor``, ``smpy host
+    gen-pages``) and so have no ``BootstrapSettings`` to read from. The host
+    passes ``settings.auth_provider`` to :func:`select_auth_provider` instead.
+    """
+    load_dotenv_into_environ()
+    return env_str("SM_AUTH_PROVIDER", DEFAULT_AUTH_PROVIDER)
+
+
+def select_auth_provider(
+    modules: Sequence[ModuleBase],
+    preferred: str = DEFAULT_AUTH_PROVIDER,
+    *,
+    strict: bool = False,
+) -> list[ModuleBase]:
+    """Drop every auth provider except ``preferred`` when several are installed.
+
+    ``users`` and ``keycloak`` both claim ``app.state.auth.auth_provider``, so
+    only one can be active — that's what SM020 reports. A dev workspace has
+    both installed (``uv sync --all-packages`` installs every member), which
+    would otherwise fail the boot on a fresh clone. Selecting one here keeps
+    the alternative provider installed and testable but inert.
+
+    Nothing is dropped when fewer than two providers are present — a host that
+    installs only ``keycloak`` keeps it whatever ``preferred`` says.
+
+    A ``preferred`` that names none of the installed providers is a
+    misconfiguration (typically a typo). Leaving every provider mounted means
+    two modules write ``app.state.auth.auth_provider`` and the topological
+    order silently decides the winner, so this always warns, and with
+    ``strict`` raises :class:`InvalidModuleError`. Callers in production
+    should pass ``strict=True``: SM020 would catch this, but diagnostics run
+    in development only, so nothing else reports it in a deployed app.
+    """
+    providers = [m for m in modules if getattr(m, "_is_auth_provider", False)]
+    if len(providers) < 2:
+        return list(modules)
+
+    installed = ", ".join(m.meta.name for m in providers)
+    keep = next((m for m in providers if m.meta.name.lower() == preferred.lower()), None)
+    if keep is None:
+        msg = (
+            f"SM_AUTH_PROVIDER={preferred!r} matches none of the installed auth "
+            f"providers ({installed}); all of them stay mounted and the last one "
+            "registered wins"
+        )
+        if strict:
+            raise InvalidModuleError(msg)
+        logger.warning("%s — set it to one of the names above", msg)
+        return list(modules)
+
+    logger.info(
+        "Auth provider '%s' active (SM_AUTH_PROVIDER); skipping also-installed: %s",
+        keep.meta.name,
+        ", ".join(m.meta.name for m in providers if m is not keep),
+    )
+    return [m for m in modules if m is keep or not getattr(m, "_is_auth_provider", False)]
+
+
 def topological_sort(modules: Sequence[ModuleBase]) -> list[ModuleBase]:
     """Sort modules so dependencies come before dependents.
 

{simple_module_core-0.0.27 → simple_module_core-0.0.29}/simple_module_core/i18n.py

@@ -78,7 +78,7 @@ class I18nRegistry:
     def __init__(self, default_locale: str, supported_locales: list[str]) -> None:
         self.default_locale = default_locale
         self.supported_locales = list(supported_locales)
-        self._sources: list[tuple[str, Path]] = []
+        self._sources: list[tuple[str, Path, str]] = []
         self._messages: dict[str, dict[str, str]] = {}
         # Immutable views into ``_messages`` — handed out by ``messages()`` to
         # avoid a per-call dict copy. Rebuilt whenever ``load()`` runs.
@@ -88,15 +88,22 @@ class I18nRegistry:
         # avoids per-request dict copies that used to dominate allocations on the
         # Inertia render path.
         self._message_snapshots: dict[str, dict[str, str]] = {}
+        self._public_snapshots: dict[str, dict[str, str]] = {}
         self._available_locales: tuple[str, ...] = ()
         self._available_locales_list: list[str] = []
         self._empty_view: MappingProxyType[str, str] = MappingProxyType({})
         self._empty_snapshot: dict[str, str] = {}
         self._loaded = False
 
-    def add_source(self, namespace: str, locale_dir: Path) -> None:
-        """Queue a module's locale directory for loading under a namespace."""
-        self._sources.append((namespace, Path(locale_dir)))
+    def add_source(self, namespace: str, locale_dir: Path, *, audience: str = "public") -> None:
+        """Queue a module's locale directory for loading under a namespace.
+
+        ``audience="admin"`` keeps the namespace out of the public snapshot
+        (:meth:`messages_snapshot` with ``include_admin=False``) so catalogs
+        for login-gated UI aren't shipped to anonymous visitors. Server-side
+        lookups (:meth:`messages`) always see every namespace.
+        """
+        self._sources.append((namespace, Path(locale_dir), audience))
 
     def load(self) -> None:
         """Read and flatten all registered JSON files.
@@ -105,8 +112,11 @@ class I18nRegistry:
         warning but do not raise. Malformed JSON raises ValueError.
         """
         self._messages = {locale: {} for locale in self.supported_locales}
+        public_messages: dict[str, dict[str, str]] = {
+            locale: {} for locale in self.supported_locales
+        }
 
-        for namespace, locale_dir in self._sources:
+        for namespace, locale_dir, audience in self._sources:
             for locale in self.supported_locales:
                 path = locale_dir / f"{locale}.json"
                 if not path.is_file():
@@ -124,6 +134,8 @@ class I18nRegistry:
                     raise ValueError(f"{path} must contain a JSON object at the top level")
                 flat = flatten_messages(raw, prefix=namespace)
                 self._messages[locale].update(flat)
+                if audience != "admin":
+                    public_messages[locale].update(flat)
 
         # Cache the derived views now that loading is complete. Downstream
         # (middleware, translator, switcher) reads these on every request.
@@ -131,8 +143,10 @@ class I18nRegistry:
             locale: MappingProxyType(msgs) for locale, msgs in self._messages.items()
         }
         # Plain-dict snapshots for serialization callers. ``dict(msgs)`` runs
-        # once here rather than on every Inertia render.
+        # once here rather than on every Inertia render. The public variant
+        # (admin namespaces excluded) is what anonymous visitors receive.
         self._message_snapshots = {locale: dict(msgs) for locale, msgs in self._messages.items()}
+        self._public_snapshots = public_messages
         self._available_locales = tuple(locale for locale, msgs in self._messages.items() if msgs)
         self._available_locales_list = list(self._available_locales)
         self._loaded = True
@@ -165,7 +179,7 @@ class I18nRegistry:
             return self._empty_view
         return MappingProxyType(raw)
 
-    def messages_snapshot(self, locale: str) -> dict[str, str]:
+    def messages_snapshot(self, locale: str, *, include_admin: bool = True) -> dict[str, str]:
         """Plain-dict snapshot for callers that JSON-serialize the result.
 
         Built once at :meth:`load` time and handed out by reference on every
@@ -173,12 +187,17 @@ class I18nRegistry:
         corrupts subsequent responses. Used by the Inertia shared-props builder
         where it sits on the request hot path; prior to this method,
         ``dict(messages(locale))`` per request was the top own-code allocator.
+
+        ``include_admin=False`` returns the variant without ``audience="admin"``
+        namespaces — what anonymous visitors are served.
         """
-        snapshot = self._message_snapshots.get(locale)
+        pool = self._message_snapshots if include_admin else self._public_snapshots
+        snapshot = pool.get(locale)
         if snapshot is not None:
             return snapshot
         # Fallback for tests that skip ``load()``: synthesize the snapshot on
-        # demand from whatever ``_messages`` holds.
+        # demand from whatever ``_messages`` holds (audience information only
+        # exists for sources that went through ``load()``).
         raw = self._messages.get(locale)
         if raw is None:
             return self._empty_snapshot

{simple_module_core-0.0.27 → simple_module_core-0.0.29}/simple_module_core/module.py

@@ -35,6 +35,15 @@ class ModuleMeta:
     installed ``simple_module_core.FRAMEWORK_API_VERSION`` does not satisfy it.
     When ``None``, no compatibility check is performed (legacy modules).
     """
+    i18n_audience: str = "public"
+    """Who this module's locale catalog is shipped to: ``"public"`` or ``"admin"``.
+
+    ``"public"`` (the default) ships the catalog in every Inertia payload.
+    ``"admin"`` ships it only to authenticated users — declare it on modules
+    whose UI sits entirely behind login (settings, permissions, dashboards) so
+    anonymous visitors don't download admin form labels on every public page.
+    The catalog is always available server-side (``Translator``) either way.
+    """
 
 
 class ModuleBase(ABC):

simple_module_core-0.0.29/tests/test_auth_provider_selection.py

@@ -0,0 +1,133 @@
+"""Tests for select_auth_provider — picking one of several installed providers."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import pytest
+from simple_module_core.discovery import (
+    DEFAULT_AUTH_PROVIDER,
+    resolve_auth_provider,
+    select_auth_provider,
+)
+from simple_module_core.exceptions import InvalidModuleError
+from simple_module_core.module import ModuleBase, ModuleMeta
+
+
+class FakeUsers(ModuleBase):
+    meta = ModuleMeta(name="Users")
+    _is_auth_provider = True
+
+
+class FakeKeycloak(ModuleBase):
+    meta = ModuleMeta(name="Keycloak")
+    _is_auth_provider = True
+
+
+class FakeDashboard(ModuleBase):
+    meta = ModuleMeta(name="Dashboard")
+
+
+def _names(modules):
+    return [m.meta.name for m in modules]
+
+
+class TestSelectAuthProvider:
+    def test_default_keeps_users_and_drops_keycloak(self):
+        """Both installed (the dev workspace) → the default provider wins, no SM020."""
+        result = select_auth_provider([FakeUsers(), FakeKeycloak(), FakeDashboard()])
+        assert _names(result) == ["Users", "Dashboard"]
+
+    def test_preferred_keycloak_drops_users(self):
+        result = select_auth_provider([FakeUsers(), FakeKeycloak()], "keycloak")
+        assert _names(result) == ["Keycloak"]
+
+    def test_match_is_case_insensitive(self):
+        result = select_auth_provider([FakeUsers(), FakeKeycloak()], "KeyCloak")
+        assert _names(result) == ["Keycloak"]
+
+    def test_non_provider_modules_keep_their_order(self):
+        modules = [FakeDashboard(), FakeKeycloak(), FakeUsers()]
+        assert _names(select_auth_provider(modules)) == ["Dashboard", "Users"]
+
+    def test_lone_provider_survives_a_mismatched_preference(self):
+        """A keycloak-only host keeps keycloak even at the default preference."""
+        result = select_auth_provider([FakeKeycloak(), FakeDashboard()], "users")
+        assert _names(result) == ["Keycloak", "Dashboard"]
+
+    def test_no_providers_is_untouched(self):
+        """SM021 territory — nothing to select, and nothing to drop."""
+        assert _names(select_auth_provider([FakeDashboard()])) == ["Dashboard"]
+
+    def test_unknown_preference_keeps_every_provider(self):
+        """Naming a provider that isn't installed must not silently pick one."""
+        result = select_auth_provider([FakeUsers(), FakeKeycloak()], "oidc")
+        assert _names(result) == ["Users", "Keycloak"]
+
+    def test_unknown_preference_warns(self, caplog):
+        """SM020 only runs in development — a typo must not pass in silence."""
+        with caplog.at_level(logging.WARNING, logger="simple_module_core.discovery"):
+            select_auth_provider([FakeUsers(), FakeKeycloak()], "keycloack")
+        warnings = [r for r in caplog.records if r.levelno >= logging.WARNING]
+        assert warnings, "an unrecognised provider name logged nothing"
+        assert "keycloack" in warnings[0].getMessage()
+
+    def test_unknown_preference_raises_when_strict(self):
+        """Production boots strict, where mounting both providers is not viable."""
+        with pytest.raises(InvalidModuleError, match="keycloack"):
+            select_auth_provider([FakeUsers(), FakeKeycloak()], "keycloack", strict=True)
+
+    def test_strict_is_quiet_on_a_valid_selection(self):
+        result = select_auth_provider([FakeUsers(), FakeKeycloak()], "users", strict=True)
+        assert _names(result) == ["Users"]
+
+    def test_strict_ignores_a_mismatch_when_only_one_is_installed(self):
+        """Nothing is ambiguous with a single provider, so strict must not raise."""
+        result = select_auth_provider([FakeKeycloak()], "oidc", strict=True)
+        assert _names(result) == ["Keycloak"]
+
+    def test_selection_is_logged(self, caplog):
+        with caplog.at_level(logging.INFO, logger="simple_module_core.discovery"):
+            select_auth_provider([FakeUsers(), FakeKeycloak()])
+        assert any("Keycloak" in rec.getMessage() for rec in caplog.records)
+
+    def test_input_is_not_mutated(self):
+        modules = [FakeUsers(), FakeKeycloak()]
+        select_auth_provider(modules)
+        assert len(modules) == 2
+
+
+class TestResolveAuthProvider:
+    @pytest.fixture(autouse=True)
+    def _isolated_environ(self, monkeypatch, tmp_path):
+        """Swap in a throwaway ``os.environ``.
+
+        ``resolve_auth_provider`` merges ``.env`` into the real environment via
+        ``setdefault``, which ``monkeypatch.delenv(raising=False)`` can't undo —
+        it records nothing for a key that was already absent. Without this the
+        provider chosen here would leak into every later test in the session.
+        """
+        monkeypatch.setattr(os, "environ", dict(os.environ))
+        monkeypatch.setenv("SM_PROJECT_ROOT", str(tmp_path))
+        monkeypatch.delenv("SM_AUTH_PROVIDER", raising=False)
+
+    def test_defaults_to_users(self):
+        assert resolve_auth_provider() == DEFAULT_AUTH_PROVIDER
+
+    def test_reads_the_env_var(self, monkeypatch):
+        monkeypatch.setenv("SM_AUTH_PROVIDER", "keycloak")
+        assert resolve_auth_provider() == "keycloak"
+
+    def test_blank_falls_back_to_the_default(self, monkeypatch):
+        monkeypatch.setenv("SM_AUTH_PROVIDER", "  ")
+        assert resolve_auth_provider() == DEFAULT_AUTH_PROVIDER
+
+    def test_reads_dotenv_when_env_is_unset(self, tmp_path):
+        (tmp_path / ".env").write_text("SM_AUTH_PROVIDER=keycloak\n", encoding="utf-8")
+        assert resolve_auth_provider() == "keycloak"
+
+    def test_real_environment_wins_over_dotenv(self, monkeypatch, tmp_path):
+        (tmp_path / ".env").write_text("SM_AUTH_PROVIDER=keycloak\n", encoding="utf-8")
+        monkeypatch.setenv("SM_AUTH_PROVIDER", "users")
+        assert resolve_auth_provider() == "users"

{simple_module_core-0.0.27 → simple_module_core-0.0.29}/tests/test_i18n.py

@@ -65,6 +65,29 @@ class TestI18nRegistry:
         reg.load()
         assert sorted(reg.available_locales()) == ["en", "es"]
 
+    def test_admin_sources_are_excluded_from_the_public_snapshot(self, tmp_path: Path) -> None:
+        """Anonymous visitors must not download catalogs for login-gated UI."""
+        self._write_locale(tmp_path / "pages", "en", {"title": "Pages"})
+        self._write_locale(tmp_path / "settings", "en", {"form": {"key": "Key"}})
+        reg = I18nRegistry(default_locale="en", supported_locales=["en"])
+        reg.add_source("pages", tmp_path / "pages")
+        reg.add_source("settings", tmp_path / "settings", audience="admin")
+        reg.load()
+        assert reg.messages_snapshot("en", include_admin=False) == {"pages.title": "Pages"}
+        # The full snapshot and server-side lookups still see everything.
+        assert reg.messages_snapshot("en") == {
+            "pages.title": "Pages",
+            "settings.form.key": "Key",
+        }
+        assert reg.messages("en")["settings.form.key"] == "Key"
+
+    def test_public_snapshot_defaults_to_everything(self, tmp_path: Path) -> None:
+        self._write_locale(tmp_path / "p", "en", {"title": "Products"})
+        reg = I18nRegistry(default_locale="en", supported_locales=["en"])
+        reg.add_source("products", tmp_path / "p")
+        reg.load()
+        assert reg.messages_snapshot("en", include_admin=False) == reg.messages_snapshot("en")
+
     def test_missing_locale_file_is_warning_not_error(
         self, tmp_path: Path, caplog: pytest.LogCaptureFixture
     ) -> None: