guard/TODO.md

# Rampart — Development TODO & Roadmap

> Живой документ. Философия: **KISS → DRY → SOLID → YAGNI**.

---

## 0. Принципы разработки

### KISS
- Не добавляй абстракцию до третьего повторения.
- Функция ≤ 60 строк, модуль ≤ 500 строк.
- Не используй generics где хватит `&str` и `Vec<u8>`.

### DRY
- Повтор > 2 раз → выноси, но лучше копипаста чем неправильная абстракция.

### SOLID (Rust)
- **S**: один файл = одна ответственность
- **O**: расширяй через трейты
- **L**: `dyn Filter` — любая реализация без side effects
- **I**: маленькие трейты вместо одного `ShieldTrait`
- **D**: core зависит от `trait StateStore`, не от Redis

### YAGNI
- Не пиши io_uring до v0.4, BGP до v0.6, K8s Operator до v0.5
- Не добавляй feature flag если фича не готова

### Rust-специфичные
1. `unwrap()` — только в main() и тестах
2. `unsafe` — только в xdp/, комментарий обязателен
3. `clone()` осознанно, профилируй hot path
4. Блокирующие операции → `spawn_blocking`
5. Логи: `tracing::info!` / `debug!` / `error!`
6. Метрики: register один раз при старте, инкремент в hot path

---

## 1. Этапы разработки

### Этап 0: Bootstrap (неделя 1)
- [ ] Инициализировать Cargo workspace (`crates/*`)
- [ ] GitHub Actions: `cargo check`, `cargo test`, `cargo clippy -- -D warnings`
- [ ] `cargo-deny` (лицензии, CVE, дубликаты)
- [ ] `Makefile` с целями: `build`, `test`, `fmt`, `ebpf`, `docker`
- [ ] `docker-compose.yml` для dev (redis, clickhouse)
- [ ] `.gitignore`, `CONTRIBUTING.md`, `rustfmt.toml`, `clippy.toml`
- [ ] **DoD:** `make test` проходит, CI зелёный, `cargo build --release` собирает

---

### Этап 1: MVP — v0.1 (недели 2–4)
> Edge нода принимает MC соединения, парсит handshake, HMAC, проксирует на Velocity.

#### rampart-core
- [ ] TCP listener с SO_REUSEPORT
- [ ] VarInt парсер с bounds check
- [ ] MC Handshake парсер (packet_id=0x00)
- [ ] HMAC-SHA256 signer
- [ ] Timeout 1.5s на handshake (Slowloris защита)
- [ ] TCP proxy (tokio::io::copy_bidirectional)
- [ ] Config из `config.toml`
- [ ] Логи через `tracing`

#### rampart-cli
- [ ] `rampart pki init` — CA + сертификаты
- [ ] `rampart pki issue --name edge-1 --ip 10.0.100.1`

#### plugins/velocity
- [ ] DomainCheck: whitelist доменов, блок direct IP
- [ ] HmacCheck: verify HMAC, extract real IP
- [ ] Передача real IP в Velocity forwarding

#### plugins/paper
- [ ] ShieldAgent: авто-регистрация в YAML
- [ ] Heartbeat: online/tps в файл каждые 10 сек

#### docs
- [ ] `deployment.md`: как поднять v0.1
- [ ] `configuration.md`: примеры конфигов

#### Тестирование
- [ ] Unit: VarInt парсер (overflow, incomplete, граничные случаи)
- [ ] Unit: HMAC sign/verify (timing, wrong secret)
- [ ] Integration: tcpkali → handshake доходит до Velocity
- [ ] Ручной: реальный Minecraft клиент через edge

- [ ] **DoD v0.1:** Реальный игрок заходит через Edge → Velocity, HMAC работает, direct IP блокируется, `cargo test` проходит

---

### Этап 2: Registry + Redis — v0.2 (недели 5–7)
- [ ] `trait StateStore` + `impl StateStore for Redis`
- [ ] DashMap blacklist cache (TTL 5 мин)
- [ ] Pub/Sub `rampart:blacklist:events`
- [ ] Token bucket rate limiter per IP
- [ ] Graceful shutdown (SIGTERM)

#### rampart-manager
- [ ] Axum REST API: `GET /api/servers`, `POST /api/blacklist`
- [ ] JWT auth (Bearer token)

#### plugins/velocity
- [ ] ServerRegistry: delta-sync из Redis
- [ ] LoadBalancer: round-robin

#### plugins/paper
- [ ] ShieldAgent: писать в Redis (`rampart:servers`)
- [ ] HeartbeatTask: online/tps в Redis
- [ ] OnDisable: удалять себя из Redis

#### dashboard
- [ ] React + Vite
- [ ] Страница Servers (online, tps, статус)
- [ ] Страница Blacklist

- [ ] **DoD v0.2:** Серверы регистрируются автоматически, блэклист синхронизируется, dashboard работает

---

### Этап 3: Observability — v0.3 (недели 8–10)
#### rampart-core
- [ ] Prometheus метрики (порт 9090): connections, active, handshake duration, rate limit hits, blacklist size
- [ ] OpenTelemetry tracing (feature flag)
- [ ] Structured logs (JSON)

#### rampart-manager
- [ ] Prometheus метрики
- [ ] ClickHouse writer (batch, раз в сек, буфер 1000)
- [ ] ClickHouse schema: `rampart.blocked`

#### plugins/velocity
- [ ] Prometheus метрики: online, domain failures, registry size

#### plugins/paper
- [ ] Prometheus метрики: tps, mspt, online

#### dashboard / docs
- [ ] Grafana dashboard JSON
- [ ] Страница Attack Log
- [ ] `observability.md`

- [ ] **DoD v0.3:** Grafana показывает онлайн/TPS/блокировки, ClickHouse хранит логи, алерт на DDoS

---

### Этап 4: XDP + eBPF — v0.4 (недели 11–14)
#### xdp/
- [ ] `xdp_filter.c`: UDP drop, SYN rate limit, blacklist (LPM_TRIE)
- [ ] Ringbuf для событий (баны, rate limit hits)
- [ ] Rust loader (libbpf-rs, attach/detach)
- [ ] Feature flag: `xdp`

#### rampart-core
- [ ] Интеграция XDP loader в startup
- [ ] Чтение ringbuf → DashMap blacklist
- [ ] BPF stats → Prometheus

#### Тестирование
- [ ] `hping3 -S --flood` → XDP дропает, CPU < 30%
- [ ] `iperf3` UDP flood → XDP дропает

- [ ] **DoD v0.4:** SYN flood 1M pps дропается в XDP, CPU < 30%, XDP отключается feature flag

---

### Этап 5: Anti-Bot — v0.5 (недели 15–18)
- [ ] GeoIP lookup (maxminddb)
- [ ] ASN reputation (datacenter строже, mobile мягче)
- [ ] Adaptive rate limiting (EWMA)
- [ ] Bloom filter для whitelist

#### plugins/velocity
- [ ] Интеграция Sonar 3.0
- [ ] Custom challenge API (timing, map CAPTCHA)
- [ ] IP reputation score → Redis

- [ ] **DoD v0.5:** Боты блокируются, GeoIP работает, Sonar интегрирован

---

### Этап 6: Scale + HA — v0.6 (недели 19–24)
- [ ] WireGuard hub-and-spoke (CLI автоконфиг)
- [ ] Rust Load Balancer (SO_REUSEPORT, несколько инстансов)
- [ ] mTLS между всеми компонентами (rustls)
- [ ] QUIC канал Edge ↔ Manager

#### rampart-manager
- [ ] NATS JetStream (blacklist, drain)
- [ ] xDS-like API для динамической конфигурации
- [ ] Auto-discovery edge нод

#### rampart-cli
- [ ] `add-node`, `wg sync`, `drain`

- [ ] **DoD v0.6:** 5+ edge нод, drain без потери соединений, mTLS везде

---

### Этап 7: Polish — v0.7 (недели 25–28)
- [ ] io_uring runtime (feature flag, 5.10+)
- [ ] NUMA-aware allocation (bare metal)
- [ ] Zero-copy splice после handshake
- [ ] SLSA Level 3: signed releases, reproducible builds
- [ ] `cargo-vet`, secret rotation (dual-key HMAC)
- [ ] Docker images, GitHub Releases

- [ ] **DoD v0.7:** io_uring +30% throughput, релизы подписаны, доки позволяют поднять систему за час

---

## 2. Технический долг (Backlog)

- [ ] **Refactor:** Вынести `rampart-store` в отдельный crate
- [ ] **Refactor:** BufferPool на `crossbeam::queue::ArrayQueue`
- [ ] **Perf:** Registered buffers для io_uring
- [ ] **Feat:** Bedrock / RakNet (UDP модуль)
- [ ] **Feat:** Plugin API через WASM
- [ ] **Feat:** BGP Anycast (требует AS + /24)
- [ ] **Feat:** ML anomaly detection (IsolationForest)
- [ ] **Test:** Chaos engineering (random node kills)
- [ ] **Test:** Fuzzing для handshake parser (`cargo-fuzz`)

---

## 3. Definition of Done

```
☐ cargo check / cargo test проходят
☐ cargo clippy -- -D warnings — 0 warnings
☐ cargo fmt --check проходит
☐ Unit тесты покрывают happy path + 2+ error cases
☐ Интеграционный тест проходит
☐ Документация обновлена
☐ CI зелёный
```

---

## 4. Anti-Patterns

```
❌ Тесты после кода. Пиши до (TDD) или вместе.
❌ Коммиты в main напрямую. Только PR.
❌ TODO в коде без issue. TODO = баг.
❌ Оптимизация без профиля.
❌ Зависимость ради 1 функции.
❌ async где хватит sync.
❌ Секреты в репозитории. Используй .env + SOPS.
❌ Игнор compiler warnings.
```

---

*Версия: 1.0 | Обновляется каждый понедельник*