jararaca 0.3.11a15__tar.gz → 0.3.12a0__tar.gz

{jararaca-0.3.11a15 → jararaca-0.3.12a0}/PKG-INFO

@@ -1,14 +1,14 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: jararaca
-Version: 0.3.11a15
+Version: 0.3.12a0
 Summary: A simple and fast API framework for Python
+Home-page: https://github.com/LuscasLeo/jararaca
 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

{jararaca-0.3.11a15 → jararaca-0.3.12a0}/docs/index.md

@@ -9,9 +9,9 @@ Jararaca is a powerful Python microservice framework that provides a comprehensi
 - 📦 **Dependency Injection**: Flexible dependency injection system with interceptors
 - 📊 **Database Integration**: SQLAlchemy integration with async support
 - 📡 **Message Bus**: RabbitMQ integration for event-driven architecture
-- 🔒 **Authentication**: Built-in JWT authentication with token blacklisting
+- ⚡ **Retry Mechanism**: Robust retry system with exponential backoff for resilient operations
 - 🔍 **Query Operations**: Advanced query capabilities with pagination and filtering
-- ⏱️ **Scheduled Tasks**: Cron-based task scheduling
+- ⏱️ **Scheduled Tasks**: Distributed cron-based task scheduling with message broker integration
 
 ## Installation
 
@@ -33,9 +33,27 @@ Starts a message bus worker that processes asynchronous messages from a message
 
 **Options:**
 
-- `--broker-url`: The URL for the message broker (required)
-- `--backend-url`: The URL for the message broker backend (required)
-- `--handlers`: Comma-separated list of handler names to listen to (optional)
+- `--broker-url`: The URL for the message broker (required) [env: BROKER_URL]
+- `--backend-url`: The URL for the message broker backend (required) [env: BACKEND_URL]
+- `--handlers`: Comma-separated list of handler names to listen to (optional) [env: HANDLERS]
+- `--reload`: Enable auto-reload when Python files change (for development) [env: RELOAD]
+- `--src-dir`: The source directory to watch for changes when --reload is enabled (default: "src") [env: SRC_DIR]
+
+**Environment Variables:**
+- `APP_PATH`: The application module path
+- All options support environment variables as indicated above
+
+**Example with environment variables:**
+```bash
+export APP_PATH="app.module:app"
+export BROKER_URL="amqp://guest:guest@localhost:5672/?exchange=jararaca&prefetch_count=1"
+export BACKEND_URL="redis://localhost:6379"
+export HANDLERS="send_email,process_payment"
+export RELOAD="true"
+jararaca worker
+```
+- `--reload`: Enable auto-reload when Python files change (for development)
+- `--src-dir`: The source directory to watch for changes when --reload is enabled (default: "src")
 
 ### `server` - HTTP Server
 
@@ -43,11 +61,39 @@ Starts a message bus worker that processes asynchronous messages from a message
 jararaca server APP_PATH [OPTIONS]
 ```
 
-#### Perfer `uvicorn` for production
-
 Starts a FastAPI HTTP server for your microservice.
 
+**Options:**
+
+- `--host`: Host to bind the server (default: "0.0.0.0") [env: HOST]
+- `--port`: Port to bind the server (default: 8000) [env: PORT]
+
+**Environment Variables:**
+- `APP_PATH`: The application module path
+- `HOST`: Host to bind the server
+- `PORT`: Port to bind the server
+
+**Example with environment variables:**
+```bash
+export APP_PATH="app.module:app"
+export HOST="127.0.0.1"
+export PORT="8080"
+jararaca server
+```
+
+#### Alternative: Using `uvicorn` directly
+
+For production environments, you can create an ASGI application and run it with uvicorn:
+
 ```python
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.types import Lifespan
+
+from jararaca.presentation.http_microservice import HttpMicroservice
+from jararaca.presentation.server import create_http_server
+
+
 def fastapi_factory(lifespan: Lifespan[FastAPI]) -> FastAPI:
     app = FastAPI(
         lifespan=lifespan,
@@ -78,26 +124,37 @@ Then run the server with:
 uvicorn app_module:asgi_app
 ```
 
-Starts a FastAPI HTTP server for your microservice.
-
-**Options:**
-
-- `--host`: Host to bind the server (default: "0.0.0.0")
-- `--port`: Port to bind the server (default: 8000)
-
-### `scheduler` - Task Scheduler
+### `beat` - Task Scheduler
 
 ```bash
-jararaca scheduler APP_PATH [OPTIONS]
+jararaca beat APP_PATH [OPTIONS]
 ```
 
 Runs scheduled tasks defined in your application using cron expressions.
 
 **Options:**
 
-- `--interval`: Polling interval in seconds (default: 1)
+- `--interval`: Polling interval in seconds (default: 1) [env: INTERVAL]
+- `--broker-url`: The URL for the message broker (required) [env: BROKER_URL]
+- `--backend-url`: The URL for the message broker backend (required) [env: BACKEND_URL]
+- `--actions`: Comma-separated list of action names to run (optional) [env: ACTIONS]
+- `--reload`: Enable auto-reload when Python files change (for development) [env: RELOAD]
+- `--src-dir`: The source directory to watch for changes when --reload is enabled (default: "src") [env: SRC_DIR]
 
-### `scheduler_v2` - Enhanced Task Scheduler
+**Environment Variables:**
+- `APP_PATH`: The application module path
+- All options support environment variables as indicated above
+
+**Example with environment variables:**
+```bash
+export APP_PATH="app.module:app"
+export INTERVAL="5"
+export BROKER_URL="amqp://guest:guest@localhost:5672/?exchange=jararaca&prefetch_count=1"
+export BACKEND_URL="redis://localhost:6379"
+export ACTIONS="send_emails,process_payments"
+export RELOAD="true"
+jararaca beat
+```
 
 ```bash
 jararaca scheduler_v2 APP_PATH [OPTIONS]
@@ -121,8 +178,14 @@ Generates TypeScript interfaces from your Python models to ensure type safety be
 
 **Options:**
 
-- `--watch`: Watch for file changes and regenerate TypeScript interfaces automatically
-- `--src-dir`: Source directory to watch for changes (default: "src")
+- `--watch`: Watch for file changes and regenerate TypeScript interfaces automatically [env: WATCH]
+- `--src-dir`: Source directory to watch for changes (default: "src") [env: SRC_DIR]
+- `--stdout`: Print generated interfaces to stdout instead of writing to a file [env: STDOUT]
+- `--post-process`: Command to run after generating the interfaces, {file} will be replaced with the output file path [env: POST_PROCESS]
+
+**Environment Variables:**
+- `APP_PATH`: The application module path
+- All options support environment variables as indicated above
 
 **Example with watch mode:**
 
@@ -132,6 +195,15 @@ jararaca gen-tsi app.module:app interfaces.ts --watch
 
 This will generate the TypeScript interfaces initially and then watch for any changes to Python files in the src directory, automatically regenerating the interfaces when changes are detected. You can stop watching with Ctrl+C.
 
+**Example with environment variables:**
+```bash
+export APP_PATH="app.module:app"
+export FILE_PATH="interfaces.ts"
+export WATCH="true"
+export SRC_DIR="src"
+jararaca gen-tsi
+```
+
 **Note:** To use the watch feature, you need to install the watchdog package:
 
 ```bash
@@ -152,6 +224,57 @@ jararaca gen-entity ENTITY_NAME FILE_PATH
 
 Generates a new entity file template with proper naming conventions in different formats (snake_case, PascalCase, kebab-case).
 
+**Environment Variables:**
+- `ENTITY_NAME`: The name of the entity to generate
+- `FILE_PATH`: The path where the entity file should be created
+
+**Example:**
+
+```bash
+# Using command line arguments
+jararaca gen-entity User user.py
+
+# Using environment variables
+export ENTITY_NAME="User"
+export FILE_PATH="user.py"
+jararaca gen-entity
+```
+
+### `declare` - Declare Message Infrastructure
+
+```bash
+jararaca declare APP_PATH [OPTIONS]
+```
+
+Declares RabbitMQ infrastructure (exchanges and queues) for message handlers and schedulers without starting the actual consumption processes.
+
+**Options:**
+- `--broker-url`: Broker URL (e.g., amqp://guest:guest@localhost/) [env: BROKER_URL]
+- `-i, --interactive-mode`: Enable interactive mode for queue declaration [env: INTERACTIVE_MODE]
+- `-f, --force`: Force recreation by deleting existing exchanges and queues [env: FORCE]
+
+**Environment Variables:**
+- `APP_PATH`: The application module path
+- `BROKER_URL`: The broker URL
+- `INTERACTIVE_MODE`: Enable interactive mode
+- `FORCE`: Force recreation of infrastructure
+
+**Examples:**
+
+```bash
+# Declare infrastructure
+jararaca declare myapp:app --broker-url amqp://guest:guest@localhost/
+
+# Force recreation of queues and exchanges
+jararaca declare myapp:app --broker-url amqp://guest:guest@localhost/ --force
+
+# Using environment variables
+export APP_PATH="myapp:app"
+export BROKER_URL="amqp://guest:guest@localhost/"
+export FORCE="true"
+jararaca declare
+```
+
 ## Quick Start
 
 Here's a basic example of how to create a microservice with Jararaca:

{jararaca-0.3.11a15 → jararaca-0.3.12a0}/docs/messagebus.md

@@ -29,6 +29,7 @@ graph TB
         ack[ack]
         nack[nack]
         retry[retry]
+        retry_later[retry_later]
         reject[reject]
     end
 
@@ -42,6 +43,7 @@ graph TB
     BusMessageController --> nack
     BusMessageController --> reject
     BusMessageController --> retry
+    BusMessageController --> retry_later
 ```
 
 ## Message Structure
@@ -453,12 +455,30 @@ jararaca worker APP_PATH [OPTIONS]
 
 Options:
 
-- `--url`: AMQP URL (default: "amqp://guest:guest@localhost/")
-- `--username`: AMQP username (optional)
-- `--password`: AMQP password (optional)
-- `--exchange`: Exchange name (default: "jararaca_ex")
-- `--queue`: Queue name (default: "jararaca_q")
-- `--prefetch-count`: Number of messages to prefetch (default: 1)
+- `--broker-url`: The URL for the message broker (required) [env: BROKER_URL]
+- `--backend-url`: The URL for the message broker backend (required) [env: BACKEND_URL]
+- `--handlers`: Comma-separated list of handler names to listen to (optional) [env: HANDLERS]
+- `--reload`: Enable auto-reload when Python files change (for development) [env: RELOAD]
+- `--src-dir`: The source directory to watch for changes when --reload is enabled (default: "src") [env: SRC_DIR]
+
+Examples:
+
+```bash
+# Standard worker execution
+jararaca worker myapp.main:app --broker-url "amqp://guest:guest@localhost:5672/?exchange=jararaca" --backend-url "redis://localhost:6379"
+
+# With auto-reload for development
+jararaca worker myapp.main:app --broker-url "amqp://guest:guest@localhost:5672/?exchange=jararaca" --backend-url "redis://localhost:6379" --reload
+
+# Using environment variables
+export APP_PATH="myapp.main:app"
+export BROKER_URL="amqp://guest:guest@localhost:5672/?exchange=jararaca"
+export BACKEND_URL="redis://localhost:6379"
+export RELOAD="true"
+export SRC_DIR="src"
+export RELOAD="true"
+jararaca worker
+```
 
 ## Conclusion
 

jararaca-0.3.12a0/docs/retry.md

@@ -0,0 +1,79 @@
+# Retry Mechanism with Exponential Backoff
+
+Jararaca implements a robust retry mechanism with exponential backoff for handling transient failures in RabbitMQ connections and operations. This mechanism helps the system gracefully handle temporary network issues, broker unavailability, and other transient failures.
+
+## Core Components
+
+The retry system consists of these main components:
+
+1. `RetryConfig` - Configuration class for customizing retry behavior
+2. `retry_with_backoff` - Utility function to execute operations with retry
+3. `with_retry` - Decorator for applying retry logic to functions
+
+## Retry Configuration
+
+The `RetryConfig` class allows customization of various retry parameters:
+
+```python
+class RetryConfig:
+    def __init__(
+        self,
+        max_retries: int = 5,         # Maximum number of retry attempts
+        initial_delay: float = 1.0,    # Initial delay between retries (seconds)
+        max_delay: float = 60.0,       # Maximum delay between retries (seconds)
+        backoff_factor: float = 2.0,   # Multiplier for delay after each retry
+        jitter: bool = True,           # Add randomness to delay to prevent thundering herd
+    ):
+        ...
+```
+
+## Integration with MessageBus Worker
+
+The RabbitMQ consumer in the message bus system uses the retry mechanism in several key areas:
+
+1. **Connection Establishment**: When establishing a connection to RabbitMQ, the system will automatically retry with increasing backoff periods if the connection fails.
+
+2. **Channel Creation**: When creating channels for publishing or consuming messages, failures trigger the retry mechanism.
+
+3. **Consumer Setup**: Setting up message consumers uses retry logic to handle temporary failures.
+
+## URL Configuration Parameters
+
+Retry behavior can be customized through URL parameters when configuring the RabbitMQ connection:
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `connection_retry_max` | Maximum number of connection retry attempts | 5 |
+| `connection_retry_delay` | Initial delay between connection retries (seconds) | 1.0 |
+| `connection_retry_max_delay` | Maximum delay between connection retries (seconds) | 60.0 |
+| `connection_retry_backoff` | Multiplier for delay after each connection retry | 2.0 |
+| `consumer_retry_max` | Maximum number of consumer setup retry attempts | 3 |
+| `consumer_retry_delay` | Initial delay between consumer setup retries (seconds) | 0.5 |
+| `consumer_retry_max_delay` | Maximum delay between consumer setup retries (seconds) | 5.0 |
+| `consumer_retry_backoff` | Multiplier for delay after each consumer setup retry | 2.0 |
+
+## Example Usage
+
+```python
+# Configure with custom retry settings in URL:
+broker_url = "amqp://guest:guest@localhost:5672/?exchange=jararaca&prefetch_count=10&connection_retry_max=10&connection_retry_delay=2.0"
+
+# Use custom retry configuration in code:
+from jararaca.utils.retry import RetryConfig, retry_with_backoff
+
+config = RetryConfig(max_retries=3, initial_delay=1.0, max_delay=30.0)
+
+async def connect_with_retry():
+    return await retry_with_backoff(
+        establish_connection,
+        retry_config=config,
+        retry_exceptions=(ConnectionError, TimeoutError)
+    )
+```
+
+## Benefits
+
+1. **Resilience** - The system can recover automatically from transient failures
+2. **Reduced downtime** - Automatic reconnection minimizes service disruption
+3. **Configuration flexibility** - Retry behavior can be tailored to different environments
+4. **Smart backoff** - Exponential backoff with jitter prevents overloading services during recovery

{jararaca-0.3.11a15 → jararaca-0.3.12a0}/docs/scheduler.md

@@ -12,22 +12,16 @@ The Jararaca scheduler allows you to:
 - Distribute scheduled tasks across multiple instances
 - Handle delayed message execution
 
-The scheduler has two implementations:
-1. **Basic Scheduler** - Simple scheduler for local execution
-2. **Enhanced Scheduler (V2)** - Distributed scheduler with improved backend support and message broker integration
+The scheduler is implemented through the BeatWorker which provides distributed task scheduling via a message broker:
 
 ```mermaid
 graph TD
-    A[Microservice] --> B[Scheduler System]
-    B --> C[Basic Scheduler]
-    B --> D[Enhanced Scheduler V2]
-
-    C --> E[Local Task Execution]
-    D --> F[Message Broker]
-    F --> G[Workers]
-    D --> H[Backend Store]
-    H --> I[Last Execution Time]
-    H --> J[Delayed Messages]
+    A[Microservice] --> B[BeatWorker]
+    B --> C[Message Broker]
+    B --> D[Backend Store]
+    C --> E[Message Processing]
+    D --> F[Last Execution Time]
+    D --> G[Delayed Messages]
 ```
 
 ## Using the Scheduler
@@ -73,31 +67,57 @@ Jararaca uses standard cron expressions for scheduling. Here are some examples:
 - `0 0 * * 0` - Run at midnight every Sunday
 - `0 0 1 * *` - Run at midnight on the first day of every month
 
-## Basic Scheduler Implementation
+## Using the BeatWorker Scheduler
 
-The basic scheduler is suitable for simpler applications where tasks run locally:
+The BeatWorker scheduler provides distributed task execution through a message broker:
 
 ```python
 from jararaca import Microservice, ScheduledAction
+from jararaca.scheduler.beat_worker import BeatWorker
 
 app = Microservice(
     # Your microservice configuration
 )
 
 # Run the scheduler
-from jararaca.scheduler.scheduler import Scheduler
-
-scheduler = Scheduler(app, interval=1)
-scheduler.run()
+beat_worker = BeatWorker(
+    app=app,
+    interval=1,
+    backend_url="redis://localhost:6379",
+    broker_url="amqp://guest:guest@localhost:5672/?exchange=jararaca",
+    scheduled_action_names=None  # Optional set of action names to run
+)
+beat_worker.run()
 ```
 
-## Enhanced Scheduler V2 Implementation
+You can also use the CLI command to run the scheduler:
 
-The V2 scheduler adds support for distributed execution and message broker integration, making it ideal for more complex applications:
+```bash
+# Standard beat scheduler execution
+jararaca beat app_module:app --interval 1 --broker-url "amqp://guest:guest@localhost:5672/?exchange=jararaca" --backend-url "redis://localhost:6379"
+
+# With auto-reload for development (automatically restarts when Python files change)
+jararaca beat app_module:app --interval 1 --broker-url "amqp://guest:guest@localhost:5672/?exchange=jararaca" --backend-url "redis://localhost:6379" --reload
+
+# Using environment variables
+export APP_PATH="app_module:app"
+export INTERVAL="1"
+export BROKER_URL="amqp://guest:guest@localhost:5672/?exchange=jararaca"
+export BACKEND_URL="redis://localhost:6379"
+export RELOAD="true"
+export SRC_DIR="src"
+jararaca beat
+```
 
-```python
-from jararaca import Microservice, ScheduledAction
-from jararaca.scheduler.scheduler_v2 import SchedulerV2
+All command options support environment variables:
+- `APP_PATH`: The application module path [required]
+- `INTERVAL`: Polling interval in seconds [default: 1]
+- `BROKER_URL`: The URL for the message broker [required]
+- `BACKEND_URL`: The URL for the message broker backend [required]
+- `ACTIONS`: Comma-separated list of action names to run [optional]
+- `RELOAD`: Enable auto-reload when Python files change [optional]
+- `SRC_DIR`: The source directory to watch for changes when using reload [default: "src"]
+```
 
 app = Microservice(
     # Your microservice configuration

{jararaca-0.3.11a15 → jararaca-0.3.12a0}/docs/websocket.md

@@ -57,24 +57,38 @@ class WebSocketMessage(WebSocketMessageBase):
 
 ### 3. WebSocketConnectionManager
 
-Manages WebSocket connections, rooms, and message distribution:
+A Protocol that defines the interface for managing WebSocket connections:
 
+```python
+class WebSocketConnectionManager(Protocol):
+    async def broadcast(self, message: bytes) -> None: ...
+    async def send(self, rooms: list[str], message: WebSocketMessageBase) -> None: ...
+    async def join(self, rooms: list[str], websocket: WebSocket) -> None: ...
+    async def add_websocket(self, websocket: WebSocket) -> None: ...
+    async def remove_websocket(self, websocket: WebSocket) -> None: ...
+```
+
+The WebSocketConnectionManager:
 - Maintains a registry of active WebSocket connections
 - Groups connections into named rooms
 - Provides methods for broadcasting and sending targeted messages
 
-### 4. WebSocketConnectionBackend
+### 4. Context-based WebSocket Access
 
-A protocol defining the contract for backend implementations:
+Jararaca uses context variables to provide access to WebSocket functionality anywhere in your application:
 
 ```python
-class WebSocketConnectionBackend(Protocol):
-    async def broadcast(self, message: bytes) -> None: ...
-    async def send(self, rooms: list[str], message: bytes) -> None: ...
-    def configure(
-        self, broadcast: BroadcastFunc, send: SendFunc, shutdown_event: asyncio.Event
-    ) -> None: ...
-    async def shutdown(self) -> None: ...
+from jararaca.presentation.websocket.context import use_ws_manager, use_ws_message_sender
+
+# Send a message to specific rooms
+async def notify_users(message_data: dict, room_id: str):
+    message = UserNotificationMessage(**message_data)
+    await use_ws_message_sender().send([room_id], message)
+
+# Or directly from a WebSocketMessage instance
+async def send_update(update_data: dict, room_id: str):
+    message = SystemUpdateMessage(**update_data)
+    await message.send(room_id)
 ```
 
 ### 5. RedisWebSocketConnectionBackend

{jararaca-0.3.11a15 → jararaca-0.3.12a0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "jararaca"
-version = "0.3.11a15"
+version = "0.3.12a0"
 description = "A simple and fast API framework for Python"
 authors = ["Lucas S <me@luscasleo.dev>"]
 readme = "README.md"