Files
mtusi2026lab4/REPORT.md
T

16 KiB
Raw Blame History

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

  • Автор, группа: Кунецкий Владислав, БВТ2303
  • Целевая оценка; выбранный трек 5: 5, трек 1 (presigned direct upload)
  • Commit/PR: ветка lab4; см. git log --oneline
  • Использованные источники, библиотеки и помощь ИИ: Go 1.27, PostgreSQL 18, SeaweedFS 3.80, HAProxy 3.2, AWS SDK for Go v2, ogen 1.24, sqlc, goose, mockery. Внешние источники: контракт 1.4.0, OWASP File Upload Cheat Sheet, AWS S3 presigned URL docs, Stripe idempotency docs, PostgreSQL advisory locks, Docker Compose startup order, SeaweedFS S3 docs. ИИ-ассистент использовался для генерации кода и текста; все сценарии воспроизведены локально, результаты сохранены в evidence/lab4/.

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

Prerequisites: Docker Engine/Desktop с Compose v2, Python 3.10+ для публичных и студенческих тестов, Go 1.27 — только для unit/integration тестов и make generate (образ собирает приложение сам).

git clone <repo> mtusi2026lab4 && cd mtusi2026lab4
git switch lab4
cp -n .env.example .env
# синтетические креды S3 уже согласованы с infra/s3/s3.json:
make check
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождаться /health/ready (LB, localhost:8080), затем:
make test
make test-attachments
make test-presign
make test-persistence ACTION_SCRIPT=scripts/restart.sh

Остановка без потери данных: docker compose --env-file .env down (named volumes сохраняются). Намеренное удаление учебных данных: docker compose --env-file .env down -v (PostgreSQL, Redis, SeaweedFS). make test-failover ACTION_SCRIPT=scripts/stop-one.sh останавливает одну API-реплику; вернуть её: docker compose --env-file .env up -d --no-deps api.

make validate требует requirements-dev.txt; локально использовался .venv: python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt. make check проверяет контракт, Python-синтаксис и совпадение S3 identities с .env. .env не коммитится; все значения в infra/s3/s3.json — синтетические для локального стенда.

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

flowchart LR
  C[Клиент] -->|HTTP| LB[HAProxy :8080]
  LB --> A1[API 1]
  LB --> A2[API 2]
  A1 --> PG[(PostgreSQL: метаданные)]
  A2 --> PG
  A1 -->|S3 SDK| S3[(SeaweedFS: байты)]
  A2 -->|S3 SDK| S3
  A1 -->|presigned PUT URL| C
  C -->|PUT напрямую| S3
  A1 -.->|sweep + advisory lock| PG
  A1 -.->|sweep| S3
  • Источник истины: метаданные (users, chats, messages, attachments, message_attachments) — PostgreSQL; оригиналы — только приватный bucket SeaweedFS. Redis используется для кэша списка чатов и не является источником истины.
  • 201 честный: upload сначала валидирует изображение, пишет объект в S3, затем переводит pending-строку в ready. 201 возвращается только после обоих шагов. Если процесс умер между ними, строка остаётся pending, объект уже в S3; sweeper либо восстанавливает ready, либо удаляет пару после grace.
  • Границы транзакций: сообщение и связи message_attachments вставляются в одной транзакции вместе с Idempotency-Key; вложения проверяются до claim. Сам S3 не транзакционен, поэтому используется pending/ready + компенсация.
  • Идемпотентность сообщений: fingerprint включает text и attachment_ids в исходном порядке; отсутствующий attachment_ids и [] эквивалентны. Повтор с другим набором или порядком — 409.
  • Sweeper: один владелец через pg_try_advisory_lock, grace period. Удаляет только объекты старше grace и только не ready; pending с валидным объектом восстанавливает в ready. Повторный запуск идемпотентен.
  • Readiness: проверяет PostgreSQL, но не S3. S3 общий для всех реплик; его недоступность не должна убирать из ротации весь стенд. Attachment-endpoint при этом отвечают 503, остальные продолжают работать. Это осознанное решение зафиксировано здесь.
  • Перенесено из lab3: пользователи, сессии, чаты, сообщения, идемпотентность, LB, PostgreSQL, Redis, Compose/Swarm-подход, HAProxy active checks. Добавлено: S3-стенд, s3-init, миграция 00004, вложения, presign-расширение, sweeper.
  • Переменные: .env.example перечисляет реальные имена, которые читает viper (S3_*, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS, S3_SWEEP_*). Для двух лимитов добавлены явные alias-биндинги, потому что skeleton предлагал имена без префикса S3_.

Presigned extension

Контракт contracts/openapi.json не изменён. Дополнительные endpoint:

  • POST /api/v1/chats/{chat_id}/attachments/presign — JSON с filename, content_type, size_bytes, sha256; создаёт pending-строку и возвращает короткоживущий URL.
  • POST /api/v1/attachments/{attachment_id}/complete — проверяет размер, фактический SHA-256 и структуру изображения, копирует объект из staging/ в attachments/ и переводит строку в ready.

Преимущества и ограничения:

  • тело не проходит через API/LB (в замере LB RX падает с 9,49 МБ до 3,8 КБ для 9 МиБ);
  • complete перечитывает объект из S3 для проверки SHA, поэтому API RX остаётся около размера файла; выигрыш — в клиентском плече и в отказе от приёма тела;
  • Content-Length подписан в URL, поэтому S3 отклоняет PUT другого размера с 403 ещё до сохранения; complete повторно сверяет размер, SHA-256 и структуру. Брошенные объекты удаляет sweeper после grace;
  • URL — bearer-токен, многоразовый до expires_at; подпись привязана к host+key, Content-Type не подписывается.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make test PASS, lab4 evidence/lab4/smoke.txt
Все обязательные endpoint lab3 сохранены smoke + make test-persistence PASS smoke.txt, persistence.txt
S3 в общем стенде, bucket приватный docker compose exec seaweedfs wget …/attachments/nope HTTP 403 private-bucket.txt
Метаданные в PostgreSQL, байты в S3 архитектура + GET /content после остановки реплики скачивание через другую реплику failover.txt
POST вложения 201 ready, оригинал побайтно attachment() в smoke checksum/size совпадают smoke.txt
Message с attachment_ids smoke, student-tests/attachments_negative.py attachment_ids сохранены smoke.txt, negative.txt
PNG/JPEG ≤10 MiB, ≤40 МП, MIME по содержимому make test-attachments 413/415 на границах negative.txt
Опасные filename 400 на /, \, NUL, control 400 negative.txt
Upload → stop реплики → download другой attachment_failover.py SHA совпадает failover.txt
Restart с volumes make test-persistence данные и сессия сохранены persistence.txt
Уровень 4: негативные тесты make test-attachments PASS, ни одного 500 negative.txt
Отказ между S3/БД не оставляет вечных объектов sweep.txt + unit-тесты sweeper pending удалён после grace, ready жив sweep.txt
Лимиты/таймауты/стриминг, RAM ограничена memory experiment 10 одновременных × 9,45 МБ; anon +1,97 МБ memory/
Bootstrap bucket идемпотентен s3-init дважды оба запуска exit 0 s3-init.txt
Отдельные ограниченные S3 credentials s3-init probes + docker compose exec app не пишет вне префиксов; anonymous 403 s3-init.txt, private-bucket.txt
Админ-консоль/порты не в общей сети docker compose ps опубликованы только LB и loopback S3 private-bucket.txt
Трек 1: presigned upload make test-presign, expiry.txt happy path, foreign, incomplete, checksum, expiry presign.txt, expiry.txt
Трек 1: трафик и RAM на ≥2 размерах scripts/lab4_track1.py LB RX 3,8 КБ vs 1,05/9,49 МБ track1/

Эксперименты и отказы

Стенд: Apple Silicon (arm64), Docker Desktop с VM 1,9 ГБ, Compose; API 2 реплики × 256 МБ, SeaweedFS 640 МБ (GOMEMLIMIT 512 MiB), PostgreSQL 192 МБ, Redis 96 МБ, HAProxy 48 МБ. Все замеры — локальные, без внешней сети.

Воздействие Что ожидали Что наблюдали Восстановление / потери
Upload, затем stop обслужившей реплики download через вторую реплику PASS, байты и SHA совпали HAProxy убрал реплику; возврат up -d --no-deps api
Restart PostgreSQL/Redis/SeaweedFS/API с volumes метаданные, сессия и оригинал сохраняются PASS 43,9 с до readiness; потерь нет
Остановка SeaweedFS upload/download 503, остальное 200 /health/ready 200, чаты 200, upload/download 503 после старта upload снова 201
Брошенный presign без PUT удаление после grace, ready не трогать pending исчез после ~2 с grace; ready скачан sweeper, потерь ready нет
10 одновременных загрузок по 9 454 448 Б, 3 раунда API не OOM, RAM ограничена 30 загрузок за 2,98 с; anon baseline 280,3 МБ, peak 281,7 МБ (+1,34 МБ); memory.current peak 411,8 МБ на две реплики; SeaweedFS restarts=0, OOM=false без OOM после подбора лимитов под 1,9 ГБ VM
Presigned URL с TTL=3 с 403 после истечения 403 через 4 с —
Неверный SHA на complete отказ и очистка 409/400, объект удалён повторная загрузка возможна

Трек 1: proxy vs presigned

Размер Поток Медиана, с p95, с LB RX, Б API RX, Б API anon peak, Б
~1 МиБ proxy 0,228 0,233 1 058 392 1 061 729 285 638 656
~1 МиБ presign 0,230 0,239 3 755 1 058 061 286 216 192
~9 МиБ proxy 0,237 0,240 9 490 341 9 494 663 286 285 824
~9 МиБ presign 0,239 0,246 3 879 9 472 840 286 367 744

Методика: 5 итераций на сценарий без прогрева (стенд уже прогрет), PNG фиксированного размера, клиент — тот же хост. lb_rx — сумма по LB; api_rx — сумма по двум API; anon — cgroup memory.stat, сэмплирование 0,1 с. Ограничение: memory.current включает page cache временных файлов; поэтому основная метрика — anon. Стенд локальный, сеть Docker bridge, поэтому абсолютные латентности не переносятся на production.

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

  • Readiness не включает S3. Это выбрано, чтобы недоступность общего S3 не убирала из ротации все API-реплики; attachment-endpoint деградируют в 503. Если политика требует fail-closed, добавьте S3 в readiness отдельным флагом.
  • Presigned PUT ограничен подписанным Content-Length. Клиент обязан прислать ровно заявленный размер; иначе SeaweedFS отвечает 403 (проверено). Это защищает от записи огромного staging-объекта, но не заменяет rate limiting: число готовых вложений и pending-строк по-прежнему не квотируется.
  • Complete перечитывает объект из S3. SeaweedFS не валидирует и не хранит checksum, поэтому честная проверка SHA требует чтения. Для больших файлов это удваивает внутренний трафик.
  • S3 — одна нода SeaweedFS. Это учебный стенд; HA/replication не настроены. Потеря volume означает потерю байтов; метаданные в PostgreSQL при этом остаются. Лимиты контейнеров подобраны под Docker Desktop VM 1,9 ГБ; HAProxy timeout server увеличен до 45 с для 10 MiB загрузок, readiness-проба по-прежнему 1 с.
  • lab5 не реализован: thumbnail, варианты, queued/processing/202, worker. Поле variants всегда [], status — только ready.
  • Старые Idempotency-Key lab3 имеют fingerprint без attachment_ids; повтор такого ключа в пределах TTL даст 409. Это осознанное изменение формата, данные не мигрируются.
  • Rate limiting (429) и квоты не реализованы; контракт их не требует. Локальный docker-compose.local.yaml публикует PostgreSQL/Redis на loopback с учебными паролями, а HAProxy stats на 8404 не требует аутентификации — это операторские порты, не публичный стенд.
  • Секреты: локальные S3-креды синтетические и лежат в infra/s3/s3.json/.env.example; admin-креды не входят в .env и не попадают в API-контейнер (проверено docker compose exec api env). Для production нужны отдельные секреты и отзыв URL через ротацию кредов.
  • Проверка изображений структурная, без decode+re-encode (OWASP рекомендует re-encode для недоверенных изображений). В lab4 изображения не обрабатываются и не исполняются; lab5 добавит контролируемый decode для thumbnail.