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
2.7 KiB
2.7 KiB
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
- ADR-015 (per-site upstream timeouts)
- ADR-002 (custom proxy handler)