EvoBGP/docs/backend-compatibility.md

# Совместимость control plane и спикеров: проверяемая основа

Обязательная legacy-версия по указанию пользователя — **2.56.2**. Новый control plane должен обслуживать эти спикеры без синхронного обновления агентов. Digest развёрнутых образов и версия BIRD внутри них ещё не подтверждены. Дополнительная проверка исходников `v1.0.0` ниже не является обещанием поддержки всех промежуточных релизов.

## Проверка исполняемого CLI 2.56.2

26.10.2026 `git ls-remote` подтвердил `refs/tags/v2.56.2` → `924f111e4871e1d6d47c9916d7da1b9051718f1c`. Из этого неизменённого commit локально собран `evobgp-node` (Go 1.26.1, Windows/amd64, зависимости из локального кэша). Тест `TestLegacyNodeBinaryCurrentControlPlane` запускает именно исторический executable против настоящего HTTP-handler нового CP: latest/pull, проверка текущего подписанного бандла, отказ неверному/чужому токену и повреждённому архиву. Локально тест прошёл для **2.56.2** и отдельно для **1.0.0**.

Отдельно собран и запущен `evobgp-agent` **2.56.2** в режиме `serve`. `TestLegacyAgentBinaryCurrentDispatch` проверил текущий dispatch, авторизацию, получение подписанного текущим builder бандла, явный ACK, health и BGP protocols. BIRD/birdc заменены изолированными helper-процессами; CP для этого теста выдаёт заранее подписанный бандл через тестовый HTTP-handler. Проверка прошла локально на Windows, без изменения BIRD хоста. В CLI-тесте дополнительно проверен отказ для корректного архива с чужим публичным ключом.

В CI добавлена матрица двух pinned commits (`scripts/ci/legacy-node-compatibility.sh`), включая agent для 2.56.2; обязательные тесты не могут быть пропущены незаметно. CI job ещё не запускался. Это source-built binaries, не опубликованные Docker images: реальные image digests, TLS, настоящий BIRD parse/apply/rollback и mixed-fleet стенд остаются отдельными gates.

Для повторного локального запуска задайте `EVOBGP_TEST_LEGACY_NODE_BIN` абсолютным путём к собранному historical CLI и выполните `go test ./internal/httpapi -run '^TestLegacyNodeBinaryCurrentControlPlane$' -count=1 -v`. Без переменной тест явно пропускается. Проверка не вызывает apply и не меняет конфигурацию BIRD хоста.

Агент проверяется аналогично: `EVOBGP_TEST_LEGACY_AGENT_BIN` и `go test ./internal/nodedispatch -run '^TestLegacyAgentBinaryCurrentDispatch$' -count=1 -v`. Вызов sync проходит через старый агент, но команды BIRD выполняет только тестовая подмена. В Linux CI включён race detector; таймаут учитывает задержку завершения race-instrumented helper-процессов.

## Доступные свидетельства

- В локальном Git имеются теги `v1.0.0`–`v2.54.0` и исходники `cmd/evobgp-node`, `internal/nodecli`, `internal/bundle` для `v1.0.0` (`6ca34b900859665eede22044d734b698059bdf84`). Это исторические исходники, а не сохранённые исполняемые файлы или подтверждение установленной версии.
- CLI в `v1.0.0` запрашивает `GET /v1/speakers/{speaker_id}/revisions/latest`, затем `GET /v1/speakers/{speaker_id}/bundle/{revision_id}` с `Authorization: Bearer`. Ответ latest читается по `revision_id`. Публичный ключ передаётся CLI отдельно в base64/hex; текущий CP предоставляет `GET /v1/bundle/signing-public-key` для роли с `bgp:network:read`.
- Формат `v1.0.0` — gzip/tar с `manifest.json`, `bundle.sig` и файлами конфигурации. В манифесте: `revision_id`, необязательный `speaker_id`, `created_at`, `files` (`path`, `sha256`), `signature_algorithm=ed25519`, `public_key_base64`. Подпись Ed25519 считается по точным байтам `manifest.json`; содержимое файлов сверяется по SHA-256. Сопоставление исходников `v1.0.0` и текущего `internal/bundle` показывает ту же структуру, но само по себе не доказывает совместимость реального бинарника или синтаксиса BIRD.
- `internal/agentserver` и `internal/nodedispatch` в дереве `v1.0.0` отсутствуют. Проверки их минимальных ответов ниже — характеристика текущего протокола и имитация legacy-формы, а не тест агента релиза `v1.0.0`.

## Автоматические проверки этой основы

| Тест | Что проверяет | Предел вывода |
|---|---|
| `internal/bundle/legacy_compatibility_test.go` | Текущий builder создаёт прежний набор полей и порядок tar entries; независимая проверка Ed25519/SHA-256 по полям старого манифеста принимает результат. Замороженный подписанный архив `internal/bundle/testdata/current_baseline_signed_bundle.tar.gz` проверяется отдельно | Фикстура создана текущим builder с тестовым ключом, не извлечена из старого релиза; исторический бинарник не запускается |
| `internal/httpapi/node_legacy_compatibility_test.go` | Node bearer auth и tenant scope для latest revision и bundle; получение ключа с операторским токеном; проверяемый подписанный bundle без новых обязательных полей | In-memory HTTP; не проверяет TLS, внешнюю БД и CLI-процесс |
| `internal/nodedispatch/legacy_compatibility_test.go` | Sync отправляет только старое поле `revision_id` и Bearer secret; health с отсутствующими дополнительными полями остаётся читаемым | Ответы агента моделируются, реальный старый агент не запущен |

В первой реализации B01 подстановка запрошенного ID удалена: `2xx` без `applied_revision_id` остаётся совместимой успешной доставкой с `confirmation=unconfirmed`. Явный совпадающий ID даёт `agent_reported`; он не означает независимую проверку фактического BIRD-конфига. Несовпадающий или устаревший ACK не меняет applied. Запрос sync по-прежнему содержит только `revision_id`, новые поля от старого агента не требуются. Старый health без времени наблюдения принимается; время опроса фиксирует CP, а его источник указан явно.

Публикация и обработка ACK теперь дополнены persistent deployment progress и атомарными проверками lease/generation в PostgreSQL. Реальная проверка нескольких CP writers и restart остаётся открытым integration gate. Смешанные старый и новый CP не поддерживаются при миграции очереди; удалённые агенты 2.56.2 при этом сохраняют прежний протокол, см. [порядок обновления](durable-jobs.md).

Агент 2.56.2 не сериализует параллельные sync. Сохранённая reservation на две минуты после неоднозначного ответа уменьшает риск перекрывающейся доставки, но timeout не доказывает завершение старой операции. Поэтому CP сохраняет unknown/unconfirmed и сверяет последующий health; exactly-once, отсутствие любых перекрытий и подтверждённый BIRD config hash для старого агента не обещаются.

## Что ещё нужно до release gate B08

### Ограничения новых сборок bundle/node

Полная таблица и настройки: [bundle-limits.md](bundle-limits.md).

Формат manifest, Ed25519-подписи и HTTP endpoints сохраняются. Новые сборки ограничивают сжатый архив 128 MiB, распакованный tar и суммарное содержимое 512 MiB, отдельный payload 256 MiB, manifest 2 MiB, число записей 4096 и длину пути 1024 байт. Лимиты проверяются также при создании bundle; downloader ограничивает metadata latest до 64 KiB и текст ошибки до 4 KiB. Для встраиваемого вызова доступны `bundle.Limits` и `SyncConfig.BundleLimits`; отдельные operator CLI flags пока не добавлены.

Это верхние защитные пределы, а не обещание низкого RSS на малом VPS: архив и проверенные файлы ещё хранятся в памяти. Тест с миллионом повторяющихся строк IPv6 проверяет вместимость типичного размера текста, не валидность миллиона уникальных маршрутов или нагрузку BIRD. Повторные проверки source-built node/agent 2.56.2 с текущим builder прошли.

Новые verifier/extractor отклоняют дубликаты, неописанные manifest файлы, небезопасные пути и ссылки, проверяют gzip trailer. Эти защиты действуют в новых бинарниках; уже установленный 2.56.2 не получает их без обновления. Поддержка его прежнего протокола сохраняется.

### Оставшиеся проверки

1. Для обязательной версии **2.56.2** подтвердить установленные image digests `evobgp-agent`/`evobgp-node`, BIRD, режим `serve` или pull-only и источник ключа подписи. Сохранить инвентарь смешанного парка; source commit сам по себе не определяет digest опубликованного образа.
2. Сохранить реальные старые binaries/images и подписанные bundle-артефакты с подтверждённым происхождением. На стенде запустить matrix: новый CP + старый и текущий agent/CLI, предыдущий CP + новый agent, смешанный парк. Проверить pull/sync, auth/TLS, подпись, BIRD parse/apply/rollback и offline/reconnect.
3. Ввести согласованные capabilities в OpenAPI и совместимый fallback. Новые ACK, config hash, telemetry и формат бандла отправлять по объявленным возможностям. `404/405` документированного endpoint может обозначать legacy; timeout, auth/TLS error и повреждённый ответ — ошибка, без ослабления защиты.
4. Завершить проверку deploy: разделение `unconfirmed`/`agent_reported`, persistent progress и fencing реализованы; `verified` требует нового подтверждения и проверки хеша. Выполнить PostgreSQL concurrent/restart tests и стендовую проверку поздних ACK, неоднозначных timeout, восстановления и ограниченного повторения доставки.
5. Проверить BIRD-синтаксис на реально установленной версии и canary без BGP flap; сохранить путь отката CP и предыдущее поколение схемы БД на окно rollback.

Пока эти шаги не выполнены, тесты подтверждают только локальный baseline совместимости формата и HTTP-форм, а не готовность смешанного production-парка.