jararaca 0.2.37a11__py3-none-any.whl → 0.3.0__py3-none-any.whl

jararaca/scheduler/scheduler.py

@@ -1,5 +1,7 @@
 import asyncio
+import inspect
 import logging
+import time
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from datetime import UTC, datetime
@@ -11,6 +13,7 @@ from croniter import croniter
 from jararaca.core.uow import UnitOfWorkContextProvider
 from jararaca.di import Container
 from jararaca.lifecycle import AppLifecycle
+from jararaca.messagebus.decorators import ScheduleDispatchData
 from jararaca.microservice import Microservice, SchedulerAppContext
 from jararaca.scheduler.decorators import ScheduledAction
 
@@ -22,9 +25,6 @@ class SchedulerConfig:
     interval: int
 
 
-class SchedulerBackend: ...
-
-
 def extract_scheduled_actions(
     app: Microservice, container: Container
 ) -> list[tuple[Callable[..., Any], "ScheduledAction"]]:
@@ -52,12 +52,11 @@ class Scheduler:
     def __init__(
         self,
         app: Microservice,
-        backend: SchedulerBackend,
-        config: SchedulerConfig,
+        interval: int,
     ) -> None:
         self.app = app
-        self.backend = backend
-        self.config = config
+
+        self.interval = interval
         self.container = Container(self.app)
         self.uow_provider = UnitOfWorkContextProvider(app, self.container)
 
@@ -115,7 +114,15 @@ class Scheduler:
             ):
                 try:
                     async with ctx:
-                        await func()
+                        signature = inspect.signature(func)
+                        if len(signature.parameters) > 0:
+                            logging.warning(
+                                f"Scheduled action {func.__module__}.{func.__qualname__} has parameters, but no arguments were provided. Must be using scheduler-v2"
+                            )
+                            await func(ScheduleDispatchData(time.time()))
+                        else:
+                            await func()
+
                 except BaseException as e:
                     if action_specs.exception_handler:
                         action_specs.exception_handler(e)
@@ -143,7 +150,7 @@ class Scheduler:
 
                         await self.process_task(func, scheduled_action)
 
-                    await asyncio.sleep(self.config.interval)
+                    await asyncio.sleep(self.interval)
 
         with asyncio.Runner(loop_factory=uvloop.new_event_loop) as runner:
             runner.run(run_scheduled_actions())

jararaca/scheduler/scheduler_v2.py

@@ -0,0 +1,346 @@
+import asyncio
+import contextlib
+import logging
+import signal
+import time
+from abc import ABC, abstractmethod
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from types import FrameType
+from typing import Any, AsyncGenerator, Callable
+from urllib.parse import parse_qs
+
+import aio_pika
+import croniter
+import urllib3
+import urllib3.util
+import uvloop
+from aio_pika import connect_robust
+from aio_pika.abc import AbstractChannel, AbstractRobustConnection
+from aio_pika.pool import Pool
+
+from jararaca.broker_backend import MessageBrokerBackend
+from jararaca.broker_backend.mapper import get_message_broker_backend_from_url
+from jararaca.core.uow import UnitOfWorkContextProvider
+from jararaca.di import Container
+from jararaca.lifecycle import AppLifecycle
+from jararaca.microservice import Microservice
+from jararaca.scheduler.decorators import ScheduledAction
+from jararaca.scheduler.types import DelayedMessageData
+
+logger = logging.getLogger(__name__)
+
+SCHEDULED_ACTION_LIST = list[tuple[Callable[..., Any], "ScheduledAction"]]
+
+
+def extract_scheduled_actions(
+    app: Microservice, container: Container
+) -> SCHEDULED_ACTION_LIST:
+    scheduled_actions: SCHEDULED_ACTION_LIST = []
+    for controllers in app.controllers:
+
+        controller_instance: Any = container.get_by_type(controllers)
+
+        controller_scheduled_actions = ScheduledAction.get_type_scheduled_actions(
+            controller_instance
+        )
+        scheduled_actions.extend(controller_scheduled_actions)
+
+    return scheduled_actions
+
+
+# region Message Broker Dispatcher
+
+
+class MessageBrokerDispatcher(ABC):
+
+    @abstractmethod
+    async def dispatch_scheduled_action(
+        self,
+        action_id: str,
+        timestamp: int,
+    ) -> None:
+        """
+        Dispatch a message to the message broker.
+        This is used to send a message to the message broker
+        to trigger the scheduled action.
+        """
+        raise NotImplementedError("dispatch() is not implemented yet.")
+
+    @abstractmethod
+    async def dispatch_delayed_message(
+        self,
+        delayed_message: DelayedMessageData,
+    ) -> None:
+        """
+        Dispatch a delayed message to the message broker.
+        This is used to send a message to the message broker
+        to trigger the scheduled action.
+        """
+
+        raise NotImplementedError("dispatch_delayed_message() is not implemented yet.")
+
+    @abstractmethod
+    async def initialize(self, scheduled_actions: SCHEDULED_ACTION_LIST) -> None:
+        raise NotImplementedError("initialize() is not implemented yet.")
+
+    async def dispose(self) -> None:
+        pass
+
+
+class RabbitMQBrokerDispatcher(MessageBrokerDispatcher):
+
+    def __init__(self, url: str) -> None:
+        self.url = url
+
+        self.conn_pool: "Pool[AbstractRobustConnection]" = Pool(
+            self._create_connection,
+            max_size=10,
+        )
+
+        self.channel_pool: "Pool[AbstractChannel]" = Pool(
+            self._create_channel,
+            max_size=10,
+        )
+
+        splitted = urllib3.util.parse_url(url)
+
+        assert splitted.scheme in ["amqp", "amqps"], "Invalid URL scheme"
+
+        assert splitted.host, "Invalid URL host"
+
+        assert splitted.query, "Invalid URL query"
+
+        query_params: dict[str, list[str]] = parse_qs(splitted.query)
+
+        assert "exchange" in query_params, "Missing exchange parameter"
+
+        assert query_params["exchange"], "Empty exchange parameter"
+
+        self.exchange = str(query_params["exchange"][0])
+
+    async def _create_connection(self) -> AbstractRobustConnection:
+        """
+        Create a connection to the RabbitMQ server.
+        This is used to send messages to the RabbitMQ server.
+        """
+        connection = await connect_robust(self.url)
+        return connection
+
+    async def _create_channel(self) -> AbstractChannel:
+        """
+        Create a channel to the RabbitMQ server.
+        This is used to send messages to the RabbitMQ server.
+        """
+        async with self.conn_pool.acquire() as connection:
+            channel = await connection.channel()
+            return channel
+
+    async def dispatch_scheduled_action(self, action_id: str, timestamp: int) -> None:
+        """
+        Dispatch a message to the RabbitMQ server.
+        This is used to send a message to the RabbitMQ server
+        to trigger the scheduled action.
+        """
+
+        logger.info(f"Dispatching message to {action_id} at {timestamp}")
+        async with self.channel_pool.acquire() as channel:
+            exchange = await channel.get_exchange(self.exchange)
+
+            await exchange.publish(
+                aio_pika.Message(body=str(timestamp).encode()),
+                routing_key=action_id,
+            )
+            logger.info(f"Dispatched message to {action_id} at {timestamp}")
+
+    async def dispatch_delayed_message(
+        self, delayed_message: DelayedMessageData
+    ) -> None:
+        """
+        Dispatch a delayed message to the RabbitMQ server.
+        This is used to send a message to the RabbitMQ server
+        to trigger the scheduled action.
+        """
+        async with self.channel_pool.acquire() as channel:
+
+            exchange = await channel.get_exchange(self.exchange)
+            await exchange.publish(
+                aio_pika.Message(
+                    body=delayed_message.payload,
+                ),
+                routing_key=f"{delayed_message.message_topic}.",
+            )
+
+    async def initialize(self, scheduled_actions: SCHEDULED_ACTION_LIST) -> None:
+        """
+        Initialize the RabbitMQ server.
+        This is used to create the exchange and queues for the scheduled actions.
+        """
+
+        async with self.channel_pool.acquire() as channel:
+
+            await channel.set_qos(prefetch_count=1)
+
+            await channel.declare_exchange(
+                name=self.exchange,
+                type="topic",
+                durable=True,
+                auto_delete=False,
+            )
+
+            for func, _ in scheduled_actions:
+                queue = await channel.declare_queue(
+                    name=ScheduledAction.get_function_id(func),
+                    durable=True,
+                )
+
+                await queue.bind(
+                    exchange=self.exchange,
+                    routing_key=ScheduledAction.get_function_id(func),
+                )
+
+    async def dispose(self) -> None:
+        await self.channel_pool.close()
+        await self.conn_pool.close()
+
+
+def get_message_broker_dispatcher_from_url(url: str) -> MessageBrokerDispatcher:
+    """
+    Factory function to create a message broker instance from a URL.
+    Currently, only RabbitMQ is supported.
+    """
+    if url.startswith("amqp://") or url.startswith("amqps://"):
+        return RabbitMQBrokerDispatcher(url=url)
+    else:
+        raise ValueError(f"Unsupported message broker URL: {url}")
+
+
+# endregion
+
+
+class SchedulerV2:
+
+    def __init__(
+        self,
+        app: Microservice,
+        interval: int,
+        broker_url: str,
+        backend_url: str,
+    ) -> None:
+        self.app = app
+
+        self.broker: MessageBrokerDispatcher = get_message_broker_dispatcher_from_url(
+            broker_url
+        )
+        self.backend: MessageBrokerBackend = get_message_broker_backend_from_url(
+            backend_url
+        )
+
+        self.interval = interval
+        self.container = Container(self.app)
+        self.uow_provider = UnitOfWorkContextProvider(app, self.container)
+
+        self.shutdown_event = asyncio.Event()
+
+        self.lifecycle = AppLifecycle(app, self.container)
+
+    def run(self) -> None:
+
+        def on_signal_received(signal: int, frame_type: FrameType | None) -> None:
+            logger.info("Received shutdown signal")
+            self.shutdown_event.set()
+
+        signal.signal(signal.SIGINT, on_signal_received)
+
+        with asyncio.Runner(loop_factory=uvloop.new_event_loop) as runner:
+            runner.run(self.start_scheduler())
+
+    async def start_scheduler(self) -> None:
+        """
+        Declares the scheduled actions and starts the scheduler.
+        This is the main entry point for the scheduler.
+        """
+        async with self.lifecycle():
+
+            scheduled_actions = extract_scheduled_actions(self.app, self.container)
+
+            await self.broker.initialize(scheduled_actions)
+
+            await self.run_scheduled_actions(scheduled_actions)
+
+    async def run_scheduled_actions(
+        self, scheduled_actions: SCHEDULED_ACTION_LIST
+    ) -> None:
+
+        while not self.shutdown_event.is_set():
+            now = int(time.time())
+            for func, scheduled_action in scheduled_actions:
+                if self.shutdown_event.is_set():
+                    break
+
+                async with self.backend.lock():
+
+                    last_dispatch_time: int | None = (
+                        await self.backend.get_last_dispatch_time(
+                            ScheduledAction.get_function_id(func)
+                        )
+                    )
+
+                    if last_dispatch_time is not None:
+                        cron = croniter.croniter(
+                            scheduled_action.cron, last_dispatch_time
+                        )
+                        next_run: datetime = cron.get_next(datetime).replace(tzinfo=UTC)
+                        if next_run > datetime.now(UTC):
+                            logger.info(
+                                f"Skipping {func.__module__}.{func.__qualname__} until {next_run}"
+                            )
+                            continue
+
+                    if not scheduled_action.allow_overlap:
+                        if (
+                            await self.backend.get_in_execution_count(
+                                ScheduledAction.get_function_id(func)
+                            )
+                            > 0
+                        ):
+                            continue
+
+                    await self.broker.dispatch_scheduled_action(
+                        ScheduledAction.get_function_id(func),
+                        now,
+                    )
+
+                    await self.backend.set_last_dispatch_time(
+                        ScheduledAction.get_function_id(func), now
+                    )
+
+                    logger.info(
+                        f"Scheduled {func.__module__}.{func.__qualname__} at {now}"
+                    )
+
+            for (
+                delayed_message_data
+            ) in await self.backend.dequeue_next_delayed_messages(now):
+                await self.broker.dispatch_delayed_message(delayed_message_data)
+
+            with contextlib.suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(self.shutdown_event.wait(), self.interval)
+
+            # await self.shutdown_event.wait(self.interval)
+
+        logger.info("Scheduler stopped")
+
+        await self.backend.dispose()
+        await self.broker.dispose()
+
+
+@asynccontextmanager
+async def none_context() -> AsyncGenerator[None, None]:
+    yield
+
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)

jararaca/scheduler/types.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+
+
+class DelayedMessageData(BaseModel):
+    message_topic: str
+    dispatch_time: int
+    payload: bytes

jararaca/utils/rabbitmq_utils.py

@@ -0,0 +1,84 @@
+from aio_pika.abc import AbstractChannel, AbstractExchange, AbstractQueue
+
+
+class RabbitmqUtils:
+
+    DEAD_LETTER_EXCHANGE = "dlx"
+    DEAD_LETTER_QUEUE = "dlq"
+
+    @classmethod
+    async def declare_dl_exchange(cls, channel: AbstractChannel) -> AbstractExchange:
+        """
+        Declare a Dead Letter Exchange (DLX) for the given channel.
+        """
+        await channel.set_qos(prefetch_count=1)
+        return await channel.declare_exchange(
+            cls.DEAD_LETTER_EXCHANGE,
+            type="direct",
+            durable=True,
+            auto_delete=False,
+        )
+
+    @classmethod
+    async def declare_dl_queue(cls, channel: AbstractChannel) -> AbstractQueue:
+        """
+        Declare a Dead Letter Queue (DLQ) for the given queue.
+        """
+        await channel.set_qos(prefetch_count=1)
+        return await channel.declare_queue(
+            cls.DEAD_LETTER_QUEUE,
+            durable=True,
+            arguments={
+                "x-dead-letter-exchange": "",
+                "x-dead-letter-routing-key": cls.DEAD_LETTER_EXCHANGE,
+            },
+        )
+
+    @classmethod
+    async def delcare_dl_kit(
+        cls,
+        channel: AbstractChannel,
+    ) -> tuple[AbstractExchange, AbstractQueue]:
+        """
+        Declare a Dead Letter Exchange and Queue (DLX and DLQ) for the given channel.
+        """
+        dlx = await cls.declare_dl_exchange(channel)
+        dlq = await cls.declare_dl_queue(channel)
+        await dlq.bind(dlx, routing_key=cls.DEAD_LETTER_EXCHANGE)
+        return dlx, dlq
+
+    @classmethod
+    async def declare_main_exchange(
+        cls,
+        channel: AbstractChannel,
+        exchange_name: str,
+    ) -> AbstractExchange:
+        """
+        Declare a main exchange for the given channel.
+        """
+        await channel.set_qos(prefetch_count=1)
+        return await channel.declare_exchange(
+            exchange_name,
+            type="topic",
+            durable=True,
+            auto_delete=False,
+        )
+
+    @classmethod
+    async def declare_queue(
+        cls,
+        channel: AbstractChannel,
+        queue_name: str,
+    ) -> AbstractQueue:
+        """
+        Declare a queue with the given name and properties.
+        """
+        await channel.set_qos(prefetch_count=1)
+        return await channel.declare_queue(
+            queue_name,
+            durable=True,
+            arguments={
+                "x-dead-letter-exchange": cls.DEAD_LETTER_EXCHANGE,
+                "x-dead-letter-routing-key": cls.DEAD_LETTER_EXCHANGE,
+            },
+        )

jararaca-0.3.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.3
+Name: jararaca
+Version: 0.3.0
+Summary: A simple and fast API framework for Python
+Author: Lucas S
+Author-email: me@luscasleo.dev
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: docs
+Provides-Extra: http
+Provides-Extra: opentelemetry
+Provides-Extra: watch
+Requires-Dist: aio-pika (>=9.4.3,<10.0.0)
+Requires-Dist: croniter (>=3.0.3,<4.0.0)
+Requires-Dist: fastapi (>=0.113.0,<0.114.0)
+Requires-Dist: mako (>=1.3.5,<2.0.0)
+Requires-Dist: opentelemetry-api (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-distro (>=0.49b2,<0.50) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-exporter-otlp (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-sdk (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
+Requires-Dist: redis (>=5.0.8,<6.0.0)
+Requires-Dist: sqlalchemy (>=2.0.34,<3.0.0)
+Requires-Dist: types-croniter (>=3.0.3.20240731,<4.0.0.0)
+Requires-Dist: types-redis (>=4.6.0.20240903,<5.0.0.0)
+Requires-Dist: uvicorn (>=0.30.6,<0.31.0)
+Requires-Dist: uvloop (>=0.20.0,<0.21.0)
+Requires-Dist: watchdog (>=3.0.0,<4.0.0) ; extra == "watch"
+Requires-Dist: websockets (>=13.0.1,<14.0.0)
+Project-URL: Repository, https://github.com/LuscasLeo/jararaca
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/LuscasLeo/jararaca/main/docs/assets/_f04774c9-7e05-4da4-8b17-8be23f6a1475.jpeg" alt="Jararaca Logo" width="250" float="right">
+
+# Jararaca Microservice Framework
+
+## Overview
+
+Jararaca is an async-first microservice framework designed to simplify the development of distributed systems. It provides a comprehensive set of tools for building robust, scalable, and maintainable microservices with a focus on developer experience and type safety.
+
+## Key Features
+
+### REST API Development
+- Easy-to-use interfaces for building REST APIs
+- Automatic request/response validation
+- Type-safe endpoints with FastAPI integration
+- Automatic OpenAPI documentation generation
+
+### Message Bus Integration
+- Topic-based message bus for event-driven architecture
+- Support for both worker and publisher patterns
+- Built-in message serialization and deserialization
+- Easy integration with AIO Pika for RabbitMQ
+
+### Distributed WebSocket
+- Room-based WebSocket communication
+- Distributed broadcasting across multiple backend instances
+- Automatic message synchronization between instances
+- Built-in connection management and room handling
+
+### Task Scheduling
+- Cron-based task scheduling
+- Support for overlapping and non-overlapping tasks
+- Distributed task execution
+- Easy integration with message bus for task distribution
+
+### TypeScript Integration
+- Automatic TypeScript interface generation
+- Command-line tool for generating TypeScript types
+- Support for REST endpoints, WebSocket events, and message bus payloads
+- Type-safe frontend-backend communication
+
+### Hexagonal Architecture
+- Clear separation of concerns
+- Business logic isolation from infrastructure
+- Easy testing and maintainability
+- Dependency injection for flexible component management
+
+### Observability
+- Built-in OpenTelemetry integration
+- Distributed tracing support
+- Logging and metrics collection
+- Performance monitoring capabilities
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install jararaca
+```
+
+### Basic Usage
+
+```python
+from jararaca import Microservice, create_http_server
+from jararaca.presentation.http_microservice import HttpMicroservice
+
+# Define your microservice
+app = Microservice(
+    providers=[
+        # Add your providers here
+    ],
+    controllers=[
+        # Add your controllers here
+    ],
+    interceptors=[
+        # Add your interceptors here
+    ],
+)
+
+# Create HTTP server
+http_app = HttpMicroservice(app)
+web_app = create_http_server(app)
+```
+
+### Running the Service
+
+```bash
+# Run as HTTP server
+jararaca server app:http_app
+
+# Run as message bus worker
+jararaca worker app:app
+
+# Run as scheduler
+jararaca scheduler app:app
+
+# Generate TypeScript interfaces
+jararaca gen-tsi app.main:app app.ts
+```
+
+## Documentation
+
+For detailed documentation, please visit our [documentation site](https://luscasleo.github.io/jararaca/).
+
+## Examples
+
+Check out the [examples directory](examples/) for complete working examples of:
+- REST API implementation
+- WebSocket usage
+- Message bus integration
+- Task scheduling
+- TypeScript interface generation
+
+## Contributing
+
+Contributions are welcome! Please read our [contributing guidelines](.github/CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+