14 KiB
Отчёт — лабораторная 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 не изменялись.