glm-5.1
fe1ae6c05e
Resolve OQ-08 through OQ-12 after reviewing implementation findings: - OQ-08: Remove /health route from the main HTTPS listener entirely. Health checking belongs on port 9900 and admin socket only, not on the public-facing proxy. This eliminates upstream collision problems and special-case routing logic. (ADR-022) - OQ-09: Not an architectural unknown — ADR-015 already decided on a separate connect timeout. The implementation gap is a known issue. - OQ-10: Not an open question — acme_contact is already specified as required in config.md. The empty contact list is bug C2. - OQ-11: Hardcoded is_https=true is correct for a TLS-terminating proxy. HTTP listener redirects, doesn't proxy. Just needs a comment. - OQ-12: Access logging is already specified as mandatory/always-on in operations.md. Missing log_request! calls are bug W13. Updated docs: proxy.md, operations.md, overview.md, config.md, open-questions.md, README.md, ADR-013. Created ADR-022.
171 lines
7.5 KiB
Markdown
171 lines
7.5 KiB
Markdown
---
|
|
status: draft
|
|
last_updated: 2026-06-12
|
|
---
|
|
|
|
# Open Questions
|
|
|
|
## TLS
|
|
|
|
### ~~OQ-01: Should cipher suites be restricted beyond rustls defaults?~~
|
|
|
|
- **Origin**: [tls.md](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](operations.md), [proxy.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](tls.md), [config.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](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](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](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](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](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](tls.md), [config.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](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](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 |