Files
mtusi2026lab4/REPORT.md
T
2026-11-06 16:21:00 +03:00

101 lines
10 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
- Автор, группа: TODO
- Целевая оценка: **4** (трек 5 не заявляется)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy 2, Alembic, boto3, Pillow, SeaweedFS (S3-совместимое хранилище), argon2-cffi. ИИ-ассистент использовался для генерации кода и текста отчёта; все команды и результаты воспроизводились локально.
## Запуск из чистого clone
Prerequisites: Docker Engine 24+, Docker Compose v2, Python 3.12 (для тестов), Git Bash/WSL на Windows (для `.sh`-хуков).
```sh
git clone <repo> && cd <repo>
cp .env.example .env
# Секреты для локального стенда (не коммитить):
mkdir -p secrets
printf 'postgresql+psycopg://messenger:messenger@postgres:5432/messenger' > secrets/database_url
printf 'redis://redis:6379/0' > secrets/cache_url
printf 'seaweedfs' > secrets/s3_access_key_id
printf 'seaweedfs-local-only' > secrets/s3_secret_access_key
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождаться /health/ready:
until curl -fsS http://localhost:8080/health/ready; do sleep 1; done
make test
python3 tests/test_attachments.py --base-url http://localhost:8080
```
Остановка: `docker compose --env-file .env down` (volumes сохраняются).
Намеренное удаление учебных данных: `docker compose --env-file .env down -v` (удаляет `pgdata` и `s3data`).
## Архитектура и решения
```
Клиент → nginx (LB, :8080) → api-1 / api-2 (FastAPI)
├── PostgreSQL (метаданные: users, chats, messages, attachments, message_attachments, idempotency_keys)
├── Redis (кэш сессий, опционально)
└── SeaweedFS (приватный bucket messenger-attachments, байты)
```
- **Источник истины**: PostgreSQL для метаданных, SeaweedFS для байтов. API-реплики stateless — любая реплика читает файл из S3.
- **Транзакционная граница**: `POST /attachments` сначала кладёт объект в S3, затем пишет метаданные в БД. При ошибке COMMIT — компенсация `delete_object` (best-effort). Обратный порядок (сначала БД, потом S3) дал бы «висячие» метаданные без байтов, что хуже для чтения.
- **Идемпотентность**: `Idempotency-Key` для сообщений (lab3) сохранён; `attachment_ids` входит в хэш тела, поэтому повтор с другим набором вложений даёт 409.
- **Лимиты**: 10 MiB на файл, 40 млн пикселей, MIME по magic bytes, `filename` не используется как путь/ключ S3.
- **Приватность bucket**: SeaweedFS S3-шлюз по умолчанию не выдаёт публичный доступ; API использует отдельные credentials (в учебном стенде — учётные данные S3-шлюза, в production — отдельный IAM-пользователь с `s3:GetObject/PutObject/DeleteObject` на bucket).
- **Что перенесено из lab3**: аутентификация (Basic → Bearer), сессии, чаты, сообщения, keyset-пагинация, идемпотентность, health, X-Request-Id/X-Instance-Id.
- **Что изменено**: добавлены `attachments`, `message_attachments`, поле `attachment_ids` в `Message`, роутер `attachments`, S3-клиент, bootstrap bucket, сервис `s3` в compose.
Соответствие `.env.example`: `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`, `UPLOAD_CHUNK_SIZE` — читаются в `app/config.py`. `S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY` — только для локального стенда SeaweedFS.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | PASS: lab4 public API scenario | `evidence/smoke.txt` |
| S3 в общем стенде, метаданные в PG, байты в приватном bucket | `docker compose ps`; `docker compose exec s3 wget -qO- http://127.0.0.1:8333/` | сервис `s3` healthy; объекты в bucket | `evidence/compose-ps.txt` |
| POST вложения → 201 ready, оригинал скачивается побайтно | `python3 tests/test_attachments.py::AttachmentTests::test_upload_and_download_roundtrip` | 201, sha256 совпадает | `evidence/attachments-roundtrip.txt` |
| Message с attachment_ids читается участниками | `test_message_with_attachment` | 201, `attachment_ids` в ответе | `evidence/attachments-message.txt` |
| Посторонний получает 404 | `test_outsider_cannot_read` | 404 для metadata и content | `evidence/attachments-outsider.txt` |
| PNG/JPEG ≤10 MiB, ≤40 млн пикселей, MIME по содержимому | `test_oversized_rejected`, `test_mime_spoof_rejected`, `test_corrupted_image_rejected` | 413 / 415 | `evidence/attachments-limits.txt` |
| Опасные filename отклоняются | `test_dangerous_filename_rejected` | 400 | `evidence/attachments-filename.txt` |
| Upload → остановка реплики → download через другую | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | PASS: failover preserved confirmed data | `evidence/failover.txt` |
| Restart с сохранением volumes | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS: persistence preserved | `evidence/persistence.txt` |
| Уровень 4: негативные тесты | `python3 tests/test_attachments.py` | все PASS | `evidence/attachments-all.txt` |
| Уровень 4: компенсация при сбое S3/БД | код `app/routers/attachments.py` (try/except + `delete_object`) | orphan не остаётся | `evidence/compensation.md` |
| Уровень 4: ≥10 одновременных загрузок, пик RAM | `test_concurrent_uploads_memory` + `docker stats` | 10/10 успешны, RSS API < 200 MiB | `evidence/memory.txt` |
| Уровень 4: идемпотентный bootstrap bucket | `docker compose up s3-init` дважды | второй запуск: "bucket already exists" | `evidence/bootstrap.txt` |
| Уровень 4: приватный bucket вне API | `curl http://localhost:8333/messenger-attachments/<key>` без подписи | 403 AccessDenied | `evidence/private-bucket.txt` |
## Эксперименты и отказы
**Эксперимент 1: одновременные загрузки и память.**
- Гипотеза: потоковая валидация с жёстким лимитом 10 MiB не даёт неограниченного роста RAM.
- Профиль: 10 параллельных POST `/attachments` с fixture 111817 байт, 1 API-реплика, `docker stats` каждые 0.5 с.
- Результат: 10/10 успешны, пик RSS API ≈ 120 MiB (базовый ≈ 80 MiB), пик не растёт линейно с числом загрузок.
- Ограничение: файл мал; для больших файлов лимит 10 MiB гарантирует верхнюю границу памяти на запрос.
**Эксперимент 2: отказ S3.**
- Воздействие: `docker compose stop s3`.
- Ожидание: `POST /attachments` → 503 `unavailable`; `GET /attachments/{id}/content` → 503; `/health/ready` остаётся 200 (S3 не критичен для синхронного пути чтения метаданных).
- Наблюдение: 503 в обоих случаях, метаданные не создаются, orphan в S3 не появляется.
**Эксперимент 3: failover API.**
- `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` — PASS, подтверждённые сообщения и вложения сохранены, дублей нет.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `stop s3` | 503 на upload/download | 503, метаданные не создаются | n/a, потерь нет |
| `stop api-1` | запись через api-2 | PASS failover | < 10 с, потерь нет |
| `restart.sh` (postgres + s3 + api) | данные и сессии сохранены | PASS persistence | ~15 с, потерь нет |
| `stop postgres` | 503 на `/health/ready` | 503 `unavailable` | n/a |
## Ограничения и следующие шаги
- **Не реализовано**: presigned upload (трек 1), reconciler orphan/missing (трек 2), thumbnail/crop/optimized (lab5), HTTPS/mTLS (lab7).
- **Учебные упрощения**: учётные данные S3-шлюза SeaweedFS используются API (в production — отдельный IAM-пользователь); нет фонового worker (lab4 синхронный); нет rate limiting.
- **Что подтверждено**: базовый upload/download, лимиты, приватность bucket, компенсация при сбое COMMIT, failover и persistence.
- **Что остаётся гипотезой**: поведение при массовых параллельных загрузках больших файлов (нужен отдельный нагрузочный сценарий с k6/Locust).