Update docs: reviews #005/#006 resolved status, AGENTS.md admin refactor

- Review #005: update W2/W5/W6 rows to show resolved status
- Review #005: update reviewed_code to reference new admin files
- Review #006: update status from draft to resolved
- Review #006: update Category 4 (SIGHUP/admin reload) for mtime check
- Review #006: update Category 6 (admin interface) for HTTP API
- Review #006: update P4 and reviewed_code for new file paths
- AGENTS.md: update project structure (admin/, config/mod.rs)
- AGENTS.md: update architecture concepts (admin HTTP, TOCTOU, wildcard)
- AGENTS.md: update config format (admin_key_path)
- AGENTS.md: update testing (admin HTTP tests)
- AGENTS.md: update common modifications (curl instead of socat)
This commit is contained in:
glm-5.1 committed 2026-06-15 06:18:12 +00:00
1 parent 143ebaae93
commit 0f4e9d596f
3 files changed
+86 -51

No files matched your search

+30 -5
View File
@@ -35,6 +35,7 @@ src/
├── cli.rs # CLI parsing (clap), config loading, validation
├── lib.rs # Library root, module declarations
├── config/
│ ├── mod.rs # ReloadError, read_and_validate_config(), FullConfig
│ ├── static_config.rs # StaticConfig — immutable, requires restart
│ ├── dynamic_config.rs# DynamicConfig — hot-reloadable via ArcSwap
│ ├── validation.rs # Config validation rules (called at startup and reload)
@@ -54,8 +55,9 @@ src/
│ ├── mod.rs # Rate limiting middleware, eviction task
│ └── bucket.rs # Token bucket implementation (IPv4 /32, IPv6 /64)
├── admin/
│ ├── socket.rs # Unix domain socket admin API (reload, status)
│ └── mod.rs
│ ├── auth.rs # Bearer token auth middleware (subtle, SHA-256)
│ ├── handler.rs # HTTP handlers for /admin/reload, /status, /rotate-key
│ └── mod.rs # Re-exports
├── health.rs # Health check endpoint on localhost:9900
├── logging/
│ ├── mod.rs # Logging init (file + stdout, ANSI disabled)
@@ -69,7 +71,7 @@ src/
- **StaticConfig vs DynamicConfig**: Static config (bind addresses, TLS,
ports) requires a restart. Dynamic config (sites, rate limits, body limits)
can be reloaded at runtime via SIGHUP or admin socket, using `ArcSwap` for
can be reloaded at runtime via SIGHUP or admin HTTP API, using `ArcSwap` for
lock-free reads.
- **Multi-listener**: `[[listeners]]` in TOML — each listener has its own bind
address, TLS config, and site routing. Sites are collected into a global
@@ -78,10 +80,18 @@ src/
(not appended), X-Real-IP is set from the connection's remote address.
- **No `/health` on public listener**: Health checking is localhost:9900 only.
The main listener does not intercept any paths.
- **Admin HTTP API**: Authenticated Bearer token endpoints on the health check
port (`admin_key_path`). Empty `admin_key_path` disables admin endpoints
(returns 404). Key file contains plaintext token, read once at startup.
- **HTTP/2 client-facing only**: ALPN detects h2 vs http/1.1. Upstream
connections are always HTTP/1.1.
- **IPv6 rate limiting**: IPv6 addresses are normalized to /64 prefixes so
addresses within the same /64 share a token bucket.
- **Config reload TOCTOU**: Both SIGHUP and admin HTTP reload paths use
`read_and_validate_config()` which checks file mtime before and after
reading. If mtime changed, reload is rejected with a retry message.
- **Wildcard bind consistency**: `cli_allow_wildcard_bind` is stored in
`ConfigReloadHandle` and used for both startup and reload validation.
## Config Format
@@ -99,12 +109,15 @@ TOML. See `docs/architecture/config.md` for full schema. Key validation rules:
- `http_port` must be 0 (disabled) or 1–65535; `https_port` must be 1–65535
- `health_check_port` must not conflict with any listener's http_port or
https_port on the same bind address
- `admin_key_path` must be an absolute path or empty (empty disables admin);
path traversal (`..`) is rejected; default is `/etc/reverse-proxy/admin-key`
## Testing
Tests use `rcgen` for self-signed certificate generation and `reqwest` for
HTTP client requests. Integration tests are in `tests/integration_test.rs`
with helpers in `tests/helpers/`.
with helpers in `tests/helpers/`. Admin endpoint tests use `reqwest` HTTP
client with Bearer token authentication.
```bash
cargo test # all tests
@@ -139,7 +152,19 @@ See `deploy/README.md` for step-by-step setup instructions.
Add a `[[listeners.sites]]` entry to config and reload:
```bash
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
```
### Checking proxy status
```bash
curl -H "Authorization: Bearer $ADMIN_KEY" http://127.0.0.1:9900/admin/status
```
### Rotating the admin key
```bash
curl -X POST -H "Authorization: Bearer $ADMIN_KEY" http://127.0.0.1:9900/admin/rotate-key
```
### Changing rate limits