- Split TODO into a thin status index plus docs/roadmap/ with one file per task (v0.4 reliability, v0.5 product, v0.6 research, icebox). - Add docs/architecture.md (current processes, packet/data path, layers, storage, metrics) and docs/development.md (rules, gates, DoD). - Add CHANGELOG.md reconstructed from history; move round details out of TODO. - Align docs with the code: config defaults and missing [detect]/ [protocol.http] sections, XDP metric names, ClickHouse table and TTL, Redis RDB restore, multiarch clang include, CLI binary name. - Add scripts/check_docs_links.sh and run it in CI. - release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB, http parser bench 314 ns -> 278 ns; panic=abort stays off for catch_unwind in the Redis subscriber. - Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
162 lines
6.1 KiB
Markdown
162 lines
6.1 KiB
Markdown
# API Reference - Rampart Manager
|
||
|
||
> REST API управления. Base URL: `http://MANAGER:8080`
|
||
> Авторизация: Bearer JWT (получить через `/api/v1/auth/login`).
|
||
|
||
Реализованные маршруты — см. `src/manager/api/guard/router.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-команда `rampart-cli drain <node>` существует, но
|
||
завершается явной ошибкой «not implemented»);
|
||
- 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.1 | Ноябрь 2026*
|