qx-events 0.2.0__tar.gz

qx_events-0.2.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+.eggs/
+sdist/
+wheels/
+*.egg-link
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.env.local
+
+# Dist artifacts
+dist/
+
+# VS Code extension build artifacts
+extensions/vscode/node_modules/
+extensions/vscode/dist/
+extensions/vscode/*.vsix

qx_events-0.2.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: qx-events
+Version: 0.2.0
+Summary: Qx events: NATS JetStream publisher/consumer, outbox relay, mediator dispatcher bridge
+Author: Qx Engineering
+License: MIT
+Requires-Python: >=3.14
+Requires-Dist: nats-py>=2.9.0
+Requires-Dist: qx-cache
+Requires-Dist: qx-core
+Requires-Dist: qx-cqrs
+Requires-Dist: qx-db
+Requires-Dist: qx-di
+Requires-Dist: qx-observability
+Description-Content-Type: text/markdown
+
+# qx-events
+
+NATS JetStream publisher/consumer, transactional outbox relay, and mediator-bridge event dispatcher for the Qx framework.
+
+## What lives here
+
+- **`qx.events.OutboxRelay`** — polls `qx_outbox_events`, publishes unpublished events to NATS JetStream, and marks them delivered. Runs as a background task alongside the HTTP server or as a standalone process. Supports optional leader election so only one relay instance publishes at a time.
+- **`qx.events.NatsPublisher`** — publishes a single `IntegrationEvent` to a JetStream subject derived from `event_name`.
+- **`qx.events.NatsConsumer`** — durable pull consumer over a JetStream stream. Used by `WorkerRuntime` to fetch and ack/nak messages.
+- **`qx.events.NatsSettings`** — Pydantic settings for NATS connection (URL, credentials, stream name, consumer name).
+- **`qx.events.EventRegistry`** — maps `event_name` strings to concrete `IntegrationEvent` subclasses. Required by both the relay (for serialisation) and the worker (for deserialisation).
+- **`qx.events.MediatorEventDispatcher`** — `EventDispatcher` implementation that routes domain events to their in-process handlers via the Mediator after a UnitOfWork commit.
+- **`qx.events.create_nats_connection`** — async factory that opens a NATS connection with retry.
+
+## Usage
+
+### Outbox relay (alongside the API server)
+
+```python
+from qx.events import OutboxRelay, NatsPublisher, NatsSettings, EventRegistry
+
+registry = EventRegistry()
+registry.register(UserRegisteredIntegration)
+
+publisher = NatsPublisher(nc, registry)
+relay = OutboxRelay(session_factory, publisher, registry)
+
+# Run in background
+asyncio.create_task(relay.run())
+```
+
+### Consuming events in a worker
+
+```python
+from qx.events import NatsConsumer, NatsSettings
+
+settings = NatsSettings(url="nats://localhost:4222", stream="events", consumer="identity-worker")
+consumer = NatsConsumer(nc, settings)
+
+# WorkerRuntime handles the fetch/ack loop
+worker = WorkerRuntime(container, consumer, registry, mediator)
+await worker.run()
+```
+
+## Design rules
+
+- **At-least-once delivery** — the outbox guarantees every `INSERT`ed event is eventually published. Consumers are expected to be idempotent (use `IdempotencyStore` from `qx-cache`).
+- **Transactional outbox** — `UnitOfWork` (in `qx-db`) writes events to `qx_outbox_events` in the same transaction as the aggregate; the relay reads and publishes asynchronously. No event is lost even if the process crashes between commit and publish.
+- **Event envelope** — each NATS message carries `event_name`, `event_version`, payload JSON, `correlation_id`, `tenant_id`, and OTel trace context headers for full observability continuity.

qx_events-0.2.0/README.md

@@ -0,0 +1,49 @@
+# qx-events
+
+NATS JetStream publisher/consumer, transactional outbox relay, and mediator-bridge event dispatcher for the Qx framework.
+
+## What lives here
+
+- **`qx.events.OutboxRelay`** — polls `qx_outbox_events`, publishes unpublished events to NATS JetStream, and marks them delivered. Runs as a background task alongside the HTTP server or as a standalone process. Supports optional leader election so only one relay instance publishes at a time.
+- **`qx.events.NatsPublisher`** — publishes a single `IntegrationEvent` to a JetStream subject derived from `event_name`.
+- **`qx.events.NatsConsumer`** — durable pull consumer over a JetStream stream. Used by `WorkerRuntime` to fetch and ack/nak messages.
+- **`qx.events.NatsSettings`** — Pydantic settings for NATS connection (URL, credentials, stream name, consumer name).
+- **`qx.events.EventRegistry`** — maps `event_name` strings to concrete `IntegrationEvent` subclasses. Required by both the relay (for serialisation) and the worker (for deserialisation).
+- **`qx.events.MediatorEventDispatcher`** — `EventDispatcher` implementation that routes domain events to their in-process handlers via the Mediator after a UnitOfWork commit.
+- **`qx.events.create_nats_connection`** — async factory that opens a NATS connection with retry.
+
+## Usage
+
+### Outbox relay (alongside the API server)
+
+```python
+from qx.events import OutboxRelay, NatsPublisher, NatsSettings, EventRegistry
+
+registry = EventRegistry()
+registry.register(UserRegisteredIntegration)
+
+publisher = NatsPublisher(nc, registry)
+relay = OutboxRelay(session_factory, publisher, registry)
+
+# Run in background
+asyncio.create_task(relay.run())
+```
+
+### Consuming events in a worker
+
+```python
+from qx.events import NatsConsumer, NatsSettings
+
+settings = NatsSettings(url="nats://localhost:4222", stream="events", consumer="identity-worker")
+consumer = NatsConsumer(nc, settings)
+
+# WorkerRuntime handles the fetch/ack loop
+worker = WorkerRuntime(container, consumer, registry, mediator)
+await worker.run()
+```
+
+## Design rules
+
+- **At-least-once delivery** — the outbox guarantees every `INSERT`ed event is eventually published. Consumers are expected to be idempotent (use `IdempotencyStore` from `qx-cache`).
+- **Transactional outbox** — `UnitOfWork` (in `qx-db`) writes events to `qx_outbox_events` in the same transaction as the aggregate; the relay reads and publishes asynchronously. No event is lost even if the process crashes between commit and publish.
+- **Event envelope** — each NATS message carries `event_name`, `event_version`, payload JSON, `correlation_id`, `tenant_id`, and OTel trace context headers for full observability continuity.

qx_events-0.2.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "qx-events"
+version = "0.2.0"
+description = "Qx events: NATS JetStream publisher/consumer, outbox relay, mediator dispatcher bridge"
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [{ name = "Qx Engineering" }]
+dependencies = [
+    "qx-core",
+    "qx-di",
+    "qx-cqrs",
+    "qx-db",
+    "qx-cache",
+    "qx-observability",
+    "nats-py>=2.9.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qx"]

qx_events-0.2.0/src/qx/events/__init__.py

@@ -0,0 +1,27 @@
+"""Qx events: outbox relay, NATS publisher/consumer, mediator bridge."""
+
+from __future__ import annotations
+
+from qx.events.dispatcher import MediatorEventDispatcher
+from qx.events.nats import (
+    NatsConsumer,
+    NatsPublisher,
+    NatsSettings,
+    create_nats_connection,
+)
+from qx.events.outbox_relay import OutboxRelay
+from qx.events.registry import EventRegistry, EventTypeNotRegistered
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "EventRegistry",
+    "EventTypeNotRegistered",
+    "MediatorEventDispatcher",
+    "NatsConsumer",
+    "NatsPublisher",
+    "NatsSettings",
+    "OutboxRelay",
+    "__version__",
+    "create_nats_connection",
+]

qx_events-0.2.0/src/qx/events/dispatcher/__init__.py

@@ -0,0 +1,31 @@
+"""Bridge between ``qx-db.UnitOfWork`` and ``qx-cqrs.Mediator``.
+
+The UoW depends on a thin ``EventDispatcher`` protocol (one method,
+``publish(event)``). The Mediator is a richer object. This module supplies a
+trivial adapter so wiring in service bootstrap is one line::
+
+    container.register_singleton(
+        EventDispatcher,
+        lambda m: MediatorEventDispatcher(m),
+    )
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qx.core import DomainEvent
+    from qx.cqrs import Mediator
+
+__all__ = ["MediatorEventDispatcher"]
+
+
+class MediatorEventDispatcher:
+    """Adapt ``Mediator.publish`` to the ``EventDispatcher`` protocol."""
+
+    def __init__(self, mediator: Mediator) -> None:
+        self._m = mediator
+
+    async def publish(self, event: DomainEvent) -> None:
+        await self._m.publish(event)

qx_events-0.2.0/src/qx/events/nats/__init__.py

@@ -0,0 +1,235 @@
+"""NATS JetStream integration.
+
+Two responsibilities:
+
+- ``NatsPublisher``: durable publish to a JetStream subject. Used by the outbox
+  relay (and only the outbox relay — application code never publishes
+  integration events directly; that's the whole point of the outbox).
+
+- ``NatsConsumer``: durable pull-subscription wrapper. Used by worker runtimes
+  to receive integration events with at-least-once semantics, ack/nack control,
+  and per-message tracing/logging.
+
+NATS connection management:
+- Single connection per process (singleton in DI).
+- Auto-reconnect on disconnect (NATS client default).
+- JetStream context obtained from the connection lazily.
+
+Subject convention: ``<service>.<event_name>``, e.g., ``identity.user.registered``.
+Streams should be configured at deployment (declarative), not at runtime; this
+module assumes the stream exists.
+"""
+
+from __future__ import annotations
+
+import json
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, ClassVar
+
+import nats
+from nats.js.api import AckPolicy, ConsumerConfig, DeliverPolicy
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from qx.events.registry import EventRegistry, EventTypeNotRegistered
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from nats.aio.client import Client as NatsClient
+    from nats.aio.msg import Msg
+    from nats.js import JetStreamContext
+    from qx.core import IntegrationEvent
+
+__all__ = [
+    "NatsConsumer",
+    "NatsPublisher",
+    "NatsSettings",
+    "create_nats_connection",
+]
+
+
+class NatsSettings(BaseSettings):
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix="QX_NATS__",
+        extra="ignore",
+    )
+
+    servers: tuple[str, ...] = ("nats://localhost:4222",)
+    max_reconnect_attempts: int = 60
+    reconnect_time_wait_seconds: float = 2.0
+    connect_timeout_seconds: float = 5.0
+    name: str | None = None  # client name shown in `nats-server -m monitoring`
+
+
+async def create_nats_connection(settings: NatsSettings) -> NatsClient:
+    """Connect to NATS with sensible reconnect behavior."""
+    return await nats.connect(
+        servers=list(settings.servers),
+        max_reconnect_attempts=settings.max_reconnect_attempts,
+        reconnect_time_wait=settings.reconnect_time_wait_seconds,
+        connect_timeout=settings.connect_timeout_seconds,
+        name=settings.name,
+        # Don't drain on close — we want to surface drops as errors.
+        drain_timeout=10,
+    )
+
+
+# ============================================================
+# Publisher
+# ============================================================
+
+
+class NatsPublisher:
+    """Publish ``IntegrationEvent`` payloads to JetStream.
+
+    Subject is computed as ``f"{prefix}.{event_name}"``. The ``prefix`` is
+    typically the service name; configure once at construction.
+    """
+
+    def __init__(
+        self,
+        connection: NatsClient,
+        *,
+        subject_prefix: str,
+    ) -> None:
+        self._nc = connection
+        self._prefix = subject_prefix
+        self._js: JetStreamContext | None = None
+
+    def _jetstream(self) -> JetStreamContext:
+        if self._js is None:
+            self._js = self._nc.jetstream()
+        return self._js
+
+    def _subject(self, event_name: str) -> str:
+        return f"{self._prefix}.{event_name}"
+
+    async def publish(self, event: IntegrationEvent) -> None:
+        """Publish a single event. Waits for JetStream ack."""
+        subject = self._subject(event.event_name)
+        payload = json.dumps(event.envelope()).encode()
+        # Headers carry W3C trace context and the event metadata in a way that
+        # consumers can read without deserializing the body. Useful for routing
+        # and observability sidecars.
+        headers = {
+            "qx.event_name": event.event_name,
+            "qx.event_version": str(event.event_version),
+            "qx.event_id": str(event.event_id),
+        }
+        if event.correlation_id:
+            headers["qx.correlation_id"] = str(event.correlation_id)
+        if event.tenant_id:
+            headers["qx.tenant_id"] = str(event.tenant_id)
+        await self._jetstream().publish(subject, payload, headers=headers)
+
+    async def publish_raw(
+        self,
+        event_name: str,
+        envelope: dict[str, Any],
+        *,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """Publish a pre-serialized envelope. Used by the outbox relay."""
+        subject = self._subject(event_name)
+        hdrs = dict(headers or {})
+        hdrs.setdefault("qx.event_name", event_name)
+        await self._jetstream().publish(subject, json.dumps(envelope).encode(), headers=hdrs)
+
+
+# ============================================================
+# Consumer
+# ============================================================
+
+
+class NatsConsumer:
+    """Durable pull-subscription for an integration-event stream.
+
+    Typical usage in the worker runtime::
+
+        async for msg, event in consumer.messages():
+            try:
+                await dispatch(event)
+                await msg.ack()
+            except Exception:
+                await msg.nak()
+    """
+
+    def __init__(
+        self,
+        connection: NatsClient,
+        registry: EventRegistry,
+        *,
+        stream: str,
+        durable_name: str,
+        subject_filter: str,
+        batch_size: int = 32,
+        fetch_timeout_seconds: float = 5.0,
+        max_deliver: int = 5,
+        ack_wait_seconds: int = 30,
+    ) -> None:
+        self._nc = connection
+        self._registry = registry
+        self._stream = stream
+        self._durable = durable_name
+        self._subject_filter = subject_filter
+        self._batch_size = batch_size
+        self._fetch_timeout = fetch_timeout_seconds
+        self._max_deliver = max_deliver
+        self._ack_wait = ack_wait_seconds
+        self._js: JetStreamContext | None = None
+
+    async def _ensure_consumer(self) -> Any:
+        """Create or attach to the durable pull consumer."""
+        if self._js is None:
+            self._js = self._nc.jetstream()
+        config = ConsumerConfig(
+            durable_name=self._durable,
+            filter_subject=self._subject_filter,
+            ack_policy=AckPolicy.EXPLICIT,
+            deliver_policy=DeliverPolicy.ALL,
+            max_deliver=self._max_deliver,
+            ack_wait=self._ack_wait,
+        )
+        # add_consumer is idempotent if the config matches.
+        await self._js.add_consumer(self._stream, config=config)
+        return await self._js.pull_subscribe(
+            self._subject_filter,
+            durable=self._durable,
+            stream=self._stream,
+        )
+
+    @asynccontextmanager
+    async def messages(self) -> AsyncIterator[Any]:
+        """Yield batches of ``(msg, IntegrationEvent)`` tuples.
+
+        Caller is responsible for ack/nak. Failures during fetch propagate;
+        the worker runtime catches and re-tries with backoff.
+        """
+        sub = await self._ensure_consumer()
+        try:
+            yield sub
+        finally:
+            await sub.unsubscribe()
+
+    def parse_message(self, msg: Msg) -> IntegrationEvent:
+        """Deserialize a NATS message into a concrete IntegrationEvent."""
+        envelope = json.loads(msg.data.decode())
+        event_name = envelope.get("event_name") or (msg.headers or {}).get("qx.event_name", "")
+        event_version = int(envelope.get("event_version", 1))
+        try:
+            cls = self._registry.lookup(event_name, event_version)
+        except EventTypeNotRegistered:
+            raise
+        # The envelope format puts business payload under "payload".
+        payload = envelope.get("payload", {})
+        # Rebuild the event with its meta fields.
+        return cls.model_validate(
+            {
+                **payload,
+                "event_id": envelope.get("event_id"),
+                "occurred_at": envelope.get("occurred_at"),
+                "correlation_id": envelope.get("correlation_id"),
+                "causation_id": envelope.get("causation_id"),
+                "tenant_id": envelope.get("tenant_id"),
+                "actor_id": envelope.get("actor_id"),
+            }
+        )

qx_events-0.2.0/src/qx/events/outbox_relay/__init__.py

@@ -0,0 +1,216 @@
+"""Outbox relay worker.
+
+Background worker that drains the ``qx_outbox_events`` table to the message
+broker. Architecture:
+
+1. Periodically (default every 500ms) take a small batch of unpublished rows
+   with ``SELECT ... FOR UPDATE SKIP LOCKED`` so concurrent relay instances
+   never claim the same row.
+2. For each row, publish to NATS JetStream and wait for the stream's ack.
+3. On success: mark ``published_at = now()``.
+4. On failure: increment ``attempts``, log, leave for retry.
+
+**HA sharding** — run N relay workers in parallel, each owning a hash-based
+shard of the outbox table (e.g., one per Kubernetes pod replica)::
+
+    # pod-0
+    relay = OutboxRelay(engine, publisher, shard_id=0, shard_count=3)
+
+    # pod-1
+    relay = OutboxRelay(engine, publisher, shard_id=1, shard_count=3)
+
+    # pod-2
+    relay = OutboxRelay(engine, publisher, shard_id=2, shard_count=3)
+
+Each relay adds ``ABS(HASHTEXT(id::text)::bigint) % shard_count = shard_id``
+to the batch query, so shards are disjoint with no coordinator overhead.
+
+**Single-instance mode** — the default (``shard_count=1``) omits the shard
+filter entirely and optionally uses a ``DistributedLock`` to guarantee a
+single active relay under multi-replica deployments.
+
+The relay is **separate** from the consumer worker (``qx-worker``) by
+design — relay is service-internal infrastructure; consumer runs the
+business handlers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from qx.db.outbox import OUTBOX_TABLE_NAME
+from qx.observability import get_logger, trace_span
+from sqlalchemy import text
+
+if TYPE_CHECKING:
+    from qx.cache import DistributedLock
+    from qx.events.nats import NatsPublisher
+    from sqlalchemy.ext.asyncio import AsyncEngine
+
+__all__ = ["OutboxRelay"]
+
+
+class OutboxRelay:
+    """Polls the outbox table and publishes pending events.
+
+    Lifecycle: ``await relay.run()`` blocks until ``await relay.stop()`` is
+    called from a signal handler.
+    """
+
+    def __init__(
+        self,
+        engine: AsyncEngine,
+        publisher: NatsPublisher,
+        *,
+        leader_lock: DistributedLock | None = None,
+        shard_id: int = 0,
+        shard_count: int = 1,
+        table_name: str = OUTBOX_TABLE_NAME,
+        batch_size: int = 100,
+        poll_interval_seconds: float = 0.5,
+        idle_poll_interval_seconds: float = 2.0,
+        max_attempts: int = 10,
+    ) -> None:
+        if shard_count < 1:
+            raise ValueError(f"shard_count must be >= 1, got {shard_count}")
+        if not (0 <= shard_id < shard_count):
+            raise ValueError(
+                f"shard_id must be in [0, shard_count), got shard_id={shard_id}, shard_count={shard_count}"
+            )
+        self._engine = engine
+        self._publisher = publisher
+        self._lock = leader_lock
+        self._shard_id = shard_id
+        self._shard_count = shard_count
+        self._table = table_name
+        self._batch = batch_size
+        self._poll = poll_interval_seconds
+        self._idle_poll = idle_poll_interval_seconds
+        self._max_attempts = max_attempts
+        self._stop = asyncio.Event()
+        self._log = get_logger(f"qx.outbox-relay[{shard_id}/{shard_count}]")
+
+    async def stop(self) -> None:
+        self._stop.set()
+
+    async def run(self) -> None:
+        """Main loop. Acquires the leader lock (if any), polls, publishes, repeats."""
+        self._log.info("outbox-relay starting")
+        while not self._stop.is_set():
+            try:
+                if self._lock is not None:
+                    async with self._lock.acquired(ttl_seconds=60) as got:
+                        if not got:
+                            # Another instance is leader; back off.
+                            await self._sleep(2.0)
+                            continue
+                        # Renew while we're working.
+                        await self._drain_loop()
+                else:
+                    await self._drain_loop()
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                self._log.error("outbox-relay error: %s", exc, exc_info=True)
+                await self._sleep(2.0)
+        self._log.info("outbox-relay stopped")
+
+    async def _drain_loop(self) -> None:
+        while not self._stop.is_set():
+            with trace_span("outbox.batch"):
+                published = await self._process_one_batch()
+            if published == 0:
+                # Nothing pending; back off for the idle interval.
+                await self._sleep(self._idle_poll)
+            else:
+                await self._sleep(self._poll)
+
+    def _shard_clause(self) -> str:
+        if self._shard_count == 1:
+            return ""
+        # Cast to bigint before ABS to avoid int4 overflow on INT_MIN.
+        return "  AND ABS(HASHTEXT(id::text)::bigint) % :shard_count = :shard_id\n"
+
+    async def _process_one_batch(self) -> int:
+        async with self._engine.begin() as conn:
+            res = await conn.execute(
+                text(
+                    f"""
+                    SELECT id, event_name, event_version, payload,
+                           correlation_id, tenant_id, attempts
+                    FROM {self._table}
+                    WHERE published_at IS NULL
+                      AND attempts < :max_attempts
+                    {self._shard_clause()}ORDER BY occurred_at ASC
+                    LIMIT :limit
+                    FOR UPDATE SKIP LOCKED
+                    """
+                ),
+                {
+                    "limit": self._batch,
+                    "max_attempts": self._max_attempts,
+                    "shard_count": self._shard_count,
+                    "shard_id": self._shard_id,
+                },
+            )
+            rows = list(res.mappings())
+            if not rows:
+                return 0
+
+            published_ids: list[str] = []
+            failed: list[tuple[str, str]] = []  # (id, error)
+            for row in rows:
+                envelope = (
+                    json.loads(row["payload"])
+                    if isinstance(row["payload"], str)
+                    else row["payload"]
+                )
+                headers = {"qx.event_name": row["event_name"]}
+                if row["correlation_id"]:
+                    headers["qx.correlation_id"] = str(row["correlation_id"])
+                if row["tenant_id"]:
+                    headers["qx.tenant_id"] = str(row["tenant_id"])
+                try:
+                    await self._publisher.publish_raw(
+                        row["event_name"],
+                        envelope,
+                        headers=headers,
+                    )
+                    published_ids.append(row["id"])
+                except Exception as exc:
+                    failed.append((row["id"], f"{type(exc).__name__}: {exc}"))
+
+            if published_ids:
+                await conn.execute(
+                    text(
+                        f"""
+                        UPDATE {self._table}
+                        SET published_at = :now
+                        WHERE id = ANY(:ids)
+                        """
+                    ),
+                    {"now": datetime.now(UTC), "ids": published_ids},
+                )
+
+            for fid, err in failed:
+                await conn.execute(
+                    text(
+                        f"""
+                        UPDATE {self._table}
+                        SET attempts = attempts + 1,
+                            last_error = :err
+                        WHERE id = :id
+                        """
+                    ),
+                    {"err": err[:2000], "id": fid},
+                )
+
+            return len(published_ids)
+
+    async def _sleep(self, seconds: float) -> None:
+        with contextlib.suppress(TimeoutError):
+            await asyncio.wait_for(self._stop.wait(), timeout=seconds)

qx_events-0.2.0/src/qx/events/registry/__init__.py

@@ -0,0 +1,67 @@
+"""Event type registry.
+
+Maps ``event_name`` strings to the concrete ``IntegrationEvent`` subclass so
+the consumer side can deserialize incoming messages. Without this, the
+worker would receive an opaque dict and the application would have to do its
+own dispatch.
+
+Services register their event types once at bootstrap::
+
+    registry = EventRegistry()
+    registry.register(UserRegistered)
+    registry.register(OrderPlaced)
+
+    container.register_instance(EventRegistry, registry)
+
+When the worker pulls a NATS message, the registry resolves the class:
+
+    cls = registry.lookup("user.registered")
+    event = cls.model_validate(payload)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qx.core import IntegrationEvent
+
+__all__ = ["EventRegistry", "EventTypeNotRegistered"]
+
+
+class EventTypeNotRegistered(Exception):
+    """Raised when an incoming event_name has no matching class."""
+
+
+class EventRegistry:
+    """Mapping from ``event_name`` to ``IntegrationEvent`` subclass."""
+
+    def __init__(self) -> None:
+        self._by_name: dict[tuple[str, int], type[IntegrationEvent]] = {}
+
+    def register(self, event_cls: type[IntegrationEvent]) -> None:
+        if not event_cls.event_name:
+            raise ValueError(f"{event_cls.__name__} has no event_name; cannot register")
+        key = (event_cls.event_name, event_cls.event_version)
+        existing = self._by_name.get(key)
+        if existing is not None and existing is not event_cls:
+            raise ValueError(
+                f"event_name {event_cls.event_name!r} v{event_cls.event_version} "
+                f"already registered to {existing.__name__}"
+            )
+        self._by_name[key] = event_cls
+
+    def lookup(self, event_name: str, version: int = 1) -> type[IntegrationEvent]:
+        try:
+            return self._by_name[(event_name, version)]
+        except KeyError as e:
+            raise EventTypeNotRegistered(
+                f"No event registered for {event_name!r} v{version}. "
+                f"Did you call EventRegistry.register({event_name})?"
+            ) from e
+
+    def __len__(self) -> int:
+        return len(self._by_name)
+
+    def known_event_names(self) -> list[str]:
+        return sorted({name for name, _ in self._by_name})

qx_events-0.2.0/tests/test_events_unit.py

@@ -0,0 +1,70 @@
+"""Unit tests for events package — registry + dispatcher bridge."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+import pytest
+from qx.core import DomainEvent, IntegrationEvent
+from qx.events import EventRegistry, EventTypeNotRegistered, MediatorEventDispatcher
+
+
+class UserRegistered(IntegrationEvent):
+    event_name: ClassVar[str] = "identity.user.registered"
+    event_version: ClassVar[int] = 1
+    email: str
+
+
+class OrderPlaced(IntegrationEvent):
+    event_name: ClassVar[str] = "commerce.order.placed"
+    event_version: ClassVar[int] = 2
+    total_cents: int
+
+
+def test_registry_round_trip() -> None:
+    r = EventRegistry()
+    r.register(UserRegistered)
+    r.register(OrderPlaced)
+    assert r.lookup("identity.user.registered", 1) is UserRegistered
+    assert r.lookup("commerce.order.placed", 2) is OrderPlaced
+
+
+def test_unknown_event_raises() -> None:
+    r = EventRegistry()
+    with pytest.raises(EventTypeNotRegistered):
+        r.lookup("missing", 1)
+
+
+def test_duplicate_registration_with_same_class_is_noop() -> None:
+    r = EventRegistry()
+    r.register(UserRegistered)
+    r.register(UserRegistered)  # idempotent
+
+
+def test_duplicate_registration_with_different_class_raises() -> None:
+    class OtherUserRegistered(IntegrationEvent):
+        event_name: ClassVar[str] = "identity.user.registered"
+        email: str
+
+    r = EventRegistry()
+    r.register(UserRegistered)
+    with pytest.raises(ValueError, match="already registered"):
+        r.register(OtherUserRegistered)
+
+
+async def test_mediator_dispatcher_bridge_calls_publish() -> None:
+    class FakeMediator:
+        def __init__(self) -> None:
+            self.published: list[DomainEvent] = []
+
+        async def publish(self, ev: DomainEvent) -> None:
+            self.published.append(ev)
+
+    class Evt(DomainEvent):
+        event_name: ClassVar[str] = "x.something"
+        payload: str
+
+    m = FakeMediator()
+    d = MediatorEventDispatcher(m)  # type: ignore[arg-type]
+    await d.publish(Evt(payload="hi"))
+    assert len(m.published) == 1

qx_events-0.2.0/tests/test_outbox_relay_unit.py

@@ -0,0 +1,152 @@
+"""OutboxRelay sharding unit tests — no real DB or broker."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from qx.events import OutboxRelay
+
+# ---- construction / validation ----
+
+
+def test_default_is_single_shard() -> None:
+    relay = OutboxRelay(_mock_engine(), MagicMock())
+    assert relay._shard_id == 0
+    assert relay._shard_count == 1
+
+
+def test_valid_shard_configuration() -> None:
+    relay = OutboxRelay(_mock_engine(), MagicMock(), shard_id=2, shard_count=3)
+    assert relay._shard_id == 2
+    assert relay._shard_count == 3
+
+
+def test_shard_count_zero_raises() -> None:
+    with pytest.raises(ValueError, match="shard_count must be >= 1"):
+        OutboxRelay(_mock_engine(), MagicMock(), shard_count=0)
+
+
+def test_shard_id_equal_to_shard_count_raises() -> None:
+    with pytest.raises(ValueError, match="shard_id must be in"):
+        OutboxRelay(_mock_engine(), MagicMock(), shard_id=3, shard_count=3)
+
+
+def test_shard_id_negative_raises() -> None:
+    with pytest.raises(ValueError, match="shard_id must be in"):
+        OutboxRelay(_mock_engine(), MagicMock(), shard_id=-1, shard_count=3)
+
+
+# ---- shard clause generation ----
+
+
+def test_single_shard_produces_no_clause() -> None:
+    relay = OutboxRelay(_mock_engine(), MagicMock(), shard_id=0, shard_count=1)
+    assert relay._shard_clause() == ""
+
+
+def test_multi_shard_produces_hashtext_clause() -> None:
+    relay = OutboxRelay(_mock_engine(), MagicMock(), shard_id=1, shard_count=4)
+    clause = relay._shard_clause()
+    assert "HASHTEXT" in clause
+    assert "shard_count" in clause
+    assert "shard_id" in clause
+
+
+# ---- batch query SQL ----
+
+
+@pytest.mark.anyio
+async def test_single_shard_batch_query_has_no_hashtext() -> None:
+    conn, engine = _mock_conn_engine()
+    relay = OutboxRelay(engine, MagicMock(), shard_id=0, shard_count=1)
+
+    await relay._process_one_batch()
+
+    sql = _first_select_sql(conn)
+    assert "HASHTEXT" not in sql
+
+
+@pytest.mark.anyio
+async def test_multi_shard_batch_query_includes_hashtext_filter() -> None:
+    conn, engine = _mock_conn_engine()
+    relay = OutboxRelay(engine, MagicMock(), shard_id=2, shard_count=5)
+
+    await relay._process_one_batch()
+
+    sql = _first_select_sql(conn)
+    assert "HASHTEXT" in sql
+    assert "shard_count" in sql
+    assert "shard_id" in sql
+
+
+@pytest.mark.anyio
+async def test_batch_query_params_include_shard_values() -> None:
+    conn, engine = _mock_conn_engine()
+    relay = OutboxRelay(engine, MagicMock(), shard_id=1, shard_count=3)
+
+    await relay._process_one_batch()
+
+    params = conn.execute.call_args_list[0].args[1]
+    assert params["shard_count"] == 3
+    assert params["shard_id"] == 1
+
+
+@pytest.mark.anyio
+async def test_batch_query_always_has_skip_locked() -> None:
+    conn, engine = _mock_conn_engine()
+    relay = OutboxRelay(engine, MagicMock(), shard_id=0, shard_count=4)
+
+    await relay._process_one_batch()
+
+    sql = _first_select_sql(conn)
+    assert "FOR UPDATE SKIP LOCKED" in sql
+
+
+@pytest.mark.anyio
+async def test_returns_zero_when_no_rows() -> None:
+    _, engine = _mock_conn_engine()
+    relay = OutboxRelay(engine, MagicMock())
+
+    result = await relay._process_one_batch()
+
+    assert result == 0
+
+
+# ---- helpers ----
+
+
+def _mock_engine() -> MagicMock:
+    conn = AsyncMock()
+    mock_result = MagicMock()
+    mock_result.mappings.return_value = []
+    conn.execute = AsyncMock(return_value=mock_result)
+
+    @asynccontextmanager
+    async def _begin():
+        yield conn
+
+    engine = MagicMock()
+    engine.begin = MagicMock(return_value=_begin())
+    return engine
+
+
+def _mock_conn_engine() -> tuple[AsyncMock, MagicMock]:
+    conn = AsyncMock()
+    mock_result = MagicMock()
+    mock_result.mappings.return_value = []
+    conn.execute = AsyncMock(return_value=mock_result)
+
+    @asynccontextmanager
+    async def _begin():
+        yield conn
+
+    engine = MagicMock()
+    engine.begin = MagicMock(return_value=_begin())
+    return conn, engine
+
+
+def _first_select_sql(conn: AsyncMock) -> str:
+    arg = conn.execute.call_args_list[0].args[0]
+    return arg.text if hasattr(arg, "text") else str(arg)