hexastack-events 0.0.0__tar.gz

hexastack_events-0.0.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.3
+Name: hexastack-events
+Version: 0.0.0
+Summary: CloudEvents serialization, Transactional Outbox pattern, and distributed event streaming for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: cloudevents>=1.11.0
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: huey>=3.3.4 ; extra == 'huey'
+Requires-Dist: sqlalchemy>=2.0.0 ; extra == 'sql'
+Requires-Python: >=3.13
+Provides-Extra: huey
+Provides-Extra: sql
+Description-Content-Type: text/markdown
+
+# hexastack-events
+
+**CNCF CloudEvents 1.0 serialization, Transactional Outbox pattern, and distributed event streaming for Hexastack.**
+
+Part of the [Hexastack Framework](https://github.com/TheTrueSCU/hexastack).
+
+---
+
+## 1. Architectural Overview
+
+`hexastack-events` extends Hexastack's in-process CQRS buses with enterprise distributed event streaming and reliability patterns:
+
+1. **CNCF CloudEvents 1.0 Protocol**: Automatic serialization and deserialization of domain `Event` models into standardized CloudEvents JSON envelopes with W3C correlation ID and multi-tenant partitioning.
+2. **Transactional Outbox Engine (Gap 6)**: Guarantees at-least-once delivery by staging uncommitted domain events in an `OutboxStoragePort` within the same transaction as business state mutations.
+3. **Dual Relay Engines**:
+   - **Native Asyncio (`AsyncioOutboxRelay`)**: In-process background task running with zero external dependencies.
+   - **Huey Worker (`HueyOutboxRelay`)**: Multi-process worker executing outbox polling in separate worker nodes (`pip install hexastack-events[huey]`).
+4. **Relational Database Outbox Storage (`SqlAlchemyOutboxStorage`)**: Pluggable storage adapter supporting SQLAlchemy tables and transactions (`pip install hexastack-events[sql]`).
+5. **Distributed Event Bus ([`DistributedEventBusPort`](file:///home/rjdw/Projects/hexastack/packages/hexastack_events/src/hexastack_events/ports/buses.py))**: Standardized cross-service messaging interface for Redis, NATS, Kafka, and in-memory brokers.
+
+```mermaid
+graph TD
+    CMD["CQRS Command Handler"]
+    UOW["Unit of Work Transaction"]
+    OUTBOX_MW["OutboxCaptureMiddleware"]
+    OUTBOX_STORE["OutboxStoragePort\n(SQLAlchemy / DB Outbox Table)"]
+    RELAY["OutboxRelayPort\n(Asyncio / Huey Worker)"]
+    BUS["DistributedEventBusPort\n(Redis / NATS / Kafka)"]
+
+    CMD --> UOW
+    CMD --> OUTBOX_MW
+    OUTBOX_MW -->|Stages Record| OUTBOX_STORE
+    UOW -->|Atomic Commit| OUTBOX_STORE
+    RELAY -->|Polls Pending| OUTBOX_STORE
+    RELAY -->|Publishes CloudEvent| BUS
+```
+
+---
+
+## 2. Key Exports & Package Structure
+
+```
+hexastack_events/
+├── domain/          # EventContext, OutboxRecord, OutboxStatus, CloudEventEnvelope, EventError
+├── ports/           # OutboxStoragePort, OutboxRelayPort, DistributedEventBusPort
+├── adapters/
+│   ├── cloudevents/ # to_cloudevent, from_cloudevent, cloudevent_to_json/dict
+│   ├── outbox/      # AsyncioOutboxRelay, HueyOutboxRelay, InMemoryOutboxStorage, SqlAlchemyOutboxStorage
+│   └── buses/       # InMemoryDistributedEventBus
+└── infra/           # EventsBootstrapper (order=22), HexastackEventsConfig, OutboxCaptureMiddleware
+```
+
+---
+
+## 3. Quickstart & Installation
+
+```bash
+# Core CloudEvents & Asyncio Outbox Relay (zero extra dependencies)
+pip install hexastack-events
+
+# With SQLAlchemy relational database outbox storage
+pip install "hexastack-events[sql]"
+
+# With Huey multi-process worker support
+pip install "hexastack-events[huey]"
+```
+
+### Configuration (`hexastack.toml` or `pyproject.toml`)
+
+```toml
+[hexastack.events]
+source = "billing-service"
+relay_mode = "asyncio" # "asyncio", "huey", "manual", "disabled"
+poll_interval_seconds = 1.0
+batch_size = 50
+max_retries = 5
+enabled = true
+```
+
+### Transactional Outbox Example with SQLAlchemy
+
+```python
+from hexastack_core.domain import Event
+from hexastack_events.adapters.outbox.sqlalchemy import OutboxEventMixin
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class OrderOutboxEvent(Base, OutboxEventMixin):
+    __tablename__ = "outbox_events"
+
+
+class OrderPlacedEvent(Event):
+    order_id: str
+    total_amount: float
+    customer_id: str
+```

hexastack_events-0.0.0/README.md

@@ -0,0 +1,100 @@
+# hexastack-events
+
+**CNCF CloudEvents 1.0 serialization, Transactional Outbox pattern, and distributed event streaming for Hexastack.**
+
+Part of the [Hexastack Framework](https://github.com/TheTrueSCU/hexastack).
+
+---
+
+## 1. Architectural Overview
+
+`hexastack-events` extends Hexastack's in-process CQRS buses with enterprise distributed event streaming and reliability patterns:
+
+1. **CNCF CloudEvents 1.0 Protocol**: Automatic serialization and deserialization of domain `Event` models into standardized CloudEvents JSON envelopes with W3C correlation ID and multi-tenant partitioning.
+2. **Transactional Outbox Engine (Gap 6)**: Guarantees at-least-once delivery by staging uncommitted domain events in an `OutboxStoragePort` within the same transaction as business state mutations.
+3. **Dual Relay Engines**:
+   - **Native Asyncio (`AsyncioOutboxRelay`)**: In-process background task running with zero external dependencies.
+   - **Huey Worker (`HueyOutboxRelay`)**: Multi-process worker executing outbox polling in separate worker nodes (`pip install hexastack-events[huey]`).
+4. **Relational Database Outbox Storage (`SqlAlchemyOutboxStorage`)**: Pluggable storage adapter supporting SQLAlchemy tables and transactions (`pip install hexastack-events[sql]`).
+5. **Distributed Event Bus ([`DistributedEventBusPort`](file:///home/rjdw/Projects/hexastack/packages/hexastack_events/src/hexastack_events/ports/buses.py))**: Standardized cross-service messaging interface for Redis, NATS, Kafka, and in-memory brokers.
+
+```mermaid
+graph TD
+    CMD["CQRS Command Handler"]
+    UOW["Unit of Work Transaction"]
+    OUTBOX_MW["OutboxCaptureMiddleware"]
+    OUTBOX_STORE["OutboxStoragePort\n(SQLAlchemy / DB Outbox Table)"]
+    RELAY["OutboxRelayPort\n(Asyncio / Huey Worker)"]
+    BUS["DistributedEventBusPort\n(Redis / NATS / Kafka)"]
+
+    CMD --> UOW
+    CMD --> OUTBOX_MW
+    OUTBOX_MW -->|Stages Record| OUTBOX_STORE
+    UOW -->|Atomic Commit| OUTBOX_STORE
+    RELAY -->|Polls Pending| OUTBOX_STORE
+    RELAY -->|Publishes CloudEvent| BUS
+```
+
+---
+
+## 2. Key Exports & Package Structure
+
+```
+hexastack_events/
+├── domain/          # EventContext, OutboxRecord, OutboxStatus, CloudEventEnvelope, EventError
+├── ports/           # OutboxStoragePort, OutboxRelayPort, DistributedEventBusPort
+├── adapters/
+│   ├── cloudevents/ # to_cloudevent, from_cloudevent, cloudevent_to_json/dict
+│   ├── outbox/      # AsyncioOutboxRelay, HueyOutboxRelay, InMemoryOutboxStorage, SqlAlchemyOutboxStorage
+│   └── buses/       # InMemoryDistributedEventBus
+└── infra/           # EventsBootstrapper (order=22), HexastackEventsConfig, OutboxCaptureMiddleware
+```
+
+---
+
+## 3. Quickstart & Installation
+
+```bash
+# Core CloudEvents & Asyncio Outbox Relay (zero extra dependencies)
+pip install hexastack-events
+
+# With SQLAlchemy relational database outbox storage
+pip install "hexastack-events[sql]"
+
+# With Huey multi-process worker support
+pip install "hexastack-events[huey]"
+```
+
+### Configuration (`hexastack.toml` or `pyproject.toml`)
+
+```toml
+[hexastack.events]
+source = "billing-service"
+relay_mode = "asyncio" # "asyncio", "huey", "manual", "disabled"
+poll_interval_seconds = 1.0
+batch_size = 50
+max_retries = 5
+enabled = true
+```
+
+### Transactional Outbox Example with SQLAlchemy
+
+```python
+from hexastack_core.domain import Event
+from hexastack_events.adapters.outbox.sqlalchemy import OutboxEventMixin
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class OrderOutboxEvent(Base, OutboxEventMixin):
+    __tablename__ = "outbox_events"
+
+
+class OrderPlacedEvent(Event):
+    order_id: str
+    total_amount: float
+    customer_id: str
+```

hexastack_events-0.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "hexastack-events"
+version = "0.0.0"
+description = "CloudEvents serialization, Transactional Outbox pattern, and distributed event streaming for Hexastack"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "cloudevents>=1.11.0",
+    "hexastack-core",
+    "hexastack-cqrs",
+    "pydantic>=2.10.0",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+huey = ["huey>=3.3.4"]
+sql = ["sqlalchemy>=2.0.0"]
+
+[project.entry-points."hexastack.bootstrappers"]
+events = "hexastack_events.infra.bootstrap:EventsBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_events"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_events"]
+layers = [
+    "adapters",
+    "ports",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_events.domain"]
+forbidden_modules = [
+    "hexastack_events.ports",
+    "hexastack_events.adapters",
+    "hexastack_events.infra",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for ports"
+type = "forbidden"
+source_modules = ["hexastack_events.ports"]
+forbidden_modules = [
+    "hexastack_events.adapters",
+    "hexastack_events.infra",
+]

hexastack_events-0.0.0/pyproject.toml.orig

@@ -0,0 +1,66 @@
+[project]
+name = "hexastack-events"
+version = "0.0.0"
+description = "CloudEvents serialization, Transactional Outbox pattern, and distributed event streaming for Hexastack"
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "cloudevents>=1.11.0",
+    "hexastack-core",
+    "hexastack-cqrs",
+    "pydantic>=2.10.0",
+]
+
+[project.optional-dependencies]
+huey = [
+    "huey>=3.3.4",
+]
+sql = [
+    "sqlalchemy>=2.0.0",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+events = "hexastack_events.infra.bootstrap:EventsBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_events"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_events"]
+layers = [
+    "adapters",
+    "ports",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_events.domain"]
+forbidden_modules = [
+    "hexastack_events.ports",
+    "hexastack_events.adapters",
+    "hexastack_events.infra",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for ports"
+type = "forbidden"
+source_modules = ["hexastack_events.ports"]
+forbidden_modules = [
+    "hexastack_events.adapters",
+    "hexastack_events.infra",
+]

hexastack_events-0.0.0/src/hexastack_events/__init__.py

@@ -0,0 +1,8 @@
+from hexastack_events import adapters, domain, infra, ports
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+    "ports",
+]

hexastack_events-0.0.0/src/hexastack_events/adapters/__init__.py

@@ -0,0 +1,31 @@
+from hexastack_events.adapters.buses import InMemoryDistributedEventBus
+from hexastack_events.adapters.cloudevents import (
+    cloudevent_to_dict,
+    cloudevent_to_json,
+    from_cloudevent,
+    to_cloudevent,
+    to_envelope,
+)
+from hexastack_events.adapters.outbox import (
+    AsyncioOutboxRelay,
+    HueyOutboxRelay,
+    InMemoryOutboxStorage,
+    OutboxEventBaseModel,
+    OutboxEventMixin,
+    SqlAlchemyOutboxStorage,
+)
+
+__all__ = [
+    "AsyncioOutboxRelay",
+    "cloudevent_to_dict",
+    "cloudevent_to_json",
+    "from_cloudevent",
+    "HueyOutboxRelay",
+    "InMemoryDistributedEventBus",
+    "InMemoryOutboxStorage",
+    "OutboxEventBaseModel",
+    "OutboxEventMixin",
+    "SqlAlchemyOutboxStorage",
+    "to_cloudevent",
+    "to_envelope",
+]

hexastack_events-0.0.0/src/hexastack_events/adapters/buses/__init__.py

@@ -0,0 +1,5 @@
+from hexastack_events.adapters.buses.in_memory import InMemoryDistributedEventBus
+
+__all__ = [
+    "InMemoryDistributedEventBus",
+]

hexastack_events-0.0.0/src/hexastack_events/adapters/buses/in_memory.py

@@ -0,0 +1,52 @@
+from collections import defaultdict
+from collections.abc import Callable
+from typing import Any
+
+from hexastack_core.domain import Event
+from hexastack_events.domain.models import CloudEventEnvelope
+from hexastack_events.ports.buses import DistributedEventBusPort
+
+
+class InMemoryDistributedEventBus(DistributedEventBusPort):
+    """In-memory implementation of DistributedEventBusPort for testing and local dev.
+
+    Notes/Architectural Intent:
+        Records published CloudEvents envelopes, maintains topic subscriptions,
+        and allows verifying published events without external message brokers.
+    """
+
+    def __init__(self) -> None:
+        self.published_events: list[Event] = []
+        self.published_envelopes: list[CloudEventEnvelope] = []
+        self._subscribers: dict[str, list[Callable[[Any], Any]]] = defaultdict(list)
+
+    def clear(self) -> None:
+        """Clear recorded events and envelopes."""
+        self.published_events.clear()
+        self.published_envelopes.clear()
+
+    def publish(self, event: Event) -> None:
+        """Publish a domain event and invoke local subscribers."""
+        self.published_events.append(event)
+        event_name = event.__class__.__name__
+        for handler in self._subscribers.get(event_name, []):
+            handler(event)
+
+    def publish_envelope(self, envelope: CloudEventEnvelope) -> None:
+        """Publish a CloudEvents envelope and invoke matching subscribers."""
+        self.published_envelopes.append(envelope)
+        for handler in self._subscribers.get(envelope.type, []):
+            handler(envelope)
+
+    def subscribe(
+        self,
+        event_type: str,
+        handler: Callable[[Any], Any],
+    ) -> None:
+        """Register a subscriber callback for a specific event type."""
+        self._subscribers[event_type].append(handler)
+
+
+__all__ = [
+    "InMemoryDistributedEventBus",
+]

hexastack_events-0.0.0/src/hexastack_events/adapters/cloudevents/__init__.py

@@ -0,0 +1,15 @@
+from hexastack_events.adapters.cloudevents.serializer import (
+    cloudevent_to_dict,
+    cloudevent_to_json,
+    from_cloudevent,
+    to_cloudevent,
+    to_envelope,
+)
+
+__all__ = [
+    "cloudevent_to_dict",
+    "cloudevent_to_json",
+    "from_cloudevent",
+    "to_cloudevent",
+    "to_envelope",
+]

hexastack_events-0.0.0/src/hexastack_events/adapters/cloudevents/serializer.py

@@ -0,0 +1,155 @@
+import json
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from cloudevents.v1.http import CloudEvent, from_dict, from_json
+
+from hexastack_core.domain import Event
+from hexastack_core.utils.context import get_correlation_id, get_user_context
+from hexastack_events.domain.exceptions import EventSerializationError
+from hexastack_events.domain.models import CloudEventEnvelope
+
+__all__ = [
+    "cloudevent_to_dict",
+    "cloudevent_to_json",
+    "from_cloudevent",
+    "to_cloudevent",
+    "to_envelope",
+]
+
+
+def cloudevent_to_dict(ce: CloudEvent) -> dict[str, Any]:
+    """Serialize a CloudEvent instance to a standard dictionary format."""
+    result = dict(ce.get_attributes())
+    result["data"] = ce.data
+    return result
+
+
+def cloudevent_to_json(ce: CloudEvent) -> str:
+    """Serialize a CloudEvent instance to a valid JSON string."""
+    return json.dumps(cloudevent_to_dict(ce))
+
+
+def from_cloudevent[T: Event](
+    cloudevent_data: CloudEvent | dict[str, Any] | str,
+    event_cls: type[T],
+) -> T:
+    """Deserialize a CloudEvent envelope or JSON payload into a typed domain Event.
+
+    Notes/Architectural Intent:
+        Reconstructs the domain Event model from CloudEvent data payload while
+        preserving structural validation via Pydantic model_validate.
+
+    Args:
+        cloudevent_data: CloudEvent instance, dictionary payload, or JSON string.
+        event_cls: Target Event class to instantiate.
+
+    Returns:
+        Instantiated and validated domain Event model.
+
+    Raises:
+        EventSerializationError: If deserialization fails.
+    """
+    try:
+        if isinstance(cloudevent_data, str):
+            ce = from_json(cloudevent_data)
+        elif isinstance(cloudevent_data, dict):
+            ce = from_dict(cloudevent_data)
+        else:
+            ce = cloudevent_data
+
+        payload = ce.data
+        if isinstance(payload, str):
+            payload = json.loads(payload)
+
+        return event_cls.model_validate(payload)
+    except Exception as exc:
+        raise EventSerializationError(
+            f"Failed to deserialize CloudEvent into '{event_cls.__name__}': {exc}"
+        ) from exc
+
+
+def to_cloudevent(
+    event: Event,
+    *,
+    source: str = "hexastack",
+    event_type: str | None = None,
+    event_id: str | None = None,
+    time: datetime | None = None,
+    extensions: dict[str, Any] | None = None,
+) -> CloudEvent:
+    """Wrap a domain Event into a standard CNCF CloudEvent envelope.
+
+    Notes/Architectural Intent:
+        Standardizes domain event serialization for cross-service, cloud-native
+        messaging. Automatically extracts active correlation_id and tenant_id
+        from context into CloudEvents extension attributes.
+
+    Args:
+        event: Domain Event Pydantic model instance.
+        source: URI identifier of the event producer (defaults to 'hexastack').
+        event_type: Event type string (defaults to event class name).
+        event_id: Unique event ID (defaults to new UUID4).
+        time: Event timestamp in UTC (defaults to current UTC datetime).
+        extensions: Optional custom extension attributes.
+
+    Returns:
+        Populated CNCF CloudEvent instance.
+    """
+    now = time or datetime.now(UTC)
+    cid = get_correlation_id()
+    user_ctx = get_user_context()
+
+    attributes: dict[str, Any] = {
+        "id": event_id or str(uuid.uuid4()),
+        "source": source,
+        "type": event_type or event.__class__.__name__,
+        "specversion": "1.0",
+        "time": now.isoformat(),
+        "datacontenttype": "application/json",
+    }
+
+    if cid:
+        attributes["correlationid"] = cid
+
+    if user_ctx and user_ctx.tenant_id:
+        attributes["tenantid"] = user_ctx.tenant_id
+
+    if extensions:
+        attributes.update(extensions)
+
+    data = event.model_dump(mode="json")
+    return CloudEvent(attributes, data)
+
+
+def to_envelope(
+    event: Event,
+    *,
+    source: str = "hexastack",
+    event_type: str | None = None,
+    event_id: str | None = None,
+) -> CloudEventEnvelope:
+    """Convert domain Event to a typed CloudEventEnvelope Pydantic model.
+
+    Args:
+        event: Domain Event instance.
+        source: Event source URI.
+        event_type: Event type identifier.
+        event_id: Optional unique event ID.
+
+    Returns:
+        Populated CloudEventEnvelope instance.
+    """
+    ce = to_cloudevent(event, source=source, event_type=event_type, event_id=event_id)
+    attrs = ce.get_attributes()
+    return CloudEventEnvelope(
+        id=str(attrs.get("id")),
+        source=str(attrs.get("source")),
+        type=str(attrs.get("type")),
+        time=str(attrs.get("time")),
+        datacontenttype=str(attrs.get("datacontenttype", "application/json")),
+        correlationid=attrs.get("correlationid"),
+        tenantid=attrs.get("tenantid"),
+        data=ce.data if isinstance(ce.data, dict) else {},
+    )

hexastack_events-0.0.0/src/hexastack_events/adapters/outbox/__init__.py

@@ -0,0 +1,17 @@
+from hexastack_events.adapters.outbox.asyncio import AsyncioOutboxRelay
+from hexastack_events.adapters.outbox.huey import HueyOutboxRelay
+from hexastack_events.adapters.outbox.in_memory import InMemoryOutboxStorage
+from hexastack_events.adapters.outbox.sqlalchemy import (
+    OutboxEventBaseModel,
+    OutboxEventMixin,
+    SqlAlchemyOutboxStorage,
+)
+
+__all__ = [
+    "AsyncioOutboxRelay",
+    "HueyOutboxRelay",
+    "InMemoryOutboxStorage",
+    "OutboxEventBaseModel",
+    "OutboxEventMixin",
+    "SqlAlchemyOutboxStorage",
+]