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