# Отчёт — лабораторная 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 отвечает. 1. **Сборка образа** из рабочего дерева. `COMMIT=` — из файлов commit через `git archive | 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` за срок — она удаляется. Её слот, если DNS уже отдал его, сначала уходит в `maint`. Новая уже `UP` (в том числе при Ctrl+C) — вывод текущей старой доводится до удаления. В любом исходе работает `API_REPLICAS` готовых реплик, слоты без ручного состояния, повторный запуск доводит замену (`evidence/rollout/script-failures.md`). Автоматического отката нет. Откат — та же замена на образ прежнего commit без миграций: `make rolling_update COMMIT= MIGRATE=0`. **Миграции однократны и совместимы с работающей версией** (expand / contract): - ревизия только расширяет схему: новая таблица, колонка с NULL или значением по умолчанию, индекс; - удаление и переименование — отдельной поставкой, когда прежнего кода не осталось. Демонстрация — колонка `messages.instance_id` (`text NULL`, ревизия `e656d6bbe1a4`): реплика, записавшая сообщение. Наружу она не отдаётся, контракт не меняется: - новый код её пишет, без неё упал бы, поэтому миграция обязана идти до новых реплик; - прежний код её не знает: вставляет свои колонки (NULL), читает свои. Первой строкой ревизии — `SET LOCAL lock_timeout = '5s'`. `ADD COLUMN` берёт `ACCESS EXCLUSIVE` на миллисекунды, но, пока ждёт блокировку, за ним в очереди стоят все запросы к `messages`. Чужая долгая транзакция без срока остановила бы запись всех реплик. Со сроком миграция падает без изменений, замена не начинается, повтор проходит. Проверено на рабочем стенде (`evidence/rollout/compatibility.md`): - реплики образа `c50b721` (до change) на схеме после новой миграции проходят `make test` и `make student_test` (131 passed); - `make rolling_update`, откат `COMMIT=c50b721 MIGRATE=0` и снова вперёд — под `tests/load.py`, 0 неуспешных запросов из 20–25 тысяч на каждый прогон; - по колонке видно, какая версия записала каждое сообщение. **`make run_docker` и пересборка.** Пункт `KNOWN_ISSUES.md` «не пересоздаёт работающие `api`» не воспроизвёлся (`evidence/rollout/compatibility.md`, шаг B): - 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`; на рабочем стенде — `make rolling_update`, откат `COMMIT=c50b721 MIGRATE=0` и снова вперёд под `tests/load.py` | замена 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 неуспешных из 25 347 / 20 114 / 20 713 / 19 199 запросов `tests/load.py` за четыре замены; контейнеров прежних реплик после замены нет | `evidence/rollout/baseline/summary.md`, `evidence/rollout/compatibility.md` | | «4»: миграции однократно и совместимы с работающей версией | реплики образа `c50b721` + `docker compose run --rm 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; откат кода без отката схемы; под чужой транзакцией `lock_timeout` 5 с → миграция падает с кодом 1, схема и реплики не тронуты, повтор проходит | `evidence/rollout/compatibility.md`, `evidence/rollout/script-failures.md` | | Замена при сбое и неготовом стенде | остановленная реплика, `API_REPLICAS=3`, `ROLLOUT_READY_TIMEOUT=1`, Ctrl+C во время дренажа под нагрузкой, порт 9999 LB из сети | код 2 до сборки; неготовая новая реплика удалена, работают 2 реплики `UP`; после Ctrl+C вывод старой доведён до удаления (код 130, 0 неуспешных запросов), повтор довёл замену; слоты LB без ручного состояния; канал управления LB из сети — отказ соединения | `evidence/rollout/script-failures.md` | | `make run_docker` после пересборки | реплики на образе прежнего commit, `docker compose build api`, `docker compose --dry-run up -d`; пересборка без изменений кода | compose пересоздаёт реплики с изменившимся образом, без изменений — не трогает; пункт `KNOWN_ISSUES.md` не воспроизвёлся и закрыт | `evidence/rollout/compatibility.md` | | Регрессия на итоговом коде `rolling-update` | `make test`, `make student_test`, `make test-persistence`, `make test-failover` (`stop` и `kill`), `make test_isolated`, `make failure_checks`, `make bench_quick`, `make bench_failover_quick`, `make bench_rollout_quick` | всё код 0 (131 passed через LB, 127 + 4 пропуска в изоляции, 15 проверок отказов); регрессия нашла дефект шага миграций (контейнер `migrate` прежнего образа ломал `restart.sh`), исправлен в `de654a1` и переснят | `evidence/tests/rolling-update-checks.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 неуспешных из 25 347, 20 114 и 20 713 запросов; замена 10–14 с; новая миграция при прежних репликах — `make test` и `make student_test` проходят | простоя нет; по `messages.instance_id` видно, какая версия что записала (`evidence/rollout/compatibility.md`) | ### Отказ каждой реплики под нагрузкой (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` до и после одинаковы). Посторонних контейнеров нет, рабочий стенд остановлен. Один прогон. **Результат** (`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`: его миграции не знают новой ревизии, поэтому шаг пропускается явно, а схема остаётся новой. - **Contract-миграции нет в этой поставке.** Удалить или переименовать колонку можно только отдельной миграцией, когда кода, который её пишет, не осталось. `downgrade` новой ревизии удаляет колонку и допустим только тогда же. - **`lock_timeout` 5 с.** Под тяжёлой записью миграция может не дождаться блокировки и упасть. Тогда замена не начинается, повтор проходит. Это осознанный выбор: иначе очередь всех записей ждала бы за миграцией. - **Сборка образа идёт на том же хосте, под нагрузкой.** Из кэша слоёв — секунды 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 (общие для реплик, переживают рестарт), как и ключи идемпотентности; в памяти процесса нет ничего, от чего зависит корректность (раздел «Балансировщик и реплики»).