# Отчёт — лабораторная 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](infrastructure/minio/Dockerfile): сервер `RELEASE.2025-10-15T17-29-55Z`, клиент `RELEASE.2025-08-13T08-35-41Z`. Базовые образы закреплены digest. ```sh 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: ```sh docker compose --env-file .env down ``` Намеренное удаление всех учебных данных выполняется только явно: ```sh 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`, а не к потере готового оригинала. Команды оператора: ```sh 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](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](tests/attachment_boundaries.py) | | Failover API | `make test-failover` с указанными в evidence env | 142 успешных записи, 0 ошибок, recovery 2.771 s; файл читается другой репликой | [evidence/lab4-results.md](evidence/lab4-results.md) | | Restart и volumes | `make test-persistence` | Сессия, метаданные и bytes пережили restart PostgreSQL/Redis/MinIO/API/frontend/HAProxy | [scripts/restart.sh](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](internal/application/attachments_test.go) | | Неоднозначный DB COMMIT | `go test ./internal/application -count=1` | Потеря ответа после commit восстанавливается readback; при одновременном read outage ready metadata сохраняет оригинал | [internal/application/attachments_test.go](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](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](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](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](tests/reconcile_integration.py) | | Стоимость обхода | `make test-reconcile-scale` | 100 objects: 9 ms; 1,000 objects: 38 ms core duration | [tests/reconcile_scale.py](tests/reconcile_scale.py) | | Static/race gates | `go test -race ./...`; `go vet ./...`; `make check`; `git diff --check` | PASS | [evidence/lab4-results.md](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 на лету.