# План лабы 3 на «5» Рабочий документ на время лабы (составлен 2026-10-07). Пункты закрываются changes OpenSpec по порядку из раздела «Последовательность работ»; решение, принятое в design change, важнее этого плана. Когда change заархивирован, его строку здесь отметить; когда закрыты все — итоги перенести в `REPORT.md`, а файл удалить. Задание — `README.md`, переходы API — `COURSE.md` (2 → 3), семантика — `contracts/README.md`, раздел «Балансировка и повторная отправка». Код пока в состоянии лабы 2 (AGENTS.md, «Переходное состояние»). ## Что требует рубрика и чем закрываем | Уровень | Пункт рубрики | Как закрываем | Change | |---|---|---|---| | 3 | стенд одной командой, ≥2 API, одна точка входа, общие БД и сессии | compose: HAProxy → `api` × `API_REPLICAS` (по умолчанию 2) → Postgres и Valkey; сессии уже в Postgres | `replicas-lb` | | 3 | разные запросы одной сессии на разных репликах без повторного входа | round-robin без sticky, `X-Instance-Id` = hostname контейнера | `instance-id-idempotency`, `replicas-lb` | | 3 | отказ любой одной реплики: ≤10 с до новых чтений и записей | активные проверки HAProxy, повтор LB только на `conn-failure`, `scripts/stop-one.sh` | `replicas-lb` | | 3 | `Idempotency-Key`: без дублей при повторе, конкурентном повторе и смене реплики | таблица ключей в Postgres, запись ключа и сообщения в одной транзакции, гонку решает уникальный ключ | `instance-id-idempotency` | | 3 | `make test`, `make test-persistence`, `make test-failover` | `restart.sh` перезапускает и LB, и все реплики | `replicas-lb` | | 4 | health/readiness, таймауты, SIGTERM согласованы; период проверок и время обнаружения | таблица цепочки таймаутов (ниже), замер времени обнаружения | `graceful-failover` | | 4 | поочерёдная остановка каждой реплики: RPS, ошибки, время восстановления | профиль `failover` нагрузочного стенда: нагрузка с постоянной интенсивностью, остановка реплики посреди прогона, посекундная шкала | `graceful-failover` | | 4 | общая идемпотентность параллельными запросами с одним ключом | тест гонки в `student-tests/` через LB, ответы минимум двух реплик | `instance-id-idempotency`, `replicas-lb` | | 4 | лимиты CPU/RAM, порты API не наружу, секреты только где нужно, нет `container_name` | compose: `deploy.resources.limits` у всех сервисов, у `api` нет `ports`, окружение разделено по сервисам | `replicas-lb` | | 4 | rolling update под нагрузкой; миграции однократно и совместимы | `scripts/rolling-update.sh` (замена по одной реплике), миграции expand/contract | `rolling-update` | | 5 | трек 1 «Цена масштабирования» | раздел «Трек 5» ниже | `scaling-bench`, `scaling-improvement` | ## Ключевые решения Ниже предложения. Окончательное решение принимается в design соответствующего change. ### 1. Compose + HAProxy, без Swarm — подтверждено 2026-10-07 Выбор подтверждён пользователем 2026-10-07; обоснование ниже идёт в `REPORT.md` («Архитектура и решения») и в ответ на защите. - **HAProxy**, а не Nginx и не Traefik. Решают две вещи, которые нужны именно этой лабе: - активные проверки `/health/ready` с явным периодом (`inter`/`fall`/`rise`) — прямой ответ на требование уровня 4 назвать период проверок и время обнаружения отказа; - статистика по каждой реплике (stats-сокет/CSV) для трека 1: очередь, повторы, время ответа сервера, статус проверок. Кроме того, реплики находятся через DNS Docker (`server-template` + `resolvers`): масштабирование `--scale api=N` не требует правки конфига. - **Compose, а не Swarm.** Один хост. Swarm ничего не даёт без нескольких узлов, а сборку образа и его доступность узлам пришлось бы описывать отдельно (рубрика «3»). | Критерий | HAProxy | Nginx (бесплатный) | Traefik | Swarm | |---|---|---|---|---| | Активная проверка `/health/ready` с периодом | есть | нет: пассивная по живым запросам (`max_fails`/`fail_timeout`), активная — только в NGINX Plus | есть (healthcheck в labels) | healthcheck контейнера, грубее (`interval × retries`) | | Новые реплики после `--scale` без правки конфига | DNS Docker | `server ... resolve` с 1.27.3, раньше адреса читались один раз при старте | через docker socket | встроено | | Повтор только недошедшего запроса | `retry-on conn-failure` | по умолчанию POST не повторяется, если уже отправлен | retry middleware, семантику для POST надо проверять | повторов нет | | Статистика по репликам (трек 1) | встроена | только общие счётчики; по репликам — разбор access-лога | метрики Prometheus | нет | | Лишние привилегии | нет | нет | docker socket — почти root на хосте | — | | Переделка стенда лабы 2 | добавить сервис | добавить сервис | сервис и labels | `build` и `depends_on` не работают в `stack deploy`, migrate как `replicated-job`, образ доступен узлам, `config.toml` через `configs` | Чем платим за HAProxy: - свой язык конфигурации; - логи нужно направить в stdout (`log stdout`); - число слотов `server-template` фиксировано, берём с запасом под 8 реплик. Swarm дал бы встроенный rolling update (`update_config`), но этот плюс не окупает переделку стенда на одном хосте. Выбор LB почти не связывает остальной стенд: от него зависят только `haproxy.cfg` и сбор статистики в `bench/`. - Реплики — один сервис `api` с `deploy.replicas: ${API_REPLICAS:-2}`, без `container_name` и без `ports`. Наружу публикуется только LB: `127.0.0.1:${APP_OUT_PORT}`. - Повтор запроса в LB — только `retry-on conn-failure` с `option redispatch`: запрос до сервера не дошёл, повтор безопасен для любого метода. Повтор на `response-timeout`/`empty-response` запрещён: создание чата и регистрация не идемпотентны (контракт: «не добавляйте прозрачные повторы этих POST»). - Sticky session не используется (README, п. 3). ### 2. `X-Instance-Id` - Значение — hostname процесса. В compose это короткий ID контейнера: `stop-one.sh` сопоставляет `TARGET_INSTANCE_ID` контейнеру проекта без таблиц соответствия. Значение стабильно, пока жив процесс (контракт). - Поле `[app] instance_id` с дефолтом «hostname» оставляет место для непрозрачного alias в лабе 7. - Заголовок ставит тот же middleware, что `X-Request-Id`, и обработчик `Exception` в `errors.py` для 500 (`api-layer.md`). Тот же id идёт полем `instance_id` в каждую строку лога. ### 3. Идемпотентность — в Postgres, в транзакции сообщения - Таблица ключей: `(user_id, chat_id, key)` — первичный ключ; хэш тела, `message_id`, `created_at`. Область контракта «пользователь + метод + путь чата + ключ» сводится к `(user_id, chat_id, key)`: ключ принимает только `POST /chats/{chat_id}/messages`. - Порядок в `MessageService.send_message`: Bearer → членство (404) → ключ. Вставка ключа и сообщения — одна транзакция (решено в design `instance-id-idempotency`, решения 2–3): - ключ вставляется первым, внешний ключ на сообщение отложен до commit: повтор не пишет и не откатывает сообщение; - захват — `ON CONFLICT DO UPDATE … WHERE` ключ просрочен: новый и просроченный ключ захватываются одним выражением; - конкурентная вставка того же ключа на другой реплике ждёт commit первой и получает конфликт; - затем читается сохранённая запись. Хэш совпал — тот же 201 и то же `Message`, прочитанное по `message_id`. Хэш другой — 409 `conflict`. Откат транзакции (5xx) не оставляет ни ключа, ни сообщения: повтор выполнится заново. - Хэш — SHA-256 канонического JSON провалидированного тела (сортированные ключи). Порядок ключей не важен; `attachment_ids` появится в лабе 4 с дефолтом `[]`. - Срок 24 ч — `[idempotency] ttl_seconds` в `config.toml`. Это соответствие имени skeleton `IDEMPOTENCY_TTL_SECONDS`, описывается в `REPORT.md`. Ключ старше срока считается свободным: старая запись заменяется в той же транзакции. Фоновой уборки нет до worker лабы 5: ограничение и команда ручной очистки — в `REPORT.md`. - `Idempotency-Key` объявляется в ручке (`Header`, шаблон и длина по контракту) и попадает в `/openapi.json`. Нет ключа или ключ неверный — 400 через общий обработчик валидации. FastAPI проверяет параметры ручки после зависимостей, поэтому ожидаемый порядок 401 → 400 → 404 → 409. Закрепить его тестом. - В логах ключа нет (`logging.md`): только `message_id` и признак `replayed`. ### 4. Состояние процесса - Сессии уже в Postgres (лаба 2) и общие для реплик. Valkey — общий кэш карточек чатов. Карточки неизменяемы (состав чата не меняется), поэтому межрепличная инвалидация не нужна. - Пройти по `src/` и подтвердить, что в памяти процесса нет ничего, от чего зависит корректность. Ожидаемо там только кэш-пропуск после отказа Valkey и фиктивный хэш пароля. Итог проверки — в `REPORT.md`. ### 5. Миграции - Уже однократно: одноразовый сервис `migrate` до старта API. Реплики ждут `service_completed_successfully` и сами миграции не запускают. - Для rolling update миграция только расширяющая (expand/contract): новая таблица ключей не ломает работающую старую версию. Ограничение — в `REPORT.md`. ### 6. Цепочка таймаутов (стартовые значения) | Звено | Значение | Зачем | |---|---|---| | HAProxy check `/health/ready` | `inter 1s fall 2 rise 2`, `timeout check 1s` | отказ замечен ≤ ~3 с, вернувшаяся реплика — через 2 успешные проверки | | HAProxy `timeout connect` | 1 с, `retries 2`, `option redispatch` | при остановленной реплике запрос уходит на живую раньше 2-секундного таймаута клиента в `tests/resilience.py` | | HAProxy `timeout server` | 10 с | больше срока запроса к БД (`[database] request_timeout_seconds` = 6) и входа с KDF | | HAProxy resolvers | DNS Docker `127.0.0.11`, `hold valid` 1–2 с | новая и пропавшая реплика видны без перезагрузки LB | | uvicorn `timeout_graceful_shutdown` | 8 с | после SIGTERM сокет закрыт, текущие запросы дорабатывают | | compose `stop_grace_period` | 10 с | SIGKILL после graceful | | `stop-one.sh` | возврат ≤ 10 с | требование `tests/README.md` | Отказ при `docker stop`: реплика закрывает сокет, HAProxy получает отказ соединения и перенаправляет запрос, так что ошибок клиента нет. При `docker kill` запросы в полёте рвутся. Клиент повторяет их с тем же ключом, и идемпотентность не даёт дублей. Оба режима замеряются. ### 7. Ресурсы и пулы - Лимиты CPU/RAM у каждого сервиса стенда: api, haproxy, postgres, valkey, migrate. - Соединения Postgres: `API_REPLICAS × (pool_size + max_overflow)` + migrate + запас ≤ `max_connections`. Сейчас пул 10 + 5 на реплику: при 2–4 репликах запас есть, при 8 — уже нет (120 > 100). Это одна из гипотез трека 1. - Окружение по сервисам: пароль Valkey получает только `api`, `migrate` — только Postgres, LB — ни одного секрета (рубрика «4»: секреты общие только там, где нужно). ## Трек 5: предлагаю трек 1 «Цена масштабирования» **Почему трек 1.** - Стенд для него уже есть: `bench/` с k6, паспортами прогонов, сравнением меток с уровнем шума A/A (`make bench_compare`) и прогоном «до/после» (`make bench_ab`) из лаб 1–2. - Всё делается на одном ноутбуке честно: трек не заявляет устойчивость к потере хоста. **Почему не трек 2.** - Нужны ≥2 узла: несколько VM через Lima/Colima/Multipass и Swarm поверх них на одном ноутбуке. - Чтобы заявить выживание БД, нужна реплицированная PostgreSQL с настоящим failover (Patroni или потоковая репликация с переключением). - LB при этом остаётся SPOF. Объём и риск в разы больше при том же итоговом балле. ### Гипотезы 1. **Фиксированный бюджет.** При фиксированных 4 CPU / 4 ГБ на все API-реплики одна реплика использует около 1 CPU: один процесс uvicorn, один event loop. Поэтому RPS(1 × 4 CPU) ≈ RPS(1 × 1 CPU), а 2 × 2 и 4 × 1 дают рост почти пропорционально числу процессов, пока не упрёмся в Postgres или LB. 2. **Рост ресурсов.** Реплик k = 1, 2, 3, 4, 6, 8 по 1 CPU, Postgres фиксирован. Рост RPS остановится, когда Postgres выйдет на свой лимит CPU или на запись WAL и commit (точка насыщения). Дальше реплики только увеличат число соединений и p99. 3. **Граница пула.** Когда `k × (pool_size + max_overflow)` превысит `max_connections`, под нагрузкой появятся отказы подключения (503). До этой границы растёт ожидание свободного соединения в пуле. ### Методика - Стенд — проект `mtusi-bench`: тот же compose с HAProxy и N репликами. Лимиты всех контейнеров — поля `Profile`. Порядок работы с хостом прежний (`bench.md`): питание, swap, без посторонних контейнеров. - Предварительно: API суммарно 4 CPU, Postgres 2 CPU / 3 ГБ, HAProxy 1 CPU, Valkey 0,5 CPU. Генератор k6 ограничен 2 CPU, VM Docker — ≥10 CPU. Сумма записывается в паспорт. - Нагрузка — открытая модель: k6 `ramping-arrival-rate` ступенями до нарушения SLO (p95 > 200 мс или ошибок > 1 %). Результат — максимальная устойчивая интенсивность. Плюс фиксированные уровни для сравнения задержек. Закрытая модель (VU) из лаб 1–2 скрывает насыщение (coordinated omission), поэтому для поиска точки насыщения не годится. - Профиль один для всех конфигураций: - 70 % — страница истории; - 20 % — запись сообщения с `Idempotency-Key`; - 10 % — `GET /users/me`. Вход по Basic (Argon2id) в замер не входит: токены готовятся до прогона. Иначе KDF доминировал бы над всем профилем. - 3 повтора каждой конфигурации, порядок перемешан, прогрев перед каждым. В отчёт идут медиана и разброс. - Метрики: - успешные RPS, ошибки по кодам, p50/p95/p99; - CPU/RAM каждого контейнера; - распределение ответов по `X-Instance-Id`; - HAProxy: очередь, повторы, время ответа сервера; - Postgres: commit/s, соединения по `wait_event`, число соединений. - Серии: - A — фиксированный бюджет 1 × 4, 2 × 2, 4 × 1; - B — рост реплик 1…8 по 1 CPU; - для улучшения — пара «до/после» с A/A. - Графики: - RPS от числа реплик (A и B); - p95 от интенсивности; - CPU по компонентам. SVG рисуется скриптом на stdlib из `runs.csv`, без новых зависимостей `bench/`. Сырые данные — в `evidence/bench/<метка>/`. ### Одно подтверждённое улучшение Выбирается по найденному узкому месту и подтверждается через `make bench_ab` с A/A. Кандидаты по вероятности: 1. Размер пула на реплику так, чтобы суммарно соединений было не больше, чем Postgres переваривает. Меньше соединений — меньше конкуренции. 2. Запись сообщения одним SQL-выражением (CTE: ключ + сообщение) вместо нескольких round-trip. 3. uvloop/httptools в uvicorn — дешевле CPU на запрос. 4. PgBouncer в transaction-режиме перед Postgres — если упрёмся в число соединений. ### Ограничения, которые заранее назвать - Генератор, LB, API и БД делят один хост. - Docker Desktop — VM. - Результаты относятся к этому ноутбуку и этому профилю. Устойчивость к потере хоста, LB и БД не заявляется (`COURSE.md`, «честные измерения»). ## Последовательность работ Этапы 1–6 — changes OpenSpec, каждый проходит `/opsx:propose` → `/opsx:apply` → `/opsx:verify` → `/opsx:archive`. Этап 7 — сборка отчёта, не change. Замеры для отчёта снимаются с закоммиченного кода (`bench.md`, «Измеренное состояние — commit»). Отчёт пополняется в каждом change, как в лабе 2: evidence и строка в таблице доказательств `REPORT.md` — часть «готово». ### Сводная таблица | № | Change | Уровень | Что происходит | Готово, когда | |---|---|---|---|---| | 0 | — (подготовка) | — | Правила, `AGENTS.md`, этот план. Ветка `solution/bvt2301-safronov` до первого коммита | сделано 2026-10-07 | | 1 | `instance-id-idempotency` | 3 (+4: гонка одного ключа) | Переименование стенда в `mtusi-lab3`. `X-Instance-Id` на каждом ответе и `instance_id` в логах. Таблица ключей, `Idempotency-Key` в ручке, сервисе и repo: повтор → тот же 201, другое тело → 409. Ключ добавляется во все свои клиенты: тесты, k6, драйвер скилла | `make test_isolated` (smoke lab3 + свой набор), `make failure_checks`, `make bench_quick` зелёные на одном процессе. **Код реализован 2026-10-08** (`/opsx:apply`); осталось: общая проверка, коммит, evidence, `REPORT.md`, verify и archive | | 2 | `replicas-lb` | 3 (+4: лимиты, порты, секреты, гонка через реплики) | HAProxy — единственная точка входа, `api` × `API_REPLICAS` без портов, лимиты CPU/RAM у всех, секреты по сервисам. `restart.sh` с LB, новый `stop-one.sh`. Тесты против стенда с LB | `make test`, `make test-persistence`, `make test-failover` через LB для каждой реплики; гонка ключа видит ≥2 реплики. **Заархивирован 2026-10-10** (`openspec/changes/archive/2026-10-10-replicas-lb/`; verify — решение 14 design: формула обнаружения зависшей реплики `fall × (inter + timeout check)` = 8 с, цена лимита 1 CPU для Argon2id, evidence снято заново с `a4ca9ef`) | | 3 | `graceful-failover` | 4 | Цепочка таймаутов зафиксирована и обоснована. Замер времени обнаружения отказа при `stop` и `kill`. Стенд `bench/` переходит на HAProxy + N реплик, профиль `failover`: поочерёдная остановка каждой реплики под нагрузкой | посекундные RPS, ошибки и время восстановления по каждой реплике в `evidence/failover/`, таблица таймаутов в `REPORT.md`. **Заархивирован 2026-10-11** (`openspec/changes/archive/2026-10-11-graceful-failover/`; замер `evidence/failover/baseline/` с `459f84c`; verify — решение 10 design: отвергнутый вариант пула LB переснят на закоммиченном коде, уборка триггера `hang-key` при прерывании, `make bench_compare` отказывает метке без LB; дренаж до SIGTERM и `make run_docker` без пересоздания реплик переданы в `rolling-update`, ниже) | | 4 | `rolling-update` | 4 | `scripts/rolling-update.sh`: замена реплик по одной на новый образ под нагрузкой. Миграции однократно и совместимы со старой версией | прогон под нагрузкой с ошибками по секундам в `evidence/rollout/`; старый образ работает на новой схеме. **Заархивирован 2026-10-11** (`openspec/changes/archive/2026-10-11-rolling-update/`; замер `evidence/rollout/baseline/` с `9dcea0b`, итоговый код `84161c0`; verify — решение 12 design: уборка при Ctrl+C внутри `up --scale`, предусловие о слотах LB с ручным состоянием, `lock_timeout` миграции 2 с вместо 5 с (при равном `statement_timeout` запросы в очереди за миграцией получали 503), ограничение отката; совместимость и отказы скрипта пересняты на `84161c0`) | | 5 | `scaling-bench` | 5 (трек 1) | Открытая модель нагрузки, серии A (фиксированный бюджет 1×4 / 2×2 / 4×1) и B (1…8 реплик), метрики HAProxy и Postgres, графики, точка насыщения | метки серий и A/A в `evidence/bench/`, точка насыщения и её причина в `REPORT.md`. **Заархивирован 2026-10-11** (`openspec/changes/archive/2026-10-11-scaling-bench/`; метки `scaling-a`, `-b`, `-pool`, `-aa` на коде `712d245`, серия B — до 6 реплик (бюджет ВМ); verify: 53300 → 503 (`68edc66`), выводы H1 и k_sat переписаны по критериям и разрешению сетки, причина насыщения — хост, механизм не разделён; по решению пользователя (S2) — серия `scaling-db`: при PostgreSQL 0,5 CPU R* 630 → 1 101 → 931 для 1 / 2 / 4 реплик; A/A улучшения — заново на коде «до») | | 6 | `scaling-improvement` | 5 (трек 1) | Одно улучшение на найденном узком месте, «до/после» через `make bench_ab`, отделение эффекта от шума | `evidence/compare/` с эффектом больше шума A/A, вывод в `REPORT.md` | | 7 | — (отчёт и PR) | 3–5 | Сводка `REPORT.md`, проверка из чистого clone, шаблон PR, уборка переходных разделов | PR `ЛР 3 — БВТ2301 — Сафронов — на 5` | Код лабы 2 (`bench_restore`, проверки отказов хранилищ, кэш) должен продолжать работать после каждого change: возможности прежних лаб сохраняются (README, «Что должно быть в PR»). ### 1. `instance-id-idempotency` — уровень 3, +4 **Пункты рубрики.** - «3»: повтор `POST` с тем же `Idempotency-Key` не создаёт дубль; неподтверждённую запись можно повторить. - Основа для «разные реплики видно по `X-Instance-Id`». - «4»: идемпотентность под параллельными запросами с одним ключом, пока на одном процессе. **Стенд — первая задача, до любого запуска.** - Имя проекта `mtusi-lab3`, образ `mtusi-messenger:lab3` в `docker-compose.yml`. - Упоминания lab2 в `Dockerfile`, `pyproject.toml`, `student-tests/failures.compose.yml`. **Код.** - `[app] instance_id`: пусто → hostname при старте. - Middleware ставит `X-Instance-Id` рядом с `X-Request-Id`, обработчик 500 в `errors.py` — сам. - `instance_id` в каждой записи лога и в строке старта. - `[idempotency] ttl_seconds` = 86400; строка в `config_example.toml`. - Миграция таблицы ключей: - PK `(user_id, chat_id, key)`; - FK на пользователя, чат и сообщение; - хэш тела, `created_at`; - `CHECK` длины ключа, индекс по `created_at`. - Модель, repo `idempotency.py`: захват `ON CONFLICT DO NOTHING`, чтение сохранённой записи. - `MessageService.send_message(..., idempotency_key)`: - порядок: членство → захват ключа → сообщение → один `commit`; - повтор отдаёт сохранённое сообщение из БД; - другой хэш → `IdempotencyConflict` → 409; - просроченный ключ заменяется. - Ручка: `Idempotency-Key` как `Header` с шаблоном из `src/utils/constants.py`. **Свои клиенты API начинают слать ключ** (иначе после change получат 400): - `student-tests/api_client.py`; - `bench/k6/lib.js` — профили `bench`, `bench_restore`; - `driver.py` скилла `run-mtusi-messenger`. **Спеки (дельты).** - `api-conventions`: «`X-Instance-Id` на каждом ответе». - `messages`: «Отправка сообщения» требует ключ. - Новая `idempotency`: повтор, другое тело, область пользователь/чат/ключ, конкурентный повтор, транзиентная ошибка, срок 24 ч, повтор проверяет сессию и доступ. - `service-configuration`: `instance_id`, срок ключа. - `service-logging`: `instance_id`; ключ не логируется. **Тесты** (`student-tests.md`, раздел лабы 3): - `X-Instance-Id` на успехе, ошибках, health, 404 и 405; - повтор — тот же JSON, другое тело — 409, ключ 400-х форм; - область пользователь/чат; - порядок ключей JSON; - отозванный токен — 401, посторонний — 404; - порядок кодов 401 → 400 → 404 → 409; - гонка одного ключа за `threading.Barrier`. **Evidence:** `evidence/idempotency/` (повтор, 409, гонка, строки таблицы ключей), `evidence/tests/`. ### 2. `replicas-lb` — уровень 3, +4 **Пункты рубрики.** - «3»: - стенд одной командой, ≥2 реплики, одна точка входа, общие БД и сессии; - запросы одной сессии на разных репликах без повторного входа; - отказ одной реплики — ≤10 с до новых чтений и записей; - `make test`, `make test-persistence`, `make test-failover`. - «4»: лимиты CPU/RAM, порты API не наружу, секреты только где нужно, нет `container_name`. **Стенд** (`balancer.md`): - Сервис `haproxy`: пин тега и digest, `infra/haproxy/haproxy.cfg` read-only. Внутри: `server-template` через DNS Docker, `httpchk` на `/health/ready`, `roundrobin` без sticky, `retry-on conn-failure` + `redispatch`, stats только внутри сети. - `api`: `deploy.replicas: ${API_REPLICAS:-2}`, без `ports` и `container_name`; строка `API_REPLICAS=2` в `.env.example`. - `deploy.resources.limits` у всех сервисов. - Окружение по сервисам: `migrate` без пароля Valkey, LB без секретов. **Скрипты и Makefile.** - `scripts/restart.sh`: ещё LB и все реплики. - Новый `scripts/stop-one.sh`: - `TARGET_INSTANCE_ID` → контейнер `api` этого проекта, иначе отказ; - `STOP_MODE=stop|kill`; - возврат ≤10 с, реплика остаётся остановленной. - Цели Makefile: восстановить реплики, изменить их число, показать распределение по `X-Instance-Id`. - `make test_isolated` и `make failure_checks` сверить с новым compose: у них свои API, без LB. - Скилл `run-mtusi-messenger`: раздел «контейнер» — под LB и реплики. **Спеки (дельты).** - `container-run`: запуск через compose с LB; на localhost публикуется только LB. - Новая `load-balancing`: одна точка входа, ≥2 реплики, без sticky, проверка готовности, повтор только при отказе соединения, отказ одной реплики ≤10 с, failover hook. - `student-tests`: тесты реплик против стенда с LB. **Тесты.** - Распределение одной сессии по ≥2 `X-Instance-Id`. - Гонка одного ключа требует ответов ≥2 реплик (против одного процесса — пропуск с причиной). **Evidence.** - `evidence/replicas/`: `docker compose ps` — порты только у LB; лимиты из `docker inspect`; распределение запросов. - `evidence/failover/`: `make test-failover` для каждой реплики, `docker compose ps` и `StartedAt` до и после, ID остановленного = `TARGET_INSTANCE_ID`. - `make test-persistence` с рестартом и LB. ### 3. `graceful-failover` — уровень 4 **Пункты рубрики «4».** - Health/readiness, таймауты и SIGTERM согласованы; LB исключает недоступный backend. - Назван период проверок и максимальное время обнаружения. - Поочерёдная остановка каждой реплики с восстановлением предыдущей: RPS, ошибки, время восстановления. **Конфигурация.** - Цепочка таймаутов («Ключевые решения», п. 6) — в `haproxy.cfg`, `config_example.toml`, compose. Соотношения из `balancer.md` проверены. - Таймаут проверки внутри `/health/ready` меньше `timeout check`. **Замер обнаружения.** - Для `stop` (SIGTERM, graceful) и `kill` (SIGKILL). - Момент действия → реплика `DOWN` в статистике HAProxy → первый успешный ответ после. - Формула сверяется с замером. Для зависшей реплики это `fall × (inter + timeout check)`, а не `inter × fall + timeout check`: так исправлено в verify `replicas-lb` (design, решение 14), замер `docker pause` — 7,7 с. **Стенд `bench/`.** - Переходит на тот же compose с HAProxy и N репликами. При N = 1 прежние профили лабы 2 работают как раньше. - Новый профиль `failover` (`make bench_failover`): - k6 с постоянной интенсивностью: запись с ключом и чтение; - по расписанию остановка реплики i, восстановление, следующая; - режимы `stop` и `kill`; - посекундные успешные RPS и ошибки по кодам; - время восстановления до доли успеха ≥99 %. **Спеки (дельты).** - `graceful-shutdown`: остановка реплики за LB — закрытый сокет, перенаправление, без ошибок клиента при `stop`. - `load-balancing`: время обнаружения. - `load-benchmark`: стенд с LB, профиль `failover`. **Evidence:** `evidence/failover/<метка>/` (шкала по каждой реплике, `stop` и `kill`), таблица таймаутов и замер обнаружения в `REPORT.md`. ### 4. `rolling-update` — уровень 4 **Пункты рубрики «4».** - Rolling update или эквивалентная поочерёдная замена под нагрузкой. - Миграции однократно и совместимы с работающей версией (либо ограничение описано). **Скрипт** `scripts/rolling-update.sh` и цель Makefile (как сделано — design change, решение 1: сборка раньше миграций, миграция в контейнере сервиса `migrate`, а не `run --rm`): 1. Миграции один раз (`run --rm migrate`). 2. Сборка нового образа. 3. `--scale api=N+1 --no-recreate`: одна новая реплика рядом со старыми. 4. Ждать `healthy` и появления в HAProxy. 5. `stop` + `rm` одной старой. 6. Шаги 3–5 N раз. **Демонстрация.** - Замена с одного коммита на другой: безвредное совместимое изменение, выбирается в design. - Профиль `rollout` стенда `bench/` с постоянной интенсивностью. - Отдельно: старый образ проходит smoke на схеме после новой миграции. **Спеки (дельты).** - `load-balancing`: поочерёдная замена без потери записей. - `db-migrations`: совместимость с работающей версией (expand/contract), однократный запуск при замене. **Evidence:** `evidence/rollout/` (ошибки по секундам, какие контейнеры и образы до и после). **Передано из `graceful-failover`** (design, решение 10; архив `openspec/changes/archive/2026-10-11-graceful-failover/`): - **Дренаж до SIGTERM.** При `docker stop` под нагрузкой остаётся одиночный 502 (гонка keep-alive: uvicorn закрывает простаивающие соединения, LB в тот же миг шлёт в одно из них запрос) — 1 из 4 фаз `stop`. Шаг 5 скрипта должен сначала вывести старую реплику из LB и дождаться конца её запросов, потом `docker stop`. Варианты: runtime API HAProxy (`set server api/<слот> state drain`; нужен admin-сокет внутри сети, слот искать по адресу контейнера, как `lb_stats`) или readiness 503 по сигналу (меняет спек `graceful-shutdown`). Срок: вывод из LB ≤ 1,5 с по проверкам (`inter` + `fastinter`) + до 8 с graceful — больше 9 с `stop-one.sh`, поэтому дренаж — в `rolling-update.sh`, а не в hook. - **`make run_docker` не пересоздаёт работающие `api`** после пересборки образа — `KNOWN_ISSUES.md`. - **Таймауты для поочерёдной замены:** новая реплика попадает в LB через ≤ 1,5 с после готовности (`init-state down`, `rise 2`, `downinter` 1 с + `fastinter` 0,5 с) — шаг 4 ждёт `UP` в статистике LB, а не только `healthy` контейнера. `http-reuse never`: соединения с репликой принадлежат сеансам клиентов, клиент k6 с keep-alive держит соединение с уходящей репликой до её закрытия. `stop_grace_period` 10 с, `graceful_shutdown_seconds` 8 с. - **Профиль `rollout` стенда `bench/`** строится по образцу `failover` (`bench/run.py`, `bench/failover.py`, `k6/failover.js`, `k6/retry.js`): постоянная интенсивность, строка k6 на запрос, посекундная шкала, повтор неуспешных записей с тем же ключом и сверка. Метки в `evidence/rollout/<метка>/`, пробные — в `.gitignore`. `make bench_compare` метки без LB уже не сравнивает. ### 5. `scaling-bench` — уровень 5, трек 1 **Пункты рубрики «5».** - Сравнение 1/2/4 реплик при фиксированном суммарном CPU/RAM. - Серия с ростом ресурсов. - Точка насыщения БД/LB/пула и почему рост реплик перестаёт помогать. - Исходные данные и графики. **До прогонов.** - Гипотезы раздела «Трек 5» коммитятся отдельно, как в лабе 2. - Подготовка хоста по `bench.md`, CPU VM Docker — в паспорт. **Стенд `bench/`.** - Поля `Profile`: CPU/RAM реплики, Postgres, HAProxy, Valkey, k6; число реплик. - Открытая модель: `ramping-arrival-rate` ступенями до нарушения SLO (p95 > 200 мс или ошибок > 1 %), плюс фиксированные уровни. - Смешанный профиль 70/20/10; токены готовятся до прогона. - 3 повтора, перемешанный порядок, прогрев. **Метрики.** - Добавляются: распределение по `X-Instance-Id`, статистика HAProxy (очередь, повторы, время сервера), Postgres (commit/s, соединения по `wait_event`). - CPU/RAM каждого контейнера. - Новые столбцы `runs.csv` — в конец. **Серии.** - A: 1 × 4 CPU, 2 × 2, 4 × 1. - B: 1, 2, 3, 4, 6, 8 реплик по 1 CPU. - A/A для уровня шума. - Быстрый профиль для самопроверки. **Графики** — SVG скриптом на stdlib из `runs.csv`: - RPS от числа реплик; - p95 от интенсивности; - CPU по компонентам. **Спеки (дельты).** `load-benchmark`: стенд с N репликами, открытая модель, серии A/B, метрики LB и Postgres, графики, точка насыщения в отчёте. **Evidence:** `evidence/bench/<серия-a>/`, `<серия-b>/`, `/`. Раздел «Эксперименты и отказы» в `REPORT.md`: гипотезы против результата, точка насыщения и её причина. ### 6. `scaling-improvement` — уровень 5, трек 1 **Пункт рубрики «5»:** одно подтверждённое улучшение. **Выбор.** Решение — по узкому месту, найденному в этапе 5. Кандидаты — «Трек 5», «Одно подтверждённое улучшение»: - размер пула на реплику; - запись одним SQL; - uvloop; - PgBouncer. **Порядок** (`bench.md`, «Сравнение меток»): 1. Изменение закоммичено, проверено тестами и откачено отдельным commit. 2. `make bench_ab BEFORE=... AFTER=... REAPPLY=...`. 3. `make bench_compare` с `AA`. Эффект засчитывается, только если он больше шума и разбросы не пересекаются. Ячейки, которые изменение не затрагивает, показываются как контроль. **A/A — заново, на коде `BEFORE`** (verify `scaling-bench`, W8). Метка `scaling-aa` снята на коде `712d245`, а правка 53300 (`68edc66`) изменила `src` после неё. Шум допустим только между метками одного кода приложения (`bench.md`), поэтому `AA=scaling-aa` для улучшения не годится: свою A/A (`make bench_scaling SERIES=ab SCALING_LABEL=…` на коде «до») снимает этот change. Шум по `scaling-aa` — 5,4–5,7 %, одна ступень сетки поиска (≈ 5,7 %); эффект R* засчитывается со сдвигом не меньше двух ступеней (≥ 12 %) или с явной оговоркой (`bench.md`). Кандидат по данным `scaling-bench` (verify S8): переполнение пула. На R* при k ≥ 2 PostgreSQL открывает 168–298 новых соединений за окно 20 с (`db_sessions_new`, `scaling-b`): вероятно, сверх `pool_size` 10 соединения закрываются при возврате и открываются заново (процесс PostgreSQL и SCRAM на каждое). Сравнить пул 15 + 0 с 10 + 5 на 6 × 1. **Спеки (дельты)** — по выбранному улучшению: `data-storage` (пул), `messages` (запись), `service-configuration` (параметры). **Evidence:** `evidence/compare/<до>__<после>.md`, раздел в `REPORT.md`: что, почему, насколько, при каких условиях. ### 7. Отчёт и PR — не change - `REPORT.md`: - запуск из чистого clone; - архитектура и соответствие переменных `.env.example`; - таблица доказательств по каждому пункту 3/4/5; - согласования с преподавателем; - ограничения: что стенд не переживает; - ответы на вопросы защиты; - ИИ и источники. - Проверка сборки и `make test` из настоящего `git clone`. - Шаблон PR: заголовок `ЛР 3 — БВТ2301 — Сафронов — на 5`. - Уборка: - удалить `PLAN.md` и раздел «Переходное состояние» в `AGENTS.md`; - `graphify update .`. ## Риски и что проверить заранее - **`docker kill` и restart policy.** Не поднимет ли `restart: unless-stopped` реплику после `docker kill`? Тест требует, чтобы остановленная реплика оставалась остановленной. Проверить в change 2; при необходимости `stop-one.sh` делает `docker stop -t 0`. - **Адрес остановленного контейнера.** Подключение к нему может висеть до `timeout connect`, а не получать мгновенный отказ. Отсюда `timeout connect` 1 с и redispatch; проверить замером. - **CPU хоста.** Сумма лимитов стенда и генератора больше числа ядер VM Docker. Перед сериями трека 1 выставить CPU VM и записать в паспорт. - **Рост таблицы ключей.** Без фоновой уборки таблица растёт. Ограничение описать, ручную очистку дать командой. - **Время прогонов.** Серии A + B × 3 повтора — порядка часа. `bench_quick`-аналог для самопроверки обязателен. ## Защита (README, «Сценарий защиты») 1. `make run_docker`, затем ≥2 разных `X-Instance-Id` через LB с одним токеном (`for i in 1..6: GET /users/me`). 2. `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`. Показать `docker compose ps`: какой контейнер остановлен, его ID совпадает с `TARGET_INSTANCE_ID`. Восстановить, повторить для второй реплики. 3. `make test-persistence ACTION_SCRIPT=scripts/restart.sh`: тот же токен после рестарта всего стенда, volumes сохранены. 4. Уровень 4: шкала failover-серии, rolling update под нагрузкой, таблица таймаутов. Уровень 5: графики серий A/B, точка насыщения и её причина, улучшение с A/A. Ответы на вопросы README готовить в `REPORT.md` по ходу changes: - отказ процесса и отказ узла; - `depends_on`/healthcheck — не балансировщик; - какие POST безопасно повторять; - локальные сессии при росте числа реплик.