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

jararaca/broker_backend/__init__.py

@@ -0,0 +1,106 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from abc import ABC
+from contextlib import asynccontextmanager
+from typing import AsyncContextManager, AsyncGenerator, Iterable
+
+from jararaca.scheduler.types import DelayedMessageData
+
+
+class MessageBrokerBackend(ABC):
+
+    def lock(self) -> AsyncContextManager[None]:
+        """
+        Acquire a lock for the message broker backend.
+        This is used to ensure that only one instance of the scheduler is running at a time.
+        """
+        raise NotImplementedError(f"lock() is not implemented by {self.__class__}.")
+
+    async def get_last_dispatch_time(self, action_name: str) -> int | None:
+        """
+        Get the last dispatch time of the scheduled action.
+        This is used to determine if the scheduled action should be executed again
+        or if it should be skipped.
+        """
+        raise NotImplementedError(
+            f"get_last_dispatch_time() is not implemented by {self.__class__}."
+        )
+
+    async def set_last_dispatch_time(self, action_name: str, timestamp: int) -> None:
+        """
+        Set the last dispatch time of the scheduled action.
+        This is used to determine if the scheduled action should be executed again
+        or if it should be skipped.
+        """
+        raise NotImplementedError(
+            f"set_last_dispatch_time() is not implemented by {self.__class__}."
+        )
+
+    async def get_in_execution_count(self, action_name: str) -> int:
+        """
+        Get the number of scheduled actions in execution.
+        This is used to determine if the scheduled action should be executed again
+        or if it should be skipped.
+        """
+        raise NotImplementedError(
+            f"get_in_execution_count() is not implemented by {self.__class__}."
+        )
+
+    def in_execution(self, action_name: str) -> AsyncContextManager[None]:
+        """
+        Acquire a lock for the scheduled action.
+        This is used to ensure that only one instance of the scheduled action is running at a time.
+        """
+        raise NotImplementedError(
+            f"in_execution() is not implemented by {self.__class__}."
+        )
+
+    async def dequeue_next_delayed_messages(
+        self, start_timestamp: int
+    ) -> Iterable[DelayedMessageData]:
+        """
+        Dequeue the next delayed messages from the message broker.
+        This is used to trigger the scheduled action.
+        """
+        raise NotImplementedError(
+            f"dequeue_next_delayed_messages() is not implemented by {self.__class__}."
+        )
+
+    async def enqueue_delayed_message(
+        self, delayed_message: DelayedMessageData
+    ) -> None:
+        """
+        Enqueue a delayed message to the message broker.
+        This is used to trigger the scheduled action.
+        """
+        raise NotImplementedError(
+            f"enqueue_delayed_message() is not implemented by {self.__class__}."
+        )
+
+    async def dispose(self) -> None:
+        """
+        Dispose of the message broker backend.
+        This is used to clean up resources used by the message broker backend.
+        """
+
+
+class NullBackend(MessageBrokerBackend):
+    """
+    A null backend that does nothing.
+    This is used for testing purposes.
+    """
+
+    @asynccontextmanager
+    async def lock(self) -> AsyncGenerator[None, None]:
+        yield
+
+    async def get_last_dispatch_time(self, action_name: str) -> int:
+        return 0
+
+    async def set_last_dispatch_time(self, action_name: str, timestamp: int) -> None:
+        pass
+
+    async def dispose(self) -> None:
+        pass

jararaca/broker_backend/mapper.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from jararaca.broker_backend import MessageBrokerBackend
+
+
+def get_message_broker_backend_from_url(url: str) -> MessageBrokerBackend:
+    """
+    Factory function to create a message broker backend instance from a URL.
+    Currently, only Redis is supported.
+    """
+    if (
+        url.startswith("redis://")
+        or url.startswith("rediss://")
+        or url.startswith("redis-socket://")
+        or url.startswith("rediss+socket://")
+    ):
+        from jararaca.broker_backend.redis_broker_backend import (
+            RedisMessageBrokerBackend,
+        )
+
+        return RedisMessageBrokerBackend(url)
+    else:
+        raise ValueError(f"Unsupported message broker backend URL: {url}")

jararaca/broker_backend/redis_broker_backend.py

@@ -0,0 +1,168 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import logging
+import time
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator, Iterable
+from uuid import uuid4
+
+import redis.asyncio
+
+from jararaca.broker_backend import MessageBrokerBackend
+from jararaca.scheduler.types import DelayedMessageData
+
+logger = logging.getLogger(__name__)
+
+
+class RedisMessageBrokerBackend(MessageBrokerBackend):
+    def __init__(self, url: str) -> None:
+        self.redis = redis.asyncio.Redis.from_url(url)
+        self.last_dispatch_time_key = "last_dispatch_time:{action_name}"
+        self.last_execution_time_key = "last_execution_time:{action_name}"
+        self.execution_indicator_key = "in_execution:{action_name}:{timestamp}"
+        self.execution_indicator_expiration = 60 * 5
+        self.delayed_messages_key = "delayed_messages"
+        self.delayed_messages_metadata_key = "delayed_messages_metadata:{task_id}"
+
+    @asynccontextmanager
+    async def lock(self) -> AsyncGenerator[None, None]:
+        yield
+
+    async def get_last_dispatch_time(self, action_name: str) -> int | None:
+
+        key = self.last_dispatch_time_key.format(action_name=action_name)
+        last_execution_time = await self.redis.get(key)
+        if last_execution_time is None:
+            return None
+        return int(last_execution_time)
+
+    async def set_last_dispatch_time(self, action_name: str, timestamp: int) -> None:
+        key = self.last_dispatch_time_key.format(action_name=action_name)
+        await self.redis.set(key, timestamp)
+
+    async def get_last_execution_time(self, action_name: str) -> int | None:
+        key = self.last_execution_time_key.format(action_name=action_name)
+        last_execution_time = await self.redis.get(key)
+        if last_execution_time is None:
+            return None
+        return int(last_execution_time)
+
+    async def set_last_execution_time(self, action_name: str, timestamp: int) -> None:
+        key = self.last_execution_time_key.format(action_name=action_name)
+        await self.redis.set(key, timestamp)
+
+    async def get_in_execution_count(self, action_name: str) -> int:
+        key = self.execution_indicator_key.format(
+            action_name=action_name, timestamp="*"
+        )
+        in_execution_count = await self.redis.keys(key)
+        if in_execution_count is None:
+            return 0
+
+        return len(in_execution_count)
+
+    @asynccontextmanager
+    async def in_execution(self, action_name: str) -> AsyncGenerator[None, None]:
+        """
+        Acquire a lock for the scheduled action.
+        This is used to ensure that only one instance of the scheduled action is running at a time.
+        """
+        key = self.execution_indicator_key.format(
+            action_name=action_name, timestamp=int(time.time())
+        )
+        await self.redis.set(key, 1, ex=self.execution_indicator_expiration)
+        try:
+            yield
+        finally:
+            await self.redis.delete(key)
+
+    async def enqueue_delayed_message(
+        self, delayed_message: DelayedMessageData
+    ) -> None:
+        """
+        Enqueue a delayed message to the message broker.
+        This is used to trigger the scheduled action.
+        """
+        task_id = str(uuid4())
+        async with self.redis.pipeline() as pipe:
+            pipe.set(
+                self.delayed_messages_metadata_key.format(task_id=task_id),
+                delayed_message.model_dump_json().encode(),
+            )
+            pipe.zadd(
+                self.delayed_messages_key,
+                {task_id: delayed_message.dispatch_time},
+                nx=True,
+            )
+            await pipe.execute()
+
+    async def dequeue_next_delayed_messages(
+        self, start_timestamp: int
+    ) -> Iterable[DelayedMessageData]:
+        """
+        Dequeue the next delayed messages from the message broker.
+        This is used to trigger the scheduled action.
+        """
+        tasks_ids = await self.redis.zrangebyscore(
+            name=self.delayed_messages_key,
+            max=start_timestamp,
+            min="-inf",
+            withscores=False,
+        )
+
+        if not tasks_ids:
+            return []
+
+        tasks_bytes_data: list[bytes] = []
+
+        for task_id_bytes in tasks_ids:
+            metadata = await self.redis.get(
+                self.delayed_messages_metadata_key.format(
+                    task_id=task_id_bytes.decode()
+                )
+            )
+            if metadata is None:
+                logger.warning(
+                    f"Delayed message metadata not found for task_id: {task_id_bytes.decode()}"
+                )
+
+                continue
+
+            tasks_bytes_data.append(metadata)
+
+        async with self.redis.pipeline() as pipe:
+            for task_id_bytes in tasks_ids:
+                pipe.zrem(self.delayed_messages_key, task_id_bytes.decode())
+                pipe.delete(
+                    self.delayed_messages_metadata_key.format(
+                        task_id=task_id_bytes.decode()
+                    )
+                )
+            await pipe.execute()
+
+        delayed_messages: list[DelayedMessageData] = []
+
+        for task_bytes_data in tasks_bytes_data:
+            try:
+                delayed_message = DelayedMessageData.model_validate_json(
+                    task_bytes_data.decode()
+                )
+                delayed_messages.append(delayed_message)
+            except Exception:
+                if logger.isEnabledFor(logging.ERROR):
+                    logger.error(
+                        "Error parsing delayed message: %s",
+                        task_bytes_data.decode(),
+                    )
+                continue
+
+        return delayed_messages
+
+    async def dispose(self) -> None:
+        """
+        Dispose of the message broker backend.
+        This is used to close the connection to the message broker.
+        """
+        await self.redis.close()