reverse-proxy/docs/architecture/open-questions.md

status, last_updated

status	last_updated
draft	2026-06-12

Open Questions

TLS

OQ-01: Should cipher suites be restricted beyond rustls defaults?

• Origin: tls.md
• Status: resolved
• Priority: medium
• Resolution: Restrict cipher suites to match the nginx scope: four ECDHE-AES-GCM suites for TLS 1.2 plus all TLS 1.3 suites. This provides behavioral parity during migration. See ADR-012.
• Cross-references: ADR-005, ADR-012

OQ-02: What log format should fail2ban consume?

• Origin: operations.md, proxy.md
• Status: resolved
• Priority: high
• Resolution: Custom structured log format with key=value pairs and RATE_LIMIT prefix. A corresponding custom fail2ban filter will be provided. See ADR-007.
• Cross-references: ADR-007

OQ-07: Should per-site TLS overrides be supported for mixed ACME/manual domains?

• Origin: tls.md, config.md
• Status: resolved
• Priority: low
• Resolution: Resolved by introducing [[listeners]] configuration. Each listener is an independent TLS endpoint with its own bind address, TLS config, and site routing. This supports both deployment models: (1) shared-IP multi-domain (one listener, SAN certificate, SNI routing) and (2) dedicated-IP single-domain (multiple listeners, each with its own IP/cert/domain). Mixed ACME/manual configurations are naturally supported since each listener has its own TLS mode. See ADR-019.
• Cross-references: ADR-011, ADR-019

Logging and Monitoring

OQ-03: Should the health check endpoint be on a separate port?

• Origin: operations.md
• Status: resolved
• Priority: low
• Resolution: Add a configurable local health check port (default: 9900) bound to 127.0.0.1 only. Health checks work even when TLS is misconfigured. There is no /health route on the main HTTPS listener — health checking is handled exclusively by the local port and admin socket. See ADR-013 and ADR-022.
• Cross-references: ADR-013, ADR-022

Configuration

OQ-04: Should config reload support a Unix domain socket API in addition to SIGHUP?

• Origin: config.md
• Status: resolved
• Priority: low
• Resolution: Yes. Add a Unix domain socket admin API alongside SIGHUP. The socket accepts a reload command and returns structured success/failure responses. SIGHUP is retained as a fallback. See ADR-014.
• Cross-references: ADR-014

Deployment

OQ-05: Should the proxy bind to multiple addresses or just one?

• Origin: overview.md
• Status: resolved
• Priority: low
• Resolution: A single bind_addr per listener entry is sufficient. ADR-019 introduced [[listeners]], where each listener has its own bind_addr. This supports multiple bind addresses in a single process — one per listener — without needing an array of addresses on a single listener. See ADR-016 and ADR-019.
• Cross-references: ADR-016, ADR-019

Proxy

OQ-06: Should upstream timeouts be configurable per-site?

• Origin: proxy.md
• Status: resolved
• Priority: low
• Resolution: Resolved by ADR-015. Per-site upstream timeout overrides with sensible defaults (5s connect, 60s request). Optional fields in SiteConfig that override global defaults when specified.
• Cross-references: ADR-015, ADR-017

OQ-08: Should the /health path use a less common endpoint to avoid upstream collision?

• Origin: Implementation review finding W5, proxy.md
• Status: resolved
• Priority: medium
• Resolution: The /health route does not belong on the main listener at all. Health checking is an operational concern served by the dedicated local port (9900) and the admin socket's status command — not by intercepting traffic on the public-facing proxy. Serving /health on the main listener creates collision with upstream applications, requires special-case routing logic before host-based matching, and is architecturally wrong: the main listener's job is to proxy requests, not to serve operational endpoints. The local health check port (bound to 127.0.0.1:9900) and the admin socket are the sole health/status mechanisms. See ADR-022.
• Cross-references: ADR-013, ADR-022

OQ-09: How should upstream_connect_timeout_secs be enforced?

• Origin: Implementation review finding W4, ADR-015, ADR-017
• Status: resolved
• Priority: medium
• Resolution: This is an implementation gap, not an architectural unknown. The architecture already specifies a 5-second default connect timeout separate from the request timeout (ADR-015, ADR-017), and SiteConfig already includes upstream_connect_timeout_secs. The implementation must wire this field to hyper's connect_timeout parameter. If hyper's API doesn't expose a separate connect timeout, a two-phase tokio::time::timeout approach should be used for Phase 2. For Phase 1, the connect timeout field exists in config but is not enforced — this is a documented known gap. No ADR needed; the decision was already made in ADR-015.
• Cross-references: ADR-015, ADR-017

OQ-10: Should ACME contact email be a required config field?

• Origin: Implementation review finding C2, tls.md, config.md
• Status: resolved
• Priority: high
• Resolution: This is not an open question — the architecture already specifies acme_contact as a required field in ACME mode (config.md validation rule 19). The field is defined in the ListenerConfig table and shown in TOML examples. Let's Encrypt requires a contact email for production certificate requests. The implementation bug (C2: contact: vec![]) must be fixed to use the configured acme_contact value. No new ADR needed — the decision is already documented in config.md and tls.md.
• Cross-references: ADR-004

OQ-11: How should X-Forwarded-Proto be derived per-listener?

• Origin: Implementation review finding W14, proxy.md
• Status: resolved
• Priority: medium
• Resolution: The hardcoded is_https: true behavior is correct for a TLS-terminating reverse proxy. The proxy only proxies requests on the HTTPS listener, which always sets X-Forwarded-Proto: https. The HTTP redirect listener sends a 301 redirect and does NOT proxy requests, so X-Forwarded-Proto is not set there. This behavior is correct and matches the architecture spec (proxy.md). The implementation should add a comment documenting this rationale to prevent future "fixes" that would change the behavior. No ADR or spec change needed — just a code comment.
• Cross-references: ADR-021

Operations

OQ-12: Should request access logging be mandatory or optional?

• Origin: Implementation review finding W13, operations.md
• Status: resolved
• Priority: high
• Resolution: Access logging is mandatory and always-on at info level. The architecture spec (operations.md) already states: "Access logging is always-on — it is the primary observability mechanism for the proxy and is required for fail2ban integration. There is no configuration option to disable access logging." The log_request! macro exists in the codebase but is not called — this is an implementation gap (W13), not an architectural question. No ADR needed; ADR-007 already covers the log format.
• Cross-references: ADR-007