docs: complete lab 3 report and add final clean clone check

Fill the remaining report sections: clean clone run with versions and
prerequisites, lab 2 carry-over, transaction boundaries, teacher
agreements, skeleton variable mapping, rubric cross-check, experiment
overview, limitations summary, sources and AI usage. Record the clean
clone run of every documented command on default ports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-11 21:53:13 +03:00
co-authored by Claude Opus 5.5
parent 67b4303a0a
commit 063eedbc71
2 changed files with 641 additions and 35 deletions
+409 -35
View File
@@ -2,56 +2,147 @@
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
- Целевая оценка 5; выбранный трек 5: трек 1 «Цена масштабирования» (серии сняты, change `scaling-bench`; одно подтверждённое улучшение — пул без переполнения, change `scaling-improvement`, засчитано с оговоркой: раздел «Улучшение по найденному узкому месту: пул без переполнения»)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Commit/PR: ветка `solution/bvt2301-safronov`, PR «ЛР 3 — БВТ2301 —
Сафронов — на 5» — ссылка на PR после публикации (push и PR делает
автор). Из чистого clone проверен код commit `67b4303`
(`evidence/tests/clean-clone-final.md`); последующие commit меняют
только документы.
- Использованные источники, библиотеки и помощь ИИ: раздел «Источники,
библиотеки и использование ИИ» в конце отчёта.
Сделано по changes OpenSpec (`openspec/changes/archive/`), поверх кода
лабы 2:
- `X-Instance-Id` и обязательный `Idempotency-Key` с ключами в
PostgreSQL — `instance-id-idempotency` (уровень «3»);
- HAProxy перед двумя репликами API, лимиты, failover hook
`scripts/stop-one.sh` — `replicas-lb` (уровни «3» и «4»);
- согласованная цепочка таймаутов и профиль отказа под нагрузкой —
`graceful-failover` (уровень «4»);
- поочерёдная замена реплик с дренажём через runtime API HAProxy,
expand-миграция и профиль замены под нагрузкой — `rolling-update`
(уровень «4»);
- трек 1 «Цена масштабирования»: серии `a`, `b`, `pool`, `db`, A/A,
графики, точка насыщения и ответ 503 на «too many clients» —
`scaling-bench` (уровень «5»);
- одно улучшение по найденному узкому месту — пул без переполнения —
`scaling-improvement` (уровень «5»).
## Запуск из чистого clone
TODO (этап 7, `PLAN.md`): версии runtime/образов и prerequisites одним
списком, повторная проверка из настоящего `git clone` на стенде с LB.
**Версии.** Образ API: `python:3.12.14-slim-trixie` и `uv 0.12.17`;
LB: `haproxy:3.4.6-trixie`; Postgres: `postgres:18.6-trixie`; Valkey:
`valkey/valkey:9.1.2-trixie`. Все закреплены тегом и digest индекса
(amd64 + arm64) в `Dockerfile` и `docker-compose.yml`. Приложение:
Python 3.12, FastAPI 0.141.1, uvicorn 0.54.0, pydantic 2.13.5,
SQLAlchemy 2.1.1 (async), asyncpg 0.31.0, alembic 1.20.0, argon2-cffi
25.1.0, redis-py 8.1.0, structlog 24.4.0 и остальное строго по
`uv.lock`. Тесты: pytest 9.1.1, httpx 0.28.1; нагрузка: k6 2.3.0 в
контейнере (`grafana/k6:2.3.0@sha256:…`, `bench/run.py`). Проверено на
Docker Desktop 29.8.2 (ВМ linux/arm64, 12 CPU, 7,7 GiB), Compose
v5.5.1, macOS на Apple M3 Pro.
Стенд с балансировщиком (change `replicas-lb`):
**Нужно на машине:**
- Docker с BuildKit и Compose v2, `make`, `openssl` (пароли в
`make env_setup`);
- `python3` 3.9+ для публичных `make check`, `make test`,
`make test-persistence`, `make test-failover`, `make instances`,
`make test_isolated`, `make failure_checks`;
- uv — для `make validate` (валидатор в dev-группе), `make
student_test`, `make failure_checks`, `make test_isolated` (внутри
`uv run pytest`), стенда замеров `make bench*` и `make run_dev`;
- свободные порты `127.0.0.1:8080` (LB), `127.0.0.1:5433` (Postgres) и
`127.0.0.1:6380` (Valkey). Стенд лабы 2 занимает те же порты: перед
запуском его нужно остановить (`make stop` в его каталоге). Другие
порты — аргументом make (`make run_docker APP_OUT_PORT=8090`) или в
`.env`, затем `make test BASE_URL=http://localhost:8090`.
**Подготовка и секреты.** `make env_setup` создаёт `.env` из
`.env.example` и `config.toml` из `config_example.toml`, существующие
файлы не трогает. В шаблоне пароли Postgres и Valkey пустые, в новый
`.env` подставляются случайные (`openssl rand -hex 16`): общего пароля
стенда в git нет. Отдельно запускать `env_setup` не обязательно, его
вызывают `make run_docker`, `make run_dev`, `make test_isolated` и `make
failure_checks`. Пароль Postgres задаётся только при создании volume:
после смены `POSTGRES_PASSWORD` нужен `make wipe_data`.
Последовательность проверяющего — та, что прошла из настоящего `git
clone` на портах по умолчанию (`evidence/tests/clean-clone-final.md`):
```sh
make env_setup # .env (случайные POSTGRES_PASSWORD и VALKEY_PASSWORD) и config.toml из шаблонов; существующие не трогает
git clone <fork> && cd <каталог clone> && git checkout solution/bvt2301-safronov
make env_setup # .env (случайные POSTGRES_PASSWORD и VALKEY_PASSWORD) и config.toml из шаблонов
make run_docker # docker compose build + up -d: postgres, valkey → migrate → api × API_REPLICAS (2) → haproxy
docker compose ps # готовность — haproxy (healthy): через LB можно обслужить запрос
docker compose ps # готовность — haproxy (healthy): через LB можно обслужить запрос; у api портов нет
make check # структура skeleton
uv sync && make validate PYTHON=.venv/bin/python # полная валидация OpenAPI 3.1
make test # публичный smoke через LB на http://localhost:8080
make student_test # свой набор через LB, тесты реплик выполняются (EXPECT_REPLICAS = API_REPLICAS)
make instances # ≥2 X-Instance-Id одной сессии через LB (шаг 1 сценария защиты)
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make replicas # вернуть остановленную реплику (те же ID) перед следующим прогоном failover
make bench_failover_quick # отказ каждой реплики под нагрузкой на своём стенде mtusi-bench, ~2 мин; полный — make bench_failover
make rolling_update # новый код на реплики без простоя: сборка, миграции один раз, по одной реплике с выводом из LB
make bench_rollout_quick # то же под нагрузкой на своём стенде с образа прежнего commit, ~2 мин; полный — make bench_rollout
make stop # остановить; make down — удалить контейнеры, volume с данными остаётся
make wipe_data # намеренно удалить учебные данные: только после ввода yes, только проект mtusi-lab3
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановлена первая реплика
make replicas # вернуть остановленную реплику (тот же контейнер и ID)
curl -s -o /dev/null http://127.0.0.1:8080/health/live # сдвиг очереди round-robin, иначе тест выберет ту же реплику
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановлена вторая
make replicas
make student_test # свой набор через LB, тесты реплик выполняются (EXPECT_REPLICAS = API_REPLICAS)
make failure_checks # проверки отказов на отдельном проекте mtusi-lab3-failures, ~70 с; рабочий стенд не трогается
make test_isolated # образ на временной базе test_messenger, один контейнер API: smoke + свой набор, ~65 с
```
Ожидаемо: `make check`, `make validate`, `make test`,
`make test-persistence` и оба `make test-failover` — `PASS`;
`make instances` — `instances: 2`; `make student_test` — `131 passed`;
`make failure_checks` — `17 passed`; `make test_isolated` — `127
passed, 4 skipped` (тесты реплик против одного процесса пропускаются с
причиной). Строка `STOP_ONE_LOG` называет `TARGET_INSTANCE_ID`, который
выбрал тест, и полный ID остановленного контейнера; `docker compose ps
-a` показывает его `Exited`.
Порт API на хосте один — у HAProxy (`127.0.0.1:${APP_OUT_PORT}`, 8080).
Число реплик — `API_REPLICAS` в `.env` (по умолчанию 2), разово —
`make replicas API_REPLICAS=N`. В консоли (`make run_dev`) — один
процесс без LB; свой набор против него — `make student_test
процесс без LB на `127.0.0.1:8080`, с Postgres и Valkey из того же
compose; свой набор против него — `make student_test
EXPECT_REPLICAS=1`.
Проверено на одном API без балансировщика (change
`instance-id-idempotency`): в настоящем `git clone` `docker build -t
mtusi-messenger:lab3 .` проходит без `.env` и `config.toml`; после
`make env_setup` на этом образе проходит smoke
(`evidence/tests/clean-clone.md`). Стенд с LB из настоящего `git clone`
(change `replicas-lb`): `make run_docker` сам создаёт `.env` и
`config.toml` и поднимает две реплики за HAProxy; на нестандартных
`APP_OUT_PORT`, `APP__PORT` и портах Postgres и Valkey проходят `make
test` и `make student_test` (`evidence/replicas/clean-clone-ports.md`). Удаление учебных данных — `make
wipe_data` с вводом `yes`, трогает только проект `mtusi-lab3`
(`evidence/tests/stand-lab3.md`).
### Сценарий защиты
```sh
make run_docker && make instances # 1. ≥2 X-Instance-Id одной сессии через LB
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # 2. запись и чтение во время отказа
cat /tmp/stop-one.log; docker compose ps -a # 3. какой контейнер остановлен: ID = TARGET_INSTANCE_ID
make replicas; curl -s -o /dev/null http://127.0.0.1:8080/health/live
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # то же для второй реплики
make replicas
make test-persistence ACTION_SCRIPT=scripts/restart.sh # 4. рестарт LB, реплик, Postgres и Valkey, тот же токен
# уровень 4 — на своём стенде mtusi-bench, рабочий стенд перед ними: make stop
make bench_failover_quick # отказ каждой реплики под нагрузкой (stop, kill), ~2 мин; полный — make bench_failover
make bench_rollout_quick # поочерёдная замена под нагрузкой с образа прежнего commit, ~2 мин; полный — make bench_rollout
make rolling_update # на рабочем стенде: новый код без простоя (под make load в соседнем терминале)
# уровень 5, трек 1: самопроверка серий (~4 мин), полные серии — make bench_scaling SERIES=…
make bench_scaling_quick
```
Полные метки и графики трека 1 уже лежат в `evidence/bench/scaling-*/`,
`evidence/plots/` и `evidence/compare/` (раздел «Цена
масштабирования»); на защите показываются они, серии идут 25–100 мин.
### Остановка и удаление данных
- `make stop` — остановить контейнеры; `make down` — удалить
контейнеры, volume `postgres_data` с данными остаётся, кэш Valkey
теряется (он без volume, данные от этого не страдают);
- `make wipe_data` — удалить контейнеры и volume, только после ввода
`yes` и только проекта `mtusi-lab3` (`evidence/tests/stand-lab3.md`);
следующий `make run_docker` поднимает пустую базу со схемой.
Ранние проверки из clone: один API без LB — сборка без `.env` и
`config.toml`, smoke на образе (`evidence/tests/clean-clone.md`); стенд
с LB на нестандартных `APP_OUT_PORT`, `APP__PORT` и портах Postgres и
Valkey — `make test` и `make student_test`
(`evidence/replicas/clean-clone-ports.md`).
## Архитектура и решения
TODO (этап 7): что перенесено из lab2 одним списком, транзакционные
границы сводно.
```
клиент → 127.0.0.1:APP_OUT_PORT → haproxy ──→ api (реплика 1) ──→ postgres (данные, сессии, ключи идемпотентности; volume)
└─→ api (реплика 2) ──→ valkey (кэш неизменяемых карточек чатов)
@@ -63,6 +154,70 @@ TODO (этап 7): что перенесено из lab2 одним списко
Postgres. Реплики `api` одинаковы и взаимозаменяемы, порта на хосте у
них нет; единственная точка входа — HAProxy.
**Что перенесено из лабы 2** (репозиторий `mtusi2026lab2-safronov`,
ветка `solution/bvt2301-safronov`, commit `c6ad34d`), без изменения
поведения, кроме перечисленного ниже:
- PostgreSQL как источник истины, схема и миграции alembic отдельным
сервисом `migrate`, ограниченный пул и таймауты, 503 при
недоступности БД;
- регистрация с паролем (Argon2id в потоке), вход по Basic только на
`POST /auth/sessions`, остальное — Bearer-сессия в таблице `sessions`
(SHA-256 токена, срок `[auth] session_ttl_seconds`, мгновенный отзыв);
- Valkey — cache-aside неизменяемой карточки чата, отказ — обход в
Postgres;
- keyset-пагинация по `(created_at, id)`, формат ошибок контракта,
JSON-журнал без содержимого сообщений;
- свои тесты `student-tests/` (`make test_isolated`, `make
failure_checks`) и стенд замеров `bench/` трека 2 лабы 2 (`make bench`,
`make bench_restore`).
Что изменилось при переходе 2 → 3: переход API (`COURSE.md`) —
`X-Instance-Id` в каждом ответе и обязательный `Idempotency-Key` у
отправки сообщения; новые миграции только добавляют (таблица
`idempotency_keys`, колонка `messages.instance_id`); проект compose
`mtusi-lab3` вместо `mtusi-lab2`, чтобы не подключиться к данным
второй лабы; HAProxy и реплики без портов; цепочка таймаутов (keep-alive
uvicorn 60 с, `idle_in_transaction_session_timeout` 10 с); пул 10 + 0
вместо 10 + 5 (`scaling-improvement`); отказ PostgreSQL «too many
clients» (SQLSTATE 53300) — 503, а не 500. Стенды `make failure_checks`
и `bench/` переведены на HAProxy перед API, `make test_isolated` остался
одним контейнером API на временной базе.
**Транзакционные границы.** Одна `AsyncSession` на запрос, commit
делает сервис, изоляция `READ COMMITTED`; реплики общих транзакций не
имеют, гонки между ними решают ограничения PostgreSQL:
| Операция | Шаги в одной транзакции |
|---|---|
| регистрация | хэш пароля (до БД) → `INSERT … ON CONFLICT (username) DO NOTHING RETURNING`; конфликт → 409 |
| вход | транзакция 1: `SELECT` учётных данных → commit; проверка пароля вне БД; транзакция 2: `INSERT sessions` → commit |
| запрос с токеном | один `SELECT sessions JOIN users WHERE token_hash = … AND expires_at > now` |
| выход | `DELETE FROM sessions WHERE id = …` → commit |
| создание чата | проверка участников → `INSERT chats` → `INSERT chat_members` → commit; ошибка до commit — откат всего. Карточка пишется в Valkey после commit |
| отправка сообщения | членство (карточка из Valkey или `SELECT`) → захват ключа `INSERT … ON CONFLICT … DO UPDATE WHERE просрочен RETURNING` → `INSERT messages` (с `instance_id` реплики) → commit с отложенной проверкой FK ключа на сообщение. Ключ занят — чтение сохранённого результата и commit (снять блокировку), тот же 201 или 409. Ошибка до commit — нет ни ключа, ни сообщения |
| чтения | карточка чата — из Valkey или одним `SELECT`; история и список чатов — один `SELECT` по keyset-индексу |
Одновременная вставка того же ключа другой репликой ждёт на
уникальном индексе commit или отката первой; явных блокировок и
распределённых транзакций нет (раздел «Идемпотентность отправки
сообщения»).
**Согласования с преподавателем** (AGENTS.md, «Согласования с
преподавателем»), действуют и в этой лабе:
- 2026-09-26 — лабы можно делать на FastAPI, несмотря на расхождения с
контрактом: лишний 422 (у нас не отдаётся вообще, всё переводится в
400) и другой порядок кодов ошибок. Публичный smoke при этом проходит.
Где это видно в лабе 3 — порядок кодов у `Idempotency-Key` (раздел
«Идемпотентность отправки сообщения»);
- 2026-09-29 — конфигурация через pydantic-settings: окружение →
`.env` → `config.toml` → дефолты. `config.toml` не в git и не в
образе, монтируется read-only при запуске; это считается выполнением
«конфигурация приходит из окружения» (README лабы 1, п. 3) и п. 6
`Dockerfile.example`. Отсюда таблица «Соответствие переменных
`.env.example`» ниже.
Новых согласований в лабе 3 не было.
### Балансировщик и реплики (change `replicas-lb`)
**Почему Compose + HAProxy** (выбор подтверждён 2026-10-07, `PLAN.md`):
@@ -405,13 +560,24 @@ SHA-256 тела; `created_at` с индексом; `CHECK` формата и д
### Соответствие переменных `.env.example`
`.env.example` skeleton предлагает «логические» имена и просит
сопоставить их с настоящими. Критерий — кто читает значение: то, что
читают compose и контейнеры зависимостей, живёт в `.env`, то, что читает
только приложение, — в секциях `config.toml` (согласование 2026-09-29).
Адреса и порты Postgres и Valkey в compose — только переменные `.env`.
| Имя skeleton | Где у нас | Почему так |
|---|---|---|
| `APP_HOST` | режим `APP__RUN_MODE`: console — `127.0.0.1`, docker — `0.0.0.0` (литерал в `environment` compose и `ENV` в `Dockerfile`) | адрес следует из режима; в `.env` режим не хранится, чтобы консоль и docker работали из одного файла |
| `APP_PORT` | `APP__PORT` в `.env` (8080) — порт, на котором слушает каждая реплика, на нём же healthcheck образа и проверки HAProxy (`API_PORT` контейнера LB); `APP_OUT_PORT` (8080) — порт на `127.0.0.1` хоста, его публикует только HAProxy | параметр приложения в формате настроек; внешний порт приложение не читает, поэтому без секции. Проверено на нестандартных портах (`evidence/replicas/clean-clone-ports.md`) |
| `APP_ENV` | не используется | окружение одно — учебный стенд |
| `SESSION_TTL_SECONDS` | `[auth] session_ttl_seconds` в `config.toml`, по умолчанию 3600; разовая подмена — `AUTH__SESSION_TTL_SECONDS` (так «тесный» API `make failure_checks` получает 2 с) | читает только приложение; мост из `.env` с этим именем окружение бы не перекрыло (`.claude/rules/settings.md`) |
| `DATABASE_URL_FILE` | не используется: URL собирает приложение из `[database]`, адрес и порт в docker — `POSTGRES_HOST` / `POSTGRES_PORT` из `environment` compose, пароль — мостом из `POSTGRES_PASSWORD` в `.env` | пароль нужен ещё и контейнеру Postgres, поэтому один источник — `.env`; файл секрета с URL дал бы второй |
| `SESSION_STORE` | `postgres`: таблица `sessions`, общая для всех реплик, без кэша — отзыв мгновенный. Отдельной настройки нет | другого хранилища сессий нет; Valkey сессий не хранит (без persistence рестарт стёр бы их) |
| `CACHE_URL_FILE` | не используется: адрес и порт Valkey — `VALKEY_HOST`, `VALKEY_PORT` (сеть compose) и `VALKEY_OUT_PORT` (консоль) в `.env`, пароль — мостом из `VALKEY_PASSWORD` в `[cache] password`; таймаут, окно пропуска, срок записей и пул — `[cache]` в `config.toml` | как у Postgres: пароль нужен и серверу Valkey (`--requirepass`) |
| `IDEMPOTENCY_TTL_SECONDS` | `[idempotency] ttl_seconds` в `config.toml`, по умолчанию 86400 (24 ч); разовая подмена — `IDEMPOTENCY__TTL_SECONDS` | значение читает только приложение; как `SESSION_TTL_SECONDS` (`.claude/rules/settings.md`). Срок меньше 86400 нарушает контракт и применяется только в проверках (2 с у «тесного» API стенда отказов) |
| `API_REPLICAS` | `API_REPLICAS` в `.env` (шаблон — 2), `deploy.replicas: ${API_REPLICAS:-2}` сервиса `api`; Makefile — `API_REPLICAS ?= 2` (`make replicas`, `EXPECT_REPLICAS` тестов). Разово — `make replicas API_REPLICAS=N` | приложение его не читает, поэтому имя без секции; без строки в `.env` действует 2 (`.claude/rules/settings.md`) |
TODO: остальные имена skeleton (`APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE`).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
@@ -444,6 +610,7 @@ TODO: остальные имена skeleton (`APP_HOST`, `APP_PORT`, `APP_ENV`,
| `X-Instance-Id` на каждом ответе, `instance_id` в журнале | тесты `api-conventions`, `curl`, `docker compose logs api` | заголовок у 2xx, 4xx, health, 404, 405, 500; значение = короткий ID контейнера; 85 из 85 записей журнала с `instance_id`, включая старт и shutdown; ключей и текста в журнале нет | `evidence/idempotency/instance-id.md` |
| Стенд лабы 3 не трогает данные лабы 2 | `make run_docker`, `make wipe_data`, снова `make run_docker`; `docker volume inspect` до и после | `wipe_data` удалил только контейнеры, сеть и volume `mtusi-lab3`; `mtusi-lab2_postgres_data` с прежней датой создания | `evidence/tests/stand-lab3.md` |
| Сборка из чистого clone | `git clone`, `docker build -t mtusi-messenger:lab3 .` до `make env_setup`; стенд на этом образе, `make test` | сборка без `.env` и `config.toml`, в образе их нет, процесс от UID 10001; `PASS: lab3 public API scenario` | `evidence/tests/clean-clone.md` |
| Итоговая проверка из чистого clone по разделу «Запуск из чистого clone» (`PLAN.md`, этап 7; COURSE.md: «PR собирается из чистого clone») | настоящий `git clone` commit `67b4303`, проект `mtusi-lab3` на портах по умолчанию: `make env_setup`, `make run_docker`, `make check`, `make validate`, `make test`, `make instances`, `make test-persistence`, `make test-failover` для каждой реплики (`stop`, затем `make replicas`; плюс `kill`), `make student_test`, `make failure_checks`, `make test_isolated`; `docker build --no-cache` | все команды — код 0 без правки файлов клона: `PASS` у публичных проверок, `instances: 2`, остановлены по очереди `0089ca350b2b` и `437292ccaf78` (ID = `TARGET_INSTANCE_ID`), первая запись через 0,99–1,0 с, неудачных попыток 0; после `restart.sh` те же ID с новым `StartedAt` у LB, реплик, Postgres и Valkey; 131 passed через LB, 17 проверок отказов, 127 passed + 4 пропуска с причиной в изоляции; образ без `.env` и `config.toml`, UID 10001 | `evidence/tests/clean-clone-final.md` |
| Стенд `bench/`: отправки с ключом при восстановлении | `make bench_restore_quick` (самопроверка, не замер) | 1000 отправок во время backup на каждом размере, 0 неудачных; сообщений в исходной базе = подтверждённых отправок; сверка баз прошла | `evidence/tests/bench-restore-quick.md` |
| «4»: rolling update (поочерёдная замена) проверен под нагрузкой | `make bench_rollout ROLLOUT_LABEL=baseline` (commit `9dcea0b`, код `de654a1`, хост проверен, рабочий стенд остановлен): 100 записей с ключом и 100 чтений в секунду, две реплики образа `c50b721` заменяются на образ текущего checkout тем же `scripts/rolling-update.sh`; на рабочем стенде (итоговый код `84161c0`) — `make rolling_update`, откат `COMMIT=c50b721 MIGRATE=0`, снова вперёд и две замены подряд под `tests/load.py`; быстрый профиль `make bench_rollout_quick` на `84161c0` | замена 8,9 с; **0 ошибок** из 24 002 запросов, доля успешных 1,0 в каждой секунде, p95 5 → макс. 11 мс; по шагам: новая `UP` в LB через 2,0–2,1 с после старта, дренаж старой 0,14–0,16 с, остановка 0,3–0,4 с; после вывода из LB старая не получила ни одного запроса; сообщений 12 001 = ключей 12 001. Рабочий стенд: 0 неуспешных из 21 043 / 16 687 / 18 480 / 27 278 запросов `tests/load.py`; старые реплики завершаются за 0,1 с с кодом 0 («Finished server process»); контейнеров прежних реплик после замены нет. Быстрый профиль на итоговом коде: замена 8,1 с, 0 ошибок, 7 301 = 7 301 | `evidence/rollout/baseline/summary.md`, `evidence/rollout/compatibility.md`, `evidence/tests/rolling-update-checks.md` |
| «4»: миграции однократно и совместимы с работающей версией | реплики образа `c50b721` + миграция нового образа в контейнере сервиса `migrate` (команда скрипта), без замены; `make test`, `make student_test`; замена; `SELECT instance_id, count(*)` по сообщениям; миграция под чужой блокировкой и нагрузкой | новая ревизия `e656d6bbe1a4` (колонка `messages.instance_id`, NULL) при прежних репликах: `PASS`, 131 passed; запись прежней версии — NULL, новой — её `X-Instance-Id`; при замене одна миграция в контейнере `migrate` до первой новой реплики, в журналах реплик alembic нет; повторный запуск — no-op; откат кода без отката схемы (после отката `migrate` прежнего образа падает на новой ревизии — ограничение, описано); под чужой транзакцией `lock_timeout` 2 с → миграция падает с кодом 1, схема и реплики не тронуты, 6 запросов из очереди за ней — успешны за 2,0 с (с 5 с в apply — все 6 получили 503), повтор проходит | `evidence/rollout/compatibility.md`, `evidence/rollout/script-failures.md` |
@@ -463,11 +630,65 @@ TODO: остальные имена skeleton (`APP_HOST`, `APP_PORT`, `APP_ENV`,
| Пул без переполнения: соединения не переоткрываются | `make failure_checks`: тест `test_pool_keeps_connections` (48 потоков × 5 запросов, пачки больше пула 10, счётчик `pg_stat_database.sessions` через hook `db-sessions`); рабочий `config.toml` с `max_overflow` 5 и 0 | 10 + 5 — красный: 18–21 новая сессия PostgreSQL за 720 запросов; 10 + 0 — 0, 17 проверок отказов прошли (4 прогона); регрессия на коде X: `make test`, `make student_test` (131 passed), `make test_isolated`, `make test-persistence`, `make test-failover` для обеих реплик — `PASS`; соединений приложения на рабочем стенде 17 ≤ 2 × 10 | `evidence/tests/scaling-improvement-checks.md` |
| Цена нового соединения PostgreSQL и пинга | микропроба в реплике рабочего стенда (`cd88b48`): проверка сессии и страница истории через repo, из пула с пингом, без пинга и с новым соединением на итерацию | новое соединение — 11,7–11,8 мс CPU реплики (SCRAM-SHA-256 asyncpg в event loop) и 2,7 мс CPU PostgreSQL против 0,6 и 0,15 мс из пула; пинг при выдаче — +0,13 мс реплики и +0,05 мс PostgreSQL на запрос | `evidence/storage/connection-cost.md` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
**Сверка с рубрикой README.** Каждому пункту — строка с командой,
наблюдением и файлом:
| Уровень | Пункт README | Строки таблицы выше |
|---|---|---|
| 3 | стенд одной командой, ≥2 API, одна точка входа, общие БД и сессии | «3»: стенд одной командой…; итоговая проверка из чистого clone |
| 3 | разные запросы одного пользователя — разные реплики без повторного входа, `X-Instance-Id`, LB — основной маршрут | «3»: разные запросы одного пользователя…; `X-Instance-Id` на каждом ответе |
| 3 | отказ любой одной реплики: ≤10 с до новых чтений и записей, подтверждённые сообщения доступны, ошибки измерены | «3»: отказ любой одной реплики…; «3»: отказ процесса без graceful; «4»: последовательная остановка каждой реплики |
| 3 | повтор с тем же `Idempotency-Key` без дублей: конкурентный, при переключении реплики, неподтверждённая запись | «3»: повтор `POST`…; другое тело с тем же ключом; повтор через другой процесс; при переключении реплики; ключ переживает рестарт; неподтверждённую запись можно повторить; «4»: идемпотентность под параллельными запросами |
| 3 | `make test`, persistence и failover проходят, ≥2 наблюдаемых реплики; hook подтверждён составом перезапущенных процессов | публичный smoke; «3»: `make test-persistence` с LB (`StartedAt` всех контейнеров до и после); «3»: отказ любой одной реплики (`STOP_ONE_LOG`, `docker compose ps -a`); failover hook не трогает чужое |
| 4 | health/readiness, таймауты, SIGTERM согласованы; LB исключает недоступный backend; период проверок и максимальное время обнаружения | «4» (часть): LB исключает недоступный backend; «4»: health/readiness, таймауты и прекращение приёма при SIGTERM |
| 4 | каждая реплика по очереди с восстановлением: RPS, ошибки, время восстановления; идемпотентность параллельными запросами | «4»: последовательная остановка каждой реплики…; «4»: идемпотентность под параллельными запросами |
| 4 | лимиты CPU/RAM, порты API не наружу, секреты только где нужно, нет `container_name` | «4»: лимиты CPU/RAM…; порты из `.env` со стендом за LB |
| 4 | rolling update под нагрузкой; миграции однократно и совместимы | «4»: rolling update…; «4»: миграции однократно и совместимы; замена при сбое и неготовом стенде |
| 5, трек 1 | 1/2/4 реплики при фиксированном бюджете; серия с ростом ресурсов | «5», трек 1: 1/2/4 реплики…; серия с ростом ресурсов |
| 5, трек 1 | точка насыщения БД / LB / пула и почему рост перестаёт помогать | «5», трек 1: точка насыщения…; граница пула; точка насыщения БД |
| 5, трек 1 | исходные данные, графики, одно подтверждённое улучшение; гипотеза, методика, ограничения | «5», трек 1: исходные данные и графики; уровень шума; одно подтверждённое улучшение (с оговоркой); раздел «Цена масштабирования» |
Пункты «Что сделать» README закрыты так же: миграции — один прогон
сервиса `migrate` до реплик (в журналах реплик alembic нет), sticky
session нет (`balance roundrobin` без cookie и stick-table, ответы
одной сессии чередуются), новые реплики LB видит через DNS Docker без
правки конфига (строка «Масштабирование без правки LB»).
**Что приложено к PR** (README, «Что должно быть в PR»):
`docker-compose.yml`, конфигурация LB `infra/haproxy/haproxy.cfg`,
`scripts/restart.sh`, `scripts/stop-one.sh` (и
`scripts/rolling-update.sh`), `Dockerfile`, миграции `migrations/` с
`alembic.ini`, результаты отказов — `evidence/failover/`,
`evidence/rollout/`, `evidence/replicas/`, `evidence/tests/`.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Три вида экспериментов: ручные отказы на рабочем стенде (таблица
ниже), профили нагрузки уровня «4» и серии трека 1. Все замеры под
нагрузкой — на отдельном проекте compose `mtusi-bench` с теми же
образами и `haproxy.cfg`, что у рабочего стенда, генератор k6 — в сети
стенда через LB. Хост общий: Apple M3 Pro (6 + 6 ядер, 18 ГиБ), Docker
Desktop 29.8.2, ВМ 12 vCPU / 7,7 GiB; перед каждым замером проверены
питание от сети, свободная память, отсутствие посторонних контейнеров
и выгрузок в swap (паспорта `meta.json`). Версии — раздел «Запуск из
чистого clone». Сырые итоги k6, журналы LB и посекундные таблицы лежат
рядом со сводками, без токенов и паролей.
| | Отказ реплик (`failover`) | Поочерёдная замена (`rollout`) | Трек 1 (`scaling_*`) |
|---|---|---|---|
| Гипотеза | `stop` и `kill` без ошибок недоступности, `pause` исключается ≤ 6,5 с, восстановление ≤ 10 с, без потерь и дублей | 0 ошибок при плановой замене, старая реплика после дренажа запросов не получает | H1–H4 (раздел «Цена масштабирования»), записаны до прогонов |
| Лимиты | API 1 CPU / 512 МиБ × 2, PostgreSQL 2 CPU / 1 ГиБ, HAProxy 1 CPU / 256 МиБ, Valkey 0,5 CPU / 128 МиБ — как у рабочего стенда | те же | реплики 1 × 4 … 6 × 1, PostgreSQL 2 или 0,5 CPU; k6 2 CPU / 1 ГиБ, сэмплер 0,25 CPU; сумма ≤ 12 vCPU |
| Данные | чат чтения из 1 000 сообщений, отдельный чат записи | те же | чат чтения из 10 000 сообщений, 10 чатов записи |
| Нагрузка | открытая модель, постоянная интенсивность: 100 записей с ключом + 100 чтений истории в секунду | та же | открытая модель 70/20/10 (история / запись / `users/me`): 250 и 500/с, затем поиск R* по ступеням |
| Длительность, прогрев | фаза 15 с до действия (опорное окно) + 20 с до возврата + 15 с; 6 фаз, ~6 мин | 15 с до замены, замена 8,9 с, ≥ 15 с после; 24 002 запроса | прогрев 15 с (5 с подъёма между ступенями), окно 20 с |
| Повторы | один прогон на фазу | один прогон | 3 повтора каждой конфигурации, свежий стенд на ячейку, A/A для шума |
| Успешные RPS, ошибки | `stop`, `kill`: ~200/с, 0 ошибок; `pause`: 99–100/с в окне, 584–602 × 504 | 200/с, 0 ошибок | R* 630–2 034 запросов/с при ошибках ≤ 1 % |
| p50 / p95 / p99 | фаза `stop` 1: 3,5 / 6,1 / 97,1 мс за прогон; p95 по секундам — до 505 мс в секунду действия | 3,3 / 5,0 / 9,7 мс за прогон | p95 / p99 на 500/с по конфигурациям — таблица R* |
| CPU / RAM | только лимиты, использование не снималось | только лимиты | посекундно у каждого контейнера и ВМ (`samples.csv`), CPU на запрос по компонентам |
| Файлы | `evidence/failover/baseline/` | `evidence/rollout/baseline/` | `evidence/bench/scaling-*/`, `evidence/plots/`, `evidence/compare/` |
Ограничения каждого замера — в конце его раздела, сводно — «Ограничения
и следующие шаги».
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
@@ -1464,7 +1685,46 @@ CHANGE=scaling-improvement`
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
**Сводно.**
- **Выдерживается:** отказ процесса API — остановка, убийство или
зависание любой одной реплики при второй живой (измерено: `stop` и
`kill` без ошибок недоступности, `pause` — 504 до исключения за
≤ 6,5 с); рестарт всего стенда с volumes; отказ Valkey (обход в
PostgreSQL); плановая замена реплик под нагрузкой без ошибок; повтор
отправки с тем же ключом через любую реплику.
- **Не выдерживается:** отказ хоста, HAProxy и PostgreSQL — это единые
точки отказа, устойчивость к ним не заявляется (трек 2 не выбран).
Отказ PostgreSQL — 503 на всё, данные целы, после его возврата
стенд работает без рестарта.
- **Не реализовано:** уборка таблицы ключей идемпотентности (до worker
лабы 5), автоматический откат замены, contract-миграции,
`429`/лимит частоты входа, HA для LB и БД.
- **Учебные упрощения:** один Docker-host; все замеры — на нём же
вместе с генератором; один прогон на фазу у профилей уровня «4»;
`X-Instance-Id` — hostname контейнера (непрозрачный alias — лаба 7).
- **Подтверждено:** цепочка таймаутов и время обнаружения (замер по
режимам), отсутствие ошибок при плановой замене; в треке 1 — граница
пула (H3), насыщение PostgreSQL управляемым опытом (серия `db`) и
механизм H1 (один процесс не занимает больше ядра при лимите 4 CPU),
хотя H1 по заранее записанным критериям целиком не подтверждена
(2 × 2 = 1,65 × при пороге 1,7). H1б и H2 опровергнуты, вместо H2
подтвердилась конкурирующая H2-хост. Улучшение «пул без
переполнения» — механизм подтверждён, R* +18,3 % при шуме 5,4 %, но
по букве заранее записанного критерия дрейфа не прошло; засчитано
решением автора с оговоркой (ниже).
- **Пока гипотеза:** почему на дефолтных лимитах рост останавливает
хост (энергоэффективные ядра, частота, гипервизор — замер не
разделяет); выигрыш пинга только после простоя соединения; эффект
пула 10 + 0 на дефолтных лимитах PostgreSQL.
**Следующие шаги:** ранний обработчик SIGTERM или `init` для реплики
(`KNOWN_ISSUES.md`); пинг соединения только после простоя (design
`scaling-improvement`, решение 6); причинная проба хоста («грелка» на
6 vCPU); фоновая уборка ключей в worker лабы 5; повтор замеров уровня
«4» с несколькими прогонами на фазу; пункты `KNOWN_ISSUES.md`
(evidence лабы 2 в исключениях сверки покрытия, буфер событий Docker в
профиле `failover`).
Идемпотентность:
@@ -1782,3 +2042,117 @@ PostgreSQL 0,5 CPU база насыщается около 950–1 000/с (тр
ошибками. Поэтому R* — максимальная интенсивность, которую стенд держит
с p95 ≤ 200 мс и ошибками ≤ 1 %, а не число, подогнанное
под скорость ответов.
## Источники, библиотеки и использование ИИ
**Документация** (официальные страницы; где точный адрес раздела не
указан — корень документации, раздел назван словами):
- HAProxy 3.4 — <https://docs.haproxy.org/>: Configuration Manual
(`server-template`, `resolvers`, `init-state`, `option httpchk`,
`inter` / `fastinter` / `downinter`, `fall` / `rise`, `timeout check`,
`retry-on`, `option redispatch`, `http-reuse`, `http-error`,
`monitor-uri`), Management Guide (stats socket, `set server … state`,
`show servers state`, CSV статистики).
- PostgreSQL 18 — <https://www.postgresql.org/docs/18/>:
[клиентские параметры](https://www.postgresql.org/docs/18/runtime-config-client.html)
(`statement_timeout`, `lock_timeout`,
`idle_in_transaction_session_timeout`),
[статистика](https://www.postgresql.org/docs/18/monitoring-stats.html)
(`pg_stat_activity`, `pg_stat_database`, `pg_stat_wal`, `pg_stat_io`),
[коды ошибок](https://www.postgresql.org/docs/18/errcodes-appendix.html)
(53300), `max_connections`, `INSERT … ON CONFLICT`, отложенные
ограничения (`DEFERRABLE INITIALLY DEFERRED`), явные блокировки
`ALTER TABLE`.
- SQLAlchemy 2.1 — <https://docs.sqlalchemy.org/>: Connection Pooling
(`QueuePool`, `pool_size`, `max_overflow`, `pool_pre_ping`), asyncio
extension; исходники `QueuePool` — почему соединения сверх
`pool_size` закрываются при возврате.
- asyncpg — <https://magicstack.github.io/asyncpg/>: параметры
подключения; исходники аутентификации SCRAM-SHA-256 (цена нового
соединения).
- k6 — <https://grafana.com/docs/k6/latest/>: сценарии и executors
`constant-arrival-rate` и `ramping-arrival-rate` (открытая модель),
`preAllocatedVUs`, `dropped_iterations`, итоговый JSON.
- FastAPI — <https://fastapi.tiangolo.com/>: параметры `Header`,
зависимости, порядок валидации, обработчики исключений.
- uvicorn — <https://www.uvicorn.org/settings/>: `timeout_keep_alive`,
`timeout_graceful_shutdown`, поведение по SIGTERM.
- Docker Compose — <https://docs.docker.com/reference/compose-file/>:
[services](https://docs.docker.com/reference/compose-file/services/)
(`depends_on` с условиями, `stop_grace_period`, `healthcheck`,
`start_interval`),
[deploy](https://docs.docker.com/reference/compose-file/deploy/)
(`replicas`, `resources.limits`); CLI `docker compose up --scale
--no-recreate --wait`, `docker events`, `docker stop` / `kill` /
`pause` — <https://docs.docker.com/reference/cli/docker/>.
- Linux — [cgroup v2](https://docs.kernel.org/admin-guide/cgroup-v2.html)
(`cpu.stat`, троттлинг CFS, `memory.current`) и
[PSI](https://docs.kernel.org/accounting/psi.html) для сэмплера
трека 1.
- Из лабы 2 — alembic, argon2-cffi, redis-py, Valkey (источники
перечислены в отчёте лабы 2).
**Библиотеки и образы:** FastAPI, pydantic, pydantic-settings,
structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, uvicorn
(версии — раздел «Запуск из чистого clone»); тесты — pytest, httpx;
стенд — HAProxy, PostgreSQL, Valkey, k6 в закреплённых образах.
Чужой код не копировался. Логгер и форма Makefile перенесены из
собственного учебного проекта автора (bp_proxies,
`.claude/rules/logging.md`).
**Использование ИИ.** Инструмент — Claude Code, модель Claude Opus 5.5.
Работа велась по changes OpenSpec (`openspec/changes/archive/`, шесть
changes лабы 3). Каждый change проходил этапы propose → apply → verify →
правки по verify и archive. Каждый этап выполнял отдельный субагент,
основная сессия координировала: передавала этапы, проверяла итоги,
присылала автору прогресс. 77 из 81 commit после skeleton помечены
`Co-Authored-By: Claude`; остальные четыре сделал скрипт `make bench_ab`
по ходу замера.
Что делал ИИ:
- код приложения, миграции, `docker-compose.yml`, `haproxy.cfg`,
скрипты `restart.sh`, `stop-one.sh`, `rolling-update.sh`;
- собственные тесты `student-tests/` и стенды проверок отказов;
- стенд замеров `bench/` (профили `failover`, `rollout`, серии трека 1,
сэмплер, графики, сравнение меток);
- запуск замеров и проверок, evidence, этот отчёт, правила
`.claude/rules/` и спеки OpenSpec.
Что решал автор:
- выбор трека 1 «Цена масштабирования» и Compose + HAProxy без Swarm
(2026-10-07, `PLAN.md`);
- согласования с преподавателем (FastAPI, `config.toml`);
- по verify `scaling-bench`: исправить ответ на «too many clients»
(500 → 503, правка `68edc66`) и добавить серию `db` с насыщением
PostgreSQL (`scaling-db`), потому что на дефолтных лимитах база не
насыщалась;
- сократить замеры улучшения до двух ячеек (`4x1-pg0.5`, `4x1-pg2`,
профиль `db4`) до начала замеров;
- переснять улучшение на тихом хосте после помех macOS (iCloud, Zoom)
в попытке 1;
- засчитать улучшение с оговоркой по пункту дрейфа после результатов
попытки 2 (design `scaling-improvement`, п. 4);
- коммиты и замеры в автономном режиме — с условием: перед каждым
замером проверка хоста, при плохом состоянии — остановка и вопрос.
Как проверялось:
- verify каждого change отдельным субагентом: сверка с задачами, спеками
и рубрикой; найденное правилось и evidence переснималось с
закоммиченного кода (например, `lock_timeout`, равный
`statement_timeout`, давал 503 запросам в очереди за миграцией;
уборка при Ctrl+C внутри `up --scale` оставляла третью реплику; см.
разделы выше);
- публичные проверки skeleton (`make test`, `make test-persistence`,
`make test-failover`) и собственные тесты (`make student_test`,
`make failure_checks`, `make test_isolated`) на итоговом коде каждого
change и из чистого clone;
- гипотезы трека 1 и критерии улучшения закоммичены до замеров, шум
отделён A/A той же сессии; хост проверялся перед каждой серией;
- ошибки ИИ, найденные по ходу, описаны в отчёте как есть: ошибочный
пункт `KNOWN_ISSUES.md` о `make run_docker` (диагноз по digest
конфигурации образа containerd), 500 вместо 503 на 53300, первая
попытка замера улучшения на зашумлённом хосте.
Утверждения отчёта о поведении стенда подтверждены командами, выводы
которых лежат в `evidence/`; решения, перечисленные выше, принимал
автор.
+232
View File
@@ -0,0 +1,232 @@
# Итоговая проверка из чистого clone: стенд с LB на портах по умолчанию
| | |
|---|---|
| Что проверялось | раздел `REPORT.md` «Запуск из чистого clone» — буквально, шаг за шагом, как у проверяющего |
| Дата | 2026-10-11 18:41–18:47 UTC |
| Commit | `67b4303` — `git clone --branch solution/bvt2301-safronov` локального репозитория во временный каталог; рабочее дерево клона чистое, `.env`, `config.toml` и `.venv` нет. Код итогового commit отличается от него только `REPORT.md` и этим файлом |
| Стенд | проект compose `mtusi-lab3` (имя из `docker-compose.yml`, без `COMPOSE_PROJECT_NAME`), порты по умолчанию: LB `127.0.0.1:8080`, Postgres 5433, Valkey 6380. Рабочий стенд с тем же именем проекта перед проверкой удалён вместе с volume (`make wipe_data`), чтобы клон стартовал на пустой базе со своим паролем, как у проверяющего. После проверки стенд клона удалён (`docker compose down -v`), рабочий поднят заново `make run_docker` |
| Хост | Docker Desktop 29.8.2, Compose v5.5.1, macOS arm64 (Apple M3 Pro); ВМ Docker: 12 CPU, 7,7 GiB RAM; `python3` 3.11.9, uv 0.12.17 |
Пароли из сгенерированного `.env` не выводились: проверялось только,
что они есть (32 hex-символа).
## Подготовка и запуск
```text
$ git clone --branch solution/bvt2301-safronov <репозиторий> clean-clone && cd clean-clone
$ git log --oneline -1; git status --short | wc -l; ls .env config.toml
67b4303 docs: archive scaling-improvement and sync its specs
0
ls: .env: No such file or directory
ls: config.toml: No such file or directory
$ make env_setup # exit 0
env ready: .env, config.toml
$ grep -c -E '^(POSTGRES|VALKEY)_PASSWORD=.{32}$' .env
2
$ make run_docker # exit 0, 4,3 с (слои — из кэша BuildKit)
DOCKER_BUILDKIT=1 docker compose build
Image mtusi-messenger:lab3 Building
#4 [internal] load metadata for docker.io/library/python:3.12.14-slim-trixie@sha256:f77ac9e4…
Container mtusi-lab3-postgres-1 Healthy
Container mtusi-lab3-valkey-1 Healthy
Container mtusi-lab3-migrate-1 Exited
Container mtusi-lab3-api-1 Started
Container mtusi-lab3-api-2 Started
Container mtusi-lab3-haproxy-1 Started
$ docker compose ps -a --format 'table {{.Name}}\t{{.Status}}\t{{.Ports}}'
NAME STATUS PORTS
mtusi-lab3-api-1 Up 9 seconds (healthy) 8080/tcp
mtusi-lab3-api-2 Up 9 seconds (healthy) 8080/tcp
mtusi-lab3-haproxy-1 Up 9 seconds (healthy) 127.0.0.1:8080->8080/tcp
mtusi-lab3-migrate-1 Exited (0) 10 seconds ago
mtusi-lab3-postgres-1 Up 13 seconds (healthy) 127.0.0.1:5433->5432/tcp
mtusi-lab3-valkey-1 Up 13 seconds (healthy) 127.0.0.1:6380->6379/tcp
$ docker compose logs migrate --no-log-prefix | tail -5 # поле event
Running upgrade -> 16c279725564, added messenger tables
Running upgrade 16c279725564 -> 42bc3b9be38f, added sessions and password hashes
Running upgrade 42bc3b9be38f -> 7652184b7016, added idempotency keys
Running upgrade 7652184b7016 -> e656d6bbe1a4, added message instance id
Finished alembic
```
`8080/tcp` у реплик — `EXPOSE` образа: опубликованного порта у них
нет, API на хосте — только через HAProxy.
Сборка без кэша слоёв из того же клона (отдельный тег, затем удалён):
```text
$ docker build --no-cache --pull -t mtusi-clean-check:nocache . # exit 0, 10,5 с
$ docker run --rm --entrypoint sh mtusi-clean-check:nocache -c 'id -u; ls /app; …'
10001
alembic.ini
migrations
src
no-.env
no-config.toml
```
Колёса зависимостей `uv sync --locked` берёт из cache mount BuildKit,
поэтому 10 с; на машине без кэша добавится их загрузка.
## Контракт, smoke и распределение
```text
$ make check # exit 0
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ uv sync # .venv клона с группой dev
$ make validate PYTHON=.venv/bin/python # exit 0
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
$ make test # exit 0
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
$ make instances
11 GET /api/v1/users/me 200 x-instance-id: 437292ccaf78
12 GET /api/v1/users/me 200 x-instance-id: 0089ca350b2b
user lb_c34d4132: one login, 12 requests with one token
437292ccaf78: 6
0089ca350b2b: 6
instances: 2
```
## `make test-persistence`
```text
$ docker inspect … (до) имя, ID, состояние, StartedAt
/mtusi-lab3-api-1 0089ca350b2b running 2026-10-11T18:41:29Z
/mtusi-lab3-api-2 437292ccaf78 running 2026-10-11T18:41:29Z
/mtusi-lab3-haproxy-1 588c7fcc58e0 running 2026-10-11T18:41:29Z
/mtusi-lab3-postgres-1 e4b53ac23602 running 2026-10-11T18:41:26Z
/mtusi-lab3-valkey-1 fca2cb095076 running 2026-10-11T18:41:26Z
$ make test-persistence ACTION_SCRIPT=scripts/restart.sh # exit 0
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
$ docker inspect … (после)
/mtusi-lab3-api-1 0089ca350b2b running 2026-10-11T18:41:58Z
/mtusi-lab3-api-2 437292ccaf78 running 2026-10-11T18:41:58Z
/mtusi-lab3-haproxy-1 588c7fcc58e0 running 2026-10-11T18:41:58Z
/mtusi-lab3-postgres-1 e4b53ac23602 running 2026-10-11T18:41:54Z
/mtusi-lab3-valkey-1 fca2cb095076 running 2026-10-11T18:41:54Z
$ docker volume inspect -f '{{.Name}} {{.CreatedAt}}' mtusi-lab3_postgres_data
mtusi-lab3_postgres_data 2026-10-11T18:41:25Z
```
Перезапущены LB, обе реплики, Postgres и Valkey: те же ID, новый
`StartedAt`. Volume тот же, что создал `make run_docker`.
## `make test-failover` для каждой реплики
`STOP_ONE_LOG` — строка hook: какой `TARGET_INSTANCE_ID` выбрал тест и
какой контейнер остановлен.
```text
$ STOP_ONE_LOG=<файл> make test-failover ACTION_SCRIPT=scripts/stop-one.sh # exit 0
{"observed_instances_before": 2, "successful_writes": 118, "failed_attempts": 0, "first_recovery_seconds": 1.0}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
2026-10-11T18:42:05Z TARGET_INSTANCE_ID=0089ca350b2b container=0089ca350b2bcbee… mode=stop
$ docker compose ps -a --format 'table {{.Name}}\t{{.ID}}\t{{.Status}}'
mtusi-lab3-api-1 0089ca350b2b Exited (0) 14 seconds ago
mtusi-lab3-api-2 437292ccaf78 Up 21 seconds (healthy)
$ make replicas # тот же контейнер api-1 снова healthy
$ make lb_stats
api-1 172.30.0.5:8080 UP L7OK …
api-2 172.30.0.4:8080 UP L7OK …
$ curl -s -o /dev/null -D - http://127.0.0.1:8080/health/live | grep -i x-instance-id
x-instance-id: 437292ccaf78 # сдвиг очереди round-robin одним запросом
$ STOP_ONE_LOG=<файл> make test-failover ACTION_SCRIPT=scripts/stop-one.sh # exit 0
{"observed_instances_before": 2, "successful_writes": 113, "failed_attempts": 0, "first_recovery_seconds": 0.991}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
2026-10-11T18:42:31Z TARGET_INSTANCE_ID=437292ccaf78 container=437292ccaf78… mode=stop
$ docker compose ps -a …
mtusi-lab3-api-1 0089ca350b2b Up 20 seconds (healthy)
mtusi-lab3-api-2 437292ccaf78 Exited (0) 14 seconds ago
$ make replicas
$ STOP_MODE=kill STOP_ONE_LOG=<файл> make test-failover ACTION_SCRIPT=scripts/stop-one.sh # exit 0
{"observed_instances_before": 2, "successful_writes": 114, "failed_attempts": 0, "first_recovery_seconds": 0.221}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
2026-10-11T18:42:56Z TARGET_INSTANCE_ID=437292ccaf78 container=437292ccaf78… mode=kill
mtusi-lab3-api-2 437292ccaf78 Exited (137) 15 seconds ago
$ make replicas; make lb_stats
api-1 172.30.0.5:8080 UP L7OK 0 205 0 0 5 0
api-2 172.30.0.4:8080 UP L7OK 0 307 0 0 2 0
BACKEND - UP - 0 507 2 0 7 2
free slots: 6
```
Остановлены по очереди обе реплики: ID остановленного контейнера
совпадает с `TARGET_INSTANCE_ID`, остальные работают; первая запись
после остановки — через 1,0 и 0,99 с (`stop`) и 0,22 с (`kill`),
неудачных попыток 0. У слотов реплик 5xx нет; два `hrsp_5xx` у
`BACKEND` — ответы самого LB. Счётчики обнулил рестарт LB в
`restart.sh`, после него тест сохранности ждёт готовности опросом, а
до проверок реплик LB отвечает 503 (так же в
`evidence/replicas/test-persistence.md`). Журнал LB до уборки клона не
сохранялся, так что это объяснение, а не сверка по журналу; клиенту
тестов отказа ни одна ошибка не досталась (`failed_attempts` 0).
## Собственные тесты
```text
$ make student_test # exit 0, 23,7 с
coverage: 137 scenarios in 11 specs, 125 tested (18 by make failure_checks), 12 excluded
one session, 20 requests: {'437292ccaf78': 10, '0089ca350b2b': 10}
key race through replicas: {'437292ccaf78': 5, '0089ca350b2b': 5}
===================== 131 passed, 17 deselected in 22.98s ======================
$ make failure_checks # exit 0, 69 с
[failure_checks] project=mtusi-lab3-failures (working stand: mtusi-lab3)
test_expired_token PASSED test_readiness_without_database PASSED
test_use_does_not_extend_session PASSED test_readiness_without_cache PASSED
test_token_while_database_stopped PASSED test_flush_cache PASSED
test_members_failure_rolls_back_chat PASSED test_valkey_stopped PASSED
test_database_stopped_and_back PASSED test_valkey_paused PASSED
test_pool_exhausted PASSED test_valkey_back PASSED
test_connection_limit_reached PASSED test_message_failure_keeps_key_free PASSED
test_pool_keeps_connections PASSED test_database_outage_keeps_key_free PASSED
test_key_free_after_ttl PASSED
================ 17 passed, 131 deselected in 60.82s (0:01:00) =================
Volume mtusi-lab3-failures_postgres_data Removed
Network mtusi-lab3-failures_default Removed
$ make test_isolated # exit 0, 65 с
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
SKIPPED [1] student-tests/test_idempotency.py:282: one API process (EXPECT_REPLICAS=1): replica checks need the stand with the load balancer
… (ещё 3 теста реплик с той же причиной)
================ 127 passed, 4 skipped, 17 deselected in 58.11s ================
[test_isolated] cleanup
[test_isolated] results: {'test': 0, 'student_test': 0}
```
## Уборка и рабочий стенд
```text
$ docker compose down -v # в каталоге клона, проект mtusi-lab3
Volume mtusi-lab3_postgres_data Removed
Network mtusi-lab3_default Removed
$ docker ps -a --filter name=failures -q | wc -l
0
$ make run_docker # в каталоге рабочего репозитория, exit 0
$ docker compose ps --format '{{.Name}} {{.Status}}'
mtusi-lab3-api-1 Up 6 seconds (healthy)
mtusi-lab3-api-2 Up 6 seconds (healthy)
mtusi-lab3-haproxy-1 Up 6 seconds (healthy)
mtusi-lab3-postgres-1 Up 9 seconds (healthy)
mtusi-lab3-valkey-1 Up 9 seconds (healthy)
$ make lb_stats
api-1 172.30.0.5:8080 UP L7OK …
api-2 172.30.0.4:8080 UP L7OK …
free slots: 6
```
Итог: все шаги инструкции из настоящего clone прошли с кодом 0 без
правки файлов клона; дефектов не найдено. Стенд лабы 2
(`mtusi-lab2_postgres_data`) не затронут.