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:
2026-06-12 13:17:39 +00:00
parent 4f537c80d2
commit 80d1fd0fb3
9 changed files with 432 additions and 53 deletions

View File

@@ -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