docs: add Patterns page composing the outbox in a service#103
Merged
Conversation
Design for docs/patterns/messaging-service.md — an anonymized chat / notifications service composing three outbox primitives end-to-end (transactional event relay, fire-unless-cancelled timer, testing the composed app), wired with a real DI container. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Address final-review minor findings: the type comment omitted "unread" (used by the timer payload), and include_routers referenced a bare broker. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…class-scoped timer methods - Use broker.include_router(ROUTER) to match the rest of the docs (both methods exist upstream; singular is the house convention). - State the load-bearing invariant: producer, repository, and transaction must resolve the same request-scoped AsyncSession or atomicity breaks. - Show arm/cancel_unread_timer under a `class OutboxEventProducer:` continuation instead of a `# inside ...` comment over module-scope defs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…103) Move the bundle active/ → archive/, set status: shipped + pr: 103 + outcome on design.md and plan.md, and add the Index line under Archived. No architecture/ promotion — docs-only change, no new invariant. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new Patterns docs section with one page,
docs/patterns/messaging-service.md, showing an anonymized chat /notifications service that composes three outbox primitives end-to-end:
publish(queue=, session=)inside the use-casetransaction beside domain writes; a subscriber relays the row to Kafka.
timer_id+activate_in, disarmwith
cancel_timeron read; covers the at-most-one-live dedup, thelease-guarded cancel, and the inherent race window.
TestOutboxBroker+TestKafkaBroker,the sync-mode /
run_loops=Truedistinction, and the real-enginevalidate_schema()caveat.The existing tutorials teach one primitive at a time and the guides document each
feature abstractly; nothing showed the primitives composed in a real service.
This page fills that gap and cross-links the primitive guides for depth.
Why
Patterns are drawn from real production usage of
faststream-outbox, presentedgenerically (a chat / notifications service — no private service named). Coverage
is the core trio only; hardening features (native relay, DLQ, observability) are
one-line "See also" links.
Verification
just docs-build(mkdocs build --strict) passes — all six cross-links resolve.OutboxBroker,OutboxRouter,make_outbox_table,TestOutboxBroker,publish/cancel_timer); a finalwhole-branch review verified each technical claim against source.
Notes
design.md+plan.md) included underplanning/changes/active/2026-06-19.01-messaging-service-patterns-doc/. Onmerge it should move to
planning/changes/archive/withstatus: shipped/pr:/outcome:filled, per the repo convention.🤖 Generated with Claude Code