Files
mtusi2026lab4/REPORT.md
T

135 lines
13 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.
# Отчёт — лабораторная 4
Целевая оценка: **3**. Исследовательский трек не заявлен.
Автор: Бахрамов Бахрам, БПИ2303.
Ветка: `solution/bpi2303-bakhramov`.
Репозиторий: https://gitea.privcloud.tech/bahram/mtusi2026lab4
Устройство решения и команды защиты приведены ниже.
## Запуск
Требуются Docker с Compose v2, Python 3.9+ и make на компьютере проверяющего.
Все команды выполняются из папки этой лабораторной.
```sh
cp .env.example .env
docker compose config --quiet
docker compose up -d --build
# Дождаться 200 по адресу http://localhost:8084/health/ready
curl -i http://localhost:8084/health/ready
make check
make test BASE_URL=http://localhost:8084
python3 tests/acceptance_extra.py --base-url http://localhost:8084
make test-persistence BASE_URL=http://localhost:8084 ACTION_SCRIPT=scripts/restart.sh
make test-failover BASE_URL=http://localhost:8084 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:8084.
## Архитектура и реализация
Клиент → 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, а также доступность S3 bucket.
Проверка 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 секунд подтверждено 107 новых сообщений,
переходных неуспешных попыток — 6; первая успешная запись после воздействия — 0.97 с.
Подтверждённые данные и прежняя сессия сохранились. Это результат одного локального запуска, не 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 |
## Вложения и S3
SeaweedFS 3.85 запускается одним S3-сервером в общем Compose. Его master, volume и filer
сохраняют данные в s3_data, рабочий каталог — /data. PostgreSQL хранит только метаданные, не байты.
Приватный bucket attachments создаётся отдельным bucket-init с повторными попытками до старта API.
Анонимной identity в infra/s3.json нет; S3 доступен только внутри Compose-сети, публичной policy нет.
Для уровня 3 API использует ту же учебную identity, что bootstrap; отдельные минимальные права не заявляются.
Если менять S3 credentials, нужно согласованно изменить .env и infra/s3.json.
Upload принимает сырые PNG/JPEG. Байты читаются порциями с пределом 10 MiB до декодирования;
Pillow проверяет реальный формат, соответствие MIME, целостность и предел 40 млн пикселей.
Имя не используется в S3: object key — UUID, назначенный сервером. Slash, backslash и управляющие символы отклоняются.
201 ready возвращается после S3 PUT и PostgreSQL COMMIT. Download проверяет участника чата и отдаёт исходные байты через API.
attachment_ids валидируются на принадлежность тому же чату; допустимо сообщение без текста с вложением.
| Требование на 3 | Проверка | Доказательство |
| --- | --- | --- |
| Побайтный оригинал, SHA-256, attachment_ids, запрет постороннему | make test | evidence/verification.txt |
| Upload → остановка загрузившей API → download через вторую, отдельно для api1 и api2 | tests/attachment_failover.py | evidence/attachment_failover.txt |
| Сохранность метаданных и оригинала после рестарта PostgreSQL и S3 | make test-persistence | evidence/verification.txt |
| Опасное имя, подмена MIME, повреждение, >10 MiB, >40 млн пикселей; настоящий JPEG; вложение другого чата | tests/acceptance_extra.py | evidence/extra_images.txt |
| Отказ S3 | tests/storage_failure.py | evidence/verification.txt |
| Анонимный S3 GET не возвращает объект | запрос из внутренней сети без подписи | evidence/verification.txt |
Для обеих API проверено: после остановки принявшей upload реплики другая отдала тот же SHA-256; время — 0,826 с (api1) и 1,498 с (api2). Подробности в evidence/attachment_failover.txt.
Команда дополнительного сценария: `python3 tests/storage_failure.py --base-url http://localhost:8084`.
Согласованность: сначала S3 PUT, затем INSERT/COMMIT метаданных. При сбое БД между ними возможен orphan object.
Автоматической сверки и очистки нет — это ограничение уровня 3, а не выполненный критерий уровня 4.
При отказе S3 ready и upload возвращают 503; HAProxy исключает неготовые API.
Повтор upload не идемпотентен и может создать ещё одно вложение.
Один файл хранится в памяти до 10 MiB, декодированное изображение — до 40 млн пикселей;
потоковая передача и эксперимент на 10 параллельных загрузках не заявлены.
## Ограничения
Устойчивость проверяется только при отказе одной API-реплики. LB, PostgreSQL и хост — единичные точки отказа.
Бэкапы, репликация БД, rolling update и нагрузочное исследование не реализованы.
HTTP предназначен для локальных синтетических данных. Уровни 4 и 5 не заявлены.
## Источники
- Исходное задание и неизменённый контракт: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4
- 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/
- SeaweedFS S3 identity configuration: https://github.com/seaweedfs/seaweedfs/blob/3.85/docker/compose/s3.json