outboxed 0.1.0__py3-none-any.whl

outboxed/__init__.py

@@ -0,0 +1,9 @@
+"""outboxed: the transactional outbox pattern for Python backends."""
+
+from outboxed.models import Event
+from outboxed.outbox import Outbox
+from outboxed.relay import Relay
+
+__all__ = ["Event", "Outbox", "Relay"]
+
+__version__ = "0.1.0"

outboxed/backends/__init__.py

@@ -0,0 +1,6 @@
+"""Broker adapters implementing the Backend protocol."""
+
+from outboxed.backends.base import Backend
+from outboxed.backends.in_memory import InMemoryBackend
+
+__all__ = ["Backend", "InMemoryBackend"]

outboxed/backends/base.py

@@ -0,0 +1,13 @@
+"""The protocol every broker adapter implements."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class Backend(Protocol):
+    """A destination the relay publishes outbox entries to."""
+
+    def publish(self, *, topic: str, key: str | None, payload: str) -> None:
+        """Publish one entry. Raise to signal failure; the relay will retry."""
+        ...

outboxed/backends/in_memory.py

@@ -0,0 +1,22 @@
+"""In-process backend for tests and for trying the library with no broker."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class _PublishedMessage:
+    topic: str
+    key: str | None
+    payload: str
+
+
+class InMemoryBackend:
+    """Collects published messages in memory instead of talking to a broker."""
+
+    def __init__(self) -> None:
+        self.messages: list[_PublishedMessage] = []
+
+    def publish(self, *, topic: str, key: str | None, payload: str) -> None:
+        self.messages.append(_PublishedMessage(topic=topic, key=key, payload=payload))

outboxed/backends/kafka.py

@@ -0,0 +1,21 @@
+"""Kafka backend. Requires the ``outboxed[kafka]`` extra."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class KafkaBackend:
+    """Publishes outbox entries to a Kafka topic via confluent-kafka."""
+
+    def __init__(self, producer: Any, *, flush_timeout: float = 10.0) -> None:
+        self._producer = producer
+        self._flush_timeout = flush_timeout
+
+    def publish(self, *, topic: str, key: str | None, payload: str) -> None:
+        self._producer.produce(
+            topic,
+            key=key.encode() if key is not None else None,
+            value=payload.encode(),
+        )
+        self._producer.flush(self._flush_timeout)

outboxed/backends/redis_streams.py

@@ -0,0 +1,17 @@
+"""Redis Streams backend. Requires the ``outboxed[redis]`` extra."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class RedisStreamsBackend:
+    """Publishes outbox entries to a Redis stream via XADD."""
+
+    def __init__(self, client: Any, *, stream_prefix: str = "") -> None:
+        self._client = client
+        self._stream_prefix = stream_prefix
+
+    def publish(self, *, topic: str, key: str | None, payload: str) -> None:
+        stream = f"{self._stream_prefix}{topic}"
+        self._client.xadd(stream, {"key": key or "", "payload": payload})

outboxed/backends/sqs.py

@@ -0,0 +1,24 @@
+"""SQS backend. Requires the ``outboxed[sqs]`` extra."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class SQSBackend:
+    """Publishes outbox entries to an SQS queue via send_message.
+
+    ``topic`` is mapped to a queue URL through ``queue_urls`` since SQS has
+    no native topic concept.
+    """
+
+    def __init__(self, client: Any, *, queue_urls: dict[str, str]) -> None:
+        self._client = client
+        self._queue_urls = queue_urls
+
+    def publish(self, *, topic: str, key: str | None, payload: str) -> None:
+        queue_url = self._queue_urls[topic]
+        kwargs: dict[str, Any] = {"QueueUrl": queue_url, "MessageBody": payload}
+        if key is not None:
+            kwargs["MessageGroupId"] = key
+        self._client.send_message(**kwargs)

outboxed/dedup.py

@@ -0,0 +1,20 @@
+"""Delivery-id tracking so retries after a crash don't double-publish downstream."""
+
+from __future__ import annotations
+
+
+class DeliveryTracker:
+    """Tracks which event ids have already been handed to the backend.
+
+    Backed by whatever store the relay is configured with; the default
+    in-process set is only suitable for a single relay instance and tests.
+    """
+
+    def __init__(self) -> None:
+        self._seen: set[str] = set()
+
+    def is_duplicate(self, event_id: str) -> bool:
+        return event_id in self._seen
+
+    def mark_delivered(self, event_id: str) -> None:
+        self._seen.add(event_id)

outboxed/models.py

@@ -0,0 +1,31 @@
+"""OutboxEntry table definition and the Event the caller enqueues."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+
+from sqlalchemy import Column, DateTime, MetaData, String, Table, func
+
+metadata = MetaData()
+
+outbox_table = Table(
+    "outboxed_entries",
+    metadata,
+    Column("id", String(36), primary_key=True),
+    Column("topic", String(255), nullable=False),
+    Column("key", String(255), nullable=True),
+    Column("payload", String, nullable=False),
+    Column("created_at", DateTime(timezone=True), server_default=func.now(), nullable=False),
+    Column("delivered_at", DateTime(timezone=True), nullable=True),
+)
+
+
+@dataclass(frozen=True)
+class Event:
+    """A single event to be delivered to a backend, exactly once observable."""
+
+    topic: str
+    payload: str
+    key: str | None = None
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))

outboxed/outbox.py

@@ -0,0 +1,25 @@
+"""The write side: enqueue an event inside the caller's own transaction."""
+
+from __future__ import annotations
+
+from sqlalchemy.engine import Connection
+
+from outboxed.models import Event, outbox_table
+
+
+class Outbox:
+    """Writes events into the outbox table using the caller's connection.
+
+    Call ``enqueue`` with the same ``Connection``/transaction used for the
+    business write. If that transaction rolls back, the event never existed.
+    """
+
+    def enqueue(self, connection: Connection, event: Event) -> None:
+        connection.execute(
+            outbox_table.insert().values(
+                id=event.id,
+                topic=event.topic,
+                key=event.key,
+                payload=event.payload,
+            )
+        )

outboxed/relay.py

@@ -0,0 +1,71 @@
+"""The read side: polls the outbox table, dispatches to a backend, marks sent."""
+
+from __future__ import annotations
+
+import time
+
+from sqlalchemy import func
+from sqlalchemy.engine import Engine
+
+from outboxed.backends.base import Backend
+from outboxed.dedup import DeliveryTracker
+from outboxed.models import outbox_table
+
+
+class Relay:
+    """Polls the outbox table and delivers undelivered events to a backend.
+
+    At-least-once delivery: a crash between dispatch and marking an entry
+    delivered means it is redelivered on restart. The ``DeliveryTracker``
+    filters duplicates before they reach the backend's handler.
+    """
+
+    def __init__(
+        self,
+        engine: Engine,
+        backend: Backend,
+        *,
+        batch_size: int = 100,
+        poll_interval: float = 1.0,
+        tracker: DeliveryTracker | None = None,
+    ) -> None:
+        self._engine = engine
+        self._backend = backend
+        self._batch_size = batch_size
+        self._poll_interval = poll_interval
+        self._tracker = tracker or DeliveryTracker()
+        self._running = False
+
+    def run_forever(self) -> None:
+        self._running = True
+        while self._running:
+            delivered = self.poll_once()
+            if delivered == 0:
+                time.sleep(self._poll_interval)
+
+    def stop(self) -> None:
+        self._running = False
+
+    def poll_once(self) -> int:
+        delivered = 0
+        with self._engine.begin() as conn:
+            rows = conn.execute(
+                outbox_table.select()
+                .where(outbox_table.c.delivered_at.is_(None))
+                .order_by(outbox_table.c.created_at)
+                .limit(self._batch_size)
+            ).fetchall()
+
+            for row in rows:
+                if not self._tracker.is_duplicate(row.id):
+                    self._backend.publish(topic=row.topic, key=row.key, payload=row.payload)
+                    self._tracker.mark_delivered(row.id)
+
+                conn.execute(
+                    outbox_table.update()
+                    .where(outbox_table.c.id == row.id)
+                    .values(delivered_at=func.now())
+                )
+                delivered += 1
+
+        return delivered

outboxed-0.1.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: outboxed
+Version: 0.1.0
+Summary: Transactional outbox pattern for Python backends
+Project-URL: Homepage, https://github.com/amin-albooyeh/outboxed
+Project-URL: Documentation, https://github.com/amin-albooyeh/outboxed/tree/main/docs
+Project-URL: Issues, https://github.com/amin-albooyeh/outboxed/issues
+Author-email: Amin Albooyeh <amin.albooyeh@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: kafka
+Requires-Dist: confluent-kafka>=2.0; extra == 'kafka'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: sqs
+Requires-Dist: boto3>=1.34; extra == 'sqs'
+Description-Content-Type: text/markdown
+
+# outboxed
+
+The transactional outbox pattern for Python backends: reliably publish an
+event every time — and only when — a database write actually commits.
+
+## The problem
+
+Writing a database row and then publishing an event about it, as two
+separate steps, is the dual-write problem: a crash between them loses the
+event forever, and blind retries trade that for duplicate events instead.
+See [docs/dual-write-problem.md](docs/dual-write-problem.md).
+
+## The fix
+
+Enqueue the event as a row in an outbox table, in the same transaction as
+the business write. A separate relay process polls that table and does the
+actual publishing, with retries and deduplication handled on the relay
+side.
+
+```python
+from sqlalchemy import create_engine
+from outboxed import Outbox, Event
+from outboxed.models import metadata
+
+engine = create_engine("postgresql://...")
+metadata.create_all(engine)
+
+outbox = Outbox()
+
+with engine.begin() as conn:
+    # ... your business write ...
+    outbox.enqueue(conn, Event(topic="orders", payload='{"id": 1}'))
+```
+
+```python
+from outboxed import Relay
+from outboxed.backends.in_memory import InMemoryBackend
+
+relay = Relay(engine, backend=InMemoryBackend())
+relay.run_forever()
+```
+
+## The guarantee
+
+Once a transaction commits, its event is delivered at least once, and
+never silently dropped. This is verified by a chaos test
+(`tests/test_chaos_crash_recovery.py`) that runs in CI on every commit. See
+[docs/guarantees.md](docs/guarantees.md) for exact semantics.
+
+## Backends
+
+Kafka, Redis Streams, and SQS adapters ship built in, alongside an
+in-memory one for tests. The core has no required broker dependency — a
+backend is a small protocol (`outboxed.backends.base.Backend`) you can
+implement yourself. See [docs/backends.md](docs/backends.md).
+
+```bash
+pip install outboxed
+pip install "outboxed[kafka]"   # or [redis], [sqs]
+```
+
+## Status
+
+v0.1.0. Python 3.10+. MIT licensed.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

outboxed-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+outboxed/__init__.py,sha256=3Whv1AuH2EOHB8i241BiI12GiM2_OBV2ZNGCR6UMSDA,236
+outboxed/dedup.py,sha256=aGlwjM3qJGAue1uI8G8YkUul-sR_Hsi8ktDtLj-1Q9M,619
+outboxed/models.py,sha256=sJZH6F9M_bUYBGx7StnbJ-aG8cfe-Y76d1XGsUAstkQ,914
+outboxed/outbox.py,sha256=SS-CDaivkrmbmEcUxag-Wh3Ooeir5qB00zC1xjw6oow,752
+outboxed/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+outboxed/relay.py,sha256=GATinkrp6dxMp5IFGzvyD4QUGtk0g7LthJMEDTzofy4,2207
+outboxed/backends/__init__.py,sha256=L9erj3BlMotOTIcpoJmdw4SmK6_3_XqqJKaamvwXEnA,199
+outboxed/backends/base.py,sha256=EXqG4vZg2Zjmz1eQiIL8mxJAvWTH1GASSusGv8S4pss,377
+outboxed/backends/in_memory.py,sha256=-C-KoKgBVyOwsPcQeRUZJhdlHpxrDEEyDvser7bFX_A,594
+outboxed/backends/kafka.py,sha256=9sm3cOFyy7A6_3Lo2nEYeNoIP9nM8TDntR2-Wi6noM0,658
+outboxed/backends/redis_streams.py,sha256=87klQw-hquLFKKGl-6e8WgOhNfFipwcLXU5Ak0oRlDc,570
+outboxed/backends/sqs.py,sha256=iQwt3DEF1x_1eW9cUOpxrv1Yy6N1hhYnk5_o2ipEDfg,780
+outboxed-0.1.0.dist-info/METADATA,sha256=P-gKVInnoLR5E3k8-MyDB8tR6QEi1Vt9S2evCeu5IAk,2903
+outboxed-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+outboxed-0.1.0.dist-info/licenses/LICENSE,sha256=191kzGOjX1TzmWu8p4TT2jdQz0BnqmFybQKbzCaEL9I,1070
+outboxed-0.1.0.dist-info/RECORD,,

outboxed-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

outboxed-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amin Albooyeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.