Save sanitized outputs from a stand started from a clean state: the clean clone run, smoke through the balancer, the stack view with the replica hostnames, ports, networks, limits and the balancer server states, the probe with two replicas behind one token and the eight way race on one key, a failover run for each replica with the container left exited and its graceful shutdown log, the hook negative cases and the balancer answer without replicas, the persistence run with StartedAt of every container before and after, schema, migration rerun, KDF prefix, ignore rules, own tests and the lab 2 stack fault tests through the balancer, plus the environment. The report covers the clean clone start, the architecture, the X-Instance-Id and idempotency decisions, the balancer settings, the role to service table, the mapping of .env.example to the real variables, one evidence row per level 3 criterion and the carried lab 2 minimum, and the failure table for level 3. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
28 KiB
Отчёт — лабораторная 3
- Автор, группа: Костылев Артём, БПИ2303
- Целевая оценка: 5; трек «5» — трек 1 «Цена масштабирования»
- Commit/PR: ветка
solution/bpi2303-kostylev, PR в репозиторий преподавателя - Использованные источники, библиотеки и помощь ИИ: FastAPI, gunicorn + uvicorn-worker, dishka, pydantic,
structlog, asyncpg, argon2-cffi, redis-py, pytest, ruff, ty (версии —
evidence/environment.txtиuv.lock); HAProxy 3.2 Configuration Manual (health checks, resolvers,retry-on,http-error), документация Docker Compose (deploy.replicas,depends_on, secrets), PostgreSQL (SELECT … FOR UPDATE,INSERT … ON CONFLICT, уровни изоляции), IETF draft «The Idempotency-Key HTTP Header Field». Решение перенесено из моей лабы 2 и выполнено с помощью Claude Code; код, стенд и отказы проверены прогонами, перечисленными ниже.
Запуск из чистого clone
Требуются Docker с Compose v2 и make; системный Python 3.9+ — только для публичных проверок и
scripts/probe.py. Образы сторонних сервисов закреплены версией и digest, API собирается из исходников.
git clone <repo> && cd mtusi2026lab3 && git checkout solution/bpi2303-kostylev
make secrets # secrets/* (пароли PostgreSQL и Valkey, DATABASE_URL, CACHE_URL, ключ курсора) и .env из .env.example
docker compose --env-file .env config --quiet
make up # docker compose up -d --build --wait: postgres, valkey → migrate → api ×2 → lb, ждёт healthy
make test # публичный smoke через балансировщик, http://localhost:8080
make lb-check # ≥2 X-Instance-Id на одном токене и 8 параллельных POST с одним ключом → evidence/lb-check.json
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make restore # вернуть остановленную реплику и дождаться её в ротации LB
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make down # безопасная остановка: контейнеры удаляются, volumes с данными остаются
make reset-data # НАМЕРЕННОЕ удаление учебных данных: docker compose down -v
make up ждёт не только healthy реплик, но и healthy балансировщика, а он здоров, только когда в ротации
есть реплика (/healthz на порту статистики). Миграции применяет одноразовый migrate до старта реплик.
Публикуются только порты lb на 127.0.0.1: LB_HTTP_PORT (по умолчанию 8080) и LB_STATS_PORT (8404,
статистика только для чтения). На машине, где выполнялась работа, параллельно работали стенды других лаб,
поэтому в локальном .env стояли LB_HTTP_PORT=18083, LB_STATS_PORT=23083, а проверки запускались с
BASE_URL=http://localhost:18083. Прогон из свежего clone — evidence/clean-clone.txt.
Собственные проверки и тулчейн:
make install # uv sync --group dev (Python 3.14 и зависимости из uv.lock)
make lint # ruff check + ruff format --check (src, student-tests, scripts/probe.py) + ty check
make student-test # собственные тесты; поднимают одноразовые PostgreSQL и Valkey того же образа в Docker
make check # офлайн-проверка skeleton
make validate PYTHON=.venv/bin/python # полная валидация OpenAPI
make test-faults # тесты стенда лабы 2 (Valkey, PostgreSQL, гонки) через балансировщик
make failover-evidence # docker inspect реплик до/после, make test-failover, логи остановленной, restore
make persistence-evidence # persistence-тест + StartedAt всех контейнеров до и после
make stack-evidence # сервисы, порты, hostname ↔ X-Instance-Id, лимиты, сети, взгляд LB
make storage-evidence # \d+ схемы, повтор миграций, префикс KDF, правила ignore
Версии и стенд: Python 3.14.7 в образе python:3.14-slim-trixie@sha256:51dafde8…,
haproxy:3.2.26-alpine@sha256:58938405…, postgres:17.11-alpine@sha256:266d3c25…,
valkey/valkey:8.1.11-alpine@sha256:2602ace2…, uv 0.9.7 по digest, Docker 28.3.2, Compose 2.38.2. Машина —
Apple M4 Max, 16 CPU, 48 ГБ RAM, macOS 15.1; VM Docker Desktop — 16 CPU, 7.65 ГиБ (evidence/environment.txt).
Архитектура и решения
┌── api (gunicorn, 2 × UvicornWorker) ──┐ asyncpg pool, 1–2 с
клиент ──HTTP──▶ lb (HAProxy 3.2) ───┤ X-Instance-Id = hostname ├──▶ postgres (источник истины, pgdata)
127.0.0.1:8080 round robin, └── api (gunicorn, 2 × UvicornWorker) ──┘──▶ valkey (кэш сессий, AOF, valkeydata)
httpchk /health/ready migrate (тот же образ, один раз до реплик) ──▶ postgres
сеть edge ─────── lb ─────── сеть backend (internal): lb, api, migrate, postgres, valkey
Перенесено из лабы 2 без изменения поведения: зоны identity и messaging, порты и адаптеры, UoW, шина
событий с журналом аудита, ASGI-конвейер, Basic → Bearer, Argon2id, сессии в PostgreSQL с read-through кэшем
в Valkey и отметками отзыва, подписанный курсор, порядок истории под блокировкой строки чата, миграции под
advisory lock, тесты стенда (make test-faults). Уже в лабе 2 реплика не держала в памяти ничего, от чего
зависит корректность: кэш и отметки отзыва общие (Valkey), курсор подписан общим секретом, отметка
created_at назначается под блокировкой строки чата, а не часами процесса. Изменено: один контейнер с
портом → сервис api с deploy.replicas за HAProxy; X-Instance-Id; обязательный Idempotency-Key;
миграция 0002; restart.sh перезапускает и LB; таймауты и воркеры под реплики; удалён api-shortttl
(публиковал порт API в обход LB, проверка истечения TTL осталась in-process тестом).
X-Instance-Id. PlatformSettings.instance_id по умолчанию — socket.gethostname(); Docker даёт
контейнеру hostname, равный короткому ID, поэтому значение одно на все воркеры реплики, стабильно на жизнь
контейнера и совпадает с docker ps (evidence/stack.txt). Конвейер ставит заголовок рядом с
X-Request-Id на каждый ответ, проходящий через него; ответ 500 формирует внешний ServerErrorMiddleware,
поэтому обработчик необработанных исключений ставит оба заголовка сам. INSTANCE_ID в compose не задаётся:
он был бы одинаков у всех реплик.
Идемпотентная отправка (зона messaging). Таблица idempotency_keys (chat_id, user_id, key, fingerprint, message_id, created_at), PK (chat_id, user_id, key) — область «пользователь + метод + путь чата + ключ»
(ключ бывает только у POST …/messages), FK (chat_id, user_id) → chat_members и message_id → messages,
CHECK формата ключа и длины отпечатка. Обработчик в одной транзакции:
SELECT … FROM chats WHERE id = $1 FOR UPDATE→404, если чата нет;- членство (
404), затем текст (400) — в памяти; - квитанция по PK, моложе
IDEMPOTENCY_TTL_SECONDS: тот же отпечаток → сохранённое сообщение (201, тот жеMessageOut,created_atхранится с микросекундами); другой →409 conflict; - квитанции нет → один оператор:
INSERT messages+INSERT idempotency_keys … ON CONFLICT DO UPDATE(перезапись истёкшего ключа) +UPDATE chats.last_message_at;COMMIT.
Сообщение и ключ фиксируются вместе или не фиксируются вовсе; маркера «в обработке» нет, поэтому после
гибели реплики посреди запроса повтор с тем же ключом создаёт сообщение один раз. Одновременные повторы
одного ключа всегда идут в один чат и ждут на блокировке его строки; следующий оператор в READ COMMITTED
видит зафиксированную квитанцию. Отпечаток — SHA-256 канонического JSON распарсенной модели, поэтому
порядок полей и пробелы не важны. Ответы 4xx/5xx ничего не пишут; lock_timeout теперь 503, а не 500.
Отвергнуто: SET NX в Valkey (не атомарен с COMMIT), отдельный маркер «processing» (залипает после отказа).
Балансировщик (infra/haproxy/haproxy.cfg):
| Параметр | Значение | Зачем |
|---|---|---|
| Обнаружение | server-template api 8 api:8080, resolvers docker (127.0.0.11), init-addr none |
остановленная реплика пропадает из DNS, новая появляется без перезапуска LB и без docker.sock |
| Алгоритм | balance roundrobin, без stick |
каждое новое соединение — следующая реплика; сессия общая, привязка не нужна |
| Проверка | GET /health/ready, inter 1s fastinter 500ms fall 2 rise 2, timeout check 1s |
реплика без БД или в остановке выходит из ротации |
| Повторы | retries 2, redispatch 1, retry-on conn-failure empty-response; disable-l7-retry всем, кроме GET и POST …/messages с ключом |
отказ соединения повторяется всегда (запрос не ушёл); после отправки — только безопасное к повтору; POST /users, /chats, вход не повторяются (contracts/README.md) |
| Соединения к API | option http-server-close |
нет простаивающих keep-alive, за которые гонится остановка реплики |
| Таймауты | connect 500ms, server 10s > REQUEST_TIMEOUT_SECONDS=8 > statement_timeout 2 с; queue 3s, maxconn 64 на сервер |
цепочка клиент > LB > приложение > БД |
| Ошибки LB | 502/503/504 — JSON {"error":{…,"request_id"}} с тем же X-Request-Id |
формат контракта даже без реплик (evidence/hooks.txt) |
X-Request-Id |
непустой входящий до 200 символов пробрасывается, иначе uuid4 | приложение эхо-возвращает его |
| Остановка | SIGUSR1, hard-stop-after 5s |
мягкий стоп внутри stop_grace_period |
Остановка и процессы. SHUTDOWN_TIMEOUT_SECONDS=5 (gunicorn graceful_timeout, uvicorn
timeout_graceful_shutdown) < stop_grace_period: 8s; stop-one.sh останавливает docker stop -t 6. По
SIGTERM gunicorn закрывает listener — LB получает отказ соединения и повторяет запрос на соседней реплике.
На реплику cpus: 1, 512m, 2 воркера, пул 8: 2 × 2 × 8 = 32 соединения < max_connections=200. API
работает read_only с tmpfs /tmp.
Хуки. scripts/stop-one.sh — контейнер api с .Config.Hostname == TARGET_INSTANCE_ID → docker stop -t 6,
реплика остаётся остановленной, неизвестный ID → код 3 без изменений. scripts/restart.sh — stop lb api,
restart postgres valkey, up -d --no-recreate --wait (те же контейнеры, повторный migrate), volumes не
трогаются. scripts/restore.sh — up --no-deps --no-recreate --wait api, затем scripts/lb-wait.sh ждёт, пока
статистика LB покажет все реплики UP.
Роли и сервисы (compose.yaml; сети edge и backend с internal: true):
| Роль | Сервис | Версия / digest | Health / readiness | Volume | Сеть / порт | Credentials |
|---|---|---|---|---|---|---|
| load_balancer | lb |
haproxy:3.2.26-alpine@sha256:58938405…, uid 99, read_only, cap_drop: ALL |
/healthz :8404 (nbsrv(api) ≥ 1); проверяет реплики GET /health/ready |
нет | edge + backend; 127.0.0.1:${LB_HTTP_PORT:-8080}, 127.0.0.1:${LB_STATS_PORT:-8404} |
нет |
api ×API_REPLICAS |
api |
сборка из Dockerfile, python по digest, uid 10001, read_only |
GET /health/ready (пингует PostgreSQL) |
нет | backend, порт не публикуется |
secrets database_url, cache_url, cursor_secret через *_FILE |
| postgres | postgres |
postgres:17.11-alpine@sha256:266d3c25…, uid 70, pg_stat_statements |
pg_isready |
pgdata:/var/lib/postgresql/data |
backend |
secret postgres_password через POSTGRES_PASSWORD_FILE |
| сессии (кэш) | valkey |
valkey/valkey:8.1.11-alpine@sha256:2602ace2…, uid 999 |
valkey-cli ping с паролем |
valkeydata:/data (AOF) |
backend |
secret valkey.conf (requirepass) |
| bootstrap | migrate |
образ api, restart: "no" |
код выхода 0 | нет | backend |
secret database_url |
Готовность реплики зависит только от PostgreSQL: Valkey — кэш, при его отказе проверка идёт в БД. Общее
хранилище сессий — PostgreSQL (источник истины) плюс общий Valkey. Bootstrap: make secrets (идемпотентен,
не перезаписывает существующие файлы), make up (миграции — migrate под advisory lock); повтор безопасен.
Лимиты: lb 1 CPU/128m, api 1 CPU/512m на реплику, migrate 0.5/256m, postgres 2/1g, valkey 0.5/128m.
Соответствие .env.example реальной конфигурации:
.env.example |
В решении | Комментарий |
|---|---|---|
APP_HOST, APP_PORT |
HOST, PORT |
заданы в образе (0.0.0.0:8080); снаружи — порт LB LB_HTTP_PORT |
APP_ENV |
не используется | режимов окружения нет |
SESSION_TTL_SECONDS |
SESSION_TTL_SECONDS |
по умолчанию 3600 |
DATABASE_URL_FILE |
DATABASE_URL_FILE |
любой параметр читается из <ИМЯ>_FILE |
SESSION_STORE=postgres |
фиксировано | PostgreSQL — источник истины сессий, Valkey — кэш поверх него |
CACHE_URL_FILE |
CACHE_URL_FILE |
без него кэш выключен |
API_REPLICAS |
deploy.replicas: ${API_REPLICAS:-2} |
число реплик сервиса api |
IDEMPOTENCY_TTL_SECONDS |
IDEMPOTENCY_TTL_SECONDS |
86 400; квитанция старше срока перезаписывается новым запросом |
| — | LB_HTTP_PORT, LB_STATS_PORT |
опубликованные порты LB на 127.0.0.1 |
| — | API_CPUS, API_MEMORY, WEB_CONCURRENCY, DB_POOL_MAX_SIZE, API_SERVER_MAXCONN |
размер реплики, воркеры, пул на воркер, очередь LB на сервер |
| — | PG_MAX_CONNECTIONS, PG_CPUS, PG_MEMORY, LB_CPUS |
лимиты PostgreSQL и LB |
| — | REQUEST_TIMEOUT_SECONDS, SHUTDOWN_TIMEOUT_SECONDS |
8 с и 5 с (заданы в compose и образе) |
| — | CURSOR_SECRET_FILE |
общий ключ подписи курсора для всех реплик |
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make test BASE_URL=http://localhost:18083 |
PASS: lab3 public API scenario (включая replay == first, 409 на другой body, 400 без ключа, X-Instance-Id на каждом ответе) |
evidence/smoke.txt |
| Запуск из чистого clone | git clone, make secrets, config --quiet, make up, make test |
valid; все сервисы Healthy, migrate Exited (0) за 15 с; smoke PASS |
evidence/clean-clone.txt |
3.1 Весь стенд в compose.yaml, ≥2 API, одна точка входа, общая БД и общее хранилище сессий |
make stack-evidence (config --quiet, ps, port api 8080, docker inspect, статистика LB) |
2 контейнера api без портов (no port 8080/tcp), порты только у lb на 127.0.0.1; container_name 0; LB видит api1 UP L7OK 200, api2 UP L7OK 200; один postgres, один valkey |
evidence/stack.txt |
3.2 Разные запросы одного пользователя — разные реплики без повторного входа, видно по X-Instance-Id |
make lb-check (40 × GET /users/me одним токеном, новые соединения) + docker inspect |
{"302cfee8f673": 20, "b582bd503bdd": 20} — ровно hostname двух контейнеров api |
evidence/lb-check.json, evidence/stack.txt |
| 3.3 Остановка любой одной реплики: ≤10 с, данные доступны, ошибки измерены | make failover-evidence → make test-failover ACTION_SCRIPT=scripts/stop-one.sh, docker inspect до/после, restore; второй прогон после сдвига round robin |
реплика 302cfee8f673: восстановление записи 1.21 с, 123 записи после, 0 ошибок; реплика b582bd503bdd: 1.73 с, 118, 0; именно target в exited, в логе — штатная остановка gunicorn; PASS: failover … |
evidence/failover-302cfee8f673.txt, evidence/failover-b582bd503bdd.txt |
| 3.3 Хук останавливает только заданную реплику | scripts/stop-one.sh с hostname, с неизвестным ID и без него |
хук 0.68 с, код 0, target exited с кодом 0; неизвестный ID → код 3, всё работает; без переменной → код 1 |
evidence/hooks.txt |
| 3.4 Повтор с тем же ключом не создаёт дубль; конкурентный повтор и смена реплики | make lb-check (8 параллельных POST с одним ключом через LB); make student-test -k idempotency; failover-тест (после ошибки — тот же ключ и текст) |
8 × 201 с одинаковым телом от обеих реплик (4 + 4), в истории 1 копия, другой body → 409; in-process: 8 повторов через два экземпляра приложения → одна строка ключа |
evidence/lb-check.json, evidence/student-tests.txt, evidence/failover-*.txt |
| 3.4 Неподтверждённую запись можно безопасно повторить | make student-test -k "rejected_attempt or expired or concurrent"; failover-тест сверяет историю байт-в-байт |
4xx не занимает ключ; истёкший ключ начинает заново; в истории после отказа нет дублей id/text |
evidence/student-tests.txt, evidence/failover-*.txt |
3.5 make test, persistence и failover проходят; ≥2 наблюдаемых реплики |
make test, make persistence-evidence, make test-failover … |
smoke PASS; persistence PASS, StartedAt у lb, обеих api, postgres, valkey, migrate после теста новее, контейнеры те же; failover observed_instances_before: 2 |
evidence/smoke.txt, evidence/persistence.txt, evidence/failover-*.txt |
| Перенос lab2: схема PK/FK/UNIQUE и миграции с нуля, повтор без дублей | make reset-data && make up; make storage-evidence |
0001_init, 0002_idempotency_keys применены; повтор up to date, счётчики строк равны (сообщений столько же, сколько ключей) |
evidence/schema.txt, evidence/migrations.txt |
Перенос lab2: Basic только на /auth/sessions, Bearer, logout, X-User-Id игнорируется |
make test; make student-test; make test-faults |
smoke PASS; logout 204 → 401 → 401 через LB |
evidence/smoke.txt, evidence/student-tests.txt, evidence/faults.txt |
| Перенос lab2: password KDF | make storage-evidence |
$argon2id$v=19$m=19456,t=2,p=1$ у всех пользователей; в sessions только 32-байтовые SHA-256 |
evidence/kdf.txt |
| Перенос lab2: секреты и volumes вне Git | git ls-files secrets .env; git check-ignore -v … |
пусто; пути игнорируются | evidence/secrets.txt |
| Перенос lab2: отказы Valkey и PostgreSQL через LB | make test-faults BASE_URL=http://localhost:18083 |
10 passed: гонка регистрации 201×1/409×49, rollback чата, остановка Valkey и PostgreSQL (503 ≤ 0.02 с, готовность через 0.3 с), рестарт API |
evidence/faults.txt |
X-Instance-Id на каждом ответе приложения |
make student-test -k instance |
200, 204, 400, 401, 404, скрытый 405, 413, 500 несут один ID реплики и X-Request-Id |
evidence/student-tests.txt |
| Непривилегированные процессы | make stack-evidence |
api — uid 10001, lb — 99, postgres — 70, valkey — 999 | evidence/environment.txt |
Строки уровня «4» и трека «5» добавляются следующими openspec-изменениями лабы.
Эксперименты и отказы
Стенд: 2 реплики × (1 CPU, 512 MiB, 2 воркера), PostgreSQL 2 CPU / 1 GiB, HAProxy 1 CPU / 128 MiB, Valkey
0.5 CPU / 128 MiB; Docker Desktop на Apple M4 Max. Нагрузка в failover-тесте — один клиент, POST каждые
0.1 с в течение 15 с, таймаут 2 с, повтор после ошибки с тем же ключом.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
stop api#1 (stop-one.sh, 302cfee8f673) |
запись продолжается ≤10 с, target больше не отвечает | 0 неудачных попыток, 123 записи после хука, последние 5 ответов — от b582bd503bdd |
первая запись через 1.21 с от старта хука (хук ≈0.7 с); потерь и дублей нет |
stop api#2 (после restore, b582bd503bdd) |
то же для второй реплики | 0 неудачных попыток, 118 записей после хука | 1.73 с; потерь и дублей нет |
Полный restart (restart.sh: lb, api ×2, postgres, valkey) |
прежний токен работает, история побайтно та же | persistence PASS, StartedAt всех контейнеров обновился, ID контейнеров прежние |
стенд healthy ≈12 с; потерь нет |
| Конкурентный одинаковый ключ (8 POST через LB) | одно сообщение, все ответы равны | 8 × 201, 4 + 4 по репликам, 1 копия, другой body → 409 |
— |
| Все реплики остановлены | LB отвечает 503 в формате контракта |
503 {"error":{"code":"unavailable",…,"request_id":"no-replica-1"}} |
после make restore — 200 |
docker compose stop postgres |
реплики выходят из ротации, ответы 503, а не 500 |
503 за ≤0.02 с на ready, me, login, register; live 200 |
после start готовность через 0.3 с без рестарта API |
docker compose stop valkey |
проверка сессий через PostgreSQL, без анонимного доступа | действующий токен 200, неизвестный 401, выход 503 |
после start выход 204 |
Повторный migrate |
схема и данные не меняются | up to date, счётчики равны |
— |
Ограничения и следующие шаги
- Один Docker-host: потеря host, LB или PostgreSQL — отказ всего стенда. LB и БД — единственные точки отказа; их резервирование вне рамок лабы.
- Цель failover-теста выбирает round robin (кто обслужил первое сообщение); для второй реплики тест
повторяется после
make restore, при необходимости с одним лишним запросом через LB. X-Instance-Idраскрывает короткий ID контейнера — допустимо до лабы 7, где появится непрозрачный alias.- Таблица ключей растёт вместе с историей (строка на сообщение); истёкшие ключи только перезаписываются при повторном использовании, фоновой очистки нет.
- Запись в один горячий чат сериализуется блокировкой строки чата; повтор с ключом берёт ту же блокировку.
- Время обнаружения отказа, поочерёдная остановка под нагрузкой, rolling update и замер лимитов — уровень «4»; серии 1/2/4 реплик и поиск насыщения — трек «5».