outboxed 0.1.0__tar.gz

outboxed-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Type check
+        run: mypy src
+
+      - name: Unit and integration tests
+        run: pytest -v

outboxed-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

outboxed-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+.DS_Store

outboxed-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-05
+
+### Added
+
+- Initial project scaffold: `Outbox` (write side), `Relay` (read side),
+  `DeliveryTracker` (dedup), and `Backend` protocol.
+- Built-in backends: in-memory, Kafka, Redis Streams, SQS.
+- Chaos test for crash/recovery semantics.
+- Docs: the dual-write problem, delivery guarantees, writing a backend.
+- FastAPI order-service example.

outboxed-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Running checks locally
+
+```bash
+ruff check src tests
+mypy src
+pytest -v
+```
+
+Integration tests for a specific broker (e.g. `tests/backends/test_kafka.py`)
+are skipped unless that broker's environment variable is set. You can bring
+up local infra with `docker compose -f examples/docker-compose.yml up`.
+
+## Adding a backend
+
+See [docs/backends.md](docs/backends.md) for the `Backend` protocol and
+guidelines for a new adapter.
+
+## Pull requests
+
+- Keep the core (`outbox.py`, `relay.py`, `dedup.py`, `models.py`) free of
+  any specific broker's SDK dependency.
+- Add or update tests for any behavior change, and update
+  [CHANGELOG.md](CHANGELOG.md) under `[Unreleased]`.

outboxed-0.1.0/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.

outboxed-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,68 @@
+# 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/docs/backends.md

@@ -0,0 +1,42 @@
+# Writing a new Backend adapter
+
+A backend is anything that implements the `Backend` protocol in
+`outboxed/backends/base.py`:
+
+```python
+from typing import Protocol
+
+class Backend(Protocol):
+    def publish(self, *, topic: str, key: str | None, payload: str) -> None:
+        ...
+```
+
+That's the entire contract. `publish` is called once per outbox row, in
+creation order, by the relay. Raise an exception to signal failure — the
+relay will leave that row undelivered and retry it on the next poll.
+
+## Example: a minimal webhook backend
+
+```python
+import httpx
+
+class WebhookBackend:
+    def __init__(self, url: str):
+        self._url = url
+
+    def publish(self, *, topic: str, key: str | None, payload: str) -> None:
+        response = httpx.post(self._url, json={"topic": topic, "key": key, "payload": payload})
+        response.raise_for_status()
+```
+
+## Guidelines
+
+- Keep broker SDK imports inside the adapter module, not in `outboxed`'s
+  core, so the core has no required dependency on any specific broker.
+- Don't swallow exceptions — let them propagate so the relay retries.
+- If your broker needs a flush/sync step (as Kafka producers do), do it
+  inside `publish` so the call only returns once delivery is confirmed (or
+  failed) to the broker.
+- Add your adapter under `src/outboxed/backends/`, with an optional extra
+  in `pyproject.toml` if it needs a broker SDK, and a corresponding test
+  under `tests/backends/`.

outboxed-0.1.0/docs/dual-write-problem.md

@@ -0,0 +1,50 @@
+# The dual-write problem
+
+A common backend shape is: write a row to the database, then publish an
+event about it (an order placed, a payment captured, a user created). Doing
+these as two separate operations is the dual-write problem.
+
+```
+   business write          publish event
+  ┌───────────────┐      ┌─────────────────┐
+  │  INSERT order  │ ---> │  producer.send   │
+  └───────────────┘      └─────────────────┘
+        commits                 ??? crash here means the
+                                 event is lost forever
+```
+
+If the process crashes between the database commit and the publish call,
+the event is lost forever, and nothing else in the system knows the write
+ever happened. Retrying blindly trades that failure for the opposite one:
+duplicate events on every retry that succeeds after a delayed
+acknowledgment.
+
+## The fix
+
+Never make that second call directly. Instead, insert the event as a row in
+an "outbox" table, in the *same database transaction* as the business
+write:
+
+```
+┌─────────────────────────────┐
+│          transaction          │
+│  INSERT order                │
+│  INSERT outbox_entries row   │
+└─────────────────────────────┘
+          commits atomically
+                 │
+                 v
+      ┌───────────────────┐
+      │   relay (separate   │
+      │   process) polls    │
+      │   outbox_entries    │
+      └───────────────────┘
+                 │
+                 v
+         publish to broker
+```
+
+A separate relay process polls that table and does the actual publishing,
+with retries and deduplication handled entirely on the relay side —
+decoupled from the request path. See [guarantees.md](guarantees.md) for the
+exact delivery semantics this gives you.

outboxed-0.1.0/docs/guarantees.md

@@ -0,0 +1,37 @@
+# Delivery guarantees
+
+outboxed is built around one explicit claim:
+
+> Once a transaction commits, its event is delivered at least once, and
+> never silently dropped.
+
+## What this means precisely
+
+- **Write side**: `Outbox.enqueue()` only has an effect if the surrounding
+  transaction commits. A rollback removes the row along with everything
+  else in that transaction. There is no window where the write succeeds but
+  the event is lost, because they're the same atomic operation.
+- **Relay side**: the relay polls for undelivered rows, dispatches them to
+  the backend, and only then marks them delivered. If the relay process
+  dies after dispatch but before marking the row delivered, the row is
+  redelivered on the next poll.
+- **At-least-once, not exactly-once, at the transport layer**: a crash in
+  that window means the backend may see the same event twice. outboxed's
+  `DeliveryTracker` filters those duplicates by event id before they reach
+  your handler, so the event is *observed* exactly once downstream even
+  though the broker may have transported it more than once.
+
+## How this is tested
+
+`tests/test_chaos_crash_recovery.py` starts a relay, kills the process
+(simulated) mid-batch at a randomized point, restarts it, and asserts that
+every committed event eventually reaches the backend, and that none of them
+are observed twice. That test runs in CI on every commit — it is not a
+README promise.
+
+## What outboxed does not guarantee
+
+- **Ordering across topics**: ordering is only guaranteed within a single
+  topic/key, and only as strongly as the underlying broker preserves it.
+- **Delivery latency**: this is a polling relay, not a push system. Latency
+  is bounded by the poll interval, not by the broker's own latency.

outboxed-0.1.0/docs/index.md

@@ -0,0 +1,45 @@
+# outboxed
+
+The transactional outbox pattern for Python backends: reliably publish an
+event every time — and only when — a database write actually commits.
+
+## Install
+
+```bash
+pip install outboxed
+# or, with a broker adapter's optional extra:
+pip install "outboxed[kafka]"
+```
+
+## Quickstart
+
+```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, e.g. inserting an order row ...
+    outbox.enqueue(conn, Event(topic="orders", payload='{"id": 1}'))
+```
+
+Run a relay process separately to deliver enqueued events to a backend:
+
+```python
+from outboxed import Relay
+from outboxed.backends.in_memory import InMemoryBackend
+
+relay = Relay(engine, backend=InMemoryBackend())
+relay.run_forever()
+```
+
+## Further reading
+
+- [The dual-write problem](dual-write-problem.md)
+- [Delivery guarantees](guarantees.md)
+- [Writing a backend adapter](backends.md)

outboxed-0.1.0/examples/docker-compose.yml

@@ -0,0 +1,23 @@
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_USER: outboxed
+      POSTGRES_PASSWORD: outboxed
+      POSTGRES_DB: outboxed
+    ports:
+      - "5432:5432"
+
+  kafka:
+    image: confluentinc/cp-kafka:7.6.0
+    environment:
+      KAFKA_NODE_ID: 1
+      KAFKA_PROCESS_ROLES: broker,controller
+      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
+      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
+      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
+      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
+      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
+      CLUSTER_ID: outboxed-local-cluster
+    ports:
+      - "9092:9092"

outboxed-0.1.0/examples/fastapi_order_service/main.py

@@ -0,0 +1,62 @@
+"""A minimal order API using outboxed end-to-end.
+
+Run Postgres via ../docker-compose.yml, then:
+
+    uvicorn main:app --reload
+
+POST /orders inserts an order row and enqueues an "order.placed" event in
+the same transaction. Run relay.py separately to deliver it.
+"""
+
+from __future__ import annotations
+
+import json
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+from sqlalchemy import Column, Integer, MetaData, String, Table, create_engine
+
+from outboxed import Event, Outbox
+from outboxed.models import metadata as outbox_metadata
+
+DATABASE_URL = "postgresql://outboxed:outboxed@localhost:5432/outboxed"
+
+engine = create_engine(DATABASE_URL)
+app_metadata = MetaData()
+
+orders_table = Table(
+    "orders",
+    app_metadata,
+    Column("id", Integer, primary_key=True, autoincrement=True),
+    Column("item", String, nullable=False),
+)
+
+outbox = Outbox()
+app = FastAPI(title="outboxed example: order service")
+
+
+class OrderRequest(BaseModel):
+    item: str
+
+
+@app.on_event("startup")
+def create_tables() -> None:
+    app_metadata.create_all(engine)
+    outbox_metadata.create_all(engine)
+
+
+@app.post("/orders")
+def place_order(order: OrderRequest) -> dict:
+    with engine.begin() as conn:
+        result = conn.execute(orders_table.insert().values(item=order.item))
+        order_id = result.inserted_primary_key[0]
+
+        outbox.enqueue(
+            conn,
+            Event(topic="order.placed", key=str(order_id), payload=json.dumps({
+                "order_id": order_id,
+                "item": order.item,
+            })),
+        )
+
+    return {"id": order_id, "item": order.item}

outboxed-0.1.0/examples/fastapi_order_service/relay.py

@@ -0,0 +1,26 @@
+"""Standalone relay process for the order service example.
+
+Run alongside main.py:
+
+    python relay.py
+"""
+
+from sqlalchemy import create_engine
+
+from outboxed import Relay
+from outboxed.backends.in_memory import InMemoryBackend
+
+DATABASE_URL = "postgresql://outboxed:outboxed@localhost:5432/outboxed"
+
+
+def main() -> None:
+    engine = create_engine(DATABASE_URL)
+    backend = InMemoryBackend()  # swap for KafkaBackend/RedisStreamsBackend/SQSBackend
+    relay = Relay(engine, backend)
+
+    print("relay running, polling for outbox entries...")
+    relay.run_forever()
+
+
+if __name__ == "__main__":
+    main()

outboxed-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "outboxed"
+version = "0.1.0"
+description = "Transactional outbox pattern for Python backends"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Amin Albooyeh", email = "amin.albooyeh@gmail.com" },
+]
+dependencies = [
+    "SQLAlchemy>=2.0",
+]
+
+[project.optional-dependencies]
+kafka = ["confluent-kafka>=2.0"]
+redis = ["redis>=5.0"]
+sqs = ["boto3>=1.34"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.9",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/amin-albooyeh/outboxed"
+Documentation = "https://github.com/amin-albooyeh/outboxed/tree/main/docs"
+Issues = "https://github.com/amin-albooyeh/outboxed/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/outboxed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["outboxed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

outboxed-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/backends/test_in_memory.py

@@ -0,0 +1,15 @@
+"""The in-memory backend just records what it's given."""
+
+from outboxed.backends.in_memory import InMemoryBackend
+
+
+def test_publish_records_message():
+    backend = InMemoryBackend()
+
+    backend.publish(topic="orders", key="order-1", payload='{"id": 1}')
+
+    assert len(backend.messages) == 1
+    message = backend.messages[0]
+    assert message.topic == "orders"
+    assert message.key == "order-1"
+    assert message.payload == '{"id": 1}'

outboxed-0.1.0/tests/backends/test_kafka.py

@@ -0,0 +1,14 @@
+"""Kafka backend tests — skipped unless a broker is available in CI."""
+
+import os
+
+import pytest
+
+pytestmark = pytest.mark.skipif(
+    not os.environ.get("KAFKA_BOOTSTRAP_SERVERS"),
+    reason="requires a running Kafka broker (set KAFKA_BOOTSTRAP_SERVERS)",
+)
+
+
+def test_publish_sends_to_topic():
+    pytest.skip("integration test: implement once a Kafka broker is wired into CI")

outboxed-0.1.0/tests/backends/test_redis_streams.py

@@ -0,0 +1,40 @@
+"""Unit tests for the Redis Streams backend, using a fake client (no broker needed)."""
+
+from outboxed.backends.redis_streams import RedisStreamsBackend
+
+
+class FakeRedisClient:
+    def __init__(self):
+        self.calls = []
+
+    def xadd(self, stream, fields):
+        self.calls.append((stream, fields))
+
+
+def test_publish_sends_to_stream():
+    client = FakeRedisClient()
+    backend = RedisStreamsBackend(client)
+
+    backend.publish(topic="orders", key="order-1", payload='{"id": 1}')
+
+    assert client.calls == [("orders", {"key": "order-1", "payload": '{"id": 1}'})]
+
+
+def test_publish_applies_stream_prefix():
+    client = FakeRedisClient()
+    backend = RedisStreamsBackend(client, stream_prefix="prod.")
+
+    backend.publish(topic="orders", key="order-1", payload="payload")
+
+    stream, _ = client.calls[0]
+    assert stream == "prod.orders"
+
+
+def test_publish_defaults_missing_key_to_empty_string():
+    client = FakeRedisClient()
+    backend = RedisStreamsBackend(client)
+
+    backend.publish(topic="orders", key=None, payload="payload")
+
+    _, fields = client.calls[0]
+    assert fields["key"] == ""

outboxed-0.1.0/tests/backends/test_sqs.py

@@ -0,0 +1,45 @@
+"""Unit tests for the SQS backend, using a fake client (no AWS needed)."""
+
+import pytest
+
+from outboxed.backends.sqs import SQSBackend
+
+
+class FakeSQSClient:
+    def __init__(self):
+        self.calls = []
+
+    def send_message(self, **kwargs):
+        self.calls.append(kwargs)
+
+
+def test_publish_sends_to_mapped_queue_url():
+    client = FakeSQSClient()
+    backend = SQSBackend(client, queue_urls={"orders": "https://sqs.example/orders"})
+
+    backend.publish(topic="orders", key="order-1", payload='{"id": 1}')
+
+    assert client.calls == [
+        {
+            "QueueUrl": "https://sqs.example/orders",
+            "MessageBody": '{"id": 1}',
+            "MessageGroupId": "order-1",
+        }
+    ]
+
+
+def test_publish_omits_message_group_id_when_key_is_none():
+    client = FakeSQSClient()
+    backend = SQSBackend(client, queue_urls={"orders": "https://sqs.example/orders"})
+
+    backend.publish(topic="orders", key=None, payload="payload")
+
+    assert "MessageGroupId" not in client.calls[0]
+
+
+def test_publish_raises_on_unmapped_topic():
+    client = FakeSQSClient()
+    backend = SQSBackend(client, queue_urls={"orders": "https://sqs.example/orders"})
+
+    with pytest.raises(KeyError):
+        backend.publish(topic="unknown", key=None, payload="payload")

outboxed-0.1.0/tests/test_chaos_crash_recovery.py

@@ -0,0 +1,59 @@
+"""Kill the relay mid-batch and assert no loss and no duplicate delivery.
+
+This is the test behind outboxed's core guarantee: once a transaction
+commits, its event is delivered at least once and is observed exactly once
+by the backend's handler (the dedup layer filters transport-level repeats).
+"""
+
+import random
+
+from sqlalchemy import create_engine
+
+from outboxed.backends.in_memory import InMemoryBackend
+from outboxed.dedup import DeliveryTracker
+from outboxed.models import Event, metadata
+from outboxed.outbox import Outbox
+from outboxed.relay import Relay
+
+
+def make_engine():
+    engine = create_engine("sqlite:///:memory:")
+    metadata.create_all(engine)
+    return engine
+
+
+def test_crash_mid_batch_then_restart_delivers_everything_once(monkeypatch):
+    engine = make_engine()
+    outbox = Outbox()
+    backend = InMemoryBackend()
+    tracker = DeliveryTracker()
+
+    event_count = 20
+    with engine.begin() as conn:
+        for i in range(event_count):
+            outbox.enqueue(conn, Event(topic="orders", payload=str(i)))
+
+    crash_after = random.randint(1, event_count - 1)
+    publish_calls = {"count": 0}
+    real_publish = backend.publish
+
+    def flaky_publish(**kwargs):
+        if publish_calls["count"] == crash_after:
+            raise RuntimeError("simulated crash mid-batch")
+        publish_calls["count"] += 1
+        real_publish(**kwargs)
+
+    monkeypatch.setattr(backend, "publish", flaky_publish)
+
+    relay = Relay(engine, backend, batch_size=1, tracker=tracker)
+    for _ in range(event_count):
+        try:
+            relay.poll_once()
+        except RuntimeError:
+            monkeypatch.setattr(backend, "publish", real_publish)
+
+    relay.poll_once()
+
+    delivered_payloads = [m.payload for m in backend.messages]
+    assert sorted(delivered_payloads, key=int) == [str(i) for i in range(event_count)]
+    assert len(delivered_payloads) == len(set(delivered_payloads))

outboxed-0.1.0/tests/test_dedup.py

@@ -0,0 +1,13 @@
+"""A redelivered event id must never reach the backend's handler twice."""
+
+from outboxed.dedup import DeliveryTracker
+
+
+def test_mark_delivered_then_is_duplicate():
+    tracker = DeliveryTracker()
+    assert not tracker.is_duplicate("evt-1")
+
+    tracker.mark_delivered("evt-1")
+
+    assert tracker.is_duplicate("evt-1")
+    assert not tracker.is_duplicate("evt-2")

outboxed-0.1.0/tests/test_outbox_enqueue.py

@@ -0,0 +1,44 @@
+"""Same-transaction write semantics: commit keeps the event, rollback drops it."""
+
+from sqlalchemy import create_engine, select
+
+from outboxed.models import Event, metadata, outbox_table
+from outboxed.outbox import Outbox
+
+
+def make_engine():
+    engine = create_engine("sqlite:///:memory:")
+    metadata.create_all(engine)
+    return engine
+
+
+def test_enqueue_is_visible_after_commit():
+    engine = make_engine()
+    outbox = Outbox()
+    event = Event(topic="orders", payload='{"id": 1}')
+
+    with engine.begin() as conn:
+        outbox.enqueue(conn, event)
+
+    with engine.connect() as conn:
+        rows = conn.execute(select(outbox_table)).fetchall()
+
+    assert len(rows) == 1
+    assert rows[0].id == event.id
+    assert rows[0].delivered_at is None
+
+
+def test_enqueue_is_rolled_back_with_the_transaction():
+    engine = make_engine()
+    outbox = Outbox()
+    event = Event(topic="orders", payload='{"id": 1}')
+
+    with engine.connect() as conn:
+        trans = conn.begin()
+        outbox.enqueue(conn, event)
+        trans.rollback()
+
+    with engine.connect() as conn:
+        rows = conn.execute(select(outbox_table)).fetchall()
+
+    assert rows == []

outboxed-0.1.0/tests/test_relay_delivery.py

@@ -0,0 +1,46 @@
+"""Polling, ordering, and marking entries delivered."""
+
+from sqlalchemy import create_engine
+
+from outboxed.backends.in_memory import InMemoryBackend
+from outboxed.models import Event, metadata
+from outboxed.outbox import Outbox
+from outboxed.relay import Relay
+
+
+def make_engine():
+    engine = create_engine("sqlite:///:memory:")
+    metadata.create_all(engine)
+    return engine
+
+
+def test_poll_once_delivers_in_order():
+    engine = make_engine()
+    outbox = Outbox()
+    backend = InMemoryBackend()
+    relay = Relay(engine, backend)
+
+    with engine.begin() as conn:
+        outbox.enqueue(conn, Event(topic="orders", payload="1"))
+        outbox.enqueue(conn, Event(topic="orders", payload="2"))
+
+    delivered = relay.poll_once()
+
+    assert delivered == 2
+    assert [m.payload for m in backend.messages] == ["1", "2"]
+
+
+def test_poll_once_skips_already_delivered_entries():
+    engine = make_engine()
+    outbox = Outbox()
+    backend = InMemoryBackend()
+    relay = Relay(engine, backend)
+
+    with engine.begin() as conn:
+        outbox.enqueue(conn, Event(topic="orders", payload="1"))
+
+    relay.poll_once()
+    delivered_again = relay.poll_once()
+
+    assert delivered_again == 0
+    assert len(backend.messages) == 1