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

160 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная 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`.