|
| 1 | +# faststream-outbox 0.12.0 — architecture-deepening pass (internal refactors, no production behavior change) |
| 2 | + |
| 3 | +**Minor release.** Every change to the installed package's **production** runtime is an |
| 4 | +**internal refactor** — the producer, subscriber, lease/terminal-write, timer, DLQ, and |
| 5 | +validation behavior are identical to 0.11.0, verified by the unchanged suite at 100% |
| 6 | +coverage across Python 3.11–3.14. The batch came out of an architecture review that |
| 7 | +deepened shallow modules, named duplicated rules, and removed a dead field. The **one** |
| 8 | +behavior change is test-broker-only (a tightened `session` argument, below), which is why |
| 9 | +this is a minor rather than a patch. Drop-in for production code. |
| 10 | + |
| 11 | +## Breaking changes |
| 12 | + |
| 13 | +- **`TestOutboxBroker`: `cancel_timer` / `fetch_unprocessed` now require `session`.** These |
| 14 | + two methods moved behind the `AbstractOutboxClient` seam (see refactors below). Under the |
| 15 | + **test broker** they previously accepted an *optional* `session` (an internal patch |
| 16 | + defaulted it to `None`); they now require `session=...`, matching the real broker's |
| 17 | + signature and the documented public contract (the argument is still ignored under the |
| 18 | + test broker). **Production is unaffected** — `broker.cancel_timer` / `broker.fetch_unprocessed` |
| 19 | + always required `session`. Only test code that called these on a `TestOutboxBroker` |
| 20 | + *without* `session` needs a one-token edit. ([#141](https://github.com/modern-python/faststream-outbox/pull/141)) |
| 21 | + |
| 22 | +## Internal refactors (no behavior change) |
| 23 | + |
| 24 | +Each deepens the codebase — more behavior behind smaller, single-owner seams — without |
| 25 | +changing observable production behavior. |
| 26 | + |
| 27 | +- **Schema-drift validator split out of `client.py`.** The ~285 LOC of Alembic-diff + |
| 28 | + `pg_catalog` probes moved to a new `schema_validation.py`; the transport client roughly |
| 29 | + halved (796 → 471 LOC) and no longer imports the optional `alembic` dependency. |
| 30 | + `broker.validate_schema()` / `client.validate_schema()` are unchanged. |
| 31 | + ([#139](https://github.com/modern-python/faststream-outbox/pull/139)) |
| 32 | +- **Dead `to_delete` intent flag removed.** `OutboxInnerMessage.to_delete` was set on every |
| 33 | + ack/terminal path but read by zero production code (dispatch branched on other fields). |
| 34 | + Removed; tests now assert on the fields the dispatcher actually reads. |
| 35 | + ([#140](https://github.com/modern-python/faststream-outbox/pull/140)) |
| 36 | +- **`cancel_timer` / `fetch_unprocessed` routed through the client seam.** Both built inline |
| 37 | + SQL on the broker's table handle, bypassing the `OutboxClient` that already owns the |
| 38 | + table. They are now methods on `AbstractOutboxClient` (real + fake); the broker delegates, |
| 39 | + and the test-broker patch machinery for them is deleted. (Carries the test-broker `session` |
| 40 | + change above.) ([#141](https://github.com/modern-python/faststream-outbox/pull/141)) |
| 41 | +- **Envelope-managed header keys named once.** `content-type` and `correlation_id` were bare |
| 42 | + string literals across `envelope.py` (write), `parser.py` (read), and the relay |
| 43 | + header-strip. Defined once in `message.py` as `CONTENT_TYPE_HEADER` / |
| 44 | + `CORRELATION_ID_HEADER` / `ENVELOPE_MANAGED_HEADERS`. |
| 45 | + ([#143](https://github.com/modern-python/faststream-outbox/pull/143)) |
| 46 | +- **Lease-token guard named; contract coverage filled.** The `NULL = NULL` token guard the |
| 47 | + fake repeated inline is now one `_lease_token_matches` helper. The cross-adapter contract |
| 48 | + suite gained the missing `mark_pending` unleased-row scenario (the delete path already had |
| 49 | + it) and an empty-queues symmetry check. |
| 50 | + ([#144](https://github.com/modern-python/faststream-outbox/pull/144)) |
| 51 | +- **Terminal intent deepened to a canonical `Outcome` sum type.** `OutboxInnerMessage` now |
| 52 | + records one `Outcome` — `Ack` | `Retry(delay_seconds)` | `Terminal(reason)` — instead of |
| 53 | + three loosely-coupled fields. Success is an explicit `Ack()`; "reason and delay both set" |
| 54 | + is now unrepresentable. `terminal_failure_reason` / `pending_delay_seconds` / `state_set` |
| 55 | + remain as **read-only property views**, so readers and the `DLQFailureReason` public |
| 56 | + contract are unchanged. ([#145](https://github.com/modern-python/faststream-outbox/pull/145)) |
| 57 | + |
| 58 | +## Design records (no code change) |
| 59 | + |
| 60 | +- **The `conn: AsyncConnection | None` union on the client seam is deliberate.** The review |
| 61 | + flagged it as a "type lie"; on inspection it is a documented widening (the fake genuinely |
| 62 | + has no connection, the subscriber genuinely produces `None` on the fake path). Recorded as |
| 63 | + an accepted decision with a revisit trigger. |
| 64 | + ([#142](https://github.com/modern-python/faststream-outbox/pull/142)) |
| 65 | +- **The two observability seams overlap on the consume/publish series.** `architecture/metrics.md` |
| 66 | + now documents that the recorder adapters and the native middleware emit the same-named |
| 67 | + consume/publish metrics — one Prometheus registry raises `Duplicated timeseries`, live OTel |
| 68 | + meters on both double-count — and why the library can't guard it at construction (separate |
| 69 | + registries / middleware-as-source-of-truth stays an operator concern). |
| 70 | + ([#146](https://github.com/modern-python/faststream-outbox/pull/146)) |
| 71 | + |
| 72 | +## Migration |
| 73 | + |
| 74 | +- **Production code:** none. No public-API change, no schema change, no config change. |
| 75 | +- **Test suites using `TestOutboxBroker`:** if you call `.cancel_timer(...)` or |
| 76 | + `.fetch_unprocessed(...)` on the test broker without a `session`, add `session=...` (any |
| 77 | + session — it is ignored under the test broker). Everywhere else, no change. |
| 78 | + |
| 79 | +## Touched surface |
| 80 | + |
| 81 | +- **Package code (internal only):** `faststream_outbox/schema_validation.py` (new), |
| 82 | + `client.py`, `broker.py`, `message.py`, `envelope.py`, `parser/parser.py`, |
| 83 | + `subscriber/usecase.py`, `testing.py`. |
| 84 | +- **Tests:** `tests/test_client_contract.py` (+2 scenarios), `tests/test_unit.py`, |
| 85 | + `tests/test_fake.py`. |
| 86 | +- **Living docs / decisions:** `CLAUDE.md`, `architecture/dlq.md`, `architecture/test-broker.md`, |
| 87 | + `architecture/metrics.md`, `docs/usage/testing.md`, `planning/decisions/2026-07-17-conn-union-is-deliberate.md`. |
| 88 | + |
| 89 | +## See also |
| 90 | + |
| 91 | +- [#139](https://github.com/modern-python/faststream-outbox/pull/139) — split schema-drift validator. |
| 92 | +- [#140](https://github.com/modern-python/faststream-outbox/pull/140) — remove dead `to_delete` flag. |
| 93 | +- [#141](https://github.com/modern-python/faststream-outbox/pull/141) — table ops behind the client seam. |
| 94 | +- [#142](https://github.com/modern-python/faststream-outbox/pull/142) — `conn` union deliberate (decision). |
| 95 | +- [#143](https://github.com/modern-python/faststream-outbox/pull/143) — name envelope header keys. |
| 96 | +- [#144](https://github.com/modern-python/faststream-outbox/pull/144) — name lease-token guard + contract coverage. |
| 97 | +- [#145](https://github.com/modern-python/faststream-outbox/pull/145) — canonical `Outcome` sum type. |
| 98 | +- [#146](https://github.com/modern-python/faststream-outbox/pull/146) — two-seam overlap hazard (docs). |
0 commit comments