forked from mtusi2026/mtusi2026lab4
160 lines
11 KiB
Markdown
160 lines
11 KiB
Markdown
# Лабораторная 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`.
|