# Proposal ## Why Последний пункт рубрики «4» лабы 3 (`README.md`) ещё не закрыт: - rolling update или эквивалентная поочерёдная замена, проверенная под нагрузкой; - миграции запускаются однократно и совместимы с работающей версией, либо ограничение честно описано. Сейчас новый код доходит до реплик только через `make down` и `make run_docker`. Это простой всего API (`KNOWN_ISSUES.md`, `PLAN.md`, раздел change `rolling-update`). Миграции действительно выполняются один раз: сервис `migrate` стартует до реплик. Но совместимость новой схемы с работающей версией нигде не проверялась. Change `graceful-failover` передал сюда ещё три пункта: - **дренаж до SIGTERM.** При `docker stop` под нагрузкой остаётся одиночный 502. Это гонка keep-alive: uvicorn закрывает простаивающие соединения, а LB в тот же миг шлёт в одно из них запрос. Так было в 1 из 4 фаз `stop`. При плановой замене реплику нужно сначала вывести из LB; - **ожидание `UP` в LB**, а не только `healthy` контейнера: новая реплика попадает в распределение через ≤ 1,5 с после готовности; - **`make run_docker` не пересоздаёт работающие `api`** после пересборки образа. Пункт записан в `KNOWN_ISSUES.md`, но отдельно не воспроизводился. ## What Changes - **`scripts/rolling-update.sh` и `make rolling_update`.** Скрипт по одной заменяет реплики на новый образ без простоя: 1. сборка образа; 2. миграции, один раз; 3. рядом со старыми поднимается одна новая реплика; 4. скрипт ждёт её готовности и `UP` в LB; 5. старая реплика выводится из LB и дорабатывает запросы, затем останавливается и удаляется; 6. шаги 3–5 повторяются для каждой старой реплики. Перед запуском скрипт проверяет состояние стенда. При сбое на середине останавливается и оставляет `API_REPLICAS` готовых реплик. - **Дренаж через runtime API HAProxy.** Канал управления LB слушает только loopback внутри контейнера LB, наружу и в сеть compose не открыт. Через него скрипт переводит слот старой реплики в `drain` и `maint` и потом возвращает его в `ready`. Поведение остановки по SIGTERM и hook `stop-one.sh` не меняются: hook имитирует отказ, а не плановую остановку. - **Новая версия для демонстрации — expand-миграция.** В таблицу `messages` добавляется колонка `instance_id`, допускающая NULL: реплика, которая записала сообщение. Новый код её заполняет, старый не знает о ней и пишет NULL. Контракт и поведение API не меняются. Миграция ограничивает ожидание блокировки (`lock_timeout`): долгая чужая транзакция не остановит все записи за ней. - **Совместимость доказывается на рабочем стенде** по шагам: 1. реплики на образе прежнего commit; 2. новая миграция, а реплики остаются прежними; 3. `make test` и `make student_test` на старом образе и новой схеме; 4. `make rolling_update` под нагрузкой `tests/load.py`; 5. проверки на новом образе. - **Профиль `rollout` стенда `bench/`** (`make bench_rollout`, `make bench_rollout_quick`) построен по образцу `failover`: - стенд стартует на образе заданного commit; - k6 даёт постоянную интенсивность записи с ключом и чтения; - посреди нагрузки работает тот же `scripts/rolling-update.sh`; - сохраняются посекундная шкала, доли ответов старой и новой версии и время каждого шага замены; - фиксируются контейнеры, образы и ревизия схемы до и после; - неуспешные записи повторяются с тем же ключом, затем идёт сверка. Результаты — в `evidence/rollout/<метка>/`. - **`make run_docker`.** Пункт `KNOWN_ISSUES.md` проверяется воспроизведением: собранный новый образ, `docker compose --dry-run up -d`. Если дефект подтвердится, он исправляется. Если нет, пункт закрывается с объяснением. В обоих случаях в документации: `run_docker` пересоздаёт все реплики разом, обновление без простоя делает `rolling_update`. - **Документы:** - правила `balancer.md`, `migrations.md`, `bench.md`, `run-modes.md`, `docker.md`; - `AGENTS.md`: команды, карта кода, «Переходное состояние»; - `REPORT.md`: строки доказательств уровня «4», процедура замены, ограничения, вопросы защиты. ## Capabilities ### New Capabilities Нет. ### Modified Capabilities - `load-balancing`: - поочерёдная замена реплик на новый образ под нагрузкой без ошибок и без потери записей; - вывод реплики из LB перед плановой остановкой; - поведение замены при сбое на середине. - `db-migrations`: - миграция совместима с работающей версией (только расширение); - при замене миграции запускаются один раз и до новых реплик; - ожидание блокировки ограничено. - `graceful-shutdown`: плановая остановка реплики после дренажа не даёт клиенту ни одной ошибки, в том числе 502 гонки keep-alive. - `load-benchmark`: - профиль `rollout` стартует на образе заданного commit, а не текущего checkout; - новый профиль поочерёдной замены под нагрузкой. ## Impact - **Новое:** - `scripts/rolling-update.sh`; - ревизия alembic `added message instance id`; - `bench/rollout.py` — разбор и сводка профиля; - `evidence/rollout/`. - **Код приложения:** - модель `Message`; - `src/core/repos/message.py` — `instance_id` при вставке; - `MessageService.send_message` передаёт `settings.app.instance_id`. HTTP API и контракт не меняются. - **Стенд:** - `infra/haproxy/haproxy.cfg` — runtime API на loopback; - `Makefile` — цели `rolling_update`, `bench_rollout`, `bench_rollout_quick`, при необходимости `run_docker`; - `.gitignore` — `evidence/rollout/quick-*/`. - **Стенд `bench/`:** - `run.py` — профили `rollout` и `rollout_quick`, сборка образа прежнего commit через `git archive`; - `k6/failover.js` и `k6/retry.js` — без изменений, повторно используются. - **Документы:** `.claude/rules/`, `AGENTS.md`, `REPORT.md`, `KNOWN_ISSUES.md`, скилл `run-mtusi-messenger` (новая цель). - **Зависимости** не прибавляются: те же образы HAProxy и k6, shell и stdlib Python.