guard/docs/api.md
loki5512344 e456cb583f
feat(manager): SCAN inventory, pagination, request limits, graceful shutdown
- Inventory nodes/servers use cursor SCAN plus MGET batches instead of KEYS
  and per-key GET; a Redis error returns 503 instead of an empty fleet.
- GET /blacklist no longer writes: the legacy metadata backfill moved to a
  one-shot startup task. The list endpoint paginates (limit 100, max 1000,
  offset max 10000) instead of dumping SMEMBERS.
- Router-wide DefaultBodyLimit 8 KiB and TimeoutLayer 10 s; every mutating
  endpoint is rate limited (30/min per client IP) with idle eviction, and the
  login limiter resets on success. reason > 256 bytes and malformed targets
  are rejected with 400.
- SIGTERM/Ctrl-C trigger graceful shutdown; the heartbeat and eviction tasks
  are cancelled and joined so in-flight ban edits reach Redis.
- MANAGER_TRUSTED_PROXIES enables X-Forwarded-For (right-to-left walk) only
  for configured proxy networks; otherwise the TCP peer is used.
- tests/manager_api.rs covers 401/400/413/429/503 and CORS preflight through
  the real router; manager_security gains limiter and proxy-IP tests.
2026-11-16 12:36:29 +01:00

160 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# API Reference - Rampart Manager
> REST API управления. Base URL: `http://MANAGER:8080`
> Авторизация: Bearer JWT (получить через `/api/v1/auth/login`).
Реализованные маршруты — см. src/bin/rampart-manager.rs. Это полный список:
ничего сверх перечисленного здесь API не предоставляет.
---
## Аутентификация
### `POST /api/v1/auth/login`
```json
// Request
{"password": "значение API_PASSWORD"}
// Response 200
{"token": "eyJhbGciOiJIUzI1NiIs..."}
// 401 → неверный пароль; 429 → больше 5 попыток за минуту с одного IP
```
Все защищённые запросы:
```
Authorization: Bearer <token>
```
Токен живёт `JWT_EXPIRATION_SECS` секунд (дефолт 86400).
---
## Health (публичный)
### `GET /api/v1/health`
```json
{"status": "healthy", "version": "0.3.0-dev"}
```
---
## Servers
### `GET /api/v1/servers` 🔒
Список серверов из Redis-реестра (`rampart:servers:*`).
```json
{
"servers": [
{"name": "app-01", "type": "tcp", "ip": "10.0.2.1", "port": 25566, "status": "online"}
]
}
```
Если Redis недоступен, API возвращает `503 Service Unavailable`.
---
## Blacklist
### `GET /api/v1/blacklist` 🔒
Query: `limit` (по умолчанию 100, максимум 1000) и `offset` (максимум 10000).
```json
{
"items": [
{"target": "1.2.3.4", "type": "ip", "reason": "manual_ban",
"created_at": "2026-10-16T12:00:00+00:00", "expires_at": "2026-10-16T13:00:00+00:00"}
],
"total": 42
}
```
Источник: Redis set `rampart:blacklist` и hash `rampart:blacklist:metadata`.
Записи читаются через `SSCAN` порциями, поэтому set никогда не выгружается целиком;
порядок страниц не определён (Redis set) и при параллельных изменениях страницы
могут пересекаться. `total` — размер set по `SCARD`, он может включать истёкшие
записи, которые API скрывает в `items`.
Метаданные содержат причину, время создания и абсолютный срок истечения; API
скрывает истёкшие записи. `GET` ничего не пишет в Redis: старые set-записи без
метаданных показываются с временной записью «пять минут» только для чтения, а
сама метаданные восстанавливаются одноразовым фоновым backfill при старте
manager (или при восстановлении снимка edge).
### `POST /api/v1/blacklist` 🔒
```json
// Request
{"target": "1.2.3.4", "type": "ip", "reason": "manual_ban", "duration_secs": 3600}
// Response 200 — запись и метаданные атомарно сохранены в Redis, а событие
// с duration_secs и expires_at_unix опубликовано в rampart:blacklist:events.
```
`target` — одиночный IPv4/IPv6-адрес (CIDR не поддерживается), `reason` — не
длиннее 256 байт; иначе `400 Bad Request`.
Edge подписывается на Pub/Sub перед загрузкой снимка из Redis. Поэтому события,
пришедшие во время загрузки, будут применены после снимка. При старте и после
переподключения активные Redis-баны восстанавливаются с оставшимся TTL; новые
события используют абсолютный срок и игнорируются, если он уже прошёл. Старый
формат события только с `duration_secs` продолжает поддерживаться.
### `DELETE /api/v1/blacklist` 🔒
```json
{"target": "1.2.3.4"}
```
Удаляет только Redis-бан и его метаданные, затем публикует событие unban.
Локальные баны детекторов хранятся отдельно и этим запросом не снимаются.
---
## Nodes
### `GET /api/v1/nodes` 🔒
Список зарегистрированных edge-нод из Redis (`rampart:nodes:*`, heartbeat).
Если Redis недоступен, API возвращает `503 Service Unavailable`; пустой массив
означает исправное, но пустое окружение.
```json
{
"nodes": [
{"id": "edge-eu-1", "role": "edge", "ip": "10.0.100.1",
"status": "online", "last_heartbeat": "..."}
]
}
```
---
## Не реализовано
Честно, на текущий момент в API **нет**:
- drain нод через API или CLI;
- webhooks, metrics summary, challenge management;
- регистрации нод через `POST /api/v1/nodes`.
## Ограничения запросов
- Тело запроса — не больше 8 КиБ (`413`), любой запрос — не дольше 10 секунд.
- `/api/v1/auth/login` — 5 попыток в минуту с одного клиентского адреса (`429`).
- `POST`/`DELETE /api/v1/blacklist` (и любые будущие mutating-методы) — 30 запросов
в минуту с одного клиентского адреса (`429`); успешный login сбрасывает счётчик.
- Клиентский адрес — TCP peer, если запрос не пришёл с сети из
`MANAGER_TRUSTED_PROXIES`; только тогда используется `X-Forwarded-For`.
---
*Версия: 2.0 | Август 2026*