- 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.
53 lines
2.6 KiB
Markdown
53 lines
2.6 KiB
Markdown
# 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 и тест.
|