Files
mtusi2026lab3/REPORT.md
T
ricoromaandClaude Opus 5.5 6f85d21f3b docs: retake rolling-update evidence on the final verify commit
Re-run the compatibility walk-through, the script failure cases with a
real Ctrl+C through a pseudo-terminal, the stand lifecycle after
replacement and the quick rollout and failover self-checks on 84161c0
with a clean tree; update the report rows and limitations.

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

847 lines
98 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.
# Отчёт — лабораторная 3
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
- Целевая оценка 5; выбранный трек 5: TODO (предложен трек 1 «Цена масштабирования», `PLAN.md`)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
## Запуск из чистого clone
TODO (этап 7, `PLAN.md`): версии runtime/образов и prerequisites одним
списком, повторная проверка из настоящего `git clone` на стенде с LB.
Стенд с балансировщиком (change `replicas-lb`):
```sh
make env_setup # .env (случайные POSTGRES_PASSWORD и VALKEY_PASSWORD) и config.toml из шаблонов; существующие не трогает
make run_docker # docker compose build + up -d: postgres, valkey → migrate → api × API_REPLICAS (2) → haproxy
docker compose ps # готовность — haproxy (healthy): через LB можно обслужить запрос
make test # публичный smoke через LB на http://localhost:8080
make student_test # свой набор через LB, тесты реплик выполняются (EXPECT_REPLICAS = API_REPLICAS)
make instances # ≥2 X-Instance-Id одной сессии через LB (шаг 1 сценария защиты)
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make replicas # вернуть остановленную реплику (те же ID) перед следующим прогоном failover
make bench_failover_quick # отказ каждой реплики под нагрузкой на своём стенде mtusi-bench, ~2 мин; полный — make bench_failover
make rolling_update # новый код на реплики без простоя: сборка, миграции один раз, по одной реплике с выводом из LB
make bench_rollout_quick # то же под нагрузкой на своём стенде с образа прежнего commit, ~2 мин; полный — make bench_rollout
make stop # остановить; make down — удалить контейнеры, volume с данными остаётся
make wipe_data # намеренно удалить учебные данные: только после ввода yes, только проект mtusi-lab3
```
Порт API на хосте один — у HAProxy (`127.0.0.1:${APP_OUT_PORT}`, 8080).
Число реплик — `API_REPLICAS` в `.env` (по умолчанию 2), разово —
`make replicas API_REPLICAS=N`. В консоли (`make run_dev`) — один
процесс без LB; свой набор против него — `make student_test
EXPECT_REPLICAS=1`.
Проверено на одном API без балансировщика (change
`instance-id-idempotency`): в настоящем `git clone` `docker build -t
mtusi-messenger:lab3 .` проходит без `.env` и `config.toml`; после
`make env_setup` на этом образе проходит smoke
(`evidence/tests/clean-clone.md`). Стенд с LB из настоящего `git clone`
(change `replicas-lb`): `make run_docker` сам создаёт `.env` и
`config.toml` и поднимает две реплики за HAProxy; на нестандартных
`APP_OUT_PORT`, `APP__PORT` и портах Postgres и Valkey проходят `make
test` и `make student_test` (`evidence/replicas/clean-clone-ports.md`). Удаление учебных данных — `make
wipe_data` с вводом `yes`, трогает только проект `mtusi-lab3`
(`evidence/tests/stand-lab3.md`).
## Архитектура и решения
TODO (этап 7): что перенесено из lab2 одним списком, транзакционные
границы сводно.
```
клиент → 127.0.0.1:APP_OUT_PORT → haproxy ──→ api (реплика 1) ──→ postgres (данные, сессии, ключи идемпотентности; volume)
└─→ api (реплика 2) ──→ valkey (кэш неизменяемых карточек чатов)
migrate (один раз на каждый up, до реплик) ──→ postgres
```
Источник истины — PostgreSQL: пользователи, чаты, сообщения, сессии и
ключи идемпотентности. Valkey — общий кэш, его отказ — обход в
Postgres. Реплики `api` одинаковы и взаимозаменяемы, порта на хосте у
них нет; единственная точка входа — HAProxy.
### Балансировщик и реплики (change `replicas-lb`)
**Почему Compose + HAProxy** (выбор подтверждён 2026-10-07, `PLAN.md`):
| Критерий | HAProxy | Nginx (бесплатный) | Traefik | Swarm |
|---|---|---|---|---|
| Активная проверка `/health/ready` с периодом | есть (`inter`/`fall`/`rise`) | нет: пассивная по живым запросам, активная — только в NGINX Plus | есть (healthcheck в labels) | healthcheck контейнера, грубее (`interval × retries`) |
| Новые реплики после `--scale` без правки конфига | DNS Docker (`server-template` + `resolvers`) | `server ... resolve` с 1.27.3 | через docker socket | встроено |
| Повтор только недошедшего запроса | `retry-on conn-failure` | по умолчанию POST не повторяется, если уже отправлен | retry middleware, семантику для POST надо проверять | повторов нет |
| Статистика по репликам (трек 1) | встроена (`/stats;csv`) | только общие счётчики | метрики Prometheus | нет |
| Лишние привилегии | нет | нет | docker socket — почти root на хосте | — |
| Переделка стенда лабы 2 | добавить сервис | добавить сервис | сервис и labels | `build` и `depends_on` не работают в `stack deploy`, migrate как job, образ доступен узлам |
Swarm на одном хосте ничего не даёт, а сборку образа и его доступность
узлам пришлось бы описывать отдельно. Цена HAProxy — свой язык
конфигурации и фиксированное число слотов `server-template` (8).
**Как устроено** (`infra/haproxy/haproxy.cfg`, HAProxy 3.4 LTS):
- реплики находятся через DNS Docker: имя сервиса `api` отвечает
адресами всех работающих реплик, HAProxy раскладывает их по 8 слотам.
Новая и пропавшая реплика видны за 1–2 с без перезагрузки LB;
- активная проверка `GET /health/ready` (200 — Postgres отвечает) раз в
секунду, `fall 2`, `rise 2`. Слот, получивший адрес из DNS, начинает
в `DOWN` (`init-state down`) и получает запросы только после
проверок: Docker регистрирует адрес при старте контейнера, раньше,
чем uvicorn слушает порт;
- `balance roundrobin`, без cookie и stick-table: запросы одной сессии
чередуются между репликами (`evidence/replicas/distribution.md`);
- повтор в LB — только `retry-on conn-failure`, `retries 2`,
`option redispatch 1` (каждый повтор — на другую реплику): запрос до
реплики не дошёл, повтор безопасен для любого метода. Оборванный или
долгий ответ не повторяется;
- ответы самого LB (502/503/504) — в формате ошибки контракта с `code`
`unavailable`, `request_id` = `X-Request-Id`, без `X-Instance-Id`
(`evidence/replicas/lb-errors.md`);
- статистика и `/lb/ready` — `frontend monitor` на `:8404`, только
внутри сети compose; оператору — `make lb_stats`. Healthcheck
контейнера LB — `/lb/ready`: 200, пока есть готовая реплика.
**Цепочка таймаутов** (change `graceful-failover`, design, решение 1;
числа — в `infra/haproxy/haproxy.cfg`, `config_example.toml`,
`docker-compose.yml`, `src/utils/constants.py`). От клиента к
PostgreSQL; «было» — до change:
| Звено | Значение | Было | Соотношение и почему |
|---|---|---|---|
| Клиент `tests/resilience.py` | 2 с | — | задан skeleton; всё, что LB делает при отказе соединения, укладывается раньше |
| Клиент k6 профиля `failover` | 15 с | — | > `timeout server`: клиент видит 504 от LB, а не свой таймаут |
| HAProxy `timeout client` / `http-request` | 30 / 10 с | — | соединения клиентов; на отказ реплики не влияют |
| HAProxy `timeout http-keep-alive` | 10 с | — | простаивающий сеанс клиента, а с `http-reuse never` — и его соединения с репликами; < keep-alive реплики (60 с) |
| HAProxy `http-reuse` | `never` | `safe` | соединение с репликой живёт не дольше сеанса клиента и не уходит в общий пул: простаивающее соединение закрывает LB, а не реплика (`evidence/failover/keep-alive.md`) |
| HAProxy `timeout connect`, `retries`, `redispatch` | 500 мс, 2, каждый повтор | — | 0,5 × 3 = 1,5 с < 2 с клиента. Живая реплика в сети Docker принимает соединение за доли миллисекунды; 500 мс ограничивают ожидание пропавшего адреса |
| HAProxy `timeout server` | 10 с | — | > `[database] request_timeout_seconds` (6 с) + KDF входа под лимитом 1 CPU (до 1,6 с) |
| HAProxy `inter` / `downinter` | 1 с / = `inter` | — | период проверок `/health/ready`, в том числе исключённой реплики |
| HAProxy `fastinter` | 500 мс | = `inter` | повторная проверка после первой неудачи и до возврата |
| HAProxy `fall` / `rise` | 2 / 2 | — | одна неудача — ещё не отказ; возврат — после двух успехов подряд |
| HAProxy `timeout check` | 2,5 с | 3 с | > таймаута `SELECT 1` внутри `/health/ready` (2 с) на 0,5 с: медленный PostgreSQL даёт 503 от реплики, а не таймаут проверки |
| Таймаут соединения проверки | 0,5 с | — | min(`timeout connect`, `inter`), правило HAProxy |
| `resolvers docker` `hold` | 1 с | — | пропавший адрес уходит из слота за 1–2 с |
| uvicorn `timeout_keep_alive` (`[app] keep_alive_seconds`) | 60 с | 5 с | > `timeout http-keep-alive` LB (10 с) |
| `/health/ready`: `SELECT 1` | 2 с | — | < `timeout check`; не меньше: проверка берёт соединение из общего пула, и заминка PostgreSQL вывела бы из LB все реплики разом |
| Пул: `pool_timeout` / `connect_timeout` | 5 / 3 с | — | < `request_timeout_seconds` |
| PostgreSQL `statement_timeout` | 5 с | — | < `request_timeout_seconds`: сервер прерывает долгую команду раньше, чем приложение рвёт соединение |
| Работа запроса с БД (`request_timeout_seconds`) | 6 с | — | < `timeout server` 10 с |
| PostgreSQL `idle_in_transaction_session_timeout` (`[database] idle_in_transaction_timeout_ms`) | 10 с | нет | > `request_timeout_seconds`: транзакция живого запроса дольше не живёт. Прерывает транзакцию замороженной реплики и снимает блокировку её ключа идемпотентности (`evidence/failover/hung-key.md`) |
| uvicorn `[app] graceful_shutdown_seconds` | 8 с | — | < `stop_grace_period` 10 с; запросы в полёте дорабатывают |
| `scripts/stop-one.sh` | `docker stop --timeout 9` | — | возврат hook < 10 с |
| compose `stop_grace_period` | 10 с | — | SIGKILL после graceful |
**Период проверок и время обнаружения.** Проверка `/health/ready`
раз в секунду. Следующая начинается через интервал после конца
предыдущей, а после первой неудачи — через `fastinter`. Худшее время
по проверкам:
| Режим | Как выглядит для проверки | Формула | Было | Стало |
|---|---|---|---|---|
| зависшая реплика (`docker pause`) | соединение принято, ответа нет | `inter` + `timeout check` + (`fall` − 1) × (`fastinter` + `timeout check`) | 8 с | **6,5 с** |
| адрес пропал (`docker stop` после выхода, `docker kill`) | таймаут соединения 0,5 с | `inter` + 0,5 + (`fall` − 1) × (`fastinter` + 0,5) | 3 с | **2,5 с** |
| сокет закрыт, адрес жив (окно graceful) | отказ соединения | `inter` + (`fall` − 1) × `fastinter` | 2 с | 1,5 с |
Остановленный контейнер ещё и пропадает из DNS Docker: слот уходит в
обслуживание за `hold` 1–2 с, действует то, что раньше. Возврат —
≤ `downinter` + `fastinter` = 1,5 с после готовности реплики. Замер
под нагрузкой по режимам — раздел «Эксперименты и отказы».
Остановленная реплика (`docker stop`) сразу закрывает приёмный сокет:
LB получает отказ соединения и перенаправляет запрос, клиент ошибок от
недоступности не видит. Убитая (`docker kill`) рвёт запросы в полёте:
LB отвечает 502, клиент повторяет с тем же ключом. Зависшая
(соединение есть, ответа нет) исключается проверками за ≤ 6,5 с, а
запрос, уже ушедший на неё, получает 504 через `timeout server` 10 с.
**Роли и сервисы** (`infra/README.md`):
| Роль | Сервис | Версия / digest | Health / readiness | Volume | Порт на хосте | Credentials |
|---|---|---|---|---|---|---|
| load_balancer | `haproxy` | `haproxy:3.4.6-trixie@sha256:e2739156…` | `/lb/ready` (есть готовая реплика) | — | `127.0.0.1:${APP_OUT_PORT}` (8080) | нет |
| api × `API_REPLICAS` | `api` | образ из `Dockerfile` (`mtusi-messenger:lab3`) | `/health/ready` (healthcheck образа и проверки LB) | — | нет | `environment`: пароли Postgres и Valkey мостами из `.env` |
| миграции | `migrate` | тот же образ, `alembic upgrade head` | код выхода 0 | — | нет | пароль Postgres |
| postgres | `postgres` | `postgres:18.6-trixie@sha256:5a5a84b1…` | `pg_isready` по TCP | `postgres_data` | `127.0.0.1:${POSTGRES_OUT_PORT}` (консоль) | `POSTGRES_*` из `.env` |
| кэш | `valkey` | `valkey/valkey:9.1.2-trixie@sha256:418652cf…` | `valkey-cli ping` с паролем | нет (persistence выключен) | `127.0.0.1:${VALKEY_OUT_PORT}` (консоль) | `VALKEY_PASSWORD` из `.env` |
**Лимиты и соединения** (`deploy.resources.limits`, `evidence/replicas/stand.md`):
| Сервис | CPU | Память |
|---|---|---|
| `api` (на реплику) | 1.0 | 512M |
| `postgres` | 2.0 | 1G |
| `valkey` | 0.5 | 128M |
| `haproxy` (`nbthread 1`) | 1.0 | 256M |
| `migrate` | 0.5 | 256M |
При двух репликах — 6 CPU и 2,6 GiB из 12 CPU и 7,7 GiB ВМ Docker.
Соединения Postgres: `API_REPLICAS × (pool_size + max_overflow)` +
`migrate` = 2 × (10 + 5) + 1 = 31 ≤ `max_connections` 100; при 6
репликах — 91, при 7 — 106 > 100. Граница пула — гипотеза 3 трека 1.
На время поочерёдной замены реплик на одну больше (`API_REPLICAS` + 1):
3 × 15 + 1 = 46 соединений, 7 CPU и 3,1 GiB лимитов.
**Секреты по сервисам.** Пароль Postgres — `postgres`, `api`,
`migrate`; пароль Valkey — `valkey` и `api`; у `haproxy` секретов нет
(окружение — только `API_PORT`). Окружение собрано из якорей
`x-db-env` / `x-cache-env` в `docker-compose.yml`.
**Состояние процесса.** Просмотр `src/` (уровень модулей): в памяти
процесса только пул соединений Postgres, клиент Valkey с отметкой
«пропускать кэш после отказа» (`retry_after_seconds`), лимитер и
фиктивный хэш KDF, `instance_id` и логгер. От них не зависит
корректность ответа: сессии, данные и ключи идемпотентности — в
Postgres, карточки чатов неизменны, поэтому общий кэш не требует
инвалидации между репликами.
**Восстановление реплики** после `scripts/stop-one.sh`: `make replicas`
(`docker compose up -d --no-deps --no-recreate --wait --scale
api=$(API_REPLICAS) api`) — тот же контейнер запускается снова, LB
включает его после проверок.
### Обновление без простоя и миграции (change `rolling-update`)
Compose сам rolling update не делает (это `update_config` Swarm),
поэтому замена — свой скрипт `scripts/rolling-update.sh`, цель `make
rolling_update`. Сторонний плагин не используется: это была бы ещё одна
незакреплённая зависимость. Порядок (design `rolling-update`, решения
1–5):
0. **Предусловия** — ничего не меняют, иначе код 2 и подсказка `make
replicas`:
- работает ровно `API_REPLICAS` реплик, остановленных нет;
- все `UP` в LB;
- для ещё одной реплики есть слот (≤ 8);
- канал управления LB отвечает;
- нет слотов в ручном `drain` / `maint`, оставленных прерванной
заменой (их не видно в `make lb_stats`, скрипт читает `show servers
state`); иначе он печатает команду, которая вернёт слот в `ready`.
1. **Сборка образа** из рабочего дерева. `COMMIT=<commit>` — из файлов
commit через `git archive <commit> | docker build`, рабочее дерево не
трогается.
2. **Миграции — один раз**, в контейнере сервиса `migrate`, на новом
образе, до первой новой реплики. Ошибка (в том числе `lock_timeout`)
— код 1, реплики не тронуты.
3. **Одна новая реплика** рядом со старыми: `up -d --no-deps
--no-recreate --scale api=N+1 api`.
4. **Ожидание готовности новой:** `healthy` **и** `UP` в статистике LB
по её адресу. Слот получает адрес из DNS и начинает в `DOWN`, в
распределение попадает через ≤ 1,5 с проверок. Вывести старую по
одному `healthy` — значит на эти 1,5 с остаться с N − 1 репликами.
5. **Вывод старой из LB и удаление:**
- runtime API HAProxy: `drain` — новых запросов нет, начатые
дорабатывают;
- ожидание, пока запросов в полёте не станет 0 (≤ 12 с, больше
`timeout server`);
- `maint`, `docker stop` (graceful, ≤ 10 с; код выхода — в строке
скрипта), `docker rm`;
- когда адрес ушёл из слота — `ready`.
6. Шаги 3–5 для каждой старой реплики. В конце `API_REPLICAS` реплик
нового образа, все `UP`.
**Канал управления LB** — `stats socket ipv4@127.0.0.1:9999 level admin`
в `haproxy.cfg`. Он слушает только loopback контейнера LB. Из сети
compose и с хоста его не достать (`evidence/rollout/script-failures.md`,
случай 6), команды идут через `docker compose exec haproxy`. Страница
статистики `:8404` с `stats admin` не годится: она открыта всей сети
compose. Альтернатива — readiness 503 по SIGTERM — отвергнута:
- она меняет поведение остановки, после SIGTERM реплика ещё ≥ 1,5 с
принимала бы запросы;
- остановка удлиняется до 1,5 + 8 с — впритык к `stop_grace_period`;
- ломается срок `stop-one.sh`.
**Почему слот возвращается в `ready`.** Ручное состояние — свойство
слота, а не реплики. IPAM Docker сразу отдаёт адрес удалённой реплики
следующей, и DNS кладёт её в тот же слот. Это видно в замере: новая
реплика второго шага получила адрес и слот только что удалённой. Слот,
оставленный в `maint`, не пустил бы к ней ни одного запроса.
**Дренаж убирает одиночный 502** гонки keep-alive. Слот выведен, и LB
не отправляет запросов в соединения, которые uvicorn закрывает по
SIGTERM. Профиль `rollout` под 200 запросами в секунду — 0 ошибок
(раздел «Эксперименты и отказы»). `scripts/stop-one.sh` и профиль
`failover` дренаж не делают намеренно: они имитируют отказ, а не
плановую остановку.
**Сбой на середине.** Новая реплика не стала `UP` за срок или замену
прервали, пока она стартует (в том числе внутри `up --scale`, когда её
ID скрипту ещё не известен), — она удаляется. Её слот, если DNS уже
отдал его, сначала уходит в `maint`. Новая уже `UP` (в том числе при
Ctrl+C) — вывод текущей старой доводится до удаления. В любом исходе работает `API_REPLICAS` готовых
реплик, слоты без ручного состояния, повторный запуск доводит замену
(`evidence/rollout/script-failures.md`). Автоматического отката нет.
Откат — та же замена на образ прежнего commit без миграций: `make
rolling_update COMMIT=<commit> MIGRATE=0`.
**Миграции однократны и совместимы с работающей версией** (expand /
contract):
- ревизия только расширяет схему: новая таблица, колонка с NULL или
значением по умолчанию, индекс;
- удаление и переименование — отдельной поставкой, когда прежнего кода
не осталось.
Демонстрация — колонка `messages.instance_id` (`text NULL`, ревизия
`e656d6bbe1a4`): реплика, записавшая сообщение. Наружу она не
отдаётся, контракт не меняется:
- новый код её пишет, без неё упал бы, поэтому миграция обязана идти
до новых реплик;
- прежний код её не знает: вставляет свои колонки (NULL), читает свои.
Первой строкой ревизии — `SET LOCAL lock_timeout = '2s'`. `ADD COLUMN`
берёт `ACCESS EXCLUSIVE` на миллисекунды, но, пока ждёт блокировку, за
ним в очереди стоят все запросы к `messages`. Чужая долгая транзакция
без срока остановила бы запись всех реплик. Со сроком миграция падает
без изменений, замена не начинается, повтор проходит. Срок меньше
`statement_timeout` приложения (5 с): запросы из очереди дожидаются
отказа миграции и выполняются. В apply срок был 5 с, равный
`statement_timeout`, и verify поймал цену: под нагрузкой все 6 запросов,
вставших в очередь, получили 503 вместе с отказом миграции; с 2 с — 0
ошибок, задержка до 2 с (`evidence/rollout/script-failures.md`).
Проверено на рабочем стенде с итогового commit `84161c0`
(`evidence/rollout/compatibility.md`):
- реплики образа `c50b721` (до change) на схеме после новой миграции
проходят `make test` и `make student_test` (131 passed);
- `make rolling_update`, откат `COMMIT=c50b721 MIGRATE=0` и снова
вперёд — под `tests/load.py`, 0 неуспешных запросов из 16–21 тысячи на
каждый прогон; старые реплики после дренажа завершаются за 0,1 с с
кодом 0;
- по колонке видно, какая версия записала каждое сообщение;
- после замен (реплики `api-7`, `api-8` и дальше) работают `make
instances`, `make test-failover` в режимах `stop` и `kill`, `make
replicas`, `make test-persistence`, `make run_docker` поверх
заменённых реплик и `make down` + `make run_docker`; две замены подряд
не оставляют слотов LB с ручным состоянием, свободных слотов — те же
6 из 8.
**`make run_docker` и пересборка.** Пункт `KNOWN_ISSUES.md` «не
пересоздаёт работающие `api`» не воспроизвёлся
(`evidence/rollout/compatibility.md`, шаг B и шаг 6 жизненного цикла):
- compose пересоздаёт реплики, у которых изменилось содержимое образа,
— все разом, с простоем;
- пересборка без изменений кода реплики не трогает.
Хранилище образов Docker Desktop — containerd, и `docker ps`
показывает у реплик digest конфигурации образа, а не имя тега. Отсюда
была ошибка диагностики. Обновление без простоя — `make rolling_update`.
### Стенд лабы 3
Проект compose — `mtusi-lab3`, образ — `mtusi-messenger:lab3`. Имя
проекта задаёт имена volumes: с именем второй лабы стенд подключился бы
к её базе. Данные второй лабы не переносились (они синтетические), volume
`mtusi-lab2_postgres_data` не затронут, в том числе `make wipe_data`
этого стенда (`evidence/tests/stand-lab3.md`).
### `X-Instance-Id`
- Значение — `[app] instance_id`. Пусто (по умолчанию) — hostname
процесса, определённый один раз при загрузке настроек; в compose это
короткий ID контейнера, то есть то, что показывает
`docker compose ps -q api`. По нему `scripts/stop-one.sh` найдёт
контейнер без таблицы соответствия.
- Значение не задаётся ни в `config.toml`, ни в `.env`, ни в compose
(`environment`, `hostname:`): эти источники общие у реплик, а значение
должно различаться. В консоли его можно заменить `APP__INSTANCE_ID`.
Формат проверяется при старте (`[A-Za-z0-9._-]{1,64}`): с `api a`
сервис не стартует (`evidence/idempotency/config-checks.md`).
- Заголовок ставит то же ASGI-middleware, что `X-Request-Id`; ответ 500
собирает `ServerErrorMiddleware` снаружи него, поэтому обработчик
`Exception` ставит оба заголовка сам. То же значение — поле
`instance_id` в каждой записи журнала, включая старт и shutdown
(`evidence/idempotency/instance-id.md`).
- `docker restart` сохраняет hostname, и значение остаётся прежним;
новый контейнер — новое значение. В лабе 7 поле получит непрозрачный
alias вместо hostname.
### Идемпотентность отправки сообщения
Таблица `idempotency_keys` (миграция `7652184b7016`, только добавляет
таблицу): первичный ключ `(user_id, chat_id, key)` — область ключа
контракта «пользователь + метод + путь чата + ключ», ключ принимает одна
ручка; внешний ключ `(chat_id, user_id) → chat_members`; `message_id →
messages` с проверкой на commit (`DEFERRABLE INITIALLY DEFERRED`);
SHA-256 тела; `created_at` с индексом; `CHECK` формата и длины ключа.
Отправка (`MessageService.send_message`) — одна транзакция:
1. Сессию проверила зависимость (401), сервис проверяет членство (404) —
и при повторе тоже.
2. Захват ключа одним выражением: `INSERT … ON CONFLICT (user_id,
chat_id, key) DO UPDATE … WHERE created_at < now − ttl RETURNING`.
Строка вернулась — ключ свободен (новый или просроченный, заменён тем
же выражением): вставка сообщения, `commit()`.
3. Ключ занят — чтение сохранённого хэша и сообщения, `commit()` (снять
блокировку строки). Хэш совпал — тот же 201 и то же `Message` из БД;
не совпал — 409 `conflict`.
Почему это корректно, в том числе между репликами (READ COMMITTED):
одновременная вставка того же ключа ждёт commit или отката чужой
транзакции на уникальном индексе. После commit — конфликт и сохранённый
результат, после отката — вставка проходит, то есть транзиентная ошибка
результатом не фиксируется. Ключ вставляется раньше сообщения, поэтому
повтор не пишет и не откатывает сообщение. Любая ошибка до commit
откатывает и ключ, и сообщение (`evidence/tests/failure-checks.md`:
сбой вставки сообщения, остановка Postgres).
«То же тело» — SHA-256 канонического JSON, собранного из разобранного
тела (сортированные ключи, значения по умолчанию подставлены): пробелы,
`\u`-экранирование и порядок полей на сравнение не влияют, другой текст
— другой хэш. В журнале ключа нет: повтор виден по `"replayed": true` и
тому же `message_id`.
Порядок кодов при нескольких ошибках — 401 → 400 → 404 → 409.
`Idempotency-Key` объявлен параметром ручки (есть в `/openapi.json`),
а FastAPI проверяет параметры после зависимостей: без сессии — 401,
затем нет ключа или неверное тело — 400, затем не участник — 404,
затем другое тело — 409. Битый JSON — 400 раньше 401. Это то самое
расхождение порядка кодов FastAPI, согласованное с преподавателем
2026-09-26 (AGENTS.md, «Согласования с преподавателем»); smoke его не
затрагивает, порядок закреплён тестами `test_idempotency.py`.
### Соответствие переменных `.env.example`
| Имя skeleton | Где у нас | Почему так |
|---|---|---|
| `IDEMPOTENCY_TTL_SECONDS` | `[idempotency] ttl_seconds` в `config.toml`, по умолчанию 86400 (24 ч); разовая подмена — `IDEMPOTENCY__TTL_SECONDS` | значение читает только приложение; как `SESSION_TTL_SECONDS` (`.claude/rules/settings.md`). Срок меньше 86400 нарушает контракт и применяется только в проверках (2 с у «тесного» API стенда отказов) |
| `API_REPLICAS` | `API_REPLICAS` в `.env` (шаблон — 2), `deploy.replicas: ${API_REPLICAS:-2}` сервиса `api`; Makefile — `API_REPLICAS ?= 2` (`make replicas`, `EXPECT_REPLICAS` тестов). Разово — `make replicas API_REPLICAS=N` | приложение его не читает, поэтому имя без секции; без строки в `.env` действует 2 (`.claude/rules/settings.md`) |
TODO: остальные имена skeleton (`APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE`).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` через LB на стенде `make run_docker`; `make test_isolated` (образ из `a4ca9ef`, временная база, один контейнер): `make test` + `make student_test EXPECT_REPLICAS=1`; `make test` через LB стенда из настоящего `git clone` на нестандартных портах | `PASS: lab3 public API scenario` во всех трёх; в изоляции 127 passed, 4 теста реплик пропущены с причиной «one API process»; сверка покрытия: 135 сценариев, 123 тестом, 12 исключений | `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated.md`, `evidence/replicas/clean-clone-ports.md` |
| «3»: стенд одной командой, ≥2 API, одна точка входа, общие БД и сессии | `make run_docker` (рабочий стенд и настоящий `git clone`); `docker compose ps`, `docker port`, `docker compose config` | `haproxy` — единственный порт API на хосте (`127.0.0.1:8080`), `api` × 2 без портов и `container_name`; общие Postgres (сессии, данные, ключи) и Valkey; миграции — один прогон `migrate` на каждый up, в журналах реплик `alembic` нет; из клона стенд поднимается одной командой, `.env` и `config.toml` создаются сами | `evidence/replicas/stand.md`, `evidence/replicas/clean-clone-ports.md` |
| «3»: разные запросы одного пользователя — разными репликами без повторного входа | `make instances` (один вход, 12 × `GET /users/me` с одним токеном); `test_load_balancing.py` | ответы чередуются `3681880fc55f` / `8100f940a5fa` по 6; 20 запросов сессии — по 10; запись через одну реплику видна в чтениях через другую | `evidence/replicas/distribution.md`, `evidence/tests/student-test-lb.md` |
| «3»: отказ любой одной реплики — ≤10 с до новых чтений и записей; `make test-failover` | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` для каждой реплики, `make replicas` и сдвиг очереди round-robin одним запросом между прогонами; `STOP_ONE_LOG` — какой `TARGET_INSTANCE_ID` выбрал тест; `docker compose ps -a` и `StartedAt` до и после | 2 × `PASS`: остановлены `8100f940a5fa`, затем `3681880fc55f`; первая запись через 1,10–1,11 с, 0 неудачных попыток, по 2 запроса перенаправлены LB; ID остановленного контейнера = `TARGET_INSTANCE_ID`, остальные контейнеры с прежним `StartedAt`; через 20 с реплика всё ещё `exited`. С цепочкой таймаутов `graceful-failover` (commit `459f84c`) — снова `PASS` для каждой реплики: `stop` — 0 неудачных попыток, первая запись через 1,62 с; `kill` — 1 неудачная попытка (запрос в полёте), повторена с тем же ключом, первая запись через 0,23 с | `evidence/failover/test-failover.md`, `evidence/tests/graceful-failover-checks.md` |
| «3»: отказ процесса без graceful, реплика остаётся остановленной | `STOP_MODE=kill make test-failover …`; через 15 с `docker inspect`; `driver.py --port 8080 kill-inflight` (kill во время входов по Basic) | `PASS`, первая запись через 0,74 с; контейнер `exited` 137, `RestartCount` 0 через 15 с (`restart: unless-stopped` его не поднял); 3 входа в полёте — 502 от LB в формате контракта без повтора (`SH--`, повторов 0), 2 в момент kill — перенаправлены | `evidence/failover/test-failover-kill.md` |
| «3»: `make test-persistence` с LB | `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; `StartedAt` до и после | `PASS` за 6,4 с; перезапущены LB, обе реплики, Postgres и Valkey (те же ID, новый `StartedAt`), volume с прежней датой создания | `evidence/replicas/test-persistence.md` |
| «3»: повтор `POST` с тем же ключом при переключении реплики | `test_idempotency.py::test_replay_on_other_replica` через LB | отправка через `8100f940a5fa`, повтор через `3681880fc55f` — тот же JSON; другое тело — 409 от обеих реплик | `evidence/tests/student-test-lb.md` |
| Failover hook не трогает чужое | `scripts/stop-one.sh` с пустым, не-hex, коротким ID, ID Postgres / Valkey / LB / `migrate`, несуществующим, контейнером `mtusi-lab2`, `STOP_MODE=pause` | код 2 (неверное значение или режим, до вызова docker) или 3 (нет такой работающей реплики); состояние и `StartedAt` всех контейнеров не изменились | `evidence/failover/stop-one-refusals.md` |
| «4»: лимиты CPU/RAM, порты API не наружу, секреты только где нужно, нет `container_name` | `docker inspect` (`NanoCpus`, `Memory`), `docker port`, имена переменных из `docker compose config` | лимиты у всех 6 контейнеров; порт API только у LB; пароль Valkey только у `valkey` и `api`, у LB секретов нет; `container_name` нет. Цена лимита 1 CPU для Argon2id измерена (раздел «Ограничения») | `evidence/replicas/stand.md` |
| «4» (часть): LB исключает недоступный backend; период проверок | `make lb_stats`, `docker compose logs -t haproxy`; все реплики остановлены; одна реплика заморожена `docker pause`; PostgreSQL остановлен | период 1 с, `fall 2`, `rise 2`, `timeout check` 3 с; остановленные реплики `DOWN` / в обслуживании, вернувшиеся — после проверки; зависшая — `DOWN` через 7,7 с (формула худшего случая — 8 с), запрос в полёте — 504 в формате контракта; без PostgreSQL обе реплики отвечают на проверку 503 и исключаются за 1,2–1,8 с; без реплик LB отвечает 503 в формате контракта, healthcheck LB `unhealthy`. Замер обнаружения по режимам под нагрузкой — строка ниже (change `graceful-failover`; `timeout check` с тех пор 2,5 с и `fastinter 500ms`) | `evidence/replicas/lb-errors.md`, `evidence/failover/test-failover.md` |
| «4»: health/readiness, таймауты и прекращение приёма при SIGTERM согласованы; период проверок и максимальное время обнаружения | таблица цепочки таймаутов (раздел «Балансировщик и реплики»); `make bench_failover FAILOVER_LABEL=baseline` (commit `459f84c`, хост проверен); `driver.py --port 8080 idle-conns`; `driver.py --port 8080 hang-key`; запуск с неверными сроками | проверка раз в 1 с, `fastinter` 0,5 с, `fall 2`, `rise 2`, `timeout check` 2,5 с > 2 с готовности; худшее обнаружение — 2,5 с для остановленной и убитой реплики, 6,5 с для зависшей (было 8 с). Замер под нагрузкой: `stop` и `kill` — 0,79–1,81 с, `pause` — 5,83–6,00 с; возврат в LB — 1,2–1,8 с. Простаивающие соединения с репликами закрывает LB через 10,1 с (keep-alive реплики 60 с > `timeout http-keep-alive` 10 с, `http-reuse never`). Отвергнутый вариант — пул LB (`http-reuse safe`) при том же keep-alive 60 с — переснят на закоммиченном коде временным вторым HAProxy с одной изменённой строкой: последнее соединение закрыла реплика через 60,4 с. Транзакцию замороженной реплики PostgreSQL прерывает через 10 с простоя: повтор того же ключа — 201, одно сообщение; временный триггер сценария удаляется и при Ctrl+C или SIGTERM. Неверные сроки — сервис не стартует | `evidence/failover/detection.md`, `evidence/failover/keep-alive.md`, `evidence/failover/hung-key.md`, `evidence/failover/baseline/` |
| «4»: последовательная остановка каждой реплики с восстановлением предыдущей: RPS, ошибки, время восстановления | `make bench_failover FAILOVER_LABEL=baseline`: 100 записей с ключом и 100 чтений в секунду, каждая из двух реплик в режимах `stop`, `kill`, `pause`, возврат через 20 с | 6 фаз. `stop` и `kill`: ~200 успешных ответов в секунду всё время, 0 ошибок, восстановление 0 с, всплеск p95 до 505 мс в секунду действия. `pause`: 602 и 584 ответа 504 (половина запросов ~6 с до исключения), доля успешных 0,5, восстановление 6 с. После возврата ошибок нет. Неуспешные записи повторены с тем же ключом: сообщений 30 005 = ключей 30 005, одинаковых текстов нет | `evidence/failover/baseline/summary.md`, `evidence/failover/detection.md` |
| Регрессия на итоговом commit `graceful-failover` | `make test`, `make student_test` через LB, `make test-persistence`, `make test-failover` (`stop` и `kill`), `make test_isolated`, `make failure_checks`, `make bench_quick`, `make bench_restore_quick`, `make bench_failover_quick` | всё код 0: 131 passed через LB; 127 passed и 4 пропуска с причиной в изоляции; 15 проверок отказов; профили лабы 2 на стенде с HAProxy и одной репликой; быстрый профиль отказа — 4 фазы, сверка сошлась | `evidence/tests/graceful-failover-checks.md` |
| Масштабирование без правки LB | `make replicas API_REPLICAS=3`, затем `make replicas` | третья реплика в распределении через 2 с без правки `haproxy.cfg`; обратно — две | `evidence/replicas/distribution.md` |
| Порты из `.env` со стендом за LB | настоящий `git clone`, `make run_docker` во временном проекте с `APP_OUT_PORT=18090`, `APP__PORT=9090`, портами Postgres и Valkey 5544 / 15545 и 6390 / 16391 | реплики слушают 9090, LB проверяет их на 9090 (`L7OK`), API на хосте — только через LB на 18090; `make test` и `make student_test` (131 passed) через LB | `evidence/replicas/clean-clone-ports.md` |
| Тесты реплик не выдают пропуск за успех | `make student_test` против одного процесса без `EXPECT_REPLICAS=1` | 4 теста реплик падают с `saw 1 X-Instance-Id … EXPECT_REPLICAS=2`, остальные 127 проходят | `evidence/tests/student-test-lb.md` |
| Свои стенды на новом compose | `make test_isolated`, `make failure_checks`, `make bench_quick`, `make bench_restore_quick` | все код 0; рабочий стенд не тронут; лимиты в паспорте `bench` те же, что до change | `evidence/tests/test-isolated.md`, `evidence/tests/failure-checks.md`, `evidence/tests/bench-self-checks.md` |
| «3»: повтор `POST` с тем же `Idempotency-Key` не создаёт дубль | разовый HTTP-скрипт: отправка, повтор, повтор в `\u`-записи | все 201 с одинаковым JSON, в истории одно сообщение | `evidence/idempotency/replay.md` |
| «3»: другое тело с тем же ключом, нет и неверный ключ | тот же скрипт | 409 `conflict`; 400 без ключа и с `a b`, значение ключа в ответ не попадает; постороннему — 404, ключ у другого пользователя — новое сообщение | `evidence/idempotency/replay.md` |
| «3»: повтор через другой процесс API | отправка, `docker compose up -d --force-recreate api`, повтор с тем же ключом и токеном | новый контейнер и `X-Instance-Id`, тот же `Message` (тот же `id` и `created_at`) | `evidence/idempotency/replay-after-restart.md` |
| «3»: ключ переживает рестарт API и хранилищ | отправка, `scripts/restart.sh` (api, Postgres, Valkey без удаления volumes), повтор с тем же ключом и токеном | новый `StartedAt` у всех трёх; повтор — 201 и тот же `Message`, другое тело — 409, в чате одно сообщение | `evidence/idempotency/replay-after-storage-restart.md` |
| «3»: неподтверждённую запись можно повторить; сбой не занимает ключ | `make failure_checks`: триггер роняет вставку сообщения после вставки ключа; остановка Postgres | 500 / 503, затем повтор с тем же ключом — 201, ровно одно сообщение | `evidence/tests/failure-checks.md` |
| Срок ключа | `make failure_checks`, «тесный» API с `IDEMPOTENCY__TTL_SECONDS=2` | в пределах срока другое тело — 409, после срока — 201 и новое сообщение | `evidence/tests/failure-checks.md` |
| Настройки `instance_id` и срока ключа | API в консоли с `APP__INSTANCE_ID=api-a`; запуск с `APP__INSTANCE_ID="api a"`, `IDEMPOTENCY__TTL_SECONDS=abc` и `0` | `X-Instance-Id: api-a` и `instance_id` = `api-a` во всех 14 записях журнала; недопустимые значения — код 1 до старта, ошибка называет поле | `evidence/idempotency/config-checks.md` |
| «4»: идемпотентность под параллельными запросами с одним ключом | `test_race.py::test_same_key_through_replicas` через LB: 10 клиентов за `threading.Barrier`, одно тело и один ключ | 10 × 201 с одним `Message`, одно сообщение в истории; ответы обеих реплик (5 + 5), есть пара пересекающихся по времени запросов разных реплик; то же на стенде из клона. Против одного процесса — `test_same_key_at_once` | `evidence/tests/student-test-lb.md`, `evidence/replicas/clean-clone-ports.md`, `evidence/idempotency/keys-table.md` |
| `X-Instance-Id` на каждом ответе, `instance_id` в журнале | тесты `api-conventions`, `curl`, `docker compose logs api` | заголовок у 2xx, 4xx, health, 404, 405, 500; значение = короткий ID контейнера; 85 из 85 записей журнала с `instance_id`, включая старт и shutdown; ключей и текста в журнале нет | `evidence/idempotency/instance-id.md` |
| Стенд лабы 3 не трогает данные лабы 2 | `make run_docker`, `make wipe_data`, снова `make run_docker`; `docker volume inspect` до и после | `wipe_data` удалил только контейнеры, сеть и volume `mtusi-lab3`; `mtusi-lab2_postgres_data` с прежней датой создания | `evidence/tests/stand-lab3.md` |
| Сборка из чистого clone | `git clone`, `docker build -t mtusi-messenger:lab3 .` до `make env_setup`; стенд на этом образе, `make test` | сборка без `.env` и `config.toml`, в образе их нет, процесс от UID 10001; `PASS: lab3 public API scenario` | `evidence/tests/clean-clone.md` |
| Стенд `bench/`: отправки с ключом при восстановлении | `make bench_restore_quick` (самопроверка, не замер) | 1000 отправок во время backup на каждом размере, 0 неудачных; сообщений в исходной базе = подтверждённых отправок; сверка баз прошла | `evidence/tests/bench-restore-quick.md` |
| «4»: rolling update (поочерёдная замена) проверен под нагрузкой | `make bench_rollout ROLLOUT_LABEL=baseline` (commit `9dcea0b`, код `de654a1`, хост проверен, рабочий стенд остановлен): 100 записей с ключом и 100 чтений в секунду, две реплики образа `c50b721` заменяются на образ текущего checkout тем же `scripts/rolling-update.sh`; на рабочем стенде (итоговый код `84161c0`) — `make rolling_update`, откат `COMMIT=c50b721 MIGRATE=0`, снова вперёд и две замены подряд под `tests/load.py`; быстрый профиль `make bench_rollout_quick` на `84161c0` | замена 8,9 с; **0 ошибок** из 24 002 запросов, доля успешных 1,0 в каждой секунде, p95 5 → макс. 11 мс; по шагам: новая `UP` в LB через 2,0–2,1 с после старта, дренаж старой 0,14–0,16 с, остановка 0,3–0,4 с; после вывода из LB старая не получила ни одного запроса; сообщений 12 001 = ключей 12 001. Рабочий стенд: 0 неуспешных из 21 043 / 16 687 / 18 480 / 27 278 запросов `tests/load.py`; старые реплики завершаются за 0,1 с с кодом 0 («Finished server process»); контейнеров прежних реплик после замены нет. Быстрый профиль на итоговом коде: замена 8,1 с, 0 ошибок, 7 301 = 7 301 | `evidence/rollout/baseline/summary.md`, `evidence/rollout/compatibility.md`, `evidence/tests/rolling-update-checks.md` |
| «4»: миграции однократно и совместимы с работающей версией | реплики образа `c50b721` + миграция нового образа в контейнере сервиса `migrate` (команда скрипта), без замены; `make test`, `make student_test`; замена; `SELECT instance_id, count(*)` по сообщениям; миграция под чужой блокировкой и нагрузкой | новая ревизия `e656d6bbe1a4` (колонка `messages.instance_id`, NULL) при прежних репликах: `PASS`, 131 passed; запись прежней версии — NULL, новой — её `X-Instance-Id`; при замене одна миграция в контейнере `migrate` до первой новой реплики, в журналах реплик alembic нет; повторный запуск — no-op; откат кода без отката схемы (после отката `migrate` прежнего образа падает на новой ревизии — ограничение, описано); под чужой транзакцией `lock_timeout` 2 с → миграция падает с кодом 1, схема и реплики не тронуты, 6 запросов из очереди за ней — успешны за 2,0 с (с 5 с в apply — все 6 получили 503), повтор проходит | `evidence/rollout/compatibility.md`, `evidence/rollout/script-failures.md` |
| Замена при сбое и неготовом стенде | остановленная реплика, `API_REPLICAS=3`, слоты в ручном `maint` / `drain`, `ROLLOUT_READY_TIMEOUT=1`, настоящий Ctrl+C (^C в псевдотерминал под `make`) во время дренажа и внутри `up --scale` под нагрузкой, порт 9999 LB из сети и с хоста | код 2 до сборки (для слотов — с командой возврата в `ready`); неготовая новая реплика удалена, работают 2 реплики `UP`; Ctrl+C во время дренажа — вывод старой доведён до удаления, внутри `up --scale` — новая реплика найдена и удалена (до исправления в verify оставалась третья реплика), 0 неуспешных запросов, повтор довёл замену; слоты LB без ручного состояния; канал управления LB из сети и с хоста — отказ соединения | `evidence/rollout/script-failures.md` |
| `make run_docker` после пересборки | реплики на образе прежнего commit, `docker compose build api`, `docker compose --dry-run up -d`; `make run_docker` поверх заменённых реплик | compose пересоздаёт реплики с изменившимся образом, без изменений — не трогает (те же ID); пункт `KNOWN_ISSUES.md` не воспроизвёлся и закрыт | `evidence/rollout/compatibility.md` |
| Регрессия на итоговом коде `rolling-update` (`84161c0`) | `make test`, `make student_test`, `make instances`, `make test-failover` (`stop` и `kill`, обе реплики), `make replicas`, `make test-persistence`, `make run_docker`, `make down` + `make run_docker`, две замены подряд — на репликах после замены; `make test_isolated`, `make failure_checks`, `make bench_failover_quick`, `make bench_rollout_quick` | всё код 0 (131 passed через LB, 127 + 4 пропуска в изоляции, 15 проверок отказов, быстрые профили на чистом дереве); apply нашёл дефект шага миграций (контейнер `migrate` прежнего образа ломал `restart.sh`, исправлен в `de654a1`), verify — уборку при Ctrl+C внутри `up --scale` и `lock_timeout`, равный `statement_timeout` (`5e102e6`, `84161c0`) | `evidence/tests/rolling-update-checks.md`, `evidence/rollout/compatibility.md` |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `docker stop` одной из двух реплик (`stop-one.sh`) во время записи раз в 0,1 с | закрытый сокет → отказ соединения → LB перенаправляет, ошибок нет | 0 неудачных попыток в 2 прогонах (по одному на реплику); по 2 отправки перенаправлены (`+1` в журнале LB), одна — через `timeout connect` 500 мс к пропавшему адресу | первая запись 1,10–1,11 с от старта hook; потерь и дублей нет (`evidence/failover/test-failover.md`) |
| `docker kill` реплики | запросы в полёте рвутся, LB их не повторяет; клиент повторяет с тем же ключом | при записи раз в 0,1 с в полёте не оказалось ни одной (0 ошибок); при входах по Basic (`driver.py kill-inflight`) 3 оборванных → 502 без повтора, 2 перенаправлены | первая запись 0,74 с; дублей нет; реплика не поднимается сама (`evidence/failover/test-failover-kill.md`) |
| `docker pause` одной реплики (зависла), до `graceful-failover` | проверка ждёт `timeout check` и исключает реплику не позже 8 с; запрос в полёте — 504 | `DOWN` через 7,7 с; запрос на ней — 504 в формате контракта через 10 с (`timeout server`), без повтора; после разморозки — `UP` через 1,1 с | 7,7 с до исключения; второй запрос сразу ушёл на живую реплику (`evidence/replicas/lb-errors.md`). С `graceful-failover` граница 6,5 с, замер — таблица ниже |
| реплика заморожена посреди отправки с ключом (`driver.py hang-key`) | ключ занят её транзакцией; PostgreSQL прерывает транзакцию через 10 с простоя, повтор того же ключа проходит | повтор через живую реплику — 503 по `statement_timeout` (ждёт блокировку), через замороженную — 504; через 12,1 с PostgreSQL прервал простаивающую транзакцию, следующий повтор — 201 | одно сообщение в чате, ключ и сообщение замороженной транзакции откатились (`evidence/failover/hung-key.md`) |
| остановка PostgreSQL | реплики отвечают 503 на `/health/ready`, LB исключает обе и отвечает 503 сам | первые ~2 с — 503 от API, затем 503 от LB на всё, включая `/health/live`; после запуска PostgreSQL обе реплики `UP` | 1,2–1,6 с после запуска PostgreSQL, без рестарта реплик и LB (`evidence/replicas/lb-errors.md`) |
| остановка всех реплик | LB отвечает 503 в формате контракта, healthcheck LB — `unhealthy` | так и есть; после `make replicas` — 200 через ~3 с | данные в Postgres не затронуты (`evidence/replicas/lb-errors.md`) |
| `scripts/restart.sh`: LB, обе реплики, Postgres, Valkey | данные и токен переживают рестарт | `PASS`; до прохождения проверок LB отвечал 503, реплики начинают в `DOWN` | 6,4 с на тест целиком; кэш пуст, данные целы (`evidence/replicas/test-persistence.md`) |
| `make rolling_update` под `tests/load.py` (4 клиента): вперёд, откат на `c50b721`, снова вперёд | новая реплика в LB до вывода старой, старая выводится из LB до SIGTERM — ошибок нет | 0 неуспешных из 21 043, 16 687 и 18 480 запросов (`84161c0`); замена 10–12 с; новая миграция при прежних репликах — `make test` и `make student_test` проходят | простоя нет; по `messages.instance_id` видно, какая версия что записала (`evidence/rollout/compatibility.md`) |
| миграция ждёт блокировку `messages` за чужой 20-секундной транзакцией, через LB идут запись и чтение | миграция сдаётся по `lock_timeout`, запросы в очереди за ней выполняются | `lock_timeout` 5 с (apply): все 6 запросов из очереди — 503 через 5,03 с (`statement_timeout` приложения 5 с истёк вместе с ним); 2 с (`84161c0`): 0 ошибок, те же 6 запросов — 2,01–2,02 с | схема и реплики не тронуты, повтор после конца транзакции прошёл (`evidence/rollout/script-failures.md`, случай 7) |
### Отказ каждой реплики под нагрузкой (change `graceful-failover`)
**Гипотеза** (design `graceful-failover`, решения 1–3):
- `docker stop` реплики не даёт ошибок от её недоступности: закрытый
сокет и пропавший адрес — отказ соединения, LB перенаправляет запрос;
- `docker kill` — то же, кроме запросов в полёте на убитой реплике: 502
без повтора LB;
- зависшую реплику (`docker pause`) LB исключает не позже 6,5 с, а до
этого половина запросов ждёт `timeout server` и получает 504;
- время восстановления до ≥ 99 % успешных в секунде — не больше
времени исключения, то есть ≤ 10 с во всех режимах;
- после повтора неуспешных записей с тем же ключом нет ни потерь, ни
дублей.
**Методика.** `make bench_failover FAILOVER_LABEL=baseline`
(`bench/run.py`, профиль `failover`; правила — `.claude/rules/bench.md`):
- стенд `mtusi-bench`: HAProxy 3.4.6 с тем же `haproxy.cfg`, две
реплики API по 1 CPU / 512 МиБ, PostgreSQL 2 CPU / 1 ГиБ, Valkey
0,5 CPU / 128 МиБ — лимиты рабочего стенда;
- k6 2.3.0 в сети стенда, через LB, открытая модель с постоянной
интенсивностью: 100 записей сообщения с `Idempotency-Key` и
100 чтений страницы истории (50 сообщений, чат из 1 000) в секунду;
- фаза — одна реплика в одном режиме: 15 с нагрузки, действие, 20 с,
возврат (`docker start` того же контейнера или `docker unpause`),
15 с. Порядок: `stop` реплики 1, 2, `kill` 1, 2, `pause` 1, 2;
- время — часы ВМ Docker: действие — событие Docker, исключение и
возврат — журнал HAProxy, запросы — отметки k6 при отправке; секунда
запроса — по отправке;
- после фазы неуспешные записи повторяются с тем же ключом до 201, затем
сверка в PostgreSQL: сообщений в чате записи = отправленных ключей,
разных текстов столько же.
Commit `459f84c`, чистое рабочее дерево. Хост: Docker Desktop 29.8.2,
macOS arm64, ВМ 12 CPU / 7,7 GiB; питание от сети, свободной памяти
56 %, посторонних контейнеров нет (рабочий стенд остановлен), выгрузки
в swap за прогон не было (`Swapouts` до и после одинаковы). Один прогон
на фазу: замер показывает поведение, а не распределение.
**Результат** (`evidence/failover/baseline/summary.md`,
`evidence/failover/detection.md`):
| Фаза | Исключение LB, с (граница) | Успешных в секунду в окне отказа, мин. | Ошибки в окне отказа | Мин. доля успешных в секунде | Восстановление ≥ 99 %, с | p95 успешных: до / макс. в окне, мс | Возврат в LB, с | Ошибки после возврата | Сверка: сообщений = ключей |
|---|---|---|---|---|---|---|---|---|---|
| `stop`, реплика 1 | 1,06 (2,5), DNS | 200 | 0 | 1 | 0 | 5 / 505 | 1,73 | 0 | 5 001 = 5 001 |
| `stop`, реплика 2 | 1,01 (2,5), DNS | 200 | 0 | 1 | 0 | 4 / 505 | 1,21 | 0 | 10 002 = 10 002 |
| `kill`, реплика 1 | 1,81 (2,5), DNS | 199 | 0 | 1 | 0 | 4 / 505 | 1,16 | 0 | 15 002 = 15 002 |
| `kill`, реплика 2 | 0,79 (2,5), DNS | 200 | 0 | 1 | 0 | 5 / 505 | 1,75 | 0 | 20 003 = 20 003 |
| `pause`, реплика 1 | 6,00 (6,5), проверки | 99 | 602 × 504 | 0,5 | 6 | 5 / 104 | 1,53 | 0 | 25 004 = 25 004 |
| `pause`, реплика 2 | 5,83 (6,5), проверки | 100 | 584 × 504 | 0,5 | 6 | 4 / 150 | 1,53 | 0 | 30 005 = 30 005 |
**Итог по гипотезе:**
- `stop` и `kill` — подтверждено, ошибок 0. Остановленную и убитую
реплику LB убирал по DNS через 0,79–1,81 с, раньше проверок. Цена —
задержка: запросы, назначенные на пропавший адрес, ждали `timeout
connect` 0,5 с и уходили на другую реплику (p95 505 мс в секунду
действия). Запросов в полёте на убитой реплике в этих двух фазах не
оказалось (p50 запроса — 3 мс). В самопроверках быстрого профиля —
1–2 ответа 502 на фазу `kill` и одиночный 502 в части фаз `stop`
(гонка keep-alive при SIGTERM, `evidence/failover/keep-alive.md`);
доля успешных и там не ниже 99 %.
- `pause` — подтверждено с ценой: 5,83–6,00 с до исключения при
границе 6,5 с, всё это время половина запросов получала 504 через
10 с, восстановление — 6 с. Во второй фазе все записи этих секунд
попали на замороженную реплику (записи и чтения идут вперемешку
поровну, round-robin чередует реплики). Зависшая реплика — самый
дорогой отказ: её не видно, пока не провалятся две проверки по 2,5 с.
- Возврат реплики — 1,2–1,8 с до `UP`, ошибок после возврата нет
(`init-state down`, два успеха проверки).
- Потерь и дублей нет: 240 и 584 неуспешные записи фаз `pause`
повторены с тем же ключом — 201, сообщений столько же, сколько ключей.
**Ограничения замера.** Один хост: генератор, LB, реплики и
PostgreSQL делят ВМ Docker. Один прогон на фазу. Интенсивность — около
половины потолка одной реплики, чтобы после отказа оставшаяся
держала всю нагрузку; на пределе мощности одной реплики отказ дал бы
ещё и ошибки перегрузки. Отказ узла, LB и PostgreSQL не воспроизводится
(«Ограничения»).
### Поочерёдная замена под нагрузкой (change `rolling-update`)
**Гипотеза** (design `rolling-update`, решения 2–4):
- клиент не видит ни одной ошибки, в том числе 502 гонки keep-alive из
профиля `failover`:
- новая реплика получает запросы только после `UP` в LB;
- старая выводится из LB раньше SIGTERM;
- в каждой секунде отвечают только реплики, которые сейчас в LB;
- после вывода старая не получает ни одного запроса;
- записи не теряются и не дублируются.
**Методика.** `make bench_rollout ROLLOUT_LABEL=baseline` (`bench/run.py`,
профиль `rollout`; `.claude/rules/bench.md`):
- стенд `mtusi-bench` с лимитами рабочего стенда, как у профиля
`failover`;
- реплики стартуют на образе `c50b721` (`git archive`, схема
`7652184b7016`);
- k6 — постоянная интенсивность, 100 записей с `Idempotency-Key` и
100 чтений истории в секунду;
- через 15 с — `scripts/rolling-update.sh` против проекта стенда: сборка
текущего checkout, миграция `e656d6bbe1a4`, замена обеих реплик;
- ещё ≥ 15 с нагрузки после замены;
- время — часы ВМ Docker: события контейнеров проекта (поток `docker
events`), журнал HAProxy, отметки k6;
- после прогона неуспешные записи повторяются с тем же ключом, затем
сверка в PostgreSQL.
Commit `9dcea0b` (код `de654a1`), чистое дерево. Хост: Docker Desktop
29.8.2, ВМ 12 CPU / 7,7 GiB, питание от сети, свободной памяти 52–53 %,
swap занят 920 МиБ, но выгрузки за прогон не было (`Swapouts` до и
после одинаковы). Посторонних контейнеров нет, рабочий стенд
остановлен. Один прогон.
Итоговый код change — `84161c0`: после замера verify поменял пути сбоя
скрипта (уборка при Ctrl+C, предусловие о слотах, код выхода в строке) и
`lock_timeout` миграции (2 с вместо 5 с). Порядок замены и то, что видит
клиент, они не меняют: `lock_timeout` действует только при чужой
блокировке, а в замере миграция получает её за миллисекунды. Поэтому
полный замер не переснимался; быстрый профиль на `84161c0` — замена
8,1 с, 0 ошибок, сверка 7 301 = 7 301
(`evidence/tests/rolling-update-checks.md`).
**Результат** (`evidence/rollout/baseline/summary.md`):
| Шаг | Новая: старт → `UP` в LB, с | Дренаж старой, с | Остановка старой, с | Шаг целиком, с | Ошибок | Запросов старой после дренажа |
|---|---|---|---|---|---|---|
| 1 | 2,08 | 0,16 | 0,42 | 3,21 | 0 | 0 |
| 2 | 2,03 | 0,14 | 0,33 | 3,13 | 0 | 0 |
- Замена целиком (от создания контейнера миграции до удаления последней
старой) — 8,9 с; сборка из кэша 0 с, миграция 2 с.
- Ошибок нет ни до, ни во время, ни после замены: 0 из 24 002
запросов. В каждой секунде 200 успешных, доля 1,0. p95 — 5 мс до
замены, максимум 11 мс во время.
- Ответы по версиям: первый ответ новой реплики — через 4,05 с,
последний ответ старой — 8,3 с. В секунду 4 — 114 старых и 86
новых, в секунду 8 — 20 и 180, с секунды 9 — только новые.
- Сверка: сообщений 12 001 = ключей 12 001, одинаковых текстов нет,
повторять было нечего.
**Итог по гипотезе:** подтверждено. В профиле `failover` `docker stop`
под той же нагрузкой давал одиночный 502 в части фаз. При плановой
замене с дренажём 502 нет ни одного: запрос в слот, выведенный в
`drain`/`maint`, LB не отправляет. Новая реплика вступает в работу через
~2 с после старта (`init-state down`, `rise 2`). Число реплик в LB не
опускается ниже двух.
**Ограничения замера.** Один хост, один прогон: замер показывает
поведение, а не распределение. Нагрузка — около половины потолка одной
реплики. Под нагрузкой выше потолка двух реплик третья на время замены
добавила бы CPU-конкуренцию. Сборка образа шла из кэша. Холодная сборка
займёт больше времени, но на шаги замены не влияет: она идёт до
миграции.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Идемпотентность:
- **Таблица ключей растёт.** Строка на каждое сообщение, фоновой
уборки нет до worker лабы 5. Просроченный ключ заменяется только при
следующей отправке с ним же. Ручная очистка — по индексу `created_at`:
```sh
docker compose exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
-c "DELETE FROM idempotency_keys WHERE created_at < now() - interval '"'"'24 hours'"'"'"'
```
Удаляются только ключи, сообщения остаются.
- **Замороженная реплика держит ключ до 10 с.** Если процесс заморожен
(`docker pause`) между захватом ключа и commit, повторы того же ключа
на других репликах ждут его блокировку до `statement_timeout` (5 с)
и получают 503. Через 10 с простоя PostgreSQL прерывает такую
транзакцию (`idle_in_transaction_session_timeout` с change
`graceful-failover`), и следующий повтор проходит: 201 через ~12 с
после начала транзакции (`evidence/failover/hung-key.md`). Раньше
ключ оставался занят до разморозки.
- **Каждая запись дороже на одну вставку** и проверку отложенного
внешнего ключа. Это цена контракта; её измеряет трек 1, там же
кандидат «ключ и сообщение одним SQL-выражением» (`PLAN.md`).
- **После 24 ч** повтор того же тела с тем же ключом создаст новое
сообщение: контракт гарантирует повтор только в пределах срока.
- **В консоли `X-Instance-Id` — имя машины разработчика**; для локальной
разработки это допустимо, `APP__INSTANCE_ID` его заменяет.
Балансировщик и реплики:
- **Что стенд выдерживает и что нет.** Один Docker-host, один HAProxy,
одна PostgreSQL, один Valkey. Выдерживается отказ процесса API —
любой одной реплики при второй живой. Не выдерживается отказ хоста,
LB и PostgreSQL: это единые точки отказа, устойчивость к ним не
заявляется. Отказ Valkey — деградация до Postgres, не отказ.
- **8 слотов `server-template`.** Девятую реплику LB не увидит; 8 —
максимум серий трека 1. Число меняется в `haproxy.cfg`.
- **Граница пула Postgres.** С пулом 10 + 5 на реплику при 7 репликах
соединений больше `max_connections` (106 > 100). Гипотеза 3 трека 1.
- **Зависшую реплику LB исключает за 6,5 с, а не мгновенно.**
`timeout check` 2,5 с, а не 1 с, как в плане: проверка не должна
обрываться раньше таймаута готовности внутри API (2 с). Уменьшать и
его нельзя: `/health/ready` берёт соединение из общего пула, и
заминка PostgreSQL на 1–2 с вывела бы из LB все реплики разом.
Худшее обнаружение зависшей реплики — `inter` + `timeout check` +
`fastinter` + `timeout check` = 6,5 с (замер под нагрузкой — 5,8–6,0 с),
всё это время половина запросов получает 504 через 10 с. Остановленную
и убитую реплику LB исключает за 0,8–1,8 с (DNS, граница проверок
2,5 с). Пассивная проверка по ошибкам живого трафика зависшую реплику
не ускорила бы: соединение с ней устанавливается, а ответ 504 приходит
только через `timeout server` (design `graceful-failover`, решение 2).
- **Оборванный ответ при `kill`.** Запросы в полёте на убитой реплике
получают 502 от LB, LB их не повторяет (они уже дошли). Отправку
сообщения клиент повторяет с тем же ключом; другие `POST` — на
усмотрение клиента, прозрачных повторов контракт не допускает.
Воспроизводится командой `driver.py --port 8080 kill-inflight`.
- **Отказ PostgreSQL выводит из LB все реплики сразу.** `/health/ready`
проверяет PostgreSQL, поэтому через 1–2 с после его отказа на всё,
включая `/health/live`, отвечает сам HAProxy: 503 `unavailable` в
формате контракта — тот же код, что отдал бы API. Liveness процесса
без LB проверяет `make failure_checks`.
- **Выбор реплики в `make test-failover`.** Тест останавливает
реплику, ответившую на его первую отправку; число запросов до неё
постоянно, и при round-robin по двум репликам после `make replicas`
тест снова выбирает ту же. Для второй реплики очередь сдвигается
одним запросом до теста (`evidence/failover/test-failover.md`).
- **Argon2id под лимитом 1 CPU.** Один процесс API — один event loop,
он больше 1 CPU не использует, а Argon2id (`p=4`) считает хэш в
четырёх потоках. Под лимитом реплики проверка пароля подряд идёт
около 0,14 с вместо 0,025 с, четыре одновременных — 0,8–1,6 с;
одиночный вход через LB — около 50 мс. Пока на реплике идёт вход, её
остальные запросы делят с ним квоту: при 8 потоках входа `GET
/users/me` — медиана 46 мс вместо 2 мс, p95 101 мс
(`evidence/replicas/stand.md`). `make test_isolated` (около 190
регистраций и 190 входов на одной реплике) идёт около минуты вместо
21 с. Лимит оставлен осознанно: вход редок, в замеры трека 1 не
входит, серия B считает реплику в 1 CPU.
- **Одиночный 502 при `docker stop` под нагрузкой.** Простаивающее
соединение LB → реплика теперь закрывает LB (`http-reuse never`,
`timeout http-keep-alive` 10 с < keep-alive реплики 60 с,
`evidence/failover/keep-alive.md`). Но при SIGTERM uvicorn сразу
закрывает простаивающие соединения, и запрос, который LB в тот же
миг отправил в такое соединение, получает 502 без повтора. Под
нагрузкой 200 запросов в секунду на закоммиченном коде — одиночный 502
в 1 из 4 фаз `stop` (регрессия и замер `baseline`), доля успешных в
секунде не ниже 99 %. С пулом (`safe`) гонка та же: в разведке на
рабочем дереве — 1 из 9 фаз против 2 из 10 с `never`, разница в
пределах случайности (это история поиска, не доказательство,
`evidence/failover/keep-alive.md`). Клиенты с новым соединением на
запрос (`make test-failover`) его не встречают; отправку сообщения
клиент повторяет с тем же ключом. README допускает краткие ошибки во
время обнаружения отказа, если они измерены. Плановая остановка
(`make rolling_update`, change `rolling-update`) сначала выводит
реплику из LB через его runtime API и только потом шлёт SIGTERM.
Под той же нагрузкой это 0 ошибок (профиль `rollout`). Одиночный 502
остаётся только у остановки без дренажа, то есть у имитации отказа
(`stop-one.sh`, профиль `failover`).
Поочерёдная замена и миграции:
- **Автоматического отката нет.** Сбой на середине оставляет
`API_REPLICAS` готовых реплик, возможно, разных версий. Миграция
только расширяет схему, так что обе версии работают; повторный запуск
доводит замену. Откат — `make rolling_update COMMIT=<прежний>
MIGRATE=0`: его миграции не знают новой ревизии, поэтому шаг
пропускается явно, а схема остаётся новой. После отката тег
`mtusi-messenger:lab3` указывает на прежний образ: `docker compose up`
без сборки пересоздал бы на нём `migrate`, и тот упал бы на новой
ревизии. Вперёд — снова `make rolling_update` или `make run_docker`
(`evidence/rollout/compatibility.md`, шаг E).
- **Contract-миграции нет в этой поставке.** Удалить или переименовать
колонку можно только отдельной миграцией, когда кода, который её
пишет, не осталось. `downgrade` новой ревизии удаляет колонку и
допустим только тогда же.
- **`lock_timeout` 2 с.** Под тяжёлой записью или во время `pg_dump`
(он держит `ACCESS SHARE` на все таблицы до конца) миграция может не
дождаться блокировки и упасть. Тогда замена не начинается, повтор
проходит. Это осознанный выбор: иначе очередь всех записей ждала бы
за миграцией. Пока миграция ждёт, запросы к `messages` стоят в
очереди до 2 с.
- **Сборка образа идёт на том же хосте, под нагрузкой.** Из кэша слоёв
— секунды CPU ВМ Docker.
- **SIGTERM во время старта реплики теряется** (процесс с PID 1 до
установки обработчиков uvicorn, `KNOWN_ISSUES.md`). Скрипт обходит это
для неготовой новой реплики: слот в `maint`, затем `docker rm -f`.
Штатные остановки касаются уже запущенных процессов.
- **Замена только на одном хосте** и только для `api`. LB, PostgreSQL и
Valkey обновляются с простоем.
- **Профиль отказа — один прогон на фазу, один хост.** Замер показывает
поведение и порядок величин, а не распределение. Генератор, LB,
реплики и PostgreSQL делят ВМ Docker (`evidence/failover/baseline/`).
## Ответы на вопросы защиты
**Чем отказ процесса отличается от отказа узла?** Отказ процесса —
остановлена, убита или зависла одна реплика API, а хост, сеть, LB и
хранилища живы. Его стенд переживает, и это измерено под нагрузкой
200 запросов в секунду (`evidence/failover/detection.md`):
- `docker stop` (SIGTERM) — процесс дорабатывает запросы в полёте и
закрывает сокет; LB получает отказ соединения и перенаправляет
запрос, через 1,0–1,1 с убирает реплику из распределения. Ошибок 0,
только задержка до 0,5 с у запросов, попавших на пропавший адрес;
- `docker kill` (SIGKILL) — то же, но запросы в полёте рвутся: 502 от
LB без повтора, клиент повторяет отправку с тем же ключом. Исключение
— 0,8–1,8 с;
- зависание (`docker pause`) — процесс жив для сети, но не отвечает.
Его видно только по проверкам: 5,8–6,0 с (граница 6,5 с), и всё это
время половина запросов получает 504. Его открытую транзакцию
PostgreSQL прерывает через 10 с простоя, ключ освобождается.
Вторая реплика обслуживает те же сессии и данные из PostgreSQL,
подтверждённые сообщения не теряются, повтор с тем же ключом не даёт
дублей. Отказ узла — пропал весь хост: вместе с ним LB, PostgreSQL,
Valkey и все реплики, и переключаться некуда. Причём для остальных
узлов отказ узла выглядит как зависание или пропавший адрес, а не как
аккуратный отказ соединения: соединения висят до таймаутов. На одном
хосте его не пережить, это трек 2, который мы не выбрали. Здесь хост,
LB и PostgreSQL честно названы единой точкой отказа.
**Почему `depends_on` и healthcheck сами по себе не являются
балансировщиком?** `depends_on` лишь упорядочивает старт контейнеров
(postgres → migrate → api), а healthcheck только меняет статус
контейнера на `unhealthy`: Docker Compose не перестаёт слать ему
запросы и не распределяет их. Распределять некому: без LB клиент
ходит на один опубликованный порт одного контейнера. Нужен отдельный
процесс, который принимает соединения, выбирает готовую реплику,
исключает неготовую по своей проверке и повторяет недошедший запрос —
здесь это HAProxy с проверкой `/health/ready` раз в секунду.
Healthcheck контейнера остаётся для `make replicas --wait` и
`docker compose ps`. При поочерёдной замене видно, что одного
`healthy` мало: реплика попадает в распределение LB только после его
собственных проверок, через ≤ 1,5 с. Поэтому `make rolling_update` ждёт
состояния `UP` в статистике HAProxy, а старую реплику выводит из LB
явно, до остановки.
**Дополнительно (уровень «4»): как обновить API без простоя и почему
миграция не ломает работающие реплики?** `make rolling_update` меняет
реплики по одной:
1. одна новая рядом со старыми;
2. ожидание её `UP` в LB;
3. старая выводится из LB (`drain`), дорабатывает запросы,
останавливается и удаляется.
Реплик всё время не меньше `API_REPLICAS`, клиент ошибок не видит:
профиль `rollout` под 200 запросами в секунду и публичный
`tests/load.py` — 0 неуспешных. Миграция выполняется один раз, до
первой новой реплики, и только расширяет схему (expand/contract).
Старые реплики работают на новой схеме: это проверено `make test` и
`make student_test` на образе прежнего commit после новой миграции.
Откат кода не требует отката схемы. Удаление и переименование —
отдельной поставкой, когда прежнего кода не осталось
(`evidence/rollout/compatibility.md`).
**Какие POST можно повторять после timeout и что защищает
`Idempotency-Key`?** После таймаута клиент не знает, выполнен ли
запрос. Безопасно повторять только `POST
/api/v1/chats/{chat_id}/messages` с тем же ключом и телом: ключ и
сообщение пишутся одной транзакцией, повтор через любую реплику вернёт
тот же 201 и то же `Message`, другое тело — 409, одновременные повторы
дают одно сообщение. Регистрация, создание чата и вход ключа не имеют:
повтор создаст второго пользователя (или 409), второй чат, вторую
сессию. Поэтому и LB повторяет запрос сам только при отказе
соединения, когда запрос до реплики точно не дошёл (`retry-on
conn-failure`), а не по таймауту или обрыву ответа
(`evidence/failover/test-failover-kill.md`).
**Что сломается при увеличении числа API, если сессии находятся в
локальной памяти?** Токен, выданный одной репликой, другая не знает:
round-robin отправит следующий запрос на другую реплику — 401, хотя
пользователь вошёл. Logout отзовёт сессию только на одной реплике, и
токен продолжит работать на остальных. Рестарт или отказ реплики
стирает её сессии, `make test-persistence` и `make test-failover`
упали бы. Sticky session это лишь маскирует и запрещена заданием.
Поэтому сессии в Postgres (общие для реплик, переживают рестарт), как
и ключи идемпотентности; в памяти процесса нет ничего, от чего зависит
корректность (раздел «Балансировщик и реплики»).