glm-5.1
7efc142406
Promote multi-site support from Phase 2 to Phase 1 (ADR-010): the proxy must support git.alk.dev and alk.dev from initial release. Add multi-domain TLS configuration (ADR-011): acme_domains array replaces acme_domain string, single SAN certificate via rustls-acme. Key changes: - ADR-010: Multi-site in Phase 1 — avoids config format migration later - ADR-011: Multi-domain TLS — single SAN cert, acme_domains Vec<String> - ADR-002: Updated rationale for multi-site (one upstream per domain) - overview.md: Phase 1 now includes multi-site, alk.dev pass-through, dual licensing (MIT OR Apache-2.0), real IP removed - config.md: acme_domain → acme_domains, TOML example shows both sites, validation adds unique host check, real IP replaced with 203.0.113.10 - tls.md: Multi-domain SNI section moved from Future to current, manual mode uses ResolvesServerCert for SNI mapping, TOML header fixed - proxy.md: Updated for multi-site, removed single-domain language - operations.md: RFC 5737 documentation IPs, clarified rate limit eviction semantics (distinct scan interval vs eviction age) - open-questions.md: OQ-05 resolved (single bind_addr sufficient), new OQ-07 (per-site TLS overrides) Review fixes: - acme_domains (plural) consistently used across all docs and diagram - ADR-011 clearly scopes acme_domain as previous design - Inline decision rationale extracted: tls.md hot-reload → ADR-004 ref, config.md static/dynamic → ADR-008 ref - TOML section headers consistent (server.tls)
60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
# ADR-002: Custom Proxy Handler
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
We need to implement HTTP reverse proxying — receiving requests and forwarding
|
|
them to an upstream service (Gitea on localhost:3000). Two approaches are
|
|
available:
|
|
|
|
1. **`axum-reverse-proxy` crate**: Provides path-based routing, header
|
|
forwarding, round-robin load balancing, TLS support, retry mechanisms, and
|
|
RFC 9110 compliance.
|
|
2. **Custom handler** (Felix Knorr pattern): Build a handler using hyper's
|
|
`Client` to forward requests. ~50-100 lines of Rust for our needs.
|
|
|
|
Our use case is minimal: single upstream per domain, no load balancing, no
|
|
retry, no HTTP/2 proxying. While the proxy supports multiple domains
|
|
(ADR-010), each domain routes to exactly one upstream.
|
|
|
|
## Decision
|
|
|
|
Implement a custom proxy handler using hyper's `Client` for request forwarding,
|
|
following the pattern demonstrated by Felix Knorr and used in the alknet
|
|
project's channel proxy.
|
|
|
|
## Rationale
|
|
|
|
- `axum-reverse-proxy` adds complexity we don't need (load balancing, retry,
|
|
path-based routing to multiple backends)
|
|
- Our proxy case is the simplest possible: match a Host header, forward the
|
|
entire request to a single upstream, stream the response back
|
|
- Multi-domain support (ADR-010) doesn't change this — each domain still maps
|
|
to one upstream
|
|
- The Felix Knorr pattern is proven, idiomatic, and ~50-100 lines
|
|
- We maintain full control over header injection, error handling, and upstream
|
|
connection behavior
|
|
- If requirements grow, we can adopt `axum-reverse-proxy` later
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
- Minimal dependencies
|
|
- Full control over proxy behavior
|
|
- Easy to understand and audit (~100 lines of proxy code)
|
|
- No unnecessary abstraction layers
|
|
|
|
**Negative:**
|
|
- We implement and maintain proxy logic ourselves (but it's trivial for our
|
|
use case — each domain maps to one upstream)
|
|
- If requirements grow to load balancing or retry, we'd need to add that
|
|
ourselves or switch to `axum-reverse-proxy`
|
|
|
|
## References
|
|
|
|
- [proxy.md](../proxy.md)
|
|
- [ADR-010](010-multi-site-phase1.md) (multi-site in Phase 1)
|
|
- Felix Knorr, "Replacing nginx with axum" (felix-knorr.net/posts/2024-10-13-replacing-nginx-with-axum.html) |