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

jararaca/cli.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import asyncio
 import importlib
 import importlib.resources
@@ -5,9 +9,11 @@ import multiprocessing
 import os
 import sys
 import time
+import traceback
+import typing
 from codecs import StreamWriter
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any, Callable
 from urllib.parse import parse_qs, urlparse
 
 import aio_pika
@@ -31,6 +37,9 @@ from jararaca.tools.typescript.interface_parser import (
 )
 from jararaca.utils.rabbitmq_utils import RabbitmqUtils
 
+if TYPE_CHECKING:
+    from watchdog.observers.api import BaseObserver
+
 LIBRARY_FILES_PATH = importlib.resources.files("jararaca.files")
 ENTITY_TEMPLATE_PATH = LIBRARY_FILES_PATH / "entity.py.mako"
 
@@ -256,7 +265,7 @@ async def declare_controller_queues(
     Declare all message handler and scheduled action queues for controllers.
     """
     for instance_type in app.controllers:
-        controller_spec = MessageBusController.get_messagebus(instance_type)
+        controller_spec = MessageBusController.get_last(instance_type)
         if controller_spec is None:
             continue
 
@@ -266,7 +275,7 @@ async def declare_controller_queues(
         for _, member in members.items():
             # Check if it's a message handler
             await declare_message_handler_queue(
-                connection, member, exchange, force, interactive_mode
+                connection, member, exchange, force, interactive_mode, controller_spec
             )
 
             # Check if it's a scheduled action
@@ -281,11 +290,12 @@ async def declare_message_handler_queue(
     exchange: str,
     force: bool,
     interactive_mode: bool,
+    controller_spec: MessageBusController,
 ) -> None:
     """
     Declare a queue for a message handler if the member is one.
     """
-    message_handler = MessageHandler.get_message_incoming(member.member_function)
+    message_handler = MessageHandler.get_last(member.member_function)
     if message_handler is not None:
         queue_name = f"{message_handler.message_type.MESSAGE_TOPIC}.{member.member_function.__module__}.{member.member_function.__qualname__}"
         routing_key = f"{message_handler.message_type.MESSAGE_TOPIC}.#"
@@ -311,7 +321,7 @@ async def declare_scheduled_action_queue(
     """
     Declare a queue for a scheduled action if the member is one.
     """
-    scheduled_action = ScheduledAction.get_scheduled_action(member.member_function)
+    scheduled_action = ScheduledAction.get_last(member.member_function)
     if scheduled_action is not None:
         queue_name = (
             f"{member.member_function.__module__}.{member.member_function.__qualname__}"
@@ -421,25 +431,52 @@ def cli() -> None:
 @click.option(
     "--handlers",
     type=str,
+    envvar="HANDLERS",
     help="Comma-separated list of handler names to listen to. If not specified, all handlers will be used.",
 )
+@click.option(
+    "--reload",
+    is_flag=True,
+    envvar="RELOAD",
+    help="Enable auto-reload when Python files change.",
+)
+@click.option(
+    "--src-dir",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True),
+    default="src",
+    envvar="SRC_DIR",
+    help="The source directory to watch for changes when --reload is enabled.",
+)
+@click.option(
+    "--gracious-shutdown-seconds",
+    type=int,
+    default=20,
+    envvar="GRACIOUS_SHUTDOWN_SECONDS",
+    help="Number of seconds to wait for graceful shutdown on reload",
+)
 def worker(
-    app_path: str, broker_url: str, backend_url: str, handlers: str | None
+    app_path: str,
+    broker_url: str,
+    backend_url: str,
+    handlers: str | None,
+    reload: bool,
+    src_dir: str,
+    gracious_shutdown_seconds: int,
 ) -> None:
     """Start a message bus worker that processes asynchronous messages from a message queue."""
-    app = find_microservice_by_module_path(app_path)
 
-    # Parse handler names if provided
-    handler_names: set[str] | None = None
-    if handlers:
-        handler_names = {name.strip() for name in handlers.split(",") if name.strip()}
-
-    worker_mod.MessageBusWorker(
-        app=app,
-        broker_url=broker_url,
-        backend_url=backend_url,
-        handler_names=handler_names,
-    ).start_sync()
+    if reload:
+        process_args = {
+            "app_path": app_path,
+            "broker_url": broker_url,
+            "backend_url": backend_url,
+            "handlers": handlers,
+        }
+        run_with_reload_watcher(
+            process_args, run_worker_process, src_dir, gracious_shutdown_seconds
+        )
+    else:
+        run_worker_process(app_path, broker_url, backend_url, handlers)
 
 
 @cli.command()
@@ -485,51 +522,78 @@ def server(app_path: str, host: str, port: int) -> None:
 @click.argument(
     "app_path",
     type=str,
+    envvar="APP_PATH",
 )
 @click.option(
     "--interval",
     type=int,
     default=1,
     required=True,
+    envvar="INTERVAL",
 )
 @click.option(
     "--broker-url",
     type=str,
     required=True,
+    envvar="BROKER_URL",
 )
 @click.option(
     "--backend-url",
     type=str,
     required=True,
+    envvar="BACKEND_URL",
 )
 @click.option(
     "--actions",
     type=str,
+    envvar="ACTIONS",
     help="Comma-separated list of action names to run (only run actions with these names)",
 )
+@click.option(
+    "--reload",
+    is_flag=True,
+    envvar="RELOAD",
+    help="Enable auto-reload when Python files change.",
+)
+@click.option(
+    "--src-dir",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True),
+    default="src",
+    envvar="SRC_DIR",
+    help="The source directory to watch for changes when --reload is enabled.",
+)
+@click.option(
+    "--gracious-shutdown-seconds",
+    type=int,
+    default=20,
+    envvar="GRACIOUS_SHUTDOWN_SECONDS",
+    help="Number of seconds to wait for graceful shutdown on reload",
+)
 def beat(
     interval: int,
     broker_url: str,
     backend_url: str,
     app_path: str,
     actions: str | None = None,
+    reload: bool = False,
+    src_dir: str = "src",
+    gracious_shutdown_seconds: int = 20,
 ) -> None:
-
-    app = find_microservice_by_module_path(app_path)
-
-    # Parse scheduler names if provided
-    scheduler_names: set[str] | None = None
-    if actions:
-        scheduler_names = {name.strip() for name in actions.split(",") if name.strip()}
-
-    beat_worker = BeatWorker(
-        app=app,
-        interval=interval,
-        backend_url=backend_url,
-        broker_url=broker_url,
-        scheduled_action_names=scheduler_names,
-    )
-    beat_worker.run()
+    """Start a scheduler that dispatches scheduled actions to workers."""
+
+    if reload:
+        process_args = {
+            "app_path": app_path,
+            "interval": interval,
+            "broker_url": broker_url,
+            "backend_url": backend_url,
+            "actions": actions,
+        }
+        run_with_reload_watcher(
+            process_args, run_beat_process, src_dir, gracious_shutdown_seconds
+        )
+    else:
+        run_beat_process(app_path, interval, broker_url, backend_url, actions)
 
 
 def generate_interfaces(
@@ -581,6 +645,7 @@ def generate_interfaces(
         return content
     except Exception as e:
         click.echo(f"Error generating TypeScript interfaces: {e}", file=sys.stderr)
+        traceback.print_exc(file=sys.stderr)
         return ""
 
 
@@ -588,29 +653,35 @@ def generate_interfaces(
 @click.argument(
     "app_path",
     type=str,
+    envvar="APP_PATH",
 )
 @click.argument(
     "file_path",
     type=click.Path(file_okay=True, dir_okay=False),
     required=False,
+    envvar="FILE_PATH",
 )
 @click.option(
     "--watch",
     is_flag=True,
+    envvar="WATCH",
 )
 @click.option(
     "--src-dir",
     type=click.Path(exists=True, file_okay=False, dir_okay=True),
     default="src",
+    envvar="SRC_DIR",
 )
 @click.option(
     "--stdout",
     is_flag=True,
+    envvar="STDOUT",
     help="Print generated interfaces to stdout instead of writing to a file",
 )
 @click.option(
     "--post-process",
     type=str,
+    envvar="POST_PROCESS",
     help="Command to run after generating the interfaces, {file} will be replaced with the output file path",
 )
 def gen_tsi(
@@ -702,19 +773,23 @@ def gen_tsi(
 
             # subprocess.run(cmd, check=False)
 
-    # Set up observer
-    observer = Observer()
-    observer.schedule(PyFileChangeHandler(), src_dir, recursive=True)  # type: ignore
-    observer.start()  # type: ignore
+    @typing.no_type_check
+    def start_watchdog() -> None:
 
-    click.echo(f"Watching for changes in {os.path.abspath(src_dir)}...")
-    try:
-        while True:
-            time.sleep(1)
-    except KeyboardInterrupt:
-        observer.stop()  # type: ignore
-        click.echo("Watch mode stopped")
-    observer.join()
+        observer: "BaseObserver" = Observer()
+        observer.schedule(PyFileChangeHandler(), src_dir, recursive=True)
+        observer.start()
+
+        click.echo(f"Watching for changes in {os.path.abspath(src_dir)}...")
+        try:
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            observer.stop()
+            click.echo("Watch mode stopped")
+        observer.join()
+
+    start_watchdog()
 
 
 def camel_case_to_snake_case(name: str) -> str:
@@ -730,10 +805,11 @@ def camel_case_to_pascal_case(name: str) -> str:
 
 
 @cli.command()
-@click.argument("entity_name", type=click.STRING)
+@click.argument("entity_name", type=click.STRING, envvar="ENTITY_NAME")
 @click.argument(
     "file_path",
     type=click.File("w"),
+    envvar="FILE_PATH",
 )
 def gen_entity(entity_name: str, file_path: StreamWriter) -> None:
 
@@ -769,6 +845,7 @@ def gen_entity(entity_name: str, file_path: StreamWriter) -> None:
     "--interactive-mode",
     is_flag=True,
     default=False,
+    envvar="INTERACTIVE_MODE",
     help="Enable interactive mode for queue declaration (confirm before deleting existing queues)",
 )
 @click.option(
@@ -776,6 +853,7 @@ def gen_entity(entity_name: str, file_path: StreamWriter) -> None:
     "--force",
     is_flag=True,
     default=False,
+    envvar="FORCE",
     help="Force recreation by deleting existing exchanges and queues before declaring them",
 )
 def declare(
@@ -835,3 +913,150 @@ def declare(
             raise
 
     asyncio.run(run_declarations())
+
+
+def run_worker_process(
+    app_path: str, broker_url: str, backend_url: str, handlers: str | None
+) -> None:
+    """Run a worker process with the given parameters."""
+    app = find_microservice_by_module_path(app_path)
+
+    # Parse handler names if provided
+    handler_names: set[str] | None = None
+    if handlers:
+        handler_names = {name.strip() for name in handlers.split(",") if name.strip()}
+
+    click.echo(f"Starting worker for {app_path}...")
+    worker_mod.MessageBusWorker(
+        app=app,
+        broker_url=broker_url,
+        backend_url=backend_url,
+        handler_names=handler_names,
+    ).start_sync()
+
+
+def run_beat_process(
+    app_path: str, interval: int, broker_url: str, backend_url: str, actions: str | None
+) -> None:
+    """Run a beat scheduler process with the given parameters."""
+    app = find_microservice_by_module_path(app_path)
+
+    # Parse scheduler names if provided
+    scheduler_names: set[str] | None = None
+    if actions:
+        scheduler_names = {name.strip() for name in actions.split(",") if name.strip()}
+
+    click.echo(f"Starting beat scheduler for {app_path}...")
+    beat_worker = BeatWorker(
+        app=app,
+        interval=interval,
+        backend_url=backend_url,
+        broker_url=broker_url,
+        scheduled_action_names=scheduler_names,
+    )
+    beat_worker.run()
+
+
+def run_with_reload_watcher(
+    process_args: dict[str, Any],
+    process_target: Callable[..., Any],
+    src_dir: str = "src",
+    max_graceful_shutdown_seconds: int = 20,
+) -> None:
+    """
+    Run a process with a file watcher that will restart it when Python files change.
+
+    Args:
+        process_args: Arguments to pass to the process function
+        process_target: The function to run as the process
+        src_dir: The directory to watch for changes
+    """
+    try:
+        from watchdog.events import FileSystemEvent, FileSystemEventHandler
+        from watchdog.observers import Observer
+    except ImportError:
+        click.echo(
+            "Watchdog is required for reload mode. Install it with: pip install watchdog",
+            file=sys.stderr,
+        )
+        return
+
+    # Run the initial process
+    process = multiprocessing.get_context("spawn").Process(
+        target=process_target,
+        kwargs=process_args,
+        daemon=False,  # Non-daemon to ensure it completes properly
+    )
+    process.start()  # Set up file system event handler
+
+    class PyFileChangeHandler(FileSystemEventHandler):
+        def __init__(self) -> None:
+            self.last_modified_time = time.time()
+            self.debounce_seconds = 1.0  # Debounce to avoid multiple restarts
+            self.active_process = process
+
+        def on_modified(self, event: FileSystemEvent) -> None:
+            src_path = (
+                event.src_path
+                if isinstance(event.src_path, str)
+                else str(event.src_path)
+            )
+
+            # Ignore non-Python files and directories
+            if event.is_directory or not src_path.endswith(".py"):
+                return
+
+            # Debounce to avoid multiple restarts
+            current_time = time.time()
+            if current_time - self.last_modified_time < self.debounce_seconds:
+                return
+            self.last_modified_time = current_time
+
+            click.echo(f"Detected change in {src_path}")
+            click.echo("Restarting process...")
+
+            # Terminate the current process
+            if self.active_process and self.active_process.is_alive():
+                self.active_process.terminate()
+                self.active_process.join(timeout=max_graceful_shutdown_seconds)
+
+                # If process doesn't terminate, kill it
+                if self.active_process.is_alive():
+                    click.echo("Process did not terminate gracefully, killing it")
+                    self.active_process.kill()
+                    self.active_process.join()
+
+            # Create a new process
+
+            self.active_process = multiprocessing.get_context("spawn").Process(
+                target=process_target,
+                kwargs=process_args,
+                daemon=False,
+            )
+            self.active_process.start()
+
+    @typing.no_type_check
+    def start_watchdog() -> None:
+
+        # Set up observer
+        observer = Observer()
+        observer.schedule(PyFileChangeHandler(), src_dir, recursive=True)
+        observer.start()
+
+        click.echo(f"Watching for changes in {os.path.abspath(src_dir)}...")
+        try:
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            observer.stop()
+            if process.is_alive():
+                click.echo("Stopping process...")
+                process.terminate()
+                process.join(timeout=max_graceful_shutdown_seconds)
+                if process.is_alive():
+                    process.kill()
+                    process.join()
+            click.echo("Reload mode stopped")
+        observer.join()
+
+    start_watchdog()

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,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/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