Files
mtusi2026lab3/REPORT.md
T

100 lines
8.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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/