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

README.md

@@ -0,0 +1,121 @@
+<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
+- **`@ExposeType` decorator** - Explicitly expose types for TypeScript generation without needing them in endpoints
+
+### 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

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from importlib import import_module
 from typing import TYPE_CHECKING
 
@@ -11,7 +15,28 @@ if TYPE_CHECKING:
         retry_later,
         use_bus_message_controller,
     )
-    from jararaca.microservice import AppContext, AppInterceptor, AppTransactionContext
+    from jararaca.microservice import (
+        AppContext,
+        AppInterceptor,
+        AppTransactionContext,
+        use_app_type,
+    )
+    from jararaca.observability.decorators import TracedClass, TracedFunc, traced_class
+    from jararaca.observability.fastapi_exception_handler import (
+        setup_fastapi_exception_handler,
+    )
+    from jararaca.observability.hooks import (
+        add_event,
+        add_span_link,
+        get_current_span,
+        get_current_span_context,
+        get_tracing_provider,
+        record_exception,
+        set_span_attribute,
+        set_span_status,
+        spawn_trace,
+        start_span,
+    )
     from jararaca.observability.interceptor import ObservabilityInterceptor
     from jararaca.observability.providers.otel import OtelObservabilityProvider
     from jararaca.persistence.sort_filter import (
@@ -22,6 +47,7 @@ if TYPE_CHECKING:
         SortModel,
         SortRuleApplier,
     )
+    from jararaca.presentation.exceptions import PresentationException
     from jararaca.presentation.hooks import (
         raises_200_on,
         raises_400_on,
@@ -38,34 +64,58 @@ if TYPE_CHECKING:
     )
     from jararaca.reflect.metadata import (
         SetMetadata,
+        TransactionMetadata,
         get_all_metadata,
         get_metadata,
         get_metadata_value,
-        provide_metadata,
+        start_providing_metadata,
+        start_transaction_metadata_context,
     )
     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,
         RouteHttpErrorHandler,
         RPCRequestNetworkError,
+        RPCRetryPolicy,
         RPCUnhandleError,
+        Timeout,
+        TimeoutException,
     )
+    from jararaca.utils.retry import RetryPolicy
 
     from .core.providers import ProviderSpec, Token
     from .di import Container
@@ -81,6 +131,9 @@ if TYPE_CHECKING:
     from .messagebus.publisher import use_publisher
     from .microservice import (
         Microservice,
+        is_shutting_down,
+        request_shutdown,
+        shutdown_race,
         use_app_context,
         use_app_transaction_context,
         use_app_tx_ctx_data,
@@ -96,6 +149,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,
@@ -120,6 +178,7 @@ if TYPE_CHECKING:
         RestController,
         UseDependency,
         UseMiddleware,
+        compose_route_decorators,
     )
     from .presentation.http_microservice import HttpMicroservice, HttpMiddleware
     from .presentation.server import create_http_server
@@ -137,14 +196,23 @@ 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 (
+        ExposeType,
+        MutationEndpoint,
+        QueryEndpoint,
+        SplitInputOutput,
+    )
 
     __all__ = [
         "SetMetadata",
-        "provide_metadata",
+        "start_transaction_metadata_context",
+        "start_providing_metadata",
+        "TransactionMetadata",
         "get_metadata",
         "get_all_metadata",
         "get_metadata_value",
         "RedisMessageBrokerBackend",
+        "RetryPolicy",
         "FilterRuleApplier",
         "SortRuleApplier",
         "use_bus_message_controller",
@@ -162,6 +230,7 @@ if TYPE_CHECKING:
         "RegisterWebSocketMessage",
         "TracedRequestMiddleware",
         "raises_http_exception_on",
+        "PresentationException",
         "raises_200_on",
         "raises_422_on",
         "raises_404_on",
@@ -183,9 +252,30 @@ if TYPE_CHECKING:
         "HttpPut",
         "HttpDelete",
         "ObservabilityInterceptor",
+        "TracedFunc",
+        "TracedClass",
+        "traced_class",
+        "start_span",
+        "add_span_link",
+        "get_current_span",
+        "get_current_span_context",
+        "spawn_trace",
+        "set_span_attribute",
+        "add_event",
+        "setup_fastapi_exception_handler",
+        "set_span_status",
+        "record_exception",
+        "get_tracing_provider",
         "QueryInjector",
         "HttpMicroservice",
         "use_current_container",
+        "use_app_context",
+        "use_app_transaction_context",
+        "use_app_tx_ctx_data",
+        "is_shutting_down",
+        "shutdown_race",
+        "request_shutdown",
+        "Microservice",
         "T_BASEMODEL",
         "DatedEntity",
         "BaseEntity",
@@ -208,7 +298,6 @@ if TYPE_CHECKING:
         "MessageBusController",
         "MessageHandler",
         "ScheduledAction",
-        "Microservice",
         "ProviderSpec",
         "Token",
         "AIOSqlAlchemySessionInterceptor",
@@ -219,7 +308,9 @@ if TYPE_CHECKING:
         "use_session",
         "use_transaction",
         "providing_session",
-        "provide_session",
+        "uses_persistence_session",
+        "skip_persistence_session",
+        "set_use_persistence_session",
         "providing_transaction",
         "providing_new_session",
         "Post",
@@ -233,8 +324,13 @@ if TYPE_CHECKING:
         "MessageBusPublisherInterceptor",
         "RedisWebSocketConnectionBackend",
         "AppConfigurationInterceptor",
+        "ExposeType",
+        "QueryEndpoint",
+        "MutationEndpoint",
+        "SplitInputOutput",
         "UseMiddleware",
         "UseDependency",
+        "compose_route_decorators",
         "GlobalHttpErrorHandler",
         "RouteHttpErrorHandler",
         "WebSocketMessage",
@@ -242,10 +338,29 @@ 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
+        "RPCRetryPolicy",
+        # Exception classes
+        "TimeoutException",
         "AppTransactionContext",
+        "use_app_type",
         "AppContext",
         "ControllerMemberReflect",
         "ControllerReflect",
@@ -257,10 +372,13 @@ __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),
+    "TransactionMetadata": (__SPEC_PARENT__, "reflect.metadata", None),
+    "start_transaction_metadata_context": (__SPEC_PARENT__, "reflect.metadata", None),
+    "start_providing_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),
+    "RetryPolicy": (__SPEC_PARENT__, "utils.retry", None),
     "RedisMessageBrokerBackend": (
         __SPEC_PARENT__,
         "broker_backend.redis_broker_backend",
@@ -301,6 +419,7 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
     ),
     "TracedRequestMiddleware": (__SPEC_PARENT__, "rpc.http.backends.otel", None),
     "raises_http_exception_on": (__SPEC_PARENT__, "presentation.hooks", None),
+    "PresentationException": (__SPEC_PARENT__, "presentation.exceptions", None),
     "raises_200_on": (__SPEC_PARENT__, "presentation.hooks", None),
     "raises_400_on": (__SPEC_PARENT__, "presentation.hooks", None),
     "raises_401_on": (__SPEC_PARENT__, "presentation.hooks", None),
@@ -322,6 +441,24 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
     "HttpPut": (__SPEC_PARENT__, "rpc.http.decorators", "Put"),
     "HttpDelete": (__SPEC_PARENT__, "rpc.http.decorators", "Delete"),
     "ObservabilityInterceptor": (__SPEC_PARENT__, "observability.interceptor", None),
+    "TracedFunc": (__SPEC_PARENT__, "observability.decorators", None),
+    "TracedClass": (__SPEC_PARENT__, "observability.decorators", None),
+    "traced_class": (__SPEC_PARENT__, "observability.decorators", None),
+    "spawn_trace": (__SPEC_PARENT__, "observability.hooks", None),
+    "setup_fastapi_exception_handler": (
+        __SPEC_PARENT__,
+        "observability.fastapi_exception_handler",
+        None,
+    ),
+    "set_span_attribute": (__SPEC_PARENT__, "observability.hooks", None),
+    "start_span": (__SPEC_PARENT__, "observability.hooks", None),
+    "add_span_link": (__SPEC_PARENT__, "observability.hooks", None),
+    "get_current_span": (__SPEC_PARENT__, "observability.hooks", None),
+    "get_current_span_context": (__SPEC_PARENT__, "observability.hooks", None),
+    "add_event": (__SPEC_PARENT__, "observability.hooks", None),
+    "set_span_status": (__SPEC_PARENT__, "observability.hooks", None),
+    "record_exception": (__SPEC_PARENT__, "observability.hooks", None),
+    "get_tracing_provider": (__SPEC_PARENT__, "observability.hooks", None),
     "QueryInjector": (__SPEC_PARENT__, "persistence.utilities", None),
     "HttpMicroservice": (__SPEC_PARENT__, "presentation.http_microservice", None),
     "use_current_container": (__SPEC_PARENT__, "microservice", None),
@@ -386,19 +523,29 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
         "persistence.interceptors.aiosqa_interceptor",
         None,
     ),
-    "provide_session": (
+    "providing_new_session": (
         __SPEC_PARENT__,
         "persistence.interceptors.aiosqa_interceptor",
         None,
     ),
-    "providing_new_session": (
+    "providing_transaction": (
         __SPEC_PARENT__,
         "persistence.interceptors.aiosqa_interceptor",
         None,
     ),
-    "providing_transaction": (
+    "uses_persistence_session": (
         __SPEC_PARENT__,
-        "persistence.interceptors.aiosqa_interceptor",
+        "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),
@@ -427,8 +574,13 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
         "tools.app_config.interceptor",
         None,
     ),
+    "ExposeType": (__SPEC_PARENT__, "tools.typescript.decorators", 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),
+    "compose_route_decorators": (__SPEC_PARENT__, "presentation.decorators", None),
     "GlobalHttpErrorHandler": (__SPEC_PARENT__, "rpc.http.decorators", None),
     "RouteHttpErrorHandler": (__SPEC_PARENT__, "rpc.http.decorators", None),
     "WebSocketMessage": (__SPEC_PARENT__, "presentation.websocket.types", None),
@@ -440,12 +592,32 @@ _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),
+    "RPCRetryPolicy": (__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),
+    "shutdown_race": (__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),
+    "use_app_type": (__SPEC_PARENT__, "microservice", None),
     "ControllerMemberReflect": (__SPEC_PARENT__, "reflect.controller_inspect", None),
     "ControllerReflect": (__SPEC_PARENT__, "reflect.controller_inspect", None),
 }

jararaca/__main__.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from jararaca.cli import cli
 
 if __name__ == "__main__":

jararaca/broker_backend/__init__.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from abc import ABC
 from contextlib import asynccontextmanager
 from typing import AsyncContextManager, AsyncGenerator, Iterable

jararaca/broker_backend/mapper.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from jararaca.broker_backend import MessageBrokerBackend
 
 

jararaca/broker_backend/redis_broker_backend.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import logging
 import time
 from contextlib import asynccontextmanager
@@ -147,9 +151,11 @@ class RedisMessageBrokerBackend(MessageBrokerBackend):
                 )
                 delayed_messages.append(delayed_message)
             except Exception:
-                logger.error(
-                    f"Error parsing delayed message: {task_bytes_data.decode()}"
-                )
+                if logger.isEnabledFor(logging.ERROR):
+                    logger.error(
+                        "Error parsing delayed message: %s",
+                        task_bytes_data.decode(),
+                    )
                 continue
 
         return delayed_messages