Files
mtusi2026lab3/REPORT.md
T
Artyom 4513d90e48 Finalize lab 3 report and evidence provenance
Tie the grade 5 claim to the final SQLAlchemy revalidation and measured scaling results. Clarify clean-clone setup, failure timings, historical evidence, and operational constraints; record report-stage checks and evidence audits.
2026-11-06 01:29:44 +03:00

788 lines
97 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
- Автор, группа: Костылев Артём, БПИ2303
- Целевая оценка: **5**; трек «5» — **трек 1 «Цена масштабирования»**
- Ветка: `solution/bpi2303-kostylev`. Уровни «3» и «4» повторно подтверждены после
оптимизации на `3fb741e6a84d2b187a0266488b018f0b684dcce5`: SQLAlchemy 2.0.45 / Alembic 1.16.5.
[Команды и результаты](evidence/track1-sqlalchemy/revalidation/commands.txt),
[аудит доказательств](evidence/track1-sqlalchemy/final-audit.txt).
Код API, миграции, инфраструктура и lockfile с этого прогона не менялись.
После него `55b99a2` исправил только сохранение диагностических журналов подготовки нагрузки;
[повторные тесты и smoke](evidence/track1-sqlalchemy/diagnostics/setup-log-fix-checks.txt) прошли.
- Трек «Цена масштабирования» переснят на SQLAlchemy: baseline `5c8f605`,
оптимизация API `57744c5`, обвязка CPU-контроля `07965a2`, графики `3fb741e`.
Текущие измерения — `evidence/track1-sqlalchemy/`; старый raw asyncpg хранится отдельно.
- Изменения завершены: [трек](openspec/changes/archive/2026-11-06-remeasure-lab3-scaling/tasks.md)
и [SQLAlchemy/Alembic](openspec/changes/archive/2026-11-05-adopt-sqlalchemy-alembic/tasks.md)
архивированы 2026-11-06; главные specs синхронизированы.
- Источники и инструменты: FastAPI, gunicorn + uvicorn-worker, dishka, pydantic, structlog,
SQLAlchemy, Alembic, asyncpg как драйвер, argon2-cffi, redis-py, pytest, ruff, ty; версии —
`evidence/environment.txt` и `uv.lock`. Документация установленного SQLAlchemy проверена через
Context7: [async sessions](https://github.com/sqlalchemy/sqlalchemy/blob/rel_2_0_45/doc/build/orm/extensions/asyncio.rst),
[проверка соединений](https://github.com/sqlalchemy/sqlalchemy/blob/rel_2_0_45/doc/build/core/pooling.rst);
[кэширование статического SQL](https://github.com/sqlalchemy/sqlalchemy/blob/rel_2_0_45/doc/build/core/connections.rst);
Alembic — [async cookbook 1.16.5](https://github.com/sqlalchemy/alembic/blob/rel_1_16_5/docs/build/cookbook.rst).
Инфраструктура опирается на HAProxy 3.2 Manual, Docker Compose, PostgreSQL и k6.
Решение перенесено из собственной ЛР2; текущий этап выполнен с помощью Codex.
## Запуск из чистого clone
Требуются Git, Docker с Compose v2, `make`, `curl`, uv и системный Python 3.9+ для публичных
проверок и обвязки. `make install` устанавливает Python 3.14 и зависимости из `uv.lock`.
Образы сторонних сервисов закреплены версией и digest, API собирается из исходников.
Текущий результат ещё не опубликован. До этапа публикации чистый clone берётся из локального
репозитория с завершёнными коммитами; `LAB3_SOURCE` заменяется своим путём к нему.
Это копирует только Git-данные, без `.env`, secrets, `.venv` и volumes. После публикации
источником может быть private-репозиторий решения в MTUCI-Labs с тем же кодом.
```sh
LAB3_SOURCE="$HOME/projects/learning/HL/labs/mtusi2026lab3"
cd "$(mktemp -d)"
git clone --no-local --branch solution/bpi2303-kostylev "$LAB3_SOURCE" mtusi2026lab3
cd mtusi2026lab3
git rev-parse HEAD
export COMPOSE_PROJECT_NAME=mtusi2026lab3-local
export LB_HTTP_PORT=18083 LB_STATS_PORT=23083 API_REPLICAS=2
export NO_PROXY=localhost,127.0.0.1,::1 no_proxy=localhost,127.0.0.1,::1
make install
make secrets # secrets/*: пароли PostgreSQL и Valkey, DATABASE_URL, CACHE_URL, ключ курсора; .env из .env.example
docker compose --env-file .env config --quiet
make up # docker compose up -d --build --wait: postgres, valkey → migrate (миграции, один раз) → api ×2 → lb,
# затем scripts/lb-wait.sh: ждёт, пока статистика LB покажет UP у всех запущенных реплик
make test # публичный smoke через балансировщик (BASE_URL — опубликованный порт lb, см. ниже)
make lb-check # ≥2 X-Instance-Id на одном токене и 20 × 8 параллельных POST с одним ключом → evidence/lb-check.json
make retry-check # потерянный ответ на живой и на убитой реплике, повтор тем же ключом → evidence/retry.json
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make restore # вернуть остановленную реплику и дождаться её в ротации LB
curl -s -o /dev/null "http://$(docker compose port lb 8080)/health/live" # сдвиг round robin: следующий прогон остановит другую реплику
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && make restore
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make migrate # повторный alembic upgrade head, версия и данные не меняются
make storage-evidence # \d+ схемы, повтор миграций, префикс KDF, правила ignore и volumes проекта → evidence/
make down # безопасная остановка: контейнеры и сети удаляются, volumes с данными остаются
```
`make secrets` идемпотентен: существующие файлы не перезаписываются, значения нигде не печатаются; `make up`
вызывает его сам. `make up` ждёт `healthy` всех сервисов, включая балансировщик (он здоров, когда в ротации есть хотя
бы одна реплика, `/healthz` на порту статистики), а затем — пока в ротацию войдут все реплики: вторая входит после
`rise 2` проверок, примерно через 2,5 с, и без этого ожидания `make test-failover` сразу после `make up` мог увидеть
один `X-Instance-Id`. Миграции применяет одноразовый `migrate` под advisory lock
до старта реплик; реплики схему не трогают. Публикуются только порты `lb` на `127.0.0.1`: `LB_HTTP_PORT`
(по умолчанию 8080) и `LB_STATS_PORT` (8404, статистика только для чтения). В текущем прогоне переменные окружения задают `LB_HTTP_PORT=18083`,
`LB_STATS_PORT=23083`. Цели `make` берут `BASE_URL` по умолчанию из `docker compose port lb 8080`, то есть
работают и с изменённым `LB_HTTP_PORT`; без поднятого стенда — `http://localhost:8080`, явный `BASE_URL=…`
переопределяет. Цель failover-теста выбирает round robin (реплика, обслужившая первое сообщение); второй
прогон сразу после первого попадает в ту же реплику, поэтому перед ним нужен один запрос через LB (строка
`curl …/health/live` выше или `make failover-evidence SHIFT=1`).
До запуска следует проверить занятость 18083/23083 и выбрать свободное имя собственного
Compose-проекта. Чужие контейнеры не останавливаются. Дополнительные порты собственных тестов
автоматически выбираются в 23000–23999. `make reset-data` для воспроизведения не нужен.
Прогон уровня «3» выполнен из рабочего checkout, на новом Compose-проекте
`mtusi2026lab3-grade3-final-20261105` и пустых volumes, с указанными портами и без явного `BASE_URL`.
`evidence/grade3-start.txt` содержит пустой список volumes перед запуском, сборку, `make up`,
`docker compose ps -a` и версию Alembic `0002_idempotency_keys`. Старые volumes не удалялись.
Исторический запуск именно из clone сохранён в `evidence/clean-clone.txt` (`e049c26`);
он не подменяет проверки текущего SQL-слоя.
Собственные проверки и тулчейн (каталог команд; для стендовых целей начиная с
`make test-faults` предварительно выполнить `make up`, после проверок — `make down`):
```sh
make install # uv sync --group dev (Python 3.14 и зависимости из uv.lock)
make lint # ruff check + ruff format --check (src, student-tests, scripts/{probe,limits,scaling}.py, tools) + ty check
make student-test # собственные тесты; поднимают одноразовые PostgreSQL и Valkey того же образа в Docker
make student-test PYTEST_ARGS=-vv # то же с именами тестов (так снят evidence/student-tests.txt)
make check # офлайн-проверка skeleton
make validate # полная валидация OpenAPI 3.1 и примеров (openapi-spec-validator из dev-группы .venv)
openspec validate --all --strict
make test-faults # тесты стенда лабы 2 (Valkey, PostgreSQL, гонки) через балансировщик
make faults-evidence # то же с датой и коммитом → evidence/faults.txt (путь репозитория → <repo>)
make failover-evidence SHIFT=1 # docker inspect реплик до/после, make test-failover, логи остановленной, restore
make persistence-evidence # persistence-тест + StartedAt всех контейнеров до и после
make stack-evidence # сервисы, порты, hostname ↔ X-Instance-Id, лимиты, сети, взгляд LB
make storage-evidence # \d+ схемы, повтор миграций, префикс KDF, правила ignore
```
Для проверки specs нужен отдельно установленный CLI OpenSpec; это инструмент разработки,
не зависимость API. Проверки `make` используют окружение из `make install`.
Проверки уровня «4» выполняются после `make up` — по одной команде на пункт рубрики;
после них — `make down`. Каждая пишет файл в `evidence/` и завершается
ненулевым кодом при нарушении (`make level4` — все подряд):
```sh
make limits # лимиты, порты, секреты, volumes, сети по политике → evidence/limits.txt
make lb-check # 40 GET одним токеном + 20 раундов × 8 параллельных POST с одним ключом
make detection # три прогона: SIGTERM, kill, pause, остановка PostgreSQL → evidence/detection/run{1,2,3}/
make failover-each # каждая реплика: остановка, 10 с без неё, возврат — под k6 100 rps
make rolling-update FROM_REV=7fc911c # предыдущая SQLAlchemy-версия → текущая под нагрузкой
make rolling-update # замена текущей сборкой (эквивалентная поочерёдная замена)
```
Генератор нагрузки — сервис `k6` под профилем `bench` (с `make up` не стартует); `RATE` задаёт интенсивность.
Трек 1 выполняется последовательно на собственном Compose-проекте. Существующие volumes
сохраняются; каждый прогон создаёт новые синтетические чаты. Старые результаты asyncpg находятся
в `evidence/track1/`, новые — в `evidence/track1-sqlalchemy/`. Для повторного полного эксперимента
нужен новый `TRACK1`, чтобы не смешать номера повторов:
```sh
export COMPOSE_PROJECT_NAME=mtusi2026lab3-track5-local
export LB_HTTP_PORT=18083 LB_STATS_PORT=23083
make up
make track1 TRACK1=evidence/track1-local
make plots TRACK1=evidence/track1-local
make down
```
`make track1-images` собирает baseline SQLAlchemy из `BEFORE_REV=5c8f605cd3bd40245109348463d3e7111379b2d3`
и текущий образ. `track1-a` / `track1-b` используют baseline; `track1-compare` чередует
baseline и текущий образ на 8×1; `track1-control` исследует пул, maxconn и размещение baseline.
`make plots` использует только каталог выбранного TRACK1. Требуются 16 доступных vCPU Docker VM
для указанного pinning. После каждой серии возвращается обычная конфигурация двух реплик.
**Версии и стенд:** Python 3.14.7 в образе `python:3.14-slim-trixie@sha256:51dafde8…`,
`haproxy:3.2.26-alpine@sha256:58938405…`, `postgres:17.11-alpine@sha256:266d3c25…`,
`valkey/valkey:8.1.11-alpine@sha256:2602ace2…`, `grafana/k6:2.3.0@sha256:2dd4756e…`, uv 0.9.7 по digest,
Docker 28.3.2, Compose 2.38.2. Машина — Apple M4 Max, 16 CPU, 48 ГБ RAM, macOS 15.1; VM Docker Desktop —
16 CPU, 7.65 ГиБ (`evidence/environment.txt`).
## Архитектура и решения
```
┌── api (gunicorn, 2 × UvicornWorker) ──┐ SQLAlchemy async pool, 1–2 с
клиент ──HTTP──▶ lb (HAProxy 3.2) ───┤ X-Instance-Id = hostname ├──▶ postgres (источник истины, pgdata)
127.0.0.1:18083 round robin, └── api (gunicorn, 2 × UvicornWorker) ──┘──▶ valkey (кэш сессий, AOF, valkeydata)
httpchk /health/ready migrate (тот же образ, один раз до реплик) ──▶ postgres
сеть edge ─────── lb ─────── сеть backend (internal): lb, api, migrate, postgres, valkey
```
**Перенесено из лабы 2 без изменения поведения:** зоны `identity` и `messaging`, порты и адаптеры, UoW, шина
событий с журналом аудита, ASGI-конвейер, Basic → Bearer, Argon2id, сессии в PostgreSQL с read-through кэшем
в Valkey и отметками отзыва, подписанный курсор, порядок истории под блокировкой строки чата, миграции под
advisory lock, тесты стенда (`make test-faults`). Уже в лабе 2 реплика не держала в памяти ничего, от чего
зависит корректность: кэш и отметки отзыва общие (Valkey), курсор подписан общим секретом, отметка
`created_at` назначается под блокировкой строки чата, а не часами процесса. **Изменено:** один контейнер с
портом → сервис `api` с `deploy.replicas` за HAProxy; `X-Instance-Id`; обязательный `Idempotency-Key`;
миграция `0002`; `restart.sh` перезапускает и LB; таймауты и воркеры под реплики; удалён `api-shortttl`
(публиковал порт API в обход LB, проверка истечения TTL осталась in-process тестом). Лаба 3 начата с коммита
`8cddb09` лабы 2, а исправления лабы 2 после её ревью (`8cddb09..102579e`) перенесены отдельным циклом
`2026-10-30-carry-over-lab2-review-fixes` (`a59e3a3`): предел тела считает фактически принятые байты
(`chunked` сверх 1 MiB → `413`), выход отзывает сессию через порт `SessionRevocations` и снимает отметку отзыва,
если PostgreSQL отверг удаление (`503` значит «сессия ещё действует»), пустой `cursor` → `400`, зоны связаны только
схемой БД, воркер сам прерывает зависший при остановке запрос до `SIGKILL` мастера. После второго ревью этот ответ —
`503 unavailable` в формате контракта (был `text/plain 500` uvicorn без `X-Request-Id` и `X-Instance-Id`), readiness
стоит за портом `Readiness`, а окно вывода пишется событием `service.draining` (цикл `2026-10-30-close-lab3-second-review-gaps`).
**SQLAlchemy и Alembic.** ORM-модели и Core-запросы остаются в инфраструктуре зон;
домен — dataclass, pydantic — на HTTP-границе. `Database` создаёт async engine
`postgresql+asyncpg`, `async_sessionmaker(expire_on_commit=False)` и ограниченный пул без overflow.
Каждая операция получает собственный `AsyncSession`; незавершённая транзакция откатывается при закрытии.
`pool_pre_ping=True` проверяет соединение до его выдачи бизнес-операции. Без этого после возврата
PostgreSQL readiness могла уже быть успешной, а регистрация через другое соединение получала `503`.
Проверка заменяет закрытое соединение; уже начатые транзакции автоматически не повторяются.
Цена — дополнительное обращение к БД на выдаче открытого соединения; старые RPS трека к этому коду неприменимы.
One-shot `migrate` выполняет `alembic upgrade head` под advisory lock. Журнал — `alembic_version`,
актуальная ревизия — `0002_idempotency_keys`. На старом volume принимается только проверенная схема:
`alembic/legacy.py` сверяет журнал и каталог PostgreSQL, сохраняет строки и прежний `schema_migrations`.
Безусловного stamp нет. Свежая схема, сохранение данных, откат неуспешной миграции и два мигратора
проверяются в `student-tests/api/test_migrations.py`; повтор на реальном стенде — `evidence/migrations.txt`.
**`X-Instance-Id`.** `PlatformSettings.instance_id` по умолчанию — `socket.gethostname()`; Docker даёт
контейнеру hostname, равный короткому ID, поэтому значение одно на все воркеры реплики, стабильно на жизнь
контейнера и совпадает с `docker ps` (`evidence/stack.txt`). Конвейер ставит заголовок рядом с
`X-Request-Id` на каждый ответ, проходящий через него; ответ `500` формирует внешний `ServerErrorMiddleware`,
поэтому обработчик необработанных исключений ставит оба заголовка сам. `INSTANCE_ID` в compose не задаётся:
он был бы одинаков у всех реплик.
**Идемпотентная отправка (зона `messaging`).** Таблица `idempotency_keys (chat_id, user_id, key, fingerprint,
message_id, created_at)`, PK `(chat_id, user_id, key)` — область «пользователь + метод + путь чата + ключ»
(ключ бывает только у `POST …/messages`), FK `(chat_id, user_id) → chat_members` и `message_id → messages`,
`CHECK` формата ключа и длины отпечатка. Отправка — **один изменяющий SQL-оператор**
в транзакции SQLAlchemy с явным `session.commit()` (`PostgresMessageLog.post`, порт `MessageLog`).
CTE появился ещё в историческом треке raw asyncpg; до него было пять обращений,
три под блокировкой чата. Нынешний трек кэширует компиляцию уже существующего CTE:
1. CTE `chat`: строка чата `FOR UPDATE`, соединённая с членством отправителя; нет строки → `404`;
2. `created_at = GREATEST(часы реплики, last_message_at + 1 мкс)` — история чата не идёт назад;
3. `INSERT idempotency_keys … ON CONFLICT DO UPDATE … WHERE` ключ истёк — живой ключ не трогается;
4. `INSERT messages` только если ключ записан, `UPDATE chats.last_message_at`; сообщение и ключ фиксируются вместе через `session.commit()`;
5. ключ занят → следующая команда в том же `AsyncSession` читает квитанцию, моложе `IDEMPOTENCY_TTL_SECONDS`: тот же
отпечаток → сохранённое сообщение (`201`, тот же `MessageOut`, `created_at` с микросекундами); другой → `409`.
Порядок проверок отправки: сессия (`401`) → форма запроса: `Idempotency-Key`, malformed JSON, лишние поля и
типы (`400`, проверяет FastAPI до обработчика, чат не читается, поэтому ответ одинаков для существующего и
несуществующего чата) → доступ к чату (`404`) → текст (`400`). Текст проверяется до записи; если он невалиден,
отдельным чтением проверяется членство, чтобы посторонний получил `404`, а не `400` (тесты
`test_access_checked_before_body` и `test_request_shape_is_checked_before_access`, сценарии
`lab3-idempotent-messages` «Порядок проверок отправки сообщения»). Сообщение и ключ фиксируются вместе или не фиксируются вовсе; маркера «в обработке»
нет, поэтому после гибели реплики посреди запроса повтор с тем же ключом создаёт сообщение один раз.
Одновременные повторы одного ключа всегда идут в один чат и ждут на блокировке его строки; дождавшийся
получает конфликт ключа, а следующая команда в `READ COMMITTED` видит зафиксированную квитанцию. Внешний ключ
квитанции на сообщение проверяется в конце команды, поэтому ключ можно вставить раньше сообщения. Отпечаток —
SHA-256 канонического JSON распарсенной модели, поэтому порядок полей и пробелы не важны. Ответы `4xx`/`5xx`
ничего не пишут; `lock_timeout` теперь `503`, а не `500`. Отвергнуто: `SET NX` в Valkey (не атомарен с
`COMMIT`), отдельный маркер «processing» (залипает после отказа).
**Кэш компиляции SQLAlchemy.** Неизменный Core CTE обёрнут в
`lambda_stmt(post_message, enable_tracking=False)`: PostgreSQL Insert с ON CONFLICT
не предоставляет обычный cache key. Структура запроса статична; все идентификаторы,
текст, отпечаток и времена поступают отдельными bindparam в `session.execute`.
Кэш содержит скомпилированный SQL, а не сообщения или результаты. Явный COMMIT,
pre-ping и порядок блокировок сохраняются. Цена — один compiled объект на движок;
при изменении структуры запросов отключённое tracking нужно пересмотреть.
Документация версии 2.0.45 проверена через Context7:
[SQL compilation caching](https://github.com/sqlalchemy/sqlalchemy/blob/rel_2_0_45/doc/build/core/connections.rst).
**Балансировщик** (`infra/haproxy/haproxy.cfg`):
| Параметр | Значение | Зачем |
| --- | --- | --- |
| Обнаружение | `server-template api 8 api:8080`, `resolvers docker` (127.0.0.11), `init-addr none` | остановленная реплика пропадает из DNS, новая появляется без перезапуска LB и без `docker.sock` |
| Алгоритм | `balance roundrobin`, без `stick` | каждое новое соединение — следующая реплика; сессия общая, привязка не нужна |
| Проверка | `GET /health/ready`, `inter 1s fastinter 500ms downinter 2s fall 2 rise 2`, `timeout check 1s`, `init-state fully-down` | реплика без БД или в остановке выходит из ротации; вернувшаяся получает трафик только после проверок |
| Повторы | `retries 2`, `redispatch 1`, `retry-on conn-failure empty-response`; `disable-l7-retry` всем, кроме `GET` и `POST …/messages` с ключом | отказ соединения повторяется всегда (запрос не ушёл); после отправки — только безопасное к повтору; `POST /users`, `/chats`, вход не повторяются (`contracts/README.md`) |
| Соединения к API | `option http-server-close` | нет простаивающих keep-alive, за которые гонится остановка реплики |
| Таймауты | `connect 500ms`, `server 10s` > `REQUEST_TIMEOUT_SECONDS=8` > `statement_timeout` 2 с; `queue 3s`, `maxconn 64` на сервер | цепочка клиент > LB > приложение > БД |
| Ошибки LB | `502/503/504` — JSON `{"error":{…,"request_id"}}` с тем же `X-Request-Id` | формат контракта даже без реплик (`evidence/hooks.txt`) |
| `X-Request-Id` | непустой входящий до 200 символов пробрасывается, иначе uuid4 | приложение эхо-возвращает его |
| Остановка | `stop_signal: SIGUSR1`, `hard-stop-after 5s` | мягкий стоп внутри `stop_grace_period` 8 с |
**Остановка и процессы (уровень «4»).** По `SIGTERM` реплика сначала выходит из ротации и только потом
перестаёт принимать соединения. Каждый воркер запускает `DrainingServer` (наследник `uvicorn.Server`,
`src/messenger/gunicorn_conf.py`): после сигнала он поднимает флаг процесса `DRAINING`
(`shared/infrastructure/readiness.py`) и пишет `service.draining`; адаптер `DatabaseReadiness` за портом `Readiness`
проверяет флаг до пинга PostgreSQL, поэтому `/health/ready` отвечает `503`, `/health/live` — `200`, запросы обслуживаются как обычно, и так `DRAIN_SECONDS=2` — дольше худшего обнаружения `503`
балансировщиком (1,5 с). Затем uvicorn закрывает listener и дообрабатывает принятые запросы ещё
`SHUTDOWN_TIMEOUT_SECONDS − DRAIN_SECONDS − 1` = 3 с (не меньше таймаутов БД 1 + 2 с), а задачу запроса, не
завершённого к этому сроку, отменяет и выходит с кодом 0. Отмену ловит конвейер: пишет `request.cancelled` и, если
ответ ещё не начат, отвечает `503 unavailable` в общем формате с `X-Request-Id` и `X-Instance-Id`, затем пробрасывает
отмену дальше (без этого uvicorn отвечал своим `text/plain 500` без заголовков контракта); весь срок — ≤5 с < gunicorn `graceful_timeout` 6 с <
`docker stop -t 7` хука < `stop_grace_period: 8s` < 10 с, поэтому мастер gunicorn не доходит до `SIGKILL` воркера. Результаты до и после оптимизации приведены ниже с SHA каждого прогона.
Хук останавливает конкретный контейнер, соответствие hostname проверяется через `docker inspect`.
На реплику `cpus: 1`, `512m`, 2 воркера, пул 8: 2 × 2 × 8 = 32 соединения <
`max_connections=200`. API работает `read_only` с `tmpfs /tmp`.
**Проверки, период и максимум обнаружения.** `GET /health/ready` раз в `inter 1s`; после первого провала —
`fastinter 500ms`; `fall 2` провала — реплика исключена; `rise 2` успеха — возвращена; `timeout check 1s`;
у `DOWN`-реплики — `downinter 2s`. Readiness пингует PostgreSQL за ≤0,4 с (общий дедлайн на получение соединения и `SELECT 1`), то есть отвечает явным `503` раньше таймаута проверки. `init-state fully-down`: сервер, который
стартовал, появился через DNS или вернулся из `MAINT (resolution)`, получает трафик только после `rise 2`
проверок (без этого HAProxy делал его `UP/READY` сразу по DNS-ответу, и запросы уходили в ещё не слушающий
gunicorn — первый прогон `failover-each` показал `wredis` 19 и 49 без ошибок; это записано в `design.md`
изменения `2026-10-28-add-lab3-failover-operations`, сырьё того прогона заменено повторным с `init-state`).
Три серии на SQLAlchemy 2.0.45 (`252e3e3`), команда `make detection`:
| Отказ | Как замечает LB | Максимум обнаружения | Замер, с |
| --- | --- | --- | --- |
| `SIGTERM` (`docker stop -t 7`) | readiness `503` в окне вывода | 1,5 с | 1.069–1.266; остановка 2.535–2.665 |
| `docker kill` | отказ соединения, DNS | 1,5 с | 0.886–0.934 |
| `docker pause` | таймаут проверки | 3,5 с | 2.778–3.215 |
| Остановка PostgreSQL | readiness всех реплик `503` | 1,5 с до 0 `UP` | 1.196–1.263; через LB `503 unavailable` без `X-Instance-Id` |
Для ответившей `503` реплики максимум — `inter + (fall−1)·fastinter` = 1,5 с;
для зависшей — дополнительно `fall·timeout check`, итого 3,5 с. Измерение начинается перед
запуском docker CLI, статистика LB опрашивается раз в 50 мс; допуск — 0,25 с. Все 12 замеров
уложились в формулу даже без допуска, SIGTERM исключён до завершения остановки.
Возврат после команды восстановления — 1.953–3.095 с.
Данные: `evidence/detection/run{1,2,3}/*.json`, команда и SHA — `evidence/grade4-detection.txt`.
**Цепочка таймаутов** (проверяется тестом `student-tests/unit/test_timeouts.py` по `compose.yaml`,
`haproxy.cfg` и `scripts/stop-one.sh`, а не только таблицей):
| Звено | Значение | Условие |
| --- | --- | --- |
| LB `timeout server` | 10 с | > `REQUEST_TIMEOUT_SECONDS` |
| `REQUEST_TIMEOUT_SECONDS` | 8 с | > ожидание соединения + оператор БД |
| `DB_ACQUIRE_TIMEOUT_SECONDS` + `DB_COMMAND_TIMEOUT_SECONDS` (`statement_timeout` = `lock_timeout`) | 1 + 2 с | ≤ дообработки после окна |
| LB `timeout check` | 1 с | > readiness 0,4 с |
| `DRAIN_SECONDS` | 2 с | > обнаружения 1,5 с |
| дообработка после окна (uvicorn `timeout_graceful_shutdown`) | `SHUTDOWN − DRAIN − 1` = 3 с | ≥ таймаутов БД 1 + 2 с; затем зависший запрос → `503 unavailable` |
| `SHUTDOWN_TIMEOUT_SECONDS` (gunicorn `graceful_timeout`) | 6 с | > окна + дообработки; < `STOP_TIMEOUT` хука |
| `STOP_TIMEOUT` хука `stop-one.sh` | 7 с | < `stop_grace_period` 8 с < 10 с |
| LB `timeout connect` / `queue` | 0,5 с / 3 с | отказ соединения повторяется на соседа сразу |
| LB `hard-stop-after` | 5 с | < `stop_grace_period` LB 8 с |
| клиенты: resilience / smoke / k6 | 2 / 10 / 10 с | — |
**Хуки.** `scripts/stop-one.sh` — контейнер `api` с `.Config.Hostname == TARGET_INSTANCE_ID` → `docker stop -t 7`,
реплика остаётся остановленной, неизвестный ID → код 3 без изменений. `scripts/restart.sh` — `stop lb api`,
`restart postgres valkey`, `up -d --no-recreate --wait` (те же контейнеры, повторный `migrate`), volumes не
трогаются. `scripts/restore.sh` — `up --no-deps --no-recreate --wait api`, затем `scripts/lb-wait.sh` ждёт, пока
статистика LB покажет все реплики `UP`.
**Роли и сервисы** (`compose.yaml`; сети `edge` и `backend` с `internal: true`):
| Роль | Сервис | Версия / digest | Health / readiness | Volume | Сеть / порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| load_balancer | `lb` | `haproxy:3.2.26-alpine@sha256:58938405…`, uid 99, `read_only`, `cap_drop: ALL` | `/healthz` :8404 (`nbsrv(api) ≥ 1`); проверяет реплики `GET /health/ready` | нет | `edge` + `backend`; `127.0.0.1:${LB_HTTP_PORT:-8080}`, `127.0.0.1:${LB_STATS_PORT:-8404}` | нет |
| api ×`API_REPLICAS` | `api` | сборка из `Dockerfile`, python по digest, uid 10001, `read_only` | `GET /health/ready` (пингует PostgreSQL) | нет | `backend`, порт не публикуется | secrets `database_url`, `cache_url`, `cursor_secret` через `*_FILE` |
| postgres | `postgres` | `postgres:17.11-alpine@sha256:266d3c25…`, uid 70, `pg_stat_statements` | `pg_isready` | `pgdata:/var/lib/postgresql/data` | `backend` | secret `postgres_password` через `POSTGRES_PASSWORD_FILE` |
| сессии (кэш) | `valkey` | `valkey/valkey:8.1.11-alpine@sha256:2602ace2…`, uid 999 | `valkey-cli ping` с паролем | `valkeydata:/data` (AOF) | `backend` | secret `valkey.conf` (`requirepass`) |
| bootstrap | `migrate` | образ api, `restart: "no"` | код выхода 0 | нет | `backend` | secret `database_url` |
| генератор нагрузки (профиль `bench`) | `k6` | `grafana/k6:2.3.0@sha256:2dd4756e…`, uid хоста | нет | нет (скрипт `infra/k6` только для чтения) | только `edge`, порт не публикуется | нет |
Готовность реплики зависит только от PostgreSQL: Valkey — кэш, при его отказе проверка идёт в БД. Общее
хранилище сессий — PostgreSQL (источник истины) плюс общий Valkey. Bootstrap: `make secrets` (идемпотентен,
не перезаписывает существующие файлы), `make up` (миграции — `migrate` под advisory lock); повтор безопасен
(`make migrate` → код 0, версия Alembic и счётчики строк неизменны). Лимиты: lb 1 CPU/128m, api 1 CPU/512m на реплику, migrate 0.5/256m,
postgres 2/1g, valkey 0.5/128m, k6 2/512m (`make limits` сверяет их и изоляцию с политикой).
**Соответствие `.env.example` реальной конфигурации:**
| `.env.example` | В решении | Комментарий |
| --- | --- | --- |
| `APP_HOST`, `APP_PORT` | `HOST`, `PORT` | заданы в образе (`0.0.0.0:8080`); снаружи — порт LB `LB_HTTP_PORT` |
| `APP_ENV` | не используется | режимов окружения нет |
| `SESSION_TTL_SECONDS` | `SESSION_TTL_SECONDS` | по умолчанию 3600 |
| `DATABASE_URL_FILE` | `DATABASE_URL_FILE` | любой параметр читается из `<ИМЯ>_FILE` |
| `SESSION_STORE=postgres` | фиксировано | PostgreSQL — источник истины сессий, Valkey — кэш поверх него |
| `CACHE_URL_FILE` | `CACHE_URL_FILE` | без него кэш выключен |
| `API_REPLICAS` | `deploy.replicas: ${API_REPLICAS:-2}` | число реплик сервиса `api` |
| `IDEMPOTENCY_TTL_SECONDS` | `IDEMPOTENCY_TTL_SECONDS` | 86 400; квитанция старше срока перезаписывается новым запросом |
| — | `LB_HTTP_PORT`, `LB_STATS_PORT` | опубликованные порты LB на `127.0.0.1` |
| — | `API_CPUS`, `API_MEMORY`, `WEB_CONCURRENCY`, `DB_POOL_MAX_SIZE`, `API_SERVER_MAXCONN` | размер реплики, воркеры, пул на воркер, очередь LB на сервер |
| — | `PG_MAX_CONNECTIONS`, `PG_CPUS`, `PG_MEMORY`, `LB_CPUS` | лимиты PostgreSQL и LB |
| — | `REQUEST_TIMEOUT_SECONDS`, `DRAIN_SECONDS`, `SHUTDOWN_TIMEOUT_SECONDS` | 8 с, 2 с и 6 с (заданы в compose и образе) |
| — | `DB_ACQUIRE_TIMEOUT_SECONDS`, `DB_COMMAND_TIMEOUT_SECONDS` | 1 с и 2 с: ожидание соединения из пула и `statement_timeout` = `lock_timeout` |
| — | `K6_CPUS`, `K6_MEMORY` | лимиты генератора нагрузки (профиль `bench`) |
| — | `API_CPUSET`, `LB_CPUSET`, `PG_CPUSET`, `VALKEY_CPUSET`, `K6_CPUSET` | закрепление за CPU для трека 1; пусто — не закреплено |
| — | `CURSOR_SECRET_FILE` | общий ключ подписи курсора для всех реплик |
## Доказательства критериев
Актуальный итог — повтор всех уровней после кэширования SQL в таблице «Повтор проверок
после оптимизации» ниже и [revalidation](evidence/track1-sqlalchemy/revalidation/commands.txt).
Следующие две таблицы сохраняют отдельное закрытие уровней «3»/«4» **до оптимизации**;
их числа относятся только к названным SHA. Старый raw asyncpg явно отделён в
[индексе evidence](evidence/README.md) и не доказывает текущую производительность.
Проверки уровня «3» до оптимизации выполнены 2026-11-05 на `0a1f48bd73e5780c732356880c23fdb476bcff98`.
Стенд — `mtusi2026lab3-grade3-final-20261105`, LB `127.0.0.1:18083`, статистика `23083`;
`BASE_URL` автоматически определяется Makefile. Даты, команды, коды завершения и SHA — в `evidence/`.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| **3.1** Документированный запуск, ≥2 API, общая БД и сессии, одна точка входа | `make up`; `make stack-evidence` | Новые пустые volumes; `migrate` завершился с 0, версия `0002_idempotency_keys`; обе API healthy/UP, один PostgreSQL и Valkey; API без опубликованных портов, только LB на 18083/23083; `container_name` отсутствует | `evidence/grade3-start.txt`, `evidence/stack.txt`, `evidence/environment.txt` |
| **3.2** Один токен работает через разные реплики | `make lb-check` | 40 GET: `1b4a73f61b07` и `8ffe0c70f4ea` по 20 ответов; hostname совпадают с двумя контейнерами | `evidence/grade3-lb-check.txt` (актуальный `lb-check.json` повторно снят на этапе grade4), `evidence/stack.txt` |
| **3.3** Остановка любой одной реплики, чтение/запись ≤10 с | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`; `docker compose ps -a`; `make restore`; сдвиг round robin и повтор | По очереди остановлены `api-1` (`8ffe0c70f4ea`) и `api-2` (`1b4a73f61b07`), обе с `Exited (0)`; сосед продолжал работать. Первая запись после хука через 2.762 / 2.817 с, 129 / 128 успешных записей, 0 / 0 ошибок, по 2 наблюдаемых реплики; история подтверждённых сообщений сохранена | `evidence/failover-current-1.txt`, `evidence/failover-current-2.txt`, `evidence/grade3-restore-1.txt`, `evidence/grade3-restore-2.txt` |
| **3.4** Конкурентный одинаковый ключ и смена реплики | `make lb-check` | 20 раундов × 8 POST: 160 ответов 201, по 80 от каждой реплики; 20/20 одинаковых тел, одна копия в истории, другой body → 409 | `evidence/grade3-lb-check.txt` (актуальный `lb-check.json` повторно снят на этапе grade4) |
| **3.4** Безопасный повтор неподтверждённой записи | `make retry-check` | При блокировке чата 1.5 с клиент прекращает ожидание через 0.5 с. Повтор с тем же ключом на другой реплике: 201 с первой попытки, одна копия и тот же ID. Оба варианта — живая реплика и `docker kill` ожидающей реплики — прошли; повтор через 1.539 / 1.551 с | `evidence/retry.json`, `evidence/grade3-retry.txt` |
| **3.5** Публичный smoke, persistence и failover | `make test`; `make persistence-evidence` (вызывает `make test-persistence ACTION_SCRIPT=scripts/restart.sh`); два failover выше | Все PASS. При persistence прежний токен и история сохранились, IDs контейнеров те же, StartedAt у lb, обеих API, postgres, valkey и migrate обновились | `evidence/smoke.txt`, `evidence/persistence.txt`, `evidence/grade3-persistence.txt`, `evidence/failover-current-*.txt` |
| Перенос lab2: миграции, схема и повтор без изменения данных | `make up` на пустых volumes; `make storage-evidence` | PK/FK/UNIQUE/CHECK и индексы показаны в схеме; Alembic head `0002_idempotency_keys`. Повтор миграций: код 0, до/после 70 users, 24 sessions, 6 chats, 12 members, 284 messages и 284 keys, 1 строка версии | `evidence/schema.txt`, `evidence/migrations.txt`, `evidence/grade3-storage.txt` |
| Перенос lab2: KDF, сессии, секреты | `make storage-evidence`; `make test`; `make test-faults` | Все 70 паролей — Argon2id, 24 хеша токенов по 32 байта; секреты и .env не отслеживаются Git. Basic/Bearer, logout 204 → 401 и абсолютный TTL сохраняются | `evidence/kdf.txt`, `evidence/secrets.txt`, `evidence/smoke.txt`, `evidence/faults.txt` |
| Перенос lab2: отказы PostgreSQL/Valkey | `make test-faults` | 12 passed. PostgreSQL недоступен → 503 за ≤0.014 с, live внутри API 200; после старта ready через 2.0 с, прежний токен 200, 40 новых регистраций 201 через обе реплики без рестарта API. Valkey обходится для проверки сессии, logout при отказе 503 и после возврата 204 | `evidence/faults.txt` |
| Негативные случаи и заголовки, гонки, миграции | `make student-test PYTEST_ARGS=-vv` | 271 passed, 12 deselected (стендовые тесты запущены отдельно). Включены X-Instance-Id/X-Request-Id на ошибках, ключи/доступ/TTL, 22 миграционных теста и первый POST после закрытия соединения | `evidence/student-tests.txt` |
| Контракт, OpenAPI, форматирование и типы | `make check`; `make validate`; `make lint`; `uv lock --check`; `openspec validate --all --strict` | Все успешно; 107 файлов соответствуют формату. Diff нормативных файлов против upstream пуст | `evidence/checks.txt` |
| Остановка без удаления данных | `make down`; `docker compose ps -a`; `docker volume ls --filter label=…` | Контейнеров этапа нет; оба volumes финального и исходного прогонов сохранены | `evidence/grade3-stop.txt`, `evidence/grade3-initial-stop.txt` |
**Уровень «4» до оптимизации подтверждён на SQLAlchemy**, код `252e3e3ffeea5004cfd9dc342e686af1417a77a2`.
Проект `mtusi2026lab3-grade4-20261105`, порты `18083/23083`; запуск и версии — `grade4-start.txt`.
Старые замеры raw asyncpg доступны через `git show 72a1e57:evidence/<имя>`.
Нагрузка — k6 open model из `edge` в `lb:8080`: 100 запросов/с, 80 % отправок сообщений,
20 % чтений истории, 20 пользователей и 10 чатов, прогрев 10 с, замер 60/90 с.
Отдельный зонд пишет каждые 0,1 с; после ошибки повторяет тот же ключ, после прогона читает
все страницы своего чата и сверяет тела Message. Время восстановления теперь считается
по завершению успешного ответа после последней ошибки; отсутствие такого ответа, дубли,
потери, dropped iterations или отсутствующая статистика LB делают прогон неуспешным.
14 регрессионных тестов покрывают эти случаи. В итоговых прогонах ошибок зонда нет,
поэтому recovery_s = 0; время первого успешного ответа после начала действия указано отдельно.
| Критерий README | Команда | Наблюдение | Доказательство |
| --- | --- | --- | --- |
| **4.1** Readiness, SIGTERM и таймауты | `make student-test PYTEST_ARGS='-v -s student-tests/api/test_drain.py student-tests/unit/test_timeouts.py'` | 3 passed. LB 10 с > запрос 8 с > acquire+SQL 3 с; drain 2 с > обнаружение 1,5 с; shutdown 6 с < hook 7 с < grace 8 с. Настоящий gunicorn: ready/live 503/200, принятый запрос 201, зависший 503 с обоими заголовками; тестовое окно 1 с, порт закрыт через 1,05 с, выход через 2,44 с | `evidence/grade4-drain.txt` |
| **4.1** Обнаружение отказа | `make detection` | 12/12 PASS; SIGTERM 1,069–1,266 с, kill 0,886–0,934 с, pause 2,778–3,215 с, PostgreSQL 1,196–1,263 с. Все в пределах формулы без допуска; SIGTERM исключён до конца остановки | `evidence/grade4-detection.txt`, `evidence/detection/` |
| **4.2** Каждая реплика под нагрузкой | `make failover-each RATE=100` | Два прогона, по 6001 запросу, 0 ошибок и dropped; конкретная реплика Exited (0), сосед healthy; исключённая реплика не обслуживает зонд, после restore возвращается; история полностью совпадает | `evidence/grade4-failover-each.txt`, `evidence/failover-each/<hostname>/action.txt`, `result.json`, `probe.csv`, `lb_up.csv`, `k6/` |
| **4.2** Общая идемпотентность | `make lb-check` | 20 × 8 параллельных POST: 160 × 201, по 80 от каждой реплики; 20/20 одинаковых тел, единственных копий и конфликтов другого body | `evidence/grade4-baseline.txt`, `evidence/lb-check.json` |
| **4.3** Лимиты и изоляция | `make limits`; `docker inspect` во время k6 | CPU/MiB: API 1/512 на реплику, LB 1/128, PostgreSQL 2/1024, Valkey 0,5/128, migrate 0,5/256, k6 2/512. Лимиты реально применены; только LB публикует порты на loopback, API read_only и без container_name; secrets/volumes/сети соответствуют политике | `evidence/limits.txt`, `evidence/grade4-runtime-limits.txt` |
| **4.3** Отрицательная проверка политики | `scripts/limits.py` с override из лога | Все 5 нарушений обнаружены, ожидаемый exit 1; конфигурация не применялась к стенду | `evidence/grade4-limits-negative.txt`, `evidence/limits-violations.txt` |
| **4.4** Поочерёдная замена | `make rolling-update RATE=100`; `make rolling-update FROM_REV=7fc911c RATE=100` | В обоих прогонах минимум 2 UP, по 9001 запросу, 0 ошибок/dropped, 913/913 сообщений зонда сохранены; после действия отвечают только новые контейнеры. Старые/новые image ID записаны для каждой замены | `evidence/grade4-rolling*.txt`, `evidence/rolling/`, `evidence/rolling-from-7fc911c/` |
| **4.4** Один migrate и совместимость | `scripts/rolling-update.sh`; повтор `make migrate` | В каждом action.txt один migrate перед первой заменой. Обе версии SQLAlchemy используют ту же схему Alembic; повтор upgrade head не меняет версию и счётчики таблиц | `evidence/rolling/action.txt`, `evidence/rolling-from-7fc911c/action.txt`, `evidence/grade4-migration-repeat.txt` |
Измерения поочерёдного отказа:
| Остановленный hostname | RPS | p50/p95/p99, мс | Обнаружение, с | Первый успешный ответ, с | Возврат в LB от начала действия, с | Подтверждено = в истории |
| --- | --- | --- | --- | --- | --- | --- |
| `7cfd91ddf780` | 100.02 | 2.97/3.86/4.47 | 0.884 | 0.023 | 14.885 | 645 = 645 |
| `5bbf259ff136` | 100.02 | 2.98/3.88/4.53 | 1.498 | 0.111 | 14.990 | 642 = 642 |
Возврат включает намеренные 10 с без реплики и её запуск; это не перерыв доступности записи.
Счётчики LB `wretr/wredis/econ/eresp/hrsp_5xx` равны нулю в обоих отказах и обоих rolling update.
Опрос LB под нагрузкой — каждые 100 мс; более короткий провал таким измерением не исключается.
| Rolling update | RPS | p50/p95/p99, мс | Действие, с | Первый успешный ответ, с | Минимум UP |
| --- | --- | --- | --- | --- | --- |
| Сборка `252e3e3` | 100.01 | 3.01/3.89/4.53 | 10.734 | 0.055 | 2 |
| `7fc911c` → `252e3e3` | 100.01 | 2.99/3.85/4.47 | 13.836 | 0.082 | 2 |
**Ограничение миграционного доказательства:** `7fc911c` — предыдущая SQLAlchemy-версия до исправления
восстановления пула, с той же схемой `0002_idempotency_keys`. Миграция в rolling update — no-op.
Это подтверждает однократный запуск и совместную работу версий на существующей схеме, но не произвольный DDL
под нагрузкой. Будущие миграции требуют expand/contract и отдельной проверки совместимости.
Подготовительная установка старого образа выполняется до запуска нагрузки; непрерывность гарантируется
измеренным окном поочерёдной замены. Новый image ID той же сборки может отличаться из-за аттестации BuildKit.
Публичные сценарии после замены, итоговые проверки и остановка — `evidence/grade4-public.txt`,
`grade4-checks.txt`, `grade4-student-tests.txt`, `grade4-stop.txt`.
Повтор persistence в `grade4-persistence-scoped.txt` фиксирует неизменные IDs и обновлённые StartedAt
всех шести контейнеров. Полный набор собственных тестов — 285 passed, 12 deselected (stack).
Неуспешный smoke через системный прокси, прерванный detection, первоначальные ошибки форматирования
и некорректная отрицательная Compose-fixture сохранены; причины и итоговые повторы перечислены
в `evidence/README.md`. Эти попытки не считаются PASS.
**Трек 1 «Цена масштабирования» на SQLAlchemy.** Полная методика и ограничения — ниже;
поля сырья и происхождение образов — `evidence/track1-sqlalchemy/README.md`.
| Критерий трека README | Команда/сценарий | Наблюдение | Файл доказательства |
| --- | --- | --- | --- |
| Методика и гипотеза | `make track1` (цели выполнены последовательно) | 135 основных точек, ≥3 повтора; собственный Compose project, снимок хоста; история попыток сохранена | `{host.txt,README.md,baseline-run.txt,comparison-run.txt,corrected-cpus-run.txt}` |
| 1/2/4 реплики при фиксированных CPU/RAM | `make track1-a` | 4 CPU/2 GiB: пики 2687/2532/2422 RPS; SLO по сетке 2020 у всех | `series-a/summary.csv`, `plots/series-a-*.png` |
| Рост ресурсов | `make track1-b` | 1→2→4→8 CPU: пики 751→1307→2422→3420; на 8 CPU эффективность 56.9% от линейной | `series-b/summary.csv`, `plots/scaling.png` |
| Saturation point и предел масштабирования | `make track1-control`; CPU-рецепт повторён после исправления порядка | API достигает CPU-квоты; на 8×1 растут Lock и очередь. Пул 16 снижает RPS на 13.7%, maxconn64 тоже хуже; 8×0.5 медленнее 4×1 на тех же CPU | `control-{pool,cpus}/summary.csv`, `plots/utilisation.png` |
| Подтверждённое улучшение | `make track1-compare` | 2400 rps: p95 14.28→4.63 мс, CPU −29.3%; 5400 rps: успешные RPS 3629→3946 (+8.7%); min–max не пересекаются | `compare/summary.csv`, `plots/compare-*.png` |
| Исходные данные и графики | `make plots`; скрипт аудита в `audit.txt` | 12 PNG, capacity.csv/md; 135 точек сверены с k6 JSON и реальными image/CPU/RAM/cpuset | `plots/`, каталоги сырых прогонов, `audit.txt` |
Все пути таблицы — относительно `evidence/track1-sqlalchemy/`. Исходные 12 CPU-контролей с неверным
порядком и промежуточные неуспехи сохранены в `evidence/track1-sqlalchemy/diagnostics/`.
**Повтор проверок после оптимизации — код `3fb741e`.** API идентичен `57744c5`,
образ SQLAlchemy 2.0.45 с активным compiled cache проверен внутри контейнера до и после rolling.
Команды и коды завершения — `evidence/track1-sqlalchemy/revalidation/commands.txt`;
это итоговые проверки поведения API; предыдущие доказательства уровней «3»/«4» сохранены
как история последовательного закрытия критериев.
| Проверка | Команда | Результат | Файл внутри `track1-sqlalchemy/` |
| --- | --- | --- | --- |
| Контракт и тулчейн | `make check validate lint`; `uv lock --check`; `make student-test` | PASS; 290 passed, 12 deselected | `revalidation/commands.txt` |
| Публичные сценарии | `make test`; `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | PASS; прежний токен и подтверждённая история сохранены; остановленная реплика видна в `docker compose ps -a`, выполнен restore | `revalidation/commands.txt` |
| Ограничения и повторы | `scripts/limits.py`; `scripts/probe.py check --rounds 20`; `scripts/probe.py retry` | PASS; 160 ответов 201 без дублей, обе реплики; потерянный ответ и kill — оба PASS | `revalidation/{limits.txt,lb-check.json,retry.json}` |
| Обнаружение, три повтора | `sh scripts/detection.sh <out>` | 12/12 PASS: SIGTERM 0.899–1.326 с; kill 0.273–0.795 с; pause 2.783–3.281 с; PostgreSQL 1.201–1.255 с | `revalidation/detection/run{1,2,3}/` |
| Каждая реплика под 100 rps | `sh scripts/failover-each.sh <out>` | d4dfe6128c9d: 6001 запрос, p95 4.39 мс; a855a190991a: 6000, p95 4.33 мс. 0 ошибок/dropped, по 661 подтверждённому сообщению, история точна; Exited и живой сосед в action.txt | `revalidation/failover-each/` |
| Rolling baseline → cached | `probe.py load --expect replace --duration 90 -- scripts/rolling-update.sh` | 9001 запрос, p95 4.18 мс, 0 ошибок/dropped; min UP=2, один migrate; 938 сообщений сохранены без дублей | `revalidation/rolling/` |
| Отказы зависимостей | `make test-faults`; финальный `make test` | 12 passed; smoke PASS | `revalidation/commands.txt` |
| Безопасная остановка | `docker compose --profile bench down` только своего project | Все контейнеры проекта удалены, оба volumes сохранены | `stop.txt` |
После полного прогона исправлен только формат журналов подготовки (`55b99a2`):
`.txt` с датой/SHA вместо игнорируемого `.log`. В сохранённом сырье было три ошибки
`LB unhealthy` до запуска k6; повтор compose и ожидание UP завершились успешно.
Дополнительные 290 тестов и smoke прошли, стенд снова остановлен с сохранением volumes
(`diagnostics/setup-log-fix-checks.txt`). Финальный аудит — `final-audit.txt`.
**Финализация отчёта — 2026-11-06.** Изменены только документы и журнал их проверки,
основа — `f591fa64e525679a31c9db7f942d36c789e1a12f`. Повторены `make check`,
`make validate`, `make lint`, `make student-test` (290 passed, 12 deselected),
`uv lock --check`, `openspec validate --all --strict` (14 passed):
[журнал](evidence/report-checks.txt). Стендовые 12 тестов и нагрузка относятся к
revalidation выше; на этапе report они не запускались повторно.
[Аудит](evidence/report-audit.txt) проверяет ссылки, исходные метрики, версии кода
и неизменность нормативных файлов. Публикаций и отправок Telegram не было.
## Эксперименты и отказы
Итоговый код API после оптимизации (`3fb741e`, API идентичен `57744c5`), k6 100 rps.
В каждом failover реально остановленный контейнер и работающий сосед показаны в `action.txt`
рядом с `result.json`. «Первый ответ» отсчитывается от начала действия и не является
временем простоя: ошибок зонда не было, измеренный `recovery_s=0`.
| Сценарий | RPS; p95/p99, мс | Обнаружение / первый ответ / возврат, с | Ошибки k6 / зонда; dropped; потери / дубли | Evidence |
| --- | --- | --- | --- | --- |
| Остановка `a855a190991a` | 100.00; 4.33/5.15 | 1.018 / 0.058 / 14.480 | 0 / 0; 0; 0 / 0, история 661 = 661 | [result](evidence/track1-sqlalchemy/revalidation/failover-each/a855a190991a/result.json), [контейнеры](evidence/track1-sqlalchemy/revalidation/failover-each/a855a190991a/action.txt) |
| Остановка `d4dfe6128c9d` | 100.02; 4.39/5.23 | 1.145 / 0.096 / 16.127 | 0 / 0; 0; 0 / 0, история 661 = 661 | [result](evidence/track1-sqlalchemy/revalidation/failover-each/d4dfe6128c9d/result.json), [контейнеры](evidence/track1-sqlalchemy/revalidation/failover-each/d4dfe6128c9d/action.txt) |
| Rolling baseline → cached | 100.01; 4.18/5.16 | первый ответ 0.037; действие 11.160; минимум 2 UP | 0 / 0; 0; 0 / 0, история 938 = 938 | [result](evidence/track1-sqlalchemy/revalidation/rolling/result.json), [замены и migrate](evidence/track1-sqlalchemy/revalidation/rolling/action.txt) |
Возврат реплики включает намеренные 10 с в остановленном состоянии. Отсутствие ошибок
в этих окнах не гарантирует отсутствия более коротких провалов между запросами зонда.
Публичный failover отдельно подтвердил 131 запись, 0 ошибок и первую запись после хука
через 2.624 с; persistence сохранил прежнюю сессию и историю
([журнал](evidence/track1-sqlalchemy/revalidation/commands.txt)).
История уровня «3» **до оптимизации**, код `0a1f48b`; все числа ниже взяты из указанных файлов.
| Сценарий | Наблюдение | Сохранность и возврат | Evidence |
| --- | --- | --- | --- |
| Остановка api-1 | 129 записей, 0 ошибок; первая запись после хука через 2.762 с | История без дублей, api-2 работает, api-1 Exited (0), затем восстановлена | `failover-current-1.txt`, `grade3-restore-1.txt` |
| Остановка api-2 | 128 записей, 0 ошибок; первая запись после хука через 2.817 с | История без дублей, api-1 работает, api-2 Exited (0), затем восстановлена | `failover-current-2.txt`, `grade3-restore-2.txt` |
| Потерянный ответ и kill | Таймаут клиента 0.5 с при блокировке чата 1.5 с; повтор через соседа 201 | Одна копия, одинаковый ID; оба варианта pass | `retry.json`, `grade3-retry.txt` |
| Полный restart | StartedAt всех сервисов обновились, IDs прежние | Старая сессия и история сохранились | `persistence.txt` |
| PostgreSQL остановлен | 503 за ≤0.014 с, live внутри API 200; LB исключил реплики ещё через 0.86 с | После запуска ready через 2.0 с; 40 регистраций через 2 реплики без рестарта API | `faults.txt` |
| Valkey остановлен | Живой токен 200, неизвестный 401; logout 503 | После запуска logout 204; рестарт Valkey сохраняет отзыв | `faults.txt` |
| Повтор Alembic | Код 0, head не меняется | Все счётчики строк до и после равны | `migrations.txt`, `grade3-storage.txt` |
Первый прогон не был успешным: `grade3-faults.txt` содержит 11 passed / 1 failed — регистрация получила
503 после возврата PostgreSQL. `grade3-pool-regression-before.txt` воспроизводит закрытое простаивающее
соединение; `pool_pre_ping` устранил ошибку (`grade3-pool-regression-after.txt`, итоговый `student-tests.txt`).
Полный набор также был прерван на коллизии порта тестового gunicorn с LB (46 passed,
`grade3-student-tests-interrupted.txt`), затем упал при старте тестовой БД (70 passed / 201 errors,
полный обезличенный вывод сжат в `grade3-student-tests-startup.txt.gz`). Исправлены изоляция порта,
дедлайн ожидания и повтор временного SQLSTATE 57P03. После исправлений итоговые 271 собственный
и 12 стендовых тестов прошли. Публичные проверки не менялись.
### Трек 5 — трек 1 «Цена масштабирования» на SQLAlchemy
Все текущие результаты лежат в `evidence/track1-sqlalchemy/`. Baseline API —
`5c8f605cd3bd40245109348463d3e7111379b2d3`, после оптимизации —
`57744c532c58d3e2bd248b4368ecba0a42402ed8`. В обоих SQLAlchemy 2.0.45, asyncpg — драйвер,
pre-ping и явный COMMIT включены. SHA обвязки A/B — `05d69ba`, сравнения/пула — `57744c5`, CPU-контроля — `07965a2`;
`metadata.json` каждой точки хранит фактический image ID и CPU/RAM/cpuset контейнеров.
`baseline-run.txt` и `comparison-run.txt` содержат команды и все итоговые строки.
Исторический `evidence/track1/` не входит ни в текущие таблицы, ни в графики.
**Гипотеза.** Компиляция неизменного CTE отнимает CPU API. Её кэширование должно снизить
p95 или повысить успешные RPS без изменения SQL, ресурсов и контракта. Дополнительные
реплики не снимают сериализацию горячего чата и ожидание COMMIT. Гипотеза и методика
зафиксированы до основных серий в `remeasure-lab3-scaling` (коммит `74a39fa`).
**Отличие от старых измерений.** Исторический raw asyncpg после перехода на CTE
(`22f0e62`, `evidence/track1/plots/capacity.csv`, compare/after/8×1) показывал пик
4894.23 RPS при 5400 предложенных. Нынешний SQLAlchemy после кэширования — 3945.63.
Это разные даты, объёмы БД и программные пути: теперь есть pre-ping, SQLAlchemy session
и явный COMMIT. Разница не является изолированным замером стоимости ORM; старое
`idle in transaction ≈0` к новому пути неприменимо. Подтверждение нового улучшения
берётся только из чередующегося SQLAlchemy before/after, приведённого ниже.
**Методика.** Последовательная открытая нагрузка k6: 80% POST с новым ключом, 20% GET
первой страницы (limit=50), 20 пользователей/10 чатов; 10 с прогрева и 30 с измерения,
5 с паузы, три повтора каждой точки. Итого 135 основных прогонов: A 54, B 36,
сравнение 18, пул/maxconn 15, CPU-контроль 12. Пилот по одному повтору — только диагностика. Ещё 12 первоначальных CPU-контролей
сгруппированы по конфигурациям из-за ошибки runner; они сохранены в
`diagnostics/ordered-control-cpus` и не входят в медианы. Ошибка закрыта регрессией
порядка; все 12 точек пересняты (`corrected-cpus-run.txt`).
До/после чередуются блоками интенсивностей внутри каждого повтора; контроли — baseline.
SLO: p95 ≤500 мс, ошибок ≤1%, dropped iterations ≤1% предложенных. Насыщение интенсивности
определяет большинство повторов; поиск останавливается после двух полностью насыщенных
интенсивностей подряд. «Пик» — максимум медианы успешных RPS; это не предел по SLO.
Граница SLO зависит от сетки: если прошла только первая точка, показывается ≥ этой точки.
Volumes сохранялись. Каждая точка использует новые синтетические чаты; размер БД
в основных сериях вырос с 33.2 до 4597.3 MiB. В измерительных окнах k6 завершил
8 271 783 запроса; это не количество сохранённых сообщений. Размер и оценка
n_live_tup записаны в summary. A: 1×4/2×2/4×1 при 4 CPU/2 GiB, 4 воркерах, суммарном пуле 32 и maxconn 128,
CPU 7–10. B: 1→2→4→8 по 1 CPU/512 MiB, 4×1 берётся из A. Общие зависимости неизменны:
PG 2 CPU/1 GiB, CPU 0–1; LB 1 CPU/128 MiB, CPU 2; Valkey 0.5 CPU/128 MiB, CPU 3;
k6 3 CPU/1 GiB, CPU 4–6. PG max_connections=200, shared_buffers=256 MiB.
Подробные VU-лимиты, отбраковка помех и смысл полей — `evidence/track1-sqlalchemy/README.md`.
Таблицы ниже: медиана, в скобках min–max трёх повторов (не доверительный интервал);
CPU — проценты одного ядра.
**A: одинаковые ресурсы.**
| API | SLO, rps | Пик RPS (min–max) | При нагрузке | p95 при 2020, мс | CPU API / PG / LB на пике | Lock / idle transaction на пике |
| --- | --- | --- | --- | --- | --- | --- |
| 1x4 | 2020 | 2687.13 (2686.43–2691.07) | 4560 | 5.86 | 409.4 / 92.7 / 22.4 | 1.33 / 17.50 |
| 2x2 | 2020 | 2531.80 (2520.70–2536.67) | 3040 | 9.36 | 408.1 / 89.1 / 21.6 | 1.69 / 16.81 |
| 4x1 | 2020 | 2421.57 (2418.07–2431.50) | 3040 | 73.27 | 406.7 / 86.2 / 21.3 | 1.69 / 16.81 |
Дробление четырёх воркеров на отдельные контейнеры снизило пик при том же бюджете.
API упирается в CPU-квоту; превышение 400% в коротких сэмплах — погрешность окна учёта,
не изменение лимита. В PostgreSQL много соединений находятся в `idle in transaction`: сервер ждёт клиента
внутри транзакции. У записи сюда входит промежуток до COMMIT, но агрегированные
сэмплы не разделяют POST, GET, readiness и другие транзакционные паузы. Здесь рост
числа реплик не добавляет ресурсов.
**B: рост ресурсов.**
| API | SLO, rps | Пик RPS (min–max) | Ускорение / эффективность | CPU API / лимит | CPU PG / лимит | Lock / idle transaction / пул | Очередь LB max |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1x1 | 680 | 750.93 (732.07–754.07) | 1.00× / 100.0% | 100.9 / 100 | 23.0 / 200 | 0.00 / 4.63 / 8 | 576 |
| 2x1 | 900 | 1306.80 (1276.80–1311.90) | 1.74× / 87.0% | 202.7 / 200 | 43.5 / 200 | 0.12 / 9.00 / 16 | 475 |
| 4x1 | 2020 | 2421.57 (2418.07–2431.50) | 3.22× / 80.6% | 406.7 / 400 | 86.2 / 200 | 1.69 / 16.81 / 32 | 872 |
| 8x1 | ≥2400 | 3420.37 (3375.80–3531.67) | 4.55× / 56.9% | 776.5 / 800 | 161.9 / 200 | 29.62 / 16.15 / 64 | 744 |
От 4 к 8 CPU прирост пика только 1.41× при удвоении ресурсов. На 8×1 рост предложения
с 3600 до 5400 не повышает throughput: медиана падает с 3420.37 до 3241.63 RPS.
При 3600 API использует 776.45/800% CPU; около 30 соединений ждут блокировку и 16 —
приложение в транзакции. PostgreSQL использует 161.91/200%, LB — 38.67/100%.
Это совместное ограничение CPU приложения и сериализации записи в общую БД;
очередь LB здесь следствие занятых API, а не доказательство насыщения CPU балансировщика.
Среднее CPU БД ниже квоты; из него нельзя ни доказать, ни исключить кратковременное
исчерпание CPU. Единственный предел в виде CPU PostgreSQL этими данными не доказан.
**Контроль общего пула и maxconn.** 8×1, 5400 предложенных запросов/с, по три повтора;
меняется один параметр. pool8 соответствует maxconn32 по умолчанию.
| Вариант | Успешные RPS (min–max) | p95, мс (min–max) | Lock / соединения | CPU API / PG | Очередь LB max | Ошибки |
| --- | --- | --- | --- | --- | --- | --- |
| pool4 | 3755.60 (3747.60–3762.47) | 351.94 (348.29–354.25) | 5.12 / 32 | 796.5 / 148.5 | 744 | 0.000% |
| pool8 | 3767.60 (3765.60–3778.90) | 348.45 (347.57–348.72) | 27.96 / 64 | 794.2 / 166.9 | 744 | 0.000% |
| pool16 | 3251.60 (3123.70–3266.63) | 429.03 (423.43–439.26) | 83.19 / 128 | 698.0 / 176.3 | 744 | 0.011% |
| maxconn16 | 3839.67 (3657.77–3884.13) | 329.99 (319.33–365.15) | 30.62 / 64 | 785.8 / 168.4 | 872 | 0.000% |
| maxconn64 | 3657.33 (3484.53–3671.03) | 405.58 (405.26–424.99) | 28.12 / 64 | 786.8 / 166.4 | 488 | 0.000% |
Пул 4 не улучшил throughput (3755.60 против 3767.60), но уменьшил ожидания Lock
с 27.96 до 5.12. Пул 16 снизил throughput на 13.7% с непересекающимися диапазонами,
увеличил Lock до 83.19/128 и дал 0.009–0.016% HTTP-ошибок в перегрузке. Увеличение
пула не снимает ограничение: оно добавляет конкурентов за те же чаты. maxconn=16
имеет более высокую медиану, но интервал 3657.77–3884.13 пересекает default;
улучшение не подтверждено. maxconn=64 хуже default, интервалы не пересекаются.
Увеличение допустимой конкуренции LB не помогает; CPU LB 33–39% квоты не насыщен.
Уменьшение maxconn после оптимизации не проверялось, поэтому default не менялся.
**Контроль числа процессов.** 4×1 и 8×0.5 закреплены за теми же CPU 7–10 и имеют
одинаковые 4 CPU/2 GiB. С ростом числа процессов растёт суммарный пул (32→64);
поэтому это контроль размещения и совокупной цены дробления, не изолированный эффект
только числа Python-процессов.
| Нагрузка | API | Успешные RPS (min–max) | p95, мс (min–max) | CPU API | Lock / idle transaction |
| --- | --- | --- | --- | --- | --- |
| 3040 | 4x1 | 2279.83 (2215.27–2332.03) | 556.14 (529.62–573.94) | 407.5 | 1.52 / 16.74 |
| 3040 | 8x0.5 | 1931.63 (1900.13–1945.90) | 728.93 (709.88–731.17) | 399.9 | 24.19 / 22.96 |
| 4560 | 4x1 | 2260.57 (2253.10–2279.93) | 554.99 (553.64–560.44) | 409.1 | 1.88 / 17.42 |
| 4560 | 8x0.5 | 1977.63 (1915.00–2004.40) | 722.17 (692.71–744.52) | 399.0 | 27.31 / 21.65 |
При обеих интенсивностях диапазоны RPS не пересекаются: 8 реплик по 0.5 CPU
медленнее четырёх по 1 CPU. Различие нельзя объяснить другим набором vCPU: он
одинаков. Отдельный вклад CFS, числа процессов и увеличенного пула этим опытом
не разделён; объяснение только «другие физические ядра» недостаточно.
**Подтверждённое улучшение.** PostgreSQL Insert с ON CONFLICT не создаёт обычный cache key.
`POST_MESSAGE = lambda_stmt(post_message, enable_tracking=False)` задаёт постоянный ключ
статического дерева; все пользовательские значения остаются явными bindparam при execute.
SQL, индексы и транзакция не изменились; состояние сессий и сообщений не кэшируется.
`diagnostics/compilation.txt` проверяет идентичный SQL и одну запись compiled cache.
Его локальный микробенчмарк не является измерением HTTP throughput.
| Нагрузка | Вариант | Успешные RPS (min–max) | p95, мс (min–max) | p99, мс | CPU API / PG | Lock / idle transaction | Dropped |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 2400 | before | 2400.03 (2400.00–2400.03) | 14.28 (10.28–14.38) | 63.16 | 573.2 / 99.8 | 1.19 / 3.96 | 0.00% |
| 2400 | after | 2400.03 (2400.00–2400.03) | 4.63 (4.43–5.14) | 14.20 | 405.2 / 94.2 | 0.07 / 2.67 | 0.00% |
| 3600 | before | 3562.00 (3560.20–3581.90) | 223.99 (155.14–238.00) | 283.23 | 774.4 / 159.6 | 26.46 / 15.08 | 1.05% |
| 3600 | after | 3587.40 (3566.83–3587.60) | 101.01 (76.11–210.49) | 156.31 | 593.0 / 150.0 | 10.23 / 8.42 | 0.35% |
| 5400 | before | 3629.17 (3169.57–3665.47) | 373.74 (362.79–538.35) | 480.28 | 775.0 / 167.7 | 29.35 / 16.04 | 32.79% |
| 5400 | after | 3945.63 (3923.97–3970.43) | 317.43 (310.83–318.15) | 415.68 | 614.4 / 175.8 | 41.56 / 11.54 | 26.93% |
При 2400 rps p95 снизился в 3.08 раза, CPU API — на 29.3%.
Диапазоны p95 до/после не пересекаются: эффект больше разброса повторов и удовлетворяет
критерию подтверждённого улучшения. При 5400 медиана throughput выросла на 8.7%: диапазоны 3169.57–3665.47
и 3923.97–3970.43 RPS также не пересекаются. Предел SLO по сетке: before ≥2400,
after 3600; при 3600 проходит один из трёх before и все три after. Интервалы p95
при 3600 пересекаются, поэтому доказательство превышения разброса основано на других
точках. У before в парном опыте результат выше, чем в серии B: сравнивать after
с более ранней B и приписывать всю разницу оптимизации было бы неверно.
Блокировка чата остаётся до COMMIT; `idle in transaction` не исчезает. После экономии CPU
ограничение сильнее смещается к конкуренции за общий чат и обработке транзакций PostgreSQL.
Изменение скомпилированного дерева проверено тестом изоляции пользователей/чатов/текстов,
гонками идемпотентности, TTL и rollback. Итоговая проверка контракта — в `revalidation/`.
**Графики и сырьё.** `make plots` пересчитывает `plots/capacity.csv`, `capacity.md` и 12 PNG
из пяти summary.csv. Усы throughput/p95/p99 — min–max, CPU — медианы с min–max; четыре точки B
дополнены описательной USL-кривой. Её коэффициенты не доказывают причину и модельный
оптимум не выдаётся за измеренную конфигурацию. Проверка сырья — `audit.txt`.
![Серия A](evidence/track1-sqlalchemy/plots/series-a-throughput.png)
![Серия B](evidence/track1-sqlalchemy/plots/series-b-throughput.png)
![Рост ресурсов](evidence/track1-sqlalchemy/plots/scaling.png)
![Загрузка звеньев](evidence/track1-sqlalchemy/plots/utilisation.png)
![До и после](evidence/track1-sqlalchemy/plots/compare-throughput.png)
![Контроль пула](evidence/track1-sqlalchemy/plots/control-pool-throughput.png)
![Контроль размещения](evidence/track1-sqlalchemy/plots/control-cpus-throughput.png)
**Ограничения и вывод.** Одна Docker VM, виртуальные CPU и два типа физических ядер M4 Max,
короткие окна, всего три повтора; тепловой режим и растущая база не полностью контролируются.
Порядок конфигураций A/B фиксирован, before всегда первый внутри парного повтора.
Сэмплы CPU получаются раз в 3–5 с из-за Docker CLI; память API — максимум одной реплики.
Успешные RPS делятся на 30 с, но k6 учитывает завершения в gracefulStop до 5 с: у перегрузки
есть пограничный эффект. Dropped iterations включают ограничение maxVUs, а не только сервер.
Профиль с 10 горячими чатами и первой страницей истории не обобщается на любое число чатов
или глубокую историю. EXPLAIN сохранён отдельно; custom plan с литералами не доказывает
форму generic prepared plan в рабочем запросе. Исторический asyncpg не является контролем.
Дробление API при фиксированном бюджете не ускорило работу; добавление ресурсов дало
сублинейный прирост, а после насыщения CPU и общей транзакционной части рост предложенной
нагрузки перестал помогать. Кэширование компиляции подтвердило практическое улучшение.
Эксперимент не доказывает, что любое увеличение числа реплик свыше восьми бесполезно:
такие конфигурации не измерялись. Для следующего улучшения нужны отдельные опыты
с числом горячих чатов и ограничением конкуренции, а не экстраполяция USL.
## Ответы на вопросы защиты
**Чем отказ процесса отличается от отказа узла?** Отказ процесса — это одна реплика: контейнер остановлен,
убит или завис, а host, LB, PostgreSQL и соседняя реплика работают. Его ловит проверка готовности LB, и
трафик уходит на соседа: `SIGTERM` — 0,899–1,326 с, `kill` — 0,273–0,795 с, зависание (`docker pause`) — 2,783–3,281 с по таймауту
проверки ([detection после оптимизации](evidence/track1-sqlalchemy/revalidation/detection/)),
в измеренном окне failover-each — 0 ошибок под 100 rps. Отказ узла
забирает всё, что на нём запущено, сразу: здесь узел один, поэтому вместе с репликами пропадают LB, PostgreSQL,
Valkey и volumes — отказ всего стенда, и никакая реплика его не переживёт. Кроме того, мёртвый узел не отвечает
`RST` и не закрывает соединения: обнаружение идёт только по таймаутам, как в сценарии `pause`, а не по отказу
соединения, как при `kill`. Защита от потери узла — несколько узлов и реплицированные LB и БД (трек 2) — в эту
работу не входит.
**Почему `depends_on`/`healthcheck` сами по себе не являются балансировщиком?** `depends_on` упорядочивает
только запуск: `migrate` ждёт `healthy` PostgreSQL, `api` — успешного завершения `migrate` и старта Valkey, один
раз, при `up`, и дальше ни на что не влияет. `healthcheck` лишь меняет статус контейнера в `docker ps`: у `api` он раз в 5 с с 3 повторами, то есть
`unhealthy` наступает через десяток секунд, и Compose ничего не делает с трафиком — встроенный DNS Docker
отдаёт адрес работающего контейнера независимо от его здоровья. Нет единой точки входа, распределения запросов,
повторов отказавшего соединения на соседа, мягкого вывода из ротации и ответа `503` в формате контракта, когда
готовых реплик нет. Всё это делает HAProxy: активная проверка `/health/ready` раз в 1 с с `fall 2`/`rise 2`,
round robin, `retry-on conn-failure` и `redispatch`. Пример — остановка PostgreSQL: контейнеры `api` продолжают
работать, а LB исключает обе реплики за 1,201–1,255 с и сам отвечает `503 unavailable`
(`evidence/track1-sqlalchemy/revalidation/detection/run*/postgres.json`).
**Какие POST можно повторять после timeout и что защищает Idempotency-Key?** Только `POST
/api/v1/chats/{chat_id}/messages` с тем же `Idempotency-Key` и тем же телом. Сообщение и квитанция ключа
фиксируются одной транзакцией, поэтому повтор после таймаута, обрыва или гибели реплики посреди запроса либо
находит квитанцию и получает тот же `201` с тем же `Message`, либо, если исходная запись не зафиксировалась,
создаёт сообщение один раз. Одновременные повторы через разные реплики сериализуются блокировкой строки чата:
160 × `201` и одна копия в каждом из 20 раундов ([lb-check](evidence/track1-sqlalchemy/revalidation/lb-check.json)).
Потерянный ответ воспроизведён на стенде
(`make retry-check`, [retry](evidence/track1-sqlalchemy/revalidation/retry.json)): запись ждёт блокировку строки чата дольше таймаута клиента, клиент повторяет её
с тем же ключом через LB — и когда реплика жива (она сама отвечает `201` уже без клиента), и когда её убили, пока
запрос ждал; в обоих случаях повтор получает `201` с тем же `id`, а в истории одна копия. Ключ не защищает от другого тела с тем же ключом
(`409`), от повтора через 24 ч и больше (`IDEMPOTENCY_TTL_SECONDS`, ключ начинается заново) и не отменяет
проверку сессии и доступа при повторе (`401`/`404`). `POST /users`, `POST /chats` и `POST /auth/sessions`
ключа не имеют: повтор после таймаута может создать второй чат или вторую сессию, поэтому их не повторяют ни
клиент, ни LB — в HAProxy `disable-l7-retry` для всего, кроме `GET` и сообщений с ключом; отказ соединения
повторяется для всех, потому что запрос до реплики не дошёл.
**Что сломается при увеличении числа API, если сессии находятся в локальной памяти?** При round robin без
привязки токен, выданный репликой A, неизвестен остальным: при N репликах доля `401` на действующий токен —
около (N−1)/N, и проверка «разные реплики без повторного входа» не проходит. Выход на реплике A не отзывает
токен на B — отозванная сессия продолжает работать. Остановка или рестарт реплики теряют её сессии, и failover и
persistence с прежним токеном падают. Sticky-сессии лишь маскируют это: при отказе реплики клиенты всё равно
теряют вход, а нагрузка распределяется неравномерно. Здесь сессии хранятся в PostgreSQL (только SHA-256
токена) с общим кэшем и отметками отзыва в Valkey: 40 запросов одним токеном — 20 + 20 по репликам
([lb-check](evidence/track1-sqlalchemy/revalidation/lb-check.json)), выход `204` → `401` → `401` через LB,
прежний токен живёт после рестарта всего стенда
([faults и persistence](evidence/track1-sqlalchemy/revalidation/commands.txt)). То же относится к ключам идемпотентности: в памяти реплики повтор через соседа
создал бы дубль.
## Ограничения и следующие шаги
Трек переснят на SQLAlchemy; действуют ограничения методики из раздела трека.
Старые числа raw asyncpg не используются как текущая производительность.
- Один Docker-host: потеря host, LB или PostgreSQL — отказ всего стенда. LB и БД — единственные точки отказа;
их резервирование вне рамок лабы.
- Цель failover-теста выбирает round robin (кто обслужил первое сообщение); второй прогон сразу после первого
и `make restore` попадает в ту же реплику, поэтому перед ним нужен один запрос через LB:
`make failover-evidence SHIFT=1` или `curl -s -o /dev/null "http://$(docker compose port lb 8080)/health/live"`
перед `make test-failover` (так снят `failover-current-2.txt`).
- `X-Instance-Id` раскрывает короткий ID контейнера — допустимо до лабы 7, где появится непрозрачный alias.
- Таблица ключей растёт вместе с историей (строка на сообщение); истёкшие ключи только перезаписываются при
повторном использовании, фоновой очистки нет.
- Запись в один горячий чат сериализуется блокировкой строки чата; повтор с ключом берёт ту же блокировку.
В SQLAlchemy блокировка держится до явного COMMIT после одного изменяющего SQL-оператора — это
следующий потолок для горячих чатов (раздел трека).
- Окно вывода из ротации удлиняет каждую остановку реплики на 2 с; оно рассчитано на проверки LB раз в
секунду: при большем `inter` окно нужно увеличить (это ловит `test_timeouts.py`).
- Время обнаружения измерено тремя прогонами на сценарий; верхняя граница — формула по параметрам проверки.
Замер считается от запуска команды отказа и включает задержку docker CLI и период опроса статистики LB, поэтому
может превысить формулу на эту величину; допуск замера — 0,25 с. На текущем коде все 12 замеров в пределах
формулы без использования допуска (`evidence/track1-sqlalchemy/revalidation/detection/`).
- Rolling update проверен со сменой кода без смены схемы. Миграция, несовместимая с работающей версией
(удаление или переименование столбца), потребовала бы двух выпусков expand/contract; в лабе таких нет.
- `scripts/rolling-update.sh` и `restore.sh` используют `--no-recreate`: после замены с другим `API_IMAGE`
обычный `make up` пересоздаст реплики под текущий конфиг — это ожидаемо.
- Секреты лежат файлами в `secrets/` на хосте (каталог `0700`, файлы `0644`, чтобы их читали непривилегированные
пользователи контейнеров); это учебное упрощение вместо менеджера секретов.
- Кэширование компиляции уменьшило p95 и CPU API; для горячих чатов остаётся сериализация
транзакций. Вклад CFS отдельно не измерялся. Изменение числа чатов и настройка admission
control после оптимизации потребуют новых опытов, поэтому их эффект не заявляется.