Files
mtusi2026lab4-implementation/REPORT.md
T
2026-11-20 05:04:28 +03:00

22 KiB
Raw Blame History

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

  • Автор, группа: Спесивцев Даниил, БПИ2301
  • Целевая оценка: 5, трек 2 — согласованность двух хранилищ
  • Commit/PR: commit 60e8f4474b
  • Использованные источники, библиотеки и помощь ИИ: Go 1.27, стандартная библиотека и перечисленные ниже модули; S3 API и MinIO-совместимая семантика — по документации AWS и RustFS. При подготовке решения и текста отчёта использовались LLM; все команды и результаты в отчёте воспроизведены на локальном стенде.

Библиотеки и компоненты:

Компонент Версия Назначение
go-chi/chi v5.3.2 HTTP-роутинг и middleware
jackc/pgx v5.11.0 PostgreSQL, пул pgxpool, транзакции
redis/go-redis v9.23.0 общие сессии
golang.org/x/crypto v0.58.0 Argon2id
minio/minio-go v7.4.1 S3-клиент (API и операторские утилиты)
minio/madmin-go v3.0.110 идемпотентный bootstrap пользователя и политики
migrate/migrate v4.20.1 (образ) однократные миграции
HAProxy 3.4.7-alpine (образ) единая точка входа

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

Стенд: i5-11400H (12 потоков), 15 GiB RAM, Linux 7.3.5, podman 6.2.0 + podman-compose 1.6.0 (evidence/env.txt). Образы закреплены тегами: rustfs/rustfs:1.0.6, postgres:18.6-alpine3.24, redis:8.10.3-alpine3.23, haproxy:3.4.7-alpine, migrate/migrate:v4.20.1, сборка API — golang:1.27.1-alpine3.24 → alpine:3.24.1.

scripts/init-secrets.sh
make up
until curl -sf http://localhost:8080/health/ready; do sleep 1; done

make check
make validate PYTHON=.venv/bin/python
make test
make test-attachments
make test-contract
make test-memory
make test-cost
make test-reconcile
make test-go
make test-idempotency
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh

scripts/reconcile.sh                      # dry-run, grace 1h
scripts/reconcile.sh -grace 0s -dry-run=false

make down                                 # остановка, volumes сохраняются
podman-compose down -v                    # намеренное удаление учебных данных

Движок выбирается так же, как в lab3: ENGINE=podman/COMPOSE=podman-compose при наличии podman, иначе docker. compose.yaml проходит docker compose config --quiet и podman-compose config.

scripts/init-secrets.sh создаёт локальные файлы секретов, повторный запуск их не перезаписывает (проверено хэшами, evidence/credentials.txt). Bootstrap S3 (s3-init) идемпотентен и запускается один раз перед API.

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

client → lb (HAProxy :8080) ──edge──▶ api ×2 ──backend──▶ postgres (метаданные, источник истины)
                                               ├────────▶ rustfs   (байты, приватный bucket)
                                               └────────▶ redis    (сессии)

migrate (one-shot) ─▶ postgres
s3-init (one-shot) ─▶ rustfs: bucket + policy + app user
reconcile (операторский запуск) ─▶ rustfs + postgres
Роль Service Образ Health/readiness Volume Сеть / порты Credentials
LB lb haproxy:3.4.7-alpine активная проверка /health/ready — edge, публикует 8080 нет
API api ×2 localhost/messenger-api:lab4 /health/live; /health/ready = PostgreSQL + Redis + S3 + не draining — edge + backend, порт не публикуется database_url, cache_url, app-креды S3
БД postgres postgres:18.6-alpine3.24 pg_isready pgdata backend, 127.0.0.1:55432 для make test-go postgres_password
Сессии redis redis:8.10.3-alpine3.23 redis-cli ping redisdata (AOF) backend, 127.0.0.1:56379 нет
S3 s3 rustfs/rustfs:1.0.6 GET /health s3data backend, порт 9000 не публикуется, консоль отключена root-креды
Bootstrap s3-init тот же образ exit 0 — backend root + app креды
Миграции migrate migrate/migrate:v4.20.1 exit 0 SQL read-only backend database_url

Ключевые решения:

  • Хранилище. Выбран RustFS: MinIO-совместимый S3, публично доступный образ с обычным semver-тегом (1.0.6). MinIO community-образы на момент работы не отдаются ни Docker Hub, ни Quay (проверено), поэтому закреплять их тег было бы невоспроизводимо.
  • Разделение данных. В PostgreSQL только метаданные и связи; байты — в приватном bucket. Ключ объекта chats/{chat_id}/{attachment_id} генерирует сервер, filename — только для отображения. В таблице attachments нет бинарных колонок (evidence/storage.txt).
  • Порядок записи. PUT в S3 → транзакция PostgreSQL (метаданные + ключ идемпотентности + связи). При ошибке БД выполняется компенсирующий DELETE; если и он не удался — объект остаётся и снимается reconciler'ом после grace period.
  • Креды. API работает отдельным S3-пользователем с политикой ListBucket/GetBucketLocation на bucket и GetObject/PutObject/DeleteObject на объекты. Root-креды смонтированы только в s3 и s3-init; удаление bucket app-кредами запрещено (Access Denied).
  • Ограничение RAM. Тело ограничено 10 MiB и читается потоково в буфер; до полной распаковки проверяются формат (image.DecodeConfig) и лимит 40 млн пикселей; полное декодирование идёт под семафором (MAX_CONCURRENT_DECODES=1), общая параллельность загрузок — MAX_CONCURRENT_UPLOADS=8. Один декод 40-мегапиксельного PNG — самая дорогая операция, поэтому верхняя граница памяти детерминирована.
  • Идемпотентность сообщений. Ключ, сообщение и связи message_attachments пишутся одной транзакцией; в хэш входят text и канонизированный (отсортированный) набор attachment_ids, отсутствие поля эквивалентно [].
  • Reconciler. Сверяет объекты S3 (по префиксу) со строками attachments. Orphan-объект удаляется только если он старше grace period и на него нет строки метаданных. «Мёртвая» строка метаданных (объект отсутствует) удаляется, только если сообщения на неё не ссылаются; используемая строка сохраняется и попадает в отчёт, потому что восстановить утраченные байты нельзя, а удаление нарушило бы историю.
  • Соответствие .env.example. SESSION_STORE=postgres в примере, фактически используются Redis-сессии из lab3 (контракт допускает оба варианта); S3_ACCESS_KEY_ID_FILE/S3_SECRET_ACCESS_KEY_FILE указывают на app-креды; MAX_UPLOAD_BYTES/MAX_IMAGE_PIXELS передаются в API; API_REPLICAS → scale; IDEMPOTENCY_TTL_SECONDS не используется — ключи хранятся бессрочно.

Таймауты: PostgreSQL statement_timeout 5 s / connect 3 s; readiness-ping 1 s; HTTP-сервер 5/15/15/60 s; HAProxy connect/server/check 2/20/1 s; graceful shutdown: drain 3 s + Shutdown 5 s при stop_grace_period: 10s.

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

Критерий Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make test PASS evidence/smoke.txt
Контракт вложений и сообщений make test-attachments 23/23 проверки evidence/negative.txt
Аудит краевых случаев контракта make test-contract 30/30 проверки evidence/contract-audit.txt
Полная OpenAPI-валидация make validate PYTHON=.venv/bin/python PASS вывод команды
Собственные Go-тесты make test-go 26 PASS evidence/test-go.txt
≥2 реплики, одна точка входа, X-Instance-Id make up, 20 запросов через LB 10/10 на каждую реплику, публикует только lb evidence/instances.txt
S3 в стенде, приватный bucket, постоянный volume анонимный GET и listing 403, порт наружу не публикуется evidence/private-bucket.txt
Метаданные в PostgreSQL, байты в S3 psql, листинг volume в таблице нет бинарных колонок, объект лежит в s3data evidence/storage.txt
201 ready после S3 и БД; скачивание байт-в-байт make test SHA-256 и размер совпадают evidence/smoke.txt
Доступ только участникам (404 постороннему) make test, make test-attachments 404 для metadata и content evidence/smoke.txt, evidence/negative.txt
Ограничения 10 MiB / 40 млн пикселей / MIME / filename make test-attachments 413, 415, 400; PNG ровно 40 000 000 px принят evidence/negative.txt
Ошибки пользователя не превращаются в 500 make test-attachments только 400/404/409/413/415 evidence/negative.txt
Upload → остановка реплики → download через другую make test-failover ×2 0 ошибок, восстановление 3.19–3.32 s evidence/failover-1.txt, evidence/failover-2.txt
Restart с volumes сохраняет метаданные и оригинал make test-persistence PASS, контейнеры перезапущены, volumes те же evidence/persistence.txt
Идемпотентность сообщений через разные реплики make test-idempotency 20 запросов → одно сообщение, обе реплики evidence/idempotency-race.txt
Миграции отдельным контейнером make up версия 3, dirty=f, повторный запуск — no change evidence/migrate.txt
Лимиты и секреты по ролям inspect, ls /run/secrets лимиты у всех сервисов, секреты только у нужных ролей evidence/limits.txt
Недоступность S3 /health/live 200, /health/ready 503, клиент через LB получает 503 evidence/s3-outage.txt
Ограничение памяти, ≥10 параллельных загрузок make test-memory пик 333 МБ при лимите 512 МБ, 10/10 успешно evidence/memory.txt, evidence/upload-memory.json
Отказ между S3 и БД не оставляет объектов инъекция отказа вставки + reconcile 503, число объектов не изменилось evidence/compensation.txt
Идемпотентный bootstrap s3-init дважды одинаковый результат evidence/credentials.txt
Ограниченные креды API удаление bucket app-кредами Access Denied evidence/credentials.txt
Трек 2: reconciler, инъекции с обеих сторон scripts/reconcile.sh, scripts/s3tool.sh детекция и безопасный ремонт evidence/track2-injection.txt
Трек 2: dry-run и повторный запуск -dry-run, повтор -dry-run=false второй прогон ничего не меняет evidence/reconcile.txt, evidence/track2-injection.txt
Трек 2: свежие и используемые не удаляются apply с grace 1h свежий объект и используемое вложение целы evidence/track2-injection.txt
Трек 2: стоимость обхода make test-cost 0.033–0.09 мс/объект, 1 LIST-страница на 1000 evidence/track2-cost.txt

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

Память при загрузках

Гипотеза: лимиты тела и пикселей вместе с семафором декодирования не дают одной загрузке занять неограниченную память.

Методика: 10 одновременных загрузок PNG 8000×5000 (40 000 000 пикселей, 126 609 байт) на реплику, лимит API 512 MiB, MAX_CONCURRENT_UPLOADS=8, MAX_CONCURRENT_DECODES=1; пик снимался через /sys/fs/cgroup/memory.peak после пересоздания реплик.

Результат: 10/10 успешно, 1.01 s, p50 613 мс, p95 1040 мс, пик 333 МБ на реплику (65 % лимита). При MAX_CONCURRENT_DECODES=2 пик упирался в лимит 512 МБ, поэтому значение по умолчанию — 1.

Стоимость обхода (трек 2)

Объектов Скан S3-запросов (LIST) DB-запросов мс/объект Ремонт (удаление)
100 9 мс 1 2 0.09 1.3 s (100 DELETE)
1000 34 мс 1 2 0.034 12.2 s (1000 DELETE)
5000 166 мс 5 2 0.033 69.9 s (5000 DELETE)

Скан линеен по числу объектов и страниц LIST (1000 на страницу), число обращений к БД постоянно. Ремонт доминируется последовательными DELETE — это осознанное упрощение, возможное улучшение — пакетное или параллельное удаление.

Инъекции и восстановление

Воздействие Ожидание Наблюдение
Отказ вставки метаданных после успешного PUT объект удаляется компенсацией, ответ 503 число объектов не изменилось, после снятия инъекции загрузка снова 201
Объект без метаданных (свежий) не удаляется в пределах grace при -grace 1h deleted_objects=0, объект на месте
Объект без метаданных (старше grace) удаляется -grace 0s → deleted_objects=1, повторный прогон — 0
Метаданные без объекта, сообщение не ссылается строка удаляется deleted_metadata=1
Метаданные без объекта, сообщение ссылается строка сохраняется, попадает в отчёт retained_missing=1, строка в БД остаётся
Остановка реплики под нагрузкой без потери подтверждённых данных 85–100 успешных записей, 0 ошибок
Перезапуск всех сервисов данные и токен сохраняются PASS, volumes не тронуты
Недоступность S3 /health/live 200, /health/ready 503, восстановление 200 / 503 / 200

Аудит контракта и спорные места

Краевые случаи проверяются отдельным сьютом make test-contract (scripts/contract-audit.py, 30 проверок, evidence/contract-audit.txt). Аудит выявил три места, где реализация была мягче контракта; они исправлены:

Место Было Стало Основание
attachment_ids: null принималось как отсутствие поля 400 схема: поле — массив; «неверные типы — 400»
?variant= (пустое значение) считалось original 400 «в lab4 допустим только original»; отсутствие параметра — отдельный случай
filename из одних пробелов принималось 400 «обязательные строки не состоят только из пробельных символов»

Решения по остальным неоднозначностям:

  • Content-Type с параметрами (image/png; charset=utf-8) принимается: сравнивается медиатип, параметры не влияют.
  • Порядок проверок загрузки: Content-Type (415) → размер тела (413) → MIME по содержимому (415) → лимит пикселей (413) → целостность (415). Если нарушено несколько правил, возвращается первая сработавшая проверка; контракт приоритет не задаёт.
  • Пустой или пробельный text разрешён только с вложениями (anyOf в схеме); без вложений — 400.
  • variant проверяется до проверки членства: посторонний с неизвестным вариантом получает 400, а не 404. Существование чужого объекта это не раскрывает: для любого id ответ одинаков.
  • Ключи идемпотентности хранятся бессрочно; контракт требует лишь повтор «в течение 24 часов».
  • Неподдерживаемый HTTP-метод на известном пути даёт 405 с кодом invalid_request — контракт этот код не описывает, поведение выбрано явно.
  • 429 rate_limited есть в перечислении кодов, но rate limiting не входит в обязательный минимум и не реализован.
  • Cursor привязан к ресурсу: курсор истории чата на списке чатов и наоборот даёт 400 (проверяется аудитом).
  • S3 включён в readiness. Пока объектное хранилище недоступно, реплики выводятся из балансировщика и клиент получает 503 на любой запрос, включая текстовые сообщения; так гарантируется, что обязательный синхронный путь (сообщения с вложениями) не обслуживается частично. /health/live при этом остаётся 200 (evidence/s3-outage.txt).
  • Валидация выполняется до проверки доступа только там, где это не раскрывает существование объекта; порядок «сначала аутентификация, затем ресурс» в middleware сохранён.

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

  • Один Docker-host: отказ host, единственного PostgreSQL и единственного LB не выдерживается. Проверен только отказ одной API-реплики.
  • Reconciler — операторская утилита, запускается вручную; расписания и фонового worker'а нет (это уже тема lab5). Удаление объектов последовательное.
  • Если объект утрачен, но на него ссылается сообщение, автоматический ремонт невозможен: байты не восстановить, а удаление строки нарушило бы историю. Такие случаи остаются в отчёте reconciler'а и требуют решения оператора. В демонстрационном наборе данных есть одно такое вложение — оно появилось в результате учения и остаётся видимым в missing.
  • Тело загрузки буферизуется в память: верхняя граница — MAX_CONCURRENT_UPLOADS × MAX_UPLOAD_BYTES (по умолчанию 80 MiB) плюс один декод.
  • Нет ограничения частоты запросов, TLS/mTLS, асинхронной обработки и вариантов изображений — это следующие лабораторные.
  • filename хранится как отображаемое имя и не используется в ключах; санитизация ограничена контролем недопустимых символов.