snakeboot 0.1.2__py3-none-any.whl

snakeboot/rest/rest_controller_advice.py

@@ -0,0 +1,38 @@
+from collections.abc import Callable
+from typing import Any
+
+from wireup import injectable
+
+from snakeboot.rest.rest_controller_errors import InvalidRestControllerError
+from snakeboot.rest.rest_controller_mappings import (
+    ADVICE_MARKER_ATTRIBUTE,
+    EXCEPTION_HANDLER_ATTRIBUTE,
+    ExceptionHandlerMapping,
+)
+
+
+def rest_controller_advice[C: type](advice_class: C) -> C:
+    """Declares how errors become HTTP answers for every controller, like Spring's `@RestControllerAdvice`.
+
+    The class becomes a wireup singleton, like a controller. RestControllerMounter finds it
+    with the same component scan and registers each `@exception_handler` method with Ninja,
+    so composition never lists an error translation.
+    """
+    setattr(advice_class, ADVICE_MARKER_ATTRIBUTE, True)
+    return injectable(advice_class)
+
+
+def exception_handler(*error_types: type[Exception], status: int) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Marks an advice method as the answer to `error_types`, like Spring's `@ExceptionHandler`.
+
+    The method receives the error and returns the body; the answer gets `status`.
+    Ninja picks the most specific error type through the class hierarchy.
+    """
+    if not error_types:
+        raise InvalidRestControllerError("@exception_handler needs at least one error type.")
+
+    def record(method: Callable[..., Any]) -> Callable[..., Any]:
+        setattr(method, EXCEPTION_HANDLER_ATTRIBUTE, ExceptionHandlerMapping(error_types, status))
+        return method
+
+    return record

snakeboot/rest/rest_controller_errors.py

@@ -0,0 +1,14 @@
+class InvalidRestControllerError(TypeError):
+    """Raised at start-up when a class or method cannot become a REST controller or endpoint.
+
+    Failing while mounting, not at the first request, is the point: a broken controller
+    must stop the application from starting, like a missing bean in Spring.
+    """
+
+
+class NoAuthenticatedPrincipalError(TypeError):
+    """Raised when an endpoint asks who is signed in, but no authentication answered with an id.
+
+    It is a programming error, not a client error: the endpoint opted out of
+    authentication (`auth=None`) or the installed authentication returns something else.
+    """

snakeboot/rest/rest_controller_mappings.py

@@ -0,0 +1,64 @@
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Final
+
+CONTROLLER_MAPPING_ATTRIBUTE: Final = "__rest_controller_mapping__"
+ROUTE_MAPPING_ATTRIBUTE: Final = "__rest_route_mapping__"
+ADVICE_MARKER_ATTRIBUTE: Final = "__rest_controller_advice__"
+EXCEPTION_HANDLER_ATTRIBUTE: Final = "__rest_exception_handler_mapping__"
+
+_PATH_PARAMETER: Final = re.compile(r"\{[^}]*\}")
+
+
+@dataclass(frozen=True, slots=True)
+class ControllerMapping:
+    """What `@rest_controller` records on a class: the URL prefix and the OpenAPI tags."""
+
+    prefix: str
+    tags: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class RouteMapping:
+    """What `@route.get(...)` and friends record on a method: HTTP method, path and Ninja options.
+
+    The options are passed to Ninja unchanged (`response`, `auth`, `summary`, ...).
+    """
+
+    http_method: str
+    path: str
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class ExceptionHandlerMapping:
+    """What `@exception_handler(...)` records on an advice method: the errors it answers and the status."""
+
+    error_types: tuple[type[Exception], ...]
+    status: int
+
+
+@dataclass(frozen=True, slots=True)
+class DeclaredEndpoint:
+    """One `@route` method of one controller, as the mounter is about to publish it."""
+
+    controller_class: type
+    method: Callable[..., Any]
+    prefix: str
+    route_mapping: RouteMapping
+
+    @property
+    def name(self) -> str:
+        """`Controller.method`, for error messages."""
+        return f"{self.controller_class.__name__}.{self.method.__name__}"
+
+    @property
+    def route_key(self) -> tuple[str, str]:
+        """HTTP method and full path, with every path parameter reduced to `{}`.
+
+        `/workshops/{workshop_id}` and `/workshops/{id}` match the same URLs, so they get
+        the same key: like Spring, two endpoints with one key are an ambiguous mapping.
+        """
+        segments = [segment for segment in f"{self.prefix}/{self.route_mapping.path}".split("/") if segment]
+        return self.route_mapping.http_method, _PATH_PARAMETER.sub("{}", "/" + "/".join(segments))

snakeboot/rest/rest_controller_mounter.py

@@ -0,0 +1,121 @@
+import inspect
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from types import ModuleType
+
+from ninja import NinjaAPI, Router
+
+from snakeboot.rest.controller_endpoint_factory import ControllerEndpointFactory
+from snakeboot.rest.rest_controller_errors import InvalidRestControllerError
+from snakeboot.rest.rest_controller_mappings import (
+    ADVICE_MARKER_ATTRIBUTE,
+    CONTROLLER_MAPPING_ATTRIBUTE,
+    EXCEPTION_HANDLER_ATTRIBUTE,
+    ROUTE_MAPPING_ATTRIBUTE,
+    ControllerMapping,
+    DeclaredEndpoint,
+    ExceptionHandlerMapping,
+)
+from snakeboot.rest.rest_controller_scanner import RestControllerScanner
+
+
+@dataclass(frozen=True, slots=True)
+class MountedRestComponents:
+    """What RestControllerMounter added to an API: the controllers and the advices it found."""
+
+    controllers: list[type]
+    advices: list[type]
+
+
+class RestControllerMounter:
+    """Finds the REST controllers and advices under some packages and adds them to a Ninja API.
+
+    Composition calls it once, with the same modules wireup scans for injectables:
+    one "component scan" feeds both dependency injection and routing, so a controller
+    the container knows always has its routes, and the other way round.
+
+    Like Spring, it refuses to start on an ambiguous mapping: two endpoints for the
+    same HTTP method and path, or two advice methods for the same error type.
+    """
+
+    def __init__(
+        self,
+        scanner: RestControllerScanner | None = None,
+        endpoint_factory: ControllerEndpointFactory | None = None,
+    ) -> None:
+        self._scanner = scanner or RestControllerScanner()
+        self._endpoint_factory = endpoint_factory or ControllerEndpointFactory()
+
+    def mount(self, api: NinjaAPI, *, scan: Iterable[str | ModuleType]) -> MountedRestComponents:
+        """Adds one router per controller and the error answers of every advice found under `scan`.
+
+        `scan` takes what `settings.WIREUP.injectables` holds: module names or module objects.
+        """
+        packages = list(scan)
+        controllers = self._scanner.scan(packages)
+        advices = self._scanner.scan(packages, marker=ADVICE_MARKER_ATTRIBUTE)
+        endpoints_by_controller = {controller: self._endpoints_of(controller) for controller in controllers}
+        self._refuse_ambiguous_routes([e for endpoints in endpoints_by_controller.values() for e in endpoints])
+        for controller_class, endpoints in endpoints_by_controller.items():
+            prefix = self._controller_mapping(controller_class).prefix
+            api.add_router(prefix, self._router_for(controller_class, endpoints))
+        self._register_error_answers(api, advices)
+        return MountedRestComponents(controllers=controllers, advices=advices)
+
+    def _controller_mapping(self, controller_class: type) -> ControllerMapping:
+        mapping: ControllerMapping = getattr(controller_class, CONTROLLER_MAPPING_ATTRIBUTE)
+        return mapping
+
+    def _endpoints_of(self, controller_class: type) -> list[DeclaredEndpoint]:
+        prefix = self._controller_mapping(controller_class).prefix
+        endpoints = [
+            DeclaredEndpoint(controller_class, method, prefix, route_mapping)
+            for _, method in inspect.getmembers(controller_class, inspect.isfunction)
+            if (route_mapping := getattr(method, ROUTE_MAPPING_ATTRIBUTE, None)) is not None
+        ]
+        if not endpoints:
+            raise InvalidRestControllerError(f"{controller_class.__name__} has no @route methods.")
+        return endpoints
+
+    def _refuse_ambiguous_routes(self, endpoints: Sequence[DeclaredEndpoint]) -> None:
+        claimed: dict[tuple[str, str], DeclaredEndpoint] = {}
+        for endpoint in endpoints:
+            if (earlier := claimed.get(endpoint.route_key)) is not None:
+                http_method, path = endpoint.route_key
+                raise InvalidRestControllerError(
+                    f"Ambiguous mapping: {http_method} '{path}' is mapped by {earlier.name} and {endpoint.name}."
+                )
+            claimed[endpoint.route_key] = endpoint
+
+    def _router_for(self, controller_class: type, endpoints: Sequence[DeclaredEndpoint]) -> Router:
+        router = Router(tags=list(self._controller_mapping(controller_class).tags))
+        for endpoint in endpoints:
+            router.add_api_operation(
+                endpoint.route_mapping.path,
+                [endpoint.route_mapping.http_method],
+                self._endpoint_factory.create(controller_class, endpoint.method),
+                **endpoint.route_mapping.options,
+            )
+        return router
+
+    def _register_error_answers(self, api: NinjaAPI, advices: Sequence[type]) -> None:
+        answered_by: dict[type[Exception], str] = {}
+        for advice_class in advices:
+            for _, method in inspect.getmembers(advice_class, inspect.isfunction):
+                mapping: ExceptionHandlerMapping | None = getattr(method, EXCEPTION_HANDLER_ATTRIBUTE, None)
+                if mapping is None:
+                    continue
+                answer = self._endpoint_factory.create_error_answer(
+                    advice_class, method, api=api, status=mapping.status
+                )
+                for error_type in mapping.error_types:
+                    self._claim_error_type(answered_by, error_type, f"{advice_class.__name__}.{method.__name__}")
+                    # Ninja annotates the handler's error as `Exception | type[Exception]`, but passes an instance.
+                    api.add_exception_handler(error_type, answer)  # type: ignore[arg-type]
+
+    def _claim_error_type(self, answered_by: dict[type[Exception], str], error_type: type[Exception], by: str) -> None:
+        if (earlier := answered_by.get(error_type)) is not None:
+            raise InvalidRestControllerError(
+                f"Ambiguous mapping: {error_type.__name__} is answered by {earlier} and {by}."
+            )
+        answered_by[error_type] = by

snakeboot/rest/rest_controller_scanner.py

@@ -0,0 +1,42 @@
+import importlib
+import pkgutil
+from collections.abc import Iterable
+from types import ModuleType
+
+from snakeboot.rest.rest_controller_mappings import CONTROLLER_MAPPING_ATTRIBUTE
+
+
+class RestControllerScanner:
+    """Component scan: finds every class with a REST marker in the modules under some packages.
+
+    Python has no classpath scanning and a decorator only runs when its module is
+    imported, so a registry filled by decorators would silently miss controllers in
+    modules nobody imported. The scanner imports the modules itself, which makes the
+    result complete and independent of import order. It is sorted, so routes are
+    always registered in the same order.
+    """
+
+    def scan(self, packages: Iterable[str | ModuleType], *, marker: str = CONTROLLER_MAPPING_ATTRIBUTE) -> list[type]:
+        """Returns the classes carrying `marker` (controllers by default) defined in `packages`.
+
+        `packages` may name packages (searched with their subpackages) or plain modules, or be
+        module objects: the same forms wireup accepts, so the list in `settings.WIREUP` fits.
+        """
+        found: dict[str, type] = {}
+        for package in packages:
+            imported = package if isinstance(package, ModuleType) else importlib.import_module(package)
+            for module in self._modules_under(imported):
+                for candidate in vars(module).values():
+                    if self._is_marked_class_defined_in(candidate, module, marker):
+                        found[f"{candidate.__module__}.{candidate.__qualname__}"] = candidate
+        return [found[name] for name in sorted(found)]
+
+    def _modules_under(self, package: ModuleType) -> list[ModuleType]:
+        if not hasattr(package, "__path__"):
+            return [package]
+        submodules = pkgutil.walk_packages(package.__path__, prefix=f"{package.__name__}.")
+        return [package, *(importlib.import_module(info.name) for info in submodules)]
+
+    def _is_marked_class_defined_in(self, candidate: object, module: ModuleType, marker: str) -> bool:
+        # A class imported into another module is found once, where it is defined.
+        return isinstance(candidate, type) and marker in vars(candidate) and candidate.__module__ == module.__name__

snakeboot/rest/route_markers.py

@@ -0,0 +1,45 @@
+from collections.abc import Callable
+from typing import Any
+
+from snakeboot.rest.rest_controller_mappings import ROUTE_MAPPING_ATTRIBUTE, RouteMapping
+
+
+class RouteMarkers:
+    """Marks controller methods as endpoints, like Spring's `@GetMapping` and `@PostMapping`.
+
+    A marker only records a RouteMapping on the method; it changes nothing else. The
+    RestControllerMounter reads the marks when it builds the Ninja routers. Use the
+    module-level instance: `@route.get("/{workshop_id}", response=WorkshopViewDTO)`.
+    """
+
+    def get(self, path: str, **options: Any) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Marks a method as the handler of `GET prefix+path`."""
+        return self._mark("GET", path, options)
+
+    def post(self, path: str, **options: Any) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Marks a method as the handler of `POST prefix+path`."""
+        return self._mark("POST", path, options)
+
+    def put(self, path: str, **options: Any) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Marks a method as the handler of `PUT prefix+path`."""
+        return self._mark("PUT", path, options)
+
+    def patch(self, path: str, **options: Any) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Marks a method as the handler of `PATCH prefix+path`."""
+        return self._mark("PATCH", path, options)
+
+    def delete(self, path: str, **options: Any) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Marks a method as the handler of `DELETE prefix+path`."""
+        return self._mark("DELETE", path, options)
+
+    def _mark(
+        self, http_method: str, path: str, options: dict[str, Any]
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        def record(method: Callable[..., Any]) -> Callable[..., Any]:
+            setattr(method, ROUTE_MAPPING_ATTRIBUTE, RouteMapping(http_method, path, options))
+            return method
+
+        return record
+
+
+route = RouteMarkers()

snakeboot/testing/__init__.py

@@ -0,0 +1,12 @@
+"""Test helpers, like spring-test: a transaction manager for tests and a reader for architecture tests.
+
+TransactionManagerRegistry.install(RecordingTransactionManager())    # use cases without a database
+
+declared = declared_classes(Path("src/myapp"), "rest_controller")    # what the source declares
+assert declared == qualified_names(urls.mounted.controllers)         # ... is what was mounted
+"""
+
+from snakeboot.testing.declared_classes import declared_classes, qualified_names
+from snakeboot.testing.recording_transaction_manager import RecordingTransactionManager
+
+__all__ = ["RecordingTransactionManager", "declared_classes", "qualified_names"]

snakeboot/testing/declared_classes.py

@@ -0,0 +1,33 @@
+import ast
+from pathlib import Path
+
+
+def declared_classes(package_directory: Path, decorator_name: str) -> set[str]:
+    """Returns `module.Class` for every class in the source under `package_directory` carrying `decorator_name`.
+
+    It reads the source instead of importing it, so an architecture test can compare what is
+    *written* with what the component scan *found*: a `@rest_controller` in a module the scan
+    skips would otherwise be silently missing from the API. Both `@name` and `@name(...)` count.
+    """
+    found: set[str] = set()
+    for path in sorted(package_directory.rglob("*.py")):
+        for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
+            if isinstance(node, ast.ClassDef) and any(_names(d, decorator_name) for d in node.decorator_list):
+                found.add(f"{_module_name(package_directory, path)}.{node.name}")
+    return found
+
+
+def qualified_names(classes: list[type]) -> set[str]:
+    """Returns `module.Class` for each class, the form `declared_classes` uses."""
+    return {f"{cls.__module__}.{cls.__qualname__}" for cls in classes}
+
+
+def _names(decorator: ast.expr, decorator_name: str) -> bool:
+    target = decorator.func if isinstance(decorator, ast.Call) else decorator
+    return isinstance(target, ast.Name) and target.id == decorator_name
+
+
+def _module_name(package_directory: Path, path: Path) -> str:
+    relative = path.relative_to(package_directory.parent).with_suffix("")
+    parts = relative.parts[:-1] if relative.name == "__init__" else relative.parts
+    return ".".join(parts)

snakeboot/testing/recording_transaction_manager.py

@@ -0,0 +1,62 @@
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager, contextmanager
+from typing import override
+
+from snakeboot.transaction import TransactionManager
+
+
+class RecordingTransactionManager(TransactionManager):
+    """Test double: remembers which transactions were opened, committed and rolled back.
+
+    Application tests install it to run `@transactional` use cases without a database,
+    to assert that a use case really runs inside a transaction, and to check that
+    `after_commit` callbacks run only after a commit.
+    """
+
+    def __init__(self) -> None:
+        self.opened = 0
+        self.committed = 0
+        self.rolled_back = 0
+        self._depth = 0
+        self._pending_callbacks: list[Callable[[], None]] = []
+        self.callback_errors: list[Exception] = []
+
+    @property
+    def in_transaction(self) -> bool:
+        """Tells whether a transaction is open right now, so a test can check where code runs."""
+        return self._depth > 0
+
+    @override
+    def atomic(self) -> AbstractContextManager[None]:
+        return self._record_transaction()
+
+    @override
+    def on_commit(self, callback: Callable[[], None]) -> None:
+        if self.in_transaction:
+            self._pending_callbacks.append(callback)
+        else:
+            self._execute_robustly(callback)
+
+    def _execute_robustly(self, callback: Callable[[], None]) -> None:
+        try:
+            callback()
+        except Exception as error:  # noqa: BLE001 - like Django's robust on_commit, any callback error is recorded
+            self.callback_errors.append(error)
+
+    @contextmanager
+    def _record_transaction(self) -> Iterator[None]:
+        self.opened += 1
+        self._depth += 1
+        try:
+            yield
+        except BaseException:
+            self._depth -= 1
+            self.rolled_back += 1
+            self._pending_callbacks.clear()
+            raise
+        self._depth -= 1
+        self.committed += 1
+        if not self.in_transaction:
+            callbacks, self._pending_callbacks = self._pending_callbacks, []
+            for callback in callbacks:
+                self._execute_robustly(callback)

snakeboot/transaction/__init__.py

@@ -0,0 +1,17 @@
+"""Technical library that declares transaction boundaries without knowing the technology."""
+
+from snakeboot.transaction.after_commit import after_commit
+from snakeboot.transaction.transaction_manager import TransactionManager
+from snakeboot.transaction.transaction_manager_not_installed_error import (
+    TransactionManagerNotInstalledError,
+)
+from snakeboot.transaction.transaction_manager_registry import TransactionManagerRegistry
+from snakeboot.transaction.transactional import transactional
+
+__all__ = [
+    "TransactionManager",
+    "TransactionManagerNotInstalledError",
+    "TransactionManagerRegistry",
+    "after_commit",
+    "transactional",
+]

snakeboot/transaction/after_commit.py

@@ -0,0 +1,13 @@
+from collections.abc import Callable
+
+from snakeboot.transaction.transaction_manager_registry import TransactionManagerRegistry
+
+
+def after_commit(callback: Callable[[], None]) -> None:
+    """Defers a side effect until the surrounding `@transactional` operation has committed.
+
+    Use it for effects outside the database, such as notifications: a participant must
+    never hear about a seat that a rolled-back transaction took away again. Mirrors
+    Spring's `@TransactionalEventListener(phase = AFTER_COMMIT)`.
+    """
+    TransactionManagerRegistry.current().on_commit(callback)

snakeboot/transaction/transaction_manager.py

@@ -0,0 +1,25 @@
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+
+
+class TransactionManager(ABC):
+    """Opens a transaction in a concrete technology, like Spring's PlatformTransactionManager.
+
+    `@transactional` and `after_commit` only know this abstraction. Composition installs
+    the concrete manager (Django's `atomic` in production, a recording fake in tests), so
+    use cases declare transaction behaviour without depending on the persistence technology.
+    """
+
+    @abstractmethod
+    def atomic(self) -> AbstractContextManager[None]:
+        """Returns a context manager that commits on success and rolls back on an exception."""
+
+    @abstractmethod
+    def on_commit(self, callback: Callable[[], None]) -> None:
+        """Runs `callback` once the current transaction has committed; drops it on a rollback.
+
+        Outside a transaction the callback runs immediately. Callbacks run robustly:
+        an exception in one callback does not prevent others from running and does not
+        mask an already committed transaction.
+        """

snakeboot/transaction/transaction_manager_not_installed_error.py

@@ -0,0 +1,6 @@
+class TransactionManagerNotInstalledError(RuntimeError):
+    """Raised when `@transactional` runs before composition installed a TransactionManager.
+
+    A missing manager is a wiring mistake. Failing loudly prevents a use case from
+    silently changing state without a transaction.
+    """

snakeboot/transaction/transaction_manager_registry.py

@@ -0,0 +1,36 @@
+from typing import ClassVar
+
+from snakeboot.transaction.transaction_manager import TransactionManager
+from snakeboot.transaction.transaction_manager_not_installed_error import (
+    TransactionManagerNotInstalledError,
+)
+
+
+class TransactionManagerRegistry:
+    """Holds the one TransactionManager that composition installed for this process.
+
+    A decorator cannot receive constructor injection, so `@transactional` looks the
+    manager up here. Only composition and tests call `install` and `uninstall`.
+    """
+
+    _installed: ClassVar[TransactionManager | None] = None
+
+    @classmethod
+    def install(cls, manager: TransactionManager) -> None:
+        """Makes `manager` the transaction manager used by every `@transactional` call."""
+        cls._installed = manager
+
+    @classmethod
+    def uninstall(cls) -> None:
+        """Removes the installed manager, so a test cannot leak its manager into the next one."""
+        cls._installed = None
+
+    @classmethod
+    def current(cls) -> TransactionManager:
+        """Returns the installed manager or fails when composition forgot to install one."""
+        if cls._installed is None:
+            raise TransactionManagerNotInstalledError(
+                "No TransactionManager installed. Composition must call "
+                "TransactionManagerRegistry.install(...) at start-up."
+            )
+        return cls._installed

snakeboot/transaction/transactional.py

@@ -0,0 +1,32 @@
+import inspect
+from collections.abc import Callable
+from functools import wraps
+
+from snakeboot.transaction.transaction_manager_registry import TransactionManagerRegistry
+
+
+def transactional[**P, R](operation: Callable[P, R]) -> Callable[P, R]:
+    """Declares that `operation` runs in one transaction, like Spring's `@Transactional`.
+
+    Put it on the `execute` method of a use case that changes state. The transaction
+    commits when `operation` returns and rolls back when it raises. Which technology
+    opens the transaction is decided by the TransactionManager composition installed.
+    """
+    if inspect.iscoroutinefunction(operation):
+        raise TypeError(
+            f"{operation.__qualname__} is an async function; @transactional supports synchronous operations only."
+        )
+
+    @wraps(operation)
+    def run_in_transaction(*args: P.args, **kwargs: P.kwargs) -> R:
+        with TransactionManagerRegistry.current().atomic():
+            result = operation(*args, **kwargs)
+            if inspect.iscoroutine(result):
+                result.close()
+                raise TypeError(
+                    f"{operation.__qualname__} returned a coroutine; "
+                    "@transactional supports synchronous operations only."
+                )
+            return result
+
+    return run_in_transaction