Resolve all architecture review findings (7 critical, 14 warnings, 6 suggestions)
Critical findings resolved: - C1: Site routing is global (per-listener TOML, global runtime lookup) - C2: X-Forwarded-For replaces (not appends) — edge proxy model (ADR-021) - C3: Hop-by-hop header handling rules specified (proxy.md) - C4: ACME failure behavior defined (tls.md) - C5: Startup sequence with fail-fast semantics (operations.md) - C6: Per-listener Router instances with shared global state (overview.md) - C7: Rate limiter adopts new params on next request, no state clear (operations.md) Warnings resolved: - W1: Admin socket wire protocol specified - W2: Host header port stripped, hostnames only in config - W3: HTTP redirect URL construction with port handling - W4: /health on HTTPS matches regardless of Host header - W5: Static config changes logged as warning during reload - W6: Reload operations serialized via Mutex - W7: http_port validation rules added (9 new rules total) - W8: upstream format validation (host:port required, no scheme) - W9: TLS error handling table (SNI, version, cipher failures) - W10: IPv6 rate limited per /64 prefix - W11: Graceful shutdown sequence specified (6 steps) - W12: Error response bodies: minimal plain text, no version disclosure - W13: upstream_scheme HTTPS uses system CA store - W14: allow_wildcard_bind is OR between config and CLI - W15: ADR-010 Phase 2 list updated (timeouts moved to Phase 1) - W17: LoggingConfig static/restart note added Suggestions applied: - S2: ConnectInfo propagation note - S3: Case-insensitive host matching (RFC 7230) - S5: Response streaming behavior (chunk-by-chunk) - S6: Token bucket nodelay semantics - S7: File watching explicitly out of scope - S8: All paths forwarded without filtering - S9: shutdown_timeout_secs referenced in shutdown description - S11: Consolidated defaults table in config.md
This commit is contained in:
@@ -243,6 +243,42 @@ suitable (e.g., behind a CDN that terminates TLS). When using HTTP-01, the
|
||||
port 80 listener serves `/.well-known/acme-challenge/{token}` paths for
|
||||
challenge verification.
|
||||
|
||||
## Certificate Failure Behavior
|
||||
|
||||
ACME certificate provisioning and renewal can fail for various reasons (network
|
||||
outages, Let's Encrypt unavailability, DNS issues, rate limiting). The proxy's
|
||||
behavior depends on the scenario:
|
||||
|
||||
| Scenario | Behavior |
|
||||
|----------|----------|
|
||||
| First start, no cached cert, ACME unreachable | **Fail to start** with clear error message. The proxy cannot serve TLS without a certificate. |
|
||||
| First start, no cached cert, ACME succeeds | Normal startup. Certificate is provisioned and cached. |
|
||||
| Start with cached cert, ACME unreachable for renewal | **Start normally** with cached cert. Log error at `warn` level. `rustls-acme` retries per its built-in schedule. |
|
||||
| Renewal failure after startup | **Continue serving existing cert**. Log error at `warn` level. `rustls-acme` retries per its built-in schedule. |
|
||||
| Cached cert expired, renewal fails at startup | **Fail to start** if cert is expired at startup. An expired certificate cannot serve valid TLS. |
|
||||
| Cached cert expires during runtime | **Continue serving expired cert**. Clients will receive certificate errors. Log at `error` level. This is the correct behavior — silently dropping TLS would be worse. |
|
||||
|
||||
The key principle: **never start without a valid TLS certificate**, but **always
|
||||
continue serving if a valid cert exists**, even if renewal fails.
|
||||
|
||||
## TLS Error Handling
|
||||
|
||||
TLS handshake failures are logged and the connection is closed. The proxy does
|
||||
not serve a default certificate for unknown hostnames — connections that don't
|
||||
match any configured certificate fail.
|
||||
|
||||
| Scenario | Behavior |
|
||||
|----------|----------|
|
||||
| SNI hostname doesn't match any certificate (manual mode) | TLS handshake fails with `unrecognized_name` alert. Log at `warn` level with client IP and SNI hostname. |
|
||||
| No SNI extension sent by client | TLS handshake fails with `handshake_failure` alert. Log at `warn` level with client IP. |
|
||||
| Unsupported TLS version (1.0/1.1) | TLS handshake fails with `protocol_version` alert. Log at `info` level. |
|
||||
| Cipher suite negotiation fails | TLS handshake fails with `handshake_failure` alert. Log at `info` level with client IP. |
|
||||
| Certificate expired (manual mode) | Connection fails during TLS handshake. Log at `error` level. Other listeners/connections continue serving. |
|
||||
|
||||
In ACME mode, the `ResolvesServerCertAcme` resolver handles certificate
|
||||
selection automatically — there is no SNI mismatch scenario because the
|
||||
resolver serves the ACME-provisioned certificate for all valid domains.
|
||||
|
||||
## Key Files and Crates
|
||||
|
||||
| Component | Crate | Purpose |
|
||||
|
||||
Reference in New Issue
Block a user