Skip to content

Commit c4cf3c9

Browse files
lesnik512claude
andauthored
docs(releases): 0.12.0 release notes (#147)
Architecture-deepening pass: six internal behavior-preserving refactors (schema validator split, dead to_delete flag removed, table ops behind the client seam, envelope header keys named, lease-token guard named, terminal path deepened to an Outcome sum type) plus two design records (conn union deliberate; two-seam overlap doc). One test-broker-only behavior change (session now required on cancel_timer/fetch_unprocessed) makes it a minor bump per the release README. Notes only — no tag/publish (that is a separate explicit step). Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 606e023 commit c4cf3c9

1 file changed

Lines changed: 98 additions & 0 deletions

File tree

‎planning/releases/0.12.0.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
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

Comments
 (0)