Files
mtusi2026lab4/REPORT.md
T

17 KiB
Raw Blame History

Отчёт — лабораторная 4

  • Автор, группа: Кузнецова Марина, БВТ2304
  • Целевая оценка: 5, Трек 1 — прямой upload (presigned)
  • Commit/PR: пока пусто
  • Использованные источники и помощь ИИ: официальная документация FastAPI, asyncpg, MinIO, Pillow, Docker Compose. ИИ применялся для пояснения требований, обсуждения архитектурных решений и проверки корректности реализации.

Запуск из чистого clone

Требования к окружению:

  • Python 3.13.15
  • Docker 26.1.1
  • git

Подготовка и запуск через Docker Compose:

cp .env.example .env
docker compose --env-file .env up -d --build --scale api=2

Ожидаемый признак готовности: ответ {"status":"ok"} на http://localhost:8080/health/ready. В логах migrate — migrations applied, контейнер Exited (0). В логах minio-init — bucket ready, контейнер Exited (0). Реплики api-1 и api-2 — healthy.

Проверка публичным smoke-тестом:

python -X utf8 tests/smoke.py --base-url http://localhost:8080

Проверка своими тестами:

python -X utf8 -m pytest student-tests/test_attachments.py -v
python -X utf8 -m pytest student-tests/test_presigned.py -v
python -X utf8 -m pytest student-tests/test_validation.py student-tests/test_race.py student-tests/test_cache.py -v

Проверка сохранности и отказа реплики:

python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8080
python -X utf8 tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://localhost:8080

Проверка сверки S3 и БД:

docker compose cp scripts/reconcile.py api:/tmp/reconcile.py
docker compose exec -T api python /tmp/reconcile.py --dry-run
docker compose exec -T api python /tmp/reconcile.py

Проверка пика RAM при 10 одновременных загрузках:

python -X utf8 scripts/ram_experiment.py

Сравнение proxy и presigned upload:

python -X utf8 scripts/presign_compare.py

Проверка приватности bucket снаружи:

docker compose exec -T postgres psql -U messenger -d messenger -c "SELECT chat_id, id FROM attachments LIMIT 1;"
curl.exe -i http://localhost:9000/attachments/<chat_id>/<id>

Ожидаемо: 403 AccessDenied.

Безопасная остановка:

  • docker compose down — остановка без потери данных.
  • docker compose down -v — удаление volumes, все данные пропадут.

Архитектура и решения

Схема:

Client → HTTP (Nginx :8080) → api-1, api-2 (FastAPI/Uvicorn)
                                  ↓
                           PostgreSQL (users/chats/messages/idempotency_keys/attachments)
                           Valkey (sessions + cache)
                           MinIO (bucket attachments, приватный)

Минимум lab3 сохранён: две реплики API за Nginx, общие PostgreSQL и Valkey, идемпотентность, failover, persistence. В lab4 добавлены MinIO, метаданные вложений в PostgreSQL, endpoint'ы вложений и attachment_ids в сообщении.

Компоненты:

  • compose.yaml — сервисы: postgres, valkey, minio, minio-init, migrate, api, lb.
  • nginx.conf — балансировщик, client_max_body_size 11m, таймауты 60 с.
  • app/main.py — FastAPI, lifespan, middleware X-Request-Id и X-Instance-Id, обработчики ошибок.
  • app/config.py — конфигурация из переменных окружения, включая S3.
  • app/db.py — пул соединений asyncpg.
  • app/migrate.py — отдельный модуль миграций.
  • app/migrations.py — раннер миграций.
  • app/models.py — Pydantic-модели, включая Attachment и attachment_ids.
  • app/security.py — Argon2id, токены, Basic и Bearer.
  • app/storage.py — PostgreSQL, транзакции, idempotency_keys, вложения.
  • app/session_store.py — backend для сессий.
  • app/cache.py — кэш истории и single-flight.
  • app/s3.py — клиент MinIO, presigned URL.
  • app/api/attachments.py — upload, download, presign, complete.
  • migrations/*.sql — 12 миграций (9 из lab3 + attachments + message_attachments + status).
  • scripts/reconcile.py — сверка S3 и БД с grace period.
  • scripts/ram_experiment.py — пик RAM при 10 загрузках.
  • scripts/presign_compare.py — сравнение proxy и presigned.
  • student-tests/test_attachments.py — негативные тесты вложений.
  • student-tests/test_presigned.py — тесты presigned.

Источник истины. PostgreSQL для пользователей, чатов, участников, сообщений, idempotency_keys и метаданных вложений. Байты — в MinIO, bucket attachments, приватный. Сессии — в Valkey.

Вложения. Метаданные в таблице attachments: id, chat_id, owner_id, object_key, filename, content_type, size_bytes, sha256, status, error_code, created_at, updated_at. object_key назначает сервер: {chat_id}/{uuid} для proxy, uploads/{chat_id}/{uuid} для presigned. filename — только для отображения, в пути не используется. Связь с сообщением — таблица message_attachments.

Proxy upload. POST /chats/{chat_id}/attachments?filename= принимает сырые bytes, проверяет членство, filename, лимиты, MIME по содержимому, пиксели, сохраняет объект в MinIO и метаданные в PostgreSQL в статусе ready. При ошибке записи метаданных объект удаляется (компенсация).

Download. GET /attachments/{id} и /content доступны только участникам чата. Без redirect, байты отдаются через API. Посторонний получает 404.

Presigned upload (Трек 1). POST /chats/{chat_id}/attachments/presign?filename=&size=&content_type= создаёт запись pending, генерирует presigned URL на 300 секунд с уникальным ключом. Клиент делает PUT напрямую в MinIO. POST /attachments/{id}/complete проверяет, что объект есть, размер совпадает, MIME по содержимому, content_type совпадает; после — ready, sha256 и фактический размер. Proxy endpoint сохранён.

Обработка ошибок. Единый формат {"error": {"code", "message", "request_id"}}. Недоступность PostgreSQL, Valkey или MinIO → 503. Пользовательские ошибки (400/413/415/404/409) не превращаются в 500.

Доказательства критериев «3»

Критерий Команда Результат
Возможности lab3 сохранены docker compose ps api-1, api-2 healthy; postgres, valkey healthy; lb Up
S3 в общем стенде, метаданные в PostgreSQL, байты в приватном bucket compose.yaml, migrations/010, 011 сервис minio + minio-init; таблицы attachments, message_attachments
POST вложения → 201 ready tests/smoke.py PASS
Оригинал скачивается побайтно tests/smoke.py PASS, sha256 и size совпадают
Message с attachment_ids читается участниками tests/smoke.py PASS
Посторонний → 404 test_attachments.py::test_outsider_cannot_download PASS
PNG/JPEG ≤10 MiB, ≤40 млн пикселей test_oversize_returns_413, test_corrupted_image_returns_415 PASS
MIME по содержимому test_mime_spoof_returns_415 PASS
Опасный filename → 400 test_bad_filename_returns_400 PASS
Upload → stop реплики → download через другую resilience.py --mode failover PASS, recovery 5.171 с, 7 записей, 0 ошибок
Restart с volumes сохраняет метаданные и оригинал resilience.py --mode persistence PASS
Приватный bucket вне API curl http://localhost:9000/attachments/<chat_id>/<id> 403 AccessDenied

Доказательства критериев «4»

Критерий Команда Результат
Негативные тесты: oversize, corrupted, MIME spoof, чужой id, другой чат pytest student-tests/test_attachments.py -v 10 passed
Пользовательская ошибка не 500 test_user_error_is_not_500 PASS
Компенсация S3↔БД с grace period scripts/reconcile.py --dry-run, scripts/reconcile.py orphans_found=0, fresh_skipped=0, metadata_without_object=0
Потоковая обработка и лимит RAM app/api/attachments.py _read_limited читает чанками по 64 КБ, обрывает при >10 MiB
Эксперимент ≥10 загрузок с пиком RAM scripts/ram_experiment.py 10 × 9 MiB, errors: 0, baseline 50.9 MiB, peak 164.9 MiB, delta 114.0 MiB, лимит 256 MiB
Bucket bootstrap идемпотентен docker compose logs minio-init bucket ready, Exited (0); --ignore-existing, `
Отдельные S3 credentials compose.yaml S3_ACCESS_KEY=api-user, S3_SECRET_KEY=api-user-secret-123
Консоль не опубликована compose.yaml minio публикует только 127.0.0.1:9000
Приватный bucket вне API curl без credentials 403 AccessDenied

Трек 1: прямой upload (presigned)

Гипотеза. Presigned upload переносит передачу байтов с API на MinIO: клиент загружает объект напрямую по подписанному URL, а API только выдаёт подпись и подтверждает завершение. Это должно снизить трафик через API при загрузке больших файлов и не менять обязательный proxy endpoint.

Реализация.

  • POST /chats/{chat_id}/attachments/presign?filename=&size=&content_type= → 201 {upload_url, attachment_id, expires_in}.
  • Подпись живёт 300 секунд. Ключ уникален: uploads/{chat_id}/{uuid}. Статус вложения — pending.
  • Клиент делает PUT upload_url напрямую в MinIO.
  • POST /attachments/{id}/complete проверяет: объект есть (stat_object), размер совпадает с заявленным, MIME по содержимому, content_type совпадает; после — status='ready', sha256 и фактический размер.
  • Proxy endpoint POST /chats/{chat_id}/attachments сохранён и работает.

Негативные сценарии.

  • Подменённая подпись → 403 от MinIO (test_presigned_bad_signature_rejected).
  • Complete без загрузки объекта → 409 (test_presigned_complete_without_upload_409).
  • Complete чужого attachment_id → 404 (test_presigned_outsider_404).
  • Complete не в pending → 409 (проверяется в коде).

Тесты: pytest student-tests/test_presigned.py -v → 5 passed.

Сравнение трафика и RAM. scripts/presign_compare.py, размеры 1 MiB и 9 MiB, пик RAM API через docker stats:

Размер Режим Время, с RAM baseline, MiB RAM peak, MiB Δ RAM, MiB
1 MiB proxy 2.47 48.9 48.9 0.0
1 MiB presigned 5.08 48.9 49.3 0.4
9 MiB proxy 3.09 49.3 49.3 0.0
9 MiB presigned 4.76 49.3 50.2 0.9

Интерпретация.

  • Трафик. В proxy-режиме тело идёт клиент → API → MinIO. В presigned — клиент → MinIO напрямую, через API только метаданные подписи и complete. Это главный выигрыш Трека 1.
  • Время. Presigned медленнее одного upload (5.08 с против 2.47 с для 1 MiB; 4.76 с против 3.09 с для 9 MiB), потому что это два раунда (presign → PUT → complete), и complete читает объект из MinIO для проверки MIME и SHA-256. Presigned выигрывает в трафике API, а не в latency одного запроса.
  • RAM. дельта RAM мал в обоих режимах (0.0–0.9 MiB), потому что docker stats --no-stream делает один снимок и не попадает в пик за 3–5 секунд. Для более чувствительного замера нужен непрерывный sampler или memory.peak из cgroup.

Ограничения.

  • Presigned URL — bearer token: кто получил URL, может загрузить объект в течение 5 минут. Поэтому подпись короткая, ключ уникальный, complete проверяет размер, тип и checksum.
  • Незавершённые загрузки (pending без объекта) не удаляются автоматически; В Треке 1 они только логируются.
  • Сравнение — на одном Docker-хосте, closed-loop.
  • Proxy endpoint остаётся обязательным; presigned — дополнительный flow, а не замена.

Исправления по ходу работы

  1. 413 от Nginx в HTML вместо JSON. В nginx.conf поставлен client_max_body_size 11m, чтобы API сам возвращал 413 в общем JSON-формате.
  2. Presigned URL указывал на minio:9000. Добавлен S3_PUBLIC_ENDPOINT=localhost:9000 и отдельный клиент для подписи. В Minio(...) задан region="us-east-1", иначе presigned_put_object ходит в сеть за регионом и падает.
  3. check_contract.py не запускался на Windows. make check использует python3; на Windows запускается python scripts/check_contract.py.

Ограничения и следующие шаги

Что выдерживается:

  • Перезапуск API, БД, Valkey и MinIO с сохранением volumes: данные, сессии и объекты на месте.
  • Остановка одной API-реплики: сервис продолжает работать, ошибки только в момент обнаружения отказа (0.015–0.046 с).
  • Вложение, загруженное на одной реплике, скачивается через другую.
  • Одновременные повторы POST сообщения с одним Idempotency-Key через разные реплики: создаётся одно сообщение.
  • Недоступность Valkey, PostgreSQL или MinIO: /health/ready → 503.
  • Пользовательские ошибки вложений (400/413/415/404/409) не превращаются в 500.

Что не выдерживается:

  • Потеря Docker-хоста целиком: все контейнеры на одном узле.
  • Потеря узла PostgreSQL: без репликации БД не выживет.
  • Потеря узла Nginx: LB — SPOF.
  • Потеря узла MinIO: без репликации S3 не выживет.
  • Rolling update на время перезапуска реплика недоступна.

Учебные упрощения:

  • Все контейнеры на одном Docker-хосте.
  • Nginx без активных healthcheck (только пассивные по max_fails).
  • HTTP без TLS.
  • Миграции не поддерживают rollback.
  • Idempotency-Key защищает только POST сообщений.
  • Presigned URL живёт 5 минут; незавершённые pending не удаляются автоматически (задача Трека 2).
  • RAM-замер через docker stats --no-stream недостаточно чувствителен.