guard/docs/api.md
loki5512344 280284667f
docs: per-task roadmap, architecture and changelog
- 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.
2026-11-16 14:51:50 +01:00

162 lines
6.1 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/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*