docs alignment: v1 TLS posture owned by deployment.md, QueueOpts numeric consumer-obligation notes (task pg-fix-docs-alignment, review 002 Finding 6 remainder)
- forwarder.rs's ListenerConnection doc corrected: NoTls is hardwired on every connection path (pooled, listener, reconnect) — the pooled path never rode the consumer's Config sslmode (a sslmode=require DSN fails at connect); grep-audited no other in-crate doc repeats the claim - PgOpts doc carries the corrected one-line TLS pointer (engine-crate- docs posture, ADR-016 §2) - deployment.md: new 'TLS posture (v1)' subsection (NoTls everywhere, sslmode=require DSN fails at connect, topology-level confidentiality is the v1 substitute, TLS a post-v1 deployment concern) and a new 'Consumer-obligation notes on engine options' section carrying the QueueOpts trusted-as-given note with code-verified per-field symptoms (max_attempts <= 0: never claimed, dead-lettered at the next claim call's pre-claim sweep; negative visibility: instantly-reclaimable claims; negative retention: every dead row at the next sweep_expired) plus the PgOpts::max_size 0-guard counter-case; frontmatter advanced - alkstore/src/opts.rs: QueueOpts struct doc mirrors the consumer-obligation note (ADR-023 §2 scoping: the domain table covers trait-surface arguments, not consumer-constructed constants) - cross-file doc sweep over the fix batch's touched files (forwarder, tx, scheduler, store) found no further doc-behavior mismatch - gates: cargo build / clippy --all-targets -D warnings / fmt --check all green (doc-only, no test touched)
This commit is contained in:
1 parent
40625090f6
commit
49face898d
5 files changed
+148
-14
No files matched your search
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-10-07 (ADR-021 — third review round: drop=rollback keeps pg pool accounting exact under error paths)
|
||||
last_updated: 2026-10-10 (docs alignment — v1 TLS posture stated; QueueOpts numeric consumer-obligation notes)
|
||||
---
|
||||
|
||||
# Deployment
|
||||
@@ -82,6 +82,60 @@ engine-owned PostgreSQL schema (default `alkstore`, per-engine option)
|
||||
— layout per [ADR-010](decisions/010-queue-semantics-depth.md) §8
|
||||
(resolved from [queues.md](queues.md)'s namespace bullet).
|
||||
|
||||
### TLS posture (v1)
|
||||
|
||||
The pg engine hardwires `NoTls` on **every connection path** in v1 —
|
||||
the pooled connections, the dedicated listener connection, and every
|
||||
reconnect attempt alike; the engine does not ride the consumer's
|
||||
`Config` sslmode setting, and a DSN carrying `sslmode=require` (or any
|
||||
TLS demand) fails at connect. The listener's `NoTls` posture is
|
||||
test-pinned in the type it carries
|
||||
([ADR-004](decisions/004-postgres-driver.md)); v1 TLS should therefore
|
||||
be treated as **effectively unavailable** — network confidentiality
|
||||
between the process and the Postgres server must come from the
|
||||
deployment topology itself (private network, egress rules, a local
|
||||
unix socket or sidecar), not from driver TLS. Encrypting traffic
|
||||
between engine and server is a **post-v1 deployment concern** (wire a
|
||||
TLS connector through the pool and listener construction); until then
|
||||
the boundary above is the honest statement, per
|
||||
[ADR-016](decisions/016-deployment-honesty.md)'s spirit — the matrix
|
||||
states the limitation rather than having code pretend otherwise.
|
||||
|
||||
## Consumer-obligation notes on engine options
|
||||
|
||||
Consumer-*constructed* numeric option values are **trusted as given —
|
||||
the engine does not validate them against domain extents**. The
|
||||
engine would be a second normative home for semantics the contract
|
||||
deliberately leaves to the caller's constants; the
|
||||
[ADR-023](decisions/023-fourth-review-round.md) §2 domain table
|
||||
covers the trait-surface arguments, not these. This applies to the
|
||||
queue stamps (`QueueOpts`: `visibility_timeout_s`,
|
||||
`dead_letter_retention_s`, `max_attempts`) on both engines:
|
||||
|
||||
- Negative or zero `visibility_timeout_s` stamps claims whose deadline
|
||||
is already past — every claim is instantly reclaimable (the
|
||||
dual-execution window is the consumer's documented budget
|
||||
[ADR-010](decisions/010-queue-semantics-depth.md) §2).
|
||||
- Zero or negative `max_attempts` stamps rows the claim statement
|
||||
never hands out — each is dead-lettered with reason "max attempts
|
||||
exceeded" at the next claim call on that queue (the pre-claim
|
||||
sweep's `attempts >= max_attempts` arm), i.e. the queue silently
|
||||
discards its work.
|
||||
- Negative `dead_letter_retention_s` deletes every dead row at the
|
||||
next `sweep_expired` call (retention is driver-free — nothing runs
|
||||
without a caller).
|
||||
- The stamps ride *future enqueues only* (`QueueOpts`'s documented
|
||||
shape) — repair the opts before enqueueing rather than repairing
|
||||
rows afterwards.
|
||||
|
||||
The same trusted-as-given shape applies to `PgOpts::max_size`'s
|
||||
*positive-integer* contract — 0 is typed-failed at open, the one knob
|
||||
with an engine-side guard; everything above has none. The
|
||||
consumer-obligation shape here is the visibility-budgeting precedent
|
||||
([ADR-010](decisions/010-queue-semantics-depth.md) §2): the constant is
|
||||
the consumer's, the behavior of a mis-set one is documented, nothing
|
||||
runtime is fabricated.
|
||||
|
||||
## Durability knobs
|
||||
|
||||
| Engine | Knob | Shape |
|
||||
|
||||
Reference in new issue
Block a user