eventable 0.1.0__tar.gz

eventable-0.1.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.3
+Name: eventable
+Version: 0.1.0
+Summary: Domain Event Message Infrastructure
+Author: Ioannis-Andreas Philippas
+Author-email: Ioannis-Andreas Philippas <ioannis.philippas@entaxilabs.gr>
+Requires-Dist: fastapi>=0.135.3
+Requires-Dist: pika>=1.3.2
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: ruff>=0.15.9
+Requires-Dist: starlette>=1.0.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# eventable
+
+Domain event infrastructure for Python microservices.
+
+Provides the building blocks to implement **domain events** following Domain-Driven Design: aggregate roots that collect events, an in-process dispatcher, and a RabbitMQ transport — with an optional plug-and-play FastAPI integration.
+
+---
+
+## Features
+
+- Frozen, serializable `DomainEvent` dataclasses
+- `AggregateRoot` (Pydantic) that accumulates and releases domain events
+- `EventDispatcher` — runs in-process handlers first, then publishes to the broker
+- RabbitMQ publisher & subscriber backed by a durable topic exchange
+- **FastAPI plugin**: one-line lifespan setup + pure-ASGI middleware that dispatches events after every successful request without swallowing exceptions
+
+---
+
+## Installation
+
+```bash
+pip install eventable
+# or with uv
+uv add eventable
+```
+
+**Requirements:** Python 3.12+, a running RabbitMQ broker (for the infrastructure layer).
+
+---
+
+## Core concepts
+
+```
+Request
+  └─ AggregateRoot.add_domain_event(event)   # collect during business logic
+       └─ EventCollector.collect_events()     # pull after request completes
+            └─ EventDispatcher.dispatch(event)
+                 ├─ in-process handlers       # same bounded context
+                 └─ RabbitMQPublisher         # cross-context via broker
+```
+
+---
+
+## Quick start
+
+### 1. Define a domain event
+
+```python
+from dataclasses import dataclass
+from uuid import UUID
+from eventable.domain_event import DomainEvent
+
+@dataclass(frozen=True)
+class OrderPlaced(DomainEvent):
+    order_id: UUID
+    total: str
+```
+
+### 2. Define an aggregate root
+
+```python
+from uuid import uuid4
+from datetime import datetime
+from eventable.aggregate_root import AggregateRoot
+from eventable.domain_event import generate_event_id
+
+class Order(AggregateRoot):
+    order_id: UUID
+    total: str
+
+    def place(self) -> None:
+        self.add_domain_event(
+            OrderPlaced(
+                event_id=generate_event_id(),
+                occurred_at=datetime.now(),
+                order_id=self.order_id,
+                total=self.total,
+            )
+        )
+```
+
+### 3. Register in-process handlers
+
+Edit `event_handlers.py` (generated alongside your app):
+
+```python
+from eventable.event_managment.event_dispatcher import EventDispatcher
+from myapp.events import OrderPlaced
+
+def handle_order_placed(event: OrderPlaced) -> None:
+    print(f"Order {event.order_id} placed — sending confirmation email")
+
+def register_handlers(dispatcher: EventDispatcher) -> None:
+    dispatcher.register(OrderPlaced, handle_order_placed)
+```
+
+---
+
+## FastAPI integration
+
+### Lifespan setup
+
+`Eventable` connects to RabbitMQ on startup, registers your in-process handlers, and disconnects cleanly on shutdown. Wire it into FastAPI's async lifespan:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from eventable.infrastructure.fastapi.eventable import Eventable, EventableSettings
+from eventable.infrastructure.fastapi.middleware import DomainEventMiddleware
+
+settings = EventableSettings(
+    rabbit_url="amqp://guest:guest@localhost/",
+    exchange_name="domain_events",   # default
+)
+eventable = Eventable(settings)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await eventable.startup(app)   # connects publisher, wires dispatcher
+    yield
+    await eventable.shutdown()     # closes RabbitMQ connection
+
+app = FastAPI(lifespan=lifespan)
+app.add_middleware(DomainEventMiddleware)
+```
+
+After startup, `app.state.publisher` and `app.state.dispatcher` are available throughout the application.
+
+### Middleware
+
+`DomainEventMiddleware` is a **pure ASGI middleware** (not `BaseHTTPMiddleware`) so exceptions from your route handlers propagate cleanly to FastAPI's exception handlers — nothing is swallowed.
+
+Per-request lifecycle:
+
+1. Attaches a fresh `EventCollector` to `request.state.collector`.
+2. Runs the route handler normally.
+3. After the response is sent, if the status code is **< 400**, pulls all collected events and dispatches them.
+4. On 4xx/5xx the collector is discarded — no events are dispatched for failed requests.
+
+### Collecting events in a route
+
+```python
+from fastapi import Request
+from eventable.event_managment.event_collector import EventCollector
+
+@app.post("/orders")
+def place_order(request: Request):
+    collector: EventCollector = request.state.collector
+
+    order = Order(order_id=uuid4(), total="99.99")
+    collector.track(order)   # middleware will pull events from this aggregate
+    order.place()
+
+    return {"order_id": str(order.order_id)}
+```
+
+---
+
+## RabbitMQ subscriber (cross-context consumer)
+
+Run a long-lived consumer process in a separate service to handle events published by another bounded context:
+
+```python
+from eventable import rabbit_subscription
+from myapp.events import OrderPlaced
+
+def handle_order_placed(event: OrderPlaced) -> None:
+    # react to the event in this bounded context
+    ...
+
+rabbit_subscription(
+    consumer_name="inventory-service",
+    rabbit_url="amqp://guest:guest@localhost/",
+    queue_name="inventory.order_placed",
+    handlers_map={
+        OrderPlaced: (handle_order_placed, {}),
+    },
+)
+```
+
+`rabbit_subscription` blocks, handles `SIGTERM`/`SIGINT` for graceful shutdown, and nacks messages that fail processing (sending them to the dead-letter queue if configured).
+
+---
+
+## Event serialization
+
+Events are serialized to JSON automatically. The following field types are supported out of the box:
+
+| Python type | JSON representation |
+|---|---|
+| `UUID` | `string` |
+| `datetime` | ISO 8601 string |
+| `Decimal` | `string` |
+| `ValueObject` | `get_value()` result |
+| `dict`, `list` | passed through recursively |
+
+### ValueObject
+
+Implement the `ValueObject` protocol to have your value objects serialize transparently:
+
+```python
+from eventable.value_object import ValueObject
+
+class Money:
+    def __init__(self, amount: str):
+        self.value = amount
+
+    def get_value(self) -> str:
+        return self.value
+```
+
+---
+
+## Architecture overview
+
+```
+eventable/
+├── domain_event.py          # DomainEvent base dataclass + serialize/deserialize
+├── aggregate_root.py        # AggregateRoot (Pydantic BaseModel)
+├── value_object.py          # ValueObject protocol
+├── event_handlers.py        # register_handlers() — your in-process handler hook
+│
+├── event_managment/
+│   ├── event_collector.py   # Tracks aggregates, pulls events after request
+│   ├── event_dispatcher.py  # Runs handlers then publishes to broker
+│   ├── event_publisher.py   # Abstract EventPublisher
+│   └── event_subscriber.py  # Abstract EventSubscriber
+│
+└── infrastructure/
+    ├── rabbitmq/
+    │   ├── event_publisher.py   # RabbitMQPublisher (thread-local channels)
+    │   └── event_subscriber.py  # RabbitMQSubscriber (blocking consumer)
+    └── fastapi/
+        ├── eventable.py         # Eventable + EventableSettings (lifespan plugin)
+        └── middleware.py        # DomainEventMiddleware (pure ASGI)
+```
+
+**RabbitMQ topology:** a single durable **topic exchange** (`domain_events` by default). Each event type is routed by its class name as the routing key. Consumers bind a durable queue to the exchange for the routing keys they care about.
+
+---
+
+## Configuration reference
+
+### `EventableSettings`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `rabbit_url` | `str` | — | AMQP connection URL |
+| `exchange_name` | `str` | `"domain_events"` | Topic exchange name |
+
+---
+
+## Running the tests
+
+```bash
+uv run pytest tests/unit/          # pure unit tests, no broker needed
+uv run pytest tests/infrastructure/ -k "not rabbitmq"  # FastAPI plugin tests only
+
+# Full suite including RabbitMQ integration tests:
+RABBITMQ_URL=amqp://admin:admin@localhost:5672/ uv run pytest
+```
+
+---
+
+## License
+
+MIT

eventable-0.1.0/README.md

@@ -0,0 +1,267 @@
+# eventable
+
+Domain event infrastructure for Python microservices.
+
+Provides the building blocks to implement **domain events** following Domain-Driven Design: aggregate roots that collect events, an in-process dispatcher, and a RabbitMQ transport — with an optional plug-and-play FastAPI integration.
+
+---
+
+## Features
+
+- Frozen, serializable `DomainEvent` dataclasses
+- `AggregateRoot` (Pydantic) that accumulates and releases domain events
+- `EventDispatcher` — runs in-process handlers first, then publishes to the broker
+- RabbitMQ publisher & subscriber backed by a durable topic exchange
+- **FastAPI plugin**: one-line lifespan setup + pure-ASGI middleware that dispatches events after every successful request without swallowing exceptions
+
+---
+
+## Installation
+
+```bash
+pip install eventable
+# or with uv
+uv add eventable
+```
+
+**Requirements:** Python 3.12+, a running RabbitMQ broker (for the infrastructure layer).
+
+---
+
+## Core concepts
+
+```
+Request
+  └─ AggregateRoot.add_domain_event(event)   # collect during business logic
+       └─ EventCollector.collect_events()     # pull after request completes
+            └─ EventDispatcher.dispatch(event)
+                 ├─ in-process handlers       # same bounded context
+                 └─ RabbitMQPublisher         # cross-context via broker
+```
+
+---
+
+## Quick start
+
+### 1. Define a domain event
+
+```python
+from dataclasses import dataclass
+from uuid import UUID
+from eventable.domain_event import DomainEvent
+
+@dataclass(frozen=True)
+class OrderPlaced(DomainEvent):
+    order_id: UUID
+    total: str
+```
+
+### 2. Define an aggregate root
+
+```python
+from uuid import uuid4
+from datetime import datetime
+from eventable.aggregate_root import AggregateRoot
+from eventable.domain_event import generate_event_id
+
+class Order(AggregateRoot):
+    order_id: UUID
+    total: str
+
+    def place(self) -> None:
+        self.add_domain_event(
+            OrderPlaced(
+                event_id=generate_event_id(),
+                occurred_at=datetime.now(),
+                order_id=self.order_id,
+                total=self.total,
+            )
+        )
+```
+
+### 3. Register in-process handlers
+
+Edit `event_handlers.py` (generated alongside your app):
+
+```python
+from eventable.event_managment.event_dispatcher import EventDispatcher
+from myapp.events import OrderPlaced
+
+def handle_order_placed(event: OrderPlaced) -> None:
+    print(f"Order {event.order_id} placed — sending confirmation email")
+
+def register_handlers(dispatcher: EventDispatcher) -> None:
+    dispatcher.register(OrderPlaced, handle_order_placed)
+```
+
+---
+
+## FastAPI integration
+
+### Lifespan setup
+
+`Eventable` connects to RabbitMQ on startup, registers your in-process handlers, and disconnects cleanly on shutdown. Wire it into FastAPI's async lifespan:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from eventable.infrastructure.fastapi.eventable import Eventable, EventableSettings
+from eventable.infrastructure.fastapi.middleware import DomainEventMiddleware
+
+settings = EventableSettings(
+    rabbit_url="amqp://guest:guest@localhost/",
+    exchange_name="domain_events",   # default
+)
+eventable = Eventable(settings)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await eventable.startup(app)   # connects publisher, wires dispatcher
+    yield
+    await eventable.shutdown()     # closes RabbitMQ connection
+
+app = FastAPI(lifespan=lifespan)
+app.add_middleware(DomainEventMiddleware)
+```
+
+After startup, `app.state.publisher` and `app.state.dispatcher` are available throughout the application.
+
+### Middleware
+
+`DomainEventMiddleware` is a **pure ASGI middleware** (not `BaseHTTPMiddleware`) so exceptions from your route handlers propagate cleanly to FastAPI's exception handlers — nothing is swallowed.
+
+Per-request lifecycle:
+
+1. Attaches a fresh `EventCollector` to `request.state.collector`.
+2. Runs the route handler normally.
+3. After the response is sent, if the status code is **< 400**, pulls all collected events and dispatches them.
+4. On 4xx/5xx the collector is discarded — no events are dispatched for failed requests.
+
+### Collecting events in a route
+
+```python
+from fastapi import Request
+from eventable.event_managment.event_collector import EventCollector
+
+@app.post("/orders")
+def place_order(request: Request):
+    collector: EventCollector = request.state.collector
+
+    order = Order(order_id=uuid4(), total="99.99")
+    collector.track(order)   # middleware will pull events from this aggregate
+    order.place()
+
+    return {"order_id": str(order.order_id)}
+```
+
+---
+
+## RabbitMQ subscriber (cross-context consumer)
+
+Run a long-lived consumer process in a separate service to handle events published by another bounded context:
+
+```python
+from eventable import rabbit_subscription
+from myapp.events import OrderPlaced
+
+def handle_order_placed(event: OrderPlaced) -> None:
+    # react to the event in this bounded context
+    ...
+
+rabbit_subscription(
+    consumer_name="inventory-service",
+    rabbit_url="amqp://guest:guest@localhost/",
+    queue_name="inventory.order_placed",
+    handlers_map={
+        OrderPlaced: (handle_order_placed, {}),
+    },
+)
+```
+
+`rabbit_subscription` blocks, handles `SIGTERM`/`SIGINT` for graceful shutdown, and nacks messages that fail processing (sending them to the dead-letter queue if configured).
+
+---
+
+## Event serialization
+
+Events are serialized to JSON automatically. The following field types are supported out of the box:
+
+| Python type | JSON representation |
+|---|---|
+| `UUID` | `string` |
+| `datetime` | ISO 8601 string |
+| `Decimal` | `string` |
+| `ValueObject` | `get_value()` result |
+| `dict`, `list` | passed through recursively |
+
+### ValueObject
+
+Implement the `ValueObject` protocol to have your value objects serialize transparently:
+
+```python
+from eventable.value_object import ValueObject
+
+class Money:
+    def __init__(self, amount: str):
+        self.value = amount
+
+    def get_value(self) -> str:
+        return self.value
+```
+
+---
+
+## Architecture overview
+
+```
+eventable/
+├── domain_event.py          # DomainEvent base dataclass + serialize/deserialize
+├── aggregate_root.py        # AggregateRoot (Pydantic BaseModel)
+├── value_object.py          # ValueObject protocol
+├── event_handlers.py        # register_handlers() — your in-process handler hook
+│
+├── event_managment/
+│   ├── event_collector.py   # Tracks aggregates, pulls events after request
+│   ├── event_dispatcher.py  # Runs handlers then publishes to broker
+│   ├── event_publisher.py   # Abstract EventPublisher
+│   └── event_subscriber.py  # Abstract EventSubscriber
+│
+└── infrastructure/
+    ├── rabbitmq/
+    │   ├── event_publisher.py   # RabbitMQPublisher (thread-local channels)
+    │   └── event_subscriber.py  # RabbitMQSubscriber (blocking consumer)
+    └── fastapi/
+        ├── eventable.py         # Eventable + EventableSettings (lifespan plugin)
+        └── middleware.py        # DomainEventMiddleware (pure ASGI)
+```
+
+**RabbitMQ topology:** a single durable **topic exchange** (`domain_events` by default). Each event type is routed by its class name as the routing key. Consumers bind a durable queue to the exchange for the routing keys they care about.
+
+---
+
+## Configuration reference
+
+### `EventableSettings`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `rabbit_url` | `str` | — | AMQP connection URL |
+| `exchange_name` | `str` | `"domain_events"` | Topic exchange name |
+
+---
+
+## Running the tests
+
+```bash
+uv run pytest tests/unit/          # pure unit tests, no broker needed
+uv run pytest tests/infrastructure/ -k "not rabbitmq"  # FastAPI plugin tests only
+
+# Full suite including RabbitMQ integration tests:
+RABBITMQ_URL=amqp://admin:admin@localhost:5672/ uv run pytest
+```
+
+---
+
+## License
+
+MIT

eventable-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "eventable"
+version = "0.1.0"
+description = "Domain Event Message Infrastructure"
+readme = "README.md"
+authors = [
+  { name = "Ioannis-Andreas Philippas", email = "ioannis.philippas@entaxilabs.gr" },
+]
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.135.3",
+    "pika>=1.3.2",
+    "pydantic>=2.12.5",
+    "ruff>=0.15.9",
+    "starlette>=1.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+#[tool.pyright]
+#include = ["src"]
+#venvPath = "."
+#venv = ".venv"
+
+
+[tool.ruff]
+# Ignore missing docstring warnings (D1xx rules)
+# F401: imported but unused (common with pytest fixtures)
+# F811: redefinition of unused (common with pytest fixtures)
+lint.ignore = ["D1", "F841", "PT019", "F401", "F811"]
+src = ["src"]
+line-length = 110
+indent-width = 4
+exclude = [
+  ".venv",
+  ".vscode",
+  "__pypackages__",
+  "node_modules",
+  "site-packages",
+  "venv",
+]
+
+[dependency-groups]
+dev = [
+    "pika-stubs>=0.1.3",
+    "pytest>=9.0.2",
+]

eventable-0.1.0/src/eventable/__init__.py

@@ -0,0 +1,41 @@
+import logging
+import signal
+from typing import Any, Callable
+
+from eventable.domain_event import DomainEvent
+from eventable.infrastructure.rabbitmq.event_publisher import RabbitMQPublisher
+from eventable.infrastructure.rabbitmq.event_subscriber import RabbitMQSubscriber
+
+
+logger = logging.getLogger(__name__)
+
+
+def rabbit_subscription(
+    consumer_name: str,
+    rabbit_url: str,
+    queue_name: str,
+    handlers_map: dict[type[DomainEvent], tuple[Callable, dict[str, Any]]],
+) -> None:
+    publisher = RabbitMQPublisher(
+        url=rabbit_url,
+    )
+    # event_collector = EventCollector()
+    publisher.connect()
+
+    subscriber = RabbitMQSubscriber(
+        url=rabbit_url,
+        queue_name=queue_name,  # unique per bounded context
+        publisher=publisher,
+    )
+
+    # Register handlers for this service:
+    # subscriber.subscribe(OrderPlaced, handle_order_placed)
+    for event_name, (handler, kwargs) in handlers_map.items():
+        subscriber.subscribe(event_name, handler, **kwargs)
+
+    # Graceful shutdown
+    signal.signal(signal.SIGTERM, lambda s, f: subscriber.stop())
+    signal.signal(signal.SIGINT, lambda s, f: subscriber.stop())
+
+    logger.info(f"{consumer_name} Consumer starting...")
+    subscriber.start()  #

eventable-0.1.0/src/eventable/aggregate_root.py

@@ -0,0 +1,16 @@
+from pydantic import BaseModel
+
+from eventable.domain_event import DomainEvent
+
+
+class AggregateRoot(BaseModel):
+    _domain_events: list[DomainEvent] = []  # private, excluded from serialization
+    model_config = {"arbitrary_types_allowed": True}
+
+    def add_domain_event(self, event: DomainEvent):
+        self._domain_events.append(event)
+
+    def pull_domain_events(self) -> list[DomainEvent]:
+        events = self._domain_events.copy()
+        self._domain_events.clear()
+        return events

eventable-0.1.0/src/eventable/domain_event.py

@@ -0,0 +1,61 @@
+from dataclasses import asdict, dataclass, fields, is_dataclass
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Type
+from uuid import UUID, uuid4
+
+from eventable.value_object import ValueObject
+
+
+@dataclass(frozen=True)
+class DomainEvent:
+    event_id: UUID
+    occurred_at: datetime
+
+
+def generate_event_id() -> UUID:
+    return uuid4()
+
+
+def _convert(obj: Any) -> Any:
+    """Recursively convert non-JSON-serializable types."""
+    if isinstance(obj, UUID):
+        return str(obj)
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, Decimal):
+        return str(obj)
+    if isinstance(obj, dict):
+        return {k: _convert(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_convert(i) for i in obj]
+    if isinstance(obj, ValueObject):
+        return obj.get_value()
+    return obj
+
+
+def serialize(event: Any) -> dict:
+    if is_dataclass(event) and not isinstance(event, type):
+        return _convert(asdict(event))  # 👈 pass through converter
+    raise TypeError(f"Cannot serialize event of type {type(event)}")
+
+
+def deserialize(payload: dict, event_type: Type) -> Any:
+    if not is_dataclass(event_type):
+        raise TypeError(f"{event_type} is not a dataclass")
+
+    kwargs = {}
+    type_hints = {f.name: f.type for f in fields(event_type)}
+
+    for field_name, field_type in type_hints.items():
+        if field_name not in payload:
+            continue
+        value = payload[field_name]
+        if field_type in (UUID, "UUID"):
+            kwargs[field_name] = UUID(value)
+        elif field_type in (datetime, "datetime"):
+            kwargs[field_name] = datetime.fromisoformat(value)
+        else:
+            kwargs[field_name] = value
+
+    return event_type(**kwargs)

eventable-0.1.0/src/eventable/event_handlers.py

@@ -0,0 +1,8 @@
+from eventable.event_managment.event_dispatcher import EventDispatcher
+
+
+def register_handlers(dispatcher: EventDispatcher) -> None:
+    # Same bounded context handlers — register here:
+    # dispatcher.register(OrderPlaced, handle_order_placed_internally)
+    # dispatcher.register(PatientAdmited, handle_patient_admited)
+    ...

eventable-0.1.0/src/eventable/event_managment/event_collector.py

@@ -0,0 +1,16 @@
+from eventable.aggregate_root import AggregateRoot
+from eventable.domain_event import DomainEvent
+
+
+class EventCollector:
+    def __init__(self):
+        self._aggregates: list[AggregateRoot] = []
+
+    def track(self, aggregate: AggregateRoot) -> None:
+        self._aggregates.append(aggregate)
+
+    def collect_events(self) -> list[DomainEvent]:
+        events = []
+        for aggregate in self._aggregates:
+            events.extend(aggregate.pull_domain_events())
+        return events

eventable-0.1.0/src/eventable/event_managment/event_dispatcher.py

@@ -0,0 +1,38 @@
+import logging
+from typing import Callable, Type
+
+from eventable.domain_event import DomainEvent
+from eventable.event_managment.event_publisher import EventPublisher
+
+
+logger = logging.getLogger(__name__)
+
+
+class EventDispatcher:
+    def __init__(self, publisher: EventPublisher):
+        self._publisher = publisher
+        self._handlers: dict[Type[DomainEvent], list[Callable]] = {}
+
+    def register(self, event_type: Type[DomainEvent], handler: Callable) -> None:
+        self._handlers.setdefault(event_type, []).append(handler)
+        logger.debug(
+            f"Registered handler '{handler.__name__}' for '{event_type.__name__}'"
+        )
+
+    def dispatch(self, event: DomainEvent) -> None:
+        event_type = type(event)
+
+        # 1. Same-context in-process handlers
+        for handler in self._handlers.get(event_type, []):
+            try:
+                handler(event)
+            except Exception:
+                logger.exception(
+                    f"In-process handler '{handler.__name__}' failed for '{event_type.__name__}'"
+                )
+
+        # 2. Cross-context via broker
+        try:
+            self._publisher.publish(event)
+        except Exception:
+            logger.exception(f"Failed to publish '{event_type.__name__}' to broker")

eventable-0.1.0/src/eventable/event_managment/event_publisher.py

@@ -0,0 +1,17 @@
+import abc
+
+from eventable.domain_event import DomainEvent
+
+
+class EventPublisher(abc.ABC):
+    @abc.abstractmethod
+    def publish(self, event: DomainEvent) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def connect(self) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def disconnect(self) -> None:
+        raise NotImplementedError

eventable-0.1.0/src/eventable/event_managment/event_subscriber.py

@@ -0,0 +1,19 @@
+import abc
+from typing import Callable, Type
+
+from eventable.domain_event import DomainEvent
+
+
+class EventSubscriber(abc.ABC):
+    @abc.abstractmethod
+    def subscribe(
+        self,
+        event_type: Type[DomainEvent],
+        handler: Callable,
+    ) -> None: ...
+
+    @abc.abstractmethod
+    def start(self) -> None: ...
+
+    @abc.abstractmethod
+    def stop(self) -> None: ...

eventable-0.1.0/src/eventable/infrastructure/fastapi/eventable.py

@@ -0,0 +1,41 @@
+from contextlib import asynccontextmanager
+import logging
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+from eventable.event_handlers import register_handlers
+from eventable.event_managment.event_dispatcher import EventDispatcher
+from eventable.infrastructure.rabbitmq.event_publisher import RabbitMQPublisher
+
+logger = logging.getLogger(__name__)
+
+
+class EventableSettings(BaseModel):
+    rabbit_url: str
+    exchange_name: str = "domain_events"
+
+
+class Eventable:
+    def __init__(self, settings: EventableSettings) -> None:
+        self.settings = settings
+        self.publisher: RabbitMQPublisher | None = None
+
+    async def startup(self, app: FastAPI):
+        self.publisher = RabbitMQPublisher(
+            url=self.settings.rabbit_url,
+            exchange_name=self.settings.exchange_name,
+        )
+        try:
+            self.publisher.connect()
+        except Exception:
+            logger.warning("RabbitMQ unavailable at startup — will retry on first publish")
+
+        dispatcher = EventDispatcher(self.publisher)
+        register_handlers(dispatcher)
+
+        app.state.publisher = self.publisher
+        app.state.dispatcher = dispatcher
+
+    async def shutdown(self):
+        if self.publisher:
+            self.publisher.disconnect()

eventable-0.1.0/src/eventable/infrastructure/fastapi/middleware.py

@@ -0,0 +1,55 @@
+# ============================================================
+# STEP 10 — infrastructure/messaging/middleware.py
+# Attaches a fresh EventCollector to every request.
+# After the response is built, pulls all collected events
+# from tracked aggregates and dispatches them.
+# Registered in main.py via app.add_middleware().
+# ============================================================
+import logging
+
+from eventable.event_managment.event_collector import EventCollector
+from eventable.event_managment.event_dispatcher import EventDispatcher
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+
+logger = logging.getLogger(__name__)
+
+
+class DomainEventMiddleware:
+    """
+    Pure ASGI middleware — avoids BaseHTTPMiddleware's exception swallowing.
+    Exceptions propagate cleanly to FastAPI's exception handlers.
+    """
+
+    def __init__(self, app: ASGIApp):
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send):
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        from starlette.requests import Request
+
+        request = Request(scope, receive, send)
+        request.state.collector = EventCollector()
+
+        # Track response status to avoid dispatching on errors
+        status_code = 500
+
+        async def send_wrapper(message):
+            nonlocal status_code
+            if message["type"] == "http.response.start":
+                status_code = message["status"]
+            await send(message)
+
+        # Let exceptions propagate naturally — no wrapping
+        await self.app(scope, receive, send_wrapper)
+
+        if status_code < 400:
+            dispatcher: EventDispatcher = scope["app"].state.dispatcher
+            for event in request.state.collector.collect_events():
+                try:
+                    dispatcher.dispatch(event)
+                except Exception:
+                    logger.exception(f"Failed to dispatch '{type(event).__name__}'")

eventable-0.1.0/src/eventable/infrastructure/rabbitmq/event_publisher.py

@@ -0,0 +1,70 @@
+from datetime import datetime, timezone
+import logging
+import json
+import threading
+
+import pika
+from pika.exchange_type import ExchangeType
+from pika import DeliveryMode
+
+from eventable.domain_event import DomainEvent, serialize
+from eventable.event_managment.event_publisher import EventPublisher
+
+logger = logging.getLogger(__name__)
+
+
+class RabbitMQPublisher(EventPublisher):
+    def __init__(self, url: str, exchange_name: str = "domain_events"):
+        self._url = url
+        self._exchange_name = exchange_name
+        self._local = threading.local()
+
+    def connect(self) -> None:
+        self._get_channel()
+        logger.info("RabbitMQ publisher connected")
+
+    def disconnect(self) -> None:
+        conn = getattr(self._local, "connection", None)
+        if conn and not conn.is_closed:
+            conn.close()
+            logger.info("RabbitMQ publisher disconnected")
+
+    def publish(self, event: DomainEvent) -> None:
+        channel = self._get_channel()
+        routing_key = type(event).__name__
+
+        payload = {
+            "event_type": routing_key,
+            "occurred_at": datetime.now(timezone.utc).isoformat(),
+            "payload": serialize(event),
+        }
+
+        channel.basic_publish(
+            exchange=self._exchange_name,
+            routing_key=routing_key,
+            body=json.dumps(payload).encode(),
+            properties=pika.BasicProperties(
+                content_type="application/json",
+                delivery_mode=DeliveryMode.Persistent,
+            ),
+        )
+        logger.debug(f"Published: {routing_key}")
+
+    def _get_channel(self):
+        conn = getattr(self._local, "connection", None)
+        chan = getattr(self._local, "channel", None)
+
+        if not conn or conn.is_closed or not chan or not chan.is_open:
+            params = pika.URLParameters(self._url)
+            params.heartbeat = 60
+            params.blocked_connection_timeout = 300
+            self._local.connection = pika.BlockingConnection(params)
+            self._local.channel = self._local.connection.channel()
+            self._local.channel.exchange_declare(
+                exchange=self._exchange_name,
+                exchange_type=ExchangeType.topic,
+                durable=True,
+            )
+            logger.info(f"RabbitMQ channel opened on thread: {threading.current_thread().name}")
+
+        return self._local.channel

eventable-0.1.0/src/eventable/infrastructure/rabbitmq/event_subscriber.py

@@ -0,0 +1,109 @@
+import json
+import logging
+from typing import Callable, Type
+from functools import partial
+
+import pika
+from pika.exchange_type import ExchangeType
+
+from eventable.domain_event import DomainEvent, deserialize
+from eventable.event_managment.event_publisher import EventPublisher
+from eventable.event_managment.event_subscriber import EventSubscriber
+
+
+logger = logging.getLogger(__name__)
+
+# Internal registry entry — keeps handler and its UoW class together
+type HandlerEntry = tuple[Type[DomainEvent], Callable]
+
+
+class RabbitMQSubscriber(EventSubscriber):
+    def __init__(
+        self,
+        url: str,
+        queue_name: str,
+        publisher: EventPublisher,
+        exchange_name: str = "domain_events",
+    ):
+        self._url = url
+        self._queue_name = queue_name
+        self._publisher = publisher
+        self._exchange_name = exchange_name
+        self._handlers: dict[str, HandlerEntry] = {}
+        self._connection: pika.BlockingConnection | None = None
+        self._channel = None
+
+    def subscribe(self, event_type: Type[DomainEvent], handler: Callable, **kwargs) -> None:
+        routing_key = event_type.__name__
+
+        handler_name = handler.__name__
+        if kwargs:
+            handler = partial(handler, **kwargs)
+
+        self._handlers[routing_key] = (event_type, handler)
+        logger.debug(f"Subscribed '{handler_name}' to '{routing_key}'")
+
+    def start(self) -> None:
+        self._connect()
+        logger.info(f"Consumer listening on queue: '{self._queue_name}'")
+        if not self._channel:
+            raise
+        self._channel.start_consuming()
+
+    def stop(self) -> None:
+        if self._channel and self._channel.is_open:
+            self._channel.stop_consuming()
+        if self._connection and not self._connection.is_closed:
+            self._connection.close()
+        logger.info("RabbitMQ subscriber stopped")
+
+    def _connect(self):
+        params = pika.URLParameters(self._url)
+        params.heartbeat = 60
+        params.blocked_connection_timeout = 300
+
+        self._connection = pika.BlockingConnection(params)
+        self._channel = self._connection.channel()
+
+        self._channel.exchange_declare(
+            exchange=self._exchange_name,
+            exchange_type=ExchangeType.topic,
+            durable=True,
+        )
+        self._channel.queue_declare(queue=self._queue_name, durable=True)
+
+        for routing_key in self._handlers:
+            self._channel.queue_bind(
+                queue=self._queue_name,
+                exchange=self._exchange_name,
+                routing_key=routing_key,
+            )
+            logger.info(f"Bound '{self._queue_name}' → '{routing_key}'")
+
+        self._channel.basic_qos(prefetch_count=1)
+        self._channel.basic_consume(
+            queue=self._queue_name,
+            on_message_callback=self._on_message,
+        )
+
+    def _on_message(self, channel, method, properties, body: bytes):
+        routing_key = method.routing_key
+
+        if routing_key not in self._handlers:
+            logger.warning(f"No handler for routing key: '{routing_key}'")
+            channel.basic_nack(method.delivery_tag, requeue=False)
+            return
+
+        event_type, handler = self._handlers[routing_key]  # 👈 unpack uow_class
+
+        try:
+            raw = json.loads(body)
+            event = deserialize(raw["payload"], event_type)
+
+            handler(event)
+
+            channel.basic_ack(method.delivery_tag)
+
+        except Exception:
+            logger.exception(f"Handler failed for '{routing_key}' — nacking to DLQ")
+            channel.basic_nack(method.delivery_tag, requeue=False)

eventable-0.1.0/src/eventable/value_object.py

@@ -0,0 +1,10 @@
+from typing import Generic, Protocol, TypeVar, runtime_checkable
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class ValueObject(Protocol, Generic[T]):
+    value: T
+
+    def get_value(self) -> T: ...