Files
mtusi2026lab4/REPORT.md
T

23 KiB
Raw Blame History

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

  • Автор, группа: Алёна Курлова, БВТ2301
  • Целевая оценка; выбранный трек 5: 5, трек 2 «Согласованность двух хранилищ»
  • Commit/PR: PR #49, основной коммит ba6e32a, ветка solution/bvt2301-kurlova
  • Источники, библиотеки, помощь ИИ: FastAPI, psycopg, boto3, Pillow, MinIO; код лабы 3 перенесён и расширен. Реализацию, тесты и черновик отчёта выполнял Claude Code (ИИ) под руководством автора; результаты прогонов ниже получены на локальном стенде.

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

Prerequisites: Docker Desktop (Compose v2), Python 3.9+, вход docker login (Docker Hub). Проверено на macOS, arm64.

cp .env.example .env            # значения в примере совпадают с теми, на которых получены evidence/
mkdir -p secrets
printf 'messenger'          > secrets/postgres_password
printf 'postgresql://messenger:messenger@postgres:5432/messenger' > secrets/database_url
printf 'valkey://valkey:6379/0' > secrets/cache_url
printf 'messenger_root'     > secrets/minio_root_user
python3 -c "import secrets;print(secrets.token_urlsafe(24),end='')" > secrets/minio_root_password
printf 'messenger_app'      > secrets/s3_access_key_id
python3 -c "import secrets;print(secrets.token_urlsafe(24),end='')" > secrets/s3_secret_access_key
docker compose --env-file .env up -d --build   # postgres, valkey, minio, minio-init, migrate, api-1, api-2, nginx
make test                                      # ждёт готовности по /health/ready

Остановка с сохранением данных: docker compose stop. Намеренное удаление учебных данных: docker compose down -v. Каталог secrets/ и .env в git не попадают.

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

Роль Сервис Версия Health Volume Сеть / порт Credentials
LB nginx 1.27.3-alpine /health/live; health-скрипт опрашивает /health/ready реплик — 127.0.0.1:8080 —
API ×2 api-1, api-2 собираются из исходников, python 3.12.8 /health/ready нет (stateless) только внутренняя сеть Docker secrets
БД postgres 17.7-alpine@sha256 pg_isready pgdata внутренняя secret
Кэш сессий valkey 8.1-alpine@sha256 valkey-cli ping нет внутренняя —
S3 minio madlabcg/minio@sha256:ad134b2d… mc ready local miniodata внутренняя, порты и консоль не опубликованы (MINIO_BROWSER=off) root-secret только у minio и minio-init
Bootstrap S3 minio-init тот же образ — — — root + app secrets

Источник истины. Метаданные — PostgreSQL (attachments, message_attachments), байты — приватный bucket. Object key назначает сервер (attachments/<uuid4>), filename хранится только как отображаемое имя.

Порядок записи и границы согласованности (ответ на «что если PUT прошёл, а COMMIT нет»):

  1. тело читается потоком в SpooledTemporaryFile (1 MiB в RAM, остальное во временный файл), считается SHA-256, лимит 10 MiB применяется на лету; MIME проверяется по magic bytes и Pillow, лимит пикселей проверяется по заголовку до декодирования; целостность проверяет app/imagecheck.py: для PNG собственный потоковый сканер (CRC всех chunk'ов, поля IHDR, zlib-поток разжимается порциями по 1 MiB, filter-байт каждой строки ∈ 0..4, размер данных точно равен вычисленному по IHDR, Adam7 учитывается), для JPEG полное декодирование через libjpeg в масштабе 1/8 (память ~1/64 изображения) плюс проверка маркера EOI;
  2. в БД вставляется строка status='uploading' (коммит);
  3. PUT в S3;
  4. UPDATE … SET status='ready' WHERE status='uploading' — только после этого клиент получает 201.

Любой сбой между шагами оставляет либо uploading-строку (с объектом или без), либо ничего. Клиентам такие строки не видны (404), прикрепить их к сообщению нельзя. Объект без строки получиться не может, потому что строка вставляется раньше. При ошибке API сам пытается компенсировать (удалить объект и строку); то, что не удалось, собирает reconciler.

Reconciler (app/reconcile.py, CLI scripts/reconcile.py, фоновый цикл в каждом API раз в RECONCILE_INTERVAL_SECONDS=300 с, grace RECONCILE_GRACE_SECONDS=900 с). Работает под pg_try_advisory_lock, поэтому две реплики не дублируют работу. Правила:

  • uploading старше grace и объект (если есть) старше grace по LastModified → удалить объект и строку; старая строка со свежим объектом не трогается (повторная проверка HEAD перед удалением);
  • объект без строки и старше grace → удалить (перед удалением строка перепроверяется);
  • ready-строка, подтверждённая (updated_at) раньше grace, без объекта (перепроверка HEAD) → status='failed', error_code='object_missing'; строка не удаляется, даже если на неё ссылается сообщение;
  • по умолчанию dry-run (--apply меняет данные), повторный запуск идемпотентен.

Что изменено в lab3-коде. Сообщение принимает attachment_ids (0–10) и допускает пустой text при наличии вложений (миграция 0004 ослабляет CHECK). Хеш идемпотентности включает attachment_ids; повтор без ключа attachment_ids равен []. Критичные зависимости /health/ready: PostgreSQL и S3. Недоступность любой из них даёт 503 в общем формате ошибки с X-Instance-Id; состояние S3 обновляется фоновой пробой раз в секунду (отдельный клиент с таймаутами 1 с / 1.5 с, чтобы зависший S3 не вешал проверку). При этом недоступный S3 не блокирует остальной API: текстовые сообщения и метаданные продолжают работать (запросы блокируются только при недоступной БД), а вложения отвечают 503. Чтобы 503 не выбивал реплики из upstream и клиенты не видели 502, nginx не использует http_503 как признак сбоя для /health/, /attachments/ и upload; если обе реплики не готовы, health-скрипт оставляет обе в ротации. nginx также отдаёт JSON-ошибку 413 (с X-Request-Id) для тел больше client_max_body_size 11m. S3-клиент: без повторов, connect 3 с, read 6 с; компенсация при сбое PUT выполняется в фоне.

Дополнительная валидация входных данных. filename: 1..255 code points, не только пробелы, не ./.., без /, \ и любых символов категорий Cc/Cs/Zl/Zp (в том числе DEL и C1). Idempotency-Key не обрезается (HTTP-парсер уже убирает крайние пробелы); порядок attachment_ids сохраняется в ответе, повторе и истории, переставленный список с тем же ключом — 409.

Права S3. API использует отдельного пользователя messenger_app с политикой infra/minio/app-policy.json: Get/Put/DeleteObject только на attachments/* и ListBucket. Bucket создаёт и делает приватным infra/minio/init.sh; скрипт идемпотентен (mb --ignore-existing, повтор политики и пользователя безвреден), запускается при каждом up.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make test PASS (загрузка, привязка, скачивание вторым участником, 404 постороннему) evidence/smoke.txt
Байты в S3, метаданные в БД, 201 после сохранения код upload_attachment; student-tests/test_attachments.py sha256/размер совпадают, Content-Length скачивания равен оригиналу evidence/attachments_tests.txt
Upload → остановка реплики → download через другую; restart с volumes student-tests/test_attachment_resilience.py загрузил api-1, скачал api-2, sha256 совпал; после рестарта postgres/valkey/minio/api/nginx метаданные и оригинал целы evidence/attachment_resilience.txt
Общие persistence / failover make test-persistence, make test-failover (хуки scripts/restart.sh, scripts/stop-one.sh) PASS; failover: 131 успешная запись, 0 ошибок, восстановление 0.45 с evidence/persistence.txt, evidence/failover.txt
Лимиты 10 MiB / 40 Mpx, MIME по содержимому, опасные filename test_attachments.py 10 MiB+ → 413; PNG 8000×6000 → 413 до декодирования; подмена MIME и мусор → 415; ../, /, \, NUL, \n, пустое, 256 символов → 400 evidence/attachments_tests.txt
Устойчивость к некорректным входным данным student-tests/test_input_hardening.py, scripts/jpeg_check_experiment.py (запуск: docker compose cp scripts/jpeg_check_experiment.py api-1:/tmp/ && docker compose exec -T api-1 python /tmp/jpeg_check_experiment.py) усечённый PNG, filter-байт 5/0xFF, битый IDAT, 27-байтный JPEG → 415 (в том числе для изображений 6 и 36 Mpx); filename из пробелов, DEL, C1, . → 400; порядок вложений; [] ≡ отсутствует; 12 MiB → JSON 413 evidence/input_hardening.txt, evidence/jpeg_check.txt
Чужое / неизвестное / чужого чата attachment_id, ошибки не 500 test_attachments.py 404 / 404 / 404; дубликаты, не-UUID, >10 → 400 там же
Недоступность и зависание S3 student-tests/test_s3_outage.py остановка: upload/download/ready → 503 JSON с X-Instance-Id, метаданные и текст работают, без 502; docker pause: upload отвечает 503 за 7 с; восстановление за секунды evidence/s3_outage.txt
Прерывание загрузки обрыв сокета на половине тела в test_attachments.py сервер здоров, следующий upload проходит там же
Компенсация / сверка, безопасный grace трек 2, ниже 18/18 проверок evidence/reconciler_experiment.txt
Пик памяти при ≥10 одновременных загрузках student-tests/memory_experiment.py см. ниже evidence/memory_experiment.txt
Private bucket вне API, консоль не открыта student-tests/check_private_bucket.sh анонимные GET/LIST из сети compose → 403, порты 9000/9001 на хосте не опубликованы, mc anonymous get → private evidence/private_bucket.txt
Отдельные S3 credentials с ограниченными правами infra/minio/app-policy.json, init.sh API работает под messenger_app; root-secret API не получает compose.yaml

Проверка hook'ов подтверждает перезапуск реальных процессов: restart.sh перезапускает postgres, valkey, minio, api-1, api-2, nginx без down -v; stop-one.sh останавливает только указанную реплику.

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

1. Память при 10 одновременных загрузках

Гипотеза: основная память уходит на параллельное декодирование Pillow и S3 PUT, а не на хранение тел запросов; ограничение числа одновременных тяжёлых стадий снизит пик.

Методика: student-tests/memory_experiment.py, PNG 8.27 MiB (1700×1700, несжимаемый шум), 10 параллельных загрузок через LB, 3 раунда, замер docker stats каждого API (лимит контейнера 256 MiB, 0.5 CPU). Mac arm64, Docker Desktop.

Вариант Простой, MiB Пик api-1 / api-2, MiB Динамика по раундам 201 / всего
До: без ограничения тяжёлых стадий 88 182 / 155 рост 144 → 166 → 182 30 / 30
После: UPLOAD_CONCURRENCY=2 на реплику 87 110 / 116 110 → 109 → 110, роста нет 30 / 30
После + потоковый PNG-сканер и JPEG-проверка (итоговая версия) 98–100 115 / 114 115 → 115 → 115, роста нет 30 / 30

Сырые данные: evidence/memory_experiment_before_semaphore.txt, evidence/memory_experiment.txt. Ограничения: docker stats даёт моментальные срезы (раз в ~1–2 с), настоящий пик мог быть выше; одна конфигурация железа; один размер файла; медиана длительности загрузки выросла с 0.82 до 1.15 с (цена ограничения), в итоговой версии 0.76 с. Причину роста «до» (фрагментация аллокатора или реальная утечка) я не выяснял.

2. Трек 2 — reconciler с внедрением ошибок

Гипотеза: сверка по правилам выше находит и исправляет расхождения, не трогая свежие и используемые вложения.

Методика: scripts/reconcile_experiment.py внутри api-контейнера снимает базовую линию (в БД могут быть остатки прошлых тестов), создаёт строки/объекты, имитирующие сбои на обеих сторонах, и запускает dry-run, apply, apply после истечения grace, повторный apply. Счётчики сравниваются с базовой линией. LastModified объекта в MinIO задним числом не изменить, поэтому «старый объект» моделируется ожиданием grace.

Внедрённая ошибка Ожидание Наблюдение
uploading старше grace, объект есть, но моложе grace (падение после PUT) не трогать до истечения grace сохранены; собраны после grace
uploading старше grace, но под его ключом свежий объект не трогать не тронуты; собраны после grace
ready, подтверждённая только что, объект ещё не виден не помечать missing не помечена
uploading старше grace, объекта нет (падение до PUT) строка удалена удалена
uploading свежее grace (загрузка идёт) не трогать не тронута; после истечения grace собрана
объект без строки внутри grace не трогать не тронут; удалён после grace
ready, объект потерян пометить failed/object_missing помечено
ready, привязано к сообщению, объект на месте не трогать не тронуто
ready, привязано к сообщению, объект потерян строку не удалять, пометить сохранена, failed
dry-run ничего не менять, но показать счётчики счётчики верны, состояние не изменилось
повторный apply нулевые изменения 0 / 0 / 0

Итог: 18/18 проверок (evidence/reconciler_experiment.txt). Стоимость обхода: 1000 ready-вложений (около 1100 объектов вместе с остатками прошлых тестов) — 1.25 с в dry-run (в основном 1000 HEAD-запросов к S3; листинг идёт страницами по 500 с одним запросом к БД на страницу). Оценка масштабирования линейна, на больших объёмах не измерялась.

3. Отказы

Воздействие Ожидаем Наблюдали Восстановление / потеря данных
Остановка обслужившей API-реплики download через другую реплику, тот же файл api-1 → api-2, sha256 совпал без потерь
Остановка MinIO 503 на вложениях и ready, текст работает upload/download/ready → 503 JSON, сообщения читаются, 502 нет возврат за секунды после старта, без потерь
Зависание MinIO (docker pause) быстрый 503 без вечного ожидания upload → 503 за 7 с, download → 503 восстановление после unpause
Остановка PostgreSQL 503 JSON с X-Instance-Id на ready и бизнес-эндпоинтах так и есть возврат после старта
Рестарт postgres, valkey, minio, API, nginx с volumes метаданные и байты на месте сохранены без потерь
Обрыв клиента на середине upload нет 500 и мусора сервер здоров; строка в БД ещё не создана —

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

  • Образ MinIO. Официальные образы minio/minio на Docker Hub и quay.io/minio/minio в моей среде недоступны (pull denied / 401), поэтому использован сторонний madlabcg/minio, закреплённый по digest. Его происхождение и содержимое я не проверял; для защиты нужно заменить образ на проверенный (собрать из исходников MinIO или взять образ, указанный преподавателем).
  • Валидация изображений. PNG проверяется собственным потоковым сканером (структура, CRC, filter-байты, точный размер данных), JPEG — полным декодированием libjpeg в масштабе 1/8 и проверкой EOI. Не обнаруживается JPEG, у которого поток обрезан посередине, а после обрезки дописан маркер EOI: libjpeg трактует это как нормальный конец данных (и Pillow тоже принимает такой файл). Также сканер не проверяет содержимое palette/ancillary chunk'ов, кроме CRC и PLTE-правил.
  • Проверка размера по Content-Length невозможна для chunked-запросов: тогда лимит применяется по факту чтения потока.
  • Проверка PNG ограничена по времени (SCAN_SECONDS=10 с); на очень медленной машине валидный файл с огромной степенью сжатия может получить 415.
  • Вложения, загруженные, но так и не прикреплённые к сообщению, не считаются мусором и не удаляются; политики TTL для них нет.
  • Reconciler при проверке ready-строк делает HEAD на каждую; для очень больших объёмов нужен инкрементальный режим по курсору или S3 Inventory.
  • Нагрузочное тестирование с заданным arrival rate, p95/p99 не выполнялось; измерялась только память.
  • Не реализованы: трек 1 (presigned upload), варианты изображений (lab5), TLS (локальный стенд с синтетическими данными).
  • Секреты в secrets/ сгенерированы локально и не коммитятся; учётные данные Postgres в примере выше — учебные.