Files
mtusi2026lab4/REPORT.md
T

30 KiB
Raw Blame History

Отчёт — лабораторная 4

  • Автор, группа: Вейнмайер Андрей Андреевич, БВТ2303
  • Целевая оценка: 5 (уровни 3, 4 и трек 2 «Согласованность двух хранилищ»)
  • Commit/PR: ветка solution/bvt2303-weinmaier в https://gitea.privcloud.tech/WeinmaierAndrew/mtusi2026lab4, PR в mtusi2026/mtusi2026lab4
  • Основа: собственная lab3 (PR mtusi2026/mtusi2026lab3#43) — балансировка, идемпотентность, отказ реплики
  • Использованные источники:
    • Контракт: contracts/openapi.json, contracts/README.md (разделы «Вложения»)
    • Библиотеки: github.com/minio/minio-go/v7, github.com/jackc/pgx/v5, github.com/redis/go-redis/v9, golang.org/x/crypto/argon2
    • Спецификации: PNG (ISO/IEC 15948: chunks, CRC, Adam7), JPEG (ITU T.81: маркеры, SOF, SOS, EOI)
    • Документация: MinIO (mc admin policy, mc anonymous), AWS S3 ListObjectsV2, Docker Compose
    • Помощь ИИ: ИИ-ассистент использовался при реализации и отладке; все результаты ниже — реальные прогоны, ссылки на них приведены.

Запуск из чистого clone

Версии

Компонент Образ
API, reconciler golang:1.26-alpine → alpine:3.20, оба закреплены по digest в Dockerfile; один образ, два бинарника (/app/api, /app/reconcile)
S3 bitnamilegacy/minio:2025.4.22@sha256:50cec18a… — MinIO RELEASE.2025-04-22T22-12-26Z
Bootstrap S3 bitnamilegacy/minio-client:2025.4.16@sha256:8a86e441… — mc RELEASE.2025-04-16
LB / БД / сессии haproxy:3.0.5-alpine, postgres:16.4-alpine, redis:7.4.1-alpine (digest в evidence/images.txt)
Миграции migrate/migrate:v4.17.0

Почему Bitnami. Официальные образы minio/minio и minio/mc в ходе работы оказались недоступны и на Docker Hub (repository does not exist), и на quay.io (unauthorized) — проверено отдельным прогоном на GitHub runner. Использована сборка Bitnami того же релиза MinIO, закреплённая по digest. Запасной вариант из задания, если и она пропадёт, — SeaweedFS (chrislusf/seaweedfs:3.97, доступен).

Prerequisites: Docker с Compose v2, Python 3.9+, POSIX shell (Linux/macOS/WSL или Git Bash).

Команды

sh scripts/init-secrets.sh                          # .env и secrets/ (пароли и ключи S3 генерируются, не печатаются)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait # postgres, redis, s3 → migrate, s3-init → api×2, reconciler → lb
make test                                           # публичный smoke lab4
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && sh scripts/restore.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-files                                     # негативный набор вложений
make test-reconcile                                 # трек 2: внедрение расхождений
make reconcile-dry                                  # отчёт reconciler без изменений
sh scripts/collect-evidence.sh all                  # все доказательства в evidence/

Остановка без потери данных: docker compose --env-file .env stop. Намеренное удаление учебных данных: docker compose --env-file .env down -v (удаляет pg_data, redis_data, s3_data).

Архитектура и решения

клиент ──► lb (HAProxy, единственный опубликованный порт 127.0.0.1:8080)
             ▼
           api × N ──► postgres: users, chats, messages, attachments (метаданные), message_attachments
             │     ──► redis: сессии, кэш истории
             └───────► s3 (MinIO, сеть back, порты не опубликованы, консоль off): bucket messenger-attachments (private)
           reconciler (тот же образ, --apply --interval 10m --grace 1h) ──► postgres + s3
           s3-init (one-shot): bucket, anonymous none, политика и пользователь API

Перенесено из lab3: всё — X-Instance-Id, идемпотентность, HAProxy с readiness, drain по SIGTERM, сессии в Redis, версия кэша истории в PostgreSQL, однократные миграции, скрипты отказа.

Новое в lab4:

  1. Модель данных (0004_attachments.up.sql): attachments(id, chat_id, owner_id, filename, object_key UNIQUE, status uploading|ready|missing, content_type, size_bytes, sha256, …) и message_attachments(message_id, attachment_id, position). Object key a/{chat_id}/{attachment_id} назначает сервер; filename только отображается.
  2. Загрузка (attachment.go):
    1. членство в чате (иначе 404) → filename (иначе 400) → Content-Type png/jpeg (иначе 415) → Content-Length > 10 MiB → 413 без чтения тела; без Content-Length тело читается максимум до лимита + 1 байт;
    2. формат по первым байтам (подмена MIME → 415); ранний отказ по пикселям, если заголовок в первых 64 KiB;
    3. намерение status=uploading в PostgreSQL — до записи в S3, поэтому у любого объекта, который может появиться в bucket, есть учётная запись;
    4. один потоковый PUT в S3; через pipe параллельно идёт SHA-256 и структурная проверка изображения (imagecheck.go): PNG — CRC каждого chunk, IHDR, длина распакованного IDAT (zlib → io.Discard, с учётом Adam7); JPEG — сегменты, SOF, сканы, EOI. Пиксели не декодируются, лимит 40 млн пикселей проверяется по IHDR/SOF до распаковки, «бомба» 100000×100000 отклоняется по 66 байтам;
    5. status=ready + content_type/size/sha256 → 201 только после того, как объект и метаданные сохранены.
  3. Компенсация. Ошибка до MarkReady (битое изображение, отказ S3, обрыв клиента) — сразу удаляются объект и намерение. Ошибка MarkReady — исход неизвестен: объект не удаляется, намерение удаляется, только если оно всё ещё uploading (см. «Исправления, найденные тестами»). Остатки любых сбоев убирает reconciler.
  4. Скачивание — только через API, без redirect: проверка членства в чате вложения, Content-Type оригинала, Content-Length, сверка размера с метаданными, Cache-Control: private, no-store. variant=original/по умолчанию — байты; thumbnail|crop|optimized — 404 (у ready-объекта lab4 вариантов нет); прочее — 400.
  5. Сообщения: attachment_ids (0–10 уникальных UUID, по умолчанию []), text="" допустим только с вложениями. Вложения проверяются и блокируются FOR SHARE в транзакции сообщения: того же чата, ready; чужое/неизвестное/незавершённое — 404, в карантине — 409. Порядок сохраняется; отпечаток идемпотентности включает attachment_ids (отсутствие = [], другой порядок = другое тело → 409).
  6. S3 и права (infra/s3/init.sh): идемпотентный bootstrap — mb --ignore-existing, anonymous set none, политика messenger-api (Get/Put/Delete объектов и List только этого bucket), отдельный пользователь API. Root-ключ есть только у s3 и s3-init; у API и reconciler — ключ с политикой. Консоль MinIO выключена (MINIO_BROWSER=off), порты S3 не публикуются.
  7. Readiness не включает S3 — сознательно: без S3 работают регистрация, сессии, чаты и текстовые сообщения, а эндпоинты вложений отвечают 503. Если бы S3 входил в readiness, LB снял бы все реплики и уронил весь мессенджер из-за одной функции.
  8. Таймауты: обычный API 5 s, загрузка/скачивание 30 s (ReadTimeout 30 s), HAProxy timeout server 15s; minio-go — 2 повтора вместо 10, чтобы отказ S3 давал быстрый 503, а не таймаут LB.

Соответствие .env.example: S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_*_FILE/MAX_UPLOAD_BYTES/MAX_IMAGE_PIXELS — как в контракте; SESSION_STORE=redis; добавлены RECONCILE_INTERVAL, RECONCILE_GRACE, DRAIN_DELAY, SHUTDOWN_TIMEOUT.

Где запускался стенд

На машине разработки нет аппаратной виртуализации для Docker Desktop, поэтому Docker-проверки выполнены на GitHub-hosted runner workflow .github/workflows/lab4-stand.yml: три независимых стенда параллельно (base, files, track2), тот же compose.yaml и те же скрипты. Runner: 2 vCPU, 8 GB, Docker 28.0.4, Compose v2.38.2.

Итоговый прогон: https://github.com/CharaWein/2026_lab3/actions/runs/41881945345 (commit 5119d0b, stand=success). Все файлы в evidence/ — из него. Предыдущие прогоны той же ветки нашли ошибки, исправленные ниже.

До Docker-прогона логика проверялась нативно (PostgreSQL 17, S3-эмулятор moto, 2 процесса API): smoke, негативный набор, reconciler.

Исправления, найденные тестами

Что показал тест Причина Исправление
db-gap: после паузы PostgreSQL во время MarkReady строка стала ready, а объекта в S3 нет клиент отвалился по таймауту LB → контекст отменён → код посчитал UPDATE неудавшимся и удалил объект; но UPDATE уже ушёл в БД и закоммитился после разморозки MarkReady выполняется в собственном контексте (байты уже сохранены, учёт доводится до конца); ошибка MarkReady считается неопределённым исходом — объект не удаляется. Повторный прогон: ready + объект, согласовано
s3-outage: при остановленном S3 загрузка давала 415 вместо 503 PUT упал → pipe закрыт с ошибкой → валидатор принял обрыв потока за «битое изображение» валидатор различает собственную ошибку и обрыв потока снаружи (trackingReader); unit-тест attachment_test.go на все четыре причины
официальные образы MinIO недоступны убраны из Docker Hub и quay.io Bitnami той же версии, по digest
файлы секретов 600 читались контейнерами (uid 1001) только потому, что uid runner совпал права файлы 644, каталог secrets/ 700

Доказательства критериев

Уровень 3

Критерий README Команда/сценарий Наблюдаемый результат Файл
Возможности lab3 сохранены регрессии lab3, идемпотентность, failover ×2, persistence, серия отказов, rolling update все PASS; 0 дублей, 0 ошибок при остановке реплик, rolling update — 0 ошибок из 34 743 запросов evidence/regressions.txt, idempotency_concurrent.json, failover_.txt, failover_series.json, rolling_update.*
S3 в общем стенде; метаданные в PostgreSQL, байты в приватном bucket compose.yaml, docker compose ps s3, s3-init, reconciler в стенде; у API нет volume, оригиналы только в s3_data evidence/docker_ps.txt
POST вложения → 201 ready; оригинал побайтно; Message с attachment_ids; посторонний — 404 make test PASS: lab4 public API scenario (SHA-256 оригинала, 404 у постороннего) evidence/smoke.txt
Реальные PNG/JPEG ≤10 MiB, ≤40 Мпикс; MIME по содержимому; опасные filename; лимиты до чтения/декодирования make test-files 28 случаев, 0 ответов 5xx (таблица ниже) evidence/files/attachments_negative.txt
Upload → остановка обслужившей реплики → download через другую attachments_ops.py failover загрузил 5c22e6c38769, контейнер остановлен, скачивал cd9621e01c62, SHA-256 совпал evidence/files/files_failover.json
Restart с volumes сохраняет метаданные и оригинал make test-persistence (lab4 проверяет и файл) PASS; перезапущены postgres, redis, s3, api, lb, reconciler evidence/persistence.txt
Failover lab4 (с проверкой оригинала) make test-failover ×2 PASS ×2, по 144 записи, 0 ошибок, восстановление записи 3.49 s / 3.35 s evidence/failover_1.txt, failover_2.txt

Уровень 4

Критерий README Команда/сценарий Наблюдаемый результат Файл
Тесты: большой файл, повреждённое изображение, подмена MIME, чужое attachment_id, вложение другого чата; без 500 attachments_negative.py 413 по Content-Length (тело не читается) и по chunked 11 MiB; 413 на «бомбе» и 40 000 001 пикселе; 415 на обрезанных/повреждённых PNG и JPEG, подмене MIME в обе стороны, тексте, GIF, пустом теле; 404 на вложение другого чата и неизвестный id; 400 на дубли, >10 id, невалидный UUID evidence/files/attachments_negative.txt
Прерывание загрузки не оставляет неучтённых объектов attachments_ops.py interrupt: отправлен 1 MiB из 4, соединение оборвано строк 0, объектов 0 (компенсация сразу) evidence/files/files_interrupt.json
Отказ между S3 и БД attachments_ops.py db-gap: PUT прошёл, PostgreSQL на паузе 45 s клиент получил 504, 201 не было; после разморозки — ready + 1 объект (согласовано); reconciler ничего исправлять не пришлось evidence/files/files_db-gap.json, compensation_log.txt
Механизм сверки/очистки с безопасным grace reconciler (сервис и make reconcile-*) grace 1h по умолчанию; <5m только с --unsafe-short-grace; трек 2 ниже cmd/reconcile, evidence/track2/
Недоступность S3 attachments_ops.py s3-outage загрузка 503 за 0.38 s, скачивание 503, метаданные 200, текстовое сообщение 201, readiness 200, брошенных намерений 0; после старта S3 загрузка снова ready, старый файл цел evidence/files/files_s3-outage.json
≥10 одновременных загрузок, пик памяти attachments_ops.py memory: 10 и 20 загрузок по 10.2 MB, memory.peak cgroup реплик см. таблицу ниже: +17.7 MiB при 97 MiB трафика, +39.7 MiB при 194 MiB evidence/files/files_memory.json
Bootstrap идемпотентен; отдельные ограниченные credentials; консоль закрыта; private bucket вне API attachments_ops.py security анонимный GET и LIST изнутри сети — 403; ключ API: свой bucket — да, создать bucket — нет, admin API — нет, видит только messenger-attachments; s3-init два раза подряд — exit 0, объектов 10→10; порты S3 не опубликованы evidence/files/files_security.json

Пик памяти при одновременных загрузках (файл 10 187 085 байт, лимит контейнера 256 MiB):

Параллельно Успешно Трафик, MiB Пик реплики до → после, MiB Рост, MiB ≈ на загрузку
10 10/10 97.2 7.3 → 25.0 17.7 1.8 MiB
20 20/20 194.3 8.1 → 47.8 39.7 2.0 MiB

Рост пропорционален числу одновременных загрузок, а не размеру файла: на загрузку уходят буферы чтения (64 KiB peek, 32 KiB валидатор, чанки подписи minio-go) и служебная память HTTP/GC. Буферизация файла целиком дала бы ≥10 MiB на загрузку (≥200 MiB при 20). Ограничение памяти по числу одновременных загрузок сверху — maxconn HAProxy и лимит контейнера; отдельного семафора на загрузки нет.

Трек 5.2: согласованность двух хранилищ

Гипотеза

  1. Повторяемый reconciler, обходящий PostgreSQL и S3 одним merge-проходом в общем порядке ключей, находит все виды расхождений (сироты, потерянные объекты, брошенные загрузки, подменённый размер) и исправляет их безопасно: dry-run ничего не меняет, повторный прогон ничего не находит, свежие (моложе grace) и используемые сообщениями вложения не удаляются никогда.
  2. Память обхода постоянна (O(1) от числа вложений), время линейно и определяется S3 LIST, а не базой.

Разбивка времени по источникам (wait_ms) добавлена после первого замера, когда рост времени на пару оказался нелинейным на малых N.

Методика

Reconciler (reconcile.go, cmd/reconcile): строки attachments (ORDER BY object_key COLLATE "C") и ListObjectsV2 (лексикографический порядок) читаются потоками и сливаются как отсортированные списки. Время «сейчас» берётся из PostgreSQL. Одновременно работает один экземпляр (pg_try_advisory_lock).

Расхождение Условие Действие (--apply) Защита
stale_intent строка uploading старше grace удалить объект (если есть), затем строку моложе grace — загрузка может идти
orphan_object объект без строки, старше grace удалить объект перед удалением повторная проверка строки по ключу
missing_object строка ready без объекта карантин status=missing (API → 503) перед карантином повторный Stat объекта
size_mismatch размер объекта ≠ метаданным карантин —
restored missing, объект снова есть и размер совпал status=ready —
purge_missing missing старше grace и ни одно сообщение не ссылается удалить строку FOR UPDATE против FOR SHARE при прикреплении; используемые остаются навсегда

Порядок «сначала объект, потом строка» выбран так, чтобы сбой между шагами оставлял учтённое намерение, а не неучтённый объект.

Внедрение ошибок (reconcile_faults.py): через API — чат и 6 вложений, 3 из них прикреплены к сообщениям. Затем: S3 — старая сирота, свежая сирота, удалены 3 объекта (2 используемых, 1 нет), подменён размер одного; БД — 2 брошенных намерения (с объектом и без), 1 «идущая» загрузка. Grace в тесте 8 s (--unsafe-short-grace), «старые» строки сдвинуты на 30 минут, чтобы фоновый reconciler стенда (grace 1h) их не трогал.

Стоимость обхода (reconcile_cost.py): досеиваем согласованные пары до N = 1 000 / 10 000 / 30 000 (строки — SQL, объекты по 1 KiB — mc mirror), три dry-run на каждый N, медиана; затем 1% расхождений (150 удалённых объектов + 150 сирот).

Результаты

Обнаружение и исправление (evidence/track2/faults.json):

Проход Найдено Исправлено Пропущено (защита)
dry-run stale_intent 2, orphan 1, missing 3, size_mismatch 1 — (снимки БД и S3 до/после совпали) fresh_intent 1, fresh_object 1
apply те же 7 все 7 fresh_intent 1, fresh_object 1
повторный apply 0 0 + fresh_missing (карантин моложе grace)
объект «восстановлен из бэкапа» restored 1 1 (скачивание снова отдаёт исходные байты) —
после grace purge_missing 2, orphan 1 (бывшая свежая), stale_intent 1 (бывшая «идущая») все referenced_missing_kept 1

После apply через API: здоровые вложения скачиваются байт-в-байт; потерянные отвечают 503 на метаданные и байты; сообщение сохраняет attachment_ids; прикрепить вложение из карантина — 409.

Стоимость обхода (evidence/track2/cost.json, медиана 3 dry-run; runner 2 vCPU):

Пар (строка+объект) Время, ms мкс на пару LIST-страниц Ожидание S3 LIST, ms Ожидание БД, ms Heap, MB
1 004 96 96 2 59–96 0–74 2.4
10 004 2 647 265 11 2 410–2 863 58–235 3.4
30 004 8 374 279 31 7 502–11 235 127–292 2.2
30 004 + 1% расхождений 10 344 — 31 — — — + 150 Stat
  • Память постоянна: heap 2–3.4 MB при росте N в 30 раз — merge-проход не держит множества в памяти. Гипотеза подтверждена.
  • Время определяется S3 LIST: 96–98% времени reconciler ждёт листинга MinIO, менее 3% — PostgreSQL. Гипотеза подтверждена.
  • Линейность — с оговоркой: от 10k к 30k время на пару почти постоянно (265 → 279 мкс, +5%), а 1k дешевле в 2.8 раза. Объяснение (не измерено отдельно): небольшой листинг MinIO отдаёт из кэша метаданных, большие требуют обхода диска. На 2 vCPU это ≈ 0.28 ms на объект, то есть ~4.6 минуты на миллион вложений — при интервале 10 минут приемлемо, дальше нужен обход по префиксам чатов или инкрементальная сверка по событиям S3.
  • 1% расхождений добавляет ~2 s: 150 точечных Stat для перепроверки перед карантином (в dry-run сироты моложе grace только учтены как fresh_object).

Ограничения трека

  • Один узел MinIO на 2 vCPU; абсолютные цифры зависят от диска и CPU, вывод о доминировании LIST — нет.
  • Объекты по 1 KiB: размер на обход не влияет (LIST не читает тела), но на время mc mirror при подготовке влияет.
  • Сверка размера — по LIST, без пересчёта SHA-256 (это потребовало бы скачать все объекты); подмена содержимого с тем же размером не обнаруживается.
  • Grace зависит от часов: время строк — из PostgreSQL, LastModified — из MinIO; на одном хосте расхождение пренебрежимо, на разных узлах grace должен покрывать skew.
  • Ready-вложение, загруженное, но так и не прикреплённое к сообщению, reconciler не удаляет (контракт не задаёт срок жизни таких вложений).

Эксперименты и отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка реплики, загрузившей файл скачивание через другую тот же SHA-256 через другую реплику 0
Остановка S3 503 на вложениях, остальное работает 503 за 0.38 s; текст, сессии, readiness — OK после старта S3 — сразу; данные целы
Обрыв клиента посреди тела ни строки, ни объекта 0/0 —
PostgreSQL замер между PUT и MarkReady не 201; нет ready без объекта 504 клиенту; ready + объект после разморозки 0 потерь; дубль загрузки при повторе клиента возможен (см. ограничения)
Restart всего стенда данные и файлы целы PASS с прежним токеном ≈14 s до healthy
Остановка каждой реплики под нагрузкой 0 ошибок 0 из 18 996 возврат в LB за 6.4 s
Rolling update под нагрузкой 0 ошибок 0 из 34 743 замена 29 s

Ограничения и следующие шаги

  • SPOF: один узел MinIO (без erasure coding), PostgreSQL, Redis, LB, хост. Выдерживается отказ API-реплики и временная недоступность S3 (вложения недоступны, мессенджер работает).
  • Загрузка не идемпотентна (контракт не требует ключа): если клиент не получил ответ (504 в db-gap) и повторит загрузку, появится второе вложение; первое останется неприкреплённым.
  • Ограничение памяти на одновременные загрузки обеспечено косвенно (буферы O(1) на загрузку + maxconn LB + лимит контейнера); явного семафора нет.
  • JPEG проверяется структурно (маркеры, SOF, EOI), без энтропийного декодирования: формально корректный JPEG с испорченными данными скана будет принят.
  • Bitnami legacy-образы больше не обновляются; при смене образа достаточно поменять image в compose.yaml (MinIO API тот же) или перейти на SeaweedFS.