Update README for admin HTTP API, mark tasks completed

- Replace admin socket section with admin HTTP API section
- Update config table (admin_socket_path → admin_key_path)
- Update project structure (admin/auth.rs, handler.rs, config/mod.rs)
- Update architecture diagram (Admin HTTP API instead of Unix socket)
- Update Docker compose volume (admin-key instead of socket dir)
- Mark all four task files as status: completed with summaries
This commit is contained in:
glm-5.1 committed 2026-06-15 06:34:21 +00:00
1 parent 0f4e9d596f
commit f6e62a37ef
5 files changed
+49 -24

No files matched your search

+25 -16
View File
@@ -28,7 +28,7 @@ server or load balancer.
- **Rate limiting** — per-IP token bucket with fail2ban-compatible structured
logging (IPv6 rate limited per /64 prefix)
- **Proxy headers** — X-Real-IP, X-Forwarded-For (edge proxy model), X-Forwarded-Proto
- **Hot config reload** — SIGHUP or admin Unix domain socket with success/failure
- **Hot config reload** — SIGHUP or authenticated admin HTTP API with success/failure
feedback
- **Health check** — localhost-only endpoint on a separate port (default: 9900)
- **HTTP → HTTPS redirect** — per-listener redirect on port 80
@@ -113,13 +113,13 @@ Configuration uses TOML and is split into **static** (requires restart) and
| `listeners` | (required) | TLS listener definitions |
| `allow_wildcard_bind` | `false` | Allow `0.0.0.0` bind addresses |
| `health_check_port` | `9900` | Local health check port (`0` to disable) |
| `admin_socket_path` | `/run/reverse-proxy/admin.sock` | Admin Unix socket (empty string to disable) |
| `admin_key_path` | `/etc/reverse-proxy/admin-key` | Path to admin Bearer token file (empty string to disable) |
| `shutdown_timeout_secs` | `30` | Graceful shutdown timeout |
| `logging.level` | `"info"` | Log level |
| `logging.format` | `"text"` | Log format (`"text"` or `"json"`) |
| `logging.log_file_path` | (not set) | Path to log file for fail2ban |
### Dynamic Config (hot-reloadable via SIGHUP or admin socket)
### Dynamic Config (hot-reloadable via SIGHUP or admin HTTP API)
| Field | Default | Description |
|-------|---------|-------------|
@@ -201,7 +201,7 @@ services:
- /etc/reverse-proxy/config.toml:/etc/reverse-proxy/config.toml:ro
- /var/lib/reverse-proxy/acme-cache:/var/lib/reverse-proxy/acme-cache
- /var/log/reverse-proxy:/var/log/reverse-proxy
- /run/reverse-proxy:/run/reverse-proxy
- /etc/reverse-proxy/admin-key:/etc/reverse-proxy/admin-key:ro
networks:
- proxy-net
healthcheck:
@@ -269,28 +269,34 @@ Enable file logging in config:
log_file_path = "/var/log/reverse-proxy/access.log"
```
## Admin Socket
## Admin HTTP API
The admin Unix domain socket supports two commands:
The admin HTTP API is available on the health check port (default: 9900) and
requires Bearer token authentication. Set `admin_key_path` to a file containing
the token (or leave empty to disable admin endpoints).
```bash
# Reload config
echo "reload" | socat - UNIX-CONNECT:/run/reverse-proxy/admin.sock
curl -X POST -H "Authorization: Bearer $ADMIN_KEY" http://127.0.0.1:9900/admin/reload
# Check status
echo "status" | socat - UNIX-CONNECT:/run/reverse-proxy/admin.sock
curl -H "Authorization: Bearer $ADMIN_KEY" http://127.0.0.1:9900/admin/status
# Rotate admin key
curl -X POST -H "Authorization: Bearer $ADMIN_KEY" http://127.0.0.1:9900/admin/rotate-key
```
Responses are newline-terminated JSON:
Responses are JSON:
```json
{"status":"ok"}
{"status":"ok","uptime_secs":1234,"sites":2}
{"status":"error","message":"config validation failed: ..."}
{"status":"error","message":"config file changed during read, please retry"}
```
Config can also be reloaded with `kill -SIGHUP $(pidof reverse-proxy)`, but
SIGHUP provides no feedback on success or failure.
If `admin_key_path` is empty or the key file is missing, admin endpoints return
`404 Not Found`. Config can also be reloaded with `kill -SIGHUP $(pidof
reverse-proxy)`, but SIGHUP provides no feedback on success or failure.
## Health Check
@@ -322,7 +328,7 @@ config.toml ──────► │ StaticConfig + DynamicConfig │
│ └────────────────────────────────┘ │
│ │
│ /health → 200 OK (port 9900) │
│ Admin socket (Unix domain) │
│ Admin HTTP API (port 9900, auth) │
└────────────────────────────────────┘
```
@@ -336,9 +342,11 @@ src/
├── cli.rs # CLI argument parsing
├── lib.rs # Library root
├── config/
│ ├── mod.rs # ReloadError, read_and_validate_config(), FullConfig
│ ├── static_config.rs # Immutable startup configuration
│ ├── dynamic_config.rs# Hot-reloadable runtime configuration
│ └── validation.rs # Config validation rules
│ ├── validation.rs # Config validation rules
│ └── test_fixtures.rs # Test config generation helpers
├── proxy/
│ ├── handler.rs # Core reverse proxy handler
│ ├── headers.rs # Proxy header injection
@@ -353,8 +361,9 @@ src/
│ ├── mod.rs # Rate limiting middleware
│ └── bucket.rs # Token bucket implementation
├── admin/
│ ├── socket.rs # Unix domain socket admin API
│ └── mod.rs
│ ├── auth.rs # Bearer token auth middleware
│ ├── handler.rs # HTTP handlers for /admin/reload, /status, /rotate-key
│ └── mod.rs # Re-exports
├── health.rs # Health check endpoint
├── logging/
│ ├── mod.rs # Logging initialization
+7 -2
View File
@@ -1,7 +1,7 @@
---
id: fix/agents-md-project-structure
name: Update AGENTS.md project structure and common modifications after admin refactor
status: pending
status: completed
depends_on: [fix/admin-http-api]
scope: narrow
risk: low
@@ -77,4 +77,9 @@ Unix socket (tokio::net::UnixStream).
## Summary
> To be filled on completion
Updated project structure (admin/auth.rs, handler.rs, mod.rs; config/mod.rs),
architecture concepts (admin HTTP API, TOCTOU check, wildcard bind consistency),
config format (admin_key_path), testing (HTTP-based admin tests), and common
modifications (curl commands replacing socat). Updated README.md with same
changes: admin HTTP API section, project structure, architecture diagram, config
table, and Docker compose volumes.
+5 -2
View File
@@ -1,7 +1,7 @@
---
id: fix/config-reload-toctou
name: Add mtime check to config reload to detect mid-write file changes (ADR-029)
status: pending
status: completed
depends_on: []
scope: narrow
risk: low
@@ -97,4 +97,7 @@ log a warning: "config file changed during read, please retry SIGHUP".
## Summary
> To be filled on completion
Implemented `read_and_validate_config()` in `src/config/mod.rs` with mtime check
before/after reading. Both SIGHUP and admin HTTP reload paths use this shared
function. `ReloadError::FileChangedDuringRead` returns HTTP 409 Conflict from
the admin endpoint and logs a warning on SIGHUP. 7 new unit tests added.
+6 -2
View File
@@ -1,7 +1,7 @@
---
id: fix/review-005-status-update
name: Update security review #005 status to reflect ADR-028 decision
status: pending
status: completed
depends_on: []
scope: narrow
risk: low
@@ -68,4 +68,8 @@ resolution status.
## Summary
> To be filled on completion
Updated review #005 status to `resolved`, added resolution table annotating all
findings. Updated W2/W5/W6 rows to show resolved status. Updated reviewed_code
to reference new admin files (auth.rs, handler.rs, mod.rs). Updated review #006
status to `resolved`, replaced Category 6 (admin socket → admin HTTP API),
updated entries 4.2, 4.3, P4, and reviewed_code for new file paths and mtime check.
+6 -2
View File
@@ -1,7 +1,7 @@
---
id: fix/wildcard-flag-reload
name: Store cli_allow_wildcard_bind in ConfigReloadHandle for consistent reload validation (ADR-030)
status: pending
status: completed
depends_on: []
scope: narrow
risk: low
@@ -109,4 +109,8 @@ parameter. Add a test that verifies:
## Summary
> To be filled on completion
Added `cli_allow_wildcard_bind: bool` field to `ConfigReloadHandle`, stored at
construction time from `LoadedConfig.allow_wildcard_bind`. `reload()` now passes
`self.cli_allow_wildcard_bind` to `validate()` instead of hardcoded `false`.
All call sites updated. 2 new unit tests verify wildcard bind acceptance/rejection
on reload.