82 lines
3.5 KiB
Markdown
82 lines
3.5 KiB
Markdown
---
|
|
id: pg-fix-docs-alignment
|
|
name: Doc alignment — TLS posture, QueueOpts consumer obligations (review 002 Finding 6 remainder)
|
|
status: pending
|
|
depends_on: [pg-fix-forwarder-reconnect]
|
|
scope: single
|
|
risk: trivial
|
|
impact: isolated
|
|
level: implementation
|
|
tags: [wave-4-fixes, postgres-engine, docs]
|
|
---
|
|
|
|
## Description
|
|
|
|
The doc-alignment remainder of the wave-4 general review
|
|
(`docs/reviews/002-wave-4-general-review.md` §Finding 6 + §Minor
|
|
notes) — the items that live in docs rather than the code files the
|
|
other fix tasks own. (The scheduler and `sweep_expired` doc fixes are
|
|
NOT here — they ride `pg-fix-scheduler-resilience` and
|
|
`pg-fix-dedupe-cleanup`, their files' tasks.)
|
|
|
|
- **TLS posture honesty**: every connection (pooled `store.rs:161`,
|
|
listener `store.rs:196`) is hardwired `NoTls`, but
|
|
`forwarder.rs:53-57`'s doc says the pooled path "rides the
|
|
consumer's Config sslmode" — misleading; a `sslmode=require` DSN
|
|
fails at connect. v1 TLS is effectively unavailable. Fix both ends:
|
|
correct the forwarder doc to match the code, and **`deployment.md`
|
|
owns the statement** (v1 ships `NoTls` on all connection paths;
|
|
TLS is a post-v1 deployment concern — the deployment matrix's
|
|
honesty posture, ADR-016's spirit). Check the crate-level docs and
|
|
`PgOpts` docs for the same claim while there.
|
|
- **QueueOpts numeric consumer-obligation note**: queue/`QueueOpts`
|
|
numeric values are trusted unvalidated (negative
|
|
`max_attempts`/visibility/retention stamp into rows verbatim; zero
|
|
`max_attempts` self-dead-letters into churn). The ADR-023 domain
|
|
table pins extents/durations/boundaries only, so this is not a
|
|
defect — but a one-sentence doc note (consumer-obligation, like the
|
|
visibility-budgeting one) prevents surprise. Home: `deployment.md`
|
|
(the budget/consumer-obligation section), with a mirror sentence in
|
|
`queue.rs`'s or `opts.rs`'s doc where the opts are documented.
|
|
- **Light mismatch sweep**: re-read the pg engine's doc comments
|
|
touched by the fix batch (forwarder, tx, scheduler, store) for any
|
|
*new* doc-behavior mismatch the fixes introduced — the fix tasks
|
|
correct their own sites, this is the cross-file consistency pass.
|
|
|
|
Doc-only task: no code behavior changes; gates must stay green.
|
|
|
|
**Depends on `pg-fix-forwarder-reconnect`** only because the forwarder
|
|
doc being corrected is in the file that task restructures — land after
|
|
it and correct against the settled code.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `forwarder.rs`'s sslmode claim matches the code (`NoTls`
|
|
hardwired); no other doc in the crate repeats the claim
|
|
- [ ] `deployment.md` states the v1 TLS-unavailable posture on all
|
|
connection paths
|
|
- [ ] `deployment.md` (plus the opts' doc home) carries the
|
|
QueueOpts numeric consumer-obligation note
|
|
- [ ] Cross-file doc sweep over the fix batch's touched files: no
|
|
doc-behavior mismatch remains (grep-auditable claims spot-checked)
|
|
- [ ] `cargo build`, clippy `-D warnings`, fmt clean (doc-only change;
|
|
tests unaffected)
|
|
|
|
## References
|
|
|
|
- docs/reviews/002-wave-4-general-review.md §Finding 6 + §Minor notes
|
|
(TLS bullet, QueueOpts bullet)
|
|
- docs/architecture/deployment.md (the budget/consumer-obligation
|
|
home; the visibility-budgeting note's precedent shape)
|
|
- docs/architecture/decisions/016-deployment-honesty.md (the honesty
|
|
posture)
|
|
- docs/architecture/decisions/023-fourth-review-round.md (the domain
|
|
table — why QueueOpts numerics are consumer-obligation, not defect)
|
|
|
|
## Notes
|
|
|
|
> To be filled by implementation agent
|
|
|
|
## Summary
|
|
|
|
> To be filled on completion |