Files
mtusi2026lab3/openspec/changes/rolling-update/tasks.md
T
ricoromaandClaude Opus 5.5 5403464cfb docs: add rolling-update compatibility and script failure evidence
Old image passes smoke and student tests on the new schema, rolling
update, rollback and roll forward under tests/load.py give zero failed
requests; the run_docker known issue is not reproduced and is closed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 01:01:33 +03:00

180 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
- [ ] 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 нет.
- [ ] 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, стенд, хост.
- [ ] 6.4 Хост по брифу: питание, давление на память, `docker ps`,
`docker info`, `vm_stat` (`Swapouts`) до и после. Затем `make stop`,
`nohup make bench_rollout` с журналом, после — снова рабочий стенд.
Проверка: `evidence/rollout/baseline/` со статусом `complete`, сверка
сошлась; плохой хост — Telegram и остановка (бриф).
- [ ] 6.5 `REPORT.md` по решению 10:
- строки доказательств уровня «4» вместо TODO;
- процедура замены;
- раздел профиля `rollout` в «Эксперименты и отказы»;
- ограничения;
- ответы на вопросы защиты.
Проверка: у каждой новой строки есть команда, наблюдение и файл; в
evidence и отчёте нет паролей, токенов и абсолютных путей домашнего
каталога.
- [ ] 6.6 Финал:
- `make lint`, `openspec validate rolling-update --strict`;
- отметить задачи, коммит evidence и отчёта (`docs: …`);
- `graphify update .`;
- рабочий стенд `mtusi-lab3` поднят, все реплики `UP`;
- рабочее дерево чистое.