# Tasks Как строить — `design.md` (дальше «решение N»). Что должно получиться — дельты в `specs/`. Перед первым файлом слоя прочитать его правило: `balancer.md`, `docker.md`, `migrations.md`, `bench.md`, `run-modes.md`, `repo-layer.md`, `service-layer.md`. Рабочий стенд `mtusi-lab3` до задачи 6.1 не трогать миграциями и пересборкой. Его база должна остаться на ревизии `7652184b7016`, а реплики — на прежнем образе: это исходное состояние демонстрации совместимости. Не запускать `make run_docker`, `make upgrade`, `make revision`. Сборка `make test_isolated` двигает тег `mtusi-messenger:lab3`, но не реплики и не базу стенда; задача 6.1 всё равно собирает прежний образ заново. Evidence снимается с закоммиченного кода: коммит кода → evidence → коммит evidence. Замер для отчёта (`make bench_rollout`) — только после проверки хоста по брифу, рабочий стенд на время замера остановлен. ## 1. Приложение: колонка `messages.instance_id` - [x] 1.1 Модель `Message` и ревизия alembic по решению 7: - `instance_id: Mapped[str | None]` (Text, NULL) с комментарием; - ревизия `added message instance id` через `uv run alembic revision --autogenerate` против базы на прежней ревизии, только чтение схемы. Затем вручную: `SET LOCAL lock_timeout = '5s'` первой строкой `upgrade` и комментарий про expand и contract. Проверка: `uv run alembic upgrade head` и `downgrade -1` / `upgrade head` на временной базе (не рабочей); `alembic check` после `upgrade` — без расхождений. - [x] 1.2 `insert_message(..., instance_id)` в repo и передача `settings.app.instance_id` из `MessageService.send_message`; DTO и ответ API не меняются. Проверка: `make lint`; после задачи 5.2 строка сообщения, записанного через API, содержит `instance_id` = `X-Instance-Id` ответа. ## 2. Балансировщик и скрипт замены - [x] 2.1 `infra/haproxy/haproxy.cfg`: `stats socket ipv4@127.0.0.1:9999 level admin` в `global` с комментарием (решение 2). Проверка: `haproxy -c` в закреплённом образе с `API_PORT=8080` — `Configuration file is valid`. - [x] 2.2 `scripts/rolling-update.sh` по решениям 1–6 (исполняемый бит в git). Внутри: - предусловия; - сборка из рабочего дерева или `ROLLOUT_COMMIT`; - миграция один раз, `ROLLOUT_MIGRATE=0` — пропуск; - цикл замены: ожидание `healthy` и `UP` по адресу, `drain` → `scur` = 0 → `maint` → `stop` → `rm` → адрес ушёл → `ready`; - итоговая проверка; - `trap` с состояниями решения 5; - строки `HH:MM:SS rolling-update: …` с контейнером, слотом и адресом; - секретов не печатает. Цель `make rolling_update` (`API_REPLICAS`, `COMMIT`, `MIGRATE`). Проверка: задачи 5.2 и 6.1–6.2. ## 3. Профиль `rollout` стенда `bench/` - [x] 3.1 `bench/rollout.py` (решение 8): разбор строк скрипта, событий Docker проекта и журнала LB по шагам замены; шкала с `old_ok` / `new_ok`; окна до, во время и после; строка прогона; строки по репликам; `summary.md`. Только stdlib, парсеры — из `failover.py`. - [x] 3.2 `bench/run.py`: - профили `rollout` и `rollout_quick`, поля `Profile`; - `--from` для отладки; - образ прежнего commit через `git archive`, тег `bench-from` и `docker tag`; - общая подготовка с `failover`; - запуск `scripts/rolling-update.sh` с окружением compose стенда; - сбор событий, журнала LB и строк скрипта; - повтор, сверка, итоговые проверки; - каталог `evidence/rollout/<метка>/`, снятие тега при уборке. Цели `bench_rollout` (`ROLLOUT_LABEL ?= baseline`) и `bench_rollout_quick` в `Makefile`, `evidence/rollout/quick-*/` в `.gitignore`. Проверка: `make lint`; `make bench_rollout_quick` — код 0, замена двух реплик, сверка сошлась, `summary.md` и `replicas.csv` с шагами; занятая метка — отказ до стенда. ## 4. Документы - [x] 4.1 Правила под решения: - `balancer.md` — порядок «сборка → миграции», дренаж, состояния слота, сбой, runtime API; - `migrations.md` — новая ревизия, `lock_timeout`, откат кода без отката схемы; - `bench.md` — профиль `rollout`; - `run-modes.md` — 502 гонки keep-alive остаётся только у остановки без дренажа; - `docker.md` — `run_docker` и обновление по решению 9. `AGENTS.md`: - команды — `rolling_update`, `bench_rollout`, `bench_rollout_quick`; - карта кода — `rolling-update.sh` без «(лаба 3)», `bench/rollout.py`, `evidence/rollout/`; - «Переходное состояние» — закрытый пункт убрать. Скилл `run-mtusi-messenger` — новая цель. Проверка: `grep -n "rolling-update" AGENTS.md .claude/rules/*.md` — нет обещаний «будет». ## 5. Общая проверка кода и коммит - [x] 5.1 `make lint`, `make check`, `openspec validate rolling-update --strict`, `haproxy -c`. Проверка: все с кодом 0. - [x] 5.2 Самопроверки на своих стендах, рабочий не трогается: - `make test_isolated` — новая ревизия на временной базе, smoke и набор; - `make failure_checks`; - `make bench_rollout_quick`; - `make bench_failover_quick`; - `make bench_quick`. Затем коммит кода (`feat: …`). Проверка: все с кодом 0, рабочее дерево чистое. ## 6. Evidence с commit кода - [x] 6.1 Совместимость и `make run_docker` на рабочем стенде (решения 6, 7, 9; `evidence/rollout/compatibility.md`): - реплики на образе `c50b721` (`git archive`), LB пересоздан с новым `haproxy.cfg`, ревизия `7652184b7016`, `make test`; - `docker compose build api` и `docker compose --dry-run up -d` — исход решения 9; - `docker compose run --rm migrate` — новая ревизия при прежних репликах, затем `make test` и `make student_test` на них; - `make rolling_update` под `tests/load.py`; - откат `make rolling_update COMMIT=c50b721 MIGRATE=0` под нагрузкой; - снова `make rolling_update`; - `make test` и `make student_test`; - `docker compose ps` и образы на каждом шаге; - `instance_id` сообщений по версиям. Исход решения 9 — в `KNOWN_ISSUES.md` (и `Makefile`, если дефект подтвердился). Проверка: в файле на каждом шаге команда, код выхода и наблюдение. - [x] 6.2 Отказы скрипта (`evidence/rollout/script-failures.md`): - остановленная реплика (`stop-one.sh`) и `API_REPLICAS=3` — отказ до сборки; - `ROLLOUT_READY_TIMEOUT=1` — новая удалена, N реплик `UP`; - Ctrl+C во время дренажа — старая доведена до удаления, слоты чистые; - миграция не получила блокировку (открытая транзакция на `messages` в `psql`) — замена не начиналась, повтор после конца транзакции прошёл (на временной базе или до 6.1); - порт 9999 LB из другого контейнера сети — отказ соединения. Проверка: после каждого случая `make lb_stats` — N реплик `UP`, слотов `DRAIN` / `MAINT` вне DNS нет. - [x] 6.3 Регрессия на commit кода (`evidence/tests/rolling-update-checks.md`): - `make test`, `make student_test` через LB; - `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; - `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` в режимах `stop` и `kill`, `make replicas` между ними; - выводы 5.1–5.2. Проверка: в шапке — спеки, change, дата, commit, стенд, хост. - [x] 6.4 Хост по брифу: питание, давление на память, `docker ps`, `docker info`, `vm_stat` (`Swapouts`) до и после. Затем `make stop`, `nohup make bench_rollout` с журналом, после — снова рабочий стенд. Проверка: `evidence/rollout/baseline/` со статусом `complete`, сверка сошлась; плохой хост — Telegram и остановка (бриф). - [x] 6.5 `REPORT.md` по решению 10: - строки доказательств уровня «4» вместо TODO; - процедура замены; - раздел профиля `rollout` в «Эксперименты и отказы»; - ограничения; - ответы на вопросы защиты. Проверка: у каждой новой строки есть команда, наблюдение и файл; в evidence и отчёте нет паролей, токенов и абсолютных путей домашнего каталога. - [x] 6.6 Финал: - `make lint`, `openspec validate rolling-update --strict`; - отметить задачи, коммит evidence и отчёта (`docs: …`); - `graphify update .`; - рабочий стенд `mtusi-lab3` поднят, все реплики `UP`; - рабочее дерево чистое. ## 7. Правки по verify (2026-10-11, решение 12) - [x] 7.1 `scripts/rolling-update.sh`: `new_id` сбрасывается до `state=starting`, уборка сама находит новую реплику (`find_new`), предусловие о слотах с ручным `drain` / `maint`, код выхода старой реплики в строке скрипта, полные команды LB в подсказках ручной уборки. Документы: `balancer.md` (предусловие, сбой, ограничение отката), `migrations.md` (шаг миграций при замене — контейнер сервиса, а не `run --rm`), `bench.md` (отказ профиля без `UP`), дельта `load-balancing`, `REPORT.md`, скилл. Проверка: `make lint`, `dash -n`, `openspec validate rolling-update --strict`, коммит кода. - [x] 7.1a `lock_timeout` ревизии `e656d6bbe1a4` — 2 с вместо 5 с (меньше `statement_timeout` приложения): при 5 с запросы в очереди за миграцией получали 503 вместе с её отказом. Дельта `db-migrations`, `migrations.md`, design (решения 7 и 12), `REPORT.md`. Проверка: случай «миграция не получила блокировку» под нагрузкой — 0 ошибок, коммит кода. - [x] 7.2 Evidence на итоговом commit кода (`84161c0`): - `compatibility.md` — шаги A–G заново, с журналом остановки старых реплик, `--dry-run` после отката и жизненным циклом стенда после замены (`make instances`, `lb_stats`, `test-failover` `stop` и `kill`, `replicas`, `test-persistence`, `run_docker` поверх заменённых, `down` + `run_docker`, повторная замена); - `script-failures.md` — случаи заново, Ctrl+C — настоящим ^C через псевдотерминал, в том числе внутри `up --scale` (до исправления и после), слот в ручном состоянии; - самопроверки `bench_failover_quick` и `bench_rollout_quick` на чистом дереве (`evidence/tests/rolling-update-checks.md`); - строки `REPORT.md`; коммит evidence.