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 при этом сохраняют прежний протокол, см. порядок обновления.

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

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

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

Полная таблица и настройки: 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-парка.