Files

glm-5.1 9a2352e61c 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

2026-06-11 09:07:36 +00:00

2.6 KiB

Raw Blame History

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:

No feedback — the sender doesn't know if the reload succeeded or failed
No structured input — you can only signal "reload", not specify which parts to reload or pass validation context
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
config.md
ADR-009 (signal handling — SIGHUP retained as fallback)
OQ-04 (now resolved)

2.6 KiB Raw Blame History