guard/docs/roadmap/v0.5-pinned-maps-openapi.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

53 lines
2.6 KiB
Markdown
Raw Permalink 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.

# v0.5 — Pinned maps и OpenAPI
| | |
|---|---|
| Milestone | v0.5 |
| Status | idea |
| Priority | P1 |
| Depends on | — |
## Цель
Динамические списки и состояние XDP доступны снаружи без перекомпиляции и без
прямого доступа к памяти: pinned maps через bpffs + описанный OpenAPI контракт
manager API.
## Зачем
Самый частый запрос у XDP-фаерволов — управлять списками на лету; у gamemann это
issues #79/#77/#78, web-панель так и не сделана. Наш manager API уже умеет
blacklist, но контракт не описан машинно, а XDP-карты не pin-ятся.
## Scope
- `bpftool`-совместимые pinned maps (blacklist, whitelist, stats) с фиксированными
именами и документированной раскладкой ключей.
- OpenAPI 3.1 spec для существующих маршрутов (`/health`, `/auth/login`,
`/servers`, `/blacklist`, `/nodes`), генерация из одного источника или
ручной файл + тест соответствия роутеру.
- Swagger UI — опционально, отдельным бинарём/фичей, не в основном edge.
## Non-goals
- Web-панель (UI) — отдельный продукт.
- Изменение ABI существующих карт без теста совместимости.
## Approach
1. Выбрать: pin-ить карты в загрузчике (`libbpf-rs` pin path) или отдельной
утилитой. Проверить, что pin не мешает перезапуску/cleanup.
2. OpenAPI: начать с ручного `docs/openapi.yaml`, добавить тест, что каждый
маршрут из `router.rs` присутствует в спецификации.
3. Документация: как читать/писать карты, какие значения, какие ограничения.
## Критерии приёмки
- [ ] `bpftool map show pin` видит карты после старта edge.
- [ ] OpenAPI валидируется в CI и покрывает 100% маршрутов.
- [ ] README/api.md ссылаются на спецификацию, а не дублируют её.
## Риски
Pinned maps усложняют graceful detach и могут оставить «висящие» карты после
краша — нужен reaper и тест.