101 lines
10 KiB
Markdown
101 lines
10 KiB
Markdown
# Отчёт — лабораторная 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).
|