glm-5.1
0d54eba41e
Architecture updates based on gaps discovered during live deployment testing: - ADR-023: HTTP/2 client-facing support via ALPN-based protocol detection. The spec previously said HTTP/2 was out of scope, but the deployment revealed that modern browsers negotiate HTTP/2 via ALPN. The proxy now correctly detects the negotiated ALPN protocol and uses the appropriate HTTP server builder (http2::Builder for h2, auto::Builder for http/1.1). Upstream connections remain HTTP/1.1. Host resolution now falls back to URI host for HTTP/2 :authority pseudo-headers. - ADR-024: ANSI-disabled logging. All tracing-subscriber layers now use with_ansi(false) to prevent ANSI escape codes in log output, which broke fail2ban regex matching in Docker deployments. Also documents the fail2ban regex anchor fix (^RATE_LIMIT → RATE_LIMIT). Bug fixes found by architecture review: - Fix missing ALPN protocols in manual TLS mode. build_manual_server_config and build_multi_domain_server_config did not set alpn_protocols, meaning manual TLS mode could not support HTTP/2. Added h2 and http/1.1 ALPN entries to both functions (acme-tls/1 only in ACME mode). - Fix missing with_ansi(false) in JSON log format. The init_json function with file output did not disable ANSI on stdout or file layers, which would break fail2ban in production JSON logging mode. Other spec updates: - All document statuses updated from draft to reviewed - proxy.md: documented Server header removal, upstream HTTPS client, two-phase timeout enforcement, HTTP/2 host resolution, connect timeout - tls.md: documented ALPN configuration differing by mode (ACME vs manual) - overview.md: added HTTP/2 client-facing support to scope, updated crate deps (hyper-rustls, rustls-native-certs, hyper-util), clarified out-of-scope - config.md: fixed http_port type (u16→u32) to match implementation, added ANSI-disabled note for LoggingConfig - operations.md: documented ANSI-disabled logging, fail2ban regex anchor - open-questions.md: updated OQ-09 resolution (connect timeout fully implemented), OQ-10 (C2 bug is fixed)
89 lines
5.8 KiB
Markdown
89 lines
5.8 KiB
Markdown
---
|
|
status: reviewed
|
|
last_updated: 2026-06-12
|
|
---
|
|
|
|
# Reverse Proxy — Architecture
|
|
|
|
## Current State
|
|
|
|
**Phase 1 (Implementation) — Complete.** The proxy is deployed and running in a
|
|
Docker container, replacing our vulnerable nginx 1.24.0 installation.
|
|
|
|
This project replaces our vulnerable nginx 1.24.0 installation with a
|
|
memory-safe Rust/axum reverse proxy. The primary motivation is CVE-2026-42945
|
|
(unauthenticated RCE in nginx's rewrite module) and the broader pattern of
|
|
memory corruption bugs in nginx's C codebase.
|
|
|
|
The proxy supports multiple domains from initial release (git.alk.dev and
|
|
alk.dev), with per-domain host-based routing and a single multi-domain SAN
|
|
certificate via ACME. HTTP/2 is supported on the client-facing side (between
|
|
the client and the proxy) with ALPN-based protocol detection. Upstream
|
|
connections remain HTTP/1.1.
|
|
|
|
## Architecture Documents
|
|
|
|
| Document | Status | Description |
|
|
|----------|--------|-------------|
|
|
| [overview.md](overview.md) | Reviewed | Vision, scope, crate dependencies, exports |
|
|
| [proxy.md](proxy.md) | Reviewed | Reverse proxy handler, request flow, header injection |
|
|
| [tls.md](tls.md) | Reviewed | TLS termination, ACME, manual certs, SNI, ALPN |
|
|
| [config.md](config.md) | Reviewed | TOML config format, static/dynamic split, ArcSwap reload |
|
|
| [operations.md](operations.md) | Reviewed | Rate limiting, logging, health check, systemd, shutdown |
|
|
|
|
## ADR Table
|
|
|
|
| ADR | Title | Status |
|
|
|-----|-------|--------|
|
|
| [001](decisions/001-rust-axum.md) | Rust with Axum | Accepted |
|
|
| [002](decisions/002-custom-proxy-handler.md) | Custom Proxy Handler | Accepted |
|
|
| [003](decisions/003-toml-config.md) | TOML Configuration Format | Accepted |
|
|
| [004](decisions/004-rustls-acme.md) | ACME-Primary Certificate Management | Accepted |
|
|
| [005](decisions/005-tokio-rustls-direct.md) | tokio-rustls Directly, Not axum-server | Accepted |
|
|
| [006](decisions/006-rate-limiting-approach.md) | Token Bucket Rate Limiting | Accepted |
|
|
| [007](decisions/007-custom-log-format.md) | Custom Structured Log Format | Accepted |
|
|
| [008](decisions/008-static-dynamic-config-split.md) | Static/Dynamic Config Split with ArcSwap | Accepted |
|
|
| [009](decisions/009-signal-handling.md) | Signal Handling Strategy | Accepted |
|
|
| [010](decisions/010-multi-site-phase1.md) | Multi-Site Support in Phase 1 | Accepted |
|
|
| [011](decisions/011-multi-domain-tls.md) | Multi-Domain TLS Configuration | Accepted |
|
|
| [012](decisions/012-cipher-suite-restriction.md) | Restrict Cipher Suites to nginx Scope | Accepted |
|
|
| [013](decisions/013-health-check-port.md) | Health Check on Separate Local Port | Accepted |
|
|
| [014](decisions/014-unix-socket-reload.md) | Unix Domain Socket Config Reload API | Accepted |
|
|
| [015](decisions/015-per-site-timeouts.md) | Per-Site Upstream Timeouts with Defaults | Accepted |
|
|
| [016](decisions/016-explicit-bind-address.md) | Explicit Bind Address Requirement | Accepted |
|
|
| [017](decisions/017-upstream-connection-defaults.md) | Upstream Connection Defaults | Accepted |
|
|
| [018](decisions/018-body-size-limit.md) | Request Body Size Limit | Accepted |
|
|
| [019](decisions/019-multi-config-listeners.md) | Multi-Config Listener Support | Accepted |
|
|
| [020](decisions/020-container-deployment.md) | Container Deployment Model | Accepted |
|
|
| [021](decisions/021-x-forwarded-for-edge-proxy.md) | X-Forwarded-For Edge Proxy Model | Accepted |
|
|
| [022](decisions/022-health-check-scope.md) | Health Check Scope — Local Port and Admin Socket Only | Accepted |
|
|
| [023](decisions/023-http2-client-facing.md) | HTTP/2 Client-Facing Support | Accepted |
|
|
| [024](decisions/024-ansi-disabled-logging.md) | ANSI-Disabled Logging for Container Deployments | Accepted |
|
|
|
|
## Open Questions
|
|
|
|
See [open-questions.md](open-questions.md) for the full tracker.
|
|
|
|
| OQ | Question | Priority | Status |
|
|
|----|----------|----------|--------|
|
|
| ~~OQ-01~~ | ~~Should cipher suites be restricted beyond rustls defaults?~~ | ~~medium~~ | **resolved** (ADR-012) |
|
|
| ~~OQ-02~~ | ~~What log format should fail2ban consume?~~ | ~~high~~ | **resolved** (ADR-007) |
|
|
| ~~OQ-03~~ | ~~Should the health check endpoint be on a separate port?~~ | ~~low~~ | **resolved** (ADR-013) |
|
|
| ~~OQ-04~~ | ~~Config reload: SIGHUP only or also Unix socket API?~~ | ~~low~~ | **resolved** (ADR-014) |
|
|
| ~~OQ-05~~ | ~~Should the proxy bind to multiple addresses?~~ | ~~low~~ | **resolved** (single bind_addr sufficient) |
|
|
| ~~OQ-06~~ | ~~Should upstream timeouts be configurable per-site?~~ | ~~low~~ | **resolved** (ADR-015) |
|
|
| ~~OQ-07~~ | ~~Should per-site TLS overrides be supported for mixed ACME/manual domains?~~ | ~~low~~ | **resolved** (ADR-019) |
|
|
| ~~OQ-08~~ | ~~Should `/health` use a less common path to avoid upstream collision?~~ | ~~medium~~ | **resolved** (ADR-022: no `/health` route on main listener) |
|
|
| ~~OQ-09~~ | ~~How should `upstream_connect_timeout_secs` be enforced?~~ | ~~medium~~ | **resolved** (implementation gap — ADR-015 already decides this) |
|
|
| ~~OQ-10~~ | ~~Should ACME contact email be a required config field?~~ | ~~high~~ | **resolved** (already specified in config.md; implementation bug C2) |
|
|
| ~~OQ-11~~ | ~~How should `X-Forwarded-Proto` be derived per-listener?~~ | ~~medium~~ | **resolved** (hardcoded `https` is correct for TLS-terminating proxy) |
|
|
| ~~OQ-12~~ | ~~Should request access logging be mandatory or optional?~~ | ~~high~~ | **resolved** (mandatory, always-on per operations.md) |
|
|
|
|
## Document Lifecycle
|
|
|
|
| Status | Meaning | Transitions |
|
|
|--------|---------|-------------|
|
|
| `draft` | Under active development. May change significantly. | → `reviewed` when open questions are resolved |
|
|
| `reviewed` | Architecture is final. Implementation may begin. Changes require review. | → `stable` when implementation is complete |
|
|
| `stable` | Locked. Changes require review and may warrant an ADR. | → `deprecated` when superseded |
|
|
| `deprecated` | Superseded. Kept for reference. | Removed when no longer referenced | |