Update architecture docs to address security review #003 findings
Add three ADRs (025-027) and update five spec documents to close gaps identified in the security and bug review: - ADR-025: Rate limiter IP source must be ConnectInfo only (C1 fix) - ADR-026: Connector timeout ceiling of 30s for per-site timeouts (C3 fix) - ADR-027: Admin socket resource limits — 5s timeout, 4096 byte line limit (W4 fix) Spec changes: - proxy.md: add rate limiter IP source section, URI error handling constraint, connector ceiling description, renumber sections - operations.md: add ConnectInfo-only IP source, in-flight counter architectural requirement (C2), JSON format guarantee (C4), admin socket resource limits, 100ms drain polling interval - config.md: fix http_port type u32→u16 (W12), tighten upstream host validation (W1), tighten ACME contact validation (W2), add X-Forwarded-Proto cross-reference, clarify alknet ADR-030 reference - overview.md: fix ambiguous C1 reference, add ADR/OQ cross-references - open-questions.md: update OQ-09 resolution, add OQ-13 (acme_contact Vec) and OQ-14 (eviction configurability) - README.md: add ADR-025/026/027 and OQ-13/14, update doc statuses to draft Also fix reviewer findings: alknet ADR-030 scope clarification, RFC 2616 reference updated to RFC 7230.
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
---
|
||||
status: reviewed
|
||||
status: draft
|
||||
last_updated: 2026-06-12
|
||||
---
|
||||
|
||||
@@ -111,18 +111,21 @@ last_updated: 2026-06-12
|
||||
|
||||
### ~~OQ-09: How should `upstream_connect_timeout_secs` be enforced?~~
|
||||
|
||||
- **Origin**: Implementation review finding W4, ADR-015, ADR-017
|
||||
- **Origin**: Implementation review finding W4, ADR-015, ADR-017, Security
|
||||
Review C3
|
||||
- **Status**: resolved
|
||||
- **Priority**: medium
|
||||
- **Resolution**: Implemented using a two-phase `tokio::time::timeout` approach.
|
||||
The inner timeout uses the per-site `upstream_connect_timeout_secs` (default
|
||||
5s) for the connect + first-byte phase, and the outer timeout uses
|
||||
`upstream_request_timeout_secs` (default 60s) for the full request/response
|
||||
cycle. Additionally, `HttpConnector::set_connect_timeout()` enforces the
|
||||
TCP-level connect timeout on both HTTP and HTTPS clients. The implementation
|
||||
is in `handler.rs` and `create_http_client()`/`create_https_client()`.
|
||||
No new ADR needed; the decision was already made in ADR-015.
|
||||
- **Cross-references**: ADR-015, ADR-017
|
||||
cycle. The shared `HttpConnector` uses a 30-second connect timeout ceiling
|
||||
via `set_connect_timeout()` — this is a safety backstop, not the primary
|
||||
enforcement mechanism. The per-site `tokio::time::timeout` enforces the
|
||||
actual connect timeout. This ensures per-site values >5s work correctly
|
||||
(previously the hardcoded 5s connector timeout silently capped them). See
|
||||
ADR-026.
|
||||
- **Cross-references**: ADR-015, ADR-017, ADR-026
|
||||
|
||||
### ~~OQ-10: Should ACME contact email be a required config field?~~
|
||||
|
||||
@@ -168,4 +171,33 @@ last_updated: 2026-06-12
|
||||
disable access logging." The `log_request!` macro exists in the codebase
|
||||
but is not called — this is an implementation gap (W13), not an
|
||||
architectural question. No ADR needed; ADR-007 already covers the log format.
|
||||
- **Cross-references**: ADR-007
|
||||
- **Cross-references**: ADR-007
|
||||
|
||||
## Configuration
|
||||
|
||||
### OQ-13: Should `acme_contact` support multiple email addresses?
|
||||
|
||||
- **Origin**: Security Review S9, [config.md](config.md), [tls.md](tls.md)
|
||||
- **Status**: open
|
||||
- **Priority**: low
|
||||
- **Details**: `acme_contact` is currently a single `String`, but ACME supports
|
||||
multiple contact emails. The `AcmeTlsConfig.contact` field in the
|
||||
implementation is already `Vec<String>`, and the single config value is
|
||||
wrapped in `vec![...]`. Changing `acme_contact` to `Vec<String>` in the
|
||||
config schema would provide consistency with the ACME protocol. However,
|
||||
this is a config format change that requires migration documentation and
|
||||
backward compatibility considerations. For Phase 1, a single email is
|
||||
sufficient.
|
||||
- **Cross-references**: ADR-004
|
||||
|
||||
### OQ-14: Should rate limiter eviction interval and max age be configurable?
|
||||
|
||||
- **Origin**: Security Review S2, [operations.md](operations.md)
|
||||
- **Status**: open
|
||||
- **Priority**: low
|
||||
- **Details**: The eviction task interval (60s) and max age (300s) are
|
||||
currently hardcoded. In high-traffic deployments, a shorter interval or
|
||||
longer max age might be desirable. These would be dynamic config fields
|
||||
(hot-reloadable via ArcSwap) if added. For Phase 1, the hardcoded values
|
||||
are reasonable defaults.
|
||||
- **Cross-references**: ADR-006
|
||||
Reference in New Issue
Block a user