22 KiB
Отчёт - лабораторная 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
Шаги запуска:
-
Клонировать fork и перейти на ветку solution:
git clone https://gitea.privcloud.tech/Maximillan_Mercer/mtusi2026lab4-fork.git cd mtusi2026lab4 git checkout solution/BVT2303-Golikov -
Создать локальные 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/* -
Создать .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.
-
Собрать образ API и запустить стек:
docker compose build api docker compose up -d -
Дождаться, пока 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. -
Прогнать публичный smoke и проверки от scaffold:
PYTHONUTF8=1 make check PYTHONUTF8=1 make test -
Проверки сохранности и отказа (требуют 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:
- Отдельный сервис minio (pgsty/silo), persistent volume minio_data.
- Одноразовый сервис mc-init: создаёт bucket, policy, API-user. Идемпотентен.
- Миграция 0003: таблицы attachments и message_attachments, индексы, ограничения (status, size, sha256, content_type, filename).
- Миграция 0004: ослаблен CHECK messages_text_not_blank - пустой текст разрешён при наличии вложений (lab4 anyOf), но whitespace-only по-прежнему запрещён.
- Три endpoint: POST /chats/{chat_id}/attachments (raw bytes PNG/JPEG, max 10 MiB, max 40M пикселей), GET /attachments/{id} и GET /attachments/{id}/content (без redirect, только участникам чата).
- POST /messages принимает attachment_ids (0-10), все вложения должны принадлежать этому чату и быть ready; anyOf text или attachments.
- RequestHash расширен: sha256(text) без attachments (обратная совместимость с lab3), sha256(text + 0x00 + ids) с attachments.
- Reconciler в API, pg advisory lock, две задачи (stale pending, orphan objects), grace 1 час.
- Healthcheck /health/ready пингует S3 (BucketExists).
- 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 |
Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| TODO | TODO | TODO | TODO |
Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.