Files
mtusi2026lab4/REPORT.md
T

16 KiB
Raw Blame History

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

  • Автор, группа: Казанцева Виктория / БПИ2301
  • Целевая оценка; выбранный трек 5: 5, трек 2 — согласованность PostgreSQL и S3
  • Commit/PR: запрос на слияние в mtusi2026/mtusi2026lab4, базовая ветка main
  • Источники и библиотеки: контракт репозитория, документация S3 и MinIO; FastAPI, uvicorn, asyncpg, argon2-cffi (Argon2id), boto3, Pillow.

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

Машина проверки: Windows, Docker Desktop 29.2.1, CPU Intel i7-12650H, 16 ГБ RAM. Лимит каждой API-реплики — 768 МиБ. Публичные тесты на Windows нужно запускать с PYTHONUTF8=1: tests/client.py читает OpenAPI через Path.read_text() без кодировки.

Образы, все с фиксированной версией или digest:

Роль Образ Digest
API python:3.12-alpine@sha256:d09d15e60962ca365d1cd544a48773bac9d33f2fb1b00f2aa0deec78ade7dc31 Python 3.12.14 внутри контейнера
PostgreSQL postgres:16.8-bookworm sha256:301bcb60b8a3ee4ab7e147932723e3abd1cef53516ce5210b39fd9fe5e3602ae
S3 minio/minio:RELEASE.2025-09-07T16-13-09Z sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e
Клиент bootstrap mc RELEASE.2025-08-13T08-35-41Z, скопирован из образа MinIO тот же digest MinIO
Балансировщик haproxy:2.8.14-alpine sha256:72030a2e37d5c5790e13387da24f890bf860b8dfef10fab1b1fd0fd2e974ff75

Порты MinIO, включая консоль :9001, наружу не публикуются. Снаружи только 127.0.0.1:8080 балансировщика.

python scripts/init_env.py
docker compose --env-file .env up -d --build

scripts/init_env.py создаёт локальный .env и не перезаписывает существующий. Секреты в отчёт и git не входят. Схема создаётся при старте API из infra/migrate.sql под advisory lock. Bucket и пользователь API создаёт одноразовый s3-init (infra/bootstrap-s3.sh); повторный запуск идемпотентен.

Дождаться GET /health/ready → 200 {"status":"ok"}. Затем:

python tests/smoke.py --base-url http://127.0.0.1:8080
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
python tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080

На Windows тот же сценарий выполняет scripts/restart.exe и scripts/stop-one.exe (исходник scripts/labhook.cs): команды совпадают с .sh, потому что subprocess не запускает shell-скрипт. После failover остановленную реплику возвращают отдельно: docker compose --env-file .env start api-1 api-2.

Остановка без удаления данных: docker compose --env-file .env down. Учебные volume удаляет только явная команда docker compose --env-file .env down -v.

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

Клиент → HAProxy (lb, round-robin, проверка /health/live) → api-1 и api-2 → PostgreSQL и приватный bucket MinIO.

Из lab3 сохранены регистрация, Argon2id-сессии в PostgreSQL, чаты, keyset-история, Idempotency-Key с advisory lock на пользователя+метод+путь+ключ и заголовок X-Instance-Id (api-1 / api-2). Сессии и сообщения переживают рестарт, TTL сессии рестарт не продлевает.

Вложение: байты лежат в S3 по ключу o/<uuid>, который назначает сервер. filename только отображаемое имя. Метаданные, связь с чатом и ссылки из сообщений — в PostgreSQL. У API нет volume. 201 возвращается после успешного PUT и COMMIT строки attachments вместе с переводом ledger в committed. Если PUT прошёл, а commit нет, процесс удаляет объект и помечает ledger aborted. Если удаление тоже не удалось, объект остаётся staging: reconciler заберёт его только после grace period 120 секунд. Свежий staging не трогается, потому что загрузка может ещё идти.

Переменные .env.example отображаются так: DATABASE_URL собирается в Compose из POSTGRES_*; S3_ENDPOINT=http://minio:9000 только во внутренней сети; ключ API — S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY. Root MinIO есть у minio и s3-init, у процесса API его нет. Политика пользователя API: GetObject, PutObject, DeleteObject на объекты bucket и ListBucket/GetBucketLocation на сам bucket.

Пароль: Argon2id, time_cost 2, memory 19 МиБ, parallelism 1. Для отсутствующего пользователя выполняется verify фиктивного хеша.

Курсор истории — непрозрачная строка с chat_id. Чужой чат даёт 400. Порядок (created_at, id). Снимок между запросами не обещается: created_at берётся из clock_timestamp() в момент вставки.

Чтение изображения ограничено 10 МиБ до разбора. Число пикселей читается из заголовка PNG/JPEG и сравнивается с 40 млн до Pillow. Полный load() делается только до 1 млн пикселей, чтобы одна загрузка не разворачивала 40-мегапиксельный буфер. Файл на время проверки пишется во временный файл контейнера и удаляется; каноническая копия — объект S3.

/health/live не смотрит зависимости. /health/ready требует SELECT 1 и доступность bucket. Балансировщик проверяет live, поэтому остановленный процесс выпадает из пула, а живой процесс при недоступном S3 продолжает отвечать 503 на ready.

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

Критерий Команда Результат Файл
Публичный smoke python tests/smoke.py --base-url http://127.0.0.1:8080 PASS: lab4 public API scenario на финальной сборке вывод команды
Контракт skeleton python scripts/check_contract.py PASS: offline skeleton structure вывод команды
JPEG, checksum, участник чата python tests_student/negative.py 201, SHA-256 совпал, скачивание вторым участником побайтово вывод PASS: negative...
Слишком большой файл тот же прогон 413 payload_too_large там же
Повреждённый PNG и подмена MIME тот же прогон 415 unsupported_media_type, не 500 там же
Опасные filename тот же прогон 400 invalid_request там же
Чужой attachment и файл другого чата тот же прогон 404 not_found для метаданных, байтов и attachment_ids там же
Пиксельная бомба 20000×20000 тот же прогон 413 до декодирования там же
Параллельный idempotency python tests_student/idempotency_race.py 8 повторов, один id в истории PASS: eight parallel...
Приватный bucket python tests_student/private_bucket.py анонимные GET и List → 403; порты MinIO не опубликованы; у API нет mounts и нет MINIO_ROOT_USER вывод команды
10 одновременных загрузок python scripts/memory_experiment.py 10/10 для 12420 байт и для 3241218 байт evidence/memory.json
Reconciler, трек 2 python scripts/reconcile_experiment.py dry-run 2 действия, повторный dry-run 0; свежий orphan и in-use metadata сохранены evidence/reconcile.json
Недоступность S3 python scripts/s3_outage.py live 200, ready 503, после start тот же SHA-256 evidence/s3_outage.json
Рестарт с volume tests/resilience.py --mode persistence --action-script scripts/restart.exe PASS: persistence preserved confirmed data and existing session вывод команды
Отказ одной реплики tests/resilience.py --mode failover --action-script scripts/stop-one.exe до отказа 2 реплики; 106 успешных записей, 1 ошибка; первое восстановление 2.390 с; PASS вывод команды

Память. Гипотеза: десять загрузок не занимают неограниченную RAM, потому что тело режется лимитом 10 МиБ, пишется во временный файл чанками и не декодируется в bitmap, если пикселей больше 1 млн. Волна 12 КиБ заняла около 0.37 с, пик docker stats 56.2 и 57.2 МиБ, VmHWM около 73 МиБ и за волну не вырос. Волна 3.24 МиБ × 10 заняла 0.74 с. Пик docker stats 65.2 МиБ на api-1 и 53.6 МиБ на api-2. VmHWM вырос с 74892 до 77184 КиБ и с 74776 до 76492 КиБ, то есть примерно на 2 МиБ на процесс, а не на 10 × 3.24 МиБ. Ограничение измерения: волна короче секунды, docker stats снимался каждые 0.25 с и включает page cache; VmHWM — честный максимум RSS процесса после рестарта перед волной.

Трек 2. Гипотеза: полный обход с grace 120 с удаляет только просроченный orphan и метаданные без объекта, на которые не ссылается сообщение; повторный запуск ничего не удаляет. Методика: через API сохранены свежее вложение в сообщении и свежее вложение без сообщения; app.admin inject добавил свежий staging-объект, staging возрастом 2 часа, строку без объекта возрастом 2 часа и такую же строку, на которую ссылается сообщение. Dry-run увидел 27 объектов за 1 страницу ListObjects, 129.4 мс, из них 127.2 мс — список S3 и 2.0 мс — запросы к PostgreSQL. Действия: удалить old-orphan и fault-stale-missing. Пропущены fresh_orphan и in_use_missing. Apply повторил те же два действия за 154.3 мс. Второй dry-run: action_count=0, объектов 26. Скачивание свежего вложения из сообщения совпало с fixture. Ограничения: это полный обход одного bucket, не инкрементальный; возраст orphan считается по ledger, потому что LastModified MinIO из лаборатории не переписывается; пропавшие байты используемого вложения не восстанавливаются, строка остаётся, content отвечает 404; reconciler запускается оператором, а не постоянным циклом.

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

Воздействие Что ожидаем Что наблюдали Восстановление
Рестарт API, PostgreSQL, MinIO и LB с сохранением volume прежний токен, сообщение и байты вложения PASS публичного persistence-теста стек снова ready, данные на месте
stop реплики, обслужившей пробный POST запись продолжается через вторую реплику, подтверждённые сообщения без дублей 2 реплики до отказа, 106 успехов, 1 ошибка, восстановление 2.390 с, остановленная реплика не в последних ответах реплика остаётся остановленной, пока её явно не запустить
Остановка MinIO live 200, ready 503, после старта те же байты именно так оригиналы в volume MinIO

Один Docker-host не переживает потерю этой машины. Один PostgreSQL и один MinIO не являются отказоустойчивой парой. Эксперимент показывает потерю одной API-реплики и краткую недоступность S3, не потерю диска.

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

Пользовательские ошибки загрузки остаются 400/404/413/415. Полный decode сознательно ограничен 1 млн пикселей: файл до 40 млн пикселей принимается после заголовка и verify(), но редкое повреждение большого файла может быть не поймано так же строго, как у маленького. Grace 120 с защищает незавершённую загрузку и одновременно откладывает уборку мусора на этот срок. Секреты живут в локальном .env, не в образе.

Ответы, которые пригодятся на защите

Файл в volume одной API-реплики не равен объектному хранилищу: у второй реплики этого диска нет, рестарт контейнера без общего volume его теряет, а bucket с собственным volume читают обе реплики.

201 честно отдаётся только когда объект уже записан в S3 и строка метаданных закоммичена. До commit клиент получает ошибку и может повторить загрузку отдельным запросом: у загрузки нет Idempotency-Key.

Если S3 PUT прошёл, а COMMIT нет, ответ не 201. Компенсация удаляет объект. Если удалить не удалось, reconciler после 120 с видит staging без строки attachments и удаляет объект. Повторный dry-run после apply пустой.

Случайный ключ и закрытый bucket не заменяют ACL: любой авторизованный пользователь, не состоящий в чате, должен получать 404 и на метаданные, и на байты. Проверка членства делается в API. Анонимный GET в MinIO и так отвечает 403, это отдельная граница.