jararaca 0.3.9__tar.gz → 0.3.11__tar.gz

{jararaca-0.3.9 → jararaca-0.3.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: jararaca
-Version: 0.3.9
+Version: 0.3.11
 Summary: A simple and fast API framework for Python
 Author: Lucas S
 Author-email: me@luscasleo.dev
@@ -16,6 +16,7 @@ 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: frozendict (>=2.4.6,<3.0.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"

{jararaca-0.3.9 → jararaca-0.3.11}/docs/index.md

@@ -33,25 +33,9 @@ Starts a message bus worker that processes asynchronous messages from a message
 
 **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)
-
-### `worker_v2` - Enhanced Message Bus Worker
-
-```bash
-jararaca worker_v2 APP_PATH [OPTIONS]
-```
-
-Starts an enhanced version of the message bus worker with improved backend support.
-
-**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)
 
 ### `server` - HTTP Server
 

{jararaca-0.3.9 → jararaca-0.3.11}/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

jararaca-0.3.11/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.9 → jararaca-0.3.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "jararaca"
-version = "0.3.9"
+version = "0.3.11"
 description = "A simple and fast API framework for Python"
 authors = ["Lucas S <me@luscasleo.dev>"]
 readme = "README.md"
@@ -28,6 +28,7 @@ types-croniter = "^3.0.3.20240731"
 types-redis = "^4.6.0.20240903"
 mako = "^1.3.5"
 watchdog = { version = "^3.0.0", optional = true }
+frozendict = "^2.4.6"
 
 
 [tool.poetry.extras]
@@ -78,3 +79,7 @@ strict = true
 # JARARACA CONFIG
 [tool.poetry.scripts]
 jararaca = "jararaca.cli:cli"
+
+[[tool.mypy.overrides]]
+module = "mako.*"
+ignore_missing_imports = true

{jararaca-0.3.9 → jararaca-0.3.11}/src/jararaca/__init__.py

@@ -11,7 +11,7 @@ if TYPE_CHECKING:
         retry_later,
         use_bus_message_controller,
     )
-    from jararaca.microservice import AppContext, AppInterceptor
+    from jararaca.microservice import AppContext, AppInterceptor, AppTransactionContext
     from jararaca.observability.interceptor import ObservabilityInterceptor
     from jararaca.observability.providers.otel import OtelObservabilityProvider
     from jararaca.persistence.sort_filter import (
@@ -32,6 +32,17 @@ if TYPE_CHECKING:
         raises_500_on,
         raises_http_exception_on,
     )
+    from jararaca.reflect.controller_inspect import (
+        ControllerMemberReflect,
+        ControllerReflect,
+    )
+    from jararaca.reflect.metadata import (
+        SetMetadata,
+        get_all_metadata,
+        get_metadata,
+        get_metadata_value,
+        provide_metadata,
+    )
     from jararaca.rpc.http.backends.httpx import HTTPXHttpRPCAsyncBackend
     from jararaca.rpc.http.backends.otel import TracedRequestMiddleware
     from jararaca.rpc.http.decorators import Body
@@ -53,6 +64,7 @@ if TYPE_CHECKING:
         RestClient,
         RouteHttpErrorHandler,
         RPCRequestNetworkError,
+        RPCUnhandleError,
     )
 
     from .core.providers import ProviderSpec, Token
@@ -67,13 +79,22 @@ if TYPE_CHECKING:
     )
     from .messagebus.message import Message, MessageOf
     from .messagebus.publisher import use_publisher
-    from .messagebus.worker import MessageBusWorker
-    from .microservice import Microservice, use_app_context, use_current_container
+    from .microservice import (
+        Microservice,
+        use_app_context,
+        use_app_transaction_context,
+        use_app_tx_ctx_data,
+        use_current_container,
+    )
     from .persistence.base import T_BASEMODEL, BaseEntity
     from .persistence.interceptors.aiosqa_interceptor import (
         AIOSQAConfig,
         AIOSqlAlchemySessionInterceptor,
+        providing_new_session,
+        providing_session,
+        providing_transaction,
         use_session,
+        use_transaction,
     )
     from .persistence.utilities import (
         CriteriaBasedAttributeQueryInjector,
@@ -118,6 +139,11 @@ if TYPE_CHECKING:
     from .tools.app_config.interceptor import AppConfigurationInterceptor
 
     __all__ = [
+        "SetMetadata",
+        "provide_metadata",
+        "get_metadata",
+        "get_all_metadata",
+        "get_metadata_value",
         "RedisMessageBrokerBackend",
         "FilterRuleApplier",
         "SortRuleApplier",
@@ -128,6 +154,7 @@ if TYPE_CHECKING:
         "retry",
         "retry_later",
         "RPCRequestNetworkError",
+        "RPCUnhandleError",
         "FILTER_SORT_ENTITY_ATTR_MAP",
         "FilterModel",
         "SortFilterRunner",
@@ -187,10 +214,14 @@ if TYPE_CHECKING:
         "AIOSqlAlchemySessionInterceptor",
         "AIOSQAConfig",
         "create_http_server",
-        "MessageBusWorker",
         "Container",
         "WebSocketInterceptor",
         "use_session",
+        "use_transaction",
+        "providing_session",
+        "provide_session",
+        "providing_transaction",
+        "providing_new_session",
         "Post",
         "Get",
         "Patch",
@@ -212,7 +243,12 @@ if TYPE_CHECKING:
         "HttpRpcClientBuilder",
         "HTTPXHttpRPCAsyncBackend",
         "use_app_context",
+        "use_app_transaction_context",
+        "use_app_tx_ctx_data",
+        "AppTransactionContext",
         "AppContext",
+        "ControllerMemberReflect",
+        "ControllerReflect",
         "AppInterceptor",
         "OtelObservabilityProvider",
     ]
@@ -220,6 +256,11 @@ if TYPE_CHECKING:
 __SPEC_PARENT__: str = __spec__.parent  # type: ignore
 # A mapping of {<member name>: (package, <module name>)} defining dynamic imports
 _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
+    "SetMetadata": (__SPEC_PARENT__, "reflect.metadata", None),
+    "provide_metadata": (__SPEC_PARENT__, "reflect.metadata", None),
+    "get_metadata": (__SPEC_PARENT__, "reflect.metadata", None),
+    "get_all_metadata": (__SPEC_PARENT__, "reflect.metadata", None),
+    "get_metadata_value": (__SPEC_PARENT__, "reflect.metadata", None),
     "RedisMessageBrokerBackend": (
         __SPEC_PARENT__,
         "broker_backend.redis_broker_backend",
@@ -243,6 +284,7 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
     "retry": (__SPEC_PARENT__, "messagebus.bus_message_controller", None),
     "retry_later": (__SPEC_PARENT__, "messagebus.bus_message_controller", None),
     "RPCRequestNetworkError": (__SPEC_PARENT__, "rpc.http.decorators", None),
+    "RPCUnhandleError": (__SPEC_PARENT__, "rpc.http.decorators", None),
     "FILTER_SORT_ENTITY_ATTR_MAP": (__SPEC_PARENT__, "persistence.sort_filter", None),
     "FilterModel": (__SPEC_PARENT__, "persistence.sort_filter", None),
     "SortFilterRunner": (__SPEC_PARENT__, "persistence.sort_filter", None),
@@ -323,7 +365,6 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
         None,
     ),
     "create_http_server": (__SPEC_PARENT__, "presentation.server", None),
-    "MessageBusWorker": (__SPEC_PARENT__, "messagebus.worker", None),
     "Container": (__SPEC_PARENT__, "di", None),
     "WebSocketInterceptor": (
         __SPEC_PARENT__,
@@ -335,6 +376,31 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
         "persistence.interceptors.aiosqa_interceptor",
         None,
     ),
+    "use_transaction": (
+        __SPEC_PARENT__,
+        "persistence.interceptors.aiosqa_interceptor",
+        None,
+    ),
+    "providing_session": (
+        __SPEC_PARENT__,
+        "persistence.interceptors.aiosqa_interceptor",
+        None,
+    ),
+    "provide_session": (
+        __SPEC_PARENT__,
+        "persistence.interceptors.aiosqa_interceptor",
+        None,
+    ),
+    "providing_new_session": (
+        __SPEC_PARENT__,
+        "persistence.interceptors.aiosqa_interceptor",
+        None,
+    ),
+    "providing_transaction": (
+        __SPEC_PARENT__,
+        "persistence.interceptors.aiosqa_interceptor",
+        None,
+    ),
     "Post": (__SPEC_PARENT__, "presentation.decorators", None),
     "Get": (__SPEC_PARENT__, "presentation.decorators", None),
     "Patch": (__SPEC_PARENT__, "presentation.decorators", None),
@@ -375,8 +441,13 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
     "HttpRpcClientBuilder": (__SPEC_PARENT__, "rpc.http.decorators", None),
     "HTTPXHttpRPCAsyncBackend": (__SPEC_PARENT__, "rpc.http.backends.httpx", 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),
     "AppContext": (__SPEC_PARENT__, "microservice", None),
     "AppInterceptor": (__SPEC_PARENT__, "microservice", None),
+    "AppTransactionContext": (__SPEC_PARENT__, "microservice", None),
+    "ControllerMemberReflect": (__SPEC_PARENT__, "reflect.controller_inspect", None),
+    "ControllerReflect": (__SPEC_PARENT__, "reflect.controller_inspect", None),
 }