diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 60e609e9..78f01b03 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -16,7 +16,9 @@ HAProxy на `APP_OUT_PORT` перед репликами API) работают сессии по репликам, `kill-inflight` — kill реплики с запросами в полёте, `idle-conns` — кто закрывает простаивающие соединения LB → реплика и `hang-key` — повтор ключа после зависшей реплики. Только -стандартная библиотека Python. +стандартная библиотека Python 3.9+: `make instances` запускает драйвер +системным `python3` (на macOS — 3.9), поэтому без `datetime.UTC`, +`match` и прочего синтаксиса 3.10+. Все пути — от корня репозитория. Проверено на macOS (arm64), uv 0.12, Python 3.12 из `.python-version`, Docker Desktop 29.8. diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index 7d3605be..58df8bbf 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -43,6 +43,11 @@ stop остановить свой экземпляр на порту all start → flow → smoke → student (если есть student-tests/) → stop +Работает на python3 3.9+ (системный python3 macOS): `make instances` +вызывает его без uv. Отсюда `from __future__ import annotations` и +`timezone.utc` вместо `datetime.UTC` (3.11+, `noqa: UP017`: ruff +проекта целится в py312 и иначе вернул бы `datetime.UTC`). + Порт по умолчанию 18080, а не 8080: на 8080 обычно работает стенд `make run_docker` (HAProxy перед репликами API) или `make run_dev` пользователя, и их процессы трогать не надо. Экземпляр драйвера пишет в @@ -51,6 +56,8 @@ балансировщик (`--port 8080`). """ +from __future__ import annotations + import argparse import base64 import contextlib @@ -68,9 +75,11 @@ import urllib.error import urllib.request import uuid from collections import Counter -from datetime import UTC, datetime +from datetime import datetime, timezone from pathlib import Path +# datetime.UTC появился в 3.11, а драйвер работает и на python3 3.9 +UTC = timezone.utc # noqa: UP017 ROOT = Path(__file__).resolve().parents[3] DEFAULT_PORT = 18080 USERS = "/api/v1/users" diff --git a/PLAN.md b/PLAN.md deleted file mode 100644 index 80b7aa4e..00000000 --- a/PLAN.md +++ /dev/null @@ -1,667 +0,0 @@ -# План лабы 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 + 0 на реплику - (change `scaling-improvement`; было 10 + 5): граница — 10 реплик - (10 × 10 + 1 > 100), при 10 + 5 была 7. Граница пула показана - управляемым опытом серии `pool` трека 1 (на 10 + 5). -- Окружение по сервисам: пароль 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`. **Заархивирован 2026-10-11** (`openspec/changes/archive/2026-10-11-scaling-improvement/`; пул 10 + 0 вместо 10 + 5 (`9c3959d`), тест `test_pool_keeps_connections`; профиль `db4`; попытка 1 (`scaling-db-aa`, `-before`, `-nooverflow`) испорчена помехами хоста, попытка 2 (`scaling-db-aa2`, `-before2`, `-nooverflow2`, итоговый код `7a38c5d`): R* `4x1-pg0.5` 931 → 1 101, +18,3 %, «эффект», механизм 102 → 4 новых сессий; по букве критерия H4 проверка дрейфа нарушена на 0,4 п. п., засчитано с оговоркой решением пользователя — против A/A2 той же сессии дрейфа нет, +11,9 %; verify: порог × 1,118 в отчёте, дельта «Серии трека 1» (`db4`), побочная проверка LB в evidence) | -| 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* засчитывается со сдвигом не -меньше двух ступеней (× 1,118, +11,8 %; порог уточнён до замеров -`scaling-improvement`) или с явной оговоркой (`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 безопасно повторять; -- локальные сессии при росте числа реплик.