# Ключевые возможности EvoBGP

EvoBGP — это control plane для описания источников префиксов (модули), сборки согласованных снимков (ревизии), генерации конфигурации BIRD и доставки подписанных артефактов на BGP-спикеры. Ниже — продуктовый обзор; точные пути и схемы запросов — в [openapi.yaml](openapi.yaml).

## Модули префиксов

Один **модуль** — настраиваемый экземпляр с типом и параметрами расписания. Поддерживаемые типы (поле `type` при создании):

| Тип | Назначение |
|-----|------------|
| `AS_PREFIXES` | Номера AS и привязка к BGP community (без статического CIDR в записи) |
| `CDN_CIDRS` | CIDR из внешних CDN-источников (URL, виды источников) |
| `DOMAINS` | FQDN с привязкой к BGP community; опционально DoH-профили |
| `IP_RANGES` | Статические CIDR + `community_id` (данные в БД, без внешнего ingest по URL) |

Для каждого модуля доступны CRUD-операции над вложенными коллекциями: `cdn-sources`, `as-entries`, `domain-entries`, `ip-range-entries` (в зависимости от типа модуля).

Дополнительно: **принудительный refresh** (`POST .../modules/{id}/refresh`) для типов, где имеет смысл пересборка/ingest (для `IP_RANGES` поведение может быть no-op или отказ — см. реализацию и OpenAPI).

## DoH-профили и BGP community

- **DoH-профили** — настройки DNS-over-HTTPS для модулей с доменами; секреты в ответах API не раскрываются.
- **Communities** — справочник BGP community в границах tenant для классификации префиксов.

## Пиры и спикеры

- **Peers** — BGP-соседи и политики; привязка к конкретному спикеру или ко всем.
- **Speakers** — зарегистрированные экземпляры BIRD (роли вроде master/replica/canary в продуктовой модели).

## Ревизии конфигурации

- **История ревизий** — неизменяемые снимки состояния конфигурации и артефактов.
- **Превью** — просмотр фрагментов BIRD без применения на железе.
- **Снимок префиксов** — материализованный список префиксов для ревизии (с пагинацией).
- **Сравнение ревизий** — diff между двумя ревизиями.
- **Откат** — создание новой ревизии на основе выбранной прошлой (часто асинхронно, через jobs).

## Применение и задачи

- **Apply** — выкладка целевой ревизии на спикеры (глобально или на один спикер); типичный ответ для долгих операций — `202 Accepted` и ссылка на job.
- **Reload BIRD** — отдельный или связанный шаг мягкой перезагрузки политики (см. OpenAPI).
- **Jobs** — асинхронные задачи: список, статус, запрос отмены (best-effort).

## Реплики: `evobgp-node` и бандлы

Узлы с ролью **`node`** в API получают не общий CRUD, а узкие эндпоинты:

- указатель на последнюю ревизию для спикера;
- скачивание **подписанного бандла** (архив + манифест + подпись Ed25519).

CLI `evobgp-node` поддерживает `pull-bundle`, `verify-bundle`, `apply-bundle` для проверки подписи и применения к локальному BIRD.

## Веб-интерфейс

Каталог `web/` — SvelteKit-приложение для операторов (статическая сборка в Docker-образе эталонного профиля). Для разработки UI обычно используется dev-сервер на порту Vite/SvelteKit с проксированием или прямым вызовом API; на стороне API задаётся CORS (`EVOBGP_CORS_ORIGINS`).

## Наблюдаемость

- **`GET /metrics`** — Prometheus-метрики процесса API (без префикса `/v1`).
- Опционально — опрос `birdc` по сокету (`EVOBGP_BIRDC_SOCKET` и связанные переменные) для метрик протоколов BGP.

## Глобальные настройки

Эндпоинты `GET/PATCH /v1/settings` — операторские флаги и лимиты (см. OpenAPI).

## Связанные документы

- [quickstart.md](quickstart.md) — Docker Compose, **готовые образы из Container Registry** (`docker pull git.shx.one/...`) без сборки на сервере.
- [api.md](api.md) — как вызывать API на практике.
- [architecture.md](architecture.md) — из каких процессов и пакетов это собрано.
- [evobgp-api-sketches.md](evobgp-api-sketches.md) — ранние таблицы эндпоинтов (черновик).