Resolve 5 open questions, add 7 ADRs for previously undocumented decisions
Resolve open questions: - OQ-01: Restrict cipher suites to match nginx scope (4 ECDHE-AES-GCM suites for TLS 1.2 + all TLS 1.3 suites) — ADR-012 - OQ-03: Health check on separate local port (default 9900, localhost only) — ADR-013 - OQ-04: Add Unix domain socket admin API for config reload alongside SIGHUP, with structured success/failure responses — ADR-014 - OQ-06: Per-site upstream timeouts with defaults (5s connect, 60s request), overridable in SiteConfig — ADR-015 Document previously undocumented decisions flagged by architecture review: - ADR-016: Explicit bind address requirement (reject 0.0.0.0) - ADR-017: Upstream connection defaults (HTTP/1.1, no redirects, pooling) - ADR-018: 100 MB body size limit (matches nginx, Gitea compatibility) OQ-07 (per-site TLS overrides) remains open for future consideration. Spec updates: - config.md: add health_check_port, admin_socket_path, per-site timeout fields, update TOML example and validation rules - proxy.md: reference ADR-015/017/018 for timeouts, connection defaults, and body limit decisions - tls.md: replace OQ-01 cipher suite section with ADR-012 decision - operations.md: add local health check port section, admin socket reload - overview.md: update Phase 1 scope with new features, add ADR references - open-questions.md: resolve OQ-01/03/04/06, keep OQ-07 open
This commit is contained in:
@@ -0,0 +1,66 @@
|
||||
# ADR-017: Upstream Connection Defaults
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The proxy forwards requests to upstream services using a shared hyper `Client`.
|
||||
The client's configuration affects all upstream connections: timeouts, redirect
|
||||
handling, and connection pooling. These are significant design choices that
|
||||
affect production behavior and should be traceable.
|
||||
|
||||
## Decision
|
||||
|
||||
Configure the hyper `Client` with the following defaults:
|
||||
|
||||
| Setting | Value | Rationale |
|
||||
|---------|-------|-----------|
|
||||
| Connect timeout | 5 seconds | Prevents hanging on unreachable upstreams |
|
||||
| Request timeout | 60 seconds (default) | Per-site override available (ADR-015) |
|
||||
| Redirect following | Disabled | Proxies should not follow redirects — they pass response status to the client |
|
||||
| Connection pooling | Enabled (hyper default) | Reuses connections to the same upstream for performance |
|
||||
| HTTP version | HTTP/1.1 only | Upstream connections use HTTP/1.1; HTTP/2 proxying is out of scope |
|
||||
|
||||
The connect timeout of 5 seconds applies to establishing a TCP connection to
|
||||
the upstream. The request timeout of 60 seconds applies to the full
|
||||
request/response cycle and can be overridden per-site (ADR-015).
|
||||
|
||||
## Rationale
|
||||
|
||||
- **5s connect timeout**: Matches common reverse proxy conventions. Long
|
||||
enough for remote upstreams with network latency, short enough to fail fast
|
||||
on unreachable services.
|
||||
- **60s request timeout**: Generous default that accommodates Gitea push
|
||||
operations with large pack files. Per-site overrides allow tuning for faster
|
||||
upstreams.
|
||||
- **No redirect following**: Standard reverse proxy behavior. If an upstream
|
||||
returns a 3xx, the proxy streams it to the client. Following redirects would
|
||||
break the client's expectation and could create security issues (redirect
|
||||
loops, credential forwarding).
|
||||
- **Connection pooling**: Hyper's default connection reuse improves performance
|
||||
for repeated requests to the same upstream without additional configuration.
|
||||
- **HTTP/1.1 only**: The proxy communicates with upstreams over plain HTTP
|
||||
(loopback). HTTP/2 proxying is explicitly out of scope (see overview.md).
|
||||
Upstreams needing HTTP/2+ run their own servers (e.g., api.alk.dev).
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
- Explicit, documented defaults that match reverse proxy conventions
|
||||
- Per-site timeout overrides available for specific needs
|
||||
- No redirect following prevents common proxy pitfalls
|
||||
- Connection pooling provides good performance by default
|
||||
|
||||
**Negative:**
|
||||
- 60s default may be too long for fast upstreams (mitigated by per-site
|
||||
overrides in ADR-015)
|
||||
- HTTP/1.1 only for upstream means no HTTP/2 multiplexing to backends (out of
|
||||
scope per project design)
|
||||
|
||||
## References
|
||||
|
||||
- [proxy.md](../proxy.md)
|
||||
- ADR-015 (per-site upstream timeouts)
|
||||
- ADR-002 (custom proxy handler)
|
||||
Reference in New Issue
Block a user