austial-core 0.1.5__tar.gz

austial_core-0.1.5/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.db
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/

austial_core-0.1.5/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: austial-core
+Version: 0.1.5
+Summary: The DI container, module scanner, router and application bootstrap -- mirrors @nestjs/core.
+Requires-Python: >=3.11
+Requires-Dist: austial-common
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: starlette
+Requires-Dist: uvicorn[standard]>=0.30.0

austial_core-0.1.5/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "austial-core"
+dynamic = ["version"]
+description = "The DI container, module scanner, router and application bootstrap -- mirrors @nestjs/core."
+requires-python = ">=3.11"
+dependencies = [
+    "austial-common",
+    "fastapi>=0.115.0",
+    "starlette",
+    "uvicorn[standard]>=0.30.0",
+    "python-multipart>=0.0.9",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/austial"]
+
+[tool.uv.sources]
+austial-common = { workspace = true }
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+root = "../.."

austial_core-0.1.5/src/austial/core/__init__.py

@@ -0,0 +1,19 @@
+"""Kept intentionally lightweight (no imports of ``app``/``factory``/``router_builder``)
+so that low-level modules like ``austial.core.metadata`` can be imported from
+deep within ``austial.common.decorators`` without triggering a circular import.
+``AustialApplication``/``AustialFactory`` are imported directly from
+``austial.core.app`` / ``austial.core.factory`` by ``austial/__init__.py``,
+*after* ``austial.common`` has fully loaded.
+"""
+
+from austial.core.container import CircularDependencyError, Container, ProviderNotFoundError
+from austial.core.dynamic_module import DynamicModule
+from austial.core.reflector import Reflector
+
+__all__ = [
+    "Container",
+    "ProviderNotFoundError",
+    "CircularDependencyError",
+    "DynamicModule",
+    "Reflector",
+]

austial_core-0.1.5/src/austial/core/app.py

@@ -0,0 +1,155 @@
+"""``AustialApplication`` -- mirrors the object returned by
+``NestFactory.create()``. Wraps a real FastAPI/Starlette app so it's a drop-in
+ASGI target (``uvicorn src.main:app``) *and* offers Nest's programmatic API
+(``app.listen()``, ``app.use_global_pipes()``, ...)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from austial.common.exceptions.http_exceptions import BadRequestException
+from austial.common.filters.all_exceptions_filter import AllExceptionsFilter
+from austial.common.logger import Logger
+from austial.core.container import Container
+from austial.core.exception_dispatch import dispatch_exception
+from austial.core.router_builder import RouterBuilder
+
+_logger = Logger("NestApplication")
+
+
+class AustialApplication:
+    def __init__(self, container: Container, fastapi_app: FastAPI, controllers: list, middleware_bindings: list):
+        self._container = container
+        self._fastapi_app = fastapi_app
+        self._controllers = controllers
+        self._middleware_bindings = middleware_bindings
+
+        self._global_guards: list = []
+        self._global_pipes: list = []
+        self._global_interceptors: list = []
+        self._global_filters: list = []
+        self._routes_built = False
+
+        self._install_fallback_exception_handlers()
+        self._install_middleware()
+
+    # -- Nest-shaped configuration API ------------------------------------------------
+    def use_global_pipes(self, *pipes: Any) -> AustialApplication:
+        self._global_pipes.extend(pipes)
+        return self
+
+    def use_global_guards(self, *guards: Any) -> AustialApplication:
+        self._global_guards.extend(guards)
+        return self
+
+    def use_global_interceptors(self, *interceptors: Any) -> AustialApplication:
+        self._global_interceptors.extend(interceptors)
+        return self
+
+    def use_global_filters(self, *filters: Any) -> AustialApplication:
+        self._global_filters.extend(filters)
+        return self
+
+    def enable_cors(self, **kwargs: Any) -> AustialApplication:
+        defaults = dict(allow_origins=["*"], allow_methods=["*"], allow_headers=["*"], allow_credentials=True)
+        defaults.update(kwargs)
+        self._fastapi_app.add_middleware(CORSMiddleware, **defaults)  # type: ignore[arg-type]
+        return self
+
+    def get(self, token: Any) -> Any:
+        """Fetches a resolved provider straight out of the DI container,
+        mirroring Nest's ``app.get(Token)``."""
+        return self._container.resolve(token)
+
+    def get_http_adapter(self) -> FastAPI:
+        """Returns the underlying FastAPI instance, mirroring Nest's
+        ``app.getHttpAdapter().getInstance()``."""
+        return self._fastapi_app
+
+    # -- lifecycle ---------------------------------------------------------------------
+    async def init(self) -> AustialApplication:
+        """Builds routes without starting a server -- mirrors Nest's
+        ``await app.init()``, the entry point ``@nestjs/testing`` e2e tests use
+        alongside ``request(app.getHttpServer())``."""
+        self._build_routes()
+        return self
+
+    def _build_routes(self) -> None:
+        if self._routes_built:
+            return
+        builder = RouterBuilder(
+            self._container,
+            global_guards=self._global_guards,
+            global_pipes=self._global_pipes,
+            global_interceptors=self._global_interceptors,
+            global_filters=self._global_filters,
+        )
+        router = builder.build(self._controllers)
+        self._fastapi_app.include_router(router)
+        self._routes_built = True
+
+    def _install_fallback_exception_handlers(self) -> None:
+        async def handle_validation_error(request: Request, exc: RequestValidationError) -> Response:
+            converted = BadRequestException({"message": exc.errors(), "error": "Bad Request"})
+            filters = self._global_filters or [AllExceptionsFilter()]
+            return await dispatch_exception(converted, request, filters)
+
+        async def handle_uncaught(request: Request, exc: Exception) -> Response:
+            filters = self._global_filters or [AllExceptionsFilter()]
+            return await dispatch_exception(exc, request, filters)
+
+        self._fastapi_app.add_exception_handler(RequestValidationError, handle_validation_error)  # type: ignore[arg-type]
+        self._fastapi_app.add_exception_handler(Exception, handle_uncaught)
+
+    def _install_middleware(self) -> None:
+        if not self._middleware_bindings:
+            return
+        bindings = self._middleware_bindings
+
+        class _MiddlewareDispatcher(BaseHTTPMiddleware):
+            async def dispatch(self, request: Request, call_next):
+                applicable = [b for b in bindings if b.matches(request.url.path)]
+                if not applicable:
+                    return await call_next(request)
+
+                chain = call_next
+
+                def make_step(mw_instance, downstream):
+                    async def step(req: Request):
+                        return await mw_instance.use(req, lambda: downstream(req))
+
+                    return step
+
+                for binding in reversed(applicable):
+                    for mw_instance in reversed(binding.middlewares):
+                        chain = make_step(mw_instance, chain)
+
+                return await chain(request)
+
+        self._fastapi_app.add_middleware(_MiddlewareDispatcher)
+
+    async def listen(self, port: int = 8000, host: str = "0.0.0.0") -> None:
+        """Boots an ASGI server in-process, mirroring Nest's ``await app.listen(3000)``."""
+        await self.init()
+        self._print_startup_banner(port)
+        config = uvicorn.Config(self._fastapi_app, host=host, port=port, log_level="warning")
+        server = uvicorn.Server(config)
+        await server.serve()
+
+    def _print_startup_banner(self, port: int) -> None:
+        _logger.log("Starting Austial application...", context="NestFactory")
+        _logger.log("AppModule dependencies initialized", context="InstanceLoader")
+        _logger.log(f"Austial application successfully started on port {port}", context="NestApplication")
+
+    # -- ASGI passthrough, so `uvicorn src.main:app` works too --------------------------
+    async def __call__(self, scope, receive, send) -> None:
+        self._build_routes()
+        await self._fastapi_app(scope, receive, send)

austial_core-0.1.5/src/austial/core/container.py

@@ -0,0 +1,161 @@
+"""The DI container -- mirrors Nest's ``IoC`` container.
+
+Providers are resolved from constructor type hints, recursively, with a
+singleton cache by default (``Scope.TRANSIENT`` opts a provider out of
+caching). Supports Nest's three "custom provider" shapes as plain dicts:
+``{"provide": TOKEN, "useValue": ...}``, ``{"provide": TOKEN, "useClass": ...}``,
+``{"provide": TOKEN, "useFactory": fn, "inject": [...]}``.
+"""
+
+from __future__ import annotations
+
+import inspect
+import typing
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from austial.common.decorators.injectable import InjectMarker, OptionalMarker
+from austial.common.enums import Scope
+from austial.core.metadata import INJECTABLE_METADATA, get_metadata
+
+_UNSET = object()
+
+
+class ProviderNotFoundError(Exception):
+    def __init__(self, token: Any):
+        name = getattr(token, "__name__", token)
+        super().__init__(
+            f"Nest can't resolve dependency '{name}'. Is it registered in a "
+            f"module's `providers=[...]` (or `exports=[...]` of an imported module)?"
+        )
+        self.token = token
+
+
+class CircularDependencyError(Exception):
+    def __init__(self, token: Any):
+        name = getattr(token, "__name__", token)
+        super().__init__(f"Circular dependency detected while resolving '{name}'.")
+
+
+@dataclass
+class ProviderDefinition:
+    token: Any
+    use_class: type | None = None
+    use_value: Any = _UNSET
+    use_factory: Callable | None = None
+    inject: Sequence[Any] = field(default_factory=list)
+    scope: Scope = Scope.DEFAULT
+
+
+class Container:
+    """One container per application. Every module's providers/controllers
+    register into the same container (Nest's DI graph is application-wide
+    too, scoped by module `exports`/`imports` only at the *visibility* level,
+    which Austial does not currently enforce for simplicity)."""
+
+    def __init__(self):
+        self._definitions: dict[Any, ProviderDefinition] = {}
+        self._singletons: dict[Any, Any] = {}
+
+    def register(self, provider: Any) -> ProviderDefinition:
+        definition = self._normalize(provider)
+        self._definitions[definition.token] = definition
+        return definition
+
+    def has(self, token: Any) -> bool:
+        return token in self._definitions or token in self._singletons
+
+    def set_instance(self, token: Any, instance: Any) -> None:
+        """Registers an already-built instance under `token` (used for
+        controllers, which the router builder constructs itself)."""
+        self._singletons[token] = instance
+        self._definitions.setdefault(token, ProviderDefinition(token=token, use_value=instance))
+
+    def _normalize(self, provider: Any) -> ProviderDefinition:
+        if isinstance(provider, dict):
+            token = provider["provide"]
+            if "useValue" in provider:
+                return ProviderDefinition(token=token, use_value=provider["useValue"])
+            if "useClass" in provider:
+                use_class = provider["useClass"]
+                scope = get_metadata(INJECTABLE_METADATA, use_class, {}).get("scope", Scope.DEFAULT)
+                return ProviderDefinition(token=token, use_class=use_class, scope=scope)
+            if "useFactory" in provider:
+                return ProviderDefinition(
+                    token=token, use_factory=provider["useFactory"], inject=provider.get("inject", [])
+                )
+            raise ValueError(f"Invalid provider definition: {provider!r}")
+        # Plain class shorthand, e.g. `providers=[HealthService]`.
+        scope = get_metadata(INJECTABLE_METADATA, provider, {}).get("scope", Scope.DEFAULT)
+        return ProviderDefinition(token=provider, use_class=provider, scope=scope)
+
+    def resolve(self, token: Any, *, _resolving: frozenset = frozenset()) -> Any:
+        if token in self._singletons:
+            return self._singletons[token]
+
+        definition = self._definitions.get(token)
+        if definition is None:
+            if isinstance(token, type):
+                # Auto-register unregistered `@Injectable` classes encountered
+                # only as a nested constructor dependency -- keeps things
+                # working even if a provider was forgotten in `providers=[]`.
+                definition = self.register(token)
+            else:
+                raise ProviderNotFoundError(token)
+
+        if token in _resolving:
+            raise CircularDependencyError(token)
+        next_resolving = _resolving | {token}
+
+        instance = self._instantiate(definition, next_resolving)
+        if definition.scope == Scope.DEFAULT:
+            self._singletons[token] = instance
+        return instance
+
+    def _instantiate(self, definition: ProviderDefinition, resolving: frozenset) -> Any:
+        if definition.use_value is not _UNSET:
+            return definition.use_value
+        if definition.use_factory is not None:
+            deps = [self.resolve(tok, _resolving=resolving) for tok in definition.inject]
+            return definition.use_factory(*deps)
+        assert definition.use_class is not None
+        kwargs = self._resolve_constructor_args(definition.use_class, resolving)
+        return definition.use_class(**kwargs)
+
+    def _resolve_constructor_args(self, cls: type, resolving: frozenset) -> dict:
+        init = cls.__init__  # type: ignore[misc]  # deliberately dynamic: `cls` is any registered provider class
+        if init is object.__init__:
+            return {}
+        try:
+            hints = typing.get_type_hints(init)
+        except Exception:
+            hints = {}
+        signature = inspect.signature(init)
+        kwargs: dict[str, Any] = {}
+        for name, param in signature.parameters.items():
+            if name == "self" or param.kind in (
+                inspect.Parameter.VAR_POSITIONAL,
+                inspect.Parameter.VAR_KEYWORD,
+            ):
+                continue
+
+            default = param.default
+            if isinstance(default, InjectMarker):
+                kwargs[name] = self.resolve(default.token, _resolving=resolving)
+                continue
+            if isinstance(default, OptionalMarker):
+                hint = hints.get(name)
+                try:
+                    kwargs[name] = self.resolve(hint, _resolving=resolving) if hint else None
+                except ProviderNotFoundError:
+                    kwargs[name] = None
+                continue
+
+            hint = hints.get(name)
+            if hint is not None:
+                kwargs[name] = self.resolve(hint, _resolving=resolving)
+            elif default is inspect.Parameter.empty:
+                raise ProviderNotFoundError(name)
+            # else: no annotation, has its own default -> let the class use it.
+        return kwargs

austial_core-0.1.5/src/austial/core/dynamic_module.py

@@ -0,0 +1,22 @@
+"""``DynamicModule`` -- mirrors Nest's dynamic module pattern
+(``ConfigModule.forRoot()``, ``TypeOrmModule.forRootAsync()``, ...).
+
+A module class exposes a classmethod (conventionally ``for_root`` /
+``for_root_async`` / ``register``) that returns a ``DynamicModule`` describing
+extra providers/controllers/imports/exports to merge in at that import site,
+instead of (or in addition to) whatever static ``@Module(...)`` metadata the
+class itself carries.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DynamicModule:
+    module: type | None = None
+    imports: list = field(default_factory=list)
+    controllers: list = field(default_factory=list)
+    providers: list = field(default_factory=list)
+    exports: list = field(default_factory=list)

austial_core-0.1.5/src/austial/core/exception_dispatch.py

@@ -0,0 +1,23 @@
+"""Shared "find the right exception filter and call it" logic, used both
+inside route handlers (:mod:`austial.core.router_builder`) and as the
+application-level fallback for errors FastAPI itself raises before a route
+handler ever runs (e.g. request validation failures)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from starlette.requests import Request
+from starlette.responses import Response
+
+from austial.common.filters.base import ArgumentsHost
+from austial.core.metadata import CATCH_METADATA, get_metadata
+
+
+async def dispatch_exception(exc: BaseException, request: Request, filters: Sequence) -> Response:
+    host = ArgumentsHost(request)
+    for exception_filter in filters:
+        catch_types = get_metadata(CATCH_METADATA, type(exception_filter), ())
+        if not catch_types or isinstance(exc, catch_types):
+            return await exception_filter.catch(exc, host)
+    raise exc

austial_core-0.1.5/src/austial/core/factory.py

@@ -0,0 +1,43 @@
+"""``AustialFactory`` -- mirrors ``NestFactory``."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from austial.common.middleware.base import MiddlewareBinding, MiddlewareConsumer
+from austial.core.app import AustialApplication
+from austial.core.container import Container
+from austial.core.module_scanner import scan_module
+
+
+class AustialFactory:
+    @staticmethod
+    def create(
+        root_module: type,
+        *,
+        title: str = "Austial",
+        version: str = "0.1.0",
+        description: str = "Built with the Austial framework.",
+    ) -> AustialApplication:
+        container = Container()
+        scan_result = scan_module(root_module, container)
+
+        fastapi_app = FastAPI(title=title, version=version, description=description)
+
+        middleware_bindings: list[MiddlewareBinding] = []
+        for module_cls in scan_result.modules:
+            configure = getattr(module_cls, "configure", None)
+            if configure is None:
+                continue
+            module_instance = container.resolve(module_cls)
+            consumer = MiddlewareConsumer()
+            module_instance.configure(consumer)
+            resolved_bindings = []
+            for binding in consumer.bindings:
+                resolved_middlewares = [
+                    container.resolve(mw) if isinstance(mw, type) else mw for mw in binding.middlewares
+                ]
+                resolved_bindings.append(MiddlewareBinding(middlewares=resolved_middlewares, routes=binding.routes))
+            middleware_bindings.extend(resolved_bindings)
+
+        return AustialApplication(container, fastapi_app, scan_result.controllers, middleware_bindings)

austial_core-0.1.5/src/austial/core/metadata.py

@@ -0,0 +1,65 @@
+"""
+Metadata storage, modeled after Nest's `@SetMetadata()` / `Reflect.defineMetadata`.
+
+Every decorator in Austial (``@Module``, ``@Controller``, ``@Get``, ``@UseGuards``,
+...) ultimately calls :func:`set_metadata` to stash data directly on the
+decorated class or function. :class:`Reflector` (see ``reflector.py``) is the
+public, Nest-shaped API for reading it back out.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_METADATA_ATTR = "__austial_metadata__"
+
+# Well-known metadata keys used across the framework.
+MODULE_METADATA = "austial:module"
+CONTROLLER_METADATA = "austial:controller"
+INJECTABLE_METADATA = "austial:injectable"
+ROUTE_METADATA = "austial:route"
+GUARDS_METADATA = "austial:guards"
+INTERCEPTORS_METADATA = "austial:interceptors"
+PIPES_METADATA = "austial:pipes"
+FILTERS_METADATA = "austial:filters"
+HTTP_CODE_METADATA = "austial:http_code"
+HEADER_METADATA = "austial:header"
+INJECT_TOKENS_METADATA = "austial:inject_tokens"
+CATCH_METADATA = "austial:catch"
+
+
+def _bucket(target: Any) -> dict:
+    bucket = target.__dict__.get(_METADATA_ATTR)
+    if bucket is None:
+        bucket = {}
+        setattr(target, _METADATA_ATTR, bucket)
+    return bucket
+
+
+def set_metadata(key: str, value: Any):
+    """Decorator factory: attaches ``value`` under ``key`` on the decorated target.
+
+    Mirrors Nest's ``@SetMetadata(key, value)``. Can decorate classes or
+    functions/methods, and is also usable directly as ``set_metadata(k, v)(target)``.
+    """
+
+    def decorator(target):
+        _bucket(target)[key] = value
+        return target
+
+    return decorator
+
+
+def get_metadata(key: str, target: Any, default: Any = None) -> Any:
+    """Reads a single metadata value previously stashed with :func:`set_metadata`."""
+    if target is None:
+        return default
+    bucket = getattr(target, _METADATA_ATTR, None)
+    if bucket is None:
+        return default
+    return bucket.get(key, default)
+
+
+def has_metadata(key: str, target: Any) -> bool:
+    bucket = getattr(target, _METADATA_ATTR, None)
+    return bucket is not None and key in bucket

austial_core-0.1.5/src/austial/core/module_scanner.py

@@ -0,0 +1,62 @@
+"""Walks the ``@Module`` import graph from the root ``AppModule``, registering
+every provider/controller into the DI :class:`~austial.core.container.Container`
+and collecting the flat list of controllers + modules for the router builder
+and the middleware system."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from austial.core.container import Container
+from austial.core.dynamic_module import DynamicModule
+from austial.core.metadata import MODULE_METADATA, get_metadata
+
+
+@dataclass
+class ScanResult:
+    controllers: list = field(default_factory=list)
+    modules: list = field(default_factory=list)
+
+
+def scan_module(root_module: type, container: Container) -> ScanResult:
+    visited: set[type] = set()
+    controllers: list = []
+    modules_in_order: list = []
+
+    def visit(entry: Any) -> None:
+        if isinstance(entry, DynamicModule):
+            for provider in entry.providers:
+                container.register(provider)
+            for controller in entry.controllers:
+                container.register(controller)
+                controllers.append(controller)
+            for imported in entry.imports:
+                visit(imported)
+            if entry.module is not None:
+                visit(entry.module)
+            return
+
+        module_cls = entry
+        if module_cls in visited:
+            return
+        visited.add(module_cls)
+
+        metadata = get_metadata(MODULE_METADATA, module_cls)
+        if metadata is None:
+            raise TypeError(f"{module_cls!r} is not decorated with @Module(...)")
+
+        for imported in metadata.imports:
+            visit(imported)
+
+        for provider in metadata.providers:
+            container.register(provider)
+
+        for controller in metadata.controllers:
+            container.register(controller)
+            controllers.append(controller)
+
+        modules_in_order.append(module_cls)
+
+    visit(root_module)
+    return ScanResult(controllers=controllers, modules=modules_in_order)

austial_core-0.1.5/src/austial/core/reflector.py

@@ -0,0 +1,38 @@
+"""Reflector: the public, Nest-shaped API for reading decorator metadata back out."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from austial.core.metadata import get_metadata
+
+
+class Reflector:
+    """Mirrors ``@nestjs/core``'s ``Reflector``.
+
+    Usable as an injectable (constructor-injected into guards/interceptors)
+    or via its static helpers.
+    """
+
+    def get(self, key: str, target: Any, default: Any = None) -> Any:
+        return get_metadata(key, target, default)
+
+    def get_all_and_merge(self, key: str, targets: Sequence[Any]) -> list:
+        """Merges array-valued metadata (e.g. guards/interceptors) across
+        class + method, matching Nest's ``getAllAndMerge``."""
+        merged: list = []
+        for target in targets:
+            value = get_metadata(key, target, [])
+            if value:
+                merged.extend(value)
+        return merged
+
+    def get_all_and_override(self, key: str, targets: Sequence[Any]) -> Any:
+        """Returns the first non-empty metadata value found, method before
+        class, matching Nest's ``getAllAndOverride``."""
+        for target in targets:
+            value = get_metadata(key, target, None)
+            if value is not None:
+                return value
+        return None

austial_core-0.1.5/src/austial/core/router_builder.py

@@ -0,0 +1,184 @@
+"""Walks the resolved controller list and builds real ``fastapi.APIRouter``s
+out of them, wiring the full Nest-style request pipeline around each handler:
+
+    guards -> pipes -> interceptors (wrapping) -> handler -> exception filters
+
+This is the piece that makes ``@Controller``/``@Get``/``@UseGuards``/etc. do
+something, instead of just being inert metadata.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+
+from fastapi import APIRouter, Request, Response
+
+from austial.common.decorators.controllers import ControllerMetadata, RouteMetadata
+from austial.common.exceptions.http_exceptions import ForbiddenException
+from austial.common.filters.all_exceptions_filter import AllExceptionsFilter
+from austial.common.guards.base import ExecutionContext
+from austial.common.interceptors.base import CallHandler
+from austial.common.logger import Logger
+from austial.common.pipes.validation_pipe import ArgumentMetadata
+from austial.core.container import Container
+from austial.core.exception_dispatch import dispatch_exception
+from austial.core.metadata import (
+    CONTROLLER_METADATA,
+    FILTERS_METADATA,
+    GUARDS_METADATA,
+    HEADER_METADATA,
+    HTTP_CODE_METADATA,
+    INTERCEPTORS_METADATA,
+    PIPES_METADATA,
+    ROUTE_METADATA,
+    get_metadata,
+)
+
+_logger = Logger("RoutesResolver")
+
+_REQUEST_PARAM_NAME = "__austial_request__"
+_RESPONSE_PARAM_NAME = "__austial_response__"
+_DEFAULT_STATUS = {"POST": 201}
+
+
+class RouterBuilder:
+    def __init__(
+        self,
+        container: Container,
+        *,
+        global_guards: list | None = None,
+        global_pipes: list | None = None,
+        global_interceptors: list | None = None,
+        global_filters: list | None = None,
+    ):
+        self._container = container
+        self._global_guards = global_guards or []
+        self._global_pipes = global_pipes or []
+        self._global_interceptors = global_interceptors or []
+        self._global_filters = global_filters or []
+
+    def build(self, controllers: list[type]) -> APIRouter:
+        root_router = APIRouter()
+        for controller_cls in controllers:
+            self._register_controller(root_router, controller_cls)
+        return root_router
+
+    def _register_controller(self, root_router: APIRouter, controller_cls: type) -> None:
+        controller_meta: ControllerMetadata = get_metadata(CONTROLLER_METADATA, controller_cls) or ControllerMetadata()
+        instance = self._container.resolve(controller_cls)
+        tags = controller_meta.tags or [controller_cls.__name__.replace("Controller", "") or controller_cls.__name__]
+        router = APIRouter(prefix=controller_meta.prefix, tags=tags)
+
+        for name, member in vars(controller_cls).items():
+            if not callable(member):
+                continue
+            route_meta: RouteMetadata | None = get_metadata(ROUTE_METADATA, member)
+            if route_meta is None:
+                continue
+            bound_handler = getattr(instance, name)
+            self._register_route(router, controller_meta, controller_cls, bound_handler, route_meta)
+            full_path = f"{controller_meta.prefix}{route_meta.path}" or "/"
+            _logger.log(f"Mapped {{{route_meta.method}, {full_path}}} route", context="RoutesResolver")
+
+        root_router.include_router(router)
+
+    def _resolve_chain(
+        self,
+        key: str,
+        controller_cls: type,
+        handler: Callable,
+        globals_list: list,
+        default: list | None = None,
+    ) -> list:
+        raw = list(globals_list)
+        raw += get_metadata(key, controller_cls, [])
+        raw += get_metadata(key, handler, [])
+        if not raw and default:
+            raw = list(default)
+        resolved = []
+        for item in raw:
+            resolved.append(self._container.resolve(item) if isinstance(item, type) else item)
+        return resolved
+
+    def _register_route(
+        self,
+        router: APIRouter,
+        controller_meta: ControllerMetadata,
+        controller_cls: type,
+        handler: Callable,
+        route_meta: RouteMetadata,
+    ) -> None:
+        guards = self._resolve_chain(GUARDS_METADATA, controller_cls, handler, self._global_guards)
+        interceptors = self._resolve_chain(INTERCEPTORS_METADATA, controller_cls, handler, self._global_interceptors)
+        pipes = self._resolve_chain(PIPES_METADATA, controller_cls, handler, self._global_pipes)
+        filters = self._resolve_chain(
+            FILTERS_METADATA, controller_cls, handler, self._global_filters, default=[AllExceptionsFilter()]
+        )
+
+        status_code = get_metadata(HTTP_CODE_METADATA, handler) or _DEFAULT_STATUS.get(route_meta.method, 200)
+        headers_meta = get_metadata(HEADER_METADATA, handler, {})
+
+        endpoint = self._build_endpoint(controller_cls, handler, guards, interceptors, pipes, filters, headers_meta)
+
+        path = route_meta.path or ("/" if not controller_meta.prefix else "")
+        router.add_api_route(path, endpoint, methods=[route_meta.method], status_code=status_code)
+
+    @staticmethod
+    def _wrap_interceptor(interceptor, context: ExecutionContext, next_call: Callable):
+        async def wrapped():
+            return await interceptor.intercept(context, CallHandler(next_call))
+
+        return wrapped
+
+    def _build_endpoint(
+        self,
+        controller_cls: type,
+        handler: Callable,
+        guards: list,
+        interceptors: list,
+        pipes: list,
+        filters: list,
+        headers_meta: dict,
+    ) -> Callable:
+        original_sig = inspect.signature(handler)  # bound method -> `self` already excluded
+        request_param = inspect.Parameter(_REQUEST_PARAM_NAME, kind=inspect.Parameter.KEYWORD_ONLY, annotation=Request)
+        response_param = inspect.Parameter(
+            _RESPONSE_PARAM_NAME, kind=inspect.Parameter.KEYWORD_ONLY, annotation=Response
+        )
+        new_sig = original_sig.replace(parameters=[*original_sig.parameters.values(), request_param, response_param])
+        is_coroutine = inspect.iscoroutinefunction(handler)
+
+        async def endpoint(**kwargs):
+            request: Request = kwargs.pop(_REQUEST_PARAM_NAME)
+            response: Response = kwargs.pop(_RESPONSE_PARAM_NAME)
+            context = ExecutionContext(request, controller_cls, handler)
+
+            try:
+                for guard in guards:
+                    if not await guard.can_activate(context):
+                        raise ForbiddenException("Forbidden resource")
+
+                for name, value in list(kwargs.items()):
+                    metadata = ArgumentMetadata(type="custom", data=name, metatype=type(value))
+                    for pipe in pipes:
+                        value = pipe.transform(value, metadata)
+                    kwargs[name] = value
+
+                async def call_handler():
+                    return await handler(**kwargs) if is_coroutine else handler(**kwargs)
+
+                chain = call_handler
+                for interceptor in reversed(interceptors):
+                    chain = self._wrap_interceptor(interceptor, context, chain)
+
+                result = await chain()
+                for key, value in headers_meta.items():
+                    response.headers[key] = value
+                return result
+            except Exception as exc:  # noqa: BLE001 - dispatched to exception filters below
+                return await dispatch_exception(exc, request, filters)
+
+        endpoint.__signature__ = new_sig  # type: ignore[attr-defined]  # FastAPI reads this to build the OpenAPI schema
+        endpoint.__name__ = getattr(handler, "__name__", "endpoint")
+        return endpoint