docs: propose rolling-update change

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-11 00:26:36 +03:00
co-authored by Claude Opus 5.5
parent c50b7211b8
commit 9a00795de1
8 changed files with 1178 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-11
+472
View File
@@ -0,0 +1,472 @@
# Design
## Context
Мотивация — `proposal.md`, «Why». Требования — дельты в `specs/`.
Стенд, LB и цепочка таймаутов — `.claude/rules/balancer.md`, миграции —
`migrations.md`, стенд `bench/` — `bench.md`.
Текущее состояние (commit `c50b721`, change `graceful-failover` в
архиве):
- **Стенд.** Сервис `api` × `API_REPLICAS` без имени контейнера. HAProxy
находит реплики через DNS Docker: 8 слотов `server-template`,
`init-state down`, `rise 2`, `inter 1s`, `fastinter 500ms`, `http-reuse
never`, `timeout server 10s`. Сервис `migrate` — одноразовый контейнер
на образе API, реплики ждут его завершения.
- **Миграции.** Три ревизии, все только добавляют. Ревизия ключей
идемпотентности `7652184b7016` уже писалась как expand.
- **Остановка реплики** (`stop-one.sh`, профиль `failover`) — `docker
stop` без вывода из LB. Под нагрузкой это даёт одиночный 502 в части
фаз `stop`: гонка keep-alive при SIGTERM (`graceful-failover`,
решения 3 и 10).
- **Обновление кода.** Сейчас — только `make down` + `make run_docker`.
`KNOWN_ISSUES.md` говорит, что `make run_docker` после пересборки не
пересоздаёт работающие `api`.
- **Хранилище образов Docker Desktop 29.8 — containerd** (`docker info`:
`io.containerd.snapshotter.v1`). У тега три разных digest: индекс
(`docker image inspect`), манифест платформы (метка
`com.docker.compose.image` контейнера) и конфигурация (поле
`.Image` контейнера; его показывает `docker ps` вместо имени тега).
Разведка 2026-10-11: реплики рабочего стенда работают на текущем
теге `mtusi-messenger:lab3`. Метка контейнера совпадает с манифестом
платформы тега, хотя `docker ps` показывает `04f700d0d939`, а не
имя.
Разведка runtime API HAProxy (2026-10-11). Временный HAProxy того же
образа и с копией `haproxy.cfg` плюс `stats socket ipv4@127.0.0.1:9999
level admin` стоял перед репликами рабочего стенда, команды шли через
`bash` `/dev/tcp` изнутри контейнера:
- `show stat` по CLI отдаёт адрес слота (`172.30.0.5:8080`);
- `set server api/api-1 state drain` — слот `DRAIN`, 6 из 6 новых
запросов ушли на вторую реплику;
- `state maint` — `MAINT`, запросов на неё тоже нет;
- `state ready` при живом адресе — слот сначала `DOWN 1/2`, затем `UP`
через проверки. Возврат из ручного состояния проходит обычный `rise`,
а не мгновенный `UP`.
## Goals / Non-Goals
**Goals:**
- Замена реплик на новый образ одной командой, без ошибок клиента под
нагрузкой и без потери записей. Плановая остановка — с дренажём,
поэтому без 502 гонки keep-alive.
- Миграция при замене: одна, до новых реплик, совместима со старым
кодом. Это проверено старым образом на новой схеме.
- Предсказуемое поведение при сбое: `API_REPLICAS` готовых реплик и
чистые слоты LB в любом исходе.
- Профиль `rollout` воспроизводим одной командой и использует тот же
скрипт, что рабочий стенд.
**Non-Goals:**
- Автоматический откат при сбое. Скрипт останавливается, а смешанные
версии допустимы: миграция только расширяет схему. Откат — тот же
скрипт с образом прежнего commit (решение 6).
- Дренаж в `stop-one.sh` и в профиле `failover`. Hook имитирует отказ,
а его срок возврата (< 10 с) не вмещает дренаж и graceful.
- Contract-миграция (удаление, переименование). В этой поставке её нет,
правило и порядок описаны.
- Swarm и сторонние плагины (`docker rollout`). Выбор Compose + HAProxy
подтверждён 2026-10-07 (`PLAN.md`); незакреплённых зависимостей не
прибавляется (`balancer.md`).
- Изменение HTTP API и контракта.
## Decisions
### 1. Порядок `scripts/rolling-update.sh`
`#!/bin/sh`, `set -eu`, как `stop-one.sh`. Скрипт вызывает `docker
compose` без `-p` и `-f`. Проект, файлы и файл подстановок берутся из
окружения (`COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`)
или из каталога репозитория. Поэтому один и тот же скрипт работает с
рабочим стендом и со стендом `bench/` (решение 8). Разведка
подтвердила: Compose 5.5.1 берёт `COMPOSE_ENV_FILES`, а
`COMPOSE_PROJECT_NAME` перекрывает `name:` файла.
0. **Предусловия** (ничего не меняют):
- работает ровно `API_REPLICAS` реплик (по умолчанию 2);
- остановленных реплик сервиса нет. Иначе `up --scale` запустил бы
остановленную старую вместо новой;
- все реплики `UP` в LB;
- `API_REPLICAS` + 1 ≤ числа слотов LB.
Нарушение — код 2 и подсказка `make replicas`.
1. **Сборка.** По умолчанию `docker compose build api` из рабочего
дерева. С `ROLLOUT_COMMIT=<commit>` образ собирается из файлов
commit (решение 6) под тем же тегом сервиса (`docker compose config
--images api`).
2. **Миграции один раз:** `docker compose run --rm --no-deps migrate` на
только что собранном образе. Ошибка — код 1 до замены. Скрипт
миграций не запускает при `ROLLOUT_MIGRATE=0` (откат, решение 6).
Порядок «сборка → миграции», а не наоборот, как в `balancer.md`:
новые ревизии лежат в новом образе. Правило исправляется.
3. **Новая реплика:** `docker compose up -d --no-deps --no-recreate
--no-build --scale api=N+1 api`. Новая — та, ID которой не было до
команды.
4. **Ожидание готовности** (решение 4).
5. **Вывод и удаление старой** (решение 3).
6. Шаги 3–5 — для каждой реплики, которая работала до шага 1.
В конце — те же проверки, что в шаге 0: `N` работающих реплик, все
`UP`, ни одной из прежнего списка. Каждый шаг пишет строку `HH:MM:SS
rolling-update: …` с контейнером, слотом и адресом. Эти строки
разбирает профиль `rollout`. Вывод сборки и миграции идёт следом, в нём
нет секретов.
### 2. Дренаж — runtime API HAProxy на loopback
В `global` `haproxy.cfg`: `stats socket ipv4@127.0.0.1:9999 level
admin`. Скрипт отправляет команды так: `docker compose exec -T haproxy
bash -c 'exec 3<>/dev/tcp/127.0.0.1/9999 …'`, как `make lb_stats` читает
статистику. Слот реплики находится по её адресу в `show stat`: имя
слота с именем контейнера не связано (`balancer.md`).
Почему так:
- Снаружи контейнера LB канал не виден: loopback другого контейнера
недоступен, на хост порт не публикуется. Кто может выполнить `docker
exec`, и так управляет всем стендом.
- Приложение и цепочка таймаутов не меняются, поведение по SIGTERM
(спек `graceful-shutdown`) остаётся прежним. Решение принимает
оркестратор замены — он знает, что остановка плановая.
- Действует мгновенно, а не через 1,5 с проверок.
Альтернативы:
- **Readiness 503 по SIGTERM.** Реплика после сигнала отвечает на
`/health/ready` 503 и ещё ≥ 1,5 с принимает запросы, пока LB её не
исключит. Минусы:
- меняется спек `graceful-shutdown` («после SIGTERM новые соединения
не принимаются»);
- нужен свой обработчик сигнала поверх uvicorn;
- остановка удлиняется до 1,5 + 8 с — впритык к `stop_grace_period`
10 с;
- срок `stop-one.sh` (< 10 с) перестаёт выполняться.
Отвергнуто.
- **`stats admin` на странице `:8404`.** Порт открыт всей сети compose:
любой контейнер стенда, включая реплику, мог бы вывести реплики из
LB. Отвергнуто.
- **Unix-сокет.** Нужен `socat` или `nc -U`, а в образе HAProxy их нет;
bash с unix-сокетом не работает. Добавлять инструмент в закреплённый
образ — свой образ LB. Отвергнуто.
- **`set weight 0`** — то же, что `drain`, но состояние не видно в
статистике явно. `drain` нагляднее (`make lb_stats` показывает
`DRAIN`).
### 3. Состояния слота старой реплики
1. `set server api/<слот> state drain`. Новых запросов нет, начатые
дорабатывают (разведка).
2. Ожидание `scur` = 0 (запросов в полёте) не дольше
`ROLLOUT_DRAIN_TIMEOUT` = 12 с. Это больше `timeout server` 10 с:
дольше запрос через LB не живёт. По сроку — предупреждение и
остановка: оставшееся доработает graceful uvicorn (8 с).
3. `state maint` — проверки слота остановлены. Гибель процесса не
пишет в журнал `DOWN` с ошибкой соединения, и слот не может
вернуться в распределение по проверкам, пока процесс ещё отвечает.
4. `docker stop --timeout 10` (= `stop_grace_period`), `docker rm`.
Простаивающие соединения LB с репликой uvicorn закрывает при
SIGTERM. LB их больше не выбирает: слот выведен. Поэтому гонки
keep-alive нет.
5. Ожидание, пока адрес уйдёт из слота: DNS `hold` 1 с, не дольше
10 с. Затем `state ready`.
Почему `ready` нужен и почему после ухода адреса. Ручное состояние —
свойство слота, а не реплики. Если слот останется в `drain` или
`maint`, следующая реплика, которой DNS отдаст этот слот, не получит ни
одного запроса. А `ready` при ещё живом адресе вернул бы проверки к
мёртвому адресу: слот был бы `DOWN`, запросов бы не получил (разведка:
`ready` → `DOWN 1/2` → проверки), но журнал LB шумел бы.
Почему `drain`, а потом `maint`, а не сразу `maint`. Исход для новых
запросов одинаков. Но `drain` — штатное «не давать новых, доработать
текущие», а ожидание `scur` = 0 видно в статистике и журнале LB как
отдельный шаг. `maint` нужен только на время гибели процесса.
### 4. Новая реплика готова — `UP` в статистике LB
Ожидание, срок `ROLLOUT_READY_TIMEOUT` = 60 с:
1. Контейнер `healthy`, если у него есть healthcheck (рабочий стенд:
healthcheck образа, `start_interval` 1 с), иначе `running`. На
стенде `bench/` healthcheck выключен.
2. Слот с адресом новой реплики в состоянии `UP`.
Только `healthy` мало. Слот получает адрес из DNS и начинает в `DOWN`
(`init-state down`). В распределение он попадает после двух успешных
проверок, то есть до 1,5 с после готовности (`downinter` + `fastinter`,
`graceful-failover`). Вывести старую раньше — на время до 1,5 с
остаться с N − 1 репликами.
### 5. Сбой на середине
Автоматического отката нет (Non-Goals). Скрипт держит инвариант
«`API_REPLICAS` готовых реплик и чистые слоты». Состояние текущей
замены — в переменных, `trap` на `EXIT`, `INT`, `TERM`:
| Где оборвалось | Что делает скрипт | Итог |
|---|---|---|
| предусловия, сборка, миграция | ничего не трогал | N старых, код 2 / 1 |
| новая реплика не `UP` за срок, или прерывание до `UP` | `docker rm -f` новой; её слот уходит по DNS, ручного состояния у него не было | N реплик (k − 1 новых, остальные старые), код 1 |
| новая `UP`, старая в дренаже или останавливается | довести шаг 3 решения 3: `maint`, `stop`, `rm`, `ready`. Повторный Ctrl+C на время уборки игнорируется | N реплик, код 1 или 130 |
| уборка сама не удалась | печатает команды для ручного завершения (`docker rm …`, `set server … state ready`) | код 1 |
Почему «довести», а не «вернуть» старую. Новая реплика уже готова и
получает запросы. Вернуть старую — значит N + 1 реплик или ещё один
вывод из LB. Довести шаг — не больше ~25 с: 12 с дренажа, 10 с
остановки, 2 с DNS.
- Смешанные версии после сбоя безопасны: схема совместима с обеими
(решение 7, спек `db-migrations`).
- Повторный запуск заменяет все работающие реплики. Уже новые
заменяются на тот же образ: это лишняя, но безопасная работа. Образы
скрипт не сравнивает, решение 9.
- Слоты не переполняются: одновременно не больше N + 1 реплик, а N + 1
≤ 8 проверяется в предусловиях.
Проверка сбоя — `ROLLOUT_READY_TIMEOUT=1`: реплика стартует ~3 с и за
1 с готовой не станет. Плюс Ctrl+C во время дренажа и остановленная
реплика перед запуском (`evidence/rollout/script-failures.md`).
### 6. Образ другого commit без изменения рабочего дерева
`git archive --format=tar <commit> | docker build -t <тег> -`.
Контекст — ровно файлы commit, `.dockerignore` commit применяется к
tar-контексту. Рабочее дерево, индекс и HEAD не меняются, лишних
каталогов нет.
Где используется:
- **Профиль `rollout`.** Старт на образе `Profile.rollout_from` (решение
8).
- **Демонстрация на рабочем стенде.** Реплики на образе прежнего
commit: `git archive c50b721 | docker build -t mtusi-messenger:lab3 -`
и `docker compose up -d --no-build`.
- **Откат кода скриптом.** `make rolling_update COMMIT=<commit>
MIGRATE=0`. Миграции прежнего образа не знают новой ревизии, и
`alembic upgrade head` упал бы на «Can't locate revision». Поэтому
при откате миграции пропускаются явно. Схема остаётся новой,
прежний код на ней работает (решение 7). Автоопределения нет: явный
флаг надёжнее разбора текста ошибки alembic.
Альтернативы:
- `git worktree add` в scratchpad — тоже не трогает рабочее дерево, но
оставляет метаданные в `.git/worktrees` и требует уборки;
- `checkout` и `stash` запрещены (бриф) и сломали бы незакоммиченную
работу;
- `docker build` с git-URL контекста — нужен доступ к удалённому
репозиторию и push.
### 7. Новая версия для демонстрации — `messages.instance_id`
Колонка `instance_id text NULL` в `messages`: `X-Instance-Id` реплики,
которая записала сообщение. Новый код пишет `settings.app.instance_id`
при вставке (параметр `insert_message`, DTO не меняется). Старый код
колонку не знает:
- вставка перечисляет колонки, и в новой колонке остаётся NULL;
- чтение выбирает `MESSAGE_COLUMNS`, то есть те же колонки.
Контракт и ответы API не меняются: колонка наружу не отдаётся.
Почему так:
- Новый код **зависит** от новой схемы: без миграции его вставка упала
бы. Значит, порядок «миграция до новых реплик» проверяется по-настоящему.
Старый код **терпит** новую схему. Это и есть expand/contract в
миниатюре.
- По данным видно, какая версия записала сообщение (NULL — прежняя).
Это доказательство замены в БД, а не только по заголовкам.
- Ревизия — `op.add_column(..., nullable=True)`. В PostgreSQL ≥ 11
колонка без значения по умолчанию добавляется изменением каталога,
без перезаписи таблицы. Блокировка `ACCESS EXCLUSIVE` берётся на
миллисекунды, но в очереди за ней ждут все новые запросы к
`messages`. Поэтому первой строкой ревизии идёт `SET LOCAL
lock_timeout = '5s'`:
- чужая долгая транзакция не заставит миграцию держать очередь;
- по сроку миграция падает, схема не меняется, и замена не
начинается (спек `db-migrations`);
- повторный запуск проходит.
- `downgrade` удаляет колонку. Это шаг contract, допустимый только
после того, как не осталось нового кода.
Альтернативы:
- **Индекс `CONCURRENTLY`.** Код от схемы не зависит, демонстрация
совместимости пустая. Кроме того, `CONCURRENTLY` не выполняется
внутри транзакции alembic.
- **Переименование колонки.** Это не expand: старый код ломается.
Годится только как пример того, чего нельзя.
- **Только правка кода без схемы.** Совместимость миграций не
проверяется вовсе.
Цена: +~13 байт на строку `messages` (12 символов ID и заголовок
varlena). Трек 1 снимает базовый замер после change, поэтому меток для
сравнения «до» нет.
### 8. Профиль `rollout` стенда `bench/`
| Поле | `rollout` | `rollout_quick` |
|---|---|---|
| реплик, лимиты | 2; как рабочий стенд (как `failover`) | те же |
| интенсивность | 100 записей с ключом + 100 чтений в секунду | та же |
| `rollout_from` | `c50b721` — последний commit до change | тот же |
| окна: до замены / бюджет замены / после | 15 / 90 / 15 с | 5 / 60 / 8 с |
| порог доли успешных | 99 % | 99 % |
| читаемый чат | 1 000 сообщений | тот же |
- **Старт.** `run.py` собирает образ текущего checkout (паспорт, как
всегда) и образ `rollout_from` через `git archive` под тегом
`mtusi-messenger:bench-from`. Затем `docker tag` на
`mtusi-messenger:bench`, `Stand.start()`. Миграции прежнего образа
дают его последнюю ревизию, реплики стартуют прежнего образа.
Подготовка — как у `failover`: фикстура, читаемый чат, курсоры
(общий хелпер).
- **Нагрузка** — тот же `k6/failover.js`, `DURATION` = до + бюджет +
после, `PHASE` 1. Через «до» секунд `run.py` запускает
`scripts/rolling-update.sh`. Окружение — `Stand.env` (пароли,
`BENCH_*`), плюс `COMPOSE_PROJECT_NAME=mtusi-bench`, `COMPOSE_FILE`
(оба файла), `COMPOSE_ENV_FILES=bench/bench.env`, `API_REPLICAS`.
`docker compose build api` пересобирает текущий checkout под тег
`mtusi-messenger:bench`, слои из кэша. Правило `bench.md` «`-p`,
оба `-f`, `--env-file`» выполняется переменными окружения.
- **Время — часы ВМ.** Начало замены `t0` — событие `create` контейнера
миграции (`docker events` с меткой проекта). Шаги каждой реплики
берутся из трёх источников:
- события Docker: `create`/`start` новой, `kill` с сигналом 15,
`die`, `destroy` старой;
- журнал LB: `UP` слота новой, `drain`/`maint` слота старой;
- строки скрипта: какие слот и адрес у какой реплики.
Сборка до `t0` измеряется по строкам скрипта (секунды).
- **Окна ошибок.** «До» — запросы, завершённые до `t0`. «Замена» —
отправленные от `t0` до `destroy` последней старой. «После» — всё
остальное.
- **Шкала.** Посекундно от `t0`, по образцу `failover`. Добавлены
`old_ok` и `new_ok`: успешные ответы с `X-Instance-Id` прежних и
новых контейнеров. Новые столбцы — в конце (`bench.md`).
- **Повтор и сверка** — `k6/retry.js` и `psql` стенда, как в `failover`.
Плюс:
- ревизия `alembic_version` до и после — измерение, а не изменение
схемы;
- контейнеры и `.Image` до и после;
- тег образа после замены.
- **Результаты** — `evidence/rollout/<метка>/`:
- `meta.json` (паспорт и раздел `rollout`);
- `rollout.csv` (строка прогона);
- `replicas.csv` (строка на заменённую реплику);
- `timeline.csv`, `summary.md`;
- `raw/rollout-k6.json`, `raw/rollout-lb.log`, `raw/rollout-script.log`
(только строки `rolling-update:`).
Пробные `quick-rollout-*` — в `.gitignore`.
- **Отказ команды** — по списку спека `load-benchmark`. Ошибки клиента
— пометка (`errors`), а не отказ.
- **Код:**
- `bench/rollout.py` — чистые функции разбора и сводки на stdlib
поверх парсеров `failover.py`;
- `run.py` — профили, `--from <commit>` для отладки (в
`overrides`), оркестрация.
Тег `bench-from` снимается при уборке.
### 9. `make run_docker` и пересборка
Гипотеза: пункт `KNOWN_ISSUES.md` — ошибка диагностики. В хранилище
containerd `docker ps` показывает у реплик digest конфигурации, а не
имя тега, и это выглядит как «старый образ» (Context). Compose
сравнивает метку `com.docker.compose.image` с манифестом платформы
тега и должен пересоздавать реплики после пересборки.
Проверка в apply. Реплики работают на образе прежнего commit, затем:
1. `docker compose build api` (новый образ);
2. `docker compose --dry-run up -d`;
3. метки контейнеров против `docker image inspect --platform`.
Исход:
- **Compose пересоздаёт** (`Recreate`). Пункт закрывается в
`KNOWN_ISSUES.md` с объяснением. В комментарии `run_docker` и в
`REPORT.md`: `run_docker` пересоздаёт все реплики разом, с простоем;
без простоя — `make rolling_update`.
- **Не пересоздаёт.** `run_docker` получает явное пересоздание `api`
после сборки, пункт закрывается исправлением.
Скрипт замены от этого не зависит: он определяет новую реплику по ID,
а не по образу.
### 10. Evidence и отчёт
| Файл | Что показывает |
|---|---|
| `evidence/rollout/<метка>/` | полный профиль `rollout` с commit change: шкала, шаги по репликам, контейнеры и образы до и после, сверка; хост по брифу |
| `evidence/rollout/compatibility.md` | рабочий стенд: реплики прежнего образа → новая миграция → `make test` и `make student_test` на прежнем образе и новой схеме → `make rolling_update` под `tests/load.py` → откат `COMMIT=c50b721 MIGRATE=0` под нагрузкой → снова вперёд; `docker compose ps` и образы до и после, `instance_id` сообщений по версиям, ревизия схемы; проверка `--dry-run` из решения 9 |
| `evidence/rollout/script-failures.md` | предусловия (остановленная реплика, не то число реплик), новая реплика не готова (`ROLLOUT_READY_TIMEOUT=1`), Ctrl+C во время дренажа, миграция не получила блокировку (`lock_timeout`), канал управления LB недоступен из сети |
| `evidence/tests/rolling-update-checks.md` | регрессия на commit кода: `make lint`, `check`, `test`, `student_test`, `test_isolated`, `failure_checks`, `test-persistence`, `test-failover` (`stop` и `kill`), `bench_quick`, `bench_failover_quick`, `bench_rollout_quick` |
`REPORT.md`:
- строки таблицы доказательств уровня «4» — замена под нагрузкой,
миграции однократно и совместимы, вместо строки TODO;
- процедура замены и состояния слота;
- раздел профиля `rollout` в «Эксперименты и отказы»;
- ограничения: нет автоотката, contract отдельной поставкой, одиночный
502 остаётся только у незапланированного `docker stop`;
- ответ на вопрос защиты о `depends_on` и healthcheck дополняется
ожиданием `UP` в LB при замене;
- раздел «Обновление без простоя и миграции» в ответах на вопросы
защиты.
## Risks / Trade-offs
- **[Канал управления LB — admin-уровень]** → слушает только
`127.0.0.1` внутри контейнера LB. Проверка — попытка подключиться к
порту 9999 LB из другого контейнера сети (`script-failures.md`).
Доступ через `docker exec` равен доступу к Docker, то есть ко всему
стенду.
- **[`lock_timeout` 5 с может не хватить под тяжёлой записью]** →
миграция падает без изменений, замена не начинается, повтор проходит.
Это лучше, чем очередь всех записей за миграцией. Без нагрузки
блокировка берётся за миллисекунды.
- **[Новый код на старой схеме падает]** → только если миграцию
пропустить при движении вперёд. Скрипт пропускает её лишь по явному
`MIGRATE=0` (откат). Порядок «миграция → новые реплики» закреплён в
скрипте и спеке.
- **[`git archive` берёт только закоммиченное]** → это и нужно:
«прежняя версия» — commit, а не рабочее дерево. Commit записывается в
паспорт.
- **[Профиль `rollout` собирает образ под нагрузкой]** → сборка из кэша
слоёв — секунды CPU ВМ, видны в шкале до `t0`. Так и при реальной
замене на том же хосте; длительность — в результатах.
- **[`docker compose exec` на каждую команду LB]** → ~0,1–0,2 с на вызов,
опрос каждые 0,25–0,5 с. Замена двух реплик — десятки вызовов,
секунды.
- **[Повторный запуск после сбоя заменяет и уже новые реплики]** → это
лишняя работа, но безопасная и проще, чем сравнивать digest в
хранилище containerd (Context).
- **[DNS отдал адрес удалённой реплики новой раньше, чем слот вернулся
в `ready`]** → IPAM Docker не переиспользует адрес сразу, а `ready`
выставляется до следующего `--scale`. Слот новой реплики проверяется
в шаге ожидания по её адресу: если он застрял в ручном состоянии,
замена падает по сроку с понятной причиной, а не тихо.
- **[Один хост]** → профиль показывает поведение замены и порядок
величин, а не распределение. Генератор, LB, реплики, сборка и
PostgreSQL делят ВМ Docker.
## Migration Plan
1. Код, ревизия, скрипт и конфиг LB коммитятся. Рабочий стенд получает
их одной командой `make rolling_update`: новая ревизия применяется,
реплики заменяются. `haproxy.cfg` с runtime API подхватывается
пересозданием LB (`docker compose up -d haproxy`). Это короткий
перерыв точки входа, а не реплик. Делается один раз, до первой
замены: без канала управления скрипт останавливается в предусловиях.
2. Откат кода — `make rolling_update COMMIT=<прежний> MIGRATE=0`. Схема
остаётся новой, прежний код на ней работает. Колонку удаляет только
отдельная contract-миграция, когда прежнего кода точно нет.
+137
View File
@@ -0,0 +1,137 @@
# 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.
@@ -0,0 +1,71 @@
# Spec Delta
## ADDED Requirements
### Requirement: Совместимость миграции с работающей версией
Миграция SHALL только расширять схему:
- новая таблица;
- новая колонка, допускающая NULL или со значением по умолчанию;
- новый индекс.
Удаление и переименование таблицы, колонки или ограничения, а также
новое ограничение, которое нарушит запись прежней версии, MUST NOT
входить в ту же поставку, что и код, которому они нужны. Такое
изменение выполняется отдельной миграцией после того, как реплик
прежней версии не осталось (expand/contract). Если так сделать нельзя,
ограничение SHALL описываться в `REPORT.md`.
Реплики прежнего образа SHALL обслуживать обязательные запросы на
схеме после новой миграции. Откат кода к прежнему образу MUST NOT
требовать отката схемы.
Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком.
Долгая транзакция приложения не должна заставить миграцию держать
очередь за собой и остановить запись остальных реплик. По истечении
срока миграция 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** скрипт завершается с ненулевым кодом до запуска новых
реплик, а прежние реплики работают и обслуживают запросы
@@ -0,0 +1,31 @@
# Spec Delta
## ADDED Requirements
### 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»
@@ -0,0 +1,120 @@
# Spec Delta
## ADDED Requirements
### 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.
Если условие не выполнено, скрипт 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`, а контейнеры не меняются
### 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 удалить её и завершиться с ненулевым кодом. Старые реплики,
которые ещё не заменены, SHALL остаться в работе.
Если замена прервана (Ctrl+C, ошибка) после того, как новая реплика
стала `UP`, скрипт SHALL довести вывод текущей старой реплики до
удаления. Только после этого он завершается.
В любом исходе SHALL работать `API_REPLICAS` готовых реплик. Слоты LB
SHALL быть без состояния, выставленного вручную. Реплики разных версий
допустимы: миграция совместима с обеими. Повторный запуск SHALL
доводить замену до конца.
#### Scenario: Новая реплика не готова
- **WHEN** новая реплика не стала `UP` в LB за срок ожидания
- **THEN** она удалена, скрипт завершился с ненулевым кодом и назвал
шаг, работают `API_REPLICAS` реплик, все `UP`, и запросы через LB
обслуживаются
#### Scenario: Прерывание во время дренажа
- **WHEN** скрипт прерван Ctrl+C, пока старая реплика выводится из LB
- **THEN** старая реплика остановлена и удалена, новая работает,
реплик `API_REPLICAS`, а слот старой реплики без ручного состояния
@@ -0,0 +1,166 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Фиксированный стенд
Стенд SHALL состоять из балансировщика (LB), реплик приложения,
PostgreSQL и Valkey. Число реплик SHALL задаваться методикой, по
умолчанию одна. Приложение SHALL запускаться в контейнерах из образа,
собранного из текущего checkout тем же `Dockerfile`. Исключение —
профиль поочерёдной замены. Он стартует на образе commit, заданного
методикой: образ собирается тем же `Dockerfile` из файлов этого commit
без изменения рабочего дерева. Заканчивается профиль на образе текущего
checkout. LB SHALL
запускаться из того же образа и с той же конфигурацией, что у рабочего
стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у
рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL
получает те же настройки образа плюс модуль записи планов, выключенный
вне снятия плана. Схема БД SHALL применяться миграциями до наполнения.
Лимиты SHALL быть одинаковыми во всех прогонах профиля:
- у каждой реплики приложения — лимит CPU и памяти без swap, заданный
методикой (в профилях лабы 2 — 1 CPU и 2 ГБ);
- у LB, PostgreSQL и Valkey — свои лимиты CPU и памяти без swap,
заданные методикой.
Healthcheck образа приложения SHALL быть отключён: готовность реплик
проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки
приложения и хранилищ SHALL браться из методики стенда, а не из `.env`
и `config.toml` рабочего стенда. Пароли хранилищ SHALL генерироваться
на прогон. Генератор нагрузки SHALL работать в той же docker-сети и
обращаться к приложению через LB по имени сервиса, минуя проброс
портов хоста. Стенд SHALL считаться готовым, когда LB видит готовыми
все реплики.
#### Scenario: Лимиты в паспорте
- **WHEN** прогон завершён
- **THEN** паспорт стенда содержит число реплик и лимиты CPU и памяти
реплики приложения, LB, PostgreSQL и Valkey, прочитанные у запущенных
контейнеров, и они одинаковы для всех размеров
#### Scenario: Нехватка памяти
- **WHEN** процесс приложения превысил лимит памяти и был убит
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
обычный результат
#### Scenario: Настройки рабочего стенда не влияют
- **WHEN** `.env` и `config.toml` рабочего стенда изменены или
отсутствуют
- **THEN** стенд запускается с теми же настройками приложения и
хранилищ, а окружение приложения в паспорте то же
#### Scenario: Схема до наполнения
- **WHEN** начинается наполнение размера
- **THEN** миграции применены до последней ревизии, и приложение
отвечает готовностью
#### Scenario: Одна реплика за балансировщиком
- **WHEN** профиль лабы 2 (`full`, `quick`, `restore`,
`restore_quick`) запущен с одной репликой
- **THEN** все запросы генератора проходят через LB, прогон завершается
с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и
разделы, что раньше
#### Scenario: Образ прежнего commit
- **WHEN** запускается профиль поочерёдной замены
- **THEN** реплики стартуют на образе commit из методики, схема — на
его последней ревизии, рабочее дерево не меняется, а commit и образы
до и после записаны в паспорт
## ADDED Requirements
### 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** команда завершается с ненулевым кодом, называет шаг из
журнала скрипта, сохраняет частичные результаты и удаляет стенд
+179
View File
@@ -0,0 +1,179 @@
# 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`
- [ ] 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`
— без расхождений.
- [ ] 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. Балансировщик и скрипт замены
- [ ] 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`.
- [ ] 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/`
- [ ] 3.1 `bench/rollout.py` (решение 8): разбор строк скрипта, событий
Docker проекта и журнала LB по шагам замены; шкала с `old_ok` /
`new_ok`; окна до, во время и после; строка прогона; строки по
репликам; `summary.md`. Только stdlib, парсеры — из `failover.py`.
- [ ] 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. Документы
- [ ] 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. Общая проверка кода и коммит
- [ ] 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 кода
- [ ] 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`, если дефект
подтвердился). Проверка: в файле на каждом шаге команда, код выхода и
наблюдение.
- [ ] 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`;
- рабочее дерево чистое.