Files
reverse-proxy/docs/architecture
glm-5.1 fecc385d75 Add container deployment model (ADR-020) and fix review issues
- ADR-020: Document defense-in-depth rationale for running in a minimal
  Docker container (memory-safe language + container isolation), flexible
  upstream addressing (Docker DNS, loopback, LAN, tunnel endpoints),
  file-primary logging for fail2ban, and volume mount strategy
- ADR-016: Add allow_wildcard_bind override for container deployments
  where 0.0.0.0 is correct inside the container network namespace
- operations.md: Add container deployment section with Docker Compose
  example, networking table, volume mounts, and health check integration;
  flip logging to file-primary for fail2ban reliability; note systemd as
  alternative to container deployment
- config.md: Restructure logging fields into nested LoggingConfig (matching
  TOML [logging] section), add allow_wildcard_bind, shutdown_timeout_secs,
  and log_file_path fields; clarify upstream addressing supports Docker
  DNS and tunnel endpoints; update validation rule for 0.0.0.0 override
- overview.md: Update architecture diagram for container model with Docker
  networking and volume mounts; add ADR-020 reference
- proxy.md: Clarify X-Forwarded-Proto is determined by listener port, not
  hardcoded 80/443
- ADR-013: Fix health_check_port default contradiction (default is 9900,
  not 0/disabled as previously stated)
2026-06-11 10:10:32 +00:00
..

status, last_updated
status last_updated
draft 2026-06-11

Reverse Proxy — Architecture

Current State

Phase 0 (Exploration) — Complete. Phase 1 (Architecture) — In progress.

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.

Architecture Documents

Document Status Description
overview.md Draft Vision, scope, crate dependencies, exports
proxy.md Draft Reverse proxy handler, request flow, header injection
tls.md Draft TLS termination, ACME, manual certs, SNI
config.md Draft TOML config format, static/dynamic split, ArcSwap reload
operations.md Draft Rate limiting, logging, health check, systemd, shutdown

ADR Table

ADR Title Status
001 Rust with Axum Accepted
002 Custom Proxy Handler Accepted
003 TOML Configuration Format Accepted
004 ACME-Primary Certificate Management Accepted
005 tokio-rustls Directly, Not axum-server Accepted
006 Token Bucket Rate Limiting Accepted
007 Custom Structured Log Format Accepted
008 Static/Dynamic Config Split with ArcSwap Accepted
009 Signal Handling Strategy Accepted
010 Multi-Site Support in Phase 1 Accepted
011 Multi-Domain TLS Configuration Accepted
012 Restrict Cipher Suites to nginx Scope Accepted
013 Health Check on Separate Local Port Accepted
014 Unix Domain Socket Config Reload API Accepted
015 Per-Site Upstream Timeouts with Defaults Accepted
016 Explicit Bind Address Requirement Accepted
017 Upstream Connection Defaults Accepted
018 Request Body Size Limit Accepted
019 Multi-Config Listener Support Accepted
020 Container Deployment Model Accepted

Open Questions

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

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