glm-5.1
9a2352e61c
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
66 lines
2.7 KiB
Markdown
66 lines
2.7 KiB
Markdown
# 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) |