jararaca 0.3.11a16__py3-none-any.whl → 0.4.0a5__py3-none-any.whl

jararaca/persistence/utilities.py

@@ -1,5 +1,10 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import asyncio
 import logging
+import math
 from datetime import UTC, date, datetime
 from functools import reduce
 from typing import (
@@ -29,6 +34,7 @@ from jararaca.persistence.base import (
     BaseEntity,
     recursive_get_dict,
 )
+from jararaca.persistence.interceptors.aiosqa_interceptor import use_session
 from jararaca.persistence.sort_filter import (
     FilterModel,
     FilterRuleApplier,
@@ -61,7 +67,7 @@ class DatedEntity(BaseEntity):
         DateTime(timezone=True), nullable=False, default=nowutc
     )
     updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), nullable=False, default=nowutc
+        DateTime(timezone=True), nullable=False, default=nowutc, onupdate=nowutc
     )
 
 
@@ -283,11 +289,13 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
     def __init__(
         self,
         entity_type: Type[QUERY_ENTITY_T],
-        session_provider: Callable[[], AsyncSession],
-        filters_functions: list[QueryInjector],
+        session_provider: Callable[[], AsyncSession] = use_session,
+        filters_functions: list[QueryInjector] = [],
+        *,
         unique: bool = False,
         sort_rule_applier: SortRuleApplier | None = None,
         filter_rule_applier: FilterRuleApplier | None = None,
+        base_statement: Select[Tuple[QUERY_ENTITY_T]] | None = None,
     ) -> None:
         self.entity_type: type[QUERY_ENTITY_T] = entity_type
         self.session_provider = session_provider
@@ -295,6 +303,7 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
         self.unique = unique
         self.sort_rule_applier = sort_rule_applier
         self.filter_rule_applier = filter_rule_applier
+        self.base_statement = base_statement
 
     @property
     def session(self) -> AsyncSession:
@@ -303,9 +312,15 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
     async def query(
         self,
         filter: QUERY_FILTER_T,
+        *,
         interceptors: list[
             Callable[[Select[Tuple[QUERY_ENTITY_T]]], Select[Tuple[QUERY_ENTITY_T]]]
         ] = [],
+        base_statement: (
+            Callable[[Select[Tuple[QUERY_ENTITY_T]]], Select[Tuple[QUERY_ENTITY_T]]]
+            | Select[Tuple[QUERY_ENTITY_T]]
+            | None
+        ) = None,
     ) -> "Paginated[QUERY_ENTITY_T]":
         """
         Executes a query with the provided filter and interceptors.
@@ -316,8 +331,15 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
             Paginated[QUERY_ENTITY_T]: A paginated result containing the items and metadata.
         """
 
+        initial_statement = self.base_statement or select(self.entity_type)
+
+        if base_statement and callable(base_statement):
+            initial_statement = base_statement(initial_statement)
+        elif base_statement and isinstance(base_statement, Select):
+            initial_statement = base_statement
+
         tier_one_filtered_query = self.generate_filtered_query(
-            filter, select(self.entity_type)
+            filter, initial_statement
         )
 
         tier_two_filtered_query = reduce(
@@ -340,30 +362,38 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
                 )
             )
 
-        unpaginated_total = (
-            await self.session.execute(
-                select(func.count()).select_from(tier_two_filtered_query.subquery())
-            )
-        ).scalar_one()
-
-        paginated_query = tier_two_filtered_query.limit(filter.page_size).offset(
+        paginated_query = tier_two_filtered_query.add_columns(
+            func.count().over().label("total_count")
+        )
+        paginated_query = paginated_query.limit(filter.page_size).offset(
             (filter.page) * filter.page_size
         )
 
-        paginated_total = (
-            await self.session.execute(
-                select(func.count()).select_from(paginated_query.subquery())
-            )
-        ).scalar_one()
-
         result = await self.session.execute(paginated_query)
-        result_scalars = list(self.judge_unique(result).scalars().all())
+        result = self.judge_unique(result)
+        rows = result.all()
+
+        if rows:
+            unpaginated_total = rows[0].total_count
+            result_scalars = [row[0] for row in rows]
+        else:
+            result_scalars = []
+            if filter.page == 0:
+                unpaginated_total = 0
+            else:
+                unpaginated_total = (
+                    await self.session.execute(
+                        select(func.count()).select_from(
+                            tier_two_filtered_query.subquery()
+                        )
+                    )
+                ).scalar_one()
 
         return Paginated(
             items=result_scalars,
-            total=paginated_total,
+            total=len(result_scalars),
             unpaginated_total=unpaginated_total,
-            total_pages=int(unpaginated_total / filter.page_size) + 1,
+            total_pages=math.ceil(unpaginated_total / filter.page_size),
         )
 
     def judge_unique(

jararaca/presentation/__init__.py

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

jararaca/presentation/decorators.py

@@ -1,7 +1,12 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import inspect
 from contextlib import contextmanager
 from contextvars import ContextVar
 from functools import wraps
-from typing import Any, Awaitable, Callable, Literal, Protocol, TypeVar, cast
+from typing import Any, Awaitable, Callable, Literal, Mapping, Protocol, TypeVar
 
 from fastapi import APIRouter
 from fastapi import Depends as DependsF
@@ -15,12 +20,13 @@ 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):
@@ -28,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,
@@ -50,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:
@@ -64,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(
@@ -79,15 +99,23 @@ class RestController:
                 **(self.options or {}),
             )
 
-            controller, members = inspect_controller(cls)
+            controller, members = inspect_controller(subject)
 
             router_members = [
                 (name, mapping, member)
                 for name, member in members.items()
                 if (
-                    mapping := (
-                        HttpMapping.get_http_mapping(member.member_function)
-                        or WebSocketEndpoint.get(member.member_function)
+                    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
@@ -97,17 +125,22 @@ class RestController:
 
             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)
@@ -141,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]
 
@@ -170,9 +188,8 @@ ResponseType = Literal[
 ]
 
 
-class HttpMapping:
+class HttpMapping(StackableDecorator):
 
-    HTTP_MAPPING_ATTR = "__http_mapping__"
     ORDER_COUNTER = 0
 
     def __init__(
@@ -190,24 +207,20 @@ class HttpMapping:
         HttpMapping.ORDER_COUNTER += 1
         self.order = HttpMapping.ORDER_COUNTER
 
-    def __call__(self, func: DECORATED_FUNC) -> DECORATED_FUNC:
-
-        HttpMapping.register(func, self)
-
-        return func
+    @classmethod
+    def decorator_key(cls) -> "type[HttpMapping]":
+        return HttpMapping
 
-    @staticmethod
-    def register(func: DECORATED_FUNC, mapping: "HttpMapping") -> None:
+    # def __call__(self, func: DECORATED_FUNC) -> DECORATED_FUNC:
 
-        setattr(func, HttpMapping.HTTP_MAPPING_ATTR, mapping)
+    #     HttpMapping.register(func, self)
 
-    @staticmethod
-    def get_http_mapping(func: DECORATED_FUNC) -> "HttpMapping | None":
+    #     return func
 
-        if not hasattr(func, HttpMapping.HTTP_MAPPING_ATTR):
-            return None
+    # @staticmethod
+    # def register(func: DECORATED_FUNC, mapping: "HttpMapping") -> None:
 
-        return cast(HttpMapping, getattr(func, HttpMapping.HTTP_MAPPING_ATTR))
+    #     setattr(func, HttpMapping.HTTP_MAPPING_ATTR, mapping)
 
 
 class Post(HttpMapping):
@@ -265,52 +278,46 @@ 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)
-
-        return subject
-
-    @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__, [])
-
 
-class UseDependency:
-
-    __DEPENDENCY_ATTR__ = "__dependencies__"
+class UseDependency(StackableDecorator):
 
     def __init__(self, dependency: Any) -> None:
         self.dependency = dependency
 
-    def __call__(self, subject: DECORATED_FUNC) -> DECORATED_FUNC:
 
-        UseDependency.register(subject, self)
+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.
 
-        return subject
+    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.
 
-    @staticmethod
-    def register(subject: DECORATED_FUNC, dependency: "UseDependency") -> None:
-        dependencies = getattr(subject, UseDependency.__DEPENDENCY_ATTR__, [])
-        dependencies.append(dependency)
-        setattr(subject, UseDependency.__DEPENDENCY_ATTR__, dependencies)
+    Returns:
+        Callable[[DECORATED_TYPE], DECORATED_TYPE]: A single decorator that applies all the given decorators.
 
-    @staticmethod
-    def get_dependencies(subject: DECORATED_FUNC) -> list["UseDependency"]:
-        return getattr(subject, UseDependency.__DEPENDENCY_ATTR__, [])
+    Example:
+        IsWorkspaceAdmin = compose_route_decorators(
+            UseMiddleware(AuthMiddleware),
+            UseMiddleware(IsWorkspaceScoped),
+            UseMiddleware(RequiresAdminRole),
+        )
+    """
+
+    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(
@@ -330,11 +337,6 @@ def wraps_with_member_data(
 
             return await func(*args, **kwargs)
 
-    # Copy metadata from the original function to the wrapper
-    # for attr in dir(func):
-    #     if not attr.startswith("__"):
-    #         setattr(wrapper, attr, getattr(func, 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,7 +1,17 @@
+# 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
@@ -10,12 +20,18 @@ from jararaca.lifecycle import AppLifecycle
 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:
 
@@ -31,58 +47,83 @@ 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]:
         if request:
             endpoint = request.scope["endpoint"]
@@ -101,17 +142,28 @@ class HttpUowContextProviderDependency:
             "ControllerMemberReflect, but got: {}".format(type(member))
         )
 
-        async with self.uow_provider(
-            AppTransactionContext(
-                controller_member_reflect=member,
-                transaction_data=(
-                    HttpTransactionData(request=request)
-                    if request
-                    else WebSocketTransactionData(websocket=websocket)
-                ),
-            )
-        ):
-            yield
+        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(