Files

27 KiB
Raw Permalink Blame History

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

  • Автор, группа: Унру Д.В. БПИ2303
  • Целевая оценка; выбранный трек 5, если нужен: 3 (трек 5 не заявлен)
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: FastAPI, Pydantic v2, Uvicorn, Psycopg 3, redis-py, argon2-cffi, boto3/botocore, Pillow, pytest; документация S3 uploads, Pillow Image, Boto3 configuration, MinIO IAM, Nginx upstream.

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

git clone <fork-url> && cd <каталог-fork-лабораторной-4>
make up                 # secrets → сборка API/MinIO/mc → migrate/init → api×2/cleanup/Nginx
curl -fsS http://localhost:8080/health/ready
docker compose ps --all  # API×2/PG/Redis/MinIO/cleanup/LB работают; migrate и minio-init — Exited(0)

make check
make validate-container
make test                # публичный smoke lab4 через Nginx
make test-student        # 21 собственный интеграционный тест
make test-fresh          # миграции 001–003, новый bucket и тесты на отдельных пустых volumes
make test-attachments    # private bucket, upload→отказ API→download, обрыв, crash+cleanup, отказ S3
make uploads             # 10 одновременных загрузок с измерением пика RAM
make test-cluster        # сохранённые проверки общей сессии/idempotency/restart/failover/SIGTERM/rolling

make up выполняет bootstrap, docker compose build api minio minio-init, затем up --wait и ожидание двух API-alias через LB. При повторной сборке Go/Python-слои используются из кэша. Сценарии отказов и замер памяти запускать по одному: они останавливают/пересоздают контейнеры. make uploads пересоздаёт только API, чтобы сбросить kernel memory high-water marks; volumes и данные сохраняются.

Почему MinIO собирается из исходников: проверенные release-образы в Docker Hub/Quay недоступны, официальный архив бинарников ответил 410. В infra/minio/Dockerfile собираются официальные теги и проверяется точный commit: MinIO RELEASE.2025-04-22T22-12-26Z / 0d7408fc9969caf07de6a8c3a84f9fbb10a6739e, mc RELEASE.2025-04-16T18-13-26Z / b00526b153a31b36767991a4f5ce2cced435ee8e. Builder — golang:1.24.2-bookworm, зависимости сверяются по upstream go.sum. Runtime-образы локальные mtusi-lab4-minio:2025-04-22 и mtusi-lab4-mc:2025-04-16; скачивать готовый сервер преподавателя не требуется.

bootstrap.sh однократно создаёт пароль БД, root-credentials MinIO и отдельные API S3 credentials в secrets/; повтор их не меняет. Каталог 0700 на хосте, файлы доступны нужному uid через Compose secrets. Root S3 secrets получает только MinIO и minio-init; API/cleanup получают ограниченного пользователя. .env, secrets и volumes не входят в Git/build context. Учебные данные и credentials lab3 не копировались.

Безопасная остановка: make down, именованные volumes postgres_data, redis_data, minio_data сохраняются. Намеренное удаление всех учебных данных: docker compose down --volumes. Restart hook volumes не удаляет. make test-fresh удаляет только созданные им временные volumes отдельного проекта. После обычных тестов синтетические пользователи/сообщения/вложения остаются — delete не входит в обязательный API.

Отдельные команды:

make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# После отдельного публичного failover восстановить остановленную реплику:
docker compose up -d --no-recreate --wait --wait-timeout 90
python3 scripts/cluster.py wait

make cleanup-dry-run
# Явная безопасная очистка с обычным grace 300s:
docker compose run --rm --no-deps cleanup python -m messenger.cleanup --apply

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

клиент → Nginx → API ×2 ──→ PostgreSQL: пользователи/чаты/сообщения/сессии/metadata/связи
                       ├─→ Redis: кэш публичного профиля
                       └─→ MinIO: оригинальные байты, приватный bucket

migrate → PostgreSQL       minio-init → bucket/user/policy
cleanup → S3 listing + PostgreSQL recheck → удаление только старых неучтённых объектов
  • Перенос из lab3. Сохранены Nginx, два экземпляра одного service api, общая PostgreSQL, Argon2id/Basic→Bearer, Redis cache-aside профиля, keyset-пагинация, X-Instance-Id и транзакционная идемпотентность сообщений. Сохранены публичные tests/contracts/README текущего skeleton. Служебные документы находятся отдельно в lab4/docs/.
  • Схема (003_attachments.sql). attachments: UUID PK, chat_id/owner_id FK, составной FK на членство, filename, MIME, размер 1–10 MiB, SHA-256, уникальный object_key, created_at/updated_at. message_attachments: FK на сообщение/вложение, position 0–9, уникальны пара и позиция. Байты не хранятся в PostgreSQL. Проверка same-chat перед INSERT связи даёт 404 для чужого/неизвестного attachment_id. Любой участник может использовать доступное вложение своего чата.
  • Совместимость сообщения. В ответах добавлен attachment_ids; в запросе по умолчанию []. Пустой/пробельный text допустим только с вложением. Список не содержит дублей, до 10 UUID, порядок сохраняется. Отсутствие списка и [] дают одинаковый fingerprint; пустой список не включается в fingerprint, поэтому сохраняется hash прежних text-only запросов lab3. Replay возвращает прежний Message 201, другой валидный body 409, доступ и сессия перепроверяются.
  • Пути и ACL. Object key — originals/<случайный UUID>, не filename и не публичный URL. Имя — только отображаемое поле: 1–255 Unicode code points, не пустое, без slash/backslash/NUL/control. Сначала Bearer и членство, затем загрузка; metadata/content доступны только участникам, посторонний/неизвестный объект 404. Публичный JSON не раскрывает object key, bucket, endpoint или credentials.
  • Получение файла. POST принимает сырой PNG/JPEG, не multipart. Content-Length проверяется заранее, но фактически полученные bytes тоже считаются. Тело читается через Request.stream в TemporaryFile на диске, SHA-256 считается по ходу. Лимит 10 MiB и абсолютное ожидание тела 30 с; слот загрузки ожидается до 1 с. Файл удаляется/закрывается в finally, постоянной локальной копии оригинала у API нет.
  • Проверка изображения. Pillow определяет формат и размеры до load; MIME должен совпадать. >40 млн пикселей даёт 413 до полной распаковки. verify проверяет структуру, повторный open/load — декодирование. Повреждённый/неподдерживаемый файл 415, слишком большой 413, опасное имя 400. Текстовые PNG chunks ограничены 1 MiB. На API один decoder и не более 6 одновременно обрабатываемых upload: несколько больших распаковок не размножают расход RAM. Оригинальные байты не перекодируются; crop/thumbnail/очереди относятся к следующим работам.
  • Буферы Nginx. На upload-route client_max_body_size 11 MiB, чтобы 10 MiB+1 дошёл до API и получил 413; client_body_buffer_size 64 KiB, остальное буферизуется на диск. proxy_request_buffering on, максимум 16 параллельных загрузок на LB, inactivity timeout тела 10 с, upload read/send timeout 30 с. Это сознательное дисковое буферизование, не обещание мгновенного приёма произвольно медленного клиента.
  • 201 и согласованность. После валидации API начинает PG-транзакцию и берёт advisory lock от object_key. Затем выполняются S3 PUT и INSERT metadata; 201 возвращается только после успешного COMMIT. У S3 и PostgreSQL нет общей атомарной транзакции. Подтверждённые metadata доступны всем API, оригинал находится в общем MinIO.
  • Компенсация неизвестного результата. Ошибка PUT/SQL/COMMIT вызывает новую проверку под тем же lock. Объект удаляется только если БД точно подтверждает отсутствие metadata. При неизвестном COMMIT или недоступной БД слепого DeleteObject нет: уже учтённый файл должен остаться, неучтённый подберёт janitor. Обрыв неполного клиентского тела не начинает S3 PUT; аварийное завершение после PUT может оставить orphan.
  • Автоматическая очистка. Отдельный cleanup-service каждые 60 с листает только originals/* страницами до 1000 объектов. Grace по умолчанию 300 с, минимум 60 с. Для старого кандидата pg_try_advisory_xact_lock и свежий SELECT повторно проверяют metadata; учтённый/свежий/активно заблокированный объект пропускается. При ошибке БД удаления не происходит. Dry-run не удаляет, повтор apply идемпотентен. Здесь реализована компенсация/orphan cleanup уровня 4, не полный исследовательский reconciler из трека 5 и не восстановление missing bytes.
  • Скачивание. GET content возвращает StreamingBody S3 кусками 64 KiB через авторизованный API, без redirect. До 8 открытых S3-stream на API; close/release выполняется в finally ответа, включая ошибку отправки headers и disconnect. Content-Length сверяется с metadata. Variant в lab4 разрешён только original; прочие значения 400. Истинный MIME и RFC5987 filename передаются в headers.
  • MinIO и права. minio-init идемпотентно создаёт bucket, запрещает anonymous, создаёт отдельного API user и policy. Get/Put/Delete разрешены только originals/* этого bucket; ListBucket — только для этого prefix; GetBucketLocation — для bucket. CreateBucket, чужие bucket/prefix и admin-права не выдаются. Console слушает 127.0.0.1:9001 внутри MinIO, не опубликована и недоступна из API-сети. Приватный bucket не заменяет ACL приложения.
  • Здоровье и таймауты. Readiness требует PostgreSQL, совместимую схему и доступный S3 bucket с API credentials; Redis — необязательный кэш. Boto3 connect 1 с/read 3 с, одна попытка, пул/stream gate 8. PG-пул 8 на API, ожидание 2 с, statement 3 с/lock 2 с. S3 outage даёт 503 API либо 502/503/504 LB после исключения backend. Nginx OSS использует Docker DNS resolve и пассивные max_fails 1/fail_timeout 2 с; активный health_check Plus не используется. SIGTERM/rolling сохраняют схему lab3.

Роли, ресурсы и запуск:

Service Версия / ресурсы Данные, сеть и готовность
api×2 mtusi-lab4-api:lab4; каждая 1 CPU/512 MiB, uid10001 front+data, без host ports; HTTP ready, только ограниченные S3 secrets
lb nginx:1.28.0-alpine; 0.5 CPU/128 MiB только front; единственный public endpoint 127.0.0.1:8080
postgres postgres:17.5-bookworm; 1 CPU/512 MiB internal data; postgres_data, pg_isready
redis redis:7.4.4-bookworm; 0.25 CPU/128 MiB internal data; redis_data, AOF, ping
minio официальный release 2025-04-22, сборка из pinned source; 1 CPU/512 MiB, uid10002 internal data; minio_data; HTTP /minio/health/ready; root secrets
minio-init официальный mc release 2025-04-16, сборка; 0.25 CPU/128 MiB root+API secrets, policy read-only, Exited(0)
migrate образ API; 0.5 CPU/256 MiB только DB secret, версии/lock/checksum, Exited(0) до API
cleanup образ API; 0.25 CPU/192 MiB DB+ограниченные S3 secrets, только data, цикл 60 с

Python 3.13.5, библиотеки и транзитивные зависимости закреплены в requirements.lock. В .env реально используется SESSION_TTL_SECONDS; S3_ENDPOINT/REGION/BUCKET и *_FILE задаются Compose. Контрактные пределы 10 MiB/40 Mp не увеличиваются через переменные. Отдельные migrate и minio-init завершаются до API. Dockerfile приложения не запускает миграции каждой репликой.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Контракт и публичный API (3) make check/validate-container/test PASS: lab4 public API scenario, checksum, ACL и сообщения с ids evidence/check.txt, openapi.txt, smoke.txt
Метаданные в PG, bytes в приватном S3 (3) схема 003, security test, download готовые originals в bucket, API не раскрывает key; anonymous 403 migrations/003_attachments.sql, evidence/s3-security.json
PNG/JPEG и исходные bytes (3) собственные тесты + smoke 201 ready, SHA-256/размер/bytes совпадают, image-only сообщение валидно evidence/student-tests.txt, smoke.txt
Byte/pixel/MIME/filename ограничения (3) тесты повреждений, >10 MiB, chunked, >40 Mp header 400/413/415; pixel limit до load, пользовательская ошибка не 500 evidence/student-tests.txt
Upload на одной, download на другой (3) verify_attachments.py failover остановлен точно upload-instance; другой вернул тот же hash/bytes evidence/attachment-failover.json
Полный restart с S3 volume (3) verify_cluster.py persistence прежняя сессия, metadata и оригинал доступны; реальные процессы перезапущены evidence/persistence.txt, persistence.json
Прежняя балансировка/идемпотентность (3) test-cluster, собственные регрессии concurrent replay, failover/SIGTERM/rolling проходят evidence/concurrent-idempotency.json, public-failover.txt, sequential-failover.json, graceful-shutdown.json, rolling-update.json
Все отрицательные случаи файлов/чужих ids (4) make test-student 21 тест PASS, включая MIME, corrupt/oversize, чужой attachment и другой чат evidence/student-tests.txt
Компенсация после PUT/DB failure (4) SQL trigger перед metadata INSERT, затем реальный SIGKILL SQL-сбой 503 компенсирован; orphan после kill обнаружен и удалён после grace evidence/student-tests.txt, orphan-cleanup.json
Безопасная очистка (4) dry-run/apply/repeat; fresh/tracked/locked dry-run: 0 удалений; apply удалил orphan; повтор 0; свежий/используемый/locked сохранены evidence/orphan-cleanup.json
Потоковая обработка и RAM при ≥10 загрузках (4) make uploads 10/10 одновременно, 2 API, 0 ошибок/OOM; пик 205.824/214.730 MiB при 512 MiB evidence/concurrent-uploads.json
Bucket bootstrap идемпотентен, IAM ограничен (4) повтор minio-init; прямые S3-запросы objects/metadata не изменились; anonymous 403, CreateBucket 403, другой prefix: 403 evidence/s3-security.json
Консоль не открыта (4) socket из API к minio:9001; infrastructure snapshot соединение не установлено, root secret в API не смонтирован, host ports только у LB evidence/s3-security.json, infrastructure.json
Миграции/инициализация с нуля make test-fresh schema 001–003 и private bucket на новых volumes, тесты PASS evidence/fresh-migrations.txt

Pytest также выводит предупреждение старой закреплённой botocore об utcnow в Python 3.13 и диагностическое предупреждение Pillow в тесте pixel-bomb; проверки результата 413 и все assertions проходят. Публичные проверки и контракт не ослаблялись.

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

Исследовательский трек 5 не выполнялся. Файлы синтетические. Обрыв тела и сбой между PUT/COMMIT проверяются раздельно: одного успешного API-запроса недостаточно для доказательства компенсации.

Воздействие Что ожидаем Что наблюдали Восстановление / потери
Upload → stop обслужившей API → download файл читается через другую API тот же SHA-256 и bytes, другой alias 1.988 с от старта действия / потерь нет
Обрыв HTTP upload неполное тело не создаёт объект/metadata из 500000 объявленных передано 108 bytes, TCP закрыт; counts не изменились orphan нет
Ошибка INSERT metadata после S3 PUT rollback PG и компенсация S3 HTTP 503, нет строки и нового объекта подтверждения не было
SIGKILL после PUT, до COMMIT неподтверждённый объект может остаться и будет очищен наблюдался exit 137; объект есть, metadata нет; после 61 с реального ожидания dry-run показал кандидата, apply удалил его orphan устранён, 201 не выдан
Repeat cleanup, fresh/linked/locked безопасные повторы повтор не удаляет объекты; свежий и используемый сохранены, объект под lock сохранён до unlock потерь используемых данных нет
MinIO недоступен ограниченная ошибка без ложного 201 upload 503 за 0.2487 с; после старта прежний оригинал читается тот же токен, bytes сохранены
Полный restart API/PG/Redis/MinIO/cleanup/Nginx сессия и оригинал переживают restart public persistence PASS именованные volumes сохранены

Методика crash/cleanup: временный BEFORE INSERT trigger задерживает ровно одно имя файла через pg_sleep(2). После наблюдения INSERT в pg_stat_activity и появления объекта в S3 API получает SIGKILL. Metadata не зафиксирована, 201 не отправлен. Контейнер восстановлен, trigger удалён. После настоящего 61-секундного ожидания применяется grace 60 с. Дополнительно проверены старый объект под advisory lock, свежий объект и старое вложение, связанное с сообщением. После снятия lock его тестовый orphan также удалён. В обычном запуске grace 300 с, цикл 60 с; при недоступной БД уборка откладывается.

Память при десяти загрузках: воспроизводимый RGB PNG 3000×1000, 9002318 bytes, zlib level 0, строки из SHAKE-256. Один неизменяемый payload используется десятью клиентскими потоками с barrier. Все десять HTTP-интервалов перекрывались 0.345 с, завершились 201, обе API наблюдались, ошибок 0. Время группы 1.563 с. Один оригинал скачан другим участником и побайтно сверен.

Перед опытом API пересозданы, чтобы memory.peak и VmHWM относились к этому запуску. Peak включает startup/bootstrap/загрузки/контрольное скачивание. Kernel high-water mark не пропускает короткие пики между samples:

API-процесс Cgroup memory peak PID 1 VmHWM Лимит OOM
Первый 205.824 MiB 182.871 MiB 512 MiB 0
Второй 214.730 MiB 183.293 MiB 512 MiB 0

Cgroup включает cache и вспомогательные процессы, VmHWM — resident peak API. Профиль, версии, limits, baseline/final, интервалы запросов и checksum — в evidence/concurrent-uploads.json. Опыт показывает расход памяти этого профиля, а не максимальный throughput или универсальный RSS для всех допустимых JPEG/PNG. Сценарии lab3 под текстовой нагрузкой сохранены отдельно; их числа не заменяют эксперимент с файлами.

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

  • Один Docker-host, одна PostgreSQL и один MinIO: отказ узла/диска и HA хранилищ не покрываются. Named volume не заменяет backup. Потерянные bytes из missing object janitor восстановить не может.
  • S3 и PostgreSQL неатомарны. Между PUT и COMMIT есть окно orphan; компенсация и grace-cleanup закрывают его после восстановления зависимостей. При недоступной БД удаление запрещено; время уборки не является SLA.
  • Janitor удаляет только неучтённые старые объекты. Учтённое, но никуда не прикреплённое вложение сохраняется: в обязательном API нет delete/retention для таких файлов.
  • Readiness считает S3 критичной зависимостью. При S3 outage Nginx может исключить обе API, и text-only запросы тоже станут недоступны, хотя PG жив. Внутренний live процесса остаётся 200.
  • Таймауты SDK/Nginx относятся к отдельным операциям I/O. После начала HTTP download нельзя заменить частичное 200 структурированным 503; клиент проверяет размер/checksum.
  • Нагрузочный замер: десять одновременных загрузок по 9 MB, две API, один прогон. Исследования максимального RPS, presigned upload, thumbnail/crop и фоновой обработки lab5 не проводились.
  • MinIO собран из закреплённого исторического релиза; стенд локальный и учебный. HTTP/Basic только на localhost с синтетическими данными; TLS, rotation, secret manager и полное разделение DB privileges оставлены следующим работам.
  • Между страницами нет общего snapshot. Сохраняются оговорённые в lab3 ограничения часов и конкурентных вставок. Breaking DB migrations потребуют отдельной стратегии.