Files
mtusi2026lab4-fork/REPORT.md
T

31 KiB
Raw Blame History

Отчёт - лабораторная 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/<key> 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/<key> 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.