jararaca 0.2.37a12__py3-none-any.whl → 0.4.0a5__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
 

jararaca/core/uow.py

@@ -1,14 +1,19 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from contextlib import asynccontextmanager
 from typing import AsyncGenerator, Sequence
 
 from jararaca.microservice import (
-    AppContext,
     AppInterceptor,
+    AppTransactionContext,
     Container,
     Microservice,
     provide_app_context,
     provide_container,
 )
+from jararaca.reflect.metadata import start_transaction_metadata_context
 
 
 class ContainerInterceptor(AppInterceptor):
@@ -17,7 +22,9 @@ class ContainerInterceptor(AppInterceptor):
         self.container = container
 
     @asynccontextmanager
-    async def intercept(self, app_context: AppContext) -> AsyncGenerator[None, None]:
+    async def intercept(
+        self, app_context: AppTransactionContext
+    ) -> AsyncGenerator[None, None]:
 
         with provide_app_context(app_context), provide_container(self.container):
             yield None
@@ -30,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]:
@@ -49,18 +55,51 @@ class UnitOfWorkContextProvider:
         return interceptors
 
     @asynccontextmanager
-    async def __call__(self, app_context: AppContext) -> AsyncGenerator[None, None]:
+    async def __call__(
+        self, app_context: AppTransactionContext
+    ) -> AsyncGenerator[None, None]:
 
         app_interceptors = self.factory_app_interceptors()
-
-        ctxs = [self.container_interceptor.intercept(app_context)] + [
-            interceptor.intercept(app_context) for interceptor in app_interceptors
-        ]
-
-        for ctx in ctxs:
-            await ctx.__aenter__()
-
-        yield None
-
-        for ctx in reversed(ctxs):
-            await ctx.__aexit__(None, None, None)
+        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
+            ]
+
+            for ctx in ctxs:
+                await ctx.__aenter__()
+
+            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/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 @@
-from .types import MessageOf
+# 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,16 +1,22 @@
-import inspect
-from dataclasses import dataclass
-from typing import Any, Awaitable, Callable, Generic, TypeVar, cast
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
 
-from jararaca.messagebus.types import INHERITS_MESSAGE_CO, Message, MessageOf
 
-DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Any])
-DECORATED_CLASS = TypeVar("DECORATED_CLASS", bound=Any)
+import inspect
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
 
+from jararaca.messagebus.message import INHERITS_MESSAGE_CO
+from jararaca.reflect.controller_inspect import (
+    ControllerMemberReflect,
+    inspect_controller,
+)
+from jararaca.reflect.decorators import DECORATED_T, StackableDecorator
+from jararaca.scheduler.decorators import ScheduledAction, ScheduledActionData
 
-class MessageHandler(Generic[INHERITS_MESSAGE_CO]):
 
-    MESSAGE_INCOMING_ATTR = "__message_incoming__"
+class MessageHandler(StackableDecorator):
 
     def __init__(
         self,
@@ -18,117 +24,116 @@ class MessageHandler(Generic[INHERITS_MESSAGE_CO]):
         timeout: int | None = None,
         exception_handler: Callable[[BaseException], None] | None = None,
         nack_on_exception: bool = False,
-        auto_ack: bool = True,
+        auto_ack: bool = False,
+        name: str | 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.auto_ack = auto_ack
-
-    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)
-
-        return func
-
-    @staticmethod
-    def register(
-        func: Callable[[Any, MessageOf[INHERITS_MESSAGE_CO]], Awaitable[None]],
-        message_incoming: "MessageHandler[Any]",
-    ) -> None:
-
-        setattr(func, MessageHandler.MESSAGE_INCOMING_ATTR, message_incoming)
-
-    @staticmethod
-    def get_message_incoming(
-        func: Callable[[MessageOf[Any]], Awaitable[Any]]
-    ) -> "MessageHandler[Message] | None":
-        if not hasattr(func, MessageHandler.MESSAGE_INCOMING_ATTR):
-            return None
-
-        return cast(
-            MessageHandler[Message], getattr(func, MessageHandler.MESSAGE_INCOMING_ATTR)
-        )
+        self.name = name
 
 
 @dataclass(frozen=True)
 class MessageHandlerData:
     message_type: type[Any]
-    spec: MessageHandler[Message]
-    callable: Callable[[MessageOf[Any]], Awaitable[None]]
+    spec: MessageHandler
+    instance_callable: Callable[..., Awaitable[None]]
+    controller_member: ControllerMemberReflect
+
+
+@dataclass(frozen=True)
+class ScheduleDispatchData:
+    timestamp: float
+
 
+SCHEDULED_ACTION_DATA_SET = set[ScheduledActionData]
 
 MESSAGE_HANDLER_DATA_SET = set[MessageHandlerData]
 
 
-class MessageBusController:
+class MessageBusController(StackableDecorator):
 
-    MESSAGEBUS_ATTR = "__messagebus__"
+    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
 
-    def __init__(self) -> None:
-        self.messagebus_factory: Callable[[Any], MESSAGE_HANDLER_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_CLASS], MESSAGE_HANDLER_DATA_SET]:
+    ) -> Callable[
+        [DECORATED_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, func: type[DECORATED_CLASS]) -> type[DECORATED_CLASS]:
+    def post_decorated(self, subject: DECORATED_T) -> None:
 
         def messagebus_factory(
-            instance: DECORATED_CLASS,
-        ) -> MESSAGE_HANDLER_DATA_SET:
+            instance: DECORATED_T,
+        ) -> tuple[MESSAGE_HANDLER_DATA_SET, SCHEDULED_ACTION_DATA_SET]:
             handlers: MESSAGE_HANDLER_DATA_SET = set()
-            inspect.signature(func)
 
-            members = inspect.getmembers(func, predicate=inspect.isfunction)
+            schedulers: SCHEDULED_ACTION_DATA_SET = set()
 
-            for name, member in members:
-                message_incoming = MessageHandler.get_message_incoming(member)
+            assert inspect.isclass(
+                subject
+            ), "MessageBusController can only be applied to classes"
 
-                if message_incoming is None:
-                    continue
+            _, members = inspect_controller(subject)
 
-                if not inspect.iscoroutinefunction(member):
-                    raise Exception(
-                        "Message incoming handler '%s' from '%s.%s' must be a coroutine function"
-                        % (name, func.__module__, func.__qualname__)
-                    )
+            for name, member in members.items():
+                message_handler_decoration = MessageHandler.get_last(
+                    member.member_function
+                )
+                scheduled_action_decoration = ScheduledAction.get_last(
+                    member.member_function
+                )
 
-                handlers.add(
-                    MessageHandlerData(
-                        message_type=message_incoming.message_type,
-                        spec=message_incoming,
-                        callable=getattr(instance, name),
+                if message_handler_decoration is not None:
+
+                    if not inspect.iscoroutinefunction(member.member_function):
+                        raise Exception(
+                            "Message incoming handler '%s' from '%s.%s' must be a coroutine function"
+                            % (name, subject.__module__, subject.__qualname__)
+                        )
+
+                    handlers.add(
+                        MessageHandlerData(
+                            message_type=message_handler_decoration.message_type,
+                            spec=message_handler_decoration,
+                            instance_callable=getattr(instance, name),
+                            controller_member=member,
+                        )
+                    )
+                elif scheduled_action_decoration is not None:
+                    if not inspect.iscoroutinefunction(member.member_function):
+                        raise Exception(
+                            "Scheduled action handler '%s' from '%s.%s' must be a coroutine function"
+                            % (name, subject.__module__, subject.__qualname__)
+                        )
+                    instance_callable = getattr(instance, name)
+
+                    schedulers.add(
+                        ScheduledActionData(
+                            controller_member=member,
+                            spec=scheduled_action_decoration,
+                            callable=instance_callable,
+                        )
                     )
-                )
 
-            return handlers
+            return handlers, schedulers
 
         self.messagebus_factory = messagebus_factory
-
-        MessageBusController.register(func, self)
-
-        return func
-
-    @staticmethod
-    def register(
-        func: type[DECORATED_CLASS], messagebus: "MessageBusController"
-    ) -> None:
-
-        setattr(func, MessageBusController.MESSAGEBUS_ATTR, messagebus)
-
-    @staticmethod
-    def get_messagebus(func: type[DECORATED_CLASS]) -> "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

jararaca/messagebus/interceptors/aiopika_publisher_interceptor.py

@@ -1,57 +1,110 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import logging
 from contextlib import asynccontextmanager
-from typing import Any, AsyncContextManager, AsyncGenerator, Protocol
+from datetime import datetime, timedelta
+from datetime import tzinfo as _TzInfo
+from typing import Any, AsyncGenerator
 
 import aio_pika
 from aio_pika.abc import AbstractConnection
 from pydantic import BaseModel
 
-from jararaca.messagebus.publisher import MessagePublisher, provide_message_publisher
-from jararaca.microservice import AppContext, AppInterceptor
-
+from jararaca.broker_backend import MessageBrokerBackend
+from jararaca.messagebus import implicit_headers
+from jararaca.messagebus.interceptors.publisher_interceptor import (
+    MessageBusConnectionFactory,
+)
+from jararaca.messagebus.publisher import IMessage, MessagePublisher
+from jararaca.scheduler.types import DelayedMessageData
 
-class MessageBusConnectionFactory(Protocol):
+logger = logging.getLogger(__name__)
 
-    def provide_connection(self) -> AsyncContextManager[MessagePublisher]: ...
 
-
-class MessageBusPublisherInterceptor(AppInterceptor):
+class AIOPikaMessagePublisher(MessagePublisher):
 
     def __init__(
         self,
-        connection_factory: MessageBusConnectionFactory,
-        connection_name: str = "default",
+        channel: aio_pika.abc.AbstractChannel,
+        exchange_name: str,
+        message_broker_backend: MessageBrokerBackend | None = None,
     ):
-        self.connection_factory = connection_factory
-        self.connection_name = connection_name
-
-    @asynccontextmanager
-    async def intercept(self, app_context: AppContext) -> AsyncGenerator[None, None]:
-        if app_context.context_type == "websocket":
-            yield
-            return
 
-        async with self.connection_factory.provide_connection() as connection:
-            with provide_message_publisher(self.connection_name, connection):
-                yield
-
-
-class AIOPikaMessagePublisher(MessagePublisher):
-
-    def __init__(self, channel: aio_pika.abc.AbstractChannel, exchange_name: str):
         self.channel = channel
         self.exchange_name = exchange_name
+        self.message_broker_backend = message_broker_backend
+        self.staged_delayed_messages: list[DelayedMessageData] = []
+        self.staged_messages: list[IMessage] = []
 
-    async def publish(self, message: BaseModel, topic: str) -> None:
-        exchange = await self.channel.declare_exchange(
-            self.exchange_name,
-            type=aio_pika.ExchangeType.TOPIC,
-        )
-        routing_key = f"{self.exchange_name}.{topic}."
+    async def publish(self, message: IMessage, topic: str) -> None:
+        self.staged_messages.append(message)
+
+    async def _publish(self, message: IMessage, topic: str) -> None:
+        exchange = await self.channel.get_exchange(self.exchange_name, ensure=False)
+        if not exchange:
+            logging.warning(f"Exchange {self.exchange_name} not found")
+            return
+        routing_key = f"{topic}.#"
+
+        implicit_headers_data = implicit_headers.use_implicit_headers()
         await exchange.publish(
-            aio_pika.Message(body=message.model_dump_json().encode()),
+            aio_pika.Message(
+                body=message.model_dump_json().encode(), headers=implicit_headers_data
+            ),
             routing_key=routing_key,
         )
 
+    async def delay(self, message: IMessage, seconds: int) -> None:
+        if not self.message_broker_backend:
+            raise NotImplementedError(
+                "Delay is not implemented for AIOPikaMessagePublisher"
+            )
+        self.staged_delayed_messages.append(
+            DelayedMessageData(
+                message_topic=message.MESSAGE_TOPIC,
+                payload=message.model_dump_json().encode(),
+                dispatch_time=int(
+                    (datetime.now(tz=None) + timedelta(seconds=seconds)).timestamp()
+                ),
+            )
+        )
+
+    async def schedule(self, message: IMessage, when: datetime, tz: _TzInfo) -> None:
+        if not self.message_broker_backend:
+            raise NotImplementedError(
+                "Schedule is not implemented for AIOPikaMessagePublisher"
+            )
+        self.staged_delayed_messages.append(
+            DelayedMessageData(
+                message_topic=message.MESSAGE_TOPIC,
+                payload=message.model_dump_json().encode(),
+                dispatch_time=int(when.timestamp()),
+            )
+        )
+
+    async def flush(self) -> None:
+        for message in self.staged_messages:
+            logger.debug(
+                f"Publishing message {message.MESSAGE_TOPIC} with payload: {message.model_dump_json()}"
+            )
+            await self._publish(message, message.MESSAGE_TOPIC)
+
+        if len(self.staged_delayed_messages) > 0:
+            if not self.message_broker_backend:
+                raise NotImplementedError(
+                    "MessageBrokerBackend is required to publish delayed messages"
+                )
+
+            for delayed_message in self.staged_delayed_messages:
+                logger.debug(
+                    f"Scheduling delayed message {delayed_message.message_topic} with payload: {delayed_message.payload.decode()}"
+                )
+                await self.message_broker_backend.enqueue_delayed_message(
+                    delayed_message
+                )
+
 
 class GenericPoolConfig(BaseModel):
     max_size: int
@@ -65,10 +118,11 @@ class AIOPikaConnectionFactory(MessageBusConnectionFactory):
         exchange: str,
         connection_pool_config: GenericPoolConfig | None = None,
         channel_pool_config: GenericPoolConfig | None = None,
+        message_broker_backend: MessageBrokerBackend | None = None,
     ):
         self.url = url
         self.exchange = exchange
-
+        self.message_broker_backend = message_broker_backend
         self.connection_pool: aio_pika.pool.Pool[AbstractConnection] | None = None
         self.channel_pool: aio_pika.pool.Pool[aio_pika.abc.AbstractChannel] | None = (
             None
@@ -77,7 +131,7 @@ class AIOPikaConnectionFactory(MessageBusConnectionFactory):
         if connection_pool_config:
 
             async def get_connection() -> AbstractConnection:
-                return await aio_pika.connect_robust(self.url)
+                return await aio_pika.connect(self.url)
 
             self.connection_pool = aio_pika.pool.Pool[AbstractConnection](
                 get_connection,
@@ -97,7 +151,7 @@ class AIOPikaConnectionFactory(MessageBusConnectionFactory):
     @asynccontextmanager
     async def acquire_connection(self) -> AsyncGenerator[AbstractConnection, Any]:
         if not self.connection_pool:
-            async with await aio_pika.connect_robust(self.url) as connection:
+            async with await aio_pika.connect(self.url) as connection:
                 yield connection
         else:
 
@@ -124,7 +178,11 @@ class AIOPikaConnectionFactory(MessageBusConnectionFactory):
             await tx.select()
 
             try:
-                yield AIOPikaMessagePublisher(channel, exchange_name=self.exchange)
+                yield AIOPikaMessagePublisher(
+                    channel,
+                    exchange_name=self.exchange,
+                    message_broker_backend=self.message_broker_backend,
+                )
                 await tx.commit()
             except Exception as e:
                 await tx.rollback()