Files
mtusi2026lab4/STUDENT_README.md
2026-11-12 19:56:00 +03:00

11 KiB
Raw Permalink Blame History

Лабораторная 4: S3-хранилище и вложения

Мессенджер на FastAPI с PostgreSQL, Redis и двумя API-репликами за HAProxy. Оригиналы PNG/JPEG хранятся в приватном MinIO, метаданные и связи с сообщениями — в PostgreSQL. Выполнены требования уровня 4 и трек 2 на 5: согласованность двух хранилищ, повторяемая сверка, безопасная очистка и эксперименты.

Автор: Каменский Андрей, БПИ2301.

Задание · Отчёт · Семантика API · OpenAPI · Алгоритм сверки · Проверка замечаний преподавателя

Запуск с нуля

Нужны Docker с Compose v2 и Python 3.13 для полного набора проверок. Публичный HTTP smoke использует только стандартную библиотеку Python 3.9+.

python3 scripts/setup-env.py
docker compose config --quiet
docker compose up -d --build --wait
python3 tests/smoke.py

setup-env.py создаёт .env с новыми случайными паролями и правами 0600, не выводит значения и не перезаписывает существующий файл. Для существующего стенда сохранить прежний .env и volumes. Логин стартового администратора — ADMIN_USERNAME, пароль — ADMIN_PASSWORD из локального .env.

Первый build собирает MinIO community из закреплённого commit, поэтому требует интернет и может занять несколько минут. Это не зависит от наличия готового официального образа MinIO. При запуске автоматически выполняются миграции до 008, создание приватного bucket, пользователей и S3-политик. Все сервисы находятся в этом Compose; заранее установленная БД или S3 не нужны.

API: http://localhost:8080, Swagger: http://localhost:8080/docs. Наружу опубликован только LB на loopback. Консоль MinIO выключена.

В этой локальной копии после переноса выбран APP_PORT=8084: Swagger находится на http://localhost:8084/docs. Верификатор читает порт из локального .env. Для отдельных Make-target можно передать BASE_URL=http://127.0.0.1:8084. Новый клон по умолчанию использует 8080.

docker compose down             # остановить, сохранить данные
# Осознанно удалить все учебные данные текущего проекта:
# docker compose down --volumes

Архитектура

flowchart LR
    C[Клиент] --> LB[HAProxy]
    LB --> A1[API 1]
    LB --> A2[API 2]
    A1 --> PG[(PostgreSQL)]
    A2 --> PG
    A1 --> R[(Redis: сессии)]
    A2 --> R
    A1 --> S3[(Приватный MinIO)]
    A2 --> S3
    W[Reconciler] --> PG
    W --> S3

PostgreSQL хранит пользователей, чаты, сообщения, вложения, идемпотентность и журнал загрузок. Redis хранит сессии с TTL/AOF и кэш профилей. MinIO хранит неизменённые оригиналы в volume minio_data. У API нет постоянного локального состояния. У сообщения до 10 уникальных вложений; одно вложение можно повторно использовать в том же чате. Связующая таблица сохраняет порядок и запрещает связывать разные чаты составными внешними ключами.

Загрузка и чтение

  1. Создать пользователя и сессию, создать чат с явным списком участников.
  2. POST /api/v1/chats/{chat_id}/attachments?filename=photo.png: Bearer-токен, Content-Type: image/png или image/jpeg, в теле сырые байты одного файла.
  3. После S3 PUT и COMMIT вернуть 201 Attachment, status=ready, variants=[].
  4. Создать сообщение с Idempotency-Key и телом {"text":"", "attachment_ids":["UUID"]}. Текст можно оставить пустым при наличии файла.
  5. GET /api/v1/attachments/{id} — метаданные; GET /api/v1/attachments/{id}/content — оригинал через API без redirect.

Доступ есть только у участников чата; посторонним — 404. Filename не используется как путь или S3 key. Размер — до 10 MiB, число пикселей — до 40 млн включительно. Формат определяется по содержимому и сравнивается с MIME; после ранней проверки размеров проверяются структура и декодирование. Оригинал не пересохраняется. Примеры для HTTP-клиента: examples/student-requests.http.

API использует отдельную S3-учётную запись без DeleteObject и административных прав. Reconciler может читать/удалять только в нашем префиксе, не может загружать объекты. Owner credentials передаются только MinIO и bootstrap.

Согласованность и отказы

Перед PUT отдельным COMMIT создаётся upload_intents.pending. Загрузчик удерживает транзакционный advisory lock на ключ до публикации Attachment и перевода намерения в committed. Reconciler пропускает занятые ключи; старые pending без Attachment закрывает, бесхозные объекты удаляет. Запас для свежих объектов/попыток — 300 секунд, настраивается через RECONCILE_GRACE_SECONDS.

Сверка проходит каждые 300 секунд, ограничена нашим bucket и originals/, читает ListObjectsV2 постранично. Потеря оригинала отмечается без удаления сообщений; его восстановление подтверждается размером и SHA-256. Ошибка удаления не закрывает возможность повторной очистки. Полный алгоритм и ограничения — LAB4_RECONCILIATION.md.

make -f student.mk reconcile          # dry-run: только показать действия
make -f student.mk reconcile-apply    # повторно проверить и применить

Readiness проверяет PostgreSQL, Redis и bucket с HTTP-бюджетом 2 секунды. Обычные бизнес-запросы ограничены 5 секундами до заголовков ответа, включая ожидание отмены SQL/rollback. Зависшие обработчики отменяются, но занимают свой лимит до завершения. После возобновления PostgreSQL API восстанавливается без перезапуска. Binary upload имеет отдельный бюджет приёма и завершающий deadline.

Проверки

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-student.txt
make -f student.mk check validate lint PYTHON=.venv/bin/python
make -f student.mk verify-lab4 PYTHON=.venv/bin/python

Полная проверка выполняет сценарии последовательно: публичный smoke, вложения, конкурентную идемпотентность, замечания преподавателя, сверку со сбоями, память при 10 загрузках, отказ загрузившей реплики, сохранность и сборку с пустыми volumes. Она создаёт синтетические данные и временно останавливает/замораживает сервисы учебного стенда; восстановление включено в сценарии. Отдельный clean-start использует UUID-проект, новый порт и новые volumes; текущие данные не удаляются. Итог: evidence/lab4-final-summary.json, детальный вывод — evidence/lab4-final-*.txt.

make -f student.mk test-attachments PYTHON=.venv/bin/python
make -f student.mk test-lab4-review PYTHON=.venv/bin/python
make -f student.mk test-reconciliation
make -f student.mk test-upload-memory PYTHON=.venv/bin/python
make -f student.mk test-attachment-failover PYTHON=.venv/bin/python
make -f student.mk test-persistence-proof ACTION_SCRIPT=scripts/restart.sh PYTHON=.venv/bin/python
make -f student.mk test-clean-lab4 PYTHON=.venv/bin/python

Параметры и локальные credentials описаны в student.env.example. Результаты, методика и ограничения находятся в REPORT.md.

Исходные материалы преподавателя

Все 34 файла skeleton сохранены побайтно, включая README.md, REPORT.md, Makefile, .env.example, requirements-dev.txt, lab.json, тесты, контракт и исходный workflow. Наши инструкции находятся в STUDENT_README.md, отчёт — в STUDENT_REPORT.md, описание PR — в PULL_REQUEST.md. Наши команды — в student.mk, шаблон настроек — student.env.example, полный набор зависимостей проверок — в requirements-student.txt. Проверка неизменности: python3 scripts/check-course-files.py.