REPORT.md: запуск, архитектура, логика загрузки, ограничения уровня 3, таблица доказательств. README: ссылка на отчёт вместо отсутствующего START_HERE.md.
11 KiB
Отчёт — лабораторная работа №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, healthpg_isready.migrateоднократно создаёт/обновляет schema_migrations.s3:minio/minio:RELEASE.2025-02-07T23-21-09Z,s3_data, без опубликованных портов, локальный health endpoint;s3-bootstrapидемпотентно создаёт приватный bucketmessenger-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.
Логика загрузки
- Bearer-сессия и принадлежность чату проверяются перед чтением тела.
filenameвалидируется, не используется в пути. Заголовок MIME и содержимое должны соответствовать PNG либо JPEG. - Лимит чтения 10 MiB + 1 байт и пикселей 40 млн проверяется до полной распаковки; Pillow проверяет структуру и полное декодирование. Объекту назначается независимый случайный ключ
originals/<random>/<random>. - Бинарный оригинал записывается в приватный S3. После успешного PUT данные метаданных коммитятся в PostgreSQL, только затем отдаётся
201 ready(variants=[],error_code=null). SHA-256 и размер считаются по исходным байтам. - Для создания сообщения допускается
attachment_ids0–10 уникальных UUID, включая пустой текст с непустым массивом. Все IDs должны принадлежать чату.message_attachmentsхранит порядок; идемпотентность учитывает текст и отсортированный по позиции список IDs (порядок важен). 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-объектов нет |