# Отчёт - лабораторная 4 - Автор, группа: Голиков Антон, БВТ2303 - Целевая оценка: на 4 (уровни 3+4, без трека 5) - Commit/PR: ветка `solution/BVT2303-Golikov`, PR будет открыт после публикации - Использованные источники, библиотеки и помощь ИИ: - Скелет лабы 4 и материалы курса: COURSE.md, contracts/openapi.json, contracts/README.md, contracts/infrastructure.json - Документация MinIO (mc admin user/policy, bucket policy), S3 API (PutObject/GetObject/ListObjects), pgx v5, goose, gin - Собственная реализация лабы 3: Go 1.26, gin, pgx, goose, Redis, nginx, две API-реплики, X-Instance-Id, Idempotency-Key - ИИ (ChatGPT) использован для структуры отчёта, вычитки формулировок и подсказок по рутинным местам (политика MinIO, healthcheck). Весь код, конфигурация, эксперименты и финальные тексты проверены и объясняются автором на защите. ## Запуск из чистого clone Prerequisites: - Docker Desktop 4.30+ (WSL2 backend) или Docker Engine с Compose v2.20+ - Go 1.26+ (для локальной сборки без Docker; в Docker-варианте не нужен) - Python 3.9+ (для публичных тестов из scaffold) - git, make Шаги запуска: 1. Клонировать fork и перейти на ветку solution: git clone https://gitea.privcloud.tech/Maximillan_Mercer/mtusi2026lab4-fork.git cd mtusi2026lab4 git checkout solution/BVT2303-Golikov 2. Создать локальные secrets. Значения генерируются оператором, в Git не попадают. Добавились четыре секрета для S3 (в дополнение к трём из lab2-3): mkdir -p secrets # PostgreSQL (как в lab2-3) PW="$(openssl rand -hex 16)" printf "%s" "$PW" > secrets/postgres_password printf "%s" "postgres://messenger:$PW@postgres:5432/messenger?sslmode=disable" \ > secrets/database_url printf "%s" "redis://redis:6379/0" > secrets/cache_url # MinIO root (только для mc-init, API их не видит) printf "%s" "messenger-minio-root" > secrets/minio_root_user openssl rand -base64 32 | tr -d '\r\n' > secrets/minio_root_password # S3 API-креды (для сервиса api) printf "%s" "messenger-api" > secrets/s3_access_key_id openssl rand -hex 32 > secrets/s3_secret_access_key chmod 600 secrets/* 3. Создать .env из .env.example: cp .env.example .env Переменные и дефолты, которые изменились относительно lab3: - S3_ENDPOINT=http://minio:9000 - S3_BUCKET=messenger-attachments - S3_REGION=us-east-1 - S3_USE_SSL=false - S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id - S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key - MAX_UPLOAD_BYTES=10485760 (10 MiB) - MAX_IMAGE_PIXELS=40000000 (40 млн) - RECONCILER_ENABLED=true - RECONCILER_INTERVAL_SECONDS=300 - RECONCILER_GRACE_SECONDS=3600 (1 час) - MINIO_ROOT_USER=messenger-minio-root - MINIO_CPUS=0.5, MINIO_MEMORY=512M Остальные переменные (SESSION_STORE=redis, SESSION_TTL_SECONDS, IDEMPOTENCY_TTL_SECONDS, SHUTDOWN_DRAIN_SECONDS, лимиты CPU/RAM, API_REPLICAS=2, LB_PORT=8080) без изменений от lab3. 4. Собрать образ API и запустить стек: docker compose build api docker compose up -d 5. Дождаться, пока mc-init создаст bucket и API-пользователя, и применились миграции 0001–0004: docker compose logs migrate # ожидать: goose: successfully migrated database to version: 4 # при первом запуске: OK 0001..0004 docker compose logs mc-init # ожидать: minio bootstrap ok: bucket=messenger-attachments user=messenger-api curl -sS http://localhost:8080/health/ready # ожидать: {"status":"ok"} Сервис mc-init идемпотентен: повторный `docker compose run --rm mc-init` не падает и не дублирует bucket или policy. API использует отдельные S3-креды (messenger-api, policy только на messenger-attachments/*); root-креды MinIO видят только minio и mc-init. 6. Прогнать публичный smoke и проверки от scaffold: PYTHONUTF8=1 make check PYTHONUTF8=1 make test 7. Проверки сохранности и отказа (требуют scripts/restart.sh и scripts/stop-one.sh из lab3, они перенесены): PYTHONUTF8=1 make test-persistence ACTION_SCRIPT=scripts/restart.sh PYTHONUTF8=1 make test-failover ACTION_SCRIPT=scripts/stop-one.sh Версии образов (закреплены в compose.yaml): - pgsty/silo:RELEASE.2026-09-16T00-00-00Z — drop-in MinIO fork. Оригинальный minio/minio заархивирован в 2025-м, официальные community-образы сняты с Docker Hub; pgsty/silo сохраняет S3 API, mc и healthcheck без изменений. - postgres:16.4-alpine - redis:7.4-alpine - nginx:1.27.4-alpine - mtusi-messenger-api:lab3 — собственный образ, собирается из Dockerfile Безопасная остановка: docker compose stop # остановить контейнеры, volumes сохранить docker compose down # удалить контейнеры и сеть, volumes сохранить Остановка с удалением учебных данных (необратимо, удалит все volumes): docker compose down -v Отдельно про .env и secrets: оба пути в .gitignore, в репозиторий не попадают. Значения паролей синтетические, для локального стенда. ## Архитектура и решения Схема: client (curl / python / smoke) | v nginx LB (:8080) единственная публичная точка | +-> api-1 :8080 реплика 1 +-> api-2 :8080 реплика 2 | +-> postgres :5432 users, chats, chat_members, messages, | sessions, idempotency_keys, attachments, | message_attachments +-> redis :6379 сессии (SESSION_STORE=redis) +-> minio :9000 S3, приватный bucket messenger-attachments (порты наружу не публикуются) | +-- mc-init (одноразовый) bootstrap: bucket + policy + API-user +-- migrate (одноразовый) goose up Источник истины - PostgreSQL для метаданных и S3 для бинарных байтов. Разделение намеренное: байты не хранятся в БД (не BLOB, не локальный каталог api), только в приватном bucket; в Postgres - object_key, sha256, content_type, size_bytes, status, привязка к chat_id и к message_attachments. Через S3 любая API-реплика читает любую вложенность одинаково; локальный volume API не годится, потому что файл лежит только на одной реплике и теряется при её остановке - это критерий README уровня 3 "Upload → остановка обслужившей API → download через другую возвращает тот же файл". Сессии - в Redis (без изменений от lab2-3). Без sticky session на LB любая реплика видит любую сессию. Транзакционные границы: - Создание чата - одна транзакция в Postgres (chats + chat_members). - Идемпотентная отправка сообщения - одна транзакция: слот в idempotency_keys, проверка и линковка attachments, INSERT в messages, INSERT в message_attachments. Либо всё, либо ничего. - Загрузка вложения - две точки сохранения без общей транзакции (S3 и Postgres - разные системы). Последовательность: INSERT attachments (status='pending', object_key, sha256) → COMMIT PutObject в S3 → OK/FAIL UPDATE attachments status='ready' → COMMIT Это ключевая граница lab4. Ниже - как каждый отказ на этой границе компенсируется. - Регистрация - один INSERT с UNIQUE-индексом на username (23505 → 409 через mapError). Компенсация и сверка (уровень 4): - Отказ между INSERT и PutObject. Строка pending осталась, объекта в S3 нет. Handler ловит ошибку PutObject и сразу вызывает MarkFailed(id, "upload_failed") - компенсация в том же запросе, без ожидания reconciler. - Отказ между PutObject и UPDATE status='ready'. Объект в S3 есть, строка pending. Это и есть "вечный неучтённый объект", если ничего не делать. Закрывает reconciler: ListStalePending(now - grace) → Delete(object_key) → DeletePending(id). Grace 1 час: свежие pending (реальные upload'ы) не трогаются, только застрявшие. - Обратный случай: PutObject прошёл, INSERT в Postgres упал. Объект в S3 есть, строки в БД нет - orphan. Закрывает reconciler: List(S3) → отфильтровать LastModified < now - grace → ExistingKeys(DB) → Delete тех, которых нет в БД. Grace 1 час защищает свежий Put, чей INSERT ещё не закоммичен. - Reconciler запускается во всех репликах, но использует pg_try_advisory_lock: одна реплика на tick берёт session-level advisory lock, остальные пропускают tick. Postgres автоматически освобождает лок, если процесс упал. Отдельные S3-креды и приватность bucket: - Root-креды MinIO (minio_root_user/minio_root_password) видят только minio и mc-init. API-контейнер их не получает. - API использует messenger-api с policy только на messenger-attachments (GetObject, PutObject, DeleteObject на bucket/*, ListBucket на bucket). Создание/удаление bucket, policy, пользователей недоступны. - Bucket приватный: без подписи GET возвращает 403. Проверяется в evidence/s3-private.txt. - MINIO_BROWSER=off: административная консоль не слушается. Порты 9000/9001 не публикуются на хост (только внутри internal-сети). Что перенесено из lab3 без изменений: - Схема БД: users, chats, chat_members, messages, sessions - idempotency_keys с TTL 24 часа, Idempotency-Key обязателен - X-Instance-Id в каждом ответе API (os.Hostname()) - Миграции goose, отдельный процесс /server migrate - Graceful drain на SIGTERM, atomic ready-флаг, SHUTDOWN_DRAIN_SECONDS - CPU/RAM лимиты на api, postgres, redis через deploy.resources - nginx LB перед двумя репликами, upstream keepalive - Горизонтальное масштабирование: две реплики, общие сессии в Redis Что добавлено/изменено в lab4: 1. Отдельный сервис minio (pgsty/silo), persistent volume minio_data. 2. Одноразовый сервис mc-init: создаёт bucket, policy, API-user. Идемпотентен. 3. Миграция 0003: таблицы attachments и message_attachments, индексы, ограничения (status, size, sha256, content_type, filename). 4. Миграция 0004: ослаблен CHECK messages_text_not_blank - пустой текст разрешён при наличии вложений (lab4 anyOf), но whitespace-only по-прежнему запрещён. 5. Три endpoint: POST /chats/{chat_id}/attachments (raw bytes PNG/JPEG, max 10 MiB, max 40M пикселей), GET /attachments/{id} и GET /attachments/{id}/content (без redirect, только участникам чата). 6. POST /messages принимает attachment_ids (0-10), все вложения должны принадлежать этому чату и быть ready; anyOf text или attachments. 7. RequestHash расширен: sha256(text) без attachments (обратная совместимость с lab3), sha256(text + 0x00 + ids) с attachments. 8. Reconciler в API, pg advisory lock, две задачи (stale pending, orphan objects), grace 1 час. 9. Healthcheck /health/ready пингует S3 (BucketExists). 10. nginx client_max_body_size=12m (10 MiB upload + запас на 11 MiB negative-тест, чтобы 413 шёл от API с X-Request-Id, а не от nginx). Соответствие переменных .env.example реальной конфигурации (новое в lab4): - S3_ENDPOINT, S3_BUCKET, S3_REGION, S3_USE_SSL - читаются в config.Load, идут в s3.Config. Для внутреннего MinIO http://minio:9000, SSL=false. - S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE - secrets в /run/secrets, читаются через readSecretOptional. - MAX_UPLOAD_BYTES - идёт в AttachmentService (io.LimitReader body = maxBytes+1, 413 при превышении). - MAX_IMAGE_PIXELS - идёт в AttachmentService (image.DecodeConfig, 413 при W*H > maxPixels). - RECONCILER_ENABLED, RECONCILER_INTERVAL_SECONDS, RECONCILER_GRACE_SECONDS - читаются в config.Load, идут в service.Reconciler. - MINIO_ROOT_USER - только для minio и mc-init, не попадает в api. ## Доказательства критериев Все evidence-файлы лежат в `evidence/`, содержат только обезличенные результаты и не включают токены, пароли, signed URL или приватные ключи. Уровень 3: | Критерий | Команда | Наблюдаемый результат | Файл | | --- | --- | --- | --- | | Публичный smoke | `PYTHONUTF8=1 make test` | PASS: lab4 public API scenario | evidence/smoke.txt | | >= 2 API-реплики за LB | `docker compose ps` | api-1 и api-2 Up (healthy), LB публикует :8080 | evidence/container-state.txt | | Остановка одной реплики <= 10 с | `make test-failover` | first_recovery_seconds 5.48 | evidence/failover-1.txt | | Поочерёдная остановка каждой (автотест) | `make test-failover` дважды | recovery 5.48 и 5.34, дублей нет | evidence/failover-1.txt, failover-2.txt | | Поочерёдная остановка каждой (ручной) | `docker stop api-1`, потом `api-2` | после остановки каждой отвечает ровно один X-Instance-Id | evidence/failover-manual.txt | | Идемпотентность POST | smoke + failover (replay с тем же ключом) | тот же ответ, дублей нет | evidence/smoke.txt, failover-*.txt | | Persistence после restart | `make test-persistence` | PASS, StartedAt всех контейнеров обновился | evidence/persistence.txt | | S3-сервер в общем стенде, приватный bucket | `docker compose ps`, `mc ls local` | minio Up (healthy), bucket messenger-attachments (0 B) | evidence/container-state.txt | | Метаданные в Postgres, байты в S3 | `psql \d attachments`, `mc ls` | таблица attachments; object_key в S3 | evidence/s3-private.txt, container-state.txt | | POST вложения возвращает 201 ready | smoke, test_attachments | 201 ready, sha256/size совпадают | evidence/attachments-negative.txt | | Download побайтно, sha256 совпадает | smoke | download.bytes == original | evidence/smoke.txt | | Чужой участник получает 404 на метаданные и байты | test_attachments | 404 без 403 | evidence/attachments-negative.txt | | Прямой GET S3 без подписи -> 403 | `wget http://minio:9000/messenger-attachments/` | HTTP/1.1 403 Forbidden | evidence/s3-private.txt | | Upload -> остановка обслужившей API -> download через другую | failover (файл приложен до отказа) | download через другую реплику == оригинал | evidence/failover-1.txt, failover-2.txt | | Restart с сохранением volumes сохраняет оригинал | persistence | PASS, download == исходный файл | evidence/persistence.txt | | S3 недоступен -> 503 без утечек | `docker compose stop minio` | /health/ready 503 unavailable; LB снимает реплики | evidence/s3-down.txt | | Не более 10 MiB, не более 40M пикселей | test_attachments | 11 MiB -> 413 payload_too_large | evidence/attachments-negative.txt | | MIME по содержимому | test_attachments | PNG-байты с Content-Type image/jpeg -> 201, content_type image/png | evidence/attachments-negative.txt | | Опасные filename отклоняются | test_attachments | /, \\, NUL -> 400 invalid_request | evidence/attachments-negative.txt | Уровень 4: | Критерий | Команда | Наблюдаемый результат | Файл | | --- | --- | --- | --- | | Тест слишком большого файла | test_attachments (11 MiB) | 413 payload_too_large, не 500 | evidence/attachments-negative.txt | | Тест повреждённого изображения | test_attachments (signature без IHDR) | 415 unsupported_media_type | evidence/attachments-negative.txt | | Тест подмены MIME | test_attachments (PNG как image/jpeg) | 201, content_type определён по magic bytes | evidence/attachments-negative.txt | | Тест чужого attachment_id | test_attachments (eve -> metadata и bytes) | 404 без утечки существования | evidence/attachments-negative.txt | | Тест attachment_id из другого чата | test_attachments (message с чужим id) | 404 not_found | evidence/attachments-negative.txt | | Failed-вложение в message | test_attachments | 409 conflict (см. Contract) | evidence/attachments-negative.txt | | Пользовательская ошибка не превращается в 500 | test_attachments | все отказы 4xx; ни одна не 500 | evidence/attachments-negative.txt | | Отказ S3/БД не оставляет вечных неучтённых объектов | reconciler с ускоренными интервалами | stale pending и orphan-объект удалены; pending_left=0 | evidence/reconciler.txt | | Документированный grace period | README/REPORT, плюс evidence | ListStalePending(now - 1h), orphan только старше 1h | этот отчёт, evidence/reconciler.txt | | Лимиты до неограниченного чтения | код + memory test | io.LimitReader(maxBytes+1), image.DecodeConfig до декодирования | student-tests/test_memory.py | | >=10 одновременных загрузок с измерением пика RAM | test_memory.py + cgroups v2 | пик 141 MiB на каждой реплике <= 256 MiB лимита | evidence/memory-10x10mb.txt | | Bucket bootstrap идемпотентен | `docker compose run --rm mc-init` дважды | exit 0, "no such bucket / user exists" не срабатывает | этот отчёт | | API использует отдельные S3-креды с ограниченными правами | `mc admin user list`, policy | только messenger-api, GetObject/PutObject/DeleteObject на bucket/* | evidence/s3-private.txt | | Административная консоль не открыта в общей сети | `docker compose port minio 9001`, `printenv MINIO_BROWSER` | порт не проброшен, браузер off | evidence/s3-private.txt | | Проверка private bucket вне API | `wget http://minio:9000/messenger-attachments/` | 403 Forbidden без подписи | evidence/s3-private.txt | ## Эксперименты и отказы Общая среда: Windows 10, Docker Desktop (WSL2 backend), одна физическая машина, на которой работают и весь стенд, и клиенты тестов. Все пользователи и изображения синтетические. Версии: PostgreSQL 16.4, Redis 7.4, nginx 1.27.4, pgsty/silo RELEASE.2026-09-16T00-00-00Z (MinIO fork), Go 1.26. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления, потеря данных | | --- | --- | --- | --- | | Остановка одной API-реплики | writes продолжаются через LB, без дублей | recovery 5.48 / 5.34 с, повтор с тем же ключом даёт то же сообщение | 5–6 с, потерь нет | | Поочерёдная остановка api-1 и api-2 вручную | каждый раз обслуживает оставшаяся | после stop api-1 отвечает один X-Instance-Id, после stop api-2 другой | <20 с суммарно, потерь нет | | Перезапуск всего стека (`scripts/restart.sh`) | данные, сессии и файлы сохранены | StartedAt всех контейнеров обновился, PASS, прежний токен работает | в пределах бюджета теста, потерь нет | | Остановка minio | /health/ready 503, LB снимает реплики; после start всё возвращается | ровно так; после start оба X-Instance-Id вернулись | ~15–20 с, потерь нет | | Stale pending (2 минуты) при grace 30 с (для теста) | reconciler удаляет строку и объект | "reconciler: sweep done pending=1 orphans=0", pending_left=0 | на следующем tick (≤10 с в тестовом прогоне) | | Orphan-объект в S3 старше grace | reconciler удаляет объект | лог orphans=N, объект удалён | аналогично | | 10 параллельных upload по 10 MiB | RAM каждой реплики в пределах 256 MiB | 10 upload за 1.79 с, peak 138 / 141.5 MiB | пик не превышен, OOM нет | Пояснения: - Ошибки в окне переключения nginx при остановке API-реплики - нормальны и разрешены README уровня 3 ("краткие ошибки во время обнаружения отказа измеряются и допустимы"). После 5 секунд writes продолжаются. - Reconciler в тесте запускался с `RECONCILER_INTERVAL_SECONDS=10` и `RECONCILER_GRACE_SECONDS=30`, чтобы уложиться в минуту. В дефолтной конфигурации интервал 5 минут, grace 1 час - для реальной работы это безопаснее, потому что не трогает свежие upload'ы и только что загруженные объекты, чей INSERT ещё в полёте. - Пик RAM 141 MiB на реплике - не от upload'ов, а от Argon2id при регистрации пользователей (6 операций × 64 MiB malloc при bootstrap). Upload'ы добавили только +1..4 MiB к peak, потому что Go heap уже раздут GC и `io.LimitReader` ограничивает каждый upload 10 MiB. Худший сценарий 141 + 100 = 240 MiB < 256 MiB - укладывается с запасом. ## Ограничения и следующие шаги Что выдерживает: - Отказ одной API-реплики при живом S3 и Postgres. - Перезапуск API и всех хранилищ (Postgres, Redis, MinIO) с сохранением volumes - данные, сессии и файлы. - Отказ S3: /health/ready 503 без утечек, LB снимает реплики, после восстановления всё возвращается. - Отказ между INSERT и PutObject: компенсация MarkFailed в том же запросе, без ожидания reconciler. - Отказ между PutObject и UPDATE ready: reconciler через grace period (1 час) удаляет застрявшие pending и объект. - Orphan-объекты (Put прошёл, INSERT упал): reconciler через grace period удаляет объекты в S3, которых нет в БД. - 10 параллельных upload по 10 MiB - peak RAM каждой реплики укладывается в лимит 256 MiB. Что не выдерживает: - Отказ узла. Всё работает на одном хосте, потеря хоста = потеря системы. PostgreSQL и MinIO без репликации, nginx LB без резерва. - Отказ MinIO на длительное время (например, потеря volume): файлы не восстановятся, потому что второй копии нет. Метаданные в Postgres остаются, скачивание отдаёт 404/503. - Grace period reconciler (1 час) защищает от случайного удаления живых загрузок, но не является транзакционной гарантией. В редком случае ровно на границе grace и очень медленной загрузки возможен false-positive, теоретически удаление свежего объекта. Вероятность пренебрежимо мала для учебного стенда, но в реальной работе grace стоит увеличивать до нескольких часов и добавлять heartbeat-обновление updated_at у активных загрузок. - Медленная сеть к S3: reconciler обходит ListObjects и Delete по одному, что на больших бакетах станет дорого. На учебном бакете это не проявляется. Не реализовано в этой работе: - Трек 5 (presigned upload или повторяемый reconciler с dry-run и инъекцией ошибок) - целевая оценка 4, трек 5 не заявлен. - Background worker и thumbnail (это уже lab5). - Argon2id вместо текущего KDF в lab7, TLS/mTLS, OpenBao. - HTTPS. По контракту до lab7 достаточно HTTP для локального стенда. - Rate limiting: схема допускает `429`, реализация не требуется. Учебные упрощения: - MinIO fork pgsty/silo: `minio/minio` заархивирован, официальных community-образов с 2025 нет. pgsty/silo - drop-in замена с тем же S3 API и mc; версия образа закреплена. - Роль reconciler в одной реплике через pg advisory lock. Не является распределённой HA-сверкой; при потере хоста обе реплики и reconciler исчезают. - БД и S3 в одном экземпляре, оба на том же хосте, что и API. Для уровня 3-4 достаточно, для продакшена нужны репликация БД, версионирование S3, отдельный хост под reconciler/worker. Подтверждённые улучшения (сводка по lab4): - Метаданные и бинарные данные разнесены: Postgres - источник истины для структуры, S3 - источник истины для байтов. Файл в локальном volume API не равен объектному хранилищу, потому что при остановке реплики файл недоступен через другую; S3 решает это. - Grace period reconciler (1 час) не трогает живые загрузки и свежие Put-объекты: stale pending и orphans обрабатываются только после истечения срока. - Отдельные S3-креды с ограниченной policy плюс приватный bucket плюс MINIO_BROWSER=off: административный доступ к S3 полностью изолирован от API. Проверяется в evidence/s3-private.txt. - nginx client_max_body_size=12m: иначе nginx режет на 1 MiB по умолчанию, 413 летит без X-Request-Id (это ответ LB, а не API), и публичный тест падает "missing X-Request-Id". - Миграция 0004 ослабляет CHECK messages_text_not_blank до `text !~ '^[[:space:]]+$'`: `text=""` с attachments валиден по lab4 anyOf, а whitespace-only по-прежнему запрещён на уровне БД. Следующий шаг для полной картины: увеличить grace period reconciler до нескольких часов и добавить heartbeat от активных загрузок (обновление updated_at), чтобы устранить теоретический false-positive на границе grace. Для production-варианта - вынести reconciler в отдельный процесс/реплику и добавить репликацию БД и S3.