17 KiB
Отчёт — лабораторная 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, middlewareX-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, а не замена.
Исправления по ходу работы
- 413 от Nginx в HTML вместо JSON. В
nginx.confпоставленclient_max_body_size 11m, чтобы API сам возвращал 413 в общем JSON-формате. - Presigned URL указывал на
minio:9000. ДобавленS3_PUBLIC_ENDPOINT=localhost:9000и отдельный клиент для подписи. ВMinio(...)заданregion="us-east-1", иначеpresigned_put_objectходит в сеть за регионом и падает. 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недостаточно чувствителен.