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

2.6 KiB
Raw Permalink Blame History

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 и тест.