forked from mtusi2026/mtusi2026lab4
10 KiB
10 KiB
Отчёт — лабораторная 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-хуков).
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→ 503unavailable;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).