Files
mtusi2026lab3/REPORT.md
T

289 lines
59 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 3
- Автор, группа: Боданюк Алексей, БВТ2302
- Целевая оценка: **5**, трек 1 «Цена масштабирования»
- Ветка: `solution/bvt2302-bodanyuk`. Форк: `https://gitea.privcloud.tech/wfa/mtusi2026lab3`. PR: «ЛР 3 — БВТ2302 — Боданюк — на 5» в mtusi2026/mtusi2026lab3
- Стек: Python 3.13.16, Starlette 1.7.0, uvicorn 0.54.0, psycopg 3.3.6 + psycopg-pool 3.3.3, redis-py 8.1.0, argon2-cffi 25.1.0; PostgreSQL 18.6, Valkey 8.1.3, HAProxy 3.2.26 (LTS); замеры — k6 2.3.0, py-spy 0.4.2. Все образы закреплены по тегу **и** digest, все Python-пакеты — по sha256 ([requirements.txt](requirements.txt), [bench/track1/pyspy/requirements.txt](bench/track1/pyspy/requirements.txt))
- Источники: README, COURSE, контракт ([openapi.json](contracts/openapi.json), [семантика](contracts/README.md)), документация HAProxy 3.2 (server-template, resolvers, http-check, retry-on, http-error), Docker Compose (deploy, networks), PostgreSQL (INSERT … ON CONFLICT, PL/pgSQL, pg_stat_statements, libpq keepalives/tcp_user_timeout), psycopg 3 (pool, autocommit), k6 (constant-arrival-rate, dropped_iterations). Учтены все замечания преподавателя к PR lab3 и lab2 других студентов ([раздел ниже](#проверки-на-которых-ловили-другие-работы)); мой PR lab2 (#42) принят без замечаний
- Помощь ИИ: код, тесты, скрипты экспериментов и черновик отчёта написаны с помощью ИИ-ассистента Claude Code (Anthropic). Все команды и замеры реально выполнены на стенде ниже; вывод — в [evidence/](evidence/). Ответы на вопросы защиты — [docs/DEFENSE.md](docs/DEFENSE.md), запуск на Windows и сценарий защиты по шагам — [docs/WINDOWS.md](docs/WINDOWS.md)
## Запуск из чистого clone
Нужны Git, Docker с Compose v2 (проверено: Docker 29.8.0, Compose 5.5.1), Python 3.9+ и GNU make (на Windows — см. [WINDOWS.md](docs/WINDOWS.md)). Учётные данные в Git не хранятся, их создаёт скрипт.
```sh
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab3 mtusi2026lab3 && cd mtusi2026lab3 && git checkout solution/bvt2302-bodanyuk
python3 scripts/init_secrets.py # случайные локальные пароли -> ./secrets (git-ignored), идемпотентно
cp .env.example .env # API_REPLICAS=2, лимиты, таймауты; значения по умолчанию есть и в compose.yaml
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
# postgres, valkey healthy -> migrate (один раз, exit 0) -> api x2 healthy -> lb healthy
curl -i http://127.0.0.1:8080/health/ready # 200, X-Instance-Id: <container id>; Swagger /docs; LB: http://127.0.0.1:8404/
make check && make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && make restore
```
- **Windows:** публичным тестам нужен `PYTHONUTF8=1`; Windows не исполняет `.sh`, поэтому хуки запускаются через обёртки `scripts/restart.cmd` и `scripts/stop-one.cmd` (тот же `.sh` в Git Bash); рецептам Makefile нужен `sh` из `C:\Program Files\Git\usr\bin`.
- **Свои тесты:** `python3 -m venv .venv`, `pip install --require-hashes --no-deps -r requirements.txt`, `pip install -r requirements-test.txt`, затем `make student-test` (~8 мин, стенд должен быть поднят). Без стенда — `make unit-test`.
- **Все доказательства одной командой** (на чистом clone, ~25 мин): `python scripts/collect_evidence.py`.
- **Миграции:** только сервис `migrate` (`python -m messenger.migrate`, advisory lock, checksum файлов), до старта реплик. Повтор: `make migrate` → `already applied, skipped`.
- **Остановка:** безопасно — `docker compose down` (volumes сохраняются). Намеренное удаление учебных данных — `docker compose down -v` и `rm -rf secrets`.
## Архитектура и решения
```text
клиент ──127.0.0.1:8080──> lb: HAProxy 3.2 ──сеть edge──> api × N (Starlette/uvicorn, без состояния, X-Instance-Id = hostname)
│ check GET /health/ready 1 с, fall 2/rise 2 │
│ Docker DNS `api` каждые 1 с (server-template, 8 слотов) └──сеть data (internal)──> postgres 18.6 (источник истины)
└ свои 502/503/504 — JSON по контракту с X-Request-Id valkey 8.1.3 (сессии, AOF always)
migrate (одноразовый) ──data──> postgres: миграции 0001–0003 до старта реплик
```
| Роль | Service | Образ | Health / readiness | Volume | Сеть / порт | Credentials | CPU / RAM |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Точка входа | `lb` | `haproxy:3.2.26-alpine@sha256:254e6370…` | `haproxy -c` + stats; бэкенды — активная проверка `/health/ready` | — | edge; `127.0.0.1:8080` и `[::1]:8080` (loopback, см. ниже), `127.0.0.1:8404` (stats) | нет | 1.0 / 128m |
| API × 2 | `api` (`deploy.replicas`) | `mtusi-messenger:lab3` из исходников | Docker: `/health/ready` 2 с; LB: своя проверка | — | edge + data, только `expose 8080` | secrets `database_url`, `cache_url` | 1.0 / 256m каждая |
| Миграции | `migrate` | тот же образ | exit 0 | — | data | secret `database_url` | 0.5 / 256m |
| БД | `postgres` | `postgres:18.6-bookworm@sha256:afc7e2d4…` | `pg_isready` | `pgdata` | data (internal) | secret `postgres_password` | 2.0 / 1g |
| Сессии | `valkey` | `valkey/valkey:8.1.3-bookworm@sha256:fea8b3e6…` | `valkey-cli ping` | `valkeydata` | data (internal) | secret `valkey_password` → include-файл | 0.5 / 256m |
**Что перенесено из lab2** (отдельный коммит `4f6cfda`, без изменений): API, PostgreSQL-схема 0001, сессии только в Valkey, Argon2id, keyset-cursor, строгая валидация, дедлайны БД/Valkey, собственные тесты. **Что изменено в lab3:**
- **Балансировка без sticky.** Один Compose-сервис `api` масштабируется (`--scale`, `deploy.replicas`), без `container_name` и `ports`. HAProxy находит реплики через Docker DNS (`server-template api 8 api:8080 … resolvers docker`, `hold valid 1s`), поэтому scale up/down, новый IP после рестарта и полный restart стенда подхватываются без перезапуска LB (проверено тестами).
- **Readiness управляет маршрутизацией.** `option httpchk GET /health/ready`, `inter 1s fastinter 500ms fall 2 rise 2`, `timeout check 1s`, без backup-слотов. Ready = PostgreSQL и Valkey отвечают и нет drain. Реплика, живая по `/health/live`, но без БД/Valkey, не получает ни одного бизнес-запроса.
- **Повторы в LB только безопасные.** `retry-on conn-failure` + `option redispatch`: повторяется только запрос, который не удалось отправить реплике. Всё, что могло дойти до API (включая неидемпотентные POST создания чата/пользователя), повторяет клиент сам; отправку сообщения — с тем же `Idempotency-Key`.
- **Graceful shutdown.** SIGTERM → readiness 503 сразу → `DRAIN_SECONDS=3` реплика ещё обслуживает (LB успевает пометить её DOWN) → uvicorn закрывает сокет, запросы в полёте ≤ `SHUTDOWN_TIMEOUT_SECONDS=8` → exit 0. 3 + 8 < `stop_grace_period: 15s`, SIGKILL не нужен.
- **`X-Instance-Id`** = hostname контейнера (короткий container ID): стабилен для процесса, однозначно сопоставляется контейнеру (`docker inspect`), что использует `scripts/stop-one.sh`. Middleware ставит его и `X-Request-Id` на **каждый** ответ API, включая 404/405/413/500/503. Ошибки, созданные самим HAProxy, — без `X-Instance-Id` (их создал не API), но в формате контракта и с тем же `X-Request-Id`.
- **Общая идемпотентность** ([0002](migrations/0002_idempotency_keys.sql), [0003](migrations/0003_post_message_function.sql), [repo.py](src/messenger/repo.py), [app.py](src/messenger/app.py)). Таблица `idempotency_keys (user_id, chat_id, key)` → SHA-256 канонического тела → `message_id`. Ключ, часы чата, сообщение и «результат» — **одна транзакция**; отдельного pending-состояния нет, поэтому сбой не оставляет «висящий» ключ, а транзиентная 5xx не фиксируется. Конкурентный повтор ждёт на уникальном индексе завершения первой транзакции и затем видит её результат (READ COMMITTED). Тот же ключ и тело → тот же 201 и Message; другое тело → 409; постороннему — 404 всегда (членство проверяется до ключа); `attachment_ids: []` = отсутствие поля, порядок ключей JSON не важен. Ключи хранятся ≥ 24 ч, старше — очищаются пачками раз в 10 мин под advisory-замком.
- **Миграции** — только сервис `migrate`, до старта реплик; 0002 и 0003 только добавляют объекты и совместимы с работающей предыдущей версией (rolling update: сначала миграция новым образом, затем замена реплик). При `docker compose start api` (например, в `restart.sh`) Compose снова запускает `migrate` как зависимость — он берёт advisory-замок и отвечает `already applied, skipped`; реплики ждут его завершения ([test-persistence.txt](evidence/test-persistence.txt)).
- **Порты только на loopback.** LB опубликован на `127.0.0.1` и `[::1]`. На Windows `localhost` сначала разрешается в `::1`, и отказ соединения по нему стоил ~2 с на **каждый** запрос (измерено: 2,0 с против 0,007 с). Публичные тесты по умолчанию ходят на `http://localhost:8080`, и в первом прогоне из чистого clone `make test-failover` из-за этого успел сделать лишь 8 записей за 15 с. После исправления — 0,013 с.
- **Сети.** `edge` (lb, api) и internal `data` (api, migrate, postgres, valkey): LB не видит хранилища, у хранилищ нет выхода наружу. Secrets — каждому сервису только свои (проверяется тестом по `docker compose config`).
- **Дефект, найденный на lab3-сценарии рецензента.** Если одной реплике отключить сеть `data`, по дедлайну задача psycopg отменялась, psycopg слал cancel-запрос, а libpq `PQcancelStart` синхронно резолвит имя хоста **в потоке event loop** — вся реплика, включая `/health/live`, зависала примерно на минуту и не возвращалась сама. Теперь по дедлайну запрос сразу получает 503, а задача не отменяется и завершается сама; мёртвые соединения рвёт TCP keepalive + `tcp_user_timeout` = 3 с ([db.py](src/messenger/db.py)). Повторная проверка: live отвечает за 0,00 с, ready 503 за 1,0 с, после восстановления сети реплика сама UP за ~2 с (тест `test_lb_stops_routing_…[network]`).
- **Улучшение трека 1** — запись сообщения одним вызовом SQL-функции `post_message` (подробно в треке); прежний путь доступен как `MESSAGE_WRITE_PATH=multi`, оба проходят одни и те же тесты.
Readiness-критичные зависимости: PostgreSQL (всё, кроме health) и Valkey (все защищённые запросы). Swagger/stats LB на readiness не влияют.
Соответствие `.env.example` реальной конфигурации ([config.py](src/messenger/config.py), [compose.yaml](compose.yaml)):
| Переменная | Значение | Где используется |
| --- | --- | --- |
| `APP_HOST`, `APP_PORT`, `APP_ENV` | `0.0.0.0`, `8080`, `lab` | bind uvicorn, стартовый лог |
| `SESSION_TTL_SECONDS` | `3600` | срок сессии (compose передаёт в каждую реплику) |
| `DATABASE_URL_FILE`, `CACHE_URL_FILE` | `/run/secrets/…` | строки подключения из secret-файлов |
| `SESSION_STORE` | `valkey` (или `postgres`) | хранилище сессий |
| `API_REPLICAS` | `2` | `deploy.replicas` сервиса `api` |
| `IDEMPOTENCY_TTL_SECONDS` | `86400` (меньше нельзя) | срок хранения результата ключа |
| `MESSAGE_WRITE_PATH` | `function` (или `multi`) | путь записи сообщения (трек 1, A/B) |
| `DRAIN_SECONDS`, `SHUTDOWN_TIMEOUT_SECONDS` | `3`, `8` | graceful shutdown |
| `DB_POOL_MIN/MAX`, `DB_TIMEOUT_SECONDS`, `CACHE_TIMEOUT_SECONDS`, `PASSWORD_HASH_CONCURRENCY` | 1/10, 3, 0.5, 2 | пул, дедлайны, параллельность Argon2id |
| `API_CPUS/MEMORY`, `PG_CPUS/MEMORY`, `VALKEY_CPUS`, `LB_CPUS`, `PG_MAX_CONNECTIONS` | 1.0/256m, 2.0/1g, 0.5, 1.0, 100 | лимиты контейнеров |
| `APP_PUBLISH_PORT`, `LB_STATS_PORT` | `8080`, `8404` | порты LB на `127.0.0.1` (API портов не публикует) |
| `LOG_LEVEL`, `DOCS_ENABLED` | `info`, `true` | логи, Swagger |
## Доказательства критериев
Стенд: Windows 10 22H2, AMD Ryzen 5 3400G (4 ядра / 8 потоков), 30 ГБ RAM, Docker Desktop 29.8.0 (WSL2, 8 vCPU), Python 3.14 на хосте, GNU make 4.4.1. Все проверки уровней 3 и 4 ниже выполнены 2026-10-19 **на стенде из чистого clone** (новая папка, `git clone`, пустые volumes, secrets созданы заново) одной командой `python scripts/collect_evidence.py`, коммит `2708732`. Вывод сохранён целиком.
| Критерий README | Команда / сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Чистый clone, secrets, миграции с нуля, одна команда запуска | `init_secrets.py`, `compose config --quiet`, `compose up -d --build --wait`, `compose logs migrate`, `git check-ignore` | все 5 сервисов healthy, `migrate` Exited (0): `0001…0003: applied`; образы по digest; `secrets/` и `.env` игнорируются Git | [clean-clone.txt](evidence/clean-clone.txt) |
| Контракт | `make check`, `make validate` | PASS, PASS | [make-check-validate-test.txt](evidence/make-check-validate-test.txt) |
| **3:** публичный smoke | `make test` | `PASS: lab3 public API scenario` | там же |
| **3:** ≥ 2 реплики, одна точка входа, общая БД и сессии | `lbctl.py replicas/status`, `test_one_session_is_served_by_every_real_replica`, `test_write_on_one_replica_is_read_on_the_other` | 2 контейнера `api` UP в HAProxy; один токен — ответы от обоих, `X-Instance-Id` = их hostname; запись на одной сразу читается на другой; logout сразу действует на обеих | [clean-clone.txt](evidence/clean-clone.txt), [student-tests.txt](evidence/student-tests.txt) |
| **3:** остановка любой реплики, ≤ 10 с, подтверждённое на месте | `make test-failover ACTION_SCRIPT=scripts/stop-one.cmd` → `make restore` → снова (по очереди обе) | PASS для `api-1` и для `api-2`: 131 / 132 успешных записи, **0 неудачных попыток**, запись после хука — 5,9 / 5,7 с; остановленный контейнер `exited (0)`, вторая реплика UP | [test-failover.txt](evidence/test-failover.txt) |
| **3:** повтор POST без дубля, в т.ч. конкурентный и через другую реплику; неподтверждённую запись можно повторить | `test_idempotency.py` (21 тест) + публичный failover-тест (повторяет неопределённый POST с тем же ключом) | см. таблицу «ловушек» ниже; публичный тест: дублей нет | [student-tests.txt](evidence/student-tests.txt) |
| **3:** persistence | `make test-persistence ACTION_SCRIPT=scripts/restart.cmd` | PASS; у `lb`, `api-1`, `api-2`, `postgres`, `valkey` новые PID и `StartedAt`, volumes те же, токен тот же | [test-persistence.txt](evidence/test-persistence.txt) |
| **4:** readiness, таймауты, SIGTERM согласованы; LB исключает недоступный backend | `test_lb_stops_routing_…[pg_hba/network × 2]`, `test_graceful_stop_…[×2]`, `test_graceful_shutdown_order_in_logs` | живая, но неготовая реплика выходит из ротации за 3–4 с, live 200 / ready 503, сама возвращается ≤ 15 с; graceful stop под нагрузкой — 0 ошибок; в логах `drain_started` → `shutdown_requested` → `stopped`, exit 0, в логе HAProxy — `is DOWN` для этой реплики | [student-tests.txt](evidence/student-tests.txt) |
| **4:** период проверок и максимальное время обнаружения | [haproxy.cfg](infra/haproxy/haproxy.cfg) + серия отказов | проверка раз в 1 с, `fall 2`/`rise 2`, `timeout check 1s`; максимум ≈ 3,5 с (заморозка); подробно — в следующем разделе | [failover/series.md](evidence/failover/series.md) |
| **4:** поочерёдная остановка каждой реплики: RPS, ошибки, восстановление | `bench/failover_series.py` (stop / kill / pause × обе реплики) | stop: 0 ошибок; kill: 3 оборванных запроса за ≤ 0,25 с; pause: 4 неудачные попытки за ≤ 3,2 с; потерь и дублей нет | [failover/series.md](evidence/failover/series.md), [series.json](evidence/failover/series.json) |
| **4:** общая идемпотентность параллельными запросами | `test_concurrent_same_key_through_different_replicas_creates_exactly_one`, `…_different_bodies_one_wins` | 24 одновременных → 24 × 201, одно тело, ≥ 2 реплики, 1 строка ключа и 1 сообщение (×3 раунда); разные тела → один победитель, остальные 409 | [student-tests.txt](evidence/student-tests.txt) |
| **4:** лимиты CPU/RAM, нет портов в обход LB, secrets по месту, нет `container_name` | `test_compose_policy_limits_ports_secrets_images`, `test_running_containers_have_limits_and_no_bypass_ports` | лимиты у всех 5 сервисов (config и `docker inspect`); порты только у `lb` и только loopback; secrets: lb — нет, migrate — `database_url`, api — `database_url`+`cache_url`; сети edge/data | там же |
| **4:** rolling update под нагрузкой | `bench/rolling_under_load.py` → `scripts/rolling-update.sh` | 57 с, 11 848 запросов, **0 ошибок**; `api-1/2 revision=dev` → `api-3/4 revision=2708732-…`; 7119 подтверждённых сообщений, 0 потерь и дублей | [rolling-update/](evidence/rolling-update/) |
| **4:** миграции однократно и совместимы | `test_migrations_ran_once_by_the_migrate_service`, `test_migrations_rerun_is_a_noop` | применяет только `migrate` (в логах API миграций нет); повтор — `already applied, skipped`; 0002/0003 только добавляют объекты и применяются до замены реплик | [student-tests.txt](evidence/student-tests.txt), [rolling-update/script-output.txt](evidence/rolling-update/script-output.txt) |
| Публичный генератор нагрузки | `tests/load.py --duration 30 --concurrency 4` | 5247 успешных, 0 ошибок, 174 req/s (closed-loop через порт Windows), p50/p95/p99 = 19 / 50 / 65 мс | [load.json](evidence/load.json) |
| Свои тесты | `python -m pytest student-tests -v` | **201 passed** (69 unit + 132 против стенда), 8 мин; все отказы восстанавливаются в `finally` | [student-tests.txt](evidence/student-tests.txt) |
| Оба пути записи эквивалентны | тесты идемпотентности, контракта и БД с `MESSAGE_WRITE_PATH=multi` | 105 passed (режим `function` — весь набор выше) | раздел трека 1 |
| **5:** трек 1 | `bench/track1/series.sh baseline|improved|ceiling`, `profile.py`, `analyze.py` | см. раздел «Трек 1» | [evidence/track1/](evidence/track1/) |
Первый прогон из чистого clone (тот же сценарий, коммит `2846cae`) нашёл проблему: через `localhost` каждое соединение на Windows стоило 2 с (LB был опубликован только на `127.0.0.1`), и `make test-failover` успел сделать 8 записей вместо ~130. Исправлено публикацией и на `[::1]` (коммит `2708732`). Таблица выше — второй, полный прогон.
## Проверки, на которых ловили другие работы
Замечания преподавателя к PR lab3 (#1–#19) и lab2 других студентов, проверенные на своём стенде:
| Замечание к чужим PR | У нас | Где проверено |
| --- | --- | --- |
| после сбоя ключ остаётся «pending»: повтор висит / 504 / 409 | ключ и сообщение в одной транзакции; сбой триггером **после** вставки ключа → нет ни ключа, ни сообщения (`n_tup_ins` доказывает, что INSERT был), повтор → 201 | `test_failure_after_the_key_insert_rolls_everything_back` |
| одновременные повторы дают 19×201 + 1×409 | 24 одновременных запроса через ≥ 2 реплики, три раунда → 24×201, одно тело, 1 сообщение, 1 строка ключа | `test_concurrent_same_key_through_different_replicas_creates_exactly_one` |
| посторонний: 404, затем 409 | всегда 404, и с чужим ключом, и с другим телом | `test_outsider_and_revoked_session_never_see_the_stored_result` |
| `attachment_ids: []` при повторе → 400 | равно отсутствию поля, тот же 201; порядок ключей не важен | `test_key_order_and_missing_attachment_ids_are_the_same_body` |
| `X-Instance-Id: unknown`; нет заголовков на 500 / 413 | hostname контейнера; middleware на всех ответах, включая 500 из триггера и 413 | `Api.call` проверяет **каждый** ответ; `test_every_api_response_carries_…` |
| LB шлёт запросы неготовой реплике (pg отнят, `network disconnect`, забит пул); fallback-слоты без проверки | активная проверка `/health/ready`, без backup; реплика выходит из ротации за 3,2–4,1 с и сама возвращается | `test_lb_stops_routing_to_a_replica_that_is_alive_but_not_ready[pg_hba/network × 2 реплики]` |
| после общего restart LB видит одну реплику | re-resolve Docker DNS каждую секунду | `test_full_restart_lb_rediscovers_all_replicas` |
| «обновление» останавливает обе API; нет проверки под нагрузкой | +1 новая реплика, затем graceful stop старой; под нагрузкой 0 ошибок | [evidence/rolling-update/](evidence/rolling-update/) |
| миграции в каждой API | только `migrate`; в логах API нет миграций | `test_migrations_ran_once_by_the_migrate_service` |
| нет лимитов у LB, migrate, PostgreSQL, Redis | лимиты у всех 5 сервисов; проверены и `compose config`, и `docker inspect` запущенных | `test_compose_policy_…`, `test_running_containers_have_limits_…` |
| неидемпотентные POST повторяются LB | `retry-on conn-failure` — только неотправленные запросы | [haproxy.cfg](infra/haproxy/haproxy.cfg), DEFENSE.md |
| cursor с числом/`null`/`[]`/`{}`/`false`, пустой, пробел → 500 или 200 | 400 на обоих списках; курсор одного списка в другом → 400 | `test_malformed_cursor_values_are_400_on_both_lists`, `test_cursor_of_one_list_is_rejected_by_the_other` |
| `{"text":"first","TEXT":"second"}`, дубли ключей, `{"text":123}`, хвост после JSON, байт FF | 400, ничего не сохраняется | `test_bad_message_body_is_400_and_nothing_is_stored` |
| `Bearer é` → 500; UUID в разном регистре → 503; тело при входе игнорируется | 401; 400 (дубль после нормализации); 400 | `test_non_ascii_or_garbage_bearer_…`, `test_member_ids_are_compared_as_uuids_…`, `test_login_with_a_body_is_rejected` |
| пароль `"a"` принят, `"я:"×64` отклонён; пробельные Unicode-строки (U+00A0, U+2003) приняты; `1e1000` роняет API; 101 участник | 400 / 201; 400; 400 и API живо; 400 | `test_password_range_…`, `test_unicode_whitespace_only_strings_are_400`, `test_odd_registration_bodies_…`, `test_more_than_100_members_is_400` |
| текст обрезается по краям, длина считается после обрезки | хранится как есть; 4001 code point → 400 | `test_text_is_stored_verbatim_and_length_counts_raw_text` |
| трек 1: в «RPS» входят ошибки; неверное суммирование CPU реплик; бюджет в отчёте не совпадает с данными; на графике несопоставимые точки | считаются только 201 (`ok_messages`), dropped отдельно; CPU реплик суммируется в каждый момент; фактические лимиты из `docker inspect` в каждом raw-файле; на графике серии одной конфигурации ресурсов | [analyze.py](bench/track1/analyze.py), [run.py](bench/track1/run.py) |
| трек 1: улучшение не воспроизвелось на другом хосте | улучшение структурное (число обращений к БД на запрос, видно в `pg_stat_statements`), A/B на одном образе одной переменной | серия D |
| lab2: отозванный токен «оживает» после восстановления Redis; БД упала → 401/500 | сессии только в Valkey (нет второй копии); 503 | `test_failures.py`, `test_sessions.py` (перенесены из lab2) |
Сам Content-Type `text/plain` даёт 400, а не 415: в OpenAPI lab3 для `POST /users` и `POST …/messages` ответ 415 не объявлен, контракт требует отклонения — оно есть.
## Эксперименты и отказы (уровень 4)
**Поочерёдная остановка каждой реплики** ([bench/failover_series.py](bench/failover_series.py), [series.md](evidence/failover/series.md)). Нагрузка — 4 closed-loop клиента с хоста через LB: POST сообщения (неопределённый результат → повтор тем же ключом) + GET последней страницы, таймаут клиента 3 с. Раунд: 6 с прогрева → остановка → 12 с без реплики → старт → ожидание UP в HAProxy → 6 с. Перед каждым раундом предыдущая реплика уже восстановлена.
| Воздействие | Что ожидаем | Что наблюдали (api-1 / api-2) | Восстановление / потери |
| --- | --- | --- | --- |
| `docker stop` (SIGTERM, drain) | 0 ошибок: реплика сама уходит из ротации до закрытия сокета | 3568 / 3565 запросов во время отказа, **0 ошибок**; цель последний раз ответила через 1,28 / 1,24 с после SIGTERM (drain) | возврат: UP через 3,3 / 1,4 с, снова обслуживает через 3,4 / 3,1 с; 0 потерь, 0 дублей |
| `docker stop -t 0` (SIGKILL) | обрываются только запросы «в полёте» на убитой реплике | 3 неудачных попытки (обрыв соединения) за ≤ 0,25 с; новые запросы сразу идут на живую (`retry-on conn-failure`) | возврат 2,8 / 3,6 с; неопределённые POST повторены тем же ключом, 0 дублей |
| `docker pause` (заморожен процесс — худший случай) | запросы на замороженную реплику ждут до таймаута, пока проверки её не выключат | 4 неудачные попытки, последняя через 3,2 / 3,1 с; ok-RPS во время отказа падает ~вдвое (часть клиентов ждёт) | после `unpause` UP через 2,2 / 1,2 с; 0 потерь, 0 дублей |
| неготовая, но живая реплика (`pg_hba reject` / `network disconnect` сети `data`) | LB исключает её по readiness, бизнес-запросы к ней не идут | DOWN через 3,2–4,1 с, затем 40 из 40 чтений и 20 из 20 регистраций — через другую реплику; live 200 / ready 503, процесс отвечает | сама UP ≤ 15 с после восстановления доступа (тест) |
| rolling update | ≥ 2 реплики в каждый момент | 57 с, 11 848 запросов, 0 ошибок, p95 53 мс | обе реплики на новой ревизии; 0 потерь, 0 дублей |
| restart всего стенда (`restart.sh`) | данные и токен на месте, LB находит новые IP сам | PASS публичного теста; новые PID у всех 5 процессов | LB видит обе реплики без своего рестарта (тест) |
**Период проверок и максимальное время обнаружения.** HAProxy проверяет `GET /health/ready` каждую 1 с, после первой неудачи — каждые 0,5 с (`fastinter`), DOWN после 2 неудач подряд, UP после 2 удач, таймаут проверки 1 с.
| Ситуация | Максимум до DOWN |
| --- | --- |
| реплика сразу отвечает 503 (drain после SIGTERM) | ≈ 1 + 0,5 = 1,5 с |
| ready отвечает медленно (отнят PostgreSQL/Valkey: ответ ≈ 1 с = таймаут проверки) | ≈ 1 + 1 + 0,5 + 1 = 3,5 с |
| процесс заморожен (каждая проверка ждёт таймаут) | ≈ 1 + 1 + 0,5 + 1 = 3,5 с |
| процесс убит или порт закрыт | новые запросы получают отказ соединения, HAProxy сразу отправляет их на другую реплику (`retry-on conn-failure` + `redispatch`); проверка лишь фиксирует это |
Измерения выше в эти пределы укладываются: при drain реплика выходит из ротации за ≈ 1,2–1,3 с, а 3,2–4,1 с (отнятая БД/сеть, заморозка) включают 0,1–0,5 с опроса через `docker exec`.
**Ограничение измерения.** Нагрузка closed-loop с хоста Windows через проброс порта Docker Desktop (~200–290 ok-RPS). Это проверка доступности и корректности, а не ёмкости — ёмкость меряет трек 1 с k6 внутри сети стенда. Неудачной попыткой считается любой не-2xx ответ или ошибка соединения/таймаут клиента.
## Трек 1. Цена масштабирования
Все цифры ниже — из [evidence/track1/summary.md](evidence/track1/summary.md) (генерирует [analyze.py](bench/track1/analyze.py) из `results.csv`); сырые данные каждой ступени — `evidence/track1/<серия>/<метка>/raw/*.json` (k6 summary, CPU по контейнерам, ожидание пула, счётчики PostgreSQL и HAProxy, фактические лимиты из `docker inspect`). Полный план повторяется одной командой: [bench/track1/series.sh](bench/track1/series.sh).
### Гипотезы
1. Один процесс Python (uvicorn, 1 воркер) исполняет байткод на одном ядре (GIL). Поэтому при фиксированном суммарном CPU одна «толстая» реплика упрётся в одно ядро, а несколько «тонких» используют весь бюджет. Дробить сильнее, чем по ядру на процесс, бесполезно.
2. Реплики API без состояния масштабируют пропускную способность линейно, пока не насытится общий ресурс — PostgreSQL (одна БД на все реплики). После этого добавление реплик не помогает, и потолок задаёт CPU БД. Если дать БД больше CPU, потолок сдвинется — это проверка причины, а не совпадения.
3. LB (HAProxy) и пул соединений не являются узким местом на этих нагрузках: HAProxy тратит единицы процентов ядра на сотни запросов/с.
4. Улучшение: основная цена запроса — накладные расходы на каждый SQL-оператор, а не сама работа БД (гипотеза из профиля). Если выполнить идемпотентную запись одним вызовом, сократятся CPU на сообщение и в API, и в PostgreSQL, и потолок вырастет в обоих режимах — и когда упираемся в API, и когда в БД.
### Методика
- **Стенд.** Ноутбук: AMD Ryzen 5 3400G (4 ядра / 8 потоков SMT), 30 ГБ RAM, Windows 10 22H2, Docker Desktop 29.8.0 (WSL2, ядро 6.18, 8 vCPU, 15,6 ГБ). «1 CPU» в лимитах = 1 vCPU = один аппаратный поток SMT, то есть примерно половина физического ядра.
- **Изоляция.** На время серий основной стенд остановлен. Каждая конфигурация в каждом повторе — **свежий стенд** в отдельном compose-проекте `mtusi-lab3-bench` с пустыми volumes (`down -v` → `up`), чтобы размер истории не копился между конфигурациями. Роли закреплены за своими CPU (`cpuset`, [compose.bench.yaml](bench/track1/compose.bench.yaml)): k6 — 0–1, LB + Valkey — 2, PostgreSQL — 3–4, все реплики API — 5–7. Поверх набора CPU действуют квоты `cpus` из конфигурации (API_CPUS на реплику, PG_CPUS). Генератор и LB не отнимают CPU у API.
- **Код.** Образ API собирается из **коммита** (`git archive <sha> | docker build`), а не из рабочей копии: базовые серии A–C — коммит `3f45eb1` (до улучшения), серии D–E — `4830be4` (с улучшением, старый путь доступен через `MESSAGE_WRITE_PATH=multi`). Фактический образ и лимиты записаны в каждом raw-файле.
- **Нагрузка.** k6 2.3.0 в отдельном контейнере в сети `edge` идёт через LB, как внешний клиент, без проброса портов Windows. Open-loop `constant-arrival-rate`: итерации стартуют с заданной частотой независимо от ответов, поэтому нет coordinated omission. Итерации, которым не хватило VU, считаются в `dropped_iterations` как неудовлетворённый спрос. Одна итерация = `POST /chats/{id}/messages` с новым `Idempotency-Key` в один из 64 чатов (64 пользователя, у каждого свой чат), чтобы блокировка строки одного чата не доминировала. Пользователи и сессии создаются оркестратором до старта k6, файл с синтетическими токенами монтируется только для чтения и удаляется после серии.
- **Ступень:** прогрев 10 с (не учитывается) + замер 20 с. Ступени по возрастанию предложенной нагрузки, 3 повтора. Таймаут запроса 10 с.
- **Метрики.** Успешные = только ответы 201 (`ok_messages`). Ошибки и dropped — отдельно; задержки p50/p95/p99 — только успешных. CPU — `docker stats` каждые ~1–2 с, медиана за фазу замера; CPU реплик суммируется в каждый момент. Ожидание пула — счётчики psycopg-pool из лога реплик (`STATS_LOG_SECONDS=2`). PostgreSQL — `pg_stat_database` (транзакции, WAL) и `pg_stat_statements` (операторы на сообщение). HAProxy — `show stat` (переходы в DOWN, очереди).
- **Определения.** *Потолок* конфигурации — наибольший успешный RPS по ступеням в повторе, затем медиана и разброс по 3 повторам. *SLO-ёмкость* — наибольшая предложенная нагрузка, обслуженная на ≥ 97 % с p95 ≤ 500 мс. *Узкое место* — компонент, чей CPU ≥ 90 % своего лимита на ступени потолка. Для API отдельно отмечается «одно ядро на процесс», когда CPU ≈ 100 % × число реплик при большей квоте.
### Результаты
**A. Фиксированный суммарный CPU API = 2,0 (768 МиБ), PostgreSQL 2,0 CPU** ([график](evidence/track1/A-fixed-total/baseline/throughput.svg)):
| Реплики × CPU | Потолок, успешных/с (мин–макс) | SLO-ёмкость | CPU API / квота | CPU БД / квота | CPU LB | Узкое место |
| --- | --- | --- | --- | --- | --- | --- |
| 1 × 2,0 | 214 (209–220) | 200 | 101 % / 200 % | 47 % / 200 % | 9 % | одно ядро на процесс (GIL) |
| 2 × 1,0 | **289** (281–291) | 250 | 198 % / 200 % | 66 % / 200 % | 14 % | CPU API |
| 4 × 0,5 | 239 (237–241) | 150 | 195 % / 200 % | 60 % / 200 % | 13 % | CPU API + флаппинг проверок |
Гипотеза 1 подтверждена. Одна реплика с квотой 2,0 использует ~1 ядро, вторая половина квоты простаивает. Две реплики по 1,0 используют весь бюджет и дают +35 %. Четыре по 0,5 при том же бюджете хуже двух (−17 %): процесс с квотой 0,5 обрабатывает каждый запрос вдвое дольше, растёт задержка (p95 уже при 150/с — 460 мс). Кроме того, при перегрузке реплики не успевают ответить на `/health/ready` за 1 с: HAProxy выводит их из ротации — 78 переходов в DOWN за серию, до 11 % ответов 503 от LB. Дробление ниже ядра на процесс ухудшает и скорость, и стабильность.
**B. Рост ресурсов API (1, 2, 3 реплики × 1,0 CPU) при узкой БД (PostgreSQL 0,5 CPU)** ([график](evidence/track1/B-replicas-vs-db/baseline/throughput.svg)):
| Реплики | Потолок, успешных/с (мин–макс) | CPU API / квота | CPU БД / квота | Узкое место | Ошибки при перегрузке |
| --- | --- | --- | --- | --- | --- |
| 1 | 178 (177–180) | 94 % / 100 % | 39 % / 50 % | CPU API | до 26 % |
| 2 | **210** (208–222) | 145 % / 200 % | 49 % / 50 % | CPU PostgreSQL | до 20 % |
| 3 | 197 (197–205) | 167 % / 300 % | 49 % / 50 % | CPU PostgreSQL | до 42 % |
Точка насыщения БД — около 200–210 успешных/с. Вторая реплика ещё помогает (+18 %), третья — нет: API простаивает (167 % из 300 %), CPU БД на квоте. При перегрузке выше этой точки запросы ждут соединения в пуле (до ~1 с), часть упирается в дедлайн 3 с (503). Readiness реплик тоже начинает отвечать дольше 1 с, и HAProxy выводит их из ротации (103 перехода в DOWN у 3 реплик). Больше реплик — больше конкурирующих соединений к той же БД и больше ошибок, а не больше пропускной способности.
**C. Рост ресурсов БД при 3 репликах × 1,0** ([график](evidence/track1/C-db-growth/baseline/throughput.svg)):
| CPU PostgreSQL | Потолок, успешных/с (мин–макс) | CPU API / квота | CPU БД / квота | Узкое место |
| --- | --- | --- | --- | --- |
| 0,5 (из серии B) | 197 (197–205) | 167 % / 300 % | 49 % / 50 % | PostgreSQL |
| 1,0 | **334** (316–337) | 281 % / 300 % | 94 % / 100 % | API и PostgreSQL |
| 2,0 | 347 (345–347) | 293 % / 300 % | 92 % / 200 % | CPU API |
Гипотеза 2 подтверждена причинно. Удвоение CPU одной только БД при тех же трёх репликах поднимает потолок на 70 % — значит, в B ограничивала именно БД. Следующее удвоение даёт только +4 %: узкое место вернулось в API (293 % из 300 %), БД загружена меньше чем на половину квоты. Узкое место переходит между компонентами (API → БД → API), и масштабировать имеет смысл только тот компонент, который сейчас насыщен.
**LB и пул (гипотеза 3).** HAProxy на всех ступенях занимает 4–24 % одного ядра. Очередь в LB появляется только на ступенях перегрузки, когда у реплики уже 200 одновременных запросов (`maxconn 200` на сервер): `qmax` 200–576 при 250–400/с, ни разу ниже потолка конфигурации. Это защита реплики, а не причина насыщения; `qmax` — максимум с момента старта стенда. Пул (10 соединений на реплику) не ограничивает сам по себе: ожидание соединения вырастает (сотни мс) только после насыщения CPU API или БД, то есть это симптом, а не причина. Под перегрузкой первым «ломается» не LB, а readiness: проверка `/health/ready` идёт через тот же пул и event loop, и под перегрузкой реплика честно сообщает «не готова». В итоге LB сбрасывает избыточную нагрузку ответами 503 — это видно в B и A (4 × 0,5).
### Улучшение: идемпотентная запись одним вызовом
**Диагностика.** Профиль одной реплики (2 × 1,0 CPU, 240 req/s, py-spy 20 с, [profile-baseline-3f45eb1.txt](evidence/track1/profile-baseline-3f45eb1.txt)) показал: **52,7 %** сэмплов — в драйвере psycopg, 23 % — в event loop, 9,6 % — в нашем коде, по 2–4 % — в uvicorn, redis-py, логировании, Starlette. Время делят функции, через которые проходит **каждый** оператор: ожидание ответа (`wait_async`), отправка команды, подготовка prepared statement, разбор результата. На одно сообщение старый путь делает ~15 операторов в двух транзакциях (`pg_stat_statements`): проверка членства, BEGIN, захват ключа, часы чата, вставка, COMMIT, проверки соединений пулом.
**Изменение** (коммит `4830be4`, [0003_post_message_function.sql](migrations/0003_post_message_function.sql), [repo.py](src/messenger/repo.py)). Вся логика — та же проверка членства, тот же `INSERT … ON CONFLICT`, те же часы чата и вставка — перенесена в PL/pgSQL-функцию `post_message`. Её вызывает один оператор в autocommit, вызов и есть транзакция. Семантика не меняется: оба пути проходят одни и те же тесты идемпотентности, контракта и БД (105 тестов в режиме `multi`, весь набор — в режиме `function`).
**A/B на одном образе одной переменной** (серия D, `MESSAGE_WRITE_PATH=multi|function`, [график](evidence/track1/D-improvement/4830be4/throughput.svg); пунктир — старый путь, сплошная — новый):
| Конфигурация | `multi`, потолок (мин–макс) | `function`, потолок (мин–макс) | Прирост | p95 на 450/с |
| --- | --- | --- | --- | --- |
| 2 × 1,0 CPU, БД 2,0 (упор в API) | 283 (281–286) | **489** (488–491) — не насыщен на сетке до 500/с | ≥ +73 % | `multi` — перегружен; `function` — 399 мс |
| 3 × 1,0 CPU, БД 0,5 (упор в БД) | 202 (200–203) | **452** (444–462) | +124 % | `multi` — перегружен; `function` — 331 мс |
Цена одного сообщения на ненасыщенных ступенях 200–250/с (медиана 3 повторов):
| На одно сообщение | `multi` | `function` | Изменение |
| --- | --- | --- | --- |
| CPU API | 7,2–8,6 мс | 4,3–4,9 мс | −38…44 % |
| CPU PostgreSQL | 2,3–2,6 мс | 1,0–1,3 мс | −50…60 % |
| SQL-операторов (pg_stat_statements) | 15 | 3 | −80 % |
| транзакций в pg_stat_database (с проверками пула) | ~6 | ~3 | −50 % |
| WAL | ~1,9 КБ | ~1,9 КБ | без изменений: пишутся те же строки, durability та же |
Профиль после изменения при тех же 240 req/s ([profile-function-4830be4.txt](evidence/track1/profile-function-4830be4.txt)): доля psycopg **19,0 %** вместо 52,7 %. Активных сэмплов реплики за те же 20 с — 2026 вместо 3889 (py-spy не считает простой), то есть −48 % CPU-времени на тот же поток запросов.
Механизм подтверждён измерением, а не только итоговым RPS: работа с данными (WAL) не изменилась, исчезли накладные расходы на операторы. Поэтому улучшение не зависит от конкретного ноутбука. Число операторов и транзакций на сообщение — свойство кода, оно воспроизводится на любом хосте через `pg_stat_statements`. Абсолютные RPS на другом железе будут другими.
**Потолок нового пути** (серия E, те же конфигурации, ступени 450–850/с, 3 повтора, [график](evidence/track1/E-improved-ceiling/4830be4/throughput.svg)):
| Конфигурация | `function`, потолок (мин–макс) | CPU API / квота | CPU БД / квота | Узкое место | Итог против `multi` |
| --- | --- | --- | --- | --- | --- |
| 2 × 1,0 CPU, БД 2,0 | **552** (530–552) | 195 % / 200 % | 66 % / 200 % | CPU API | 283 → 552: **+95 %** |
| 3 × 1,0 CPU, БД 0,5 | 423 (395–440) | 177 % / 300 % | 50 % / 50 % | CPU PostgreSQL | 202 → 423–452: **+110…124 %** |
В серии E DB-bound конфигурация начинает сразу со ступени 450 — это уже выше её потолка, поэтому её максимум здесь ниже, чем в D (452 при 450/с). Обе серии сходятся на ~420–460/с.
После улучшения узкие места остались на своих местах, но каждый компонент делает вдвое больше полезной работы на единицу CPU. В 2 × 1,0 потолок снова задаёт CPU API (два процесса по ядру), и следующий рост — снова реплики и ядра под API. В 3 × 1,0 при БД 0,5 потолок задаёт CPU PostgreSQL: прирост реплик API за пределами точки насыщения БД по-прежнему не помогает. Улучшение сдвинуло эту точку более чем вдвое.
### Ограничения трека
- Один хост и SMT: 8 vCPU — это 4 физических ядра. k6, LB, БД и API разнесены по `cpuset`, но делят физические ядра попарно и общий кэш, а Windows-хост создаёт фоновый шум. Абсолютные числа годятся только для сравнения конфигураций **на этом стенде** (одинаковые ресурсы, одинаковый профиль), универсального RPS нет.
- Профиль нагрузки — только запись сообщений (новые ключи, 64 чата). Чтение истории, повторы ключей и вход (Argon2id) не нагружались. Профиль с горячим чатом (все пишут в один чат) упрётся в блокировку строки чата, а не в CPU — это отдельный эксперимент.
- Сетка ступеней шагом 50/с. Потолок известен с точностью до ступени; для `function` в 2 × 1,0 потолок в серии D не достигнут, его ищет серия E.
- CPU из `docker stats` — медиана выборок ~1–2 с. Это не точный учёт cgroup за окно. Окно замера определяется по времени выхода k6 (±1–2 с).
- Замер 20 с после прогрева 10 с на пустой БД: эффекты роста таблиц (autovacuum, раздувание индексов) не исследовались.
- py-spy с `--nonblocking` слегка замедляет профилируемую реплику, поэтому профиль показывает доли, а не абсолютный RPS.
## Ограничения и следующие шаги
**Какие отказы выдерживаются (доказано на стенде):**
- остановка, SIGKILL или заморозка **одной API-реплики** из двух: запись продолжается, подтверждённые сообщения на месте, дублей нет;
- потеря одной репликой связи с PostgreSQL/Valkey: реплика выходит из ротации, после восстановления сама возвращается;
- рестарт всего стенда с сохранением volumes: данные и прежний токен на месте, LB находит новые адреса реплик;
- поочерёдная замена реплик (rolling update) под нагрузкой — без ошибок;
- отказ PostgreSQL или Valkey целиком: ограниченные по времени 503, без анонимного доступа; после восстановления всё работает (перенесено из lab2).
**Какие не выдерживаются (честно):**
- **Один Docker-host** — это SPOF всего стенда: потеря хоста = потеря всего.
- **LB один.** Отказ HAProxy = недоступность API, хотя реплики живы. Нужны два LB с VIP (keepalived) или DNS/anycast. В Compose на одном хосте это не даёт реальной устойчивости.
- **PostgreSQL и Valkey не реплицированы.** Их отказ — 503 до восстановления, их диск — единственная копия данных (резервное копирование и PITR — тема трека 2 lab2, здесь не повторялось).
- **Обнаружение замороженной реплики** (`docker pause`) — до ~3,5 с. Запросы, попавшие на неё раньше, ждут клиентский таймаут: в доказательной серии — 4 неудачные попытки, последняя через 3,1–3,2 с (в предварительном прогоне — 8 попыток, последняя через 6,2 с: клиент дважды подряд попал на замороженную реплику до её выключения). HAProxy не повторяет такие запросы сам — они могли дойти до API, а неидемпотентные POST повторять нельзя.
- **Под глобальной перегрузкой** readiness всех реплик может стать 503 (проверка идёт через тот же пул и event loop), и LB отвечает 503 на всё. Это сброс нагрузки, но грубый. Следующий шаг — ограничение одновременных запросов на реплику ниже `maxconn` LB и отдельный лёгкий канал для readiness. Но рецензент требует исключать реплику с заблокированным пулом, поэтому зависимость readiness от пула сохранена сознательно.
- `X-Instance-Id` = hostname контейнера: в lab7 его нужно заменить непрозрачным alias.
**Учебные упрощения:** HTTP без TLS (lab7), один `uvicorn`-воркер на контейнер (масштабирование — репликами), секреты — файлы Docker secrets на одном хосте, нет rate limiting. Ключи идемпотентности хранятся в PostgreSQL рядом с данными (так проще атомарность), очистка — пачками по расписанию.
**Подтверждено измерениями:** улучшение записи сообщения (серии D и E, по 3 повтора): −80 % SQL-операторов, −40 % CPU API и −55 % CPU БД на сообщение, потолок +95 % в конфигурации с упором в API и +110…124 % с упором в БД; узкое место после улучшения — снова CPU API и CPU БД соответственно. **Пока гипотеза:** что ограничение одновременных запросов на реплику (ниже `maxconn` LB) уберёт флаппинг readiness под перегрузкой; что несколько uvicorn-воркеров в одном контейнере дадут то же, что реплики того же суммарного CPU.