18 KiB
Отчёт — лабораторная 4
- Автор, группа: Меркулова М.А., БВТ2303
- Целевая оценка: 4, трек 5 не заявлен
- Ветка:
solution/BVT2303-Merkulova, создана от исходногоmain - API: Go 1.26.8, PostgreSQL 17.6, Redis 8.2.1, Nginx 1.29.1.
- S3: MinIO
RELEASE.2025-10-15T17-29-55Z, официальный commit9e49d5e7a648f00e26f2246f4dc28e6b07f8c84a. - Библиотеки: pgx/v5, go-redis/v9, scrypt, minio-go/v7 7.0.95 и madmin-go/v3 3.0.95.
- ИИ использован для проектирования, кода и проверок. Публичный контракт и тесты не изменены; приведены результаты локальных запусков.
Запуск из чистого clone
Нужны Docker Desktop с Compose/BuildKit, Python 3.9+, make, OpenSSL и доступ к Docker Hub, GitHub codeload и Go module proxy. Локальный Go нужен только для отдельных go test/go vet.
./scripts/init-local.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
make check
make test
Dockerfile собирает образ Go API, а infra/Dockerfile.minio — MinIO из официальных исходников закреплённого commit. SHA-256 архива проверяется при сборке. Docker Compose автоматически собирает оба образа и запускает сервисы; отдельная установка MinIO не требуется.
init-local.sh генерирует случайные локальные secrets и .env, которые игнорируются Git. Миграции выполняет одноразовый migrate; приватный bucket и ограниченного пользователя создаёт s3-init. Он повторяем и не выдаёт root credentials API-копиям. Единственный публичный адрес — http://127.0.0.1:8080; API и S3 порты наружу не публикуются. Консоль MinIO выключена (MINIO_BROWSER=off), адрес дополнительно ограничен loopback контейнера.
Остановка с сохранением данных: docker compose --env-file .env down. Намеренный сброс только учебных данных: docker compose --env-file .env down -v — удаляет PostgreSQL/Redis/MinIO volumes.
Архитектура и изменения относительно lab3
flowchart LR
C[HTTP-клиент] --> L[Nginx]
L --> A1[API api-1]
L --> A2[API api-2]
A1 --> P[(PostgreSQL: метаданные)]
A2 --> P
A1 --> R[(Redis: сессии)]
A2 --> R
A1 --> S[(MinIO: приватные оригиналы)]
A2 --> S
G[Очистка незавершённых загрузок] --> P
G --> S
Перенесены регистрация, scrypt-пароли, Basic/Bearer, TTL/AOF, чаты, keyset-пагинация, две API-копии, общий Idempotency-Key, readiness-aware Nginx и graceful shutdown. Добавлены attachments.go, objectstore/, cleanup, миграция 003 и attachment_ids сообщений. Отсутствующее поле и [] эквивалентны; null и неверные типы отклоняются. Прежняя идемпотентность текстовых сообщений совместима с lab3.
PostgreSQL — источник истины для пользователей, чатов, сообщений, метаданных и журнала незавершённых upload. Оригиналы — только в приватном bucket messenger-attachments с ключами originals/<UUID>, которые назначает сервер. Filename — только отображаемое имя. Публичный ответ не содержит object key или credentials.
История сортируется по (created_at, id); время назначает PostgreSQL через clock_timestamp(). Каждый запрос страницы читает актуальные подтверждённые записи, общей snapshot между страницами нет. В неизменной истории курсор не повторяет последнюю запись. При конкурентных транзакциях запись с ключом раньше уже выданного курсора может подтвердиться позднее и не попасть в продолжение обхода; гарантия полного snapshot при одновременных вставках не заявляется.
Участие в чате проверяется до доступа к вложению; посторонние и attachment другого чата получают 404. Любой участник может прикрепить доступный файл своего чата. Download идёт через API без redirect и возвращает исходные bytes/Content-Type. Ready-метаданные: SHA-256 оригинала, размер, variants=[], error_code=null.
Лимиты и ресурсы
Лимиты оригинала жёсткие: 10 485 760 байт, 40 млн пикселей, PNG/JPEG. Content-Type сверяется с содержимым. Размеры проверяются через DecodeConfig до полной распаковки; полное декодирование отбрасывает повреждённые изображения. Filename — 1–255 Unicode code points без /, \, NUL и управляющих символов.
Upload копируется через ограниченный reader и буфер 32 KiB с вычислением SHA-256 во временный файл, затем передаётся в S3. Нет неограниченного ReadAll. На реплику один активный upload/decoder, временный файл <=10 MiB + 1 проверочный байт, tmpfs <=20 MiB. Файл удаляется при завершении запроса; API не имеет persistent volume с оригиналами, download от него не зависит. Максимальный 16-bit RGBA bitmap ограничен примерно 320 MB; декодер PNG также выделяет два буфера строк. Для крайнего широкого изображения нужен запас до примерно 960 MB живых буферов. Поэтому лимит API 1536 MiB, а мягкий Go GOMEMLIMIT — 1200 MiB. Потоковый приём не отменяет памяти декодера.
HTTP: header 5 s, read 45 s, write 60 s. Upload/download context 45 s, S3 PUT 20 s, соединение S3 2 s, SQL обычно 3 s. Nginx не буферизует request/response, upstream timeout 65 s. Байтный лимит применяет API для JSON 413. MAX_UPLOAD_BYTES/MAX_IMAGE_PIXELS в примере описывают фиксированные пределы, а не увеличение разрешённых значений.
Ресурсы Docker: API по 0.5 CPU/1536 MiB; PostgreSQL 1 CPU/512 MiB; MinIO 1 CPU/512 MiB; Redis 0.25 CPU/128 MiB; Nginx 0.25 CPU/64 MiB; cleanup 0.25 CPU/128 MiB. Проверки проведены на macOS arm64 с Docker VM 10 vCPU и 8 217 059 328 байт доступной памяти (около 7.65 GiB).
SIGTERM: Go прекращает новые соединения и ждёт текущие до 8 s; Compose даёт API 10 s. Hook намеренного отказа использует stop timeout 3 s и может оборвать запрос, который клиент повторяет по правилам контракта.
Согласованность БД и S3
- Неверный или прерванный HTTP upload не создаёт ready-метаданные. Файл полностью принят с лимитами и проверен до S3 PUT.
- Перед PUT отдельно фиксируется durable intent в
attachment_uploads. - Транзакция берёт advisory lock по object key, выполняет PUT, создаёт ready-метаданные, удаляет intent и делает COMMIT. Только после этого возвращается 201.
- Ошибка/падение оставляет intent. При неопределённом COMMIT объект немедленно не удаляется: COMMIT мог состояться.
- Cleanup раз в 60 s просматривает старые intents и S3 originals. Grace по умолчанию 3600 s, минимум 120 s — больше бюджета обычного upload. Свежий intent/объект сохраняется. Объект с ready-метаданными сохраняется при любом возрасте, даже если ещё не привязан к сообщению.
- Cleanup использует тот же advisory lock, пропускает активную запись и повторно проверяет БД. Сначала удаляется неучтённый объект, потом intent. Повтор после ошибки/падения безопасен. S3-обход покрывает и объект без intent, например поздний PUT после разрыва связи.
Ручной проход: docker compose --env-file .env exec -T cleanup /messenger cleanup. Это механизм очистки для уровня 4; ремонта missing-объектов и исследовательского трека 5 нет. Время отдельного прохода ограничено; полный обход рассчитан на учебный объём.
Root credentials есть только у MinIO и s3-init. API/cleanup имеют отдельного пользователя: GetBucketLocation/ListBucket только нашего bucket, GetObject/PutObject/DeleteObject только originals/*; создание других bucket запрещено. Nginx не получает секреты БД/S3.
Проверки критериев
go test ./...
go vet ./...
python3 student-tests/verify_attachments.py
python3 student-tests/verify_upload_recovery.py
python3 student-tests/upload_experiment.py
ACTION_SCRIPT=./scripts/restart.sh make test-persistence
ACTION_SCRIPT=./scripts/stop-one.sh make test-failover
./scripts/start-api.sh
В student-tests/ находятся три проверки lab4: вложения и права доступа, восстановление после ошибок загрузки, конкурентные загрузки с измерением памяти. Публичные tests/ проверяют общий API, сохранность данных и отказ API-реплики. start-api.sh восстанавливает реплики после failover; rolling-update.sh остаётся служебной командой последовательного обновления API.
После изменений сервиса дополнительные проверки из student-tests/regression/ запускаются по отдельности:
python3 student-tests/regression/verify_idempotency.py
python3 student-tests/regression/verify_expiry.py
python3 student-tests/regression/verify_dependencies.py
python3 student-tests/regression/verify_unready_backend.py
| Файл | Что проверяет |
|---|---|
| verify_idempotency.py | 12 одновременных повторов через две API создают одно сообщение; изменение тела с прежним ключом даёт 409 |
| verify_expiry.py | Истечение сессии с TTL 2 секунды и возврат обычных настроек |
| verify_dependencies.py | Ответы 503 при отказе Redis/PostgreSQL и восстановление доступа |
| verify_unready_backend.py | Неготовая api1 исключается из балансировки, api2 продолжает чтение и запись |
Нужен запущенный локальный Compose-стенд. Тесты выполняются последовательно: они временно меняют TTL, останавливают хранилища или отключают сеть api1 и восстанавливают настройки в finally. Старые нагрузочные эксперименты и SQL-демонстрация в этот набор не входят.
| Критерий | Сценарий | Доказательство |
|---|---|---|
| Публичный API, checksum, сообщения с файлом, ACL | make test | evidence/lab4-results.md |
| Размер, повреждение, MIME, pixel bomb, filename | verify_attachments.py | evidence/attachments-grade4.json |
| Чужой attachment_id и привязка другого чата | verify_attachments.py | evidence/attachments-grade4.json |
| Upload → остановка загрузившей API → download на другой | verify_attachments.py | evidence/attachments-grade4.json |
| Приватный bucket, отдельные ограниченные credentials | anonymous GET=403 и запрещённое CreateBucket | evidence/attachments-grade4.json |
| Прерванная передача, отказ S3, ошибка после PUT до INSERT | verify_upload_recovery.py | evidence/upload-recovery.json |
| Grace, сохранность fresh/ready, повторная очистка | verify_upload_recovery.py | evidence/upload-recovery.json |
| >=10 одновременных upload, измеренный пик памяти | upload_experiment.py | evidence/upload-memory.json |
| Restart всех хранилищ с прежним токеном и оригиналом | restart.sh + официальный persistence | evidence/persistence.json |
| Отказ API с сохранностью подтверждений и оригинала | официальный failover | evidence/failover.json |
| Повтор bootstrap и запуск на новых volumes | s3-init и отдельный тестовый проект | evidence/lab4-results.md |
Recovery-тест обрывает HTTP-передачу, останавливает S3 и временно добавляет отдельный CHECK к attachments: S3 PUT проходит, а INSERT метаданных отклоняется. CHECK снимается в finally. Выдерживается настоящий grace 120 s. Затем проверяется удаление двух orphan (одного даже без intent), сохранение fresh/ready и повторяемость очистки. Это проверка на учебном стенде.
Эксперимент памяти
Гипотеза: один decoder и ограниченный spool на реплику ограничивают память при конкурентных upload. Генерируется PNG 3000×3000 (9 млн пикселей); 10 клиентов начинают по одному upload через общий барьер. API пересоздаются до опыта для сброса cgroup memory.peak. Прогрев — readiness, отдельного upload-прогрева нет. Фиксируются время, успехи/ошибки, RPS, p50/p95/p99 и kernel memory.peak каждой API, включая её старт и tmpfs. Каждый оригинал затем скачивается и сравнивается побайтно. Реальные значения — в evidence/upload-memory.json.
Это один локальный повтор короткой пачки, а не поиск предельного RPS. RSS не обязан мгновенно падать после запроса из-за Go GC. Чтение memory.peak самим бинарным файлом также входит в cgroup; публичного debug endpoint нет.
Результаты серии 10 upload: 10/10 успехов, 0 ошибок; peak API 88.72/88.86 MiB при лимите 1536 MiB. Отдельно корректная PNG 40 млн пикселей с крайним соотношением сторон принята, пик обслужившей копии 665.25 MiB. Это разные опыты; полные результаты приведены в evidence/lab4-results.md.
Ограничения
Все компоненты на одном Docker-host. Отказ одной API переносится, но MinIO/Redis/PostgreSQL/Nginx и host остаются единичными точками отказа. При отказе S3 — 503 и отрицательная readiness. Не реализованы прямой presigned-upload, worker и варианты изображений, репликация хранилищ и треки на 5.
LB опрашивает readiness с паузой 1 s и таймаутом каждой пробы 2 s: расчётно до 5 s на обнаружение в цикле плюс reload; healthstatus Docker независим и может измениться позже. Краткие ошибки POST до обнаружения допустимы и измеряются; клиент сообщения повторяет тот же ключ.
Источники
Контракт текущего skeleton; официальный MinIO commit, MinIO Go SDK, Admin SDK, Go image, Docker Compose.