Files

glm-5.1 7efc142406 Expand architecture: multi-site Phase 1, multi-domain TLS, fix review issues

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)

2026-06-11 08:50:03 +00:00

2.2 KiB

Raw Blame History

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:

axum-reverse-proxy crate: Provides path-based routing, header forwarding, round-robin load balancing, TLS support, retry mechanisms, and RFC 9110 compliance.
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
ADR-010 (multi-site in Phase 1)
Felix Knorr, "Replacing nginx with axum" (felix-knorr.net/posts/2024-10-13-replacing-nginx-with-axum.html)

2.2 KiB Raw Blame History