Files
mtusi2026lab4/REPORT.md
T
nothingredmouth 75cbe925d3 Заполнить отчёт и README лабораторной работы
REPORT.md: запуск, архитектура, логика загрузки, ограничения уровня 3,
таблица доказательств. README: ссылка на отчёт вместо отсутствующего
START_HERE.md.
2026-11-17 03:37:45 +00:00

11 KiB
Raw Blame History

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

  • Автор: Сиренко Илья.
  • Группа: БПИ2304.
  • Целевая оценка: 3. Уровни 4/5 не заявлены.
  • Основа: лабораторная №3 (Flask + PostgreSQL + HAProxy, две API-реплики, сессии и идемпотентные сообщения).
  • Commit/PR: указать после публикации репозитория.
  • Стек: Python 3.9+, Flask 3.1.0, Waitress 3.0.2, PostgreSQL 16.6, psycopg 3.2.6, HAProxy 3.0.8, boto3 1.36.26, Pillow 11.1.0, S3-совместимое объектное хранилище.
  • Использованные источники и помощь ИИ: требования из Markdown-файлов лабораторной №4, contracts/openapi.json, публичные тесты и собственный проект лабораторной №3. ИИ использовался для разбора требований, проектирования структуры приложения, проверки соответствия контракту и подготовки отчёта.

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

Нужны Docker Engine с Compose v2, Python 3.9+ для публичных тестов и доступ к registry для загрузки контейнерных образов. Все команды выполняются в корне mtusi2026lab4. Опубликован только HAProxy на 127.0.0.1:8080.

python3 scripts/init_local.py
# Секреты создаются один раз в secrets/ и не входят в ZIP/Git.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
# дождаться: curl -fsS http://localhost:8080/health/ready
make check
make test

Swagger UI в четвёртой лабораторной не заявлен; машинно-читаемый контракт доступен в contracts/openapi.json. Проверка через curl: curl http://localhost:8080/health/live. Выключение: docker compose down (данные остаются); намеренное уничтожение всех учебных данных: docker compose down -v (не делайте при проверке persistence). После изменения миграций запустить docker compose up -d --build, сервис migrate применит версии однократно. Если ранее был развёрнут lab3 со своими томами, сохраняйте его PostgreSQL volume и секреты при переносе; новая миграция 003_attachments.sql добавляется к существующей схеме.

Архитектура

REST-клиент -> HAProxy :8080 -> api1 / api2 (Flask + waitress)
                                  |          |
                                  +-- PostgreSQL :5432 (таблицы/сессии/идемпотентность)
                                  +-- MinIO S3 :9000 (оригиналы PNG/JPEG)
  • db: postgres:16.6-bookworm, БД messenger, postgres_data, health pg_isready. migrate однократно создаёт/обновляет schema_migrations.
  • s3: minio/minio:RELEASE.2025-02-07T23-21-09Z, s3_data, без опубликованных портов, локальный health endpoint; s3-bootstrap идемпотентно создаёт приватный bucket messenger-attachments.
  • api1 и api2: сборка из Dockerfile на python:3.11.11-slim-bookworm, readiness проверяет и БД, и S3; не имеют volume для бинарных вложений.
  • lb: haproxy:3.0.8-bookworm, опубликован только 127.0.0.1:8080.
  • Секреты: secrets/postgres_password, secrets/database_url, secrets/s3_password создаются локально scripts/init_local.py; DATABASE_URL_FILE, S3_SECRET_FILE указывают на Docker secrets. APP_ENV, TTL и сетевые параметры заданы в Compose. API использует административные MinIO credentials ради простоты уровня 3; разграничение S3 permissions — задача уровня 4.

Логика загрузки

  1. Bearer-сессия и принадлежность чату проверяются перед чтением тела. filename валидируется, не используется в пути. Заголовок MIME и содержимое должны соответствовать PNG либо JPEG.
  2. Лимит чтения 10 MiB + 1 байт и пикселей 40 млн проверяется до полной распаковки; Pillow проверяет структуру и полное декодирование. Объекту назначается независимый случайный ключ originals/<random>/<random>.
  3. Бинарный оригинал записывается в приватный S3. После успешного PUT данные метаданных коммитятся в PostgreSQL, только затем отдаётся 201 ready (variants=[], error_code=null). SHA-256 и размер считаются по исходным байтам.
  4. Для создания сообщения допускается attachment_ids 0–10 уникальных UUID, включая пустой текст с непустым массивом. Все IDs должны принадлежать чату. message_attachments хранит порядок; идемпотентность учитывает текст и отсортированный по позиции список IDs (порядок важен).
  5. GET /attachments/{id} и /content разрешены только участникам чата. API скачивает байты напрямую из S3, без редиректа и без открытия bucket наружу. Чужому пользователю возвращается одинаковый 404 для несуществующего или недоступного объекта.

SQL-транзакция не охватывает S3: если PUT прошёл, а запись БД не состоялась, выполняется best-effort удаление ключа. При разрыве процесса либо при отказе удаления возможен orphan-объект; полноценную фоновую сверку на уровне 3 не заявляем. Приватность bucket обеспечивается отсутствием публичной policy и закрытым сетевым портом; авторизация реализована отдельно в API.

Доказательства критериев оценки «3»

Результаты ниже отделяют фактически выполненные локальные проверки от контейнерных и сетевых сценариев, требующих работающего Docker-стенда. Для подтверждения на машине студента вывод команд можно сохранить в evidence/:

mkdir -p evidence
make check 2>&1 | tee evidence/contract-local.txt
python3 -m unittest discover -s student-tests -p test_images.py -v 2>&1 | tee evidence/images-local.txt
docker compose --env-file .env ps -a 2>&1 | tee evidence/docker-services.txt
make test 2>&1 | tee evidence/public-smoke.txt
Проверка Команда / метод Ожидаемый критерий
Контракт и исходники make check Корректная структура lab4/OpenAPI и синтаксис Python
Локальная валидация файлов python -m unittest discover -s student-tests -p test_images.py -v Реальный PNG, неверный MIME, повреждение, лимит bytes/pixels
Сквозной API make test Авторизация и lab3-функции, 201 ready, SHA-256, бинарный download, чужой пользователь 404
Отказ API-реплики make test-failover ACTION_SCRIPT=scripts/stop-one.sh TARGET_INSTANCE_ID останавливается, другой API обслуживает запросы; тест включает S3 file check для lab4
Долговечность make test-persistence ACTION_SCRIPT=scripts/restart.sh Перезапуск двух API, PostgreSQL и MinIO с прежними volumes, затем чтение с прежним токеном
Приватность S3 docker compose exec -T api1 python -c 'from messenger.config import Settings; from messenger.storage import ObjectStore; s=ObjectStore(Settings.from_env()); print(s.s3.get_bucket_policy(Bucket=s.bucket))' Без заданной публичной policy запрос должен закончиться ошибкой NoSuchBucketPolicy; по умолчанию бакет приватен

Фактически выполнено в среде подготовки: python scripts/check_contract.py — PASS; python -m unittest discover -s student-tests -p test_images.py -v — 4 OK; python -m compileall -q messenger — без ошибок.

Эксперименты и отказы

Сценарий Ожидаемое поведение Наблюдение / статус
Неверный MIME или повреждённое изображение Отказ без создания корректного вложения Проверено локальными unit-тестами, 4 теста OK
Файл, превышающий лимиты Отказ в загрузке Проверено локальными unit-тестами
Чтение чужого вложения 404 без раскрытия данных Реализовано в API, end-to-end проверка на Docker-хосте требуется
Перезапуск API и хранилищ Сохранение метаданных в PostgreSQL и оригиналов в S3 volumes Подготовлен тест make test-persistence, Docker-подтверждение не получено
Остановка одной API-реплики Вторая реплика продолжает обслуживать HTTP-запросы через HAProxy Подготовлен тест make test-failover, Docker-подтверждение не получено
Отказ между PUT в S3 и COMMIT в БД Best-effort удаление S3-объекта Реализована компенсация, гарантированной очистки orphan-объектов нет