16 KiB
Отчёт — лабораторная 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.