# Отчёт — лабораторная 3 Целевая оценка: **3**. Исследовательский трек не заявлен. Автор: Бахрамов Бахрам, БПИ2303. Ветка: `solution/bpi2303-bakhramov`. Репозиторий: https://gitea.privcloud.tech/bahram/mtusi2026lab3 Запрос на слияние: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3/pulls/136 Устройство решения и команды защиты приведены ниже. ## Запуск Требуются Docker с Compose v2, Python 3.9+ и make на компьютере проверяющего. Все команды выполняются из папки этой лабораторной. ```sh cp .env.example .env docker compose config --quiet docker compose up -d --build # Дождаться 200 по адресу http://localhost:8080/health/ready curl -i http://localhost:8080/health/ready make check make test BASE_URL=http://localhost:8080 python3 tests/acceptance_extra.py --base-url http://localhost:8080 make test-persistence BASE_URL=http://localhost:8080 ACTION_SCRIPT=scripts/restart.sh make test-failover BASE_URL=http://localhost:8080 ACTION_SCRIPT=scripts/stop-one.sh # После failover одна API остаётся остановленной. Восстановить её: docker compose up -d api1 api2 ``` Порты двух лабораторных различаются, поэтому их можно запускать одновременно. Для обычной остановки: `docker compose down` (volumes сохраняются). Намеренный сброс только учебных данных: `docker compose down -v` (не применять при проверке persistence). Значения .env.example — открытые демонстрационные credentials для локального стенда с синтетическими данными. API и хранилища не публикуют порты. Только HAProxy принимает соединения на 127.0.0.1:8080. ## Архитектура и реализация Клиент → HAProxy → api1 / api2 → PostgreSQL. FastAPI 0.115.12, Uvicorn 0.34.2, Python 3.12.10; HAProxy 3.0.10; PostgreSQL 16.8. Полные версии прямых Python-зависимостей закреплены в requirements.txt, образы — в compose.yaml. Обе API работают с одной PostgreSQL; локальное состояние API не используется для сессий и сообщений. Пароли — Argon2id, случайный Bearer-токен имеет 256 бит энтропии; в БД хранится SHA-256 токена. Сессии имеют абсолютный expires_at, не продлеваются рестартом и отзываются DELETE. Источник истины — PostgreSQL, подтверждённая запись читается из неё через любую реплику. Одноразовый сервис migrate выполняет идемпотентный SQL до запуска API. Он не запускается каждой репликой. Схема таблиц находится в migrations/001_init.sql. Пользовательские поля хранятся в JSONB, идентификаторы и связи — также в отдельных колонках с внешними ключами. Миграции здесь только создают начальную схему; обновление несовместимой схемы без остановки не заявляется. Для сообщения PostgreSQL advisory transaction lock берётся по user+chat+key. После блокировки повторно проверяется существующий результат за последние 24 часа. Одинаковое нормализованное тело возвращает прежний Message и 201, отличающееся — 409. Вставка сообщения и данных для повтора выполняется одной транзакцией. При разрыве до ответа клиент повторяет тот же ключ: committed запись будет возвращена, rollback позволит новую запись. Порядок JSON-ключей и отсутствие attachment_ids вместо [] не меняют сравнение. HAProxy использует round-robin без sticky sessions. Каждый API сообщает hostname контейнера в X-Instance-Id. GET /health/live проверяет процесс; /health/ready проверяет PostgreSQL. Проверка backend идёт раз в 1 секунду; после двух неудач сервер исключается. Connect timeout — 1 секунда, client/server timeout — 30 секунд. Это настройки обнаружения, не гарантия для любых сетевых отказов. Docker DNS повторно разрешается HAProxy. При SIGTERM Uvicorn завершает текущие запросы до 5 секунд; Compose даёт 10 секунд. Лимит каждой API — 512 MiB и 1 CPU. Пагинация — keyset по (created_at,id). Cursor содержит scope и последнюю пару; от другого чата не принимается. Это не snapshot: вставка с более ранним временем после уже прочитанного cursor может не попасть в продолжение. Время UTC назначает API; при обычном локальном стенде контейнеры используют общие часы хоста. ## Проверки и доказательства Проверено 12.11.2026 на Docker Desktop (Linux arm64). Все записанные проверки пройдены. В failover наблюдались 2 разные API; за 15 секунд подтверждено 103 новых сообщений, переходных неуспешных попыток — 5; первая успешная запись после воздействия — 2.114 с. Подтверждённые данные и прежняя сессия сохранились. Это результат одного локального запуска, не SLA. Фактические команды и результаты находятся в evidence/verification.txt. Повторить полный набор: `python3 scripts/verify.py > evidence/verification.txt 2>&1`. Публичные contracts/ и tests/smoke.py, tests/resilience.py не изменены. | Требование на 3 | Проверка | Доказательство | | --- | --- | --- | | Один LB и две API с общей БД/сессиями | docker compose ps; failover наблюдает разные X-Instance-Id одной сессии | evidence/verification.txt | | Обязательный API и ошибки | make test | evidence/verification.txt | | Конкурентный повтор без дублей | 16 запросов с одним ключом через LB | tests/acceptance_extra.py; evidence/verification.txt | | Остановка выбранной реальной API, восстановление чтения/записи ≤10 секунд | make test-failover, hook сопоставляет X-Instance-Id с hostname и останавливает контейнер | scripts/stop-one.sh; evidence/verification.txt | | Сохранность пользователей, чатов, сообщений и действующих сессий после restart всех хранилищ | make test-persistence; сравнение StartedAt до/после | scripts/restart.sh; evidence/verification.txt | ## Ограничения Устойчивость проверяется только при отказе одной API-реплики. LB, PostgreSQL и хост — единичные точки отказа. Бэкапы, репликация БД, rolling update и нагрузочное исследование не реализованы. HTTP предназначен для локальных синтетических данных. Уровни 4 и 5 не заявлены. ## Источники - Исходное задание и неизменённый контракт: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3 - PostgreSQL advisory locks: https://www.postgresql.org/docs/16/explicit-locking.html#ADVISORY-LOCKS - HAProxy configuration: https://docs.haproxy.org/3.0/configuration.html - Docker Compose: https://docs.docker.com/compose/ - Argon2: https://argon2-cffi.readthedocs.io/