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

10 KiB
Raw Blame History

Отчёт — лабораторная 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 → 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).