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>
98 KiB
Отчёт — лабораторная 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):
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) — в формате ошибки контракта с
codeunavailable,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):
- Предусловия — ничего не меняют, иначе код 2 и подсказка
make replicas:- работает ровно
API_REPLICASреплик, остановленных нет; - все
UPв LB; - для ещё одной реплики есть слот (≤ 8);
- канал управления LB отвечает;
- нет слотов в ручном
drain/maint, оставленных прерванной заменой (их не видно вmake lb_stats, скрипт читаетshow servers state); иначе он печатает команду, которая вернёт слот вready.
- работает ровно
- Сборка образа из рабочего дерева.
COMMIT=<commit>— из файлов commit черезgit archive <commit> | docker build, рабочее дерево не трогается. - Миграции — один раз, в контейнере сервиса
migrate, на новом образе, до первой новой реплики. Ошибка (в том числеlock_timeout) — код 1, реплики не тронуты. - Одна новая реплика рядом со старыми:
up -d --no-deps --no-recreate --scale api=N+1 api. - Ожидание готовности новой:
healthyиUPв статистике LB по её адресу. Слот получает адрес из DNS и начинает вDOWN, в распределение попадает через ≤ 1,5 с проверок. Вывести старую по одномуhealthy— значит на эти 1,5 с остаться с N − 1 репликами. - Вывод старой из LB и удаление:
- runtime API HAProxy:
drain— новых запросов нет, начатые дорабатывают; - ожидание, пока запросов в полёте не станет 0 (≤ 12 с, больше
timeout server); maint,docker stop(graceful, ≤ 10 с; код выхода — в строке скрипта),docker rm;- когда адрес ушёл из слота —
ready.
- runtime API HAProxy:
- Шаги 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) — одна транзакция:
- Сессию проверила зависимость (401), сервис проверяет членство (404) — и при повторе тоже.
- Захват ключа одним выражением:
INSERT … ON CONFLICT (user_id, chat_id, key) DO UPDATE … WHERE created_at < now − ttl RETURNING. Строка вернулась — ключ свободен (новый или просроченный, заменён тем же выражением): вставка сообщения,commit(). - Ключ занят — чтение сохранённого хэша и сообщения,
commit()(снять блокировку строки). Хэш совпал — тот же 201 и то жеMessageиз БД; не совпал — 409conflict.
Почему это корректно, в том числе между репликами (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,kill1, 2,pause1, 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 connect0,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: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с changegraceful-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 check2,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(designgraceful-failover, решение 2). - Оборванный ответ при
kill. Запросы в полёте на убитой реплике получают 502 от LB, LB их не повторяет (они уже дошли). Отправку сообщения клиент повторяет с тем же ключом; другиеPOST— на усмотрение клиента, прозрачных повторов контракт не допускает. Воспроизводится командойdriver.py --port 8080 kill-inflight. - Отказ PostgreSQL выводит из LB все реплики сразу.
/health/readyпроверяет PostgreSQL, поэтому через 1–2 с после его отказа на всё, включая/health/live, отвечает сам HAProxy: 503unavailableв формате контракта — тот же код, что отдал бы 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-alive10 с < 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, changerolling-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_timeout2 с. Под тяжёлой записью или во время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 меняет
реплики по одной:
- одна новая рядом со старыми;
- ожидание её
UPв LB; - старая выводится из 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 (общие для реплик, переживают рестарт), как
и ключи идемпотентности; в памяти процесса нет ничего, от чего зависит
корректность (раздел «Балансировщик и реплики»).