jararaca 0.3.11a16__py3-none-any.whl → 0.3.12__py3-none-any.whl

README.md

@@ -0,0 +1,120 @@
+<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.

jararaca/__init__.py

@@ -45,26 +45,47 @@ if TYPE_CHECKING:
     )
     from jararaca.rpc.http.backends.httpx import HTTPXHttpRPCAsyncBackend
     from jararaca.rpc.http.backends.otel import TracedRequestMiddleware
-    from jararaca.rpc.http.decorators import Body
+    from jararaca.rpc.http.decorators import (  # New request parameter decorators; Configuration decorators; Authentication classes; Middleware classes; Configuration classes; Exception classes
+        ApiKeyAuth,
+        AuthenticationMiddleware,
+        BasicAuth,
+        BearerTokenAuth,
+        Body,
+        CacheMiddleware,
+        ContentType,
+    )
     from jararaca.rpc.http.decorators import Delete as HttpDelete
+    from jararaca.rpc.http.decorators import (  # New request parameter decorators; Configuration decorators; Authentication classes; Middleware classes; Configuration classes; Exception classes
+        File,
+        FormData,
+    )
     from jararaca.rpc.http.decorators import Get as HttpGet
-    from jararaca.rpc.http.decorators import (
+    from jararaca.rpc.http.decorators import (  # New request parameter decorators; Configuration decorators; Authentication classes; Middleware classes; Configuration classes; Exception classes
         GlobalHttpErrorHandler,
         Header,
         HttpMapping,
         HttpRpcClientBuilder,
     )
     from jararaca.rpc.http.decorators import Patch as HttpPatch
-    from jararaca.rpc.http.decorators import PathParam
+    from jararaca.rpc.http.decorators import (  # New request parameter decorators; Configuration decorators; Authentication classes; Middleware classes; Configuration classes; Exception classes
+        PathParam,
+    )
     from jararaca.rpc.http.decorators import Post as HttpPost
     from jararaca.rpc.http.decorators import Put as HttpPut
-    from jararaca.rpc.http.decorators import (
+    from jararaca.rpc.http.decorators import (  # New request parameter decorators; Configuration decorators; Authentication classes; Middleware classes; Configuration classes; Exception classes
         Query,
         RequestAttribute,
+        RequestHook,
+        ResponseHook,
+        ResponseMiddleware,
         RestClient,
+        Retry,
+        RetryConfig,
         RouteHttpErrorHandler,
         RPCRequestNetworkError,
         RPCUnhandleError,
+        Timeout,
+        TimeoutException,
     )
 
     from .core.providers import ProviderSpec, Token
@@ -81,6 +102,8 @@ if TYPE_CHECKING:
     from .messagebus.publisher import use_publisher
     from .microservice import (
         Microservice,
+        is_shutting_down,
+        request_shutdown,
         use_app_context,
         use_app_transaction_context,
         use_app_tx_ctx_data,
@@ -96,6 +119,11 @@ if TYPE_CHECKING:
         use_session,
         use_transaction,
     )
+    from .persistence.interceptors.decorators import (
+        set_use_persistence_session,
+        skip_persistence_session,
+        uses_persistence_session,
+    )
     from .persistence.utilities import (
         CriteriaBasedAttributeQueryInjector,
         CRUDOperations,
@@ -137,6 +165,11 @@ if TYPE_CHECKING:
     from .presentation.websocket.websocket_interceptor import WebSocketInterceptor
     from .scheduler.decorators import ScheduledAction
     from .tools.app_config.interceptor import AppConfigurationInterceptor
+    from .tools.typescript.decorators import (
+        MutationEndpoint,
+        QueryEndpoint,
+        SplitInputOutput,
+    )
 
     __all__ = [
         "SetMetadata",
@@ -186,6 +219,12 @@ if TYPE_CHECKING:
         "QueryInjector",
         "HttpMicroservice",
         "use_current_container",
+        "use_app_context",
+        "use_app_transaction_context",
+        "use_app_tx_ctx_data",
+        "is_shutting_down",
+        "request_shutdown",
+        "Microservice",
         "T_BASEMODEL",
         "DatedEntity",
         "BaseEntity",
@@ -208,7 +247,6 @@ if TYPE_CHECKING:
         "MessageBusController",
         "MessageHandler",
         "ScheduledAction",
-        "Microservice",
         "ProviderSpec",
         "Token",
         "AIOSqlAlchemySessionInterceptor",
@@ -220,6 +258,9 @@ if TYPE_CHECKING:
         "use_transaction",
         "providing_session",
         "provide_session",
+        "uses_persistence_session",
+        "skip_persistence_session",
+        "set_use_persistence_session",
         "providing_transaction",
         "providing_new_session",
         "Post",
@@ -233,6 +274,9 @@ if TYPE_CHECKING:
         "MessageBusPublisherInterceptor",
         "RedisWebSocketConnectionBackend",
         "AppConfigurationInterceptor",
+        "QueryEndpoint",
+        "MutationEndpoint",
+        "SplitInputOutput",
         "UseMiddleware",
         "UseDependency",
         "GlobalHttpErrorHandler",
@@ -242,9 +286,27 @@ if TYPE_CHECKING:
         "provide_ws_manager",
         "HttpRpcClientBuilder",
         "HTTPXHttpRPCAsyncBackend",
-        "use_app_context",
-        "use_app_transaction_context",
-        "use_app_tx_ctx_data",
+        # New request parameter decorators
+        "FormData",
+        "File",
+        # Configuration decorators
+        "Timeout",
+        "Retry",
+        "ContentType",
+        # Authentication classes
+        "BearerTokenAuth",
+        "BasicAuth",
+        "ApiKeyAuth",
+        # Middleware classes
+        "CacheMiddleware",
+        "AuthenticationMiddleware",
+        "ResponseMiddleware",
+        "RequestHook",
+        "ResponseHook",
+        # Configuration classes
+        "RetryConfig",
+        # Exception classes
+        "TimeoutException",
         "AppTransactionContext",
         "AppContext",
         "ControllerMemberReflect",
@@ -401,6 +463,21 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
         "persistence.interceptors.aiosqa_interceptor",
         None,
     ),
+    "uses_persistence_session": (
+        __SPEC_PARENT__,
+        "persistence.interceptors.decorators",
+        None,
+    ),
+    "skip_persistence_session": (
+        __SPEC_PARENT__,
+        "persistence.interceptors.decorators",
+        None,
+    ),
+    "set_use_persistence_session": (
+        __SPEC_PARENT__,
+        "persistence.interceptors.decorators",
+        None,
+    ),
     "Post": (__SPEC_PARENT__, "presentation.decorators", None),
     "Get": (__SPEC_PARENT__, "presentation.decorators", None),
     "Patch": (__SPEC_PARENT__, "presentation.decorators", None),
@@ -427,6 +504,9 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
         "tools.app_config.interceptor",
         None,
     ),
+    "QueryEndpoint": (__SPEC_PARENT__, "tools.typescript.decorators", None),
+    "MutationEndpoint": (__SPEC_PARENT__, "tools.typescript.decorators", None),
+    "SplitInputOutput": (__SPEC_PARENT__, "tools.typescript.decorators", None),
     "UseMiddleware": (__SPEC_PARENT__, "presentation.decorators", None),
     "UseDependency": (__SPEC_PARENT__, "presentation.decorators", None),
     "GlobalHttpErrorHandler": (__SPEC_PARENT__, "rpc.http.decorators", None),
@@ -440,9 +520,27 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
     "provide_ws_manager": (__SPEC_PARENT__, "presentation.websocket.context", None),
     "HttpRpcClientBuilder": (__SPEC_PARENT__, "rpc.http.decorators", None),
     "HTTPXHttpRPCAsyncBackend": (__SPEC_PARENT__, "rpc.http.backends.httpx", None),
+    # New HTTP RPC classes
+    "FormData": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "File": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "Timeout": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "Retry": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "ContentType": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "BearerTokenAuth": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "BasicAuth": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "ApiKeyAuth": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "CacheMiddleware": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "AuthenticationMiddleware": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "ResponseMiddleware": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "RequestHook": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "ResponseHook": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "RetryConfig": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "TimeoutException": (__SPEC_PARENT__, "rpc.http.decorators", None),
     "use_app_context": (__SPEC_PARENT__, "microservice", None),
     "use_app_transaction_context": (__SPEC_PARENT__, "microservice", None),
     "use_app_tx_ctx_data": (__SPEC_PARENT__, "microservice", None),
+    "is_shutting_down": (__SPEC_PARENT__, "microservice", None),
+    "request_shutdown": (__SPEC_PARENT__, "microservice", None),
     "AppContext": (__SPEC_PARENT__, "microservice", None),
     "AppInterceptor": (__SPEC_PARENT__, "microservice", None),
     "AppTransactionContext": (__SPEC_PARENT__, "microservice", None),

jararaca/cli.py

@@ -5,9 +5,10 @@ import multiprocessing
 import os
 import sys
 import time
+import traceback
 from codecs import StreamWriter
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
 from urllib.parse import parse_qs, urlparse
 
 import aio_pika
@@ -421,25 +422,42 @@ 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.",
+)
 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,
 ) -> 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)
+    else:
+        run_worker_process(app_path, broker_url, backend_url, handlers)
 
 
 @cli.command()
@@ -485,51 +503,68 @@ 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.",
+)
 def beat(
     interval: int,
     broker_url: str,
     backend_url: str,
     app_path: str,
     actions: str | None = None,
+    reload: bool = False,
+    src_dir: str = "src",
 ) -> 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)
+    else:
+        run_beat_process(app_path, interval, broker_url, backend_url, actions)
 
 
 def generate_interfaces(
@@ -581,6 +616,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 +624,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(
@@ -730,10 +772,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 +812,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 +820,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 +880,143 @@ 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",
+) -> 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=5)
+
+                # 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()
+
+    # Set up observer
+    observer = Observer()
+    observer.schedule(PyFileChangeHandler(), src_dir, recursive=True)  # type: ignore[no-untyped-call]
+    observer.start()  # type: ignore[no-untyped-call]
+
+    click.echo(f"Watching for changes in {os.path.abspath(src_dir)}...")
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        observer.stop()  # type: ignore[no-untyped-call]
+        if process.is_alive():
+            click.echo("Stopping process...")
+            process.terminate()
+            process.join(timeout=5)
+            if process.is_alive():
+                process.kill()
+                process.join()
+        click.echo("Reload mode stopped")
+    observer.join()