EvoBGP/docs/durable-jobs.md

Общая очередь задач

В production PostgreSQL является источником состояния jobs. HTTP возвращает 202 после фиксации enqueue; повтор ключа с тем же исходным запросом возвращает сохранённую операцию, включая terminal status. Другой запрос с тем же ключом получает 409. Ключи старых записей без сохранённого request hash также дают 409: исходный запрос нельзя надёжно восстановить из изменявшихся результатов. Для нового намеренного запуска нужен новый ключ.

API/all резервируют локальную worker capacity до claim. Lease содержит owner, срок и fencing token; heartbeat продлевает lease и сохраняет текущую metadata каждые 15 секунд. List/get/cancel/report используют общее хранилище. Потеря heartbeat/terminal write оставляет lease для восстановления; максимум три попытки, затем failed. Операторский POST /v1/jobs/{job_id}/retry сохраняет ID и исходные параметры, сбрасывает бюджет и проверяет квоты. При graceful shutdown незавершённые jobs освобождаются без расхода попытки; БД закрывается после остановки claim и сохранения результатов workers.

EVOBGP_JOB_MAX_PENDING (по умолчанию 10000) и EVOBGP_JOB_MAX_TENANT_PENDING (1000) ограничивают queued+running; EVOBGP_JOB_MAX_CONCURRENT ограничивает исполнителей одного процесса. Memory — явный режим разработки, без сохранности после перезапуска. Доставка — at-least-once: обработчики и побочные эффекты должны выдерживать повтор.

CRUD и автоматический enqueue пока не составляют одну SQL-транзакцию. Если изменение сохранено, а enqueue вернул ошибку, ответ содержит X-EvoBGP-Job-Status: enqueue-failed, а аудит — bgp.job.enqueue_failed. Повторять создание объекта не нужно; следует явно запустить refresh/reconcile. Падение процесса между CRUD и enqueue требует transactional outbox для полной гарантии восстановления.

Обновление control plane

1. Остановить приём новых мутаций и дождаться завершения/отмены jobs старого control plane.
2. Остановить все старые процессы API/all и прочие CP writers. Старый best-effort протокол не поддерживает lease/fencing: смешанная работа старого и нового CP не поддерживается.
3. Выполнить migration 000034 и последующие migrations, затем запускать новый control plane. Legacy running rows получают 15 минут grace до reclaim; это средство восстановления записей, а не разрешение оставить старые writers работающими.
4. Проверить /v1/ready, общую видимость jobs, queue metrics и явный replay запроса.

Удалённые speakers с агентом 2.56.2 не являются writers очереди control plane; их останавливать или обновлять для этой миграции не требуется. Обратная migration удаляет данные протокола владения; rollback схемы требует полной остановки CP и заранее проверенного backup, а не смешанного rolling rollback.

PostgreSQL integration tests выполняются только с EVOBGP_TEST_DATABASE_URL. Пропуск этих тестов локально не подтверждает поведение SQL; CI требует их успешного выполнения без skips.