jararaca 0.2.37a11__tar.gz → 0.2.37a12__tar.gz

jararaca-0.2.37a12/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.3
+Name: jararaca
+Version: 0.2.37a12
+Summary: A simple and fast API framework for Python
+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
+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: 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"
+Requires-Dist: opentelemetry-exporter-otlp (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-sdk (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
+Requires-Dist: redis (>=5.0.8,<6.0.0)
+Requires-Dist: sqlalchemy (>=2.0.34,<3.0.0)
+Requires-Dist: types-croniter (>=3.0.3.20240731,<4.0.0.0)
+Requires-Dist: types-redis (>=4.6.0.20240903,<5.0.0.0)
+Requires-Dist: uvicorn (>=0.30.6,<0.31.0)
+Requires-Dist: uvloop (>=0.20.0,<0.21.0)
+Requires-Dist: websockets (>=13.0.1,<14.0.0)
+Project-URL: Repository, https://github.com/LuscasLeo/jararaca
+Description-Content-Type: text/markdown
+
+<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-0.2.37a12/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-0.2.37a12/docs/CNAME

@@ -0,0 +1 @@
+jararaca.luscasleo.dev

jararaca-0.2.37a12/docs/architecture.md

@@ -0,0 +1,372 @@
+# Jararaca Architecture
+
+## Core Concept: Unified Runtime Interface
+
+Jararaca implements a unified runtime interface that allows different types of applications (REST API, Message Bus Worker, and Scheduler) to share the same utilities and context. This means that utilities like `@use_session` can be used consistently across different runtime contexts, even though they run as separate processes.
+
+## Runtime Types
+
+1. **REST API Runtime**
+
+   - Handles HTTP requests and WebSocket connections
+   - Executes REST controllers
+   - Uses `@RestController` decorator for route definitions
+
+2. **Message Bus Worker Runtime**
+
+   - Processes asynchronous messages and events
+   - Handles tasks and events through `@MessageBusController`
+   - Manages message queues and event processing
+
+3. **Scheduler Runtime**
+   - Executes scheduled tasks at specified intervals
+   - Uses `@ScheduledAction` decorator for task definitions
+   - Manages cron-based job execution
+
+## Application Structure
+
+The application structure follows a hierarchical pattern:
+
+1. **Microservice Declaration**
+
+   - Uses `@Microservice` class for configuration
+   - Declares providers, controllers, and interceptors
+   - No execution happens at declaration time
+   - Configuration is shared across all runtimes
+
+2. **Application Implementation**
+
+   - **REST Controllers** (`@RestController`)
+
+     - Handle HTTP endpoints
+     - Run in REST API runtime
+     - Support middleware and dependency injection
+
+   - **Events and Tasks** (`@MessageBusController`)
+
+     - Handle asynchronous operations
+     - Run in Message Bus Worker runtime
+     - Support message publishing and consumption
+
+   - **Scheduled Jobs** (`@ScheduledAction`)
+     - Execute at specified intervals
+     - Run in Scheduler runtime
+     - Support cron-based scheduling
+
+## Architecture Diagram
+
+```mermaid
+graph LR
+    subgraph "Runtime Layer"
+        REST[REST API Runtime]
+        Worker[Message Bus Worker Runtime]
+        Scheduler[Scheduler Runtime]
+    end
+
+    subgraph "Application Layer"
+        Microservice[Microservice Declaration]
+        RESTController[REST Controllers]
+        MessageBus[Events & Tasks]
+        ScheduledJobs[Scheduled Jobs]
+    end
+
+    subgraph "Shared Utilities"
+        Session[use_session]
+        Publisher[use_publisher]
+        WS[use_ws_manager]
+    end
+
+    Microservice --> REST
+    Microservice --> Worker
+    Microservice --> Scheduler
+
+    REST --> RESTController
+    Worker --> MessageBus
+    Scheduler --> ScheduledJobs
+
+    RESTController --> Session
+    MessageBus --> Session
+    ScheduledJobs --> Session
+
+    RESTController --> Publisher
+    MessageBus --> Publisher
+    ScheduledJobs --> Publisher
+
+    RESTController --> WS
+    MessageBus --> WS
+    ScheduledJobs --> WS
+```
+
+## Key Features
+
+1. **Shared Context**
+
+   - All runtimes share the same context and utilities
+   - Consistent access to services like database sessions
+   - Unified dependency injection system
+
+2. **Declarative Configuration**
+
+   - Configuration is defined once in `Microservice`
+   - Runtime-specific settings are handled separately
+   - Easy to maintain and modify
+
+3. **Process Isolation**
+
+   - Each runtime runs as a separate process
+   - Clear separation of concerns
+   - Independent scaling and deployment
+
+4. **Unified Utilities**
+   - Common utilities like `@use_session` work across all runtimes
+   - Consistent API for database access, message publishing, etc.
+   - Reduced code duplication
+
+## Usage Example
+
+```python
+from jararaca import (
+    AIOPikaConnectionFactory,
+    AIOSQAConfig,
+    AIOSqlAlchemySessionInterceptor,
+    AppConfigurationInterceptor,
+    HttpMicroservice,
+    MessageBusPublisherInterceptor,
+    Microservice,
+    ProviderSpec,
+    RedisWebSocketConnectionBackend,
+    Token,
+    WebSocketInterceptor,
+    create_http_server,
+)
+
+
+# Define your application configuration
+class AppConfig:
+    DATABASE_URL: str
+    REDIS_URL: str
+    AMQP_URL: str
+
+# Create the microservice with all necessary components
+app = Microservice(
+    providers=[
+        ProviderSpec(
+            provide=Token(Redis, "REDIS"),
+            use_factory=lambda config: Redis.from_url(config.REDIS_URL, decode_responses=False),
+            after_interceptors=True,
+        ),
+    ],
+    controllers=[
+        TasksController,  # Your controller class
+    ],
+    interceptors=[
+        # Configuration interceptor
+        AppConfigurationInterceptor(
+            global_configs=[
+                (Token(AppConfig, "APP_CONFIG"), AppConfig),
+            ]
+        ),
+        # Message bus interceptor
+        AppFactoryWithAppConfig(
+            lambda config: MessageBusPublisherInterceptor(
+                connection_factory=AIOPikaConnectionFactory(
+                    url=config.AMQP_URL,
+                    exchange="jararaca_ex",
+                ),
+            )
+        ),
+        # Database session interceptor
+        AppFactoryWithAppConfig(
+            lambda config: AIOSqlAlchemySessionInterceptor(
+                AIOSQAConfig(
+                    connection_name="default",
+                    url=config.DATABASE_URL,
+                )
+            )
+        ),
+        # WebSocket interceptor
+        AppFactoryWithAppConfig(
+            lambda config: WebSocketInterceptor(
+                backend=RedisWebSocketConnectionBackend(
+                    send_pubsub_channel="jararaca:websocket:send",
+                    broadcast_pubsub_channel="jararaca:websocket:broadcast",
+                    conn=Redis.from_url(config.REDIS_URL, decode_responses=False),
+                )
+            ),
+        ),
+    ],
+)
+
+# Create HTTP server for REST API runtime
+http_app = create_http_server(
+    HttpMicroservice(
+        app=app,
+        factory=fastapi_factory,
+    )
+)
+
+
+class HelloTask(Message):
+    MESSAGE_TYPE = "task"
+    MESSAGE_TOPIC = "task.topic.name"
+
+    message: str
+
+# Example controller showing unified utilities across runtimes
+@MessageBusController()
+@RestController("/tasks")
+class TasksController:
+    def __init__(self, redis: Annotated[Redis, Token(Redis, "REDIS")]):
+        self.redis = redis
+        self.tasks_crud = CRUDOperations(TaskEntity, use_session)
+
+    @Post("/")
+    async def create_task(self, task: CreateTaskSchema) -> Identifiable[TaskSchema]:
+        # Use session in REST context
+        task_entity = await self.tasks_crud.create(task)
+        await use_ws_manager().broadcast(b"New Task Created")
+        await use_publisher().publish(task_entity.to_identifiable(TaskSchema), topic="task")
+        return task_entity.to_identifiable(TaskSchema)
+
+    @MessageHandler(HelloTask)
+    async def process_task(self, message: MessageOf[HelloTask]) -> None:
+        # Use session in Message Bus context
+        print(message.message)
+
+    @ScheduledAction("* * * * * */5")
+    async def scheduled_task(self) -> None:
+        # Use session in Scheduler context
+        pending_tasks = await use_session().execute(select(TaskEntity))
+        for task in pending_tasks:
+            await use_publisher().publish(task.to_identifiable(TaskSchema), topic="task")
+```
+
+## Context Hooks and Interceptors
+
+Jararaca provides a powerful system of context hooks (like `use_session`, `use_publisher`, `use_ws_manager`) that are managed through Python's `ContextVar` system. These hooks are configured separately for each execution context and are provided by interceptors configured in the `Microservice` instance.
+
+> **Important Note on Interceptor Order**
+> The order of interceptors in the `Microservice` instance matters significantly. Interceptors are executed in the order they are defined, meaning:
+>
+> - The first interceptor in the list will set up its context before the subsequent ones
+> - This order affects how dependencies between different context hooks are resolved
+> - For example, if a database session is needed by a message publisher, the session interceptor should be configured before the publisher interceptor
+
+### How Context Hooks Work
+
+1. **Context Isolation**
+
+   - Each execution (HTTP request, message processing, scheduled job) gets its own isolated context
+   - Context hooks provide access to resources specific to that execution
+   - Resources are automatically cleaned up when the execution completes
+
+2. **Interceptor-Based Provision**
+   - Interceptors are responsible for setting up and managing the context
+   - They are configured in the `Microservice` instance
+   - Each interceptor handles a specific type of resource
+
+### Example: Database Session Management
+
+```python
+# The AIOSqlAlchemySessionInterceptor manages database sessions
+class AIOSqlAlchemySessionInterceptor(AppInterceptor):
+    def __init__(self, config: AIOSQAConfig):
+        self.config = config
+        self.engine = create_async_engine(self.config.url)
+        self.sessionmaker = async_sessionmaker(self.engine)
+
+    @asynccontextmanager
+    async def intercept(self, app_context: AppContext) -> AsyncGenerator[None, None]:
+        # Creates a new session for this execution
+        async with self.sessionmaker() as session:
+            # Provides the session to the context
+            with provide_session(self.config.connection_name, session):
+                try:
+                    yield
+                    await session.commit()
+                except Exception as e:
+                    await session.rollback()
+                    raise e
+```
+
+### Context Hook Lifecycle
+
+1. **Configuration**
+
+   ```python
+   app = Microservice(
+       interceptors=[
+           AIOSqlAlchemySessionInterceptor(
+               AIOSQAConfig(
+                   connection_name="default",
+                   url=config.DATABASE_URL,
+               )
+           ),
+           # Other interceptors...
+       ]
+   )
+   ```
+
+2. **Execution**
+
+   - When a request/message/job starts, interceptors are activated
+   - Each interceptor sets up its context using `ContextVar`
+   - The context is available throughout the execution
+
+3. **Cleanup**
+   - When execution completes, interceptors clean up resources
+   - Context is automatically reset
+   - Resources are properly closed/released
+
+### Available Context Hooks
+
+1. **Database Sessions** (`use_session`)
+
+   - Provided by `AIOSqlAlchemySessionInterceptor`
+   - Creates isolated database sessions per execution
+   - Handles transaction management automatically
+
+2. **Message Publishing** (`use_publisher`)
+
+   - Provided by `MessageBusPublisherInterceptor`
+   - Manages message publishing context
+   - Ensures proper message delivery
+
+3. **WebSocket Management** (`use_ws_manager`)
+   - Provided by `WebSocketInterceptor`
+   - Handles WebSocket connections and broadcasting
+   - Manages connection state
+
+### Usage in Different Contexts
+
+```python
+# In a REST Controller
+@RestController("/tasks")
+@MessageBusController()
+class TasksController:
+    @Get("/")
+    async def get_tasks(self):
+        # Gets a session specific to this HTTP request
+        session = use_session()
+        return await session.execute(select(TaskEntity))
+
+
+    @MessageHandler(SomeTask)
+    async def process_task(self, message: MessageOf[SomeTask]):
+        # Gets a session specific to this message processing
+        session = use_session()
+
+    # In a Scheduled Job
+    @ScheduledAction("* * * * *")
+    async def scheduled_task(self):
+        # Gets a session specific to this job execution
+        session = use_session()
+        await session.execute(select(TaskEntity))
+```
+
+This system ensures that:
+
+- Each execution has its own isolated resources
+- Resources are properly managed and cleaned up
+- The same utilities can be used consistently across different runtime contexts
+- Dependencies are properly injected and managed