chore: archive rolling-update change

Sync the rolling-update delta specs into db-migrations,
graceful-shutdown, load-balancing and load-benchmark, move the change to
the archive, mark it in PLAN.md and update the transitional state and
code map in AGENTS.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-11 01:59:19 +03:00
co-authored by Claude Opus 5.5
parent 6f85d21f3b
commit 84ee13ca5a
14 changed files with 352 additions and 11 deletions
@@ -103,8 +103,9 @@ SHALL оставаться доступной.
### Requirement: Сбой поочерёдной замены
Если новая реплика не стала готовой в LB за срок ожидания, скрипт
SHALL удалить её и завершиться с ненулевым кодом. Старые реплики,
Если новая реплика не стала готовой в LB за срок ожидания или замена
прервана раньше, скрипт SHALL удалить её и завершиться с ненулевым
кодом, в том числе когда её ID скрипту ещё не известен. Старые реплики,
которые ещё не заменены, SHALL остаться в работе.
Если замена прервана (Ctrl+C, ошибка) после того, как новая реплика
+71
View File
@@ -87,3 +87,74 @@
- **WHEN** та же миграция применяется к пустой базе или повторно
- **THEN** ничего не удаляется, и команда завершается с кодом 0
### Requirement: Совместимость миграции с работающей версией
Миграция SHALL только расширять схему:
- новая таблица;
- новая колонка, допускающая NULL или со значением по умолчанию;
- новый индекс.
Удаление и переименование таблицы, колонки или ограничения, а также
новое ограничение, которое нарушит запись прежней версии, MUST NOT
входить в ту же поставку, что и код, которому они нужны. Такое
изменение выполняется отдельной миграцией после того, как реплик
прежней версии не осталось (expand/contract). Если так сделать нельзя,
ограничение SHALL описываться в `REPORT.md`.
Реплики прежнего образа SHALL обслуживать обязательные запросы на
схеме после новой миграции. Откат кода к прежнему образу MUST NOT
требовать отката схемы.
Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком.
Долгая транзакция приложения не должна заставить миграцию держать
очередь за собой и остановить запись остальных реплик. Срок SHALL быть
меньше срока запроса приложения к БД (`statement_timeout`): запросы,
вставшие в очередь за миграцией, дожидаются её отказа и выполняются, а
не завершаются ошибкой вместе с ним. По истечении срока миграция SHALL
завершаться ошибкой без изменения схемы, а её повторный запуск SHALL
проходить.
#### Scenario: Старый образ на новой схеме
- **WHEN** стенд работает на образе прежнего commit, и миграции нового
образа применены, а реплики не заменены
- **THEN** `make test` и `make student_test` через LB проходят на
прежних репликах
#### Scenario: Запись прежней версии
- **WHEN** после новой миграции сообщение отправлено через реплику
прежнего образа
- **THEN** ответ 201, а сообщение видно в истории через реплику любого
образа
#### Scenario: Блокировка не получена
- **WHEN** таблицу, которую меняет миграция, держит открытая
транзакция дольше срока ожидания блокировки
- **THEN** миграция завершается ошибкой, схема не меняется, запросы
других клиентов, ждавшие за миграцией, получают успешный ответ, а
после окончания транзакции повторный запуск применяет миграцию
### Requirement: Однократные миграции при замене реплик
Поочерёдная замена реплик (`load-balancing`) SHALL применять миграции
один раз за запуск: отдельным одноразовым контейнером на новом образе,
после сборки образа и до запуска первой новой реплики. Реплики MUST
NOT запускать миграции сами. Если миграция завершилась ошибкой, замена
MUST NOT начинаться: работающие реплики не трогаются, скрипт
завершается с ненулевым кодом.
#### Scenario: Одна миграция на замену
- **WHEN** выполнен `make rolling_update` для двух реплик
- **THEN** в журнале замены одна миграция до первой новой реплики, в
журналах реплик записей alembic нет, а ревизия схемы после замены —
последняя
#### Scenario: Миграция упала
- **WHEN** миграция при замене завершается ошибкой
- **THEN** скрипт завершается с ненулевым кодом до запуска новых
реплик, а прежние реплики работают и обслуживают запросы
+28
View File
@@ -107,3 +107,31 @@ keep_alive_seconds`. LB MUST NOT держать простаивающие со
- **THEN** соединения на порт API внутри каждой реплики закрываются
раньше `keep_alive_seconds` с момента последнего запроса, по сроку
простоя LB
### Requirement: Плановая остановка реплики без ошибок
При плановой остановке реплики за балансировщиком (поочерёдная замена,
`load-balancing`) реплика SHALL сначала выводиться из LB. Только когда
у неё не осталось запросов в полёте, она получает SIGTERM. Поэтому
плановая остановка под постоянной нагрузкой MUST NOT давать клиенту ни
одной ошибки, включая 502 гонки keep-alive из требования «Остановка
реплики за балансировщиком».
Поведение процесса по SIGTERM не меняется: требования выше действуют. Не
меняется и остановка без дренажа (`scripts/stop-one.sh`, `docker
stop`): она имитирует отказ, и исключение для 502 гонки keep-alive к
ней по-прежнему применяется.
#### Scenario: Остановка после дренажа под нагрузкой
- **WHEN** через LB с постоянной интенсивностью идут запись с ключом и
чтение истории, и реплика остановлена после вывода из LB
- **THEN** ни одного неуспешного ответа, в том числе 502, а журнал LB
не показывает ошибок соединения с этой репликой
#### Scenario: Остановка за заявленный срок после дренажа
- **WHEN** реплика выведена из LB и получила SIGTERM
- **THEN** процесс завершается быстрее 10 с с кодом выхода не 137, а в
её журнале есть «Shutting down», «Stopped API» и «Finished server
process»
+135
View File
@@ -321,3 +321,138 @@ idle_in_transaction_timeout_ms`. Блокировки этой транзакц
- **THEN** после прерывания транзакции повтор получает 201, в чате
ровно одно сообщение с этим текстом, а после разморозки реплика
снова обслуживает запросы
### Requirement: Поочерёдная замена реплик
Команда `make rolling_update` (`scripts/rolling-update.sh`) SHALL
заменять работающие реплики API на образ из текущего checkout по одной,
без остановки обслуживания. Порядок:
1. сборка образа;
2. миграции, один раз (`db-migrations`);
3. для каждой старой реплики:
- рядом запускается одна новая;
- скрипт ждёт её готовности и состояния `UP` в статистике LB;
- старая выводится из LB, дорабатывает запросы, останавливается и
удаляется.
Реплик одновременно SHALL быть не больше `API_REPLICAS` + 1. Число
должно помещаться в слоты LB. Правка конфигурации LB и его перезапуск
MUST NOT требоваться.
После успешной замены SHALL работать ровно `API_REPLICAS` реплик. Все
они SHALL быть на новом образе и в состоянии `UP` в LB. Контейнеров
прежнего образа SHALL не остаться ни работающих, ни остановленных.
Под постоянной нагрузкой через LB (запись с ключом и чтение истории)
замена MUST NOT давать клиенту ошибок. Каждая подтверждённая запись
SHALL оставаться доступной.
Перед заменой скрипт SHALL проверять стенд:
- работает ровно `API_REPLICAS` реплик;
- остановленных реплик нет;
- все реплики `UP` в LB;
- для ещё одной реплики есть свободный слот LB;
- нет слотов LB в ручном дренаже или обслуживании, которое оставила
прерванная замена.
Если условие не выполнено, скрипт SHALL завершаться с ненулевым кодом
до сборки и ничего не менять.
#### Scenario: Замена двух реплик
- **WHEN** работают две реплики прежнего образа, и выполнен `make
rolling_update`
- **THEN** команда завершается с кодом 0, работают две реплики с новыми
`X-Instance-Id` на новом образе, обе `UP` в LB, а контейнеров прежних
реплик нет
#### Scenario: Замена под нагрузкой
- **WHEN** во время `make rolling_update` через LB с постоянной
интенсивностью идут запись с ключом и чтение истории
- **THEN** ни один ответ клиенту не ошибочен, в ответах сначала есть
только старые `X-Instance-Id`, затем старые и новые, затем только
новые, а число сообщений в чате равно числу отправленных ключей
#### Scenario: Стенд не готов к замене
- **WHEN** одна реплика остановлена `scripts/stop-one.sh`, или работает
не `API_REPLICAS` реплик
- **THEN** скрипт завершается с ненулевым кодом до сборки, называет
причину и предлагает `make replicas`, а контейнеры не меняются
#### Scenario: Слот остался в ручном состоянии
- **WHEN** слот LB без адреса оставлен в ручном обслуживании или
дренаже, и выполнен `make rolling_update`
- **THEN** скрипт завершается с ненулевым кодом до сборки, называет слот
и печатает команду, которая возвращает его в `ready`, а контейнеры не
меняются
### Requirement: Вывод реплики из балансировщика перед остановкой
Перед плановой остановкой реплики LB SHALL перестать направлять ей
новые запросы. Запросы, которые она уже обрабатывает, SHALL
дорабатываться. Остановка SHALL начинаться после того, как запросов в
полёте у неё не осталось, или по истечении срока ожидания, большего
`timeout server` LB. Управление LB SHALL быть доступно только изнутри
контейнера LB. Из сети compose и с хоста оно MUST NOT быть доступно.
Состояние слота, выставленное при замене, SHALL сниматься, когда адрес
удалённой реплики ушёл из слота. Слот, который потом получит новая
реплика, SHALL включаться по обычным проверкам готовности.
#### Scenario: Выведенная реплика не получает запросов
- **WHEN** слот реплики переведён в дренаж, и через LB идут запросы
- **THEN** все новые ответы приходят от других реплик, а запросы,
начатые до дренажа, получают ответ
#### Scenario: Управление LB недоступно из сети
- **WHEN** контейнер в сети стенда или процесс на хосте обращается к
портам LB
- **THEN** изменить состояние реплики он не может: канал управления LB
слушает только loopback внутри контейнера LB
#### Scenario: Слот после замены
- **WHEN** замена завершена
- **THEN** в статистике LB нет слотов в дренаже или в обслуживании,
выставленном вручную; свободные слоты — только в обслуживании по DNS
### Requirement: Сбой поочерёдной замены
Если новая реплика не стала готовой в LB за срок ожидания или замена
прервана раньше, скрипт SHALL удалить её и завершиться с ненулевым
кодом, в том числе когда её ID скрипту ещё не известен. Старые реплики,
которые ещё не заменены, SHALL остаться в работе.
Если замена прервана (Ctrl+C, ошибка) после того, как новая реплика
стала `UP`, скрипт SHALL довести вывод текущей старой реплики до
удаления. Только после этого он завершается.
В любом исходе SHALL работать `API_REPLICAS` готовых реплик. Слоты LB
SHALL быть без состояния, выставленного вручную. Реплики разных версий
допустимы: миграция совместима с обеими. Повторный запуск SHALL
доводить замену до конца.
#### Scenario: Новая реплика не готова
- **WHEN** новая реплика не стала `UP` в LB за срок ожидания
- **THEN** она удалена, скрипт завершился с ненулевым кодом и назвал
шаг, работают `API_REPLICAS` реплик, все `UP`, и запросы через LB
обслуживаются
#### Scenario: Прерывание при запуске новой реплики
- **WHEN** скрипт прерван Ctrl+C, пока compose создаёт новую реплику, и
её ID скрипту ещё не известен
- **THEN** новая реплика удалена, работают `API_REPLICAS` прежних
реплик, все `UP`, а слоты без ручного состояния
#### Scenario: Прерывание во время дренажа
- **WHEN** скрипт прерван Ctrl+C, пока старая реплика выводится из LB
- **THEN** старая реплика остановлена и удалена, новая работает,
реплик `API_REPLICAS`, а слот старой реплики без ручного состояния
+101 -1
View File
@@ -56,7 +56,11 @@ Ctrl+C, контейнеры, сеть и volume стенда SHALL удалят
Стенд SHALL состоять из балансировщика (LB), реплик приложения,
PostgreSQL и Valkey. Число реплик SHALL задаваться методикой, по
умолчанию одна. Приложение SHALL запускаться в контейнерах из образа,
собранного из текущего checkout тем же `Dockerfile`. LB SHALL
собранного из текущего checkout тем же `Dockerfile`. Исключение —
профиль поочерёдной замены. Он стартует на образе commit, заданного
методикой: образ собирается тем же `Dockerfile` из файлов этого commit
без изменения рабочего дерева. Заканчивается профиль на образе текущего
checkout. LB SHALL
запускаться из того же образа и с той же конфигурацией, что у рабочего
стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у
рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL
@@ -112,6 +116,13 @@ Healthcheck образа приложения SHALL быть отключён:
с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и
разделы, что раньше
#### Scenario: Образ прежнего commit
- **WHEN** запускается профиль поочерёдной замены
- **THEN** реплики стартуют на образе commit из методики, схема — на
его последней ревизии, рабочее дерево не меняется, а commit и образы
до и после записаны в паспорт
### Requirement: Сценарии нагрузки
Стенд SHALL поддерживать два сценария с синтетическими данными
@@ -962,3 +973,92 @@ SHALL совпадать с числом разных ключей, отправ
время фазы
- **THEN** команда завершается с ненулевым кодом, называет контейнер, а
стенд удаляется
### Requirement: Профиль поочерёдной замены
Команда `make bench_rollout` (метка `ROLLOUT_LABEL`) SHALL на свежем
стенде с лимитами рабочего стенда и `API_REPLICAS` по методике
выполнять поочерёдную замену реплик (`scripts/rolling-update.sh`,
`load-balancing`) под нагрузкой. Реплики стартуют на образе прежнего
commit и заменяются на образ текущего checkout. Команда `make
bench_rollout_quick` делает то же с короткими окнами, метка
`quick-rollout-…`, в git она не идёт. Результаты SHALL сохраняться в
`evidence/rollout/<метка>/`. Занятая метка SHALL давать отказ до
запуска стенда.
Нагрузка — постоянная интенсивность, заданная методикой: запись
сообщения с `Idempotency-Key` и чтение страницы истории. Скрипт
замены SHALL запускаться через заданное методикой время после начала
нагрузки. Нагрузка SHALL продолжаться после его завершения. Скрипт
SHALL быть тем же, что у рабочего стенда, и выполняться против проекта
compose стенда.
SHALL сохраняться посекундная шкала от начала замены (создание
контейнера миграции):
- успешные записи и чтения;
- ошибки по кодам;
- доля успешных;
- p50 и p95 задержки успешных;
- число успешных ответов старых и новых реплик;
- распределение ответов по `X-Instance-Id`.
По каждой заменённой реплике SHALL сохраняться:
- время от запуска новой реплики до её `UP` в LB;
- время дренажа старой реплики;
- время её остановки;
- время замены целиком.
Для прогона целиком SHALL сохраняться:
- длительность замены;
- ошибки по кодам до, во время и после замены;
- минимальная доля успешных в секунде;
- контейнеры, их образы и ревизия схемы до и после.
После прогона каждая неподтверждённая запись SHALL повторяться с тем
же ключом и телом до 201. Число сообщений чата записи SHALL совпадать
с числом отправленных ключей, одинаковых текстов MUST NOT быть.
Команда SHALL завершаться с ненулевым кодом в случаях:
- скрипт замены вернул ненулевой код;
- генератор упал;
- PostgreSQL или Valkey падал;
- сверка не сошлась;
- в конце работает не `API_REPLICAS` реплик;
- среди работающих реплик есть реплика прежнего образа;
- не все реплики `UP` в LB.
Ошибки клиента при замене — результат, а не отказ команды: они
считаются и показываются.
#### Scenario: Полный профиль
- **WHEN** выполнен `make bench_rollout`
- **THEN** в `evidence/rollout/<метка>/` есть посекундная шкала, таблица
шагов по каждой заменённой реплике, сводка, контейнеры и образы до и
после, код выхода 0
#### Scenario: Быстрый профиль
- **WHEN** выполнен `make bench_rollout_quick`
- **THEN** за несколько минут проходит замена всех реплик, код выхода 0,
каталог метки в git не попадает
#### Scenario: Версии в ответах
- **WHEN** замена завершена
- **THEN** шкала показывает, как доля ответов старых реплик падает до
нуля, а новых растёт до всех, а ответов прежних `X-Instance-Id` после
удаления их контейнеров нет
#### Scenario: Без потерь и дублей при замене
- **WHEN** нагрузка с записью шла всё время замены
- **THEN** после повтора неподтверждённых записей с тем же ключом в чате
записи столько сообщений, сколько отправлено ключей, без одинаковых
текстов
#### Scenario: Замена не удалась
- **WHEN** скрипт замены завершился с ненулевым кодом
- **THEN** команда завершается с ненулевым кодом, называет шаг из
журнала скрипта, сохраняет частичные результаты и удаляет стенд