666 lines
50 KiB
Markdown
666 lines
50 KiB
Markdown
# План лабы 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>/`, `<aa>/`.
|
||
Раздел «Эксперименты и отказы» в `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 безопасно повторять;
|
||
- локальные сессии при росте числа реплик.
|