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:
2026-06-11 09:07:36 +00:00
parent 7efc142406
commit 9a2352e61c
14 changed files with 613 additions and 89 deletions

View File

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