txoutbox 0.2.2__tar.gz → 0.2.3__tar.gz

{txoutbox-0.2.2 → txoutbox-0.2.3}/.gitignore

@@ -19,3 +19,5 @@ wheels/
 *.db-wal
 *.db-shm
 pgdata/
+.coverage
+coverage.xml

{txoutbox-0.2.2 → txoutbox-0.2.3}/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-11-04
+
+### Fixed
+
+- `async with Relay(...)` hung forever when the body returned before the background
+  `run()` had started: `run()` reset the stop flag that `__aexit__` had just set.
+  `__aexit__` now cancels a relay task that has not started yet; `run()` semantics are
+  unchanged.
+- `PostgresStorage` with `visibility_delay` and strict ordering could publish messages
+  of one key out of order: `created_at` defaulted to `now()` (transaction start), so a
+  lower id could be younger than a higher one, and the ordering predicate did not hold
+  a row back behind an earlier row that was still too young. Both are fixed: the
+  predicate checks the age of earlier rows, and the schema uses `clock_timestamp()`.
+- `run(handle_signals=True)` raised `NotImplementedError` on exit on Windows, where the
+  event loop cannot install signal handlers: it tried to remove handlers it never added.
+
+### Changed
+
+- CI: Postgres 14/17/18, macOS and Windows, lowest direct dependency versions, branch
+  coverage gate, tests against the built wheel, workflow linting (actionlint, zizmor),
+  actions pinned by SHA with Dependabot. Releases now require green CI, a tag on `main`
+  and a changelog entry.
+
+### Upgrading
+
+- Tables created by earlier versions default `created_at` to `now()`. With that
+  default the predicate fix is not enough: a row whose transaction has not committed
+  is invisible to the check, so `visibility_delay` would have to exceed twice your
+  longest producer transaction. `schema_sql()` / `create_schema()` now end with
+  `ALTER TABLE ... ALTER COLUMN created_at SET DEFAULT clock_timestamp()` (a brief
+  metadata-only lock); run `create_schema()` once or add that statement to a migration.
+
 ## [0.2.2] - 2026-09-12
 
 ### Fixed
@@ -125,7 +157,8 @@ guarantees were fixed instead of patched.
   `Storage` implementation against the relay's expectations, including lease
   expiry, concurrent claims and strict per-key ordering.
 
-[Unreleased]: https://github.com/OsmnvAslan/txoutbox/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/OsmnvAslan/txoutbox/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/OsmnvAslan/txoutbox/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/OsmnvAslan/txoutbox/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/OsmnvAslan/txoutbox/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/OsmnvAslan/txoutbox/compare/v0.1.0...v0.2.0

{txoutbox-0.2.2 → txoutbox-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: txoutbox
-Version: 0.2.2
+Version: 0.2.3
 Summary: Storage-agnostic Transactional Outbox relay for asyncio: bring your own table, bring your own broker.
 Project-URL: Homepage, https://github.com/OsmnvAslan/txoutbox
 Project-URL: Repository, https://github.com/OsmnvAslan/txoutbox
@@ -221,7 +221,8 @@ RelayConfig(
 * **Insertion order is id order, not commit order.** On Postgres a `BIGSERIAL` id is assigned at `INSERT`;
   a transaction with a smaller id can commit later and be picked up after a larger one. If that matters
   for your keys, set `PostgresStorage(visibility_delay=timedelta(seconds=2))` to only claim rows older than
-  your longest producer transaction.
+  your longest producer transaction. Age is measured from `created_at`, which the schema sets to the
+  insert time (`clock_timestamp()`); for tables created before 0.2.3, `create_schema()` switches the default.
 * **Leases bound duplicates.** A round must finish inside its lease. `RelayConfig` warns at construction
   when `ceil(batch_size / concurrency) * publish_timeout` exceeds `lease`, and the relay warns after the
   fact when a round ran long. Leave `publish_timeout` on.

{txoutbox-0.2.2 → txoutbox-0.2.3}/README.md

@@ -192,7 +192,8 @@ RelayConfig(
 * **Insertion order is id order, not commit order.** On Postgres a `BIGSERIAL` id is assigned at `INSERT`;
   a transaction with a smaller id can commit later and be picked up after a larger one. If that matters
   for your keys, set `PostgresStorage(visibility_delay=timedelta(seconds=2))` to only claim rows older than
-  your longest producer transaction.
+  your longest producer transaction. Age is measured from `created_at`, which the schema sets to the
+  insert time (`clock_timestamp()`); for tables created before 0.2.3, `create_schema()` switches the default.
 * **Leases bound duplicates.** A round must finish inside its lease. `RelayConfig` warns at construction
   when `ceil(batch_size / concurrency) * publish_timeout` exceeds `lease`, and the relay warns after the
   fact when a round ran long. Leave `publish_timeout` on.

{txoutbox-0.2.2 → txoutbox-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "txoutbox"
-version = "0.2.2"
+version = "0.2.3"
 description = "Storage-agnostic Transactional Outbox relay for asyncio: bring your own table, bring your own broker."
 readme = "README.md"
 license = "MIT"
@@ -42,6 +42,7 @@ dev = [
   "asyncpg>=0.31.0",
   "pgserver>=0.1.4; python_version < '3.13'",
   "pytest-timeout>=2.3",
+  "pytest-cov>=7.1.0",
 ]
 examples = [
   "django>=5.0",
@@ -57,13 +58,22 @@ build-backend = "hatchling.build"
 packages = ["src/txoutbox"]
 
 [tool.hatch.build.targets.sdist]
-exclude = [".github", ".python-version", "uv.lock"]
+exclude = [".github", ".python-version", "uv.lock", "CLAUDE.md"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 testpaths = ["tests"]
 
+[tool.coverage.run]
+source = ["txoutbox"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]
+
 [tool.ruff]
 line-length = 100
 target-version = "py311"

{txoutbox-0.2.2 → txoutbox-0.2.3}/src/txoutbox/adapters/postgres.py

@@ -39,10 +39,12 @@ CREATE TABLE IF NOT EXISTS {table} (
     leased_by   TEXT,
     lease_until TIMESTAMPTZ,
     last_error  TEXT,
-    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
 );
 CREATE INDEX IF NOT EXISTS {name}_pending_idx ON {table} (id) WHERE status = 'pending';
 CREATE INDEX IF NOT EXISTS {name}_key_pending_idx ON {table} (key, id) WHERE status = 'pending';
+-- Tables created before 0.2.3 defaulted to now(), the transaction start (metadata-only change).
+ALTER TABLE {table} ALTER COLUMN created_at SET DEFAULT clock_timestamp();
 """
 
 NOTIFY_SQL = """
@@ -77,6 +79,9 @@ class PostgresStorage:
       are assigned at insert time, not commit time, so a long transaction can commit a
       lower id *after* a higher one was already delivered. A delay of a few seconds
       (longer than your slowest producing transaction) makes that reordering impossible.
+      Age is measured from ``created_at``, which must be the insert time
+      (``clock_timestamp()``), not the transaction start (``now()``); with strict
+      ordering, a row is also held back while an earlier row with its key is too young.
     * ``notify_channel`` adds an ``AFTER INSERT`` trigger to :meth:`schema_sql` that
       calls ``pg_notify``; pair it with :meth:`listen` to wake the relay instantly.
     """
@@ -403,10 +408,12 @@ class _Sql:
     """Statements pre-rendered for one table."""
 
     def __init__(self, table: str, strict_ordering: bool, visibility_delay: bool) -> None:
+        young = " OR p.created_at > now() - $4::interval" if visibility_delay else ""
         blocked = (
             " AND (o.key IS NULL OR NOT EXISTS ("
             f"SELECT 1 FROM {table} p WHERE p.key = o.key AND p.id < o.id"
-            " AND p.status = 'pending' AND (p.retry_at > now() OR p.lease_until > now())))"
+            " AND p.status = 'pending'"
+            f" AND (p.retry_at > now() OR p.lease_until > now(){young})))"
             if strict_ordering
             else ""
         )

{txoutbox-0.2.2 → txoutbox-0.2.3}/src/txoutbox/relay.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import inspect
 import logging
 import math
 import os
@@ -10,7 +11,7 @@ import signal
 import socket
 import time
 import uuid
-from collections.abc import Awaitable, Callable, Sequence
+from collections.abc import Awaitable, Callable, Coroutine, Sequence
 from dataclasses import dataclass, field
 from datetime import UTC, datetime, timedelta
 from types import TracebackType
@@ -190,11 +191,13 @@ class Relay:
 
         if handle_signals:
             for sig in (signal.SIGINT, signal.SIGTERM):
+                current = signal.getsignal(sig)
                 try:
-                    previous[sig] = signal.getsignal(sig)
                     loop.add_signal_handler(sig, on_signal)
-                except (NotImplementedError, RuntimeError):  # pragma: no cover - Windows
+                except (NotImplementedError, RuntimeError):  # Windows
                     log.warning("cannot install handler for %s", sig.name)
+                    continue
+                previous[sig] = current
         try:
             while not self._stopping:
                 try:
@@ -244,9 +247,19 @@ class Relay:
         tb: TracebackType | None,
     ) -> None:
         self.stop()
-        if self._task is not None:
-            await self._task
-            self._task = None
+        task, self._task = self._task, None
+        if task is None:
+            return
+        coro = task.get_coro()
+        if isinstance(coro, Coroutine) and inspect.getcoroutinestate(coro) == inspect.CORO_CREATED:
+            # run() has not started, so it would reset the stop flag; there is no round to finish.
+            task.cancel()
+        try:
+            await task  # not asyncio.wait: cancelling __aexit__ must reach the relay task
+        except asyncio.CancelledError:
+            current = asyncio.current_task()
+            if current is not None and current.cancelling():
+                raise
 
     # -- one round ---------------------------------------------------------------------
 

{txoutbox-0.2.2 → txoutbox-0.2.3}/tests/test_postgres.py

@@ -239,6 +239,49 @@ async def test_visibility_delay(pool) -> None:
     await _drop(pool, storage)
 
 
+async def test_visibility_delay_holds_back_successors_of_a_young_row(pool) -> None:
+    # A lower id can be younger than a higher one (rows from a table created before
+    # 0.2.3 used now(), the transaction start). The older row must still wait.
+    # A full second before the young row is visible keeps this stable on slow CI.
+    storage = await _make(pool, visibility_delay=timedelta(seconds=1))
+    t = storage.qualified_table
+    await pool.execute(f"INSERT INTO {t} (topic, key, payload) VALUES ('t', 'k', 'young')")
+    await pool.execute(
+        f"INSERT INTO {t} (topic, key, payload, created_at)"
+        " VALUES ('t', 'k', 'old', now() - interval '5 seconds')"
+    )
+    assert list(await storage.claim(batch_size=10, lease=LEASE, worker_id="w")) == []
+    await asyncio.sleep(1.1)
+    got = await storage.claim(batch_size=10, lease=LEASE, worker_id="w")
+    assert [m.payload for m in got] == [b"young", b"old"]
+    await _drop(pool, storage)
+
+
+async def test_created_at_is_the_insert_time_not_the_transaction_start(pool) -> None:
+    storage = await _make(pool)
+    async with pool.acquire() as conn, conn.transaction():
+        await storage.insert(conn, "t", b"first")
+        await asyncio.sleep(0.05)
+        await storage.insert(conn, "t", b"second")
+    got = await storage.claim(batch_size=10, lease=LEASE, worker_id="w")
+    assert got[1].created_at > got[0].created_at  # type: ignore[operator]
+    await _drop(pool, storage)
+
+
+async def test_create_schema_upgrades_a_pre_0_2_3_created_at_default(pool) -> None:
+    storage = await _make(pool)
+    t = storage.qualified_table
+    await pool.execute(f"ALTER TABLE {t} ALTER COLUMN created_at SET DEFAULT now()")
+    await storage.create_schema()
+    default = await pool.fetchval(
+        "SELECT column_default FROM information_schema.columns"
+        " WHERE table_name = $1 AND column_name = 'created_at'",
+        storage.table,
+    )
+    assert default == "clock_timestamp()"
+    await _drop(pool, storage)
+
+
 def test_visibility_delay_validation() -> None:
     with pytest.raises(ValueError):
         PostgresStorage(object(), visibility_delay=timedelta(seconds=-1))  # type: ignore[arg-type]

{txoutbox-0.2.2 → txoutbox-0.2.3}/tests/test_relay.py

@@ -1,5 +1,6 @@
 import asyncio
 import signal
+import sys
 import time
 from datetime import UTC, datetime, timedelta
 
@@ -8,6 +9,8 @@ import pytest
 from txoutbox import Backoff, Hooks, OutboxMessage, Relay, RelayConfig
 from txoutbox.adapters.memory import MemoryPublisher, MemoryStorage, Status
 
+posix_signals = pytest.mark.skipif(sys.platform == "win32", reason="POSIX signals")
+
 
 def cfg(**kw) -> RelayConfig:
     base = dict(poll_min=0.01, poll_max=0.05, backoff=Backoff(base=timedelta(seconds=10), jitter=0))
@@ -198,6 +201,56 @@ async def test_context_manager_and_wake() -> None:
     assert len(publisher.published) == 1
 
 
+async def test_context_manager_exits_when_the_body_returns_at_once() -> None:
+    # stop() from __aexit__ lands before the background run() has started.
+    async with Relay(MemoryStorage(), MemoryPublisher(), config=cfg()):
+        pass
+
+
+async def test_cancelling_context_exit_cancels_the_relay_task() -> None:
+    storage = MemoryStorage()
+    await storage.add("t", b"x")
+    relay = Relay(storage, MemoryPublisher(delay=5), config=cfg())
+
+    async def app() -> None:
+        async with relay:
+            await asyncio.sleep(0.05)  # a round with a slow publish is in flight
+
+    outer = asyncio.create_task(app())
+    await asyncio.sleep(0.02)
+    (inner,) = [t for t in asyncio.all_tasks() if t.get_name().startswith("txoutbox-relay")]
+    await asyncio.sleep(0.08)  # outer is inside __aexit__, waiting for the round
+    outer.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await outer
+    assert inner.cancelled()
+
+
+async def test_stop_after_a_cancelled_run_does_not_stick() -> None:
+    storage, publisher = MemoryStorage(), MemoryPublisher()
+    relay = Relay(storage, publisher, config=cfg())
+    task = asyncio.create_task(relay.run())
+    await asyncio.sleep(0.02)
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    relay.stop()  # a late shutdown hook
+    await storage.add("t", b"x")
+    task = asyncio.create_task(relay.run())
+    while not publisher.published:
+        await asyncio.sleep(0.005)
+    relay.stop()
+    await asyncio.wait_for(task, 1)
+
+
+async def test_stop_ends_every_loop_sharing_a_relay() -> None:
+    relay = Relay(MemoryStorage(), MemoryPublisher(), config=cfg())
+    loops = [asyncio.create_task(relay.run()) for _ in range(2)]
+    await asyncio.sleep(0.02)
+    relay.stop()
+    await asyncio.wait_for(asyncio.gather(*loops), 1)
+
+
 async def test_storage_errors_do_not_kill_the_loop() -> None:
     calls = 0
 
@@ -245,6 +298,7 @@ async def test_hook_exceptions_are_swallowed() -> None:
     assert result.published == 1
 
 
+@posix_signals
 async def test_signal_handler_stops_run() -> None:
     storage, publisher = MemoryStorage(), MemoryPublisher()
     relay = Relay(storage, publisher, config=cfg())
@@ -352,6 +406,7 @@ async def test_on_round_hook_and_failure_summary(caplog: pytest.LogCaptureFixtur
     logging.getLogger("txoutbox").setLevel(logging.CRITICAL)
 
 
+@posix_signals
 async def test_second_signal_cancels_the_round_and_returns_quietly() -> None:
     storage = MemoryStorage()
     await storage.add("t", b"x")
@@ -366,6 +421,7 @@ async def test_second_signal_cancels_the_round_and_returns_quietly() -> None:
     assert signal.getsignal(signal.SIGTERM) is signal.SIG_DFL
 
 
+@posix_signals
 async def test_plain_signal_handler_is_restored() -> None:
     hits: list[int] = []
     previous = signal.signal(signal.SIGTERM, lambda signum, frame: hits.append(signum))
@@ -382,6 +438,7 @@ async def test_plain_signal_handler_is_restored() -> None:
         signal.signal(signal.SIGTERM, previous)
 
 
+@posix_signals
 async def test_loop_signal_handler_is_not_clobbered_into_a_noop() -> None:
     """We cannot restore a loop-level handler, but we must not leave asyncio's C stub behind."""
     loop = asyncio.get_running_loop()
@@ -450,6 +507,7 @@ async def test_stop_cuts_the_storage_error_pause_short() -> None:
     await asyncio.wait_for(task, 1)
 
 
+@posix_signals
 async def test_two_signals_during_storage_error_pause_return_quietly() -> None:
     relay = Relay(_DownStorage(), MemoryPublisher(), config=cfg(storage_error_delay=30))
     task = asyncio.create_task(relay.run(handle_signals=True))
@@ -467,3 +525,19 @@ async def test_external_cancellation_still_propagates_from_the_pause() -> None:
     task.cancel()
     with pytest.raises(asyncio.CancelledError):
         await task
+
+
+async def test_handle_signals_without_loop_support_runs_and_exits(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Windows' ProactorEventLoop raises NotImplementedError for both calls.
+    loop = asyncio.get_running_loop()
+
+    def unsupported(*args: object) -> None:
+        raise NotImplementedError
+
+    monkeypatch.setattr(loop, "add_signal_handler", unsupported)
+    monkeypatch.setattr(loop, "remove_signal_handler", unsupported)
+    relay = Relay(MemoryStorage(), MemoryPublisher(), config=cfg())
+    loop.call_later(0.05, relay.stop)
+    await asyncio.wait_for(relay.run(handle_signals=True), 1)