You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 306ad25
Browse filesBrowse the repository at this point in the historyBrowse files
refactor(message): canonical Outcome sum type on OutboxInnerMessage (#145)
Replace the three loosely-coupled intent fields (terminal_failure_reason,
pending_delay_seconds, state_set) with one canonical `outcome` holding a sum type
Ack | Retry(delay) | Terminal(reason). Success becomes an explicit Ack() instead
of the implicit "all None" state, and "reason and delay both set" is now
unrepresentable.
Option A (surgical): outcome is the single canonical field; the three old
attributes become read-only @Property views of it, so the five other subscriber
readers and every read-assertion in the tests are unchanged. dispatch_one matches
on the disjoint variant -- which dissolves the terminal-before-retry ordering
invariant (mutually exclusive variants have no ordering dependence). Only the 12
test sites that *wrote* the old fields change, to set `outcome`.
DLQFailureReason (the public wire contract) is unchanged -- it is now
Terminal.reason's type. dlq_table=None stays bit-for-bit identical.
Truth-home promotion in architecture/dlq.md + the CLAUDE.md DLQ invariant line.
Behavior-preserving. Full suite green (603 passed, coverage 100%), lint + ty
+ check-planning clean.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: CLAUDE.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,7 +30,7 @@ The package wires a FastStream `Broker`/`Registrator`/`Subscriber` trio whose tr
30
30
-**Relay to foreign broker** — native FastStream publisher-chain (`@kafka_pub @broker_outbox.subscriber("q")`); bad chain composition raises `_OutboxConfigError` and retries via **lease expiry**, not the retry strategy. → [relay.md](architecture/relay.md)
31
31
-**Timers** — `activate_in`/`activate_at` are mutually exclusive and gate eligibility; `timer_id` is "at most one *live* row per `(queue, timer_id)`", not a global idempotency key; `cancel_timer`'s `acquired_token IS NULL` guard is load-bearing. → [timers.md](architecture/timers.md)
32
32
-**User-owned schema** — caller owns the table; the three partial indexes + the `<table>_lease_ck` CHECK are load-bearing; **no `state` column**; `validate_schema()` is opt-in. → [schema.md](architecture/schema.md)
33
-
-**Opt-in DLQ** — with `dlq_table=None` every path is **bit-for-bit identical**; the `DLQFailureReason``Literal` is the **public contract** (changes are API-breaking); branch on `terminal_failure_reason`**before**`last_exception`. → [dlq.md](architecture/dlq.md)
33
+
-**Opt-in DLQ** — with `dlq_table=None` every path is **bit-for-bit identical**; the `DLQFailureReason``Literal` is the **public contract** (changes are API-breaking); delivery records one disjoint `Outcome` (`Ack`/`Retry`/`Terminal`) that `dispatch_one` matches on (`terminal_failure_reason`/`pending_delay_seconds`/`state_set` are read-only views). → [dlq.md](architecture/dlq.md)
34
34
-**Two-loop subscriber + lease-token invariant** — fetch loop + N worker loops; **every terminal write filters on `acquired_token`** (a stale write finds `rowcount==0` and is dropped) — any new fetch/terminal path must preserve this; `AckPolicy.ACK_FIRST` is rejected at registration; `lease_ttl_seconds` must exceed handler P99. → [subscriber.md](architecture/subscriber.md)
35
35
-**Drain on stop** — custom `stop()` overrides + the `dispatch_one` shutdown-race guard prevent row leaks on rolling deploys; **re-check both overrides when touching shutdown**. → [drain.md](architecture/drain.md)
36
36
-**Test broker** — `TestOutboxBroker` swaps in `FakeOutboxClient`; sync mode dispatches the handler before `publish` returns; `test_client_contract.py` pins real-vs-fake parity. → [test-broker.md](architecture/test-broker.md)
The CTE's `RETURNING` / `INSERT` / `SELECT` column lists are not hand-written — they derive from `_DLQ_PROJECTION` (the `(outbox_col, dlq_col)` pairs copied verbatim) plus `_DLQ_INJECTED_COLUMNS` (`failure_reason`, `last_exception`, supplied by the caller) in `schema.py`. The fake (`FakeOutboxClient.delete_with_lease`) builds its audit dict from the same constants, so the two substrates can't drift on which columns the archive carries — a DLQ column change is one edit in `schema.py`, verified across both adapters by `tests/test_client_contract.py`. `failed_at` is not in the projection; it rides the DLQ column's `server_default`.
14
14
15
-
## `terminal_failure_reason` routing
15
+
## Terminal-outcome routing
16
16
17
-
`OutboxInnerMessage.terminal_failure_reason` is set on the three failure paths:
17
+
`OutboxInnerMessage.outcome` records a single canonical `Outcome` (`message.py`): `Ack` (success), `Retry(delay_seconds)`, or `Terminal(reason)`. The three failure paths record a `Terminal`:
`_flush_terminal` reads it to decide whether to build a DLQ payload; `dispatch_one` also reads it to pick the `nacked_terminal(reason=…)` tag value. **Branch on `terminal_failure_reason` BEFORE `last_exception`**, so manual `await msg.reject()` (no exception raised) routes correctly to `nacked_terminal(reason="rejected")`instead of the previously-incorrect `acked`. Success (`_ack`) leaves the field None; success rows never touch the DLQ.
23
+
`terminal_failure_reason` is now a **read-only view** of `outcome` (`Terminal.reason`, else `None`), so existing readers are unchanged: `_flush_terminal` reads it to decide whether to build a DLQ payload; the `nacked_terminal(reason=…)` tag value comes from the same reason. `dispatch_one`**matches on the disjoint `Outcome` variant** — `Terminal → nacked_terminal`, `Retry → reschedule`, `Ack → delete`. Because the variants are mutually exclusive there is no ordering dependence between the arms: a manual `await msg.reject()` (no exception raised) records `Terminal("rejected")`directly, independent of `last_exception`. Success (`_ack` → `Ack`) leaves `terminal_failure_reason` None; success rows never touch the DLQ.
24
24
25
25
**The `DLQFailureReason``Literal` type (`message.py`) is the public contract** for this string — operator queries and dashboard labels key off these values, so changing them is API-breaking.
summary: Replaced OutboxInnerMessage's terminal_failure_reason / pending_delay_seconds / state_set fields with one canonical Outcome sum type (Ack | Retry | Terminal); the old attributes become read-only views. Behavior-preserving; dissolves the terminal-before-retry ordering invariant.
3
+
---
4
+
5
+
# Change: Canonical Outcome sum type on OutboxInnerMessage
6
+
7
+
**Lane:** lightweight. A behavior-preserving refactor of the load-bearing
8
+
terminal/dispatch path that reshapes an internal representation and dissolves a
9
+
documented ordering invariant — recorded here so the change is legible.
10
+
11
+
## Goal
12
+
13
+
Deepen `OutboxInnerMessage`: `ack`/`nack`/`reject`/`allow_delivery` recorded delivery
14
+
intent across three loosely-coupled fields (`terminal_failure_reason`,
15
+
`pending_delay_seconds`, `state_set`), where "success" was the implicit "all None"
16
+
state and "reason and delay both set" was representable-but-never-used. Replace them
17
+
with one canonical `Outcome` sum type so success is an explicit variant and the
18
+
impossible combination is unrepresentable.
19
+
20
+
## Approach (Option A — canonical outcome + derived views)
0 commit comments