22 KiB
Отчёт — лабораторная 4
- Автор, группа: Никитин Андрей Александрович, группа БВТ2301
- Целевая оценка: 5
- Трек 5: Track 1 (Presigned upload)
- Commit/PR: ветка
solution/nikitin-bvt2301→ MR вmain(шаблон.github/pull_request_template.md); remotegitea.privcloud.tech/AndrewNikkk/mtusi2026lab4 - Источники и помощь: контракт и публичные тесты курса; PostgreSQL 16, Valkey, Nginx, MinIO, libpqxx 7.10.0, libsodium, hiredis, nlohmann/json, minio-cpp v0.3.0 (официальный SigV4), stb_image. Помощь ИИ: Cursor.
Запуск из чистого clone
Хост прогона: 12th Gen Intel Core i5-12450H, 12 потоков, 14 GiB RAM.
Образы (закреплены в compose.yaml / локальных Dockerfile):
| Сервис | Образ |
|---|---|
| db | postgres:16.15-alpine |
| cache | valkey/valkey:8.1.10-alpine |
| lb | nginx:1.28.0-alpine |
| api | mtusi2026lab4-api:local (multi-stage ubuntu:24.04; libpqxx 7.10.0 собран из git-тега https://github.com/jtv/libpqxx.git, prefix /opt/libpqxx; minio-cpp v0.3.0 FetchContent) |
| minio | mtusi2026lab4-minio:RELEASE.2025-04-22T22-12-26Z (бинарник с GitHub; Docker Hub в среде мог быть недоступен) |
| mc (init) | mtusi2026lab4-mc:RELEASE.2025-04-16T18-13-26Z |
Лимиты compose: db 1 CPU / 512 MiB; cache 0.5 / 256 MiB; api ×2 по 0.5 CPU / 256 MiB; lb 0.25 / 128 MiB; minio 0.5 / 512 MiB.
Prerequisites: Docker Compose v2, Python 3.9+, curl, jq, sha256sum. Для make validate — venv из requirements-dev.txt.
cp .env.example .env
# Задать POSTGRES_*, MINIO_ROOT_*, MINIO_USER_*, S3_BUCKET (без коммита .env)
mkdir -p secrets
printf 'postgresql://USER:PASSWORD@db:5432/DB\n' > secrets/database_url
printf 'redis://cache:6379/0\n' > secrets/cache_url
# Те же значения, что MINIO_USER_* в .env (не root):
printf 'ACCESS_KEY\n' > secrets/s3_access_key_id
printf 'SECRET_KEY\n' > secrets/s3_secret_access_key
chmod 600 secrets/*
# Чистый clone: Dockerfile сам тянет ubuntu:24.04 и собирает libpqxx 7.10.0.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Эквивалент без compose:
# docker build -t mtusi2026lab4-api:local .
# Дождаться healthy у lb, затем:
curl -fsS http://127.0.0.1:8080/health/ready
make check
make test BASE_URL=http://127.0.0.1:8080
sh student-tests/run_grade3.sh
sh student-tests/run_grade4.sh
sh student-tests/run_grade5_track1.sh
# Опционально: сравнение RAM proxy vs direct (≥2 размера)
# sh tools/exp_direct_vs_proxy.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# Безопасная остановка (volumes сохраняются):
docker compose --env-file .env stop
# Намеренное удаление учебных данных:
# docker compose --env-file .env down -v
Хосты в секретах — имена сервисов Compose (db, cache, minio), не loopback. Порты MinIO не публикуются по умолчанию; снаружи только LB :8080. Для host-side PUT к presigned URL — опционально compose.presign.yaml + S3_PRESIGN_ENDPOINT=http://127.0.0.1:9000 (loopback). Иначе PUT идёт из контейнера на сети compose (http://minio:9000/...). Миграции 001–007 применяет API при старте под pg_advisory_lock.
Соответствие .env.example → compose: S3_ENDPOINT/S3_BUCKET/S3_REGION, S3_*_FILE → docker secrets, MAX_UPLOAD_BYTES/MAX_IMAGE_PIXELS, DIRECT_UPLOAD_TTL_SECONDS, DRAIN_SECONDS, API_REPLICAS, SESSION_STORE=redis. Root MinIO только у minio / init-job'ов; API видит лишь limited *_FILE.
Архитектура и решения
Proxy: Клиент → lb → api (buffer body) → MinIO PutObject → PG attachments
Direct: Клиент → lb → api init → presigned PUT URL (staging/{chat}/{upload})
Клиент ─────────────── PUT ──────→ MinIO staging
Клиент → lb → api complete (HEAD+Get+sha256+image+CopyObject)
staging → attachments/{chat}/{attachment}
→ PG attachment + completed session
Источник истины: метаданные вложений и связь message↔attachment — PostgreSQL; оригинал — объект MinIO attachments/{chat_id}/{attachment_id} (filename только для отображения). Presigned PUT пишет в отдельный staging/{chat_id}/{upload_id}. Direct sessions хранят оба ключа в direct_uploads (миграции 006–007).
Порядок записи (proxy, компенсация): S3 PutObject → INSERT attachments → COMMIT. Если INSERT/COMMIT упал — best-effort DeleteObject, ответ 500. Строка в PG без объекта недопустима. Orphan'ы: tools/gc_orphans.sh (учитывает direct_uploads.status=pending).
Track 1 (presigned): POST /api/v1/chats/{id}/direct-uploads создаёт pending сессию и выдаёт SigV4 PUT URL (minio-cpp GetPresignedObjectUrl, TTL по DIRECT_UPLOAD_TTL_SECONDS, 30–3600 секунд; default 300). URL сам по себе повторно используем до истечения TTL, поэтому он не считается одноразовым токеном. Одноразово публикуется именно сессия complete: её статус переходит pending → completed.
POST /api/v1/direct-uploads/{id}/complete в одной PostgreSQL-транзакции делает SELECT ... FOR UPDATE, проверяет существование/размер/hash staging-объекта и изображение, затем выполняет серверный CopyObject в final prefix, вставляет attachments.status=ready, помечает сессию completed и коммитит. SHA-256 берётся из expected_sha256, заявленного при init. Повторный complete возвращает сохранённый Attachment без повторного S3 copy; конкурентные complete одного id сериализуются блокировкой строки. Удаление staging после публикации best-effort.
Повторный PUT по ещё действующей старой ссылке может создать staging-orphan, но не перезаписывает final object. tools/gc_orphans.sh сканирует attachments/ и staging/, сохраняет pending staging keys и удаляет неизвестные объекты только после GRACE_SECONDS. Abort удаляет staging best-effort; стандартный proxy POST /api/v1/chats/{id}/attachments сохранён.
ACL: метаданные и /content только участнику чата; чужой → 404; без Bearer → 401. Unsigned GET на http://minio:9000/$BUCKET/$KEY → 403.
Валидация изображения: magic (JPEG FFD8FF / PNG 89504E47) → stbi_info (пиксели ≤40e6) → stbi_load (целостность) → сравнение с Content-Type. Spoof MIME → 415. Тело ≤10 485 760; ранний отказ по Content-Length с drain, чтобы nginx не отдавал 502. LB: client_max_body_size 12m.
Message.attachment_ids: 0..10 уникальных UUID того же чата со status=ready; пустой/blank text без вложений → 400; с вложениями пустой text допустим. Идемпотентность хеширует text + список id.
Из lab3: пользователи/чаты/сообщения, Redis-сессии, Idempotency-Key, LB×2 API, drain по SIGTERM (DRAIN_SECONDS, ready=503).
S3-клиент: minio-cpp v0.3.0 через FetchContent (не самописный SigV4). aws-sdk-cpp отвергнут из‑за тяжёлой сборки aws-lc в этой среде.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|---|---|---|---|
| Контракт offline | make check |
PASS: offline skeleton structure… | вывод команды |
| OpenAPI 3.1 | make validate PYTHON=.venv/bin/python |
PASS: full OpenAPI 3.1 and JSON Schema validation | вывод команды |
| Публичный smoke | make test BASE_URL=http://127.0.0.1:8080 |
PASS (lab4 smoke) | вывод команды |
MinIO в стенде, private bucket, volume miniodata |
docker compose ps; sh tests/check_bucket_private.sh |
minio healthy; unsigned GET → 403; host :9000/:9001 closed |
evidence/resilience_grade4.txt |
| POST attachment → 201 ready; download = sha256 | sh student-tests/test_attachment_upload_ok.sh |
201, status=ready, variants=[], bob скачал тот же SHA-256 |
вывод теста |
Message + attachment_ids, empty text ok |
тот же + wrong_chat | empty+att 201; blank без att → 400; чужой chat → 404 | student-tests/ |
| Лимиты / MIME / corrupt / foreign | too_large, corrupted, mime_spoof, foreign | 413 / 415 / 415 / 404 (не 500) | student-tests/run_grade3.sh |
| Persistence (метаданные + байты) | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS; hook рестартит db, cache, minio, api, lb; volumes на месте | evidence/resilience_grade4.txt |
| Failover: upload на одной → download с другой | make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
PASS; 2 instance до отказа; 115 успехов; 1 ошибка; first_recovery ≈5.3 с; attachment bytes совпали | evidence/resilience_grade4.txt |
| Limited S3 creds, не root | sh student-tests/test_attachment_limited_creds.sh |
API только S3_*_FILE; key ≠ root; mc rb limited → deny; upload 201 |
тот же evidence |
| Компенсация / GC | код upload + tools/gc_orphans.sh |
dry-run: orphans=0 при согласованном стенде; grace skip свежих | вывод gc_orphans |
| ≥10 параллельных загрузок ~5 MiB | sh scripts/load_uploads.sh |
10×201; delta < naive (см. JSON); MAX_CONCURRENT_UPLOADS=3; слот до буферизации body |
evidence/load_uploads.json |
| Graceful drain | sh student-tests/test_graceful_drain.sh |
SIGTERM → ready 503/stop; стенд восстановлен | вывод теста |
| Идемпотентный bootstrap bucket/user | minio-init, minio-user-init |
повторный up без ошибки; mc mb --ignore-existing; anonymous none |
логи init |
| Трек 1: init→PUT→complete; proxy жив | sh student-tests/run_grade5_track1.sh |
PASS (ok + negatives + gc dry-run) | student-tests/ |
| Track 1: concurrent complete | sh student-tests/test_presigned_complete_concurrent.sh |
4 complete: ровно 1×201, остальные 200/409, ни одного 500; metadata и /content SHA-256 совпали с исходником |
student-tests/test_presigned_complete_concurrent.sh |
| Track 1: replay safety | sh student-tests/test_direct_upload_ok.sh |
upload → complete → повторный PUT 20 B по старой ссылке → download SHA-256 исходного PNG; final не изменён | student-tests/test_direct_upload_ok.sh |
| Download при отсутствующем S3-объекте | sh student-tests/test_download_missing_object.sh |
после mc rm content отвечает 404/5xx, не 200; объект восстанавливается тестом |
student-tests/test_download_missing_object.sh |
| Трек 1: RAM/трафик ≥2 размеров | sh tools/exp_direct_vs_proxy.sh |
transfer: direct ≪ proxy по RSS и api_body | artifacts/track1/results.tsv |
Перезапускаемые процессы при persistence hook: db, cache, minio, api (все реплики), lb. Volumes pgdata, valkeydata, miniodata не удаляются. Failover hook останавливает только одну API-реплику по X-Instance-Id ≡ Config.Hostname.
Эксперименты и отказы
Гипотеза (нагрузка upload): пик RSS не должен расти как N×размер файла. Ограничение — семафор MAX_CONCURRENT_UPLOADS (по умолчанию 3) на процесс API: слот берётся до буферизации body (>256 KiB), независимо от HTTP_WORKERS=8. После каждого upload — malloc_trim(0), чтобы docker-stats RSS отражал concurrent footprint, а не рост арен. Тело ≤10 MiB; stbi_load освобождает raster; MemBuf без лишней копии.
Пик RSS ограничен формулой
rss_peak ≤ baseline + MAX_CONCURRENT_UPLOADS × (max_body + decoded_raster).
При MAX_CONCURRENT_UPLOADS=3 delta < naive_full_buffer_mib.
См. evidence/load_uploads.json.
Профиль: closed-loop, concurrency=10, fixture ≈5 881 918 байт (валидный PNG 1400×1400), один прогон. Клиент — urllib в N процессах. Baseline RSS — медиана нескольких docker stats после прогрева; peak — max MemUsage api во время окна. Ограничение измерения: coordinated omission / closed-loop; RPS отражает длительную валидацию+PUT.
Сырой summary без токенов: evidence/load_uploads.json.
| Метрика | Значение |
|---|---|
| success / codes | 10 / {201: 10} |
| wall / latency / RPS | см. JSON |
| API RSS baseline → peak (delta) | 51.96 → 68.4 (+16.44) MiB |
| naive N×fixture | ≈56.09 MiB |
MAX_CONCURRENT_UPLOADS |
3 (слот до body >256 KiB; malloc_trim после upload) |
Критерий защиты: api_rss_delta_mib (16.44) < naive_full_buffer_mib (56.09).
| Воздействие | Ожидание | Наблюдение | Восстановление / данные |
|---|---|---|---|
restart.sh (db+cache+minio+api+lb) |
сессия и attachment живы | test-persistence PASS |
hook <90 с; volumes целы |
stop-one.sh одной api |
≥2 id до отказа; запись ≤10 с; файл тот же | 2 id; 115 ok / 1 fail; recovery 5.338 с | attachment SHA совпал; реплика затем up -d |
| unsigned S3 GET | не 200 | 403 | — |
| host :9000/:9001 | connection fail | fail | — |
| 11 MiB upload | 413 JSON | 413 payload_too_large (после drain CL) |
— |
JPEG + Content-Type: image/png |
415 | 415 | — |
| truncate PNG | 415 | 415 | — |
| eve → чужой attachment | 404 | 404 meta и content | — |
| SIGTERM api | ready 503, затем exit | drain PASS | compose up api |
Ограничения и следующие шаги
Выдерживается: отказ одной API-реплики при живых LB/БД/MinIO; полный restart с сохранением volumes; private bucket; limited IAM-подобные creds; негативные upload без 500; идемпотентные сообщения с attachment_ids.
Не выдерживается / не обещается: падение единственной PostgreSQL или MinIO; потеря volume; HA брокера; сетевой partition между API и S3 без ручного GC; точный open-loop RPS.
Учебные упрощения: proxy-тело буферизуется до MAX_UPLOAD_BYTES; complete direct-upload кратковременно читает объект для sha256/image check (байты PUT при этом не идут через API); нет thumbnail/вариантов (lab5); один Docker-host, один LB, одна БД, один MinIO; console MinIO :9001 внутри сети compose.
Подтверждено измерением (grade 4): 10 параллельных ~5.6 MiB proxy-загрузок → 201; delta RSS < naive; private bucket; persistence/failover.
Track 1: Presigned upload
Архитектура и семантика: presigned PUT направлен только на staging/{chat_id}/{upload_id}. После HEAD/stat, проверки expected_size, SHA-256 из init и image validation API копирует staging в attachments/{chat_id}/{attachment_id}. В attachments.s3_key хранится только final key. TTL ссылки задаётся DIRECT_UPLOAD_TTL_SECONDS (30–3600 секунд, default 300); пока TTL не истёк, URL можно повторно вызвать, но replay меняет только staging. Complete логически single-use: pending → completed; SELECT FOR UPDATE делает повторы и конкурентные запросы идемпотентными, они возвращают существующий Attachment без S3-публикации.
Если старый PUT выполняется после complete, он оставляет staging-orphan; final-объект остаётся прежним. tools/gc_orphans.sh очищает orphan-объекты обоих prefix по GRACE_SECONDS, не удаляя staging активных pending сессий. Staging cleanup после успешной публикации и abort — best-effort.
Ограничения: стандартная загрузка ограничена 10 MiB. Multipart-upload для файлов больше 100 MiB не реализован; presigned GET для скачивания тоже не реализован. Download остаётся авторизованным через API. Контракт contracts/openapi.json не менялся: Track 1 — расширение, обязательный proxy upload сохранён.
Proxy vs presigned: proxy передаёт тело через LB/API и буферизует его перед MinIO, поэтому upload потребляет память API и дополнительный сетевой hop. При presigned передаче байты идут клиент→MinIO напрямую, API получает только init/complete и не буферизует тело PUT. Complete добавляет HEAD/stat, чтение для SHA/image validation и server-side copy, поэтому его latency выше собственно PUT и измеряется отдельно.
API (расширение, openapi не менялся):
| Метод | Путь | Назначение |
|---|---|---|
| POST | /api/v1/chats/{id}/direct-uploads |
JSON: filename, content_type, size_bytes, sha256 → upload_url + TTL |
| PUT | presigned URL | байты напрямую в MinIO (Content-Type из ответа) |
| POST | /api/v1/direct-uploads/{id}/complete |
Stat/size/sha256/image → attachment ready |
| DELETE | /api/v1/direct-uploads/{id} |
abort + DeleteObject |
| POST | /api/v1/chats/{id}/attachments |
обязательный proxy — без изменений |
Состояния и ошибки: complete без объекта → 409 not_ready; размер или checksum mismatch → 409 hash_mismatch; чужой upload → 404; abort → 204; повторный complete после успеха → 200 с тем же Attachment; aborted/expired session не публикуется; просроченный pending → 410.
Проверка: sh student-tests/run_grade5_track1.sh → PASS; sh student-tests/run_grade3.sh → PASS; sh student-tests/run_grade4.sh → PASS. Четыре одновременных complete дали ровно один 201, остальные ответы были 200/409, 500 не было; metadata и content SHA-256 совпали. Replay-проверка повторно PUT-ит 20-byte текст по старому URL и подтверждает SHA-256 исходного PNG при download. Эксперимент proxy vs direct: sh tools/exp_direct_vs_proxy.sh → artifacts/track1/results.tsv.
Методика: closed-loop; concurrency 3 (1 MiB) / 4 (4 MiB); RSS = сумма VmRSS процессов messenger по репликам api; фаза transfer — только передача байт (для direct — параллельные PUT на MinIO); complete — отдельно (GetObject+sha256+image на API). api_body_bytes_approx — оценка объёма тел через API (proxy = N×size; direct transfer = 0).
| size_mb | mode / phase | rss_delta_kb | api_body_bytes_approx |
|---|---|---|---|
| 1 | proxy / transfer | 1112 | 3 145 752 |
| 1 | direct / transfer | 4 | 0 |
| 1 | direct / complete | 4104 | (GetObject на API) |
| 4 | proxy / transfer | 3320 | 16 777 248 |
| 4 | direct / transfer | 0 | 0 |
| 4 | direct / complete | 15592 | (GetObject на API) |
Вывод: на этапе передачи байт direct почти не двигает RSS API и не гонит payload через LB/API; proxy платит и трафиком, и пиком RSS. Complete у direct кратковременно читает объект (учебный verify) — это отдельная фаза, не отменяет выигрыш на upload path.
Ограничение: без compose.presign.yaml PUT выполняется с контейнера на сети compose (порты MinIO на хост не открыты). Подпись — minio-cpp PresignV4 (не самописный SigV4).
Track 5 (reconciler) не выполнялся; Track 1 (presigned) выполнен, см. раздел выше.