reverse-proxy/tasks/ops/admin-socket.md at 36319db10e1f72bc42315234a985f7c0836ee1f7

Files

glm-5.1 309878c561 Decompose architecture into 23 atomic tasks across 7 parallel generations

Task graph covers all Phase 1 concerns: config system, TLS termination,
proxy handler, operations (rate limiting, logging, health check, admin
socket, signals, shutdown, body size limit), deployment artifacts, and
two review checkpoints.

No circular dependencies. Critical path length of 7. Risk distribution:
3 high-risk (ACME, TLS listener setup, startup orchestration), 7 medium,
11 low, 2 trivial.

2026-06-11 11:21:10 +00:00

3.0 KiB

Raw Blame History

id, name, status, depends_on, scope, risk, impact, level

name

status

depends_on

scope

risk

impact

level

ops/admin-socket

Implement Unix domain socket admin API for config reload with feedback and status

pending

config/dynamic-config

moderate

medium

component

implementation

Description

Implement the Unix domain socket admin API for programmatic config reload with success/failure feedback. This is an alternative to SIGHUP that provides structured responses.

Protocol

Connection lifecycle: One command per connection. Client connects, sends one newline-terminated command, receives one newline-terminated JSON response, then the server closes the connection.
Message framing: Newline-delimited (\n). Responses end with \n.

Commands

reload — Re-read config file, validate, and swap DynamicConfig. Returns:
- Success: {"status": "ok"}
- Failure: {"status": "error", "message": "..."}
status — Return basic process info. Returns:
- {"status": "ok", "uptime_secs": 1234, "sites": 2}

Error Responses

Unrecognized commands: {"status": "error", "message": "unknown command: <cmd>"}
Invalid or empty input: {"status": "error", "message": "invalid input"}

Socket Lifecycle

Socket path from admin_socket_path config (default: /run/reverse-proxy/admin.sock)
Empty string disables the admin socket
Remove any existing socket file at startup before binding
If the socket file exists and another process is listening, log a warning and disable the admin socket (but continue starting)

Concurrency

Multiple clients can connect simultaneously
Reload operations are serialized via the same tokio::sync::Mutex used by SIGHUP reload
If a reload is in progress, subsequent reload requests wait, then re-read the config file (getting the latest version)

Acceptance Criteria

Unix domain socket bound at admin_socket_path
reload command triggers config reload and returns structured JSON response
status command returns process uptime and site count
Unknown commands return {"status": "error", "message": "unknown command: ..."}
Empty/invalid input returns {"status": "error", "message": "invalid input"}
One command per connection, server closes connection after response
Stale socket file removed at startup
If socket file exists and is active (another process), log warning and continue
admin_socket_path = "" disables admin socket
Reload operations serialized with same Mutex as SIGHUP reload
Integration test: connect to socket, send reload, receive JSON response
Integration test: connect to socket, send status, receive JSON response

References

docs/architecture/operations.md — admin socket section
docs/architecture/decisions/014-unix-socket-reload.md — admin socket rationale
docs/architecture/config.md — reload serialization

Notes

The admin socket and SIGHUP converge on the same reload code path. The only difference is that the admin socket returns a structured response while SIGHUP provides no feedback.

Summary

To be filled on completion

3.0 KiB Raw Blame History