# Лабораторная 4: S3-хранилище и вложения Мессенджер на FastAPI с PostgreSQL, Redis и двумя API-репликами за HAProxy. Оригиналы PNG/JPEG хранятся в приватном MinIO, метаданные и связи с сообщениями — в PostgreSQL. Выполнены требования уровня 4 и трек 2 на 5: согласованность двух хранилищ, повторяемая сверка, безопасная очистка и эксперименты. Автор: Каменский Андрей, БПИ2301. [Задание](README.md) · [Отчёт](STUDENT_REPORT.md) · [Семантика API](contracts/README.md) · [OpenAPI](contracts/openapi.json) · [Алгоритм сверки](LAB4_RECONCILIATION.md) · [Проверка замечаний преподавателя](LAB4_AUDIT.md) ## Запуск с нуля Нужны Docker с Compose v2 и Python 3.13 для полного набора проверок. Публичный HTTP smoke использует только стандартную библиотеку Python 3.9+. ```sh 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](http://localhost:8080), Swagger: [http://localhost:8080/docs](http://localhost:8080/docs). Наружу опубликован только LB на loopback. Консоль MinIO выключена. В этой локальной копии после переноса выбран `APP_PORT=8084`: Swagger находится на [http://localhost:8084/docs](http://localhost:8084/docs). Верификатор читает порт из локального `.env`. Для отдельных Make-target можно передать `BASE_URL=http://127.0.0.1:8084`. Новый клон по умолчанию использует 8080. ```sh docker compose down # остановить, сохранить данные # Осознанно удалить все учебные данные текущего проекта: # docker compose down --volumes ``` ## Архитектура ```mermaid 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](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](LAB4_RECONCILIATION.md). ```sh 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. ## Проверки ```sh 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`. ```sh 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](student.env.example). Результаты, методика и ограничения находятся в [REPORT.md](STUDENT_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`.