Files
mtusi2026lab4/REPORT.md

22 KiB
Raw Permalink Blame History

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

  • Автор, группа: Никитин Андрей Александрович, группа БВТ2301
  • Целевая оценка: 5
  • Трек 5: Track 1 (Presigned upload)
  • Commit/PR: ветка solution/nikitin-bvt2301 → MR в main (шаблон .github/pull_request_template.md); remote gitea.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) выполнен, см. раздел выше.