Files
mtusi2026lab4/REPORT.md
T
2026-10-29 15:00:36 +03:00

29 KiB
Raw Blame History

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

  • Автор, группа: Кораблев Петр, БВТ2304
  • Целевая оценка: 5 (уровень 3 + уровень 4 + трек 2 «Согласованность двух хранилищ»)
  • Commit/PR: ветка solution/BVT2304-korablev
  • Использованные источники, библиотеки и помощь ИИ: Go 1.23.4, net/http, pgx/v5 5.7.2, go-redis/v9 9.7.0, golang.org/x/crypto (Argon2id), golang.org/x/sync 0.10.0 (semaphore), google/uuid 1.6.0, minio-go/v7 7.0.82 (S3-клиент, работает с любым S3-совместимым сервером), стандартные image/png и image/jpeg. Образы: PostgreSQL 17.2-alpine3.21, Valkey 8.0.2-alpine3.21, HAProxy 3.0.5-alpine, SeaweedFS 3.80 (chrislusf/seaweedfs:3.80), golang:1.23.4-alpine3.21 → alpine:3.21.2; для проверок вне API — python:3.12.8-alpine3.21. Документация: AWS S3 (uploads, SigV4, ListObjectsV2), SeaweedFS wiki (S3 API, s3.config identities), Go image.DecodeConfig. Помощь ИИ использовалась при написании отчёта.

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

Prerequisites: Docker 29.x + Compose v2 (Docker Desktop/WSL2), Python 3.9+, Git. Go и make локально не нужны (сборка в Docker; без make команды ниже запускаются через python). На Windows тесты запускать с PYTHONUTF8=1 (контракт в UTF-8).

python3 scripts/init_secrets.py            # = make secrets: secrets/* + .env из .env.example
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait   # = make up
make check && make test                    # smoke через LB http://localhost:8080
make test-student                          # собственные тесты (18 кейсов)
make test-persistence ACTION_SCRIPT=scripts/restart.sh   # Windows: scripts/restart.cmd
make test-failover    ACTION_SCRIPT=scripts/stop-one.sh  # Windows: scripts/stop-one.cmd
docker compose up -d --no-recreate --wait api            # вернуть остановленную реплику
make ops-checks memory track2-faults track2-cost         # уровень 4 и трек 2 (нужен Docker)
  • init_secrets.py генерирует случайные пароли PostgreSQL/Valkey и две S3-идентичности: bootstrap-admin (только для s3-init) и messenger-api (права Read/Write/List только на bucket messenger-attachments), а также secrets/s3_identities.json — конфиг SeaweedFS. Всё в secrets/ (в .gitignore и .dockerignore), контейнерам передаётся как Compose secrets /run/secrets/*.
  • Порядок старта задан depends_on: postgres/valkey/s3 healthy → migrate (миграции под advisory lock) → s3-init (идемпотентное создание bucket) → api ×2 → lb; reconciler стартует после s3-init. Готовность — --wait//health/ready.
  • Безопасная остановка: docker compose stop (make down), данные в volumes pgdata, s3data сохраняются. Намеренное удаление учебных данных: docker compose down -v (удаляет volumes — необратимо).

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

client → HAProxy (lb, 127.0.0.1:8080) → api ×2 (Go, read-only rootfs)
                                         ├─ PostgreSQL: users, chats, messages, sessions, idempotency,
                                         │              attachments (метаданные), message_attachments
                                         ├─ Valkey: кэш сессий (из lab3)
                                         └─ SeaweedFS S3 (bucket messenger-attachments, приватный): байты
reconciler (тот же образ, `reconcile --apply --every 10m`) — сверка БД ↔ S3

Перенесено из lab3 без изменения поведения: пользователи, Basic → Bearer-сессии (Argon2id, Valkey-кэш), чаты, keyset-пагинация, обязательный Idempotency-Key, X-Instance-Id, HAProxy с health-check, хуки restart/stop-one. Изменено: убран экспериментальный путь MESSAGE_WRITE_PATH=tx трека 1 lab3 (остался один путь — one-shot CTE), лимит памяти API 256M → 512M, таймауты HAProxy client/server 30s/10s → 75s (загрузка до 10 MiB).

Выбор S3-сервера. Планировался MinIO, но на 2026-10 образы minio/minio и minio/mc недоступны ни в Docker Hub, ни в quay.io (pull access denied / 401). Выбран SeaweedFS 3.80: одна команда weed server -s3 (master+volume+filer+S3), идентичности с правами на конкретный bucket через -s3.config, без анонимной идентичности — значит bucket приватный. S3-порт 8333 не публикуется, консоли master (9333) и filer (8888) тоже: сервис только в сети data.

Модель данных (src/internal/db/migrations/0003_attachments.sql):

  • attachments: id, chat_id, owner_id, filename (только для отображения), content_type, size_bytes, sha256, width, height, object_key (UNIQUE, генерирует сервер: attachments/<chat_id>/<attachment_id>), status ∈ {pending, ready}, missing_at, created_at, updated_at. FK (chat_id, owner_id) → chat_members, CHECK-и на размер ≤ 10 MiB, пиксели ≤ 40M, формат sha256.
  • message_attachments(message_id, chat_id, attachment_id, position) с составным FK (chat_id, attachment_id) → attachments(chat_id, id): сама БД не даёт привязать к сообщению файл другого чата.
  • messages.text теперь может быть пустым (CHECK 0..4000); правило «пустой текст только при ≥1 вложении» проверяет API.

Загрузка POST /api/v1/chats/{id}/attachments?filename=… (src/internal/api/attachments.go):

  1. Аутентификация → членство в чате (посторонний получает 404 до чтения тела) → filename (1..255 code points, без /, \, NUL, управляющих и bidi-override символов, не ./..) → Content-Type ∈ {image/png, image/jpeg} иначе 415 → Content-Length > 10 MiB → 413 сразу.
  2. Слот загрузки (семафор UPLOAD_CONCURRENCY=8 на реплику), тело читается через http.MaxBytesReader(10 MiB) → 413 при превышении. Тело буферизуется в памяти (≤ 10 MiB на слот), значит память одной реплики под загрузки ограничена 8 × 10 MiB.
  3. Формат определяется по magic bytes и сравнивается с заявленным (подмена → 415); image.DecodeConfig читает только заголовок: >40M пикселей → 413 до декодирования; затем полное декодирование под общим бюджетом памяти (DECODE_BUDGET_BYTES=128 MiB, взвешенный семафор по оценке пиксели × байт/пиксель) — повреждённые данные → 415.
  4. Транзакционная граница: (a) INSERT attachments status='pending' → (b) S3 PUT (Content-MD5) → (c) UPDATE … SET status='ready' WHERE status='pending' → 201 ready. 201 возвращается только когда и байты, и метаданные зафиксированы.
  5. Ошибка на (b) или (c) → 503 и фоновая компенсация, которая начинается со строки: DELETE … WHERE status='pending', и только если строка удалена — удаление объекта. Если UPDATE → ready на самом деле закоммитился, а ответ БД потерялся, строка уже ready, и объект не трогаем (иначе получилось бы ready-вложение без байтов). Если недоступна БД, остаётся stale pending; если недоступен S3, может остаться объект без строки. Оба случая убирает reconciler после grace.

Скачивание GET /attachments/{id}/content: только участники чата (иначе 404), только status='ready'; Stat до первого байта ответа (отсутствие объекта → 404, недоступность S3 → 503), затем поток из S3 в ответ, без redirect; заголовки Content-Type (истинный), Content-Length, X-Content-Type-Options: nosniff, Cache-Control: private, no-store, ETag: "<sha256>". variant=thumbnail|crop|optimized → 404 (вариантов в lab4 нет), неизвестный → 400.

Сообщение с attachment_ids: 0..10 уникальных UUID (иначе 400). Проверка «все ready и в этом чате», запись idempotency, сообщения и связей — одним SQL-оператором (CTE), как в lab3. Чужое, неизвестное или из другого чата → 404, ничего не сохраняется. Отпечаток идемпотентности считается по {text, attachment_ids} с нормализацией «нет поля» = [].

Готовность и отказы. /health/ready зависит только от PostgreSQL. Недоступность S3 ломает только эндпоинты вложений (503), а текстовый мессенджер продолжает работать: если бы ready зависел от S3, LB снял бы обе реплики и упал бы весь API. SDK S3 настроен на быстрый отказ: MaxRetry=1, dial-таймаут 2 с, ResponseHeaderTimeout 10 с, операции под S3_TIMEOUT=15s.

Соответствие .env.example — все переменные реально используются в compose.yaml: S3_ENDPOINT=http://s3:8333, S3_REGION, S3_BUCKET, S3_*_FILE (secrets), MAX_UPLOAD_BYTES (не больше 10 MiB, иначе старт с ошибкой), MAX_IMAGE_PIXELS, плюс UPLOAD_CONCURRENCY, DECODE_BUDGET_BYTES, UPLOAD_TIMEOUT, S3_TIMEOUT, API_MEMORY, API_GOMEMLIMIT, RECONCILE_GRACE, RECONCILE_EVERY.

Роль Service Образ Health Volume Сеть / порт Credentials
LB lb haproxy:3.0.5-alpine :8404/healthz — app; 127.0.0.1:8080 —
API ×2 api mtusi-messenger:lab4 (сборка) /health/ready нет (read-only rootfs, tmpfs /tmp 1m) app, data secrets: database_url, cache_url, s3_access_key_id, s3_secret_access_key
БД postgres postgres:17.2-alpine3.21 pg_isready pgdata data pg_password
Сессии valkey valkey/valkey:8.0.2-alpine3.21 ping — data valkey_auth
S3 s3 chrislusf/seaweedfs:3.80 :8333/healthz s3data data, не публикуется s3_identities.json
Bootstrap migrate, s3-init mtusi-messenger:lab4 one-shot — data database_url / s3_admin_*
Сверка reconciler mtusi-messenger:lab4 — — data database_url, s3 api-ключи

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

Окружение всех замеров: Windows 11, Docker Desktop 29.7.2 / Compose 5.5.0, WSL2 kernel 6.18; лимиты: API 1 CPU / 512M ×2, S3 1 CPU / 1G, PostgreSQL 2 CPU / 1G, reconciler 0.5 CPU / 128M. Дата — 2026-10-29.

Уровень 3

Критерий README Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make check, make test PASS: lab4 public API scenario evidence/check-smoke.txt
Возможности lab3 сохранены make test-student (8 кейсов lab3) no-sticky, идемпотентность через 2 реплики, logout на всех репликах — PASS evidence/student-tests.txt
S3 в общем стенде, байты в приватном bucket lab4ops.py private аноним GET/LIST/CreateBucket → 403; api-ключ GET → 200, sha256 совпадает; порт S3 не опубликован evidence/private.json
Метаданные в PostgreSQL, не байты в БД/на диске API lab4ops.py no-local-file у API read-only rootfs (touch → Read-only file system), монтируются только secrets, новых файлов 0 evidence/no-local-file.json
201 ready, побайтный download, ACL smoke + t_upload_formats, t_attachment_acl PNG и JPEG: sha256/размер/Content-Type совпадают; посторонний получает 404 на метаданные/content/upload, без токена 401 evidence/student-tests.txt
Реальные PNG/JPEG ≤10 MiB, ≤40M px, MIME по содержимому, опасные filename t_size_limit, t_bomb, t_corrupt_and_spoof, t_filenames PNG 10 420 335 B → 201; 10 MiB+1 → 413; заголовок 20000×20000 → 413 за 32 мс; 9 вариантов подмены/повреждения → 415; 12 опасных имён → 400 evidence/student-tests.txt
Upload → стоп обслужившей реплики → download через другую lab4ops.py failover-upload загрузка через api-2, docker stop api-2, 10/10 скачиваний через api-1 с верным sha256 evidence/failover-upload.json
Failover (публичный тест) make test-failover для каждой реплики остановлена api-2: PASS, 123 записи, 0 ошибок, восстановление за 4.1 с; остановлена api-1: PASS, 116 записей, 0 ошибок, 4.1 с; файл цел в обоих случаях evidence/failover.txt
Restart всего стенда с volumes make test-persistence (restart.cmd) PASS; postgres/valkey/s3/api перезапущены (uptime до/после в файле), файл и сессия сохранились evidence/persistence.txt

Уровень 4

Критерий Команда/сценарий Наблюдаемый результат Файл
Тесты: большой файл, повреждённое изображение, подмена MIME, чужой attachment_id, файл другого чата; нет 500 make test-student (10 кейсов lab4) 18/18 PASS; в логах API за все прогоны нет ни одного 500 evidence/student-tests.txt
Нет вечных неучтённых объектов: компенсация + сверка с grace pending-intent + компенсация + reconciler (grace 15 мин, каждые 10 мин) см. трек 2; реальный случай: после падения S3 reconciler нашёл 19 stale pending из прерванных загрузок и удалил их evidence/track2/faults.json
Отказ S3 lab4ops.py s3-outage upload 503 за 2.0 с, download 503 за 2.0 с, метаданные 200, текстовое сообщение 201, ready 200; после старта S3 загрузки сразу работают, старый файл цел; pending-строк не осталось (компенсация удалила строку) evidence/s3-outage.json
Ограниченная RAM, ≥10 одновременных загрузок make memory см. «Эксперименты»: пик API ≤ 311 MiB при 40 одновременных 10-МБ загрузках, плато уже после 20 evidence/memory.json
Bootstrap идемпотентен lab4ops.py bootstrap (двойной запуск migrate и s3-init) «migrations up to date», created:false evidence/bootstrap.json
Отдельные ограниченные S3 credentials; консоль закрыта; private bucket проверен вне API lab4ops.py private api-идентичность: CreateBucket → 403, PUT в другой bucket → 403; S3/консоли не опубликованы; аноним → 403 evidence/private.json

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

Критерий Команда Результат Файл
Повторяемый reconciler с dry-run server reconcile [--apply] [--grace] [--every] dry-run по умолчанию; advisory lock — одновременно идёт один проход src/internal/reconcile/reconcile.go
Ошибки на обеих сторонах: обнаружение и исправление make track2-faults 5 из 5 внедрённых сбоев найдены, 7 исправлений, повторный apply → 0 evidence/track2/faults.json
Свежие и используемые не удаляются там же свежий orphan, свежий pending и используемые U1/U2 остались целы evidence/track2/faults.json
Стоимость обхода make track2-cost линейно, ~70 мкс/объект, 20k за 1.4–1.6 с evidence/track2/cost.json

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

Память API при одновременных загрузках (уровень 4)

Гипотеза: пиковая память реплики ограничена ≈ база + UPLOAD_CONCURRENCY × 10 MiB + бюджет декодирования, поэтому она выходит на плато и не растёт с числом клиентов.

Методика: scripts/lab4ops.py memory. Синтетический шумовой PNG 1000×3480, 10 420 335 B (почти лимит). Перед каждым прогоном docker compose restart api, одна прогревочная загрузка, затем N одновременных загрузок (барьер) через LB. Пик читается из cgroup v2 memory.peak каждой реплики. По 2 повтора.

Одновременно Успешно Wall, с p50 / max, мс Пик API, MiB (max из 2 реплик)
1 1/1, 1/1 0.35 337–344 64.4 / 66.4
10 10/10, 10/10 3.1–4.1 2844–3830 / 2882–3945 148.2 / 151.7
20 20/20, 20/20 6.4–7.1 5476–6097 / 6062–6830 286.0 / 263.7
40 40/40, 40/40 11.8–12.6 8542–9590 / 11156–12044 264.5 / 311.1

Вывод: память выходит на плато ~250–310 MiB между 20 и 40 клиентами (слоты по 8 на реплику). Лишние клиенты ждут слота, это видно по росту latency, а не памяти. Это ниже лимита 512M и GOMEMLIMIT 400MiB. Ограничения: буфер одного тела ≤10 MiB в RAM — сознательное упрощение вместо потокового парсера PNG. 40M-пиксельный RGBA PNG при декодировании занимает ~160 MB и упирается в бюджет 128 MiB (декодируется один, остальные ждут). Запуск на одном ноутбуке, клиент и стенд делят CPU.

Найденный отказ: первый прогон шёл с лимитом S3 512M, и на 20 параллельных PUT процесс SeaweedFS перезапустился (RestartCount 1, логов завершения нет — kill по памяти). 18 из 20 загрузок получили корректный 503, их pending-строки остались (тогдашняя версия компенсации сначала удаляла объект и при недоступном S3 сохраняла строку) и затем были найдены reconciler как 19 stale pending, вместе с одной от теста отказа S3. Лимит S3 поднят до 1G: в повторе 0 рестартов при memory.peak ≈ 1 GiB. Этот пик включает page cache записываемых файлов, который ядро может вытеснить.

Трек 2: внедрение ошибок (grace = 1 мин для эксперимента, 15 мин в стенде)

Методика scripts/track2/run_track2.py faults. Периодический reconciler на время теста останавливается. Сбои вносятся напрямую: в S3 через scripts/track2/s3tool.py (SigV4 на stdlib, запускается в одноразовом контейнере в сети data), в БД через psql.

Сбой (сторона) Ожидание dry-run apply
F1 объект без строки (S3) удалить после grace orphan_object удалён
F2 потеряна строка неиспользуемого U3 (БД) объект стал сиротой → удалить orphan_object удалён
F3 потерян объект используемого U2 (S3) метаданные не трогать, пометить missing_object missing_at выставлен; GET метаданных 200, content 404, сообщение по-прежнему ссылается на U2
F4 падение между PUT и ready (pending + объект, 1 ч) удалить строку, затем объект stale_pending удалены оба
F5 падение до PUT (pending без объекта, 1 ч) удалить строку stale_pending удалена
F7 загрузка «в процессе» (свежие pending + объект) не трогать не найдена (row известен) цела
F8 свежий объект без строки не трогать skip: younger than grace цел
U1 используемый, исправный не трогать — скачивается, sha256 верный
  • Dry-run ничего не меняет: счётчики S3-объектов, строк, pending и missing до и после совпадают (dry_run_changed_nothing: true).
  • Первый apply: 7 исправлений, 0 ошибок.
  • Повторный apply: 0 исправлений, только skip свежего F8 — проход идемпотентен.
  • Восстановление: после возврата объекта U2 «из бэкапа» (те же байты) apply выдаёт recovered=1, снимает missing_at, и скачивание отдаёт исходный sha256.
  • Сторонние находки: dry-run отдельно учитывает находки вне чата эксперимента (other_findings_outside_experiment) — это остатки предыдущих прогонов.

Почему это безопасно. Порядок «сначала LIST S3, потом скан БД» плюс «pending-строка пишется до PUT» означают, что у любого объекта из листинга строка уже есть. Перед каждым разрушающим действием есть повторная проверка: сирота — ObjectKeyKnown в БД, missing — StatObject, pending — DELETE … WHERE status='pending'. Удаляются только объекты без строк и pending-строки; ни одна из них не может быть в message_attachments, потому что привязать можно только ready. Используемые метаданные никогда не удаляются. Grace 15 мин намного больше бюджета загрузки (60 с). Если UPDATE → ready проигрывает гонку с reconciler, загрузка отвечает 503, а не 201.

Трек 2: стоимость обхода

scripts/track2/run_track2.py cost: в БД добавляются N ready-строк (SQL generate_series), в S3 — N объектов по 100 B. Каждый размер замеряется трижды в dry-run, после замеров bench-данные удаляются.

Объектов list S3, мс скан БД, мс всего, мс мкс/объект пик памяти reconciler, MiB находок
1 229 52 6–9 59–61 48–50 10.1–10.9 0
5 229 258–345 62–70 326–408 62–78 15.8–17.2 0
20 229 1321–1537 41–95 1404–1618 69–80 30.8–31.2 0

Вывод: стоимость линейна, примерно 70 мкс и 1 КБ RAM на объект. Больше 90% времени занимает постраничный LIST в S3 (по 1000 ключей). На 20k объектов ложных срабатываний 0. При частоте раз в 10 минут нагрузка ничтожна. Ограничение: все ключи держатся в памяти, на 10M объектов это ~1 ГБ. Дальше нужен обход по префиксам attachments/<chat_id>/ или потоковое слияние двух отсортированных списков: ключи S3 и ORDER BY object_key в БД.

Сводка отказов

Воздействие Что ожидаем Что наблюдали Восстановление / потеря данных
docker stop обслужившей API-реплики LB уводит трафик первая успешная запись через ~4 с, 0 дублей; файл скачивается через другую без потерь
Restart postgres+valkey+s3+api данные, сессия и файл живы PASS, тот же токен работает без потерь
Остановка S3 503 только на вложениях upload/download 503 за 2 с, текст и ready работают после старта S3 сразу; pending-строк не осталось
SeaweedFS убит по памяти (лимит 512M) 503, без 201 на несохранённое 18× 503, 2× 201 19 pending-строк убраны reconciler; лимит поднят до 1G
Внедрённые orphan/missing/pending найти, исправить безопасно 5/5 найдены, повторный apply = no-op missing-байты невосстановимы без бэкапа: метаданные помечены и сохранены

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

  • Один Docker-host, по одному PostgreSQL, S3-узлу и LB: выдерживается отказ одной API-реплики и рестарт стенда, но не потеря хоста или диска S3. В SeaweedFS нет репликации томов.
  • Тело загрузки буферизуется в RAM до 10 MiB на слот. Это ограничено и измерено, но не полностью потоковый режим.
  • Полное декодирование нужно для отсева повреждённых файлов и стоит CPU: 40 одновременных загрузок 10 МБ занимают ~12 с на 2×1 CPU.
  • Объект, у которого обнаружен missing, невосстановим без бэкапа. Reconciler только помечает его, и API отдаёт 404 на content.
  • Reconciler хранит все ключи в памяти (ограничение указано выше). size_mismatch только сообщается, автоматически не исправляется.
  • Цель failover-теста выбирается по X-Instance-Id обслужившего ответа, а HAProxy раздаёт запросы по кругу, поэтому без вмешательства тест детерминированно останавливал api-2. Для проверки api-1 перед запуском был сделан один лишний запрос через LB (curl http://localhost:8080/health/live), сдвигающий очередь; так получен прогон с остановкой api-1.
  • CI-job со сборкой стенда и make test не добавлен: workflow skeleton проверяет только контракт.