snakeboot 0.1.2__py3-none-any.whl

snakeboot/__init__.py

@@ -0,0 +1,12 @@
+"""snakeboot: Spring Boot ergonomics for hexagonal Python applications.
+
+    snakeboot.transaction     @transactional, after_commit, TransactionManager    (no dependencies)
+    snakeboot.component_scan  @application_root, ComponentScan                    (no dependencies)
+    snakeboot.events          ApplicationEventPublisher, @transactional_event_listener   (wireup)
+    snakeboot.rest            @rest_controller, @route, @rest_controller_advice   (extra: ninja)
+    snakeboot.django          DjangoAtomicTransactionManager                      (extra: django)
+    snakeboot.testing         RecordingTransactionManager, declared_classes       (no dependencies)
+
+The libraries imitate the basics of Spring Boot, not Spring itself: each one is a few
+small classes a reader can follow, and none knows anything about the application's domain.
+"""

snakeboot/component_scan/__init__.py

@@ -0,0 +1,27 @@
+"""Technical library: one component scan for dependency injection and routing.
+
+    @application_root                         # @SpringBootApplication: scan from this package down
+    class MyApplication: ...
+
+    # in settings.py, inside the setting wireup needs anyway:
+    WIREUP = WireupSettings(injectables=[*ComponentScan.of(MyApplication).module_names()])
+
+Standard library only: it finds module names without importing them, so settings can use it
+before Django has started.
+"""
+
+from snakeboot.component_scan.application_root import application_root
+from snakeboot.component_scan.component_scan import (
+    DJANGO_ENTRY_POINTS,
+    SNAKEBOOT_AUTO_CONFIGURATION,
+    ComponentScan,
+    InvalidApplicationRootError,
+)
+
+__all__ = [
+    "DJANGO_ENTRY_POINTS",
+    "SNAKEBOOT_AUTO_CONFIGURATION",
+    "ComponentScan",
+    "InvalidApplicationRootError",
+    "application_root",
+]

snakeboot/component_scan/application_root.py

@@ -0,0 +1,56 @@
+import sys
+from collections.abc import Callable
+from typing import overload
+
+from snakeboot.component_scan.component_scan import (
+    APPLICATION_ROOT_ATTRIBUTE,
+    DJANGO_ENTRY_POINTS,
+    ComponentScan,
+    InvalidApplicationRootError,
+)
+
+
+@overload
+def application_root[C: type](application_class: C, /) -> C: ...
+
+
+@overload
+def application_root[C: type](
+    *, exclude: tuple[str, ...] = (), default_exclude: tuple[str, ...] = DJANGO_ENTRY_POINTS
+) -> Callable[[C], C]: ...
+
+
+def application_root[C: type](
+    application_class: C | None = None,
+    /,
+    *,
+    exclude: tuple[str, ...] = (),
+    default_exclude: tuple[str, ...] = DJANGO_ENTRY_POINTS,
+) -> C | Callable[[C], C]:
+    """Marks the root of the application, like Spring's `@SpringBootApplication`.
+
+    The component scan starts in the package of the marked class and covers everything
+    below it, so the class belongs in the top package (`myapp/myapp_application.py`).
+    Use it bare (`@application_root`) or with own exclusions on top of the Django defaults
+    (`@application_root(exclude=(...))`). Settings read the result with `ComponentScan.of(...)`.
+    """
+
+    def declare(declared_class: C) -> C:
+        scan = ComponentScan((_package_of(declared_class),), exclude=exclude, default_exclude=default_exclude)
+        setattr(declared_class, APPLICATION_ROOT_ATTRIBUTE, scan)
+        return declared_class
+
+    return declare if application_class is None else declare(application_class)
+
+
+def _package_of(declared_class: type) -> str:
+    module = sys.modules.get(declared_class.__module__)
+    if module is not None and hasattr(module, "__path__"):
+        return module.__name__
+    package, _, _ = declared_class.__module__.rpartition(".")
+    if not package:
+        raise InvalidApplicationRootError(
+            f"{declared_class.__name__} is defined in {declared_class.__module__!r}, outside any package; "
+            "an application root lives in the top package it scans."
+        )
+    return package

snakeboot/component_scan/component_scan.py

@@ -0,0 +1,104 @@
+import importlib.util
+import pkgutil
+from collections.abc import Iterator
+from dataclasses import dataclass
+from fnmatch import fnmatchcase
+from pathlib import Path
+from typing import Final
+
+DJANGO_ENTRY_POINTS: Final = ("*.wsgi", "*.asgi", "*.migrations")
+"""Modules every Django project has that are never components.
+
+`wsgi.py` and `asgi.py` start Django when they are imported; a scan that imported them
+during start-up would start Django a second time, which Django refuses. Migrations hold
+no components. These are conventions of Django, so the scan needs no Django import to know them.
+"""
+
+SNAKEBOOT_AUTO_CONFIGURATION: Final = ("snakeboot.events.application_event_publisher_injectable",)
+"""Modules of snakeboot itself that register components, like Spring Boot's `@EnableAutoConfiguration`.
+
+Spring Boot always provides an `ApplicationEventPublisher`; so does snakeboot, through this
+module. The scan adds it to every application without the application naming it. The names
+are strings: the scan still imports nothing and depends on no other part of snakeboot.
+"""
+
+APPLICATION_ROOT_ATTRIBUTE: Final = "__component_scan__"
+
+
+class InvalidApplicationRootError(TypeError):
+    """Raised at start-up when a class cannot be, or is not, the root of a component scan.
+
+    The application root decides what the application is made of; a wrong one must stop
+    the start-up instead of silently scanning nothing.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class ComponentScan:
+    """Which modules make up the application, like `@ComponentScan(basePackages, excludeFilters)` in Spring.
+
+    Spring Boot scans from the package of the `@SpringBootApplication` class downwards and
+    skips what is never a component through its default filters. Here the base packages are
+    named, `default_exclude` skips Django's entry points, and `exclude` adds the application's
+    own exclusions (rarely needed). `default_exclude=()` turns the defaults off, like Spring's
+    `useDefaultFilters = false`. `auto_configuration` adds the modules through which snakeboot
+    registers its own components; an exclusion pattern can remove one, `auto_configuration=()`
+    removes them all.
+
+    `module_names()` lists plain modules only, never packages. Given a package, wireup
+    and the controller scanner import every file below it themselves, past any exclusion;
+    given only modules, both look exactly where this scan points. Finding the names
+    imports nothing, so settings can call it before Django has started.
+    """
+
+    base_packages: tuple[str, ...]
+    exclude: tuple[str, ...] = ()
+    default_exclude: tuple[str, ...] = DJANGO_ENTRY_POINTS
+    auto_configuration: tuple[str, ...] = SNAKEBOOT_AUTO_CONFIGURATION
+
+    @classmethod
+    def of(cls, application_class: type) -> "ComponentScan":
+        """Returns the scan that `@application_root` declared on `application_class`."""
+        scan = vars(application_class).get(APPLICATION_ROOT_ATTRIBUTE)
+        if not isinstance(scan, ComponentScan):
+            raise InvalidApplicationRootError(f"{application_class.__name__} is not an @application_root.")
+        return scan
+
+    def module_names(self) -> list[str]:
+        """Returns the dotted names of every module under the base packages, plus the auto-configuration, sorted.
+
+        Excluded modules are left out, auto-configuration included.
+        """
+        scanned = (name for base_package in self.base_packages for name in self._modules_under(base_package))
+        return sorted({name for name in (*scanned, *self.auto_configuration) if not self.is_excluded(name)})
+
+    def is_excluded(self, module_name: str) -> bool:
+        """Tells whether a default or an own exclusion pattern matches the module or one of its parent packages.
+
+        A pattern is a dotted name with `fnmatch` wildcards: `myapp.composition.django_project`
+        excludes that package and everything below it, `*.migrations` every migrations package.
+        """
+        return any(
+            fnmatchcase(module_name, pattern) or fnmatchcase(module_name, f"{pattern}.*")
+            for pattern in (*self.default_exclude, *self.exclude)
+        )
+
+    def _modules_under(self, package_name: str) -> Iterator[str]:
+        spec = importlib.util.find_spec(package_name)
+        if spec is None:
+            raise ModuleNotFoundError(
+                f"The component scan cannot find the package {package_name!r}.", name=package_name
+            )
+        if spec.submodule_search_locations is None:
+            yield package_name
+            return
+        for location in spec.submodule_search_locations:
+            yield from self._modules_in_directory(Path(location), package_name)
+
+    def _modules_in_directory(self, directory: Path, package_name: str) -> Iterator[str]:
+        for module in pkgutil.iter_modules([str(directory)]):
+            name = f"{package_name}.{module.name}"
+            if module.ispkg:
+                yield from self._modules_in_directory(directory / module.name, name)
+            else:
+                yield name

snakeboot/django/__init__.py

@@ -0,0 +1,5 @@
+"""Django integration: runs `@transactional` on Django's `transaction.atomic` (extra: `snakeboot[django]`)."""
+
+from snakeboot.django.django_atomic_transaction_manager import DjangoAtomicTransactionManager
+
+__all__ = ["DjangoAtomicTransactionManager"]

snakeboot/django/django_atomic_transaction_manager.py

@@ -0,0 +1,24 @@
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+from typing import override
+
+from django.db import transaction
+
+from snakeboot.transaction import TransactionManager
+
+
+class DjangoAtomicTransactionManager(TransactionManager):
+    """Opens transactions with Django's `transaction.atomic`, for the default database.
+
+    It lives in composition because choosing the transaction technology is a wiring
+    decision: the transaction library stays free of Django, and no bounded context
+    owns the database connection. Nested `@transactional` calls become savepoints.
+    """
+
+    @override
+    def atomic(self) -> AbstractContextManager[None]:
+        return transaction.atomic()
+
+    @override
+    def on_commit(self, callback: Callable[[], None]) -> None:
+        transaction.on_commit(callback, robust=True)

snakeboot/events/__init__.py

@@ -0,0 +1,33 @@
+"""Technical library: in-process application events, like Spring's `ApplicationEventPublisher`.
+
+    @application_event_listener                                    # a @Component with listener methods
+    class ParticipantNotificationListener:
+        def __init__(self, notifications: NotificationPort) -> None:   # constructor injection
+            self._notifications = notifications
+
+        @transactional_event_listener(WaitlistedParticipantPromoted)    # @TransactionalEventListener
+        def notify_promoted(self, event: WaitlistedParticipantPromoted) -> None: ...
+
+    # in a @transactional use case, after saving the aggregate:
+    self._events.publish_all(workshop.pull_events())
+
+Events are facts, never requests: a caller that needs an outcome calls a facade instead.
+The library knows wireup and `snakeboot.transaction`, but no framework and no bounded context.
+"""
+
+from snakeboot.events.application_event_listener import (
+    ApplicationEventListener,
+    InvalidApplicationEventListenerError,
+    application_event_listener,
+)
+from snakeboot.events.application_event_publisher import ApplicationEventPublisher
+from snakeboot.events.event_listener_markers import event_listener, transactional_event_listener
+
+__all__ = [
+    "ApplicationEventListener",
+    "ApplicationEventPublisher",
+    "InvalidApplicationEventListenerError",
+    "application_event_listener",
+    "event_listener",
+    "transactional_event_listener",
+]

snakeboot/events/application_event_listener.py

@@ -0,0 +1,30 @@
+from typing import Protocol
+
+from wireup import injectable
+
+
+class ApplicationEventListener(Protocol):
+    """The type under which wireup collects every listener, so the publisher receives them all.
+
+    A listener is any class whose methods carry `@event_listener` or `@transactional_event_listener`;
+    it does not inherit from this protocol. Wireup injects `Sequence[ApplicationEventListener]`.
+    """
+
+
+class InvalidApplicationEventListenerError(TypeError):
+    """Raised at start-up when a class or method cannot listen to application events.
+
+    Like a broken controller, a broken listener must stop the application from starting,
+    not fail silently at the first event.
+    """
+
+
+def application_event_listener[C: type](listener_class: C) -> C:
+    """Declares a listener: a wireup singleton whose marked methods receive published events.
+
+    Spring finds `@EventListener` methods on any bean. Here the class says it listens, so wireup
+    registers it as an `ApplicationEventListener` (qualified by its name, so several can exist)
+    and the component scan finds it like every other injectable.
+    """
+    qualifier = f"{listener_class.__module__}.{listener_class.__qualname__}"
+    return injectable(as_type=ApplicationEventListener, qualifier=qualifier)(listener_class)

snakeboot/events/application_event_publisher.py

@@ -0,0 +1,80 @@
+import inspect
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from functools import partial
+from typing import Any, Final
+
+from snakeboot.events.application_event_listener import InvalidApplicationEventListenerError
+from snakeboot.events.event_listener_markers import LISTENER_MAPPING_ATTRIBUTE, ListenerMapping
+from snakeboot.transaction import after_commit
+
+_SELF_AND_EVENT: Final = 2
+
+
+@dataclass(frozen=True, slots=True)
+class _Subscription:
+    """One listener method and the events it receives."""
+
+    name: str
+    receive: Callable[[object], None]
+    mapping: ListenerMapping
+
+    def deliver(self, event: object) -> None:
+        if self.mapping.after_commit:
+            after_commit(partial(self.receive, event))
+        else:
+            self.receive(event)
+
+
+class ApplicationEventPublisher:
+    """Hands each event to the listener methods that asked for its type (Spring's `ApplicationEventPublisher`).
+
+    It is the Observer pattern for facts: the use case that publishes does not know who
+    reacts, and a new reaction is a new listener, not a change to the use case. Delivery is
+    synchronous and in-process, in a stable order (by listener name). A listener for a base
+    class (`WorkshopEvent`) receives every subclass.
+
+    The library registers it with wireup (`application_event_publisher_injectable`), connected
+    to every listener wireup found, or to none; tests build it with the listeners they need.
+    """
+
+    def __init__(self, listeners: Iterable[object]) -> None:
+        self._subscriptions = sorted(
+            (subscription for listener in listeners for subscription in self._subscriptions_of(listener)),
+            key=lambda subscription: subscription.name,
+        )
+
+    def publish(self, event: object) -> None:
+        """Delivers `event` to every listener method for its type; immediately or after the commit."""
+        for subscription in self._subscriptions:
+            if isinstance(event, subscription.mapping.event_types):
+                subscription.deliver(event)
+
+    def publish_all(self, events: Iterable[object]) -> None:
+        """Publishes `events` in the order they happened."""
+        for event in events:
+            self.publish(event)
+
+    def _subscriptions_of(self, listener: object) -> list[_Subscription]:
+        listener_class = type(listener)
+        subscriptions = [
+            _Subscription(
+                name=f"{listener_class.__module__}.{listener_class.__qualname__}.{name}",
+                receive=self._receiver(listener, name, method),
+                mapping=mapping,
+            )
+            for name, method in inspect.getmembers(listener_class, inspect.isfunction)
+            if (mapping := getattr(method, LISTENER_MAPPING_ATTRIBUTE, None)) is not None
+        ]
+        if not subscriptions:
+            raise InvalidApplicationEventListenerError(f"{listener_class.__name__} has no listener methods.")
+        return subscriptions
+
+    def _receiver(self, listener: object, name: str, method: Callable[..., Any]) -> Callable[[object], None]:
+        owner = f"{type(listener).__name__}.{name}"
+        if inspect.iscoroutinefunction(method):
+            raise InvalidApplicationEventListenerError(f"{owner} is async; listeners are synchronous.")
+        if len(inspect.signature(method).parameters) != _SELF_AND_EVENT:
+            raise InvalidApplicationEventListenerError(f"{owner} must take exactly one argument: the event.")
+        receive: Callable[[object], None] = getattr(listener, name)
+        return receive

snakeboot/events/application_event_publisher_injectable.py

@@ -0,0 +1,24 @@
+"""Registers the one ApplicationEventPublisher with wireup, so no application has to.
+
+Spring always provides an `ApplicationEventPublisher`, with or without listeners; this
+module is the library's equivalent. A component scan that covers the library finds it;
+otherwise an application lists this module among wireup's injectables.
+"""
+
+from collections.abc import Sequence
+
+from wireup import injectable
+
+from snakeboot.events.application_event_listener import ApplicationEventListener
+from snakeboot.events.application_event_publisher import ApplicationEventPublisher
+
+
+@injectable
+def application_event_publisher(listeners: Sequence[ApplicationEventListener] = ()) -> ApplicationEventPublisher:
+    """Provides the publisher, connected to every `@application_event_listener` wireup knows.
+
+    Wireup only creates `Sequence[ApplicationEventListener]` when at least one listener
+    exists. Without the default, an application without listeners would not even start;
+    with it, wireup leaves the parameter out and the publisher simply has nobody to tell.
+    """
+    return ApplicationEventPublisher(listeners)

snakeboot/events/event_listener_markers.py

@@ -0,0 +1,41 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Final
+
+LISTENER_MAPPING_ATTRIBUTE: Final = "__application_event_listener_mapping__"
+
+type MethodMarker = Callable[[Callable[..., Any]], Callable[..., Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class ListenerMapping:
+    """What a listener marker records on a method: the events it receives and when."""
+
+    event_types: tuple[type, ...]
+    after_commit: bool
+
+
+def event_listener(*event_types: type) -> MethodMarker:
+    """Marks a method that receives `event_types` at once, inside the publisher's transaction (`@EventListener`).
+
+    Use it for work that must commit or roll back together with the change that caused the event.
+    """
+    return _mark(event_types, after_commit=False)
+
+
+def transactional_event_listener(*event_types: type) -> MethodMarker:
+    """Marks a method that receives `event_types` once the transaction has committed.
+
+    Spring: `@TransactionalEventListener(phase = AFTER_COMMIT)`. Use it for effects outside the
+    database, such as notifications: they are delivered through `after_commit`, so a rolled-back
+    change never reaches anyone, and a failing listener cannot undo the committed change.
+    """
+    return _mark(event_types, after_commit=True)
+
+
+def _mark(event_types: tuple[type, ...], *, after_commit: bool) -> MethodMarker:
+    def record(method: Callable[..., Any]) -> Callable[..., Any]:
+        setattr(method, LISTENER_MAPPING_ATTRIBUTE, ListenerMapping(event_types, after_commit))
+        return method
+
+    return record

snakeboot/rest/__init__.py

@@ -0,0 +1,47 @@
+"""Technical library: Spring-style singleton REST controllers on Django Ninja, wired by wireup.
+
+    @rest_controller("/workshops", tags=["workshops"])     # @RestController + @RequestMapping
+    class WorkshopRestController:
+        def __init__(self, enrollment: EnrollmentFacadePort) -> None:   # constructor injection
+            self._enrollment = enrollment
+
+        @route.get("/{workshop_id}", response=WorkshopViewDTO)          # @GetMapping
+        def get_workshop(self, request: HttpRequest, workshop_id: str) -> WorkshopViewDTO: ...
+
+    @rest_controller_advice                                            # @RestControllerAdvice
+    class EnrollmentRestErrorAdvice:
+        @exception_handler(WorkshopNotFoundError, status=404)            # @ExceptionHandler
+        def answer_not_found(self, error: Exception) -> dict[str, str]:
+            return error_answer(error)
+
+Composition mounts every controller and advice it finds in the modules wireup scans:
+
+    RestControllerMounter().mount(api, scan=settings.WIREUP.injectables or ())
+
+It knows Django Ninja and wireup, but nothing of the application (extra: snakeboot[ninja]).
+"""
+
+from snakeboot.rest.authenticated_principal import authenticated_principal
+from snakeboot.rest.controller_endpoint_factory import ControllerEndpointFactory
+from snakeboot.rest.error_answer import error_answer
+from snakeboot.rest.rest_controller import rest_controller
+from snakeboot.rest.rest_controller_advice import exception_handler, rest_controller_advice
+from snakeboot.rest.rest_controller_errors import InvalidRestControllerError, NoAuthenticatedPrincipalError
+from snakeboot.rest.rest_controller_mounter import MountedRestComponents, RestControllerMounter
+from snakeboot.rest.rest_controller_scanner import RestControllerScanner
+from snakeboot.rest.route_markers import route
+
+__all__ = [
+    "ControllerEndpointFactory",
+    "InvalidRestControllerError",
+    "MountedRestComponents",
+    "NoAuthenticatedPrincipalError",
+    "RestControllerMounter",
+    "RestControllerScanner",
+    "authenticated_principal",
+    "error_answer",
+    "exception_handler",
+    "rest_controller",
+    "rest_controller_advice",
+    "route",
+]

snakeboot/rest/authenticated_principal.py

@@ -0,0 +1,15 @@
+from django.http import HttpRequest
+
+from snakeboot.rest.rest_controller_errors import NoAuthenticatedPrincipalError
+
+
+def authenticated_principal(request: HttpRequest) -> str:
+    """Returns the id that the API's authentication stored on `request.auth` (Spring: `@AuthenticationPrincipal`).
+
+    Ninja adds `auth` to the request at run time, so a type checker cannot see it. This is
+    the one place that reads it, so controllers stay fully typed.
+    """
+    principal = request.auth  # type: ignore[attr-defined]
+    if not isinstance(principal, str):
+        raise NoAuthenticatedPrincipalError(f"Expected the id of a signed-in principal, got {principal!r}.")
+    return principal

snakeboot/rest/controller_endpoint_factory.py

@@ -0,0 +1,72 @@
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from django.http import HttpRequest, HttpResponse
+from ninja import NinjaAPI
+from wireup.integration.django import get_request_container
+
+from snakeboot.rest.rest_controller_errors import InvalidRestControllerError
+
+ControllerResolver = Callable[[type], object]
+ErrorAnswer = Callable[[HttpRequest, Exception], HttpResponse]
+
+
+def resolve_from_wireup_request_scope(controller_class: type) -> object:
+    """Asks wireup for the controller during the current request; a singleton is the same object every time."""
+    return get_request_container().get(controller_class)
+
+
+class ControllerEndpointFactory:
+    """Turns one controller or advice method into a function Django Ninja can call.
+
+    Ninja inspects a view's signature to read path, query and body parameters. A method
+    has `self` in front, which Ninja would take for a query parameter, so the endpoint
+    shows Ninja the signature *without* `self`. When called, the endpoint asks the
+    resolver for the controller instance and calls the method on it.
+
+    Resolving per call (not once at start-up) keeps two things working: wireup's
+    request scope under both WSGI and ASGI, and wireup overrides in tests.
+    """
+
+    def __init__(self, resolve_controller: ControllerResolver = resolve_from_wireup_request_scope) -> None:
+        self._resolve_controller = resolve_controller
+
+    def create(self, controller_class: type, method: Callable[..., Any]) -> Callable[..., Any]:
+        """Returns the Ninja view for `method` of `controller_class`."""
+        signature = inspect.signature(method)
+        parameters_after_self = self._parameters_after_self(controller_class, method)
+        resolve_controller = self._resolve_controller
+
+        @functools.wraps(method)
+        def endpoint(*args: Any, **kwargs: Any) -> Any:
+            return method(resolve_controller(controller_class), *args, **kwargs)
+
+        endpoint.__signature__ = signature.replace(parameters=parameters_after_self)  # type: ignore[attr-defined]
+        return endpoint
+
+    def create_error_answer(
+        self, advice_class: type, method: Callable[..., Any], *, api: NinjaAPI, status: int
+    ) -> ErrorAnswer:
+        """Returns the Ninja exception handler that answers with `status` and the body `method` builds."""
+        self._parameters_after_self(advice_class, method)
+        resolve_advice = self._resolve_controller
+
+        def answer(request: HttpRequest, error: Exception) -> HttpResponse:
+            body = method(resolve_advice(advice_class), error)
+            return api.create_response(request, body, status=status)
+
+        return answer
+
+    def _parameters_after_self(self, owner: type, method: Callable[..., Any]) -> list[inspect.Parameter]:
+        if inspect.iscoroutinefunction(method):
+            raise InvalidRestControllerError(
+                f"{owner.__name__}.{method.__name__} is async; controller endpoints are synchronous."
+            )
+        parameters = list(inspect.signature(method).parameters.values())
+        if not parameters or parameters[0].name != "self":
+            raise InvalidRestControllerError(
+                f"{owner.__name__}.{method.__name__} must be a regular method taking `self` first."
+            )
+        return parameters[1:]

snakeboot/rest/error_answer.py

@@ -0,0 +1,14 @@
+import re
+from typing import Final
+
+_WORD_BOUNDARY: Final = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+def error_answer(error: Exception) -> dict[str, str]:
+    """Builds the error body `{"code": ..., "detail": ...}`, the shape of Spring's `ProblemDetail` in small.
+
+    `code` is derived from the class name (`AlreadyRegisteredError` -> `already_registered`),
+    so a client can rely on it; `detail` is the message, meant for developers.
+    """
+    name = type(error).__name__.removesuffix("Error")
+    return {"code": _WORD_BOUNDARY.sub("_", name).lower(), "detail": str(error)}

snakeboot/rest/rest_controller.py

@@ -0,0 +1,25 @@
+from collections.abc import Callable, Sequence
+
+from wireup import injectable
+
+from snakeboot.rest.rest_controller_errors import InvalidRestControllerError
+from snakeboot.rest.rest_controller_mappings import CONTROLLER_MAPPING_ATTRIBUTE, ControllerMapping
+
+
+def rest_controller[C: type](prefix: str, *, tags: Sequence[str] = ()) -> Callable[[C], C]:
+    """Declares a REST controller, like Spring's `@RestController` with `@RequestMapping(prefix)`.
+
+    The class becomes a wireup singleton (do not add `@injectable` yourself): its
+    constructor receives facade ports by type, it is created once, and the container
+    refuses to start when a dependency is missing. RestControllerMounter finds it by
+    scanning and turns its `@route` methods into Ninja endpoints under `prefix`.
+    """
+    if prefix != "" and not prefix.startswith("/"):
+        raise InvalidRestControllerError(f"A controller prefix starts with '/', got {prefix!r}.")
+
+    def declare(controller_class: C) -> C:
+        mapping = ControllerMapping(prefix=prefix, tags=tuple(tags) or (controller_class.__name__,))
+        setattr(controller_class, CONTROLLER_MAPPING_ATTRIBUTE, mapping)
+        return injectable(controller_class)
+
+    return declare