feat!: universal redesign — drop Minecraft stack, single-crate architecture
- remove Java plugins (velocity/paper), dashboard, all MC-specific code
(handshake, death_code, varint, hostname-HMAC); available in history pre-v0.2
- merge crates/* into one package with src/bin/{rampart,rampart-manager,rampart-cli}
- ProtocolHandler trait + registry (no implementations yet), universal PoW kept
- XDP: universal L3/L4 filter (xdp/core/) + pluggable hook API (xdp/hooks/),
fix IPv6 saddr bug; clang build verified
- docs: bilingual knowledge base (docs/kb/: attacks x4, defense-levels,
practice x3), rewrite README/architecture for universal concept
- TODO.md v4.0: <=300-line module limit, competitor benchmark section (ref/)
- deploy/CI/docs cleanup: no MC references, new binary names
cargo build/clippy(-D warnings)/test green (55 tests)
This commit is contained in:
parent
0b53ed720b
commit
15f474486a
GPG key ID:
253067914055423B
179 changed files with 5044 additions and 11519 deletions
424
docs/api.md
424
docs/api.md
|
|
@ -1,8 +1,10 @@
|
|||
# API Reference - Rampart Manager
|
||||
|
||||
> REST API для управления Rampart.
|
||||
> Base URL: `https://manager.rampart.internal/api/v1`
|
||||
> Авторизация: Bearer JWT (получить через `/api/v1/auth/login`)
|
||||
> REST API управления. Base URL: `http://MANAGER:8080`
|
||||
> Авторизация: Bearer JWT (получить через `/api/v1/auth/login`).
|
||||
|
||||
Реализованные маршруты — см. src/bin/rampart-manager.rs. Это полный список:
|
||||
ничего сверх перечисленного здесь API не предоставляет.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -10,408 +12,110 @@
|
|||
|
||||
### `POST /api/v1/auth/login`
|
||||
|
||||
Получение JWT токена.
|
||||
|
||||
```json
|
||||
// Request
|
||||
{
|
||||
"password": "changeme"
|
||||
}
|
||||
{"password": "значение API_PASSWORD"}
|
||||
|
||||
// Response 200
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIs..."
|
||||
}
|
||||
{"token": "eyJhbGciOiJIUzI1NiIs..."}
|
||||
|
||||
// 401 → неверный пароль; 429 → больше 5 попыток за минуту с одного IP
|
||||
```
|
||||
|
||||
Все последующие запросы:
|
||||
Все защищённые запросы:
|
||||
|
||||
```
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
Токен живёт `JWT_EXPIRATION_SECS` секунд (дефолт 86400).
|
||||
|
||||
---
|
||||
|
||||
## Nodes
|
||||
## Health (публичный)
|
||||
|
||||
### `GET /api/v1/nodes`
|
||||
|
||||
Список всех зарегистрированных нод.
|
||||
### `GET /api/v1/health`
|
||||
|
||||
```json
|
||||
// Response 200
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"id": "edge-eu-1",
|
||||
"role": "edge",
|
||||
"ip": "10.0.100.1",
|
||||
"public_ip": "45.200.10.1",
|
||||
"status": "online",
|
||||
"version": "0.4.0",
|
||||
"uptime_secs": 86400,
|
||||
"metrics": {
|
||||
"connections_per_sec": 1200,
|
||||
"active_connections": 45000,
|
||||
"cpu_percent": 45.2,
|
||||
"memory_mb": 512
|
||||
},
|
||||
"last_heartbeat": "2026-07-19T10:30:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/v1/nodes/{id}`
|
||||
|
||||
Детальная информация о ноде.
|
||||
|
||||
### `POST /api/v1/nodes`
|
||||
|
||||
Регистрация новой ноды (или через авто-discovery).
|
||||
|
||||
```json
|
||||
// Request
|
||||
{
|
||||
"name": "edge-us-2",
|
||||
"role": "edge",
|
||||
"public_ip": "45.200.20.5",
|
||||
"wg_public_key": "<BASE64_KEY>"
|
||||
}
|
||||
|
||||
// Response 201
|
||||
{
|
||||
"id": "edge-us-2",
|
||||
"wg_config": "https://manager/api/v1/nodes/edge-us-2/wg-config",
|
||||
"tls_cert": "https://manager/api/v1/nodes/edge-us-2/cert"
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/v1/nodes/{id}/drain`
|
||||
|
||||
Вывести ноду из ротации (graceful shutdown).
|
||||
|
||||
```json
|
||||
// Response 200
|
||||
{
|
||||
"status": "draining",
|
||||
"active_connections_before": 45000,
|
||||
"estimated_seconds": 30
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Blacklist
|
||||
|
||||
### `GET /api/v1/blacklist`
|
||||
|
||||
Список забаненных IP/ASN.
|
||||
|
||||
| Параметр | Тип | По умолчанию | Описание |
|
||||
|----------|-----|-------------|----------|
|
||||
| `page` | int | 1 | Пагинация |
|
||||
| `per_page` | int | 100 | Элементов на странице |
|
||||
| `reason` | string | - | Фильтр по причине |
|
||||
| `search` | string | - | Поиск по IP/ASN |
|
||||
|
||||
```json
|
||||
// Response 200
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"target": "1.2.3.4",
|
||||
"type": "ip", // ip | asn | cidr
|
||||
"reason": "rate_limit",
|
||||
"created_by": "admin",
|
||||
"created_at": "2026-07-19T10:00:00Z",
|
||||
"expires_at": "2026-07-20T10:00:00Z",
|
||||
"hits": 1500
|
||||
}
|
||||
],
|
||||
"total": 42,
|
||||
"page": 1,
|
||||
"per_page": 100
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/v1/blacklist`
|
||||
|
||||
Добавить IP/ASN/CIDR в блэклист.
|
||||
|
||||
```json
|
||||
// Request
|
||||
{
|
||||
"target": "1.2.3.4",
|
||||
"type": "ip", // ip | asn | cidr
|
||||
"reason": "manual_ban",
|
||||
"duration_secs": 3600 // null = навсегда
|
||||
}
|
||||
|
||||
// Response 201
|
||||
{
|
||||
"status": "added",
|
||||
"target": "1.2.3.4",
|
||||
"propagated_to_nodes": 2,
|
||||
"expires_at": "2026-07-19T11:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### `DELETE /api/v1/blacklist/{id}`
|
||||
|
||||
Удалить запись из блэклиста.
|
||||
|
||||
```json
|
||||
// Response 200
|
||||
{
|
||||
"status": "removed",
|
||||
"target": "1.2.3.4"
|
||||
}
|
||||
{"status": "healthy", "version": "0.3.0-dev"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Servers
|
||||
|
||||
### `GET /api/v1/servers`
|
||||
### `GET /api/v1/servers` 🔒
|
||||
|
||||
Список зарегистрированных game серверов.
|
||||
Список серверов из Redis-реестра (`rampart:servers:*`).
|
||||
|
||||
```json
|
||||
// Response 200
|
||||
{
|
||||
"servers": [
|
||||
{
|
||||
"name": "survival-01",
|
||||
"type": "survival",
|
||||
"ip": "10.0.2.1",
|
||||
"port": 25565,
|
||||
"status": "online",
|
||||
"proxy": "velocity-01",
|
||||
"online": 42,
|
||||
"max_players": 100,
|
||||
"tps": 19.8,
|
||||
"mspt": 25.3,
|
||||
"ram_used_mb": 2048,
|
||||
"ram_max_mb": 8192,
|
||||
"last_heartbeat": "2026-07-19T10:30:00Z"
|
||||
}
|
||||
{"name": "app-01", "type": "tcp", "ip": "10.0.2.1", "port": 25566, "status": "online"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/v1/servers/{name}`
|
||||
|
||||
Детальная информация о сервере.
|
||||
|
||||
### `DELETE /api/v1/servers/{name}`
|
||||
|
||||
Принудительно удалить сервер из registry.
|
||||
Redis недоступен → пустой список.
|
||||
|
||||
---
|
||||
|
||||
## Challenges (v0.5+)
|
||||
## Blacklist
|
||||
|
||||
### `GET /api/v1/challenges/status`
|
||||
|
||||
Статус challenge системы.
|
||||
### `GET /api/v1/blacklist` 🔒
|
||||
|
||||
```json
|
||||
// Response 200
|
||||
{
|
||||
"enabled": true,
|
||||
"mode": "auto",
|
||||
"active_challenges": 15,
|
||||
"passed_last_hour": 1200,
|
||||
"failed_last_hour": 45,
|
||||
"current_type": "timing"
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/v1/challenges/rotate`
|
||||
|
||||
Принудительно сменить тип challenge.
|
||||
|
||||
```json
|
||||
// Request
|
||||
{
|
||||
"type": "map_captcha" // timing | map_captcha | behavioral | contextual
|
||||
}
|
||||
|
||||
// Response 200
|
||||
{
|
||||
"status": "rotated",
|
||||
"previous_type": "timing",
|
||||
"new_type": "map_captcha",
|
||||
"rotated_at": "2026-07-19T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Metrics
|
||||
|
||||
### `GET /api/v1/metrics/summary`
|
||||
|
||||
Сводка метрик за период.
|
||||
|
||||
| Параметр | Тип | По умолчанию | Описание |
|
||||
|----------|-----|-------------|----------|
|
||||
| `since` | ISO8601 | -24h | Начало периода |
|
||||
| `until` | ISO8601 | now | Конец периода |
|
||||
|
||||
```json
|
||||
// Response 200
|
||||
{
|
||||
"total_connections": 5200000,
|
||||
"blocked": 45000,
|
||||
"allowed": 5155000,
|
||||
"active_connections": 85000,
|
||||
"top_attackers": [
|
||||
{"ip": "5.5.5.5", "hits": 12000, "country": "NL"},
|
||||
{"ip": "6.6.6.6", "hits": 8000, "country": "RU"}
|
||||
"items": [
|
||||
{"target": "1.2.3.4", "type": "ip", "reason": "manual_ban",
|
||||
"created_at": "...", "expires_at": null}
|
||||
],
|
||||
"top_countries": [
|
||||
{"country": "US", "connections": 2000000},
|
||||
{"country": "DE", "connections": 1000000}
|
||||
"total": 42
|
||||
}
|
||||
```
|
||||
|
||||
Источник: Redis set `rampart:blacklist`. Пагинации и фильтров нет.
|
||||
|
||||
### `POST /api/v1/blacklist` 🔒
|
||||
|
||||
```json
|
||||
// Request
|
||||
{"target": "1.2.3.4", "type": "ip", "reason": "manual_ban", "duration_secs": 3600}
|
||||
|
||||
// Response 200/201 — запись добавлена в Redis set
|
||||
```
|
||||
|
||||
Edge-ноды подхватывают ban при следующей синхронизации блэклиста.
|
||||
|
||||
---
|
||||
|
||||
## Nodes
|
||||
|
||||
### `GET /api/v1/nodes` 🔒
|
||||
|
||||
Список зарегистрированных edge-нод из Redis (`rampart:nodes:*`, heartbeat).
|
||||
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{"id": "edge-eu-1", "role": "edge", "ip": "10.0.100.1",
|
||||
"status": "online", "last_heartbeat": "..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Health
|
||||
## Не реализовано
|
||||
|
||||
### `GET /api/v1/health`
|
||||
Честно, на текущий момент в API **нет**:
|
||||
|
||||
```json
|
||||
// Response 200
|
||||
{
|
||||
"status": "healthy",
|
||||
"version": "0.4.0",
|
||||
"uptime_secs": 604800,
|
||||
"components": {
|
||||
"redis": "healthy",
|
||||
"nats": "healthy",
|
||||
"clickhouse": "healthy",
|
||||
"edge_nodes": {"online": 2, "offline": 0},
|
||||
"velocity_nodes": {"online": 3, "offline": 1},
|
||||
"game_servers": {"online": 45, "offline": 2}
|
||||
}
|
||||
}
|
||||
```
|
||||
- удаления записей blacklist (только add/list);
|
||||
- drain нод через API (есть только CLI `rampart-cli drain`);
|
||||
- webhooks, metrics summary, challenge management;
|
||||
- регистрации нод через `POST /api/v1/nodes`;
|
||||
- rate limiting на сами запросы API (кроме login).
|
||||
|
||||
---
|
||||
|
||||
## Webhooks
|
||||
|
||||
### `POST /api/v1/webhooks`
|
||||
|
||||
Настройка webhook для событий.
|
||||
|
||||
```json
|
||||
// Request
|
||||
{
|
||||
"url": "https://discord.com/api/webhooks/...",
|
||||
"events": ["blacklist.added", "node.down", "attack.detected"],
|
||||
"secret": "optional_hmac_secret"
|
||||
}
|
||||
|
||||
// Response 201
|
||||
{
|
||||
"id": "wh_abc123",
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
### Payload пример (blacklist.added)
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "blacklist.added",
|
||||
"timestamp": "2026-07-19T10:30:00Z",
|
||||
"data": {
|
||||
"target": "1.2.3.4",
|
||||
"reason": "rate_limit",
|
||||
"added_by": "auto"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## OpenAPI Spec
|
||||
|
||||
Полная OpenAPI 3.0 спецификация: `docs/api/openapi.yaml`
|
||||
|
||||
```yaml
|
||||
openapi: "3.0.3"
|
||||
info:
|
||||
title: Rampart Manager API
|
||||
version: "0.4.0"
|
||||
servers:
|
||||
- url: https://manager.rampart.internal/api/v1
|
||||
paths:
|
||||
/nodes:
|
||||
get:
|
||||
summary: List all nodes
|
||||
security:
|
||||
- bearerAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Node list
|
||||
/blacklist:
|
||||
post:
|
||||
summary: Add to blacklist
|
||||
security:
|
||||
- bearerAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
target:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
enum: [ip, asn, cidr]
|
||||
reason:
|
||||
type: string
|
||||
duration_secs:
|
||||
type: integer
|
||||
responses:
|
||||
'201':
|
||||
description: Added
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
API имеет rate limiting: **60 запросов в минуту** на один JWT токен.
|
||||
|
||||
```json
|
||||
// Response 429
|
||||
{
|
||||
"error": "rate_limit_exceeded",
|
||||
"retry_after_secs": 30
|
||||
}
|
||||
```
|
||||
|
||||
Headers:
|
||||
```
|
||||
X-RateLimit-Limit: 60
|
||||
X-RateLimit-Remaining: 42
|
||||
X-RateLimit-Reset: 1626688800
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Версия: 1.0 | Июль 2026*
|
||||
*Версия: 2.0 | Август 2026*
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue