Files
mtusi2026lab4/REPORT.md
T
2026-10-30 12:30:59 +03:00

16 KiB
Raw Blame History

Отчёт — лабораторная 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, metadata GET и авторизованный streaming GET /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 на лету.