Resolve 5 open questions, add 7 ADRs for previously undocumented decisions
Resolve open questions: - OQ-01: Restrict cipher suites to match nginx scope (4 ECDHE-AES-GCM suites for TLS 1.2 + all TLS 1.3 suites) — ADR-012 - OQ-03: Health check on separate local port (default 9900, localhost only) — ADR-013 - OQ-04: Add Unix domain socket admin API for config reload alongside SIGHUP, with structured success/failure responses — ADR-014 - OQ-06: Per-site upstream timeouts with defaults (5s connect, 60s request), overridable in SiteConfig — ADR-015 Document previously undocumented decisions flagged by architecture review: - ADR-016: Explicit bind address requirement (reject 0.0.0.0) - ADR-017: Upstream connection defaults (HTTP/1.1, no redirects, pooling) - ADR-018: 100 MB body size limit (matches nginx, Gitea compatibility) OQ-07 (per-site TLS overrides) remains open for future consideration. Spec updates: - config.md: add health_check_port, admin_socket_path, per-site timeout fields, update TOML example and validation rules - proxy.md: reference ADR-015/017/018 for timeouts, connection defaults, and body limit decisions - tls.md: replace OQ-01 cipher suite section with ADR-012 decision - operations.md: add local health check port section, admin socket reload - overview.md: update Phase 1 scope with new features, add ADR references - open-questions.md: resolve OQ-01/03/04/06, keep OQ-07 open
This commit is contained in:
76
docs/architecture/decisions/014-unix-socket-reload.md
Normal file
76
docs/architecture/decisions/014-unix-socket-reload.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# ADR-014: Unix Domain Socket Config Reload API
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The proxy supports config reload via SIGHUP (ADR-009). SIGHUP is simple and
|
||||
well-understood, but has limitations:
|
||||
|
||||
1. No feedback — the sender doesn't know if the reload succeeded or failed
|
||||
2. No structured input — you can only signal "reload", not specify which parts
|
||||
to reload or pass validation context
|
||||
3. Requires process signal permissions — not all deployment tools can send
|
||||
signals
|
||||
|
||||
A Unix domain socket API would allow programmatic config reload with
|
||||
success/failure status, enabling integration with CI/CD pipelines, admin
|
||||
tools, and automated configuration management.
|
||||
|
||||
## Decision
|
||||
|
||||
Add a Unix domain socket API for config reload alongside SIGHUP. The socket
|
||||
accepts commands and returns structured responses.
|
||||
|
||||
The socket path is configurable via `admin_socket_path` in StaticConfig
|
||||
(default: `/run/reverse-proxy/admin.sock`). Setting it to empty string
|
||||
disables the admin socket.
|
||||
|
||||
Initial commands:
|
||||
|
||||
- `reload` — Re-read config file, validate, and swap DynamicConfig. Returns
|
||||
`{"status": "ok"}` or `{"status": "error", "message": "..."}`.
|
||||
- `status` — Return basic process info (uptime, config load time, site count).
|
||||
Returns `{"status": "ok", "uptime_secs": 1234, "sites": 2}`.
|
||||
|
||||
Future commands (not in Phase 1, but the protocol supports extension):
|
||||
|
||||
- `metrics` — Return Prometheus-compatible metrics
|
||||
- `shutdown` — Graceful shutdown command
|
||||
|
||||
## Rationale
|
||||
|
||||
- Providing reload feedback is operationally valuable — CI/CD pipelines can
|
||||
verify config changes before proceeding
|
||||
- The implementation cost is low — a Unix domain socket listener is ~50 lines
|
||||
of tokio code, and the command protocol is simple
|
||||
- SIGHUP is retained as a fallback for environments where socket access is
|
||||
inconvenient
|
||||
- This pattern will integrate naturally with alknet's admin interface when the
|
||||
projects merge
|
||||
- Unix domain sockets are filesystem-permission-based, providing access control
|
||||
without additional authentication
|
||||
- The socket path is configurable, allowing deployment-specific paths
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
- Config reload with success/failure feedback
|
||||
- Programmatic integration with CI/CD and admin tools
|
||||
- Structured response format enables automation
|
||||
- SIGHUP still works as fallback
|
||||
- Natural path to future admin commands
|
||||
|
||||
**Negative:**
|
||||
- Additional listener and command parsing logic (~100-150 lines)
|
||||
- Socket file management (cleanup on startup, stale socket detection)
|
||||
- One more config option (`admin_socket_path`)
|
||||
|
||||
## References
|
||||
|
||||
- [operations.md](../operations.md)
|
||||
- [config.md](../config.md)
|
||||
- ADR-009 (signal handling — SIGHUP retained as fallback)
|
||||
- OQ-04 (now resolved)
|
||||
Reference in New Issue
Block a user