From 063eedbc71c6e9337f9c451faf1fe1ef7d89b002 Mon Sep 17 00:00:00 2001 From: roman Date: Sun, 11 Oct 2026 21:53:13 +0300 Subject: [PATCH] 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 --- REPORT.md | 444 +++++++++++++++++++++++++--- evidence/tests/clean-clone-final.md | 232 +++++++++++++++ 2 files changed, 641 insertions(+), 35 deletions(-) create mode 100644 evidence/tests/clean-clone-final.md diff --git a/REPORT.md b/REPORT.md index 8f00762c..ef077dca 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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 && 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 — : 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/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 — : Connection Pooling + (`QueuePool`, `pool_size`, `max_overflow`, `pool_pre_ping`), asyncio + extension; исходники `QueuePool` — почему соединения сверх + `pool_size` закрываются при возврате. +- asyncpg — : параметры + подключения; исходники аутентификации SCRAM-SHA-256 (цена нового + соединения). +- k6 — : сценарии и executors + `constant-arrival-rate` и `ramping-arrival-rate` (открытая модель), + `preAllocatedVUs`, `dropped_iterations`, итоговый JSON. +- FastAPI — : параметры `Header`, + зависимости, порядок валидации, обработчики исключений. +- uvicorn — : `timeout_keep_alive`, + `timeout_graceful_shutdown`, поведение по SIGTERM. +- Docker Compose — : + [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` — . +- 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/`; решения, перечисленные выше, принимал +автор. diff --git a/evidence/tests/clean-clone-final.md b/evidence/tests/clean-clone-final.md new file mode 100644 index 00000000..c4ff93d7 --- /dev/null +++ b/evidence/tests/clean-clone-final.md @@ -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`) не затронут.