docs: fix 14 confirmed bugs from the 2026-06-12 docs audit (B1–B14)#63
Merged
Conversation
Fixes every bug-severity finding from
planning/active/2026-06-12-docs-audit-findings.md — broken examples,
nonexistent attributes/imports/metrics, and false claims, each verified
against current source:
- B1/B2 relay.md: OutboxBroker/OutboxRouter missing required outbox_table
- B3 testing.md/timers.md/dlq.md: broker.fake_client → bind the
TestOutboxBroker harness (dlq.md site the audit's list missed)
- B4 router.md: OutboxRoute imported from faststream_outbox.router
- B5 fastapi.md: HTTP route reaches the broker via router.broker, not a
broker: OutboxBroker annotation (422); shortcuts are subscriber-only
- B6 publisher.md: OutboxMessage from annotations (context-resolved)
- B7 subscriber.md: retry override renamed to get_next_attempt_delay
- B8 subscriber.md: MANUAL handler msg annotated OutboxMessage
- B9 add-kafka-relay.md: durability qualified to the retry budget
- B10 setup-prometheus-opentelemetry.md: separate registries for the
middleware + recorder (shared one raises Duplicated timeseries);
double-counting warning
- B11 observability.md: alert uses faststream_outbox_terminal_total
- B12 observability.md: nacked_retried / published catalog rows corrected
- B13 checklist.md: long table name raises ValueError at build time (bytes)
- B14 checklist.md/troubleshooting.md: LISTEN fallback is silent for
missing-driver / non-asyncpg URL; WARNING only on connect failure
Inaccuracies (I1–I22) and improvements (P1–P25) remain open triage.
mkdocs build --strict passes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Jun 12, 2026
lesnik512
added a commit
that referenced
this pull request
Jun 13, 2026
…hive findings (#72) * docs: resolve docs-audit improvements P1–P25 + 4 source-side notes Closes the open tail of the 2026-06-12 docs audit (bugs B1–B14 shipped in #63, inaccuracies I1–I22 in #64; this is the improvements + source-side remainder). Every source-referenced claim was verified against the code. Docs (P1–P25): - index.md: sync the on-page index with mkdocs nav (tutorials, instrumentation seams, prometheus/otel setup, new Operations section). - installation.md: document the `all` extra. - how-it-works.md: self-contained DLQ snippet; retarget "Relay tutorial" link to the actual tutorial. - basic.md: say to save the module as app.py. - tutorials: schema-validation "what's next" pointer; `faststream[cli,kafka]`. - relay.md: import OutboxMessage alias; document the unstarted-foreign-broker WARNING + fail-and-retry safety net; correct the _OutboxConfigError row fate (lease-expiry retry, not retry_strategy); fix the misplaced NotImplementedError comment. - timers.md: timer_id dedups only live rows (partial index); fix the undefined-`order` snippet. - subscriber.md: document multi-queue subscribers + connection budget + same-queue competition; MANUAL silent-return = terminal reject warning. - publisher.md: "publisher's" not "decorator's" static headers; make the chained example coherent (FastAPI-context session note, no undefined symbols); duplicate-delivery-on-crash caveat. - fastapi.md: document dlq_table/metrics_recorder/routers not exposed on OutboxRouter (no router workaround); clarify "fresh session per delivery"; self-contained quickstart stubs. - schema-validation.md + alembic.md: compare_server_default=False caveat (a green validate_schema does not prove server defaults exist). - observability.md: `sum by (destination)` on per-queue PromQL; correct the `fetched` footnote (skipped when inflight full; first-queue tag only). - checklist.md: real ExponentialRetry kwarg names (the shorthand raised TypeError if copied). Source-side docstring/comment fixes (no logic change): - testing.py: "list of _FakeRow records" not "list of dicts"; fix the `test_broker.fake_client.dlq_rows` accessor comment; correct the TestOutboxBroker docstring (future-dated rows fire immediately in sync mode — it contradicted the already-correct module docstring). - publisher/usecase.py: de-duplicate the _REJECT_RELAY_MSG wording. Verified: mkdocs build --strict clean (all links/anchors resolve); lint-ci clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: archive the 2026-06-12 docs-audit findings (shipped) All findings resolved: B1–B14 (#63), I1–I22 (#64), and P1–P25 + the 4 source-side notes (#72). Move active → archived with status: shipped and PR provenance. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- 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
Fixes all 14 bug-severity findings from
planning/active/2026-06-12-docs-audit-findings.md— doc statements that are flatly false: snippets that raise if copied, attributes/imports/metrics that don't exist, claims the code contradicts. Each fix was re-verified against current source (post-#61 line shifts accounted for).OutboxBroker/OutboxRouternow pass the requiredoutbox_tablebroker.fake_client→ bind theTestOutboxBrokerharness (tb.fake_client); dlq.md prose site the audit's enumeration missedOutboxRouteimported fromfaststream_outbox.router(not root)router.broker, not abroker: OutboxBrokerannotation (→ 422); documents that annotation shortcuts are subscriber-onlyOutboxMessageimported fromannotations(context-resolved alias)get_next_attempt_at→get_next_attempt_delaymsgannotatedOutboxMessageDuplicated timeseries); two scrape routes; double-counting warningfaststream_outbox_terminal_total(real metric)nacked_retried/publishedevent-catalog rows corrected to actual emission tagsValueErrorat build time (63 bytes), no silent truncationScope
dlq.md:182) that the audit's site list omitted but is the identical bug.Test plan
just docs-build(mkdocs build --strict) passesbroker.fake_client,get_next_attempt_at,OutboxBroker(engine=engine), ornacked_terminal_totalremain in docs🤖 Generated with Claude Code