Files
mtusi2026lab3/REPORT.md

14 KiB
Raw Permalink Blame History

Отчёт — лабораторная 3

  • Автор: Владислав Гавриленко, БПИ2303.
  • Целевая оценка: 3; исследовательские треки 5 не заявлены.
  • MR: ЛР 3 — БПИ2303 — Гавриленко — на 3, #146.
  • Ветка: solution/bpi2303-gavrilenko, форк: https://gitea.privcloud.tech/sxdees/mtusi2026lab3.
  • Основа: собственная реализация из соседнего mtusi2026lab2: src/, миграция 001_initial.sql, Dockerfile, зависимости, генерация secrets и собственные тесты. Первая лаба лежит в GitFlic; исходный код её HTTP API уже включён в lab2. Публичные tests/, contracts/, README задания и COURSE сохранены из skeleton lab3.
  • Источники: контракт этого репозитория, Python standard library и psycopg 3.2.10; DNS HAProxy, остановка socketserver. Реализация и оформление подготовлены с помощью Codex.

Запуск из чистого clone

Нужны Docker Engine с Compose v2+ и Python 3.9+ для проверок. Проверено: Docker 29.8.2, Compose 5.5.0, macOS arm64 / OrbStack, Mac15,6; Docker VM: 11 CPU, 9 434 726 400 bytes RAM. Образы: Python 3.13.7 slim-bookworm, PostgreSQL 17.6 bookworm, HAProxy 3.2.6 alpine. У API лимит 0.5 CPU / 256 MiB на реплику, БД 1 CPU / 512 MiB, LB 0.5 CPU / 128 MiB. Сторонняя зависимость API — psycopg[binary] 3.2.10.

git clone -b solution/bpi2303-gavrilenko https://gitea.privcloud.tech/sxdees/mtusi2026lab3.git
cd mtusi2026lab3
scripts/setup.sh
docker compose config --quiet
docker compose up -d --build --wait
curl --fail http://localhost:8083/health/ready
make check test BASE_URL=http://localhost:8083
python3 student-tests/check.py --base-url http://localhost:8083
python3 student-tests/idempotency.py --base-url http://localhost:8083
docker compose exec -T api python - < student-tests/db_check.py
make test-persistence BASE_URL=http://localhost:8083 ACTION_SCRIPT=scripts/restart.sh
make test-failover BASE_URL=http://localhost:8083 ACTION_SCRIPT=scripts/stop-one.sh
docker compose ps --all
docker compose up -d --wait

setup.sh создаёт случайный пароль, DSN в secrets/ и .env, существующие файлы не перезаписывает. Secrets не коммитятся; хостовый каталог доступен только владельцу. DSN доступен UID приложения внутри контейнера через read-only mount. HOST_PORT=8083 выбран, чтобы не мешать соседним лабораторным; тестам явно передаётся BASE_URL. На хосте опубликован только LB на loopback. API_REPLICAS по умолчанию 2 (для лабы минимум 2, конфигурация LB содержит до 10 мест), SESSION_TTL_SECONDS=3600, IDEMPOTENCY_TTL_SECONDS=86400 (меньше 24 часов запрещено). APP_HOST/APP_PORT и путь DATABASE_URL_FILE заданы в Compose; SESSION_STORE — PostgreSQL. APP_ENV, CACHE_URL_FILE не используются.

Миграции запускает отдельный завершающийся service migrate, API ждут успешного завершения. Версии записываются в schema_migrations, advisory lock защищает от параллельного запуска операторами. Схема описана в infra/schema.md, перенесённом из lab2 и дополненном таблицей ключей. Миграция 002 добавляет отдельную таблицу и совместима со старой схемой; старый API lab2 не поддерживает новую гарантию идемпотентности, смешанный запуск lab2/lab3 за одним LB не допускается. Для переноса используются исходники и миграции, существующие volumes lab2 не изменяются.

Остановка без потери данных: docker compose down. Повторный запуск: docker compose up -d --wait. Намеренное удаление всех учебных данных именно этого проекта: docker compose down -v. Secrets сохраняются отдельно; не менять пароль файла без изменения пароля в существующей БД.

Полная проверка схемы:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python

Архитектура и решения

Клиент → HAProxy round-robin → два контейнера одного Compose-service API → общая PostgreSQL. Сессии, пользователи, чаты, сообщения и ключи идемпотентности находятся в БД. Sticky session нет. Заголовок X-Instance-Id содержит hostname контейнера, стабилен в течение процесса и сопоставляется реальному контейнеру через docker inspect; все ответы API также содержат X-Request-Id. Один пользователь работает через обе реплики с одним Bearer token. Пароли хешируются scrypt с индивидуальной солью; в sessions хранится только SHA-256 случайного 256-битного токена, срок не продлевается после restart.

Соединение с БД и транзакция создаются на запрос; ответ отправляется после COMMIT. POST сообщения проверяет сессию, членство, тело и ключ, берёт транзакционный advisory lock по (user_id, chat_id, key), проверяет прежний результат и атомарно сохраняет сообщение вместе с ключом. HTTP-метод и маршрут фиксированы обработчиком POST messages. Конкурентная реплика ждёт завершения транзакции, после чего возвращает тот же Message и 201; другой текст получает 409. Отсутствующий attachment_ids и [] эквивалентны; непустые вложения не входят в lab3. После 24 часов ключ можно использовать заново, старое сообщение сохраняется. Ошибка до COMMIT откатывает и сообщение, и ключ. После неопределённого ответа клиент повторяет тот же ключ и тело. HAProxy не повторяет POST автоматически (retries 0).

HAProxy проверяет /health/ready каждую секунду, исключает backend после 2 неуспехов, возвращает после 1 успеха. timeout check=1s, timeout connect=1s: консервативное ожидаемое обнаружение до 4 секунд при молчащем backend, фактический переход измеряется публичным failover. Docker DNS обновляется через resolver 127.0.0.11, hold valid/obsolete — 1s, поэтому пересозданные контейнеры обнаруживаются без рестарта LB. /health/live не обращается к БД; ready требует доступной БД, единственной критичной зависимости. Таймаут SQL 5s, подключения к БД 3s, LB server/client 10s; сокет API 5s. SIGTERM прекращает accept через shutdown в другом потоке; активные недемонические request threads завершаются до выхода, Compose даёт 15s.

История сортируется (created_at, id), cursor привязан к истории чата либо списку чатов пользователя. Это не snapshot: конкурентные вставки могут попасть в следующие страницы; при обратном скачке часов запись может оказаться до уже пройденного cursor. Новое чтение через любую реплику видит подтверждённую запись из общей БД.

Доказательства критериев

Критерий уровня 3 Команда / сценарий Результат Доказательство
Воспроизводимый стенд, ≥2 API, единый LB, общие данные и сессии docker compose up -d --build --wait, docker compose ps --all Две реальные API-реплики; только LB публикует порт evidence/failover.txt
Контракт и публичный smoke make check, make validate, make test BASE_URL=http://localhost:8083 PASS evidence/checks.txt
Одна сессия через разные реплики, конкурентный повтор без дублей python3 student-tests/idempotency.py --base-url http://localhost:8083 32 конкурентных запроса через ≥2 X-Instance-Id вернули один Message evidence/checks.txt
Проверки валидации и изоляции предыдущей лабы python3 student-tests/check.py --base-url http://localhost:8083 PASS: Unicode, границы паролей, чужой cursor, членство evidence/checks.txt
Истечение сессии из lab2 Одноразовый API с SESSION_TTL_SECONDS=2, python3 student-tests/expiry.py --base-url http://localhost:18083 Сразу 200, спустя 3s чтение и logout → 401; основной стенд остаётся на TTL=3600 evidence/expiry.txt
Пароли/токены, повтор миграций, rollback docker compose exec -T api python - < student-tests/db_check.py PASS: KDF/digest, FK, неизменные counts после повторных миграций evidence/checks.txt
Перезапуск API и всех используемых хранилищ make test-persistence BASE_URL=http://localhost:8083 ACTION_SCRIPT=scripts/restart.sh Данные и прежняя сессия сохранены; StartedAt API/БД изменились evidence/persistence.txt
Остановка выбранной реальной API-реплики и чтение/запись при отказе make test-failover BASE_URL=http://localhost:8083 ACTION_SCRIPT=scripts/stop-one.sh ≥2 реплик до отказа; запись восстановилась ≤10s; подтверждённые сообщения без потери и дублей evidence/failover.txt

Эксперименты и ограничения

Проверки функциональные на локальном синтетическом стенде, без претензии на оценку 4/5 или максимальный RPS. Публичный failover работает 15 секунд, один клиент отправляет уникальные сообщения примерно раз в 0.1s, повторяя неопределённый POST с прежним ключом; до отказа 40 чтений проверяют наличие двух реплик. Для каждого запуска сохраняются successful_writes, failed_attempts и first_recovery_seconds. До испытания стенд ожидает Compose healthchecks; отдельный нагрузочный прогрев не заявлен. Остановка api-1: 97 подтверждённых записей, 2 ошибки, восстановление 1.785s (повтор: 106, 1, 1.470s); api-2: 108 записей, 2 ошибки, восстановление 2.068s. После каждого сценария обе реплики восстановлены. Итоги и реальные состояния контейнеров приведены в evidence, сессии и пароли не печатаются. Полный restart проверяется отдельно с сохранённым volume и прежним токеном.

Отказ одного API-процесса выдерживается. LB, БД, диск и единственный Docker-host остаются SPOF; потеря их узла не исследована. Rolling update под нагрузкой, исследование масштабирования, p50/p95/p99 и уровни 4/5 не заявлены. CI приложения добавлен для GitHub Actions; Gitea этого форка не включает Actions, поэтому фактические доказательства — локальные проверки.

http.server и соединение на каждый запрос — учебное упрощение. Нет TLS, ограничения числа клиентских потоков или rate limiting; HTTP допустим только для локальных синтетических данных. Истёкшие сессии и неиспользуемые ключи не чистятся фоновым заданием; истёкший ключ удаляется при повторном использовании его scope, поэтому размер БД растёт. БД должна иметь достаточно места для WAL; первому запуску мешал заполненный диск OrbStack, после очистки старого build-cache стенд успешно инициализирован. Другие лабораторные и их volumes не изменялись.