jararaca 0.2.37a12__py3-none-any.whl → 0.4.0a5__py3-none-any.whl

jararaca/presentation/decorators.py

@@ -1,5 +1,12 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import inspect
-from typing import Any, Callable, Literal, Protocol, TypeVar, cast
+from contextlib import contextmanager
+from contextvars import ContextVar
+from functools import wraps
+from typing import Any, Awaitable, Callable, Literal, Mapping, Protocol, TypeVar
 
 from fastapi import APIRouter
 from fastapi import Depends as DependsF
@@ -9,12 +16,17 @@ from fastapi.params import Depends
 from jararaca.lifecycle import AppLifecycle
 from jararaca.presentation.http_microservice import HttpMiddleware
 from jararaca.presentation.websocket.decorators import WebSocketEndpoint
+from jararaca.reflect.controller_inspect import (
+    ControllerMemberReflect,
+    inspect_controller,
+)
+from jararaca.reflect.decorators import DECORATED_T, StackableDecorator
 
+DECORATED_TYPE = TypeVar("DECORATED_TYPE", bound=Any)
 DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Any])
-DECORATED_CLASS = TypeVar("DECORATED_CLASS", bound=Any)
 
 
-ControllerOptions = dict[str, Any]
+ControllerOptions = Mapping[str, Any]
 
 
 class RouterFactory(Protocol):
@@ -22,20 +34,25 @@ class RouterFactory(Protocol):
     def __call__(self, lifecycle: AppLifecycle, instance: Any) -> APIRouter: ...
 
 
-class RestController:
+class RestController(StackableDecorator):
     REST_CONTROLLER_ATTR = "__rest_controller__"
 
     def __init__(
         self,
         path: str = "",
+        *,
         options: ControllerOptions | None = None,
         middlewares: list[type[HttpMiddleware]] = [],
         router_factory: RouterFactory | None = None,
+        class_inherits_decorators: bool = True,
+        methods_inherit_decorators: bool = True,
     ) -> None:
         self.path = path
         self.options = options
         self.router_factory = router_factory
         self.middlewares = middlewares
+        self.class_inherits_decorators = class_inherits_decorators
+        self.methods_inherit_decorators = methods_inherit_decorators
 
     def get_router_factory(
         self,
@@ -44,12 +61,15 @@ class RestController:
             raise Exception("Router factory is not set")
         return self.router_factory
 
-    def __call__(self, cls: type[DECORATED_CLASS]) -> type[DECORATED_CLASS]:
+    def post_decorated(self, subject: DECORATED_T) -> None:
 
         def router_factory(
             lifecycle: AppLifecycle,
-            instance: DECORATED_CLASS,
+            instance: DECORATED_T,
         ) -> APIRouter:
+            assert inspect.isclass(
+                subject
+            ), "RestController can only be applied to classes"
             dependencies: list[Depends] = []
 
             for self_middleware_type in self.middlewares:
@@ -58,13 +78,19 @@ class RestController:
                 )
                 dependencies.append(Depends(middleware_instance.intercept))
 
-            for middlewares_by_hook in UseMiddleware.get_middlewares(instance):
+            class_middlewares = UseMiddleware.get_all_from_type(
+                subject, self.class_inherits_decorators
+            )
+            for middlewares_by_hook in class_middlewares:
                 middleware_instance = lifecycle.container.get_by_type(
                     middlewares_by_hook.middleware
                 )
                 dependencies.append(Depends(middleware_instance.intercept))
 
-            for dependency in UseDependency.get_dependencies(instance):
+            class_dependencies = UseDependency.get_all_from_type(
+                subject, self.class_inherits_decorators
+            )
+            for dependency in class_dependencies:
                 dependencies.append(DependsF(dependency.dependency))
 
             router = APIRouter(
@@ -73,15 +99,23 @@ class RestController:
                 **(self.options or {}),
             )
 
-            members = inspect.getmembers(cls, predicate=inspect.isfunction)
+            controller, members = inspect_controller(subject)
 
             router_members = [
-                (name, mapping)
-                for name, member in members
+                (name, mapping, member)
+                for name, member in members.items()
                 if (
-                    mapping := (
-                        HttpMapping.get_http_mapping(member)
-                        or WebSocketEndpoint.get(member)
+                    mapping := HttpMapping.get_bound_from_method(
+                        subject,
+                        name,
+                        self.methods_inherit_decorators,
+                        last=True,
+                    )
+                    or WebSocketEndpoint.get_bound_from_method(
+                        subject,
+                        name,
+                        self.methods_inherit_decorators,
+                        last=True,
                     )
                 )
                 is not None
@@ -89,27 +123,38 @@ class RestController:
 
             router_members.sort(key=lambda x: x[1].order)
 
-            for name, mapping in router_members:
+            for name, mapping, member in router_members:
                 route_dependencies: list[Depends] = []
-                for middlewares_by_hook in UseMiddleware.get_middlewares(
-                    getattr(instance, name)
-                ):
+
+                method_middlewares = UseMiddleware.get_all_from_method(
+                    subject, name, self.methods_inherit_decorators
+                )
+                for middlewares_by_hook in method_middlewares:
                     middleware_instance = lifecycle.container.get_by_type(
                         middlewares_by_hook.middleware
                     )
                     route_dependencies.append(Depends(middleware_instance.intercept))
 
-                for dependency in UseDependency.get_dependencies(
-                    getattr(instance, name)
-                ):
+                method_dependencies = UseDependency.get_all_from_method(
+                    subject,
+                    name,
+                    self.methods_inherit_decorators,
+                )
+                for dependency in method_dependencies:
                     route_dependencies.append(DependsF(dependency.dependency))
 
+                instance_method = getattr(instance, name)
+                instance_method = wraps_with_attributes(
+                    instance_method,
+                    controller_member_reflect=member,
+                )
+
                 if isinstance(mapping, HttpMapping):
                     try:
                         router.add_api_route(
                             methods=[mapping.method],
                             path=mapping.path,
-                            endpoint=getattr(instance, name),
+                            endpoint=instance_method,
                             dependencies=route_dependencies,
                             **(mapping.options or {}),
                         )
@@ -120,7 +165,7 @@ class RestController:
                 else:
                     router.add_api_websocket_route(
                         path=mapping.path,
-                        endpoint=getattr(instance, name),
+                        endpoint=instance_method,
                         dependencies=route_dependencies,
                         **(mapping.options or {}),
                     )
@@ -129,21 +174,6 @@ class RestController:
 
         self.router_factory = router_factory
 
-        RestController.register(cls, self)
-
-        return cls
-
-    @staticmethod
-    def register(cls: type[DECORATED_CLASS], controller: "RestController") -> None:
-        setattr(cls, RestController.REST_CONTROLLER_ATTR, controller)
-
-    @staticmethod
-    def get_controller(cls: type[DECORATED_CLASS]) -> "RestController | None":
-        if not hasattr(cls, RestController.REST_CONTROLLER_ATTR):
-            return None
-
-        return cast(RestController, getattr(cls, RestController.REST_CONTROLLER_ATTR))
-
 
 Options = dict[str, Any]
 
@@ -158,9 +188,8 @@ ResponseType = Literal[
 ]
 
 
-class HttpMapping:
+class HttpMapping(StackableDecorator):
 
-    HTTP_MAPPING_ATTR = "__http_mapping__"
     ORDER_COUNTER = 0
 
     def __init__(
@@ -178,24 +207,20 @@ class HttpMapping:
         HttpMapping.ORDER_COUNTER += 1
         self.order = HttpMapping.ORDER_COUNTER
 
-    def __call__(self, func: DECORATED_FUNC) -> DECORATED_FUNC:
+    @classmethod
+    def decorator_key(cls) -> "type[HttpMapping]":
+        return HttpMapping
 
-        HttpMapping.register(func, self)
+    # def __call__(self, func: DECORATED_FUNC) -> DECORATED_FUNC:
 
-        return func
-
-    @staticmethod
-    def register(func: DECORATED_FUNC, mapping: "HttpMapping") -> None:
+    #     HttpMapping.register(func, self)
 
-        setattr(func, HttpMapping.HTTP_MAPPING_ATTR, mapping)
+    #     return func
 
-    @staticmethod
-    def get_http_mapping(func: DECORATED_FUNC) -> "HttpMapping | None":
+    # @staticmethod
+    # def register(func: DECORATED_FUNC, mapping: "HttpMapping") -> None:
 
-        if not hasattr(func, HttpMapping.HTTP_MAPPING_ATTR):
-            return None
-
-        return cast(HttpMapping, getattr(func, HttpMapping.HTTP_MAPPING_ATTR))
+    #     setattr(func, HttpMapping.HTTP_MAPPING_ATTR, mapping)
 
 
 class Post(HttpMapping):
@@ -253,49 +278,112 @@ class Patch(HttpMapping):
         super().__init__("PATCH", path, options, response_type)
 
 
-class UseMiddleware:
-
-    __MIDDLEWARES_ATTR__ = "__middlewares__"
+class UseMiddleware(StackableDecorator):
 
     def __init__(self, middleware: type[HttpMiddleware]) -> None:
         self.middleware = middleware
 
-    def __call__(self, subject: DECORATED_FUNC) -> DECORATED_FUNC:
 
-        UseMiddleware.register(subject, self)
+class UseDependency(StackableDecorator):
 
-        return subject
+    def __init__(self, dependency: Any) -> None:
+        self.dependency = dependency
 
-    @staticmethod
-    def register(subject: DECORATED_FUNC, middleware: "UseMiddleware") -> None:
-        middlewares = getattr(subject, UseMiddleware.__MIDDLEWARES_ATTR__, [])
-        middlewares.append(middleware)
-        setattr(subject, UseMiddleware.__MIDDLEWARES_ATTR__, middlewares)
 
-    @staticmethod
-    def get_middlewares(subject: DECORATED_FUNC) -> list["UseMiddleware"]:
-        return getattr(subject, UseMiddleware.__MIDDLEWARES_ATTR__, [])
+def compose_route_decorators(
+    *decorators: UseMiddleware | UseDependency,
+    reverse: bool = False,
+) -> Callable[[DECORATED_TYPE], DECORATED_TYPE]:
+    """
+    Compose multiple route decorators (middlewares/dependencies) into a single decorator.
 
+    Args:
+        *decorators (UseMiddleware | UseDependency): The decorators to compose.
+        reverse (bool): Whether to apply the decorators in reverse order. Warning: This may affect the order of middleware execution.
 
-class UseDependency:
+    Returns:
+        Callable[[DECORATED_TYPE], DECORATED_TYPE]: A single decorator that applies all the given decorators.
 
-    __DEPENDENCY_ATTR__ = "__dependencies__"
+    Example:
+        IsWorkspaceAdmin = compose_route_decorators(
+            UseMiddleware(AuthMiddleware),
+            UseMiddleware(IsWorkspaceScoped),
+            UseMiddleware(RequiresAdminRole),
+        )
+    """
 
-    def __init__(self, dependency: Any) -> None:
-        self.dependency = dependency
+    def composed_decorator(func: DECORATED_TYPE) -> DECORATED_TYPE:
+        for decorator in reversed(decorators) if reverse else decorators:
+            func = decorator(func)
+        return func
+
+    return composed_decorator
+
+
+def wraps_with_member_data(
+    controller_member: ControllerMemberReflect, func: Callable[..., Awaitable[Any]]
+) -> Callable[..., Any]:
+    """
+    A decorator that wraps a function and preserves its metadata.
+    This is useful for preserving metadata when using decorators.
+    """
+
+    @wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+
+        with providing_controller_member(
+            controller_member=controller_member,
+        ):
+
+            return await func(*args, **kwargs)
+
+    return wrapper
+
+
+controller_member_ctxvar = ContextVar[ControllerMemberReflect](
+    "controller_member_ctxvar"
+)
+
+
+@contextmanager
+def providing_controller_member(
+    controller_member: ControllerMemberReflect,
+) -> Any:
+    """
+    Context manager to provide the controller member metadata.
+    This is used to preserve the metadata of the controller member
+    when using decorators.
+    """
+    token = controller_member_ctxvar.set(controller_member)
+    try:
+        yield
+    finally:
+        controller_member_ctxvar.reset(token)
+
+
+def use_controller_member() -> ControllerMemberReflect:
+    """
+    Get the current controller member metadata.
+    This is used to access the metadata of the controller member
+    when using decorators.
+    """
+    return controller_member_ctxvar.get()
 
-    def __call__(self, subject: DECORATED_FUNC) -> DECORATED_FUNC:
 
-        UseDependency.register(subject, self)
+def wraps_with_attributes(
+    func: Callable[..., Awaitable[Any]], **attributes: Any
+) -> Callable[..., Awaitable[Any]]:
+    """
+    A decorator that wraps a function and preserves its attributes.
+    This is useful for preserving attributes when using decorators.
+    """
 
-        return subject
+    @wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        return await func(*args, **kwargs)
 
-    @staticmethod
-    def register(subject: DECORATED_FUNC, dependency: "UseDependency") -> None:
-        dependencies = getattr(subject, UseDependency.__DEPENDENCY_ATTR__, [])
-        dependencies.append(dependency)
-        setattr(subject, UseDependency.__DEPENDENCY_ATTR__, dependencies)
+    # Copy attributes from the original function to the wrapper
+    for key, value in attributes.items():
+        setattr(wrapper, key, value)
 
-    @staticmethod
-    def get_dependencies(subject: DECORATED_FUNC) -> list["UseDependency"]:
-        return getattr(subject, UseDependency.__DEPENDENCY_ATTR__, [])
+    return wrapper

jararaca/presentation/exceptions.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from fastapi import Request, Response, WebSocket
+
+
+class PresentationException(Exception):
+    """Base exception for presentation layer errors."""
+
+    def __init__(
+        self,
+        *,
+        original_exception: Exception,
+        request: Request | None = None,
+        response: Response | None = None,
+        websocket: WebSocket | None = None,
+    ) -> None:
+        super().__init__(str(original_exception))
+        self.original_exception = original_exception
+        self.request = request
+        self.response = response
+        self.websocket = websocket

jararaca/presentation/hooks.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from contextlib import contextmanager
 from typing import Any, ContextManager, Generator, Type
 

jararaca/presentation/http_microservice.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from dataclasses import dataclass, field
 from typing import Any, AsyncGenerator, Callable, Protocol
 

jararaca/presentation/server.py

@@ -1,15 +1,36 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import asyncio
+import logging
+import os
+import signal
+import threading
 from contextlib import asynccontextmanager
+from signal import SIGINT, SIGTERM
 from typing import Any, AsyncGenerator
 
-from fastapi import Depends, FastAPI, Request, WebSocket
+from fastapi import Depends, FastAPI, HTTPException, Request, Response, WebSocket
 from starlette.types import ASGIApp
 
 from jararaca.core.uow import UnitOfWorkContextProvider
 from jararaca.di import Container
 from jararaca.lifecycle import AppLifecycle
-from jararaca.microservice import HttpAppContext, WebSocketAppContext
+from jararaca.microservice import (
+    AppTransactionContext,
+    HttpTransactionData,
+    ShutdownState,
+    WebSocketTransactionData,
+    provide_shutdown_state,
+    providing_app_type,
+)
 from jararaca.presentation.decorators import RestController
+from jararaca.presentation.exceptions import PresentationException
 from jararaca.presentation.http_microservice import HttpMicroservice
+from jararaca.reflect.controller_inspect import ControllerMemberReflect
+
+logger = logging.getLogger(__name__)
 
 
 class HttpAppLifecycle:
@@ -26,65 +47,123 @@ class HttpAppLifecycle:
 
     @asynccontextmanager
     async def __call__(self, api: FastAPI) -> AsyncGenerator[None, None]:
-        async with self.lifecycle():
+        with providing_app_type("http"):
+            async with self.lifecycle():
 
-            # websocket_interceptors = [
-            #     interceptor
-            #     for interceptor in self.lifecycle.initialized_interceptors
-            #     if isinstance(interceptor, WebSocketInterceptor)
-            # ]
+                for controller_t in self.lifecycle.app.controllers:
+                    controller = RestController.get_last(controller_t)
 
-            # for interceptor in websocket_interceptors:
-            #     router = interceptor.get_ws_router(
-            #         self.lifecycle.app, self.lifecycle.container, self.uow_provider
-            #     )
+                    if controller is None:
+                        continue
 
-            #     api.include_router(router)
+                    instance: Any = self.lifecycle.container.get_by_type(controller_t)
 
-            for controller_t in self.lifecycle.app.controllers:
-                controller = RestController.get_controller(controller_t)
+                    router = controller.get_router_factory()(self.lifecycle, instance)
 
-                if controller is None:
-                    continue
+                    api.include_router(router)
 
-                instance: Any = self.lifecycle.container.get_by_type(controller_t)
+                    for middleware in self.http_app.middlewares:
+                        middleware_instance = self.lifecycle.container.get_by_type(
+                            middleware
+                        )
+                        api.router.dependencies.append(
+                            Depends(middleware_instance.intercept)
+                        )
 
-                # dependencies: list[DependsCls] = []
-                # for middleware in controller.middlewares:
-                #     middleware_instance = self.lifecycle.container.get_by_type(
-                #         middleware
-                #     )
-                #     dependencies.append(Depends(middleware_instance.intercept))
+                yield
 
-                router = controller.get_router_factory()(self.lifecycle, instance)
 
-                api.include_router(router)
+class HttpShutdownState(ShutdownState):
+    def __init__(self) -> None:
+        self._requested = False
+        self.old_signal_handlers = {
+            SIGINT: signal.getsignal(SIGINT),
+            SIGTERM: signal.getsignal(SIGTERM),
+        }
+        self.thread_lock = threading.Lock()
+        self.aevent = asyncio.Event()
 
-                for middleware in self.http_app.middlewares:
-                    middleware_instance = self.lifecycle.container.get_by_type(
-                        middleware
-                    )
-                    api.router.dependencies.append(
-                        Depends(middleware_instance.intercept)
-                    )
+    def request_shutdown(self) -> None:
+        if not self._requested:
+            self._requested = True
+            os.kill(os.getpid(), SIGINT)
+
+    def is_shutdown_requested(self) -> bool:
+        return self._requested
+
+    def handle_signal(self, signum: int, frame: Any) -> None:
+        logger.warning(f"Received signal {signum}, initiating shutdown...")
+        self.aevent.set()
+        if self._requested:
+            logger.warning("Shutdown already requested, ignoring signal.")
+            return
+        logger.warning("Requesting shutdown...")
+        self._requested = True
 
-            yield
+        # remove the signal handler to prevent recursion
+        for sig in (SIGINT, SIGTERM):
+            if self.old_signal_handlers[sig] is not None:
+                signal.signal(sig, self.old_signal_handlers[sig])
+
+        signal.raise_signal(signum)
+
+    async def wait_for_shutdown(self) -> None:
+        await self.aevent.wait()
+
+    def setup_signal_handlers(self) -> None:
+        signal.signal(SIGINT, self.handle_signal)
+        signal.signal(SIGTERM, self.handle_signal)
 
 
 class HttpUowContextProviderDependency:
 
     def __init__(self, uow_provider: UnitOfWorkContextProvider) -> None:
         self.uow_provider = uow_provider
+        self.shutdown_state = HttpShutdownState()
+        self.shutdown_state.setup_signal_handlers()
 
     async def __call__(
-        self, websocket: WebSocket = None, request: Request = None  # type: ignore
+        self, websocket: WebSocket = None, request: Request = None, response: Response = None  # type: ignore
     ) -> AsyncGenerator[None, None]:
-        async with self.uow_provider(
-            HttpAppContext(request=request)
-            if request
-            else WebSocketAppContext(websocket=websocket)
-        ):
-            yield
+        if request:
+            endpoint = request.scope["endpoint"]
+        elif websocket:
+            endpoint = websocket.scope["endpoint"]
+        else:
+            raise ValueError("Either request or websocket must be provided.")
+
+        member = getattr(endpoint, "controller_member_reflect", None)
+
+        if member is None:
+            raise ValueError("The endpoint does not have a controller member reflect.")
+
+        assert isinstance(member, ControllerMemberReflect), (
+            "Expected endpoint.controller_member_reflect to be of type "
+            "ControllerMemberReflect, but got: {}".format(type(member))
+        )
+
+        with provide_shutdown_state(self.shutdown_state):
+            async with self.uow_provider(
+                AppTransactionContext(
+                    controller_member_reflect=member,
+                    transaction_data=(
+                        HttpTransactionData(request=request, response=response)
+                        if request
+                        else WebSocketTransactionData(websocket=websocket)
+                    ),
+                )
+            ):
+                try:
+                    yield
+                except HTTPException:
+                    raise
+                except Exception as e:
+                    raise PresentationException(
+                        original_exception=e,
+                        request=request,
+                        response=response,
+                        websocket=websocket,
+                    )
 
 
 def create_http_server(

jararaca/presentation/websocket/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later

jararaca/presentation/websocket/base_types.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from typing import ClassVar
 
 from pydantic import BaseModel