16 KiB
Отчёт — лабораторная 4
- Автор, группа: Чурилин, БВТ2301
- Целевая оценка: 5, выбран трек 2 — согласованность PostgreSQL и S3.
- Commit/PR: TODO после публикации.
- Использованные источники и библиотеки: Go standard library,
pgx/v5,minio-go/v7, официальный исходный код MinIO иmc, Redis Go client. OpenAI Codex использовался для анализа контракта, проектирования, реализации и тестов; все утверждения ниже проверены перечисленными воспроизводимыми командами.
Запуск из чистого clone
Prerequisites: Docker с Compose v2, GNU Make, Python 3.9+, OpenSSL. Локально проверено в WSL2. MinIO и mc собираются из официальных Go-модулей в infrastructure/minio/Dockerfile: сервер RELEASE.2025-10-15T17-29-55Z, клиент RELEASE.2025-08-13T08-35-41Z. Базовые образы закреплены digest.
cp .env.example .env
make init-secrets
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
BASE_URL=http://127.0.0.1:8080 make test
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
make init-secrets создаёт недостающие файлы с mode 600 и никогда не перезаписывает существующие значения. Секреты находятся в игнорируемом каталоге secrets/ и не передаются через переменные окружения контейнера. Если 8080 занят, задаётся PUBLIC_PORT, например PUBLIC_PORT=18080; внутренний APP_INTERNAL_PORT=8080 от него не зависит.
Безопасная остановка сохраняет named volumes:
docker compose --env-file .env down
Намеренное удаление всех учебных данных выполняется только явно:
docker compose --env-file .env down -v
Архитектура и решения
Путь запроса: клиент → HAProxy → две API-реплики → PostgreSQL (источник истины метаданных/сессий) + приватный MinIO bucket (байты); Redis остаётся восстанавливаемым кешем чатов. У каждой API-реплики нет постоянного каталога оригиналов. Во время синхронного upload тело ограниченно копируется в файл OS temp, файл имеет случайное имя, удаляется в defer и нужен только для двукратной проверки/потокового S3 PUT.
Из lab3 сохранены два API-инстанса, HAProxy, PostgreSQL, Redis fallback, bearer-сессии, idempotency сообщений, курсоры, graceful shutdown и persistence/failover hooks. В lab4 добавлены:
Attachmentсо статусамиpending/ready/failed, SHA-256, истинным MIME, размером и размерами изображения;- таблицы
attachmentsиmessage_attachments, same-chat foreign keys и deferred constraint «текст или вложение»; attachment_idsво всех слоях Message без нарушения старого JSON ([]по умолчанию);- binary
POST, metadataGETи авторизованный streamingGET /contentбез redirect; - общий MinIO volume, idempotent bootstrap приватного bucket и отдельный API user с минимальной policy;
- readiness, зависящий от PostgreSQL и MinIO;
- one-shot reconciler с dry-run по умолчанию,
--apply, grace period и условными DB updates.
Upload возвращает 201 ready только после последовательности: полное ограниченное чтение → проверка MIME/PNG/JPEG/пикселей и SHA-256 → insert pending → успешный S3 PUT → update ready. Ошибка PUT удаляет возможный объект и фиксирует failed. Ошибка ответа на финальный DB update считается неоднозначной: update мог уже закоммититься, поэтому объект не удаляется. API делает best-effort readback и либо восстанавливает успешный 201, либо возвращает 503, сохранив metadata+object для reconciler. Это исключает состояние ready без оригинала при потере ответа PostgreSQL.
Лимиты применяются до неограниченной работы: body читается через LimitReader(10 MiB + 1), DecodeConfig проверяет максимум 40 млн пикселей до полного Decode, а полный Decode проверяет поток/CRC/IDAT/SOS до S3 PUT. Filename не участвует в object key и проверяется на valid UTF-8/blank/path/C0+C1 control characters. Object key формируется сервером как attachments/{chat_id}/{attachment_id}/original. На реплику допускаются не более четырёх upload pipeline и одного полного decode одновременно; GOMEMLIMIT=220MiB ниже container limit 256 MiB. S3 operation timeout — 5 s, HTTP read/write timeout — 15 s, HAProxy server/client timeout — 30 s, DB query timeout задаётся конфигурацией. Компенсация сначала получает отдельный 1 s budget для DB transition и лишь затем отдельный 1 s budget для best-effort S3 delete.
Публичный /health/ready проверяет PostgreSQL и MinIO и возвращает контрактный JSON 503, если зависимость недоступна. HAProxy использует отдельный внутренний /health/lb, отражающий жизнеспособность/drain процесса, поэтому при общем отказе MinIO запросы не заменяются generic HTML-ошибкой балансировщика, а доходят до API и получают согласованный 503 unavailable.
Соответствие ключевых переменных: PUBLIC_PORT — host port HAProxy; APP_INTERNAL_PORT — порт API в сети Compose; DATABASE_URL_FILE, CURSOR_SIGNING_KEY_FILE, S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE — Docker secrets; S3_ENDPOINT=http://minio:9000; S3_BUCKET=messenger-attachments; S3_OPERATION_TIMEOUT=5s.
Механизм согласованности и трек 5
Гипотеза: периодический inventory PostgreSQL и MinIO с консервативным grace period способен повторяемо исправлять безопасные orphan/missing состояния, не удаляя свежие объекты и вложения, уже связанные с сообщениями.
Reconciler сравнивает все attachments/ objects с метаданными:
- старый object без metadata удаляется только в apply;
- старый
pendingочищает object и условно становитсяfailed; - старый
readyбез object условно становитсяfailed, только если не используется сообщением; - object у старого
failedудаляется, только если запись не используется; - свежие записи/objects игнорируются, а referenced missing помечается
manual_repair_requiredбез мутации; - SQL update берёт row lock, затем отдельным statement на свежем READ COMMITTED snapshot повторно проверяет status, cutoff и отсутствие ссылки; concurrent message/reconciler race либо создаёт ссылку, либо переводит attachment в failed, но не оба состояния одновременно;
- object stale-pending удаляется только после успешного условного DB transition, поэтому проигранная гонка приводит к
skipped_concurrent_change, а не к потере готового оригинала.
Команды оператора:
make reconcile-dry-run RECONCILE_GRACE=15m
# Просмотреть JSON; затем при согласии:
make reconcile-apply RECONCILE_GRACE=15m
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство |
|---|---|---|---|
| Публичный smoke | BASE_URL=http://127.0.0.1:18080 make test |
PASS: upload/message/download/checksum/outsider 404 | evidence/lab4-results.md |
| Границы/полная декодировка | make test-attachment-boundaries |
Ровно 10 MiB и 40 млн пикселей приняты; truncated/corrupt-after-64-KiB отклонены 415; whitespace/C1 filename — 400 | tests/attachment_boundaries.py |
| Failover API | make test-failover с указанными в evidence env |
142 успешных записи, 0 ошибок, recovery 2.771 s; файл читается другой репликой | evidence/lab4-results.md |
| Restart и volumes | make test-persistence |
Сессия, метаданные и bytes пережили restart PostgreSQL/Redis/MinIO/API/frontend/HAProxy | scripts/restart.sh |
| Файловые негативные тесты | go test ./... |
oversized bytes/pixels, invalid IDAT, truncated PNG/JPEG, corruption after 64 KiB, MIME substitution, unsafe filename, interrupted body, foreign attachment/chat | internal/application/attachments_test.go |
| Неоднозначный DB COMMIT | go test ./internal/application -count=1 |
Потеря ответа после commit восстанавливается readback; при одновременном read outage ready metadata сохраняет оригинал | internal/application/attachments_test.go |
| Реальный отказ MinIO | make test-storage-outage |
readiness 503 за 2.004 s, upload 503 за 6.016 s; после recovery прежний original неизменен | tests/storage_outage.py |
| RAM при concurrency ≥10 | make test-attachment-memory |
12 × 6,293,028 B, 12/12 success; пики 31,216,107 и 26,214,400 B | tests/attachment_memory.py |
| Private bucket / API policy | make test-minio-policy |
Root secrets/env отсутствуют в API; limited user не создаёт bucket; anonymous GET запрещён | tests/minio_policy.sh |
| Reconciler dry-run/apply/repeat | make test-reconcile |
4 issues; 2 objects deleted; 2 metadata failed; repeat 0 mutations; referenced защищён | tests/reconcile_integration.py |
| Стоимость обхода | make test-reconcile-scale |
100 objects: 9 ms; 1,000 objects: 38 ms core duration | tests/reconcile_scale.py |
| Static/race gates | go test -race ./...; go vet ./...; make check; git diff --check |
PASS | evidence/lab4-results.md |
Эксперименты и отказы
Memory experiment: один прогон, 12 concurrent uploads, каждый PNG 2048×1024 и 6,293,028 bytes; суммарно 75,516,336 bytes. HAProxy распределил запросы по двум репликам. Docker stats опрашивался во время прогона. 12/12 завершились за 0.599 s, наблюдаемые пики — 29.8 и 25.0 MiB, существенно ниже container limit 256 MiB. После измерения отдельный chat prefix и синтетические DB rows удалены.
Reconciler integration: в отдельном namespace созданы old orphan object, old pending metadata+object, unreferenced ready metadata без object и referenced ready metadata без object. Dry-run нашёл четыре состояния и не мутировал данные. Apply удалил два objects и перевёл две записи в failed. Повторный apply сделал ноль мутаций; referenced missing остался ручной задачей. Синтетические данные удалены в finally.
Traversal experiment использовал один и тот же стенд после прогрева, один прогон на размер, отдельный prefix и однобайтовые objects. 100 injected orphans: 109 objects total, 9 ms core и 1,978 ms с запуском one-shot container. 1,000: 1,009 total, 38 ms core и 2,019 ms end-to-end. Это подтверждает повторяемость методики и ожидаемую близкую к линейной стоимость лишь на малом локальном масштабе.
| Воздействие | Ожидание | Наблюдение | Потеря данных |
|---|---|---|---|
| Stop одной API-реплики | Вторая продолжает запись/чтение общего файла | recovery 2.771 s, 142 writes, 0 errors | Нет |
| Restart общего стенда | Named volumes сохраняют DB и S3 | persistence PASS | Нет |
| S3 PUT error | 503, metadata failed, object отсутствует | Unit injection PASS | Нет ready-данных |
| MinIO недоступен | readiness/upload дают JSON 503 до API/LB timeout | 2.004 s / 6.016 s, реальный stop/recovery PASS | Старый original неизменен |
| DB finalize response потерян после COMMIT | Readback возвращает ready; при DB outage object не удаляется | Два unit fault-теста PASS | Ready не остаётся без original |
| Orphan/missing/stale состояния | Dry-run, безопасный apply, repeat | Integration PASS | Referenced missing не изменён |
Ограничения и следующие шаги
- Inventory materializes metadata и object list в RAM; для большого bucket нужны pagination/checkpoints и пакетная выдача issues.
- Один reconciler предполагается запускать оператором; перед scheduler нужны PostgreSQL advisory lock/lease и метрики длительности/ошибок.
referenced_missing_objectнамеренно не чинится автоматически: требуется восстановление bytes из backup или операторское решение.- Один-node MinIO и локальные измерения не доказывают HA самого object storage; это учебный стенд.
- Experiment содержит по одному измерению на размер без статистических повторов; для production нужны warm-up, серии, p50/p95/p99, CPU/IO и существенно больший inventory.
- Оригинал проверяется SHA-256 при upload и клиентом в smoke; каждый download не пересчитывает hash на лету.