simple-module-core 0.0.17__tar.gz → 0.0.18__tar.gz

{simple_module_core-0.0.17 → simple_module_core-0.0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_core
-Version: 0.0.17
+Version: 0.0.18
 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.17 → simple_module_core-0.0.18}/pyproject.toml

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

{simple_module_core-0.0.17 → simple_module_core-0.0.18}/simple_module_core/__init__.py

@@ -33,6 +33,7 @@ from simple_module_core.i18n import I18nRegistry, Translator
 from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
 from simple_module_core.module import ModuleBase, ModuleMeta
 from simple_module_core.permissions import PermissionRegistry
+from simple_module_core.public_routes import PublicRoute, PublicRouteRegistry
 from simple_module_core.services import Services
 from simple_module_core.versioning import FRAMEWORK_API_VERSION, check_framework_compatibility
 
@@ -60,6 +61,8 @@ __all__ = [
     "ModuleMeta",
     "NotFoundError",
     "PermissionRegistry",
+    "PublicRoute",
+    "PublicRouteRegistry",
     "Services",
     "Translator",
     "ValidationError",

{simple_module_core-0.0.17 → simple_module_core-0.0.18}/simple_module_core/diagnostics/_module.py

@@ -95,6 +95,7 @@ class ModuleDiagnostics:
                     "register_event_handlers",
                     "register_middleware",
                     "register_health_checks",
+                    "register_public_routes",
                     "register_exception_handlers",
                     "register_settings",
                     "template_dirs",

{simple_module_core-0.0.17 → simple_module_core-0.0.18}/simple_module_core/module.py

@@ -15,6 +15,7 @@ if TYPE_CHECKING:
     from simple_module_core.health import HealthRegistry
     from simple_module_core.menu import MenuRegistry
     from simple_module_core.permissions import PermissionRegistry
+    from simple_module_core.public_routes import PublicRouteRegistry
 
 
 @dataclass(frozen=True)
@@ -118,6 +119,24 @@ class ModuleBase(ABC):
     def register_health_checks(self, registry: HealthRegistry) -> None:
         """Contribute health checks for the ``/health/ready`` endpoint."""
 
+    def register_public_routes(self, registry: PublicRouteRegistry) -> None:
+        """Declare routes that must bypass authentication (anonymous access).
+
+        ``AuthMiddleware`` gates every request behind the active auth provider.
+        Override this hook to exempt read-only or webhook routes that are meant
+        to be reached without a session — e.g. a STAC / OGC API surface::
+
+            def register_public_routes(self, registry):
+                registry.add_prefix("/api/gis/stac")
+                registry.add_regex(
+                    r"/api/gis/datasets/[^/]+/tilejson$", methods={"GET"}
+                )
+
+        Rules are method-aware, so a GET read route nested under a prefix that
+        also carries POST/PATCH mutations can be exempted without opening the
+        mutations. Called once at boot, in dependency order.
+        """
+
     def register_middleware(self, app: FastAPI) -> None:
         """Add middleware to the application.
 

simple_module_core-0.0.18/simple_module_core/public_routes.py

@@ -0,0 +1,129 @@
+"""Public-route registry — modules declare routes the auth layer must NOT gate.
+
+``AuthMiddleware`` gates every request behind the active auth provider. Modules
+that expose anonymous read APIs (STAC / OGC API / TileJSON, public webhooks,
+status pages) contribute exemptions here via
+:meth:`~simple_module_core.module.ModuleBase.register_public_routes`. The host
+collects them into one registry at boot and the middleware consults it on every
+request.
+
+Unlike the legacy ``AuthProvider.get_public_paths`` contract — a flat tuple of
+prefixes matched with ``str.startswith`` — a :class:`PublicRoute` is
+**method-aware** and supports prefix / exact / suffix / regex matching. That
+lets a module expose ``GET /api/gis/datasets/{id}/tilejson`` while leaving
+``PATCH``/``POST`` siblings under the same prefix authenticated.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+_MatchKind = str  # one of: "prefix" | "exact" | "suffix" | "regex"
+_VALID_KINDS = ("prefix", "exact", "suffix", "regex")
+
+
+class PublicRoute:
+    """A single anonymous-access rule.
+
+    Args:
+        pattern: The path (or path fragment / regex) to match against
+            ``request.url.path``.
+        methods: HTTP methods this rule applies to (case-insensitive). ``None``
+            (the default) means *any* method — the rule matches every verb.
+        kind: How ``pattern`` is interpreted — ``"prefix"`` (default, matches
+            any path that starts with it), ``"exact"``, ``"suffix"``, or
+            ``"regex"`` (anchored at the start of the path via ``re.match``).
+    """
+
+    __slots__ = ("_regex", "kind", "methods", "pattern")
+
+    def __init__(
+        self,
+        pattern: str,
+        *,
+        methods: Iterable[str] | None = None,
+        kind: _MatchKind = "prefix",
+    ) -> None:
+        if kind not in _VALID_KINDS:
+            raise ValueError(f"Unknown match kind {kind!r}; expected one of {_VALID_KINDS}")
+        self.pattern = pattern
+        self.methods: frozenset[str] | None = (
+            None if methods is None else frozenset(m.upper() for m in methods)
+        )
+        self.kind = kind
+        self._regex = re.compile(pattern) if kind == "regex" else None
+
+    def matches(self, method: str, path: str) -> bool:
+        """Return ``True`` if *method* + *path* are exempt under this rule."""
+        if self.methods is not None and method.upper() not in self.methods:
+            return False
+        if self.kind == "prefix":
+            return path.startswith(self.pattern)
+        if self.kind == "exact":
+            return path == self.pattern
+        if self.kind == "suffix":
+            return path.endswith(self.pattern)
+        assert self._regex is not None  # kind == "regex"
+        return self._regex.match(path) is not None
+
+    def __repr__(self) -> str:
+        methods = "*" if self.methods is None else ",".join(sorted(self.methods))
+        return f"PublicRoute({self.pattern!r}, kind={self.kind!r}, methods={methods})"
+
+
+class PublicRouteRegistry:
+    """Aggregates every module's :class:`PublicRoute` rules.
+
+    Populated once during boot (``register_public_routes`` hook) and read on
+    every unauthenticated request by ``AuthMiddleware`` — effectively immutable
+    after the registration phase.
+    """
+
+    def __init__(self) -> None:
+        self._routes: list[PublicRoute] = []
+
+    def add(
+        self,
+        route: PublicRoute | str,
+        *,
+        methods: Iterable[str] | None = None,
+        kind: _MatchKind = "prefix",
+    ) -> None:
+        """Register a rule — either a prebuilt :class:`PublicRoute` or a pattern.
+
+        Passing a string builds a :class:`PublicRoute` from ``methods``/``kind``;
+        passing a :class:`PublicRoute` ignores those keyword arguments.
+        """
+        if isinstance(route, PublicRoute):
+            self._routes.append(route)
+        else:
+            self._routes.append(PublicRoute(route, methods=methods, kind=kind))
+
+    def add_prefix(self, prefix: str, *, methods: Iterable[str] | None = None) -> None:
+        """Exempt any path starting with *prefix*."""
+        self._routes.append(PublicRoute(prefix, methods=methods, kind="prefix"))
+
+    def add_exact(self, path: str, *, methods: Iterable[str] | None = None) -> None:
+        """Exempt exactly *path*."""
+        self._routes.append(PublicRoute(path, methods=methods, kind="exact"))
+
+    def add_suffix(self, suffix: str, *, methods: Iterable[str] | None = None) -> None:
+        """Exempt any path ending with *suffix*."""
+        self._routes.append(PublicRoute(suffix, methods=methods, kind="suffix"))
+
+    def add_regex(self, pattern: str, *, methods: Iterable[str] | None = None) -> None:
+        """Exempt any path whose start matches *pattern* (``re.match`` semantics)."""
+        self._routes.append(PublicRoute(pattern, methods=methods, kind="regex"))
+
+    def matches(self, method: str, path: str) -> bool:
+        """Return ``True`` if any registered rule exempts *method* + *path*."""
+        return any(route.matches(method, path) for route in self._routes)
+
+    @property
+    def routes(self) -> list[PublicRoute]:
+        """All registered rules (a copy — mutating it doesn't affect the registry)."""
+        return list(self._routes)
+
+
+__all__ = ["PublicRoute", "PublicRouteRegistry"]

{simple_module_core-0.0.17 → simple_module_core-0.0.18}/simple_module_core/services.py

@@ -27,6 +27,7 @@ if TYPE_CHECKING:
     from simple_module_core.menu import MenuRegistry
     from simple_module_core.module import ModuleBase
     from simple_module_core.permissions import PermissionRegistry
+    from simple_module_core.public_routes import PublicRouteRegistry
 
 
 @dataclass(frozen=True, slots=True)
@@ -40,6 +41,7 @@ class Services:
     permissions: PermissionRegistry
     feature_flags: FeatureFlagRegistry
     health_registry: HealthRegistry
+    public_routes: PublicRouteRegistry
     i18n_registry: I18nRegistry
     inertia_config: InertiaConfig
     modules: tuple[ModuleBase, ...]

{simple_module_core-0.0.17 → simple_module_core-0.0.18}/tests/test_module_base.py

@@ -101,6 +101,30 @@ class TestModuleNewHooks:
         mod = DummyModule()
         mod.register_settings(None)
 
+    async def test_register_public_routes_default_noop(self):
+        from simple_module_core.public_routes import PublicRouteRegistry
+
+        mod = DummyModule()
+        reg = PublicRouteRegistry()
+        mod.register_public_routes(reg)
+        assert reg.routes == []
+
+    async def test_register_public_routes_override(self):
+        from simple_module_core.public_routes import PublicRouteRegistry
+
+        class ModWithPublic(ModuleBase):
+            meta = ModuleMeta(name="WithPublic")
+
+            def register_public_routes(self, registry):
+                registry.add_prefix("/api/with-public/stac")
+                registry.add_regex(r"/api/with-public/datasets/[^/]+/tilejson$", methods={"GET"})
+
+        reg = PublicRouteRegistry()
+        ModWithPublic().register_public_routes(reg)
+        assert reg.matches("GET", "/api/with-public/stac/collections")
+        assert reg.matches("GET", "/api/with-public/datasets/9/tilejson")
+        assert not reg.matches("PATCH", "/api/with-public/datasets/9/tilejson")
+
 
 class TestModuleAssetHooks:
     async def test_template_dirs_default_empty(self):

{simple_module_core-0.0.17 → simple_module_core-0.0.18}/tests/test_module_diagnostics.py

@@ -193,6 +193,36 @@ class TestSM018InertiaApiCalls:
         assert results == []
 
 
+class TestSM007EmptyModules:
+    """SM007 fires only when a module overrides no registration hooks at all."""
+
+    def _diags(self, modules):
+        from simple_module_core.diagnostics._module import ModuleDiagnostics
+
+        return list(ModuleDiagnostics()._check_empty_modules(modules))
+
+    async def test_fires_when_no_hooks_overridden(self):
+        from simple_module_core.module import ModuleBase, ModuleMeta
+
+        class Bare(ModuleBase):
+            meta = ModuleMeta(name="Bare")
+
+        results = self._diags([Bare()])
+        assert len(results) == 1
+        assert results[0].code == "SM007"
+
+    async def test_silent_when_only_public_routes_registered(self):
+        from simple_module_core.module import ModuleBase, ModuleMeta
+
+        class PublicOnly(ModuleBase):
+            meta = ModuleMeta(name="PublicOnly")
+
+            def register_public_routes(self, registry):
+                registry.add_prefix("/api/public_only/stac")
+
+        assert self._diags([PublicOnly()]) == []
+
+
 class TestSM019ViewsWithoutMenu:
     """SM019 fires when a module ships view routes but never registers a menu item."""
 

simple_module_core-0.0.18/tests/test_public_routes.py

@@ -0,0 +1,94 @@
+"""Tests for PublicRouteRegistry — method-aware anonymous-access rules.
+
+The registry is the extension point modules use (via
+``ModuleBase.register_public_routes``) to declare routes the auth layer must
+let through unauthenticated. Unlike the legacy provider ``get_public_paths``
+contract, a rule can be scoped to specific HTTP methods so a read route nested
+under a mutation-bearing prefix can be exempted without opening the mutations.
+"""
+
+from __future__ import annotations
+
+from simple_module_core.public_routes import PublicRoute, PublicRouteRegistry
+
+
+class TestPublicRouteMatching:
+    def test_prefix_matches_any_subpath(self):
+        route = PublicRoute("/api/gis/stac")
+        assert route.matches("GET", "/api/gis/stac")
+        assert route.matches("GET", "/api/gis/stac/collections")
+        assert not route.matches("GET", "/api/gis/datasets")
+
+    def test_exact_matches_only_full_path(self):
+        route = PublicRoute("/api/gis/catalog/search", kind="exact")
+        assert route.matches("GET", "/api/gis/catalog/search")
+        assert not route.matches("GET", "/api/gis/catalog/search/extra")
+
+    def test_suffix_matches_path_tail(self):
+        route = PublicRoute("/tilejson", kind="suffix")
+        assert route.matches("GET", "/api/gis/datasets/42/tilejson")
+        assert not route.matches("GET", "/api/gis/datasets/42/visibility")
+
+    def test_regex_is_anchored_at_start(self):
+        route = PublicRoute(r"/api/gis/datasets/[^/]+/tilejson$", kind="regex")
+        assert route.matches("GET", "/api/gis/datasets/42/tilejson")
+        assert not route.matches("GET", "/api/gis/datasets/42/tilejson/extra")
+        assert not route.matches("GET", "/prefix/api/gis/datasets/42/tilejson")
+
+    def test_methods_none_matches_every_verb(self):
+        route = PublicRoute("/api/gis/stac")
+        for method in ("GET", "POST", "PATCH", "DELETE"):
+            assert route.matches(method, "/api/gis/stac")
+
+    def test_methods_restrict_to_listed_verbs(self):
+        route = PublicRoute("/api/gis/datasets/", methods={"GET"})
+        assert route.matches("GET", "/api/gis/datasets/42/tilejson")
+        assert not route.matches("PATCH", "/api/gis/datasets/42/visibility")
+        assert not route.matches("POST", "/api/gis/datasets/42/reprocess")
+
+    def test_method_matching_is_case_insensitive(self):
+        route = PublicRoute("/api/gis/stac", methods={"get"})
+        assert route.matches("GET", "/api/gis/stac")
+
+
+class TestPublicRouteRegistry:
+    def test_empty_registry_matches_nothing(self):
+        registry = PublicRouteRegistry()
+        assert not registry.matches("GET", "/api/gis/stac")
+
+    def test_add_prefix(self):
+        registry = PublicRouteRegistry()
+        registry.add_prefix("/api/gis/ogc/")
+        assert registry.matches("GET", "/api/gis/ogc/collections")
+        assert not registry.matches("GET", "/api/gis/datasets")
+
+    def test_add_exact(self):
+        registry = PublicRouteRegistry()
+        registry.add_exact("/api/gis/catalog/search")
+        assert registry.matches("POST", "/api/gis/catalog/search")
+        assert not registry.matches("POST", "/api/gis/catalog/search/x")
+
+    def test_add_regex_with_method(self):
+        registry = PublicRouteRegistry()
+        registry.add_regex(r"/api/gis/datasets/[^/]+/tilejson$", methods={"GET"})
+        assert registry.matches("GET", "/api/gis/datasets/7/tilejson")
+        assert not registry.matches("PATCH", "/api/gis/datasets/7/tilejson")
+
+    def test_matches_is_true_if_any_route_matches(self):
+        registry = PublicRouteRegistry()
+        registry.add_prefix("/api/gis/ogc/")
+        registry.add_exact("/api/gis/catalog/search")
+        assert registry.matches("GET", "/api/gis/ogc/tiles")
+        assert registry.matches("GET", "/api/gis/catalog/search")
+
+    def test_routes_exposes_registered_rules(self):
+        registry = PublicRouteRegistry()
+        registry.add_prefix("/a")
+        registry.add_exact("/b")
+        assert len(registry.routes) == 2
+        assert all(isinstance(r, PublicRoute) for r in registry.routes)
+
+    def test_add_accepts_a_prebuilt_route(self):
+        registry = PublicRouteRegistry()
+        registry.add(PublicRoute("/api/gis/stac"))
+        assert registry.matches("GET", "/api/gis/stac")

{simple_module_core-0.0.17 → simple_module_core-0.0.18}/tests/test_services.py

@@ -29,6 +29,7 @@ class TestServices:
         assert s.permissions is _SENTINEL_PERMS
         assert s.feature_flags is _SENTINEL_FLAGS
         assert s.health_registry is _SENTINEL_HEALTH
+        assert s.public_routes is _SENTINEL_PUBLIC_ROUTES
         assert s.i18n_registry is _SENTINEL_I18N
         assert s.inertia_config is _SENTINEL_INERTIA
         assert s.modules == ()
@@ -41,6 +42,7 @@ _SENTINEL_MENU = object()
 _SENTINEL_PERMS = object()
 _SENTINEL_FLAGS = object()
 _SENTINEL_HEALTH = object()
+_SENTINEL_PUBLIC_ROUTES = object()
 _SENTINEL_I18N = object()
 _SENTINEL_INERTIA = object()
 
@@ -55,6 +57,7 @@ def _make_services() -> Services:
         permissions=_SENTINEL_PERMS,  # type: ignore[arg-type]
         feature_flags=_SENTINEL_FLAGS,  # type: ignore[arg-type]
         health_registry=_SENTINEL_HEALTH,  # type: ignore[arg-type]
+        public_routes=_SENTINEL_PUBLIC_ROUTES,  # type: ignore[arg-type]
         i18n_registry=_SENTINEL_I18N,  # type: ignore[arg-type]
         inertia_config=_SENTINEL_INERTIA,  # type: ignore[arg-type]
         modules=(),