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

jararaca/common/__init__.py

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

jararaca/core/__init__.py

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

jararaca/core/providers.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from dataclasses import dataclass
 from typing import Any, Callable, Generic, Type, TypeVar
 
@@ -9,6 +13,10 @@ class Token(Generic[T]):
     type_: Type[T]
     name: str
 
+    @classmethod
+    def create(cls, type_: Type[T], name: str) -> "Token[T]":
+        return cls(type_=type_, name=name)
+
 
 @dataclass
 class ProviderSpec:

jararaca/core/uow.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from contextlib import asynccontextmanager
 from typing import AsyncGenerator, Sequence
 
@@ -9,7 +13,7 @@ from jararaca.microservice import (
     provide_app_context,
     provide_container,
 )
-from jararaca.reflect.metadata import provide_metadata
+from jararaca.reflect.metadata import start_transaction_metadata_context
 
 
 class ContainerInterceptor(AppInterceptor):
@@ -33,7 +37,6 @@ class UnitOfWorkContextProvider:
         self.container = container
         self.container_interceptor = ContainerInterceptor(container)
 
-    # TODO: Guarantee that the context is closed whenever an exception is raised
     # TODO: Guarantee a unit of work workflow for the whole request, including all the interceptors
 
     def factory_app_interceptors(self) -> Sequence[AppInterceptor]:
@@ -57,7 +60,9 @@ class UnitOfWorkContextProvider:
     ) -> AsyncGenerator[None, None]:
 
         app_interceptors = self.factory_app_interceptors()
-        with provide_metadata(app_context.controller_member_reflect.metadata):
+        with start_transaction_metadata_context(
+            app_context.controller_member_reflect.metadata
+        ):
             ctxs = [self.container_interceptor.intercept(app_context)] + [
                 interceptor.intercept(app_context) for interceptor in app_interceptors
             ]
@@ -65,7 +70,36 @@ class UnitOfWorkContextProvider:
             for ctx in ctxs:
                 await ctx.__aenter__()
 
-            yield None
-
-            for ctx in reversed(ctxs):
-                await ctx.__aexit__(None, None, None)
+            exc_type = None
+            exc_value = None
+            exc_traceback = None
+
+            try:
+                yield None
+            except BaseException as e:
+                exc_type = type(e)
+                exc_value = e
+                exc_traceback = e.__traceback__
+                raise
+            finally:
+                # Exit interceptors in reverse order, propagating exception info
+                for ctx in reversed(ctxs):
+                    try:
+                        suppressed = await ctx.__aexit__(
+                            exc_type, exc_value, exc_traceback
+                        )
+                        # If an interceptor returns True, it suppresses the exception
+                        if suppressed and exc_type is not None:
+                            exc_type = None
+                            exc_value = None
+                            exc_traceback = None
+                    except BaseException as exit_exc:
+                        # If an interceptor raises an exception during cleanup,
+                        # replace the original exception with the new one
+                        exc_type = type(exit_exc)
+                        exc_value = exit_exc
+                        exc_traceback = exit_exc.__traceback__
+
+                # Re-raise the exception if it wasn't suppressed
+                if exc_type is not None and exc_value is not None:
+                    raise exc_value.with_traceback(exc_traceback)

jararaca/di.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from jararaca.microservice import Container
 
 __all__ = [

jararaca/files/entity.py.mako

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from datetime import datetime
 from typing import Annotated
 from uuid import UUID, uuid4

jararaca/helpers/__init__.py

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

jararaca/helpers/global_scheduler/__init__.py

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

jararaca/helpers/global_scheduler/config.py

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Annotated
+
+from pydantic import BaseModel
+
+from jararaca.core.providers import Token
+
+
+class GlobalSchedulerConfig(BaseModel):
+    MAX_CONCURRENT_JOBS: int = 10
+
+
+GlobalSchedulerConfigToken = Token.create(
+    GlobalSchedulerConfig, "GlobalSchedulerConfig"
+)
+GlobalSchedulerConfigAnnotated = Annotated[
+    GlobalSchedulerConfig, GlobalSchedulerConfigToken
+]

jararaca/helpers/global_scheduler/controller.py

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import asyncio
+
+from jararaca.helpers.global_scheduler.config import GlobalSchedulerConfigAnnotated
+from jararaca.helpers.global_scheduler.registry import (
+    GlobalScheduleFnType,
+    GlobalSchedulerRegistry,
+)
+from jararaca.messagebus.decorators import MessageBusController
+from jararaca.scheduler.decorators import ScheduledAction
+from jararaca.utils.env_parse_utils import get_env_str
+
+SCHEDULER_CRON = get_env_str("SCHEDULER_CRON", "*/5 * * * *")
+
+
+@MessageBusController()
+class GlobalSchedulerController:
+
+    def __init__(self, config: GlobalSchedulerConfigAnnotated):
+        self._config = config
+
+    @ScheduledAction(cron=SCHEDULER_CRON)
+    async def trigger_scheduled_actions(self) -> None:
+        """Trigger all registered scheduled actions."""
+
+        taks = []
+
+        semaphore = asyncio.Semaphore(self._config.MAX_CONCURRENT_JOBS)
+
+        for action in GlobalSchedulerRegistry.get_registered_actions():
+            task = asyncio.create_task(self._run_with_semaphore(semaphore, action))
+
+            taks.append(task)
+
+    async def _run_with_semaphore(
+        self, semaphore: asyncio.Semaphore, action: GlobalScheduleFnType
+    ) -> None:
+        async with semaphore:
+            await action()

jararaca/helpers/global_scheduler/registry.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+
+from typing import Any, Awaitable, Callable
+
+GlobalScheduleFnType = Callable[[], Awaitable[Any]]
+
+
+class GlobalSchedulerRegistry:
+    """Registry for the Global Scheduler helper."""
+
+    _REGISTRY: list[GlobalScheduleFnType] = []
+
+    @classmethod
+    def register(cls, fn: GlobalScheduleFnType) -> None:
+        """Register a scheduled action function.
+
+        Args:
+            fn: The scheduled action function to register.
+        """
+        cls._REGISTRY.append(fn)
+
+    @classmethod
+    def get_registered_actions(cls) -> list[GlobalScheduleFnType]:
+        """Get the list of registered scheduled action functions.
+
+        Returns:
+            A list of registered scheduled action functions.
+        """
+        return cls._REGISTRY

jararaca/lifecycle.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import logging
 from contextlib import asynccontextmanager
 from typing import AsyncContextManager, AsyncGenerator, Sequence
@@ -33,7 +37,7 @@ class AppLifecycle:
         self.container.fill_providers(False)
         lifecycle_ctxs: list[AsyncContextManager[None]] = []
 
-        logger.info("Initializing interceptors lifecycle")
+        logger.debug("Initializing interceptors lifecycle")
         for interceptor_dep in self.app.interceptors:
             interceptor: AppInterceptor
             if not isinstance(interceptor_dep, AppInterceptor):
@@ -57,6 +61,6 @@ class AppLifecycle:
 
         yield
 
-        logger.info("Finalizing interceptors lifecycle")
+        logger.debug("Finalizing interceptors lifecycle")
         for ctx in lifecycle_ctxs:
             await ctx.__aexit__(None, None, None)

jararaca/messagebus/__init__.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from .message import MessageOf
 
 __all__ = ["MessageOf"]

jararaca/messagebus/bus_message_controller.py

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

jararaca/messagebus/consumers/__init__.py

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

jararaca/messagebus/decorators.py

@@ -1,72 +1,140 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+
 import inspect
 from dataclasses import dataclass
-from typing import Any, Awaitable, Callable, Generic, TypeVar, cast
+from typing import Any, Awaitable, Callable, Literal, TypeVar, cast, get_args
 
 from jararaca.messagebus.message import INHERITS_MESSAGE_CO, Message, MessageOf
 from jararaca.reflect.controller_inspect import (
     ControllerMemberReflect,
     inspect_controller,
 )
+from jararaca.reflect.decorators import (
+    FUNC_OR_TYPE_T,
+    GenericStackableDecorator,
+    StackableDecorator,
+)
+from jararaca.reflect.helpers import is_generic_alias
 from jararaca.scheduler.decorators import ScheduledAction, ScheduledActionData
+from jararaca.utils.env_parse_utils import get_env_float, get_env_int, is_env_truffy
+from jararaca.utils.retry import RetryPolicy
 
-DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Any])
-DECORATED_T = TypeVar("DECORATED_T", bound=Any)
+AcceptableHandler = (
+    Callable[[Any, MessageOf[Any]], Awaitable[None]]
+    | Callable[[Any, Any], Awaitable[None]]
+)
+MessageHandlerT = TypeVar("MessageHandlerT", bound=AcceptableHandler)
 
+DEFAULT_TIMEOUT = get_env_int("JARARACA_MESSAGEBUS_HANDLER_TIMEOUT")
+DEFAULT_NACK_ON_EXCEPTION = is_env_truffy("JARARACA_MESSAGEBUS_NACK_ON_EXCEPTION")
+DEFAULT_AUTO_ACK = is_env_truffy("JARARACA_MESSAGEBUS_AUTO_ACK")
+DEFAULT_NACK_DELAY_ON_EXCEPTION = get_env_float(
+    "JARARACA_MESSAGEBUS_NACK_DELAY_ON_EXCEPTION"
+)
 
-class MessageHandler(Generic[INHERITS_MESSAGE_CO]):
 
-    MESSAGE_INCOMING_ATTR = "__message_incoming__"
+class MessageHandler(GenericStackableDecorator[AcceptableHandler]):
 
     def __init__(
         self,
         message: type[INHERITS_MESSAGE_CO],
-        timeout: int | None = None,
+        *,
+        timeout: int | None = DEFAULT_TIMEOUT if DEFAULT_TIMEOUT is not False else None,
         exception_handler: Callable[[BaseException], None] | None = None,
-        nack_on_exception: bool = False,
-        auto_ack: bool = True,
+        nack_on_exception: bool = DEFAULT_NACK_ON_EXCEPTION,
+        nack_delay_on_exception: float = DEFAULT_NACK_DELAY_ON_EXCEPTION or 5.0,
+        auto_ack: bool = DEFAULT_AUTO_ACK,
         name: str | None = None,
+        retry_config: RetryPolicy | None = None,
     ) -> None:
         self.message_type = message
 
         self.timeout = timeout
         self.exception_handler = exception_handler
-        self.requeue_on_exception = nack_on_exception
+        self.nack_on_exception = nack_on_exception
+        self.nack_delay_on_exception = nack_delay_on_exception
+
         self.auto_ack = auto_ack
         self.name = name
+        self.retry_config = retry_config
 
-    def __call__(
-        self, func: Callable[[Any, MessageOf[INHERITS_MESSAGE_CO]], Awaitable[None]]
-    ) -> Callable[[Any, MessageOf[INHERITS_MESSAGE_CO]], Awaitable[None]]:
-
-        MessageHandler[Any].register(func, self)
+    def __call__(self, subject: MessageHandlerT) -> MessageHandlerT:
+        return cast(MessageHandlerT, super().__call__(subject))
 
-        return func
+    def pre_decorated(self, subject: FUNC_OR_TYPE_T) -> None:
+        MessageHandler.validate_decorated_fn(subject)
 
     @staticmethod
-    def register(
-        func: Callable[[Any, MessageOf[INHERITS_MESSAGE_CO]], Awaitable[None]],
-        message_incoming: "MessageHandler[Any]",
-    ) -> None:
+    def validate_decorated_fn(
+        subject: FUNC_OR_TYPE_T,
+    ) -> tuple[Literal["WRAPPED", "DIRECT"], type[Message]]:
+        """Validates that the decorated function has the correct signature
+        the decorated must follow one of the patterns:
 
-        setattr(func, MessageHandler.MESSAGE_INCOMING_ATTR, message_incoming)
+        async def handler(self, message: MessageOf[YourMessageType]) -> None:
+            ...
 
-    @staticmethod
-    def get_message_incoming(
-        func: Callable[[MessageOf[Any]], Awaitable[Any]],
-    ) -> "MessageHandler[Message] | None":
-        if not hasattr(func, MessageHandler.MESSAGE_INCOMING_ATTR):
-            return None
+        async def handler(self, message: YourMessageType) -> None:
+            ...
+
+        """
+
+        if not inspect.iscoroutinefunction(subject):
+            raise RuntimeError(
+                "Message handler '%s' must be a coroutine function"
+                % (subject.__qualname__)
+            )
+
+        signature = inspect.signature(subject)
+
+        parameters = list(signature.parameters.values())
+
+        if len(parameters) != 2:
+            raise RuntimeError(
+                "Message handler '%s' must have exactly two parameters (self, message)"
+                % (subject.__qualname__)
+            )
+
+        message_param = parameters[1]
+
+        if message_param.annotation is inspect.Parameter.empty:
+            raise RuntimeError(
+                "Message handler '%s' must have type annotation for the message parameter"
+                % (subject.__qualname__)
+            )
+
+        annotation_type = message_param.annotation
+        mode: Literal["WRAPPED", "DIRECT"]
+        if is_generic_alias(annotation_type):
+
+            message_model_type = get_args(annotation_type)[0]
 
-        return cast(
-            MessageHandler[Message], getattr(func, MessageHandler.MESSAGE_INCOMING_ATTR)
-        )
+            mode = "WRAPPED"
+
+        else:
+            message_model_type = annotation_type
+
+            mode = "DIRECT"
+
+        if not inspect.isclass(message_model_type) or not issubclass(
+            message_model_type, Message
+        ):
+            raise RuntimeError(
+                "Message handler '%s' message parameter must be of type 'MessageOf[YourMessageType]' or 'YourMessageType' where 'YourMessageType' is a subclass of 'Message'"
+                % (subject.__qualname__)
+            )
+
+        return mode, message_model_type
 
 
 @dataclass(frozen=True)
 class MessageHandlerData:
     message_type: type[Any]
-    spec: MessageHandler[Message]
-    instance_callable: Callable[[MessageOf[Any]], Awaitable[None]]
+    spec: MessageHandler
+    instance_callable: Callable[..., Awaitable[None]]
     controller_member: ControllerMemberReflect
 
 
@@ -80,41 +148,51 @@ SCHEDULED_ACTION_DATA_SET = set[ScheduledActionData]
 MESSAGE_HANDLER_DATA_SET = set[MessageHandlerData]
 
 
-class MessageBusController:
-
-    MESSAGEBUS_ATTR = "__messagebus__"
+class MessageBusController(StackableDecorator):
 
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        *,
+        inherit_class_decorators: bool = True,
+        inherit_methods_decorators: bool = True,
+    ) -> None:
         self.messagebus_factory: (
             Callable[[Any], tuple[MESSAGE_HANDLER_DATA_SET, SCHEDULED_ACTION_DATA_SET]]
             | None
         ) = None
 
+        self.inherit_class_decorators = inherit_class_decorators
+        self.inherit_methods_decorators = inherit_methods_decorators
+
     def get_messagebus_factory(
         self,
     ) -> Callable[
-        [DECORATED_T], tuple[MESSAGE_HANDLER_DATA_SET, SCHEDULED_ACTION_DATA_SET]
+        [FUNC_OR_TYPE_T], tuple[MESSAGE_HANDLER_DATA_SET, SCHEDULED_ACTION_DATA_SET]
     ]:
         if self.messagebus_factory is None:
             raise Exception("MessageBus factory is not set")
         return self.messagebus_factory
 
-    def __call__(self, cls_t: type[DECORATED_T]) -> type[DECORATED_T]:
+    def post_decorated(self, subject: FUNC_OR_TYPE_T) -> None:
 
         def messagebus_factory(
-            instance: DECORATED_T,
+            instance: FUNC_OR_TYPE_T,
         ) -> tuple[MESSAGE_HANDLER_DATA_SET, SCHEDULED_ACTION_DATA_SET]:
             handlers: MESSAGE_HANDLER_DATA_SET = set()
 
             schedulers: SCHEDULED_ACTION_DATA_SET = set()
 
-            _, members = inspect_controller(cls_t)
+            assert inspect.isclass(
+                subject
+            ), "MessageBusController can only be applied to classes"
+
+            _, members = inspect_controller(subject)
 
             for name, member in members.items():
-                message_handler_decoration = MessageHandler.get_message_incoming(
+                message_handler_decoration = MessageHandler.get_last(
                     member.member_function
                 )
-                scheduled_action_decoration = ScheduledAction.get_scheduled_action(
+                scheduled_action_decoration = ScheduledAction.get_last(
                     member.member_function
                 )
 
@@ -123,7 +201,7 @@ class MessageBusController:
                     if not inspect.iscoroutinefunction(member.member_function):
                         raise Exception(
                             "Message incoming handler '%s' from '%s.%s' must be a coroutine function"
-                            % (name, cls_t.__module__, cls_t.__qualname__)
+                            % (name, subject.__module__, subject.__qualname__)
                         )
 
                     handlers.add(
@@ -138,7 +216,7 @@ class MessageBusController:
                     if not inspect.iscoroutinefunction(member.member_function):
                         raise Exception(
                             "Scheduled action handler '%s' from '%s.%s' must be a coroutine function"
-                            % (name, cls_t.__module__, cls_t.__qualname__)
+                            % (name, subject.__module__, subject.__qualname__)
                         )
                     instance_callable = getattr(instance, name)
 
@@ -153,21 +231,3 @@ class MessageBusController:
             return handlers, schedulers
 
         self.messagebus_factory = messagebus_factory
-
-        MessageBusController.register(cls_t, self)
-
-        return cls_t
-
-    @staticmethod
-    def register(func: type[DECORATED_T], messagebus: "MessageBusController") -> None:
-
-        setattr(func, MessageBusController.MESSAGEBUS_ATTR, messagebus)
-
-    @staticmethod
-    def get_messagebus(func: type[DECORATED_T]) -> "MessageBusController | None":
-        if not hasattr(func, MessageBusController.MESSAGEBUS_ATTR):
-            return None
-
-        return cast(
-            MessageBusController, getattr(func, MessageBusController.MESSAGEBUS_ATTR)
-        )

jararaca/messagebus/implicit_headers.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import datetime
+import decimal
+import typing
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any, Dict, Generator
+
+FieldArray = list["FieldValue"]
+"""A data structure for holding an array of field values."""
+
+FieldTable = typing.Dict[str, "FieldValue"]
+FieldValue = (
+    bool
+    | bytes
+    | bytearray
+    | decimal.Decimal
+    | FieldArray
+    | FieldTable
+    | float
+    | int
+    | None
+    | str
+    | datetime.datetime
+)
+
+ImplicitHeaders = Dict[str, FieldValue]
+
+implicit_headers_ctx = ContextVar[ImplicitHeaders | None](
+    "implicit_headers_ctx", default=None
+)
+
+
+def use_implicit_headers() -> ImplicitHeaders | None:
+    return implicit_headers_ctx.get()
+
+
+@contextmanager
+def provide_implicit_headers(
+    implicit_headers: ImplicitHeaders,
+) -> Generator[None, Any, None]:
+    token = implicit_headers_ctx.set(implicit_headers)
+    try:
+        yield
+    finally:
+        implicit_headers_ctx.reset(token)

jararaca/messagebus/interceptors/__init__.py

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