austial-common 0.1.5__tar.gz

austial_common-0.1.5/.gitignore

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

austial_common-0.1.5/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: austial-common
+Version: 0.1.5
+Summary: Decorators, exceptions, pipes, guards and other symbols shared across Austial -- mirrors @nestjs/common.
+Requires-Python: >=3.11
+Requires-Dist: austial-core
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: starlette

austial_common-0.1.5/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "austial-common"
+dynamic = ["version"]
+description = "Decorators, exceptions, pipes, guards and other symbols shared across Austial -- mirrors @nestjs/common."
+requires-python = ">=3.11"
+dependencies = [
+    "austial-core",
+    "fastapi>=0.115.0",
+    "pydantic>=2.7.0",
+    "rich>=13.7.0",
+    "starlette",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/austial"]
+
+[tool.uv.sources]
+austial-core = { workspace = true }
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+root = "../.."

austial_common-0.1.5/src/austial/common/__init__.py

@@ -0,0 +1,106 @@
+from austial.common.decorators import (
+    Body,
+    Catch,
+    Controller,
+    Delete,
+    Get,
+    Global,
+    Head,
+    Header,
+    Headers,
+    HttpCode,
+    Inject,
+    Injectable,
+    Module,
+    Optional_,
+    Options,
+    Param,
+    Patch,
+    Post,
+    Put,
+    Query,
+    Req,
+    Res,
+    UseFilters,
+    UseGuards,
+    UseInterceptors,
+    UsePipes,
+)
+from austial.common.enums import Scope
+from austial.common.exceptions import (
+    BadRequestException,
+    ConflictException,
+    ForbiddenException,
+    HttpException,
+    InternalServerErrorException,
+    MethodNotAllowedException,
+    NotFoundException,
+    NotImplementedException,
+    ServiceUnavailableException,
+    TooManyRequestsException,
+    UnauthorizedException,
+    UnprocessableEntityException,
+)
+from austial.common.filters import AllExceptionsFilter, ArgumentsHost, ExceptionFilter
+from austial.common.guards import CanActivate, ExecutionContext
+from austial.common.interceptors import CallHandler, NestInterceptor, TransformInterceptor
+from austial.common.logger import Logger
+from austial.common.middleware import LoggingMiddleware, MiddlewareConsumer, NestMiddleware
+from austial.common.pipes import ArgumentMetadata, PipeTransform, ValidationPipe
+
+__all__ = [
+    "Body",
+    "Catch",
+    "Controller",
+    "Delete",
+    "Get",
+    "Global",
+    "Head",
+    "Header",
+    "Headers",
+    "HttpCode",
+    "Inject",
+    "Injectable",
+    "Module",
+    "Options",
+    "Optional_",
+    "Param",
+    "Patch",
+    "Post",
+    "Put",
+    "Query",
+    "Req",
+    "Res",
+    "UseFilters",
+    "UseGuards",
+    "UseInterceptors",
+    "UsePipes",
+    "Scope",
+    "BadRequestException",
+    "ConflictException",
+    "ForbiddenException",
+    "HttpException",
+    "InternalServerErrorException",
+    "MethodNotAllowedException",
+    "NotFoundException",
+    "NotImplementedException",
+    "ServiceUnavailableException",
+    "TooManyRequestsException",
+    "UnauthorizedException",
+    "UnprocessableEntityException",
+    "AllExceptionsFilter",
+    "ArgumentsHost",
+    "ExceptionFilter",
+    "CanActivate",
+    "ExecutionContext",
+    "CallHandler",
+    "NestInterceptor",
+    "TransformInterceptor",
+    "Logger",
+    "LoggingMiddleware",
+    "MiddlewareConsumer",
+    "NestMiddleware",
+    "ArgumentMetadata",
+    "PipeTransform",
+    "ValidationPipe",
+]

austial_common-0.1.5/src/austial/common/decorators/__init__.py

@@ -0,0 +1,48 @@
+from austial.common.decorators.controllers import (
+    Controller,
+    Delete,
+    Get,
+    Head,
+    Header,
+    HttpCode,
+    Options,
+    Patch,
+    Post,
+    Put,
+)
+from austial.common.decorators.filters import Catch, UseFilters
+from austial.common.decorators.guards import UseGuards
+from austial.common.decorators.injectable import Inject, Injectable, Optional_
+from austial.common.decorators.interceptors import UseInterceptors
+from austial.common.decorators.modules import Global, Module
+from austial.common.decorators.params import Body, Headers, Param, Query, Req, Res
+from austial.common.decorators.pipes import UsePipes
+
+__all__ = [
+    "Controller",
+    "Delete",
+    "Get",
+    "Head",
+    "Header",
+    "HttpCode",
+    "Options",
+    "Patch",
+    "Post",
+    "Put",
+    "Catch",
+    "UseFilters",
+    "UseGuards",
+    "Inject",
+    "Injectable",
+    "Optional_",
+    "UseInterceptors",
+    "Global",
+    "Module",
+    "Body",
+    "Headers",
+    "Param",
+    "Query",
+    "Req",
+    "Res",
+    "UsePipes",
+]

austial_common-0.1.5/src/austial/common/decorators/controllers.py

@@ -0,0 +1,109 @@
+"""``@Controller()`` and HTTP method decorators -- mirrors ``@nestjs/common``."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TypeVar
+
+from austial.core.metadata import (
+    CONTROLLER_METADATA,
+    HEADER_METADATA,
+    HTTP_CODE_METADATA,
+    ROUTE_METADATA,
+    set_metadata,
+)
+
+T = TypeVar("T")
+
+_EXPRESS_PARAM_RE = re.compile(r":([A-Za-z_][A-Za-z0-9_]*)")
+
+
+def _to_fastapi_path(path: str) -> str:
+    """Translates Nest/Express-style ``:id`` path params into FastAPI/Starlette's
+    ``{id}`` syntax, so route paths can be written exactly like in Nest, e.g.
+    ``@Get(":id")`` or ``@Get("users/:id/posts/:postId")``."""
+    return _EXPRESS_PARAM_RE.sub(r"{\1}", path)
+
+
+@dataclass
+class ControllerMetadata:
+    prefix: str = ""
+    tags: list | None = None
+
+
+@dataclass
+class RouteMetadata:
+    method: str
+    path: str = ""
+
+
+def Controller(prefix: str = "", *, tags: list | None = None) -> Callable[[T], T]:
+    """Class decorator: declares a controller and its route prefix.
+
+    Example::
+
+        @Controller("health")
+        class HealthController:
+            def __init__(self, health_service: HealthService):
+                self.health_service = health_service
+
+            @Get()
+            async def check(self):
+                ...
+    """
+    prefix = "/" + prefix.strip("/") if prefix else ""
+
+    def decorator(cls: T) -> T:
+        set_metadata(CONTROLLER_METADATA, ControllerMetadata(prefix=prefix, tags=tags))(cls)
+        return cls
+
+    return decorator
+
+
+def _route_decorator(method: str):
+    def factory(path: str = "") -> Callable:
+        path = _to_fastapi_path(path)
+        normalized = "/" + path.strip("/") if path else ""
+
+        def decorator(fn):
+            set_metadata(ROUTE_METADATA, RouteMetadata(method=method, path=normalized))(fn)
+            return fn
+
+        return decorator
+
+    return factory
+
+
+Get = _route_decorator("GET")
+Post = _route_decorator("POST")
+Put = _route_decorator("PUT")
+Patch = _route_decorator("PATCH")
+Delete = _route_decorator("DELETE")
+Options = _route_decorator("OPTIONS")
+Head = _route_decorator("HEAD")
+
+
+def HttpCode(status_code: int) -> Callable:
+    """Method decorator overriding the default 2xx status code, mirrors
+    Nest's ``@HttpCode()``."""
+
+    def decorator(fn):
+        set_metadata(HTTP_CODE_METADATA, status_code)(fn)
+        return fn
+
+    return decorator
+
+
+def Header(key: str, value: str) -> Callable:
+    """Method decorator adding a static response header, mirrors Nest's ``@Header()``.
+    Stackable -- multiple ``@Header`` calls accumulate."""
+
+    def decorator(fn):
+        headers: dict[str, str] = dict(getattr(fn, "__austial_metadata__", {}).get(HEADER_METADATA, {}))
+        headers[key] = value
+        set_metadata(HEADER_METADATA, headers)(fn)
+        return fn
+
+    return decorator

austial_common-0.1.5/src/austial/common/decorators/filters.py

@@ -0,0 +1,31 @@
+"""``@UseFilters()`` / ``@Catch()`` -- mirrors ``@nestjs/common``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from austial.core.metadata import CATCH_METADATA, FILTERS_METADATA, get_metadata, set_metadata
+
+
+def UseFilters(*filters: Any) -> Callable:
+    """Attaches one or more ``ExceptionFilter``s (classes or instances) to a
+    controller or a single route handler."""
+
+    def decorator(target):
+        existing = list(get_metadata(FILTERS_METADATA, target, []))
+        set_metadata(FILTERS_METADATA, existing + list(filters))(target)
+        return target
+
+    return decorator
+
+
+def Catch(*exceptions: type[BaseException]) -> Callable:
+    """Class decorator declaring which exception types a filter handles.
+    An empty call (``@Catch()``) catches everything, mirroring Nest."""
+
+    def decorator(cls):
+        set_metadata(CATCH_METADATA, tuple(exceptions))(cls)
+        return cls
+
+    return decorator

austial_common-0.1.5/src/austial/common/decorators/guards.py

@@ -0,0 +1,20 @@
+"""``@UseGuards()`` -- mirrors ``@nestjs/common``. Applicable to controllers or handlers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from austial.core.metadata import GUARDS_METADATA, get_metadata, set_metadata
+
+
+def UseGuards(*guards: Any) -> Callable:
+    """Attaches one or more ``CanActivate`` guards (classes or instances) to a
+    controller or a single route handler. Stacks across repeated calls."""
+
+    def decorator(target):
+        existing = list(get_metadata(GUARDS_METADATA, target, []))
+        set_metadata(GUARDS_METADATA, existing + list(guards))(target)
+        return target
+
+    return decorator

austial_common-0.1.5/src/austial/common/decorators/injectable.py

@@ -0,0 +1,68 @@
+"""``@Injectable()`` and ``@Inject(token)`` -- mirrors ``@nestjs/common``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from austial.common.enums import Scope
+from austial.core.metadata import INJECTABLE_METADATA, set_metadata
+
+T = TypeVar("T")
+
+
+def Injectable(scope: Scope = Scope.DEFAULT) -> Callable[[T], T]:
+    """Marks a class as a provider that the DI container can construct.
+
+    Usable as ``@Injectable()`` or ``@Injectable(scope=Scope.TRANSIENT)``,
+    exactly like Nest.
+    """
+
+    def decorator(cls: T) -> T:
+        set_metadata(INJECTABLE_METADATA, {"scope": scope})(cls)
+        return cls
+
+    return decorator
+
+
+def Inject(token: Any):
+    """Parameter-level marker for constructor injection by *token* rather than
+    by type. Mirrors Nest's ``@Inject(TOKEN)``.
+
+    Usage::
+
+        class CatsService:
+            def __init__(self, @Inject("CATS_CONFIG") config: dict): ...
+
+    Python has no parameter decorators, so instead this is used as a *default
+    value* combined with a type-hint-less parameter, e.g.::
+
+        class CatsService:
+            def __init__(self, config = Inject("CATS_CONFIG")): ...
+
+    The container recognises :class:`InjectMarker` sentinels returned here and
+    resolves them by token instead of by annotation type.
+    """
+    return InjectMarker(token)
+
+
+class InjectMarker:
+    __slots__ = ("token",)
+
+    def __init__(self, token: Any):
+        self.token = token
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"InjectMarker({self.token!r})"
+
+
+def Optional_() -> OptionalMarker:  # noqa: N802 - mirrors Nest's @Optional()
+    return OptionalMarker()
+
+
+class OptionalMarker:
+    """Marks a constructor param as optional; unresolved deps become ``None``
+    instead of raising, mirroring Nest's ``@Optional()``."""
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return "OptionalMarker()"

austial_common-0.1.5/src/austial/common/decorators/interceptors.py

@@ -0,0 +1,20 @@
+"""``@UseInterceptors()`` -- mirrors ``@nestjs/common``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from austial.core.metadata import INTERCEPTORS_METADATA, get_metadata, set_metadata
+
+
+def UseInterceptors(*interceptors: Any) -> Callable:
+    """Attaches one or more ``NestInterceptor``s (classes or instances) to a
+    controller or a single route handler."""
+
+    def decorator(target):
+        existing = list(get_metadata(INTERCEPTORS_METADATA, target, []))
+        set_metadata(INTERCEPTORS_METADATA, existing + list(interceptors))(target)
+        return target
+
+    return decorator

austial_common-0.1.5/src/austial/common/decorators/modules.py

@@ -0,0 +1,65 @@
+"""``@Module()`` -- mirrors ``@nestjs/common``'s ``@Module()`` decorator."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+
+from austial.core.metadata import MODULE_METADATA, set_metadata
+
+T = TypeVar("T")
+
+
+@dataclass
+class ModuleMetadata:
+    imports: list[Any] = field(default_factory=list)
+    controllers: list[type] = field(default_factory=list)
+    providers: list[Any] = field(default_factory=list)
+    exports: list[Any] = field(default_factory=list)
+    is_global: bool = False
+
+
+def Module(
+    *,
+    imports: Sequence[Any] = (),
+    controllers: Sequence[type] = (),
+    providers: Sequence[Any] = (),
+    exports: Sequence[Any] = (),
+) -> Callable[[T], T]:
+    """Class decorator declaring a module's imports/controllers/providers/exports.
+
+    Example::
+
+        @Module(
+            imports=[ConfigModule.for_root()],
+            controllers=[HealthController],
+            providers=[HealthService],
+            exports=[HealthService],
+        )
+        class HealthModule:
+            pass
+    """
+
+    def decorator(cls: T) -> T:
+        metadata = ModuleMetadata(
+            imports=list(imports),
+            controllers=list(controllers),
+            providers=list(providers),
+            exports=list(exports),
+        )
+        set_metadata(MODULE_METADATA, metadata)(cls)
+        return cls
+
+    return decorator
+
+
+def Global(cls: T) -> T:
+    """Class decorator marking a module's providers as available application-wide
+    without needing to be re-imported, mirroring Nest's ``@Global()``."""
+    from austial.core.metadata import get_metadata
+
+    metadata: ModuleMetadata = get_metadata(MODULE_METADATA, cls)
+    if metadata is not None:
+        metadata.is_global = True
+    return cls

austial_common-0.1.5/src/austial/common/decorators/params.py

@@ -0,0 +1,50 @@
+"""Parameter helpers -- mirrors Nest's ``@Param()``/``@Query()``/``@Body()``/etc.
+
+Python has no parameter decorators, so instead of annotating the parameter,
+these are used as **default values** in the handler signature, e.g.::
+
+    @Get(":id")
+    async def find_one(self, id: str = Param("id")):
+        ...
+
+    @Post()
+    async def create(self, dto: CreateCatDto = Body()):
+        ...
+
+Under the hood these simply return FastAPI's own ``Path``/``Query``/``Body``/
+``Header`` markers, since FastAPI + pydantic already do exactly what Nest's
+param decorators + ``ValidationPipe`` do. ``Req``/``Res`` are just re-exports
+of Starlette's ``Request``/``Response`` for type-hinting convenience.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Body as _Body
+from fastapi import Header as _Header
+from fastapi import Path as _Path
+from fastapi import Query as _Query
+from fastapi import Request as Req  # noqa: F401  (re-export, Nest-style alias)
+from fastapi import Response as Res  # noqa: F401  (re-export, Nest-style alias)
+
+
+def Param(name: str | None = None, *, default: Any = ..., **kwargs) -> Any:
+    """Equivalent to Nest's ``@Param('id')``: binds a path parameter."""
+    return _Path(default=default, alias=name, **kwargs)
+
+
+def Query(name: str | None = None, *, default: Any = None, **kwargs) -> Any:
+    """Equivalent to Nest's ``@Query('search')``: binds a query-string parameter."""
+    return _Query(default=default, alias=name, **kwargs)
+
+
+def Body(*, default: Any = ..., embed: bool = False, **kwargs) -> Any:
+    """Equivalent to Nest's ``@Body()``: binds (and, via pydantic, validates)
+    the request body against the parameter's type annotation."""
+    return _Body(default=default, embed=embed, **kwargs)
+
+
+def Headers(name: str | None = None, *, default: Any = None, **kwargs) -> Any:
+    """Equivalent to Nest's ``@Headers('x-api-key')``: binds a request header."""
+    return _Header(default=default, alias=name, **kwargs)

austial_common-0.1.5/src/austial/common/decorators/pipes.py

@@ -0,0 +1,20 @@
+"""``@UsePipes()`` -- mirrors ``@nestjs/common``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from austial.core.metadata import PIPES_METADATA, get_metadata, set_metadata
+
+
+def UsePipes(*pipes: Any) -> Callable:
+    """Attaches one or more ``PipeTransform``s (classes or instances) to a
+    controller or a single route handler."""
+
+    def decorator(target):
+        existing = list(get_metadata(PIPES_METADATA, target, []))
+        set_metadata(PIPES_METADATA, existing + list(pipes))(target)
+        return target
+
+    return decorator

austial_common-0.1.5/src/austial/common/enums.py

@@ -0,0 +1,15 @@
+from enum import StrEnum
+
+
+class Scope(StrEnum):
+    """Provider scope, mirrors ``@nestjs/common``'s ``Scope``.
+
+    Only ``DEFAULT`` (singleton, one instance per application) and
+    ``TRANSIENT`` (a new instance every time it's resolved) are supported.
+    Nest's ``REQUEST`` scope is intentionally not implemented in v1 -- FastAPI's
+    async request model doesn't map onto it cleanly, and it's rarely needed
+    outside multi-tenant setups.
+    """
+
+    DEFAULT = "DEFAULT"
+    TRANSIENT = "TRANSIENT"

austial_common-0.1.5/src/austial/common/exceptions/__init__.py

@@ -0,0 +1,29 @@
+from austial.common.exceptions.http_exceptions import (
+    BadRequestException,
+    ConflictException,
+    ForbiddenException,
+    HttpException,
+    InternalServerErrorException,
+    MethodNotAllowedException,
+    NotFoundException,
+    NotImplementedException,
+    ServiceUnavailableException,
+    TooManyRequestsException,
+    UnauthorizedException,
+    UnprocessableEntityException,
+)
+
+__all__ = [
+    "BadRequestException",
+    "ConflictException",
+    "ForbiddenException",
+    "HttpException",
+    "InternalServerErrorException",
+    "MethodNotAllowedException",
+    "NotFoundException",
+    "NotImplementedException",
+    "ServiceUnavailableException",
+    "TooManyRequestsException",
+    "UnauthorizedException",
+    "UnprocessableEntityException",
+]

austial_common-0.1.5/src/austial/common/exceptions/http_exceptions.py

@@ -0,0 +1,109 @@
+"""HTTP exceptions -- mirrors ``@nestjs/common``'s exception hierarchy.
+
+All of these carry a ``status_code`` and a Nest-shaped ``response`` payload
+(``{"statusCode": ..., "message": ..., "error": ...}``) so the default
+:class:`~austial.common.filters.all_exceptions_filter.AllExceptionsFilter`
+can render them exactly like Nest's built-in filter does.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class HttpException(Exception):
+    def __init__(self, message: str | dict | None = None, status_code: int = 500, error: str | None = None):
+        self.status_code = status_code
+        if isinstance(message, dict):
+            self.response: dict[str, Any] = {"statusCode": status_code, **message}
+        else:
+            self.response = {
+                "statusCode": status_code,
+                "message": message or _default_message(status_code),
+                "error": error or _default_message(status_code),
+            }
+        super().__init__(str(self.response.get("message")))
+
+    def get_status(self) -> int:
+        return self.status_code
+
+    def get_response(self) -> dict:
+        return self.response
+
+
+def _default_message(status_code: int) -> str:
+    return _REASON_PHRASES.get(status_code, "Error")
+
+
+_REASON_PHRASES = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    422: "Unprocessable Entity",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+}
+
+
+class BadRequestException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 400)
+
+
+class UnauthorizedException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 401)
+
+
+class ForbiddenException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 403)
+
+
+class NotFoundException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 404)
+
+
+class MethodNotAllowedException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 405)
+
+
+class ConflictException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 409)
+
+
+class UnprocessableEntityException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 422)
+
+
+class TooManyRequestsException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 429)
+
+
+class InternalServerErrorException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 500)
+
+
+class NotImplementedException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 501)
+
+
+class ServiceUnavailableException(HttpException):
+    def __init__(self, message: str | dict | None = None):
+        super().__init__(message, 503)

austial_common-0.1.5/src/austial/common/filters/__init__.py

@@ -0,0 +1,4 @@
+from austial.common.filters.all_exceptions_filter import AllExceptionsFilter
+from austial.common.filters.base import ArgumentsHost, ExceptionFilter
+
+__all__ = ["AllExceptionsFilter", "ArgumentsHost", "ExceptionFilter"]

austial_common-0.1.5/src/austial/common/filters/all_exceptions_filter.py

@@ -0,0 +1,31 @@
+"""``AllExceptionsFilter`` -- the default global exception filter.
+
+Renders errors in the exact shape Nest's built-in filter produces::
+
+    {"statusCode": 404, "message": "Not Found", "error": "Not Found",
+     "timestamp": "...", "path": "/cats/42"}
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from starlette.responses import JSONResponse
+
+from austial.common.exceptions.http_exceptions import HttpException
+from austial.common.filters.base import ArgumentsHost, ExceptionFilter
+
+
+class AllExceptionsFilter(ExceptionFilter):
+    async def catch(self, exception: BaseException, host: ArgumentsHost) -> JSONResponse:
+        request = host.get_request()
+        if isinstance(exception, HttpException):
+            status_code = exception.get_status()
+            body = dict(exception.get_response())
+        else:
+            status_code = 500
+            body = {"statusCode": 500, "message": "Internal Server Error", "error": "Internal Server Error"}
+
+        body.setdefault("timestamp", datetime.now(UTC).isoformat())
+        body.setdefault("path", request.url.path)
+        return JSONResponse(status_code=status_code, content=body)

austial_common-0.1.5/src/austial/common/filters/base.py

@@ -0,0 +1,28 @@
+"""``ExceptionFilter`` + ``ArgumentsHost`` -- mirrors ``@nestjs/common``."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class ArgumentsHost:
+    """Minimal stand-in for Nest's ``ArgumentsHost`` -- gives filters access to
+    the underlying HTTP request."""
+
+    def __init__(self, request: Request):
+        self._request = request
+
+    def switch_to_http(self) -> ArgumentsHost:
+        return self
+
+    def get_request(self) -> Request:
+        return self._request
+
+
+class ExceptionFilter(ABC):
+    @abstractmethod
+    async def catch(self, exception: BaseException, host: ArgumentsHost) -> Response:
+        raise NotImplementedError

austial_common-0.1.5/src/austial/common/guards/__init__.py

@@ -0,0 +1,3 @@
+from austial.common.guards.base import CanActivate, ExecutionContext
+
+__all__ = ["CanActivate", "ExecutionContext"]

austial_common-0.1.5/src/austial/common/guards/base.py

@@ -0,0 +1,39 @@
+"""``CanActivate`` + ``ExecutionContext`` -- mirrors ``@nestjs/common``."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from starlette.requests import Request
+
+
+class ExecutionContext:
+    """Gives guards/interceptors/filters access to the current request and to
+    the controller class + handler function being invoked, mirroring Nest's
+    ``ExecutionContext``."""
+
+    def __init__(self, request: Request, controller_class: type, handler: Any):
+        self._request = request
+        self._controller_class = controller_class
+        self._handler = handler
+
+    def switch_to_http(self) -> ExecutionContext:
+        return self
+
+    def get_request(self) -> Request:
+        return self._request
+
+    def get_class(self) -> type:
+        return self._controller_class
+
+    def get_handler(self) -> Any:
+        return self._handler
+
+
+class CanActivate(ABC):
+    """Base class for guards. Implement ``can_activate`` to allow/deny a request."""
+
+    @abstractmethod
+    async def can_activate(self, context: ExecutionContext) -> bool:
+        raise NotImplementedError

austial_common-0.1.5/src/austial/common/interceptors/__init__.py

@@ -0,0 +1,4 @@
+from austial.common.interceptors.base import CallHandler, NestInterceptor
+from austial.common.interceptors.transform_interceptor import TransformInterceptor
+
+__all__ = ["CallHandler", "NestInterceptor", "TransformInterceptor"]

austial_common-0.1.5/src/austial/common/interceptors/base.py

@@ -0,0 +1,30 @@
+"""``NestInterceptor`` + ``CallHandler`` -- mirrors ``@nestjs/common``.
+
+Nest interceptors wrap an RxJS ``Observable``; Austial has no RxJS, so
+``CallHandler.handle()`` is simply an ``async`` continuation representing
+"run the rest of the pipeline (further interceptors, then the handler) and
+give me its return value". Interceptors can inspect/replace the result, time
+the call, catch+rethrow, etc. -- same capabilities, async/await shaped.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from austial.common.guards.base import ExecutionContext
+
+
+class CallHandler:
+    def __init__(self, next_call: Callable[[], Awaitable[Any]]):
+        self._next_call = next_call
+
+    async def handle(self) -> Any:
+        return await self._next_call()
+
+
+class NestInterceptor(ABC):
+    @abstractmethod
+    async def intercept(self, context: ExecutionContext, next: CallHandler) -> Any:
+        raise NotImplementedError

austial_common-0.1.5/src/austial/common/interceptors/transform_interceptor.py

@@ -0,0 +1,19 @@
+"""``TransformInterceptor`` -- the canonical Nest "wrap every response" example.
+
+Wraps every successful controller response in a ``{"data": ..., "timestamp": ...}``
+envelope, exactly like the interceptor from the official NestJS docs.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from austial.common.guards.base import ExecutionContext
+from austial.common.interceptors.base import CallHandler, NestInterceptor
+
+
+class TransformInterceptor(NestInterceptor):
+    async def intercept(self, context: ExecutionContext, next: CallHandler) -> Any:
+        result = await next.handle()
+        return {"data": result, "timestamp": datetime.now(UTC).isoformat()}

austial_common-0.1.5/src/austial/common/logger.py

@@ -0,0 +1,56 @@
+"""``Logger`` -- mirrors ``@nestjs/common``'s ``Logger``, including the
+familiar colored ``[Austial] 12345  - 07/11/2026, 10:00:00 AM   LOG [Context] message``
+startup banner style."""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+
+from rich.console import Console
+
+_console = Console()
+
+_LEVEL_COLORS = {
+    "LOG": "green",
+    "ERROR": "red",
+    "WARN": "yellow",
+    "DEBUG": "magenta",
+    "VERBOSE": "cyan",
+}
+
+
+class Logger:
+    """Usable standalone (``Logger("HealthController").log("...")``) or as a
+    class-level helper via the static methods, same dual API as Nest's."""
+
+    app_name = "Austial"
+
+    def __init__(self, context: str | None = None):
+        self.context = context or "Austial"
+
+    def _write(self, level: str, message: str, context: str | None = None) -> None:
+        color = _LEVEL_COLORS.get(level, "white")
+        timestamp = datetime.now().strftime("%m/%d/%Y, %I:%M:%S %p")
+        ctx = context or self.context
+        _console.print(
+            f"[bold {color}][{self.app_name}][/bold {color}] "
+            f"[dim]{os.getpid():<6}[/dim] - {timestamp}   "
+            f"[bold {color}]{level:<7}[/bold {color}] "
+            f"[yellow][{ctx}][/yellow] {message}"
+        )
+
+    def log(self, message: str, context: str | None = None) -> None:
+        self._write("LOG", message, context)
+
+    def error(self, message: str, context: str | None = None) -> None:
+        self._write("ERROR", message, context)
+
+    def warn(self, message: str, context: str | None = None) -> None:
+        self._write("WARN", message, context)
+
+    def debug(self, message: str, context: str | None = None) -> None:
+        self._write("DEBUG", message, context)
+
+    def verbose(self, message: str, context: str | None = None) -> None:
+        self._write("VERBOSE", message, context)

austial_common-0.1.5/src/austial/common/middleware/__init__.py

@@ -0,0 +1,4 @@
+from austial.common.middleware.base import MiddlewareBinding, MiddlewareConsumer, NestMiddleware
+from austial.common.middleware.logging_middleware import LoggingMiddleware
+
+__all__ = ["MiddlewareBinding", "MiddlewareConsumer", "NestMiddleware", "LoggingMiddleware"]

austial_common-0.1.5/src/austial/common/middleware/base.py

@@ -0,0 +1,60 @@
+"""``NestMiddleware`` + ``MiddlewareConsumer`` -- mirrors ``@nestjs/common``.
+
+A module opts into middleware by defining a ``configure(self, consumer)``
+method (mirroring Nest's ``NestModule`` interface)::
+
+    class AppModule:
+        def configure(self, consumer: MiddlewareConsumer) -> None:
+            consumer.apply(LoggingMiddleware).for_routes("*")
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class NestMiddleware(ABC):
+    @abstractmethod
+    async def use(self, request: Request, call_next: Callable[[], Awaitable[Response]]) -> Response:
+        raise NotImplementedError
+
+
+@dataclass
+class MiddlewareBinding:
+    middlewares: Sequence[Any]
+    routes: Sequence[str]
+
+    def matches(self, path: str) -> bool:
+        for route in self.routes:
+            if route in ("*", "(.*)"):
+                return True
+            if path == route or path.startswith(route.rstrip("*")):
+                return True
+        return False
+
+
+class _RouteBinder:
+    def __init__(self, consumer: MiddlewareConsumer, middlewares: Sequence[Any]):
+        self._consumer = consumer
+        self._middlewares = middlewares
+
+    def for_routes(self, *routes: str) -> MiddlewareConsumer:
+        self._consumer.bindings.append(MiddlewareBinding(middlewares=self._middlewares, routes=routes or ("*",)))
+        return self._consumer
+
+
+class MiddlewareConsumer:
+    """Passed into a module's ``configure()`` hook; collects
+    ``apply(...).for_routes(...)`` bindings for the factory to wire up."""
+
+    def __init__(self):
+        self.bindings: list[MiddlewareBinding] = []
+
+    def apply(self, *middlewares: Any) -> _RouteBinder:
+        return _RouteBinder(self, middlewares)

austial_common-0.1.5/src/austial/common/middleware/logging_middleware.py

@@ -0,0 +1,24 @@
+"""``LoggingMiddleware`` -- the canonical Nest "log every request" example
+(nestjs.com/docs/middleware uses the exact same one, just in TypeScript)."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Awaitable, Callable
+
+from starlette.requests import Request
+from starlette.responses import Response
+
+from austial.common.logger import Logger
+from austial.common.middleware.base import NestMiddleware
+
+_logger = Logger("HTTP")
+
+
+class LoggingMiddleware(NestMiddleware):
+    async def use(self, request: Request, call_next: Callable[[], Awaitable[Response]]) -> Response:
+        start = time.perf_counter()
+        response = await call_next()
+        duration_ms = (time.perf_counter() - start) * 1000
+        _logger.log(f"{request.method} {request.url.path} {response.status_code} - {duration_ms:.1f}ms")
+        return response

austial_common-0.1.5/src/austial/common/pipes/__init__.py

@@ -0,0 +1,3 @@
+from austial.common.pipes.validation_pipe import ArgumentMetadata, PipeTransform, ValidationPipe
+
+__all__ = ["ArgumentMetadata", "PipeTransform", "ValidationPipe"]

austial_common-0.1.5/src/austial/common/pipes/validation_pipe.py

@@ -0,0 +1,51 @@
+"""``PipeTransform`` + ``ValidationPipe`` -- mirrors ``@nestjs/common``.
+
+FastAPI/pydantic already parse and validate the request body against a
+handler's type hints (that's Austial's equivalent of Nest's ``class-validator``
+integration). The pipe pipeline still runs for real on top of that, mirroring
+Nest's "pipes transform/validate arguments right before the handler runs":
+each resolved argument is passed through ``transform()`` for every pipe in
+scope (global -> controller -> route), in order.
+"""
+
+from __future__ import annotations
+
+import builtins
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from pydantic import BaseModel, ValidationError
+
+from austial.common.exceptions.http_exceptions import BadRequestException
+
+
+@dataclass
+class ArgumentMetadata:
+    # Field name intentionally mirrors Nest's `ArgumentMetadata.type` -- annotate
+    # `metatype` via `builtins.type` to avoid this field shadowing the builtin.
+    type: Literal["body", "query", "param", "custom"]
+    data: str | None
+    metatype: builtins.type | None
+
+
+class PipeTransform(ABC):
+    @abstractmethod
+    def transform(self, value: Any, metadata: ArgumentMetadata) -> Any:
+        raise NotImplementedError
+
+
+class ValidationPipe(PipeTransform):
+    """Re-validates pydantic-model arguments, raising Nest-shaped
+    ``BadRequestException``s on failure -- the workhorse pipe almost every
+    Nest app registers globally via ``app.useGlobalPipes(new ValidationPipe())``."""
+
+    def transform(self, value: Any, metadata: ArgumentMetadata) -> Any:
+        if isinstance(value, BaseModel):
+            try:
+                type(value).model_validate(value.model_dump())
+            except ValidationError as exc:
+                raise BadRequestException(
+                    {"message": [str(e["msg"]) for e in exc.errors()], "error": "Bad Request"}
+                ) from exc
+        return value