Files
mtusi2026lab4/README.md
T

99 lines
5.7 KiB
Markdown
Raw 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 — В. Вотчицева, БВТ2302
**Тема:** приватное S3-хранилище изображений и вложения в сообщения.
Цель: оценка **4**. Проект основан на личной ЛР3 (FastAPI + SQLAlchemy async + HAProxy), не на чужой реализации.
## Что перенесено из ЛР3
Два FastAPI-контейнера `api1`, `api2`, HAProxy 3.0.5 (`roundrobin`), PostgreSQL 16.4,
Redis 7.4.1, bcrypt_sha256 и `Idempotency-Key` с `SELECT FOR UPDATE`.
Пользователи/чаты/старые сообщения остаются в базе при миграции на ЛР4.
## Что добавлено в ЛР4
- S3-совместимый **SeaweedFS 4.03** с volume, приватным bucket `messenger-attachments`.
- Раздельные S3 учётные записи: admin и API (доступ только к своему bucket).
- PostgreSQL: `attachments` (метаданные) + `message_attachments` (связь), дополнение idempotency key.
- `POST /api/v1/chats/{chat_id}/attachments?filename=photo.png` — **сырые байты** PNG/JPEG (НЕ multipart),
лимит 10 MiB и 40 MP, защита от опасных filename, проверка реального формата и декодирования.
- `GET /api/v1/attachments/{id}` — метаданные, `GET /content` — потоковое скачивание оригинала после проверки членства.
- Сообщения могут иметь до десяти `attachment_ids`; теперь разрешён пустой текст при непустом списке вложений.
- Компенсирующее удаление S3 при неудаче PostgreSQL + безопасный `reconcile` после аварии с grace period >=1 час.
## Запуск (Windows PowerShell)
1. Откройте Docker Desktop и распакованную папку проекта в VS Code.
2. Создайте локальный файл конфигурации:
```powershell
Copy-Item .env.example .env
notepad .env
```
Замените пароли `POSTGRES_PASSWORD`, `S3_ROOT_PASSWORD`, `S3_SECRET_ACCESS_KEY` на свои.
Секреты нельзя публиковать в Git или отчёте. Если уже существует volume PostgreSQL от ЛР3,
оставьте прежний пароль PostgreSQL, иначе аутентификация перестанет работать.
3. Запустите:
```powershell
docker compose config --quiet
docker compose up -d --build --wait --wait-timeout 150
docker compose ps -a
Invoke-RestMethod http://localhost:8080/health/ready
```
Swagger: `http://localhost:8080/docs`.
**Важный нюанс:** `POST /attachments` принимает сырые bytes. Swagger отправляет их через body типа `image/png`;
не используйте `multipart/form-data` и `UploadFile` с полем `file`.
## Тестирование
```powershell
python tests/smoke.py
python student-tests/run.py
python student-tests/test_attachments.py
python scripts/check_grade4.py
python scripts/experiment_uploads.py
```
Проверка private bucket (после любого успешного upload):
```powershell
docker compose exec -T api1 python -m src.private_check
```
Проверка cleanup (по умолчанию dry-run):
```powershell
docker compose exec -T api1 python -m src.reconcile
docker compose exec -T api1 python -m src.reconcile --apply
```
**ОСТОРОЖНО:** `--apply` удаляет только старые незарегистрированные S3 объекты, но без необходимости его не запускайте.
Для тестов отказа и сохранности см. `tests/README.md`; используйте `scripts/stop-one.sh`/`scripts/restart.sh`
в среде, где `.sh` запускаются. В Windows можно продемонстрировать остановку `api1` через
`docker compose stop api1`, доступность файла через API на `api2`, и восстановить `docker compose up -d --wait api1`.
Для полного теста сохранности: `docker compose down` (БЕЗ `-v`) и повторное `docker compose up -d --wait`.
**Не запускайте `docker compose down -v`** при проверке сохранности — удалятся данные.
## Файлы для защиты
- `src/main.py` — API, авторизация, проверки доступа и сообщения.
- `src/db.py`, `src/migrate.py` — модели SQLAlchemy, миграции без удаления данных.
- `src/images.py` — проверка настоящего формата и декодирования PNG/JPEG.
- `src/storage.py` — boto3 S3 client; `src/reconcile.py` — очистка старых orphan.
- `infra/haproxy.cfg` — `roundrobin`, активные проверки.
- `infra/generate-s3-config.py` — разграничение S3 credentials, приватный bucket.
- `scripts/experiment_uploads.py` — 10 одновременных upload и замер памяти контейнеров.
Официальные спецификация и тесты курса: `contracts/`, `tests/`.
## Ограничения
Это учебный стенд. Модель S3 с одним SeaweedFS — общая точка отказа. Нет HTTPS для внешней сети.
Результаты контейнерных испытаний и замеры RAM нужно заполнить **после реального запуска**; статический анализ их не заменяет.