Files
mtusi2026lab4/REPORT.md
2026-11-08 18:17:48 +03:00

32 KiB
Raw Permalink Blame History

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

  • Автор, группа: TODO: Хуцаева Айса, БПИ2302.
  • Целевая оценка: 5.
  • Выбранный трек: трек 2 — согласованность двух хранилищ.
  • Commit/PR: solution/khutsaeva-bpi2302.

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

Процессы и хранилища

flowchart TD
    Client["Клиент"] --> LB["HAProxy"]
    LB --> API["API × 2"]
    API --> PG["PostgreSQL: метаданные"]
    API --> Redis["Redis: сессии"]
    API --> S3["MinIO: оригиналы"]
    R["Служебный reconciler"] --> PG
    R --> S3
    Backup["Проверенные резервные копии"] --> R

Что перенесено из lab3

  • Две API-реплики и HAProxy.
  • PostgreSQL и Redis с persistent volumes.
  • Авторизация и серверные сессии.
  • Проверка участия пользователя в чате.
  • Идемпотентная отправка сообщений.
  • Health/readiness endpoints.
  • Миграции Flyway.
  • Проверки перезапуска и отказа API-реплики.

Что добавлено в lab4

  • Приватное S3-хранилище MinIO.
  • Метаданные Attachment в PostgreSQL.
  • Связь сообщения с attachment_ids.
  • Синхронный binary upload PNG/JPEG.
  • Авторизованное скачивание оригиналов.
  • Проверки размера, формата, filename и числа пикселей.
  • Ограничение числа одновременно принимаемых загрузок.
  • Очистка временных файлов и orphan-объектов.
  • Отдельные ограниченные S3 credentials для API.
  • Служебный reconciler с dry-run и восстановлением из проверенной копии.
  • Эксперименты согласованности и стоимости обхода.

Загрузка и ограничения

API принимает сырое тело PNG/JPEG, а не multipart-запрос.

Ограничения:

  • размер оригинала — не более 10 MiB;
  • число декодированных пикселей — не более 40 миллионов;
  • MIME проверяется по содержимому;
  • filename используется только для отображения;
  • запрещаются разделители пути и управляющие символы в filename;
  • object key назначает сервер;
  • лишние параллельные загрузки получают 429 rate_limited.

Тело запроса читается ограниченными порциями во временный файл. Размер контролируется при чтении, в том числе при неизвестном Content-Length. Размеры изображения проверяются до полного декодирования.

Локальный временный файл API используется только во время обработки. После успешной загрузки оригинал хранится в S3, а не в каталоге API.

Ответ 201 ready возвращается после сохранения оригинала и метаданных.

Транзакционные границы

Общей атомарной транзакции между PostgreSQL и S3 нет.

При сохранении вложения:

  1. Принимается и проверяется изображение.
  2. Открывается транзакция PostgreSQL.
  3. Захватывается advisory lock для object key.
  4. Оригинал записывается в S3.
  5. Метаданные записываются в PostgreSQL.
  6. Транзакция фиксируется.
  7. API возвращает 201.

Если S3-запись прошла, а транзакция PostgreSQL не зафиксировалась, возможно появление orphan-объекта. Он удаляется последующей сверкой после grace period.

Очистка и reconciler используют тот же ключ блокировки, что и upload. Перед удалением повторно проверяются наличие метаданных и возраст объекта. Это защищает от удаления объекта незавершённой штатной загрузки.

Поведение reconciler

Состояние Dry-run Apply
Старый объект без метаданных would_delete_orphans Удаление после повторной проверки
Свежий объект без метаданных Пропуск Пропуск
Метаданные и оригинал существуют Проверка наличия и размера То же
Оригинал отсутствует, проверенная копия есть would_restore Восстановление и проверка SHA-256
Оригинал отсутствует, копии нет unresolved_missing Метаданные сохраняются
БД или S3 недоступны Проход прерывается Проход прерывается
Объект занят другим процессом busy Пропуск до следующего запуска

Копия для восстановления имеет имя <sha256>.bin. Перед восстановлением проверяются её размер и SHA-256. После записи проверяются скачанные из S3 байты.

Reconciler не создаёт резервные копии автоматически. В эксперименте копия сохранялась до восстановления намеренно удалённого тестового оригинала.

Публичный контракт lab4 не расширялся статусом missing. При отсутствии оригинала сохраняются сообщение и метаданные, а download возвращает 503 unavailable.

Конфигурация

Переменная Назначение
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD Инициализация PostgreSQL и подключение приложения через Compose
DB_URL, DB_USERNAME, DB_PASSWORD Настройки PostgreSQL внутри API
REDIS_HOST, REDIS_PASSWORD Подключение к Redis
S3_ENDPOINT Внутренний адрес http://minio:9000
S3_BUCKET Bucket messenger-attachments
S3_ACCESS_KEY, S3_SECRET_KEY Ограниченные credentials API
MINIO_ROOT_USER, MINIO_ROOT_PASSWORD Административная инициализация MinIO
API_REPLICAS Число API-реплик
API_CPUS, API_MEMORY Лимиты API-контейнера
DB_POOL_SIZE Размер пула соединений API
APP_CLEANUP_ENABLED Временное отключение фоновой очистки в эксперименте

В Java S3-параметры используются через app.s3.*. Reconciler получает настройки из контейнеров и использует S3 credentials API, а не root-пользователя MinIO.

В текущей реализации регион S3 задан как us-east-1. Изменение одной переменной S3_REGION не переключает регион автоматически.

Предложенные skeleton переменные DATABASE_URL_FILE, S3_ACCESS_KEY_ID_FILE и S3_SECRET_ACCESS_KEY_FILE не следует считать реализованными автоматически: текущий вариант использует переменные окружения.

TODO перед публикацией: сверить актуальный .env.example с этой таблицей, удалить неподдерживаемые настройки либо явно пометить их как примеры. Лимиты 10 MiB и 40 миллионов пикселей реализованы в валидаторе; наличие одноимённых переменных в skeleton само по себе их не меняет.

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

JSON-отчёты экспериментов сохранены в results/. Обозначения каталогов:

  • results/reconcile-<chat_id>/ — эксперимент исправления расхождений;
  • results/reconcile-failure-<chat_id>/ — отказы зависимостей;
  • results/reconcile-cost-<run_id>/ — измерения стоимости обхода.

Для проверок, выполненных ранее только с выводом в терминал, ниже явно указана необходимость сохранить файл доказательства.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Валидность контракта make validate PASS: OpenAPI и JSON Schema валидны; приложение этим не тестируется TODO: сохранить вывод
Структура skeleton make check PASS: структура, ссылки и синтаксис Python; приложение этим не тестируется TODO: сохранить вывод
Публичный smoke make test PASS: публичный сценарий lab4 TODO: сохранить вывод
Сохранение возможностей lab3 make test, persistence и failover Сохраняются сообщения и действующая сессия TODO: логи smoke и resilience
Метаданные в PostgreSQL, оригиналы в S3 Миграция Attachment, код сохранения, smoke Оригинал скачивается через API; метаданные отделены от байтов Миграции, AttachmentPersistenceService.java, S3StorageService.java; TODO: лог smoke
Сообщения с вложениями Smoke и tests/reconcile_check.py Сообщение и ссылки на вложения сохраняются после сверки и восстановления results/reconcile-<chat_id>/; TODO: итоговый stdout теста
Ограничения изображения make test-attachments Негативный suite прошёл: превышение размера/пикселей, повреждение, MIME и filename TODO: сохранить stdout negative suite
Запрет чужого доступа Smoke и negative suite Посторонний не получает чужое вложение; чужой attachment и другой чат отклоняются TODO: логи smoke и negative suite
Переключение API-реплики make test-failover ACTION_SCRIPT=./scripts/stop-one.sh 2 реплики до воздействия, 74 успешные записи, 2 неудачные попытки; первая успешная запись через 1,833 с TODO: лог теста и состояние контейнеров
Остановка именно загрузившей реплики Upload → фиксация X-Instance-Id → остановка этой реплики → download Отдельная привязка остановленной реплики к успешному upload пока не зафиксирована в представленном доказательстве TODO: добавить адресное доказательство
Сохранение после restart make test-persistence ACTION_SCRIPT=./scripts/restart.sh PASS: подтверждённые данные и действующая сессия сохранены TODO: stdout теста и трасса hook
Недоступность S3 tests/reconcile_failure_check.py При остановке MinIO reconciler завершился без изменения объектов; после восстановления оригинал доступен через API 02-minio-unavailable.json, summary.json в каталоге failure
Пользовательские ошибки не превращаются в 500 make test-attachments Негативные сценарии завершились ожидаемыми клиентскими ошибками TODO: stdout negative suite
Прерывание HTTP upload make test-upload-abort Временный файл удалён; обе реплики принимают следующие загрузки; оригинал цел TODO: сохранить stdout
Аварийное завершение API python3 -X utf8 tests/upload_crash_check.py После SIGKILL файл сохранился; после запуска того же контейнера просроченный файл удалён TODO: сохранить stdout
Отказ БД после S3-записи tests/upload_db_failure_check.py После исправления кода ошибки на unavailable сценарий прошёл; orphan удаляется очисткой TODO: сохранить stdout
Безопасная очистка orphan tests/cleanup_check.py --bucket messenger-attachments Старый orphan удалён; свежий объект и зарегистрированное вложение сохранены TODO: сохранить stdout
Ограниченная память при ≥10 клиентах tests/upload_memory_check.py 10 клиентов, 81 успешная загрузка, 661 ответ 429, 0 неожиданных ошибок и OOM results/upload-memory.json
Идемпотентный bootstrap Два запуска docker compose run --rm --no-deps --pull never minio-init Оба завершились успешно; повторное назначение политики обработано TODO: сохранить вывод обоих запусков
Отдельные ограниченные S3 credentials infra/minio/check-access.sh через minio-init API может записывать и читать разрешённые объекты; запрещённые операции отклоняются TODO: сохранить итоговый stdout проверки
Private bucket вне API Та же проверка доступа Анонимное скачивание существующего объекта запрещено TODO: сохранить stdout
Изоляция административной консоли docker compose port minio 9001 и проверка Compose Требуется подтвердить отсутствие публикации на общем интерфейсе; при локальной публикации ожидается 127.0.0.1 TODO: сохранить вывод и фрагмент конфигурации
Трек 5: обнаружение orphan и missing tests/reconcile_check.py Dry-run обнаружил по одному orphan и missing без изменений 01-dry-run.json
Трек 5: безопасное исправление Тот же тест, apply Старый orphan удалён; missing без копии не уничтожает метаданные 02-apply-no-backup.json
Трек 5: восстановление Тот же тест с резервной копией Dry-run запланировал восстановление; apply восстановил оригинал с проверкой байтов 03-dry-run-with-backup.json, 04-restore.json
Трек 5: повторный запуск Повторный apply Нет повторных удалений или восстановлений 05-repeat.json
Трек 5: отказы обеих зависимостей tests/reconcile_failure_check.py MinIO и PostgreSQL останавливались по очереди; ложных missing и изменений данных нет results/reconcile-failure-<chat_id>/summary.json
Трек 5: измерение стоимости обхода tests/reconcile_cost_check.py --sizes 10 100 1000 --repeats 3 Все проходы завершены; количество SQL/S3-вызовов совпало с расчётом summary.json, samples.csv, n*-run-*.json в каталоге cost

Подтверждение инфраструктурных воздействий

Для persistence недостаточно одного PASS.

В показанной трассе restart-hook выполнялись:

  • остановка API и LB;
  • перезапуск PostgreSQL, Redis и MinIO;
  • ожидание готовности хранилищ;
  • запуск API;
  • запуск LB.

Volumes при этом сохранялись.

Для сдачи необходимо приложить трассу фактической версии hook и состояние контейнеров после выполнения. Аналогично для failover необходимо сохранить идентификатор остановленной API-реплики.

В тесте отказов reconciler использовались реальные docker stop и docker start для контейнеров MinIO и PostgreSQL. Настройки подключений фиксировались до остановки, поэтому проверялось поведение worker при недоступной зависимости, а не только ошибка обнаружения контейнера.

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

Гипотеза

Повторяемая сверка PostgreSQL и S3 позволяет обнаруживать и безопасно исправлять расхождения при следующих условиях:

  • свежие объекты защищены grace period;
  • удаление проверяет отсутствие метаданных под общей с upload блокировкой;
  • отказ хранилища не считается отсутствием объекта;
  • потерянный оригинал восстанавливается только из проверенной копии;
  • повторный запуск не создаёт дополнительных изменений.

Для исправного набора данных ожидается примерно линейный рост числа SQL-вызовов и операций S3 относительно количества вложений. Время полного запуска дополнительно включает постоянные накладные расходы.

Окружение и лимиты

Эксперименты выполнялись в Windows с Docker Desktop и WSL.

Ресурс Значение
CPU, доступные Docker 12
RAM, доступная Docker 8 171 163 648 байт, около 7,61 GiB
API 2 реплики, каждая 1 CPU и 768 MiB
PostgreSQL 1 CPU, 512 MiB
MinIO 1 CPU, 768 MiB
Reconciler 1 CPU, 256 MiB

Это лимиты контейнеров, а не измеренное потребление CPU/RAM. Фактическая загрузка CPU в эксперименте сверки отдельно не измерялась.

Image ID reconciler в эксперименте:

sha256:1e2c36d99dfe28d7f9eb8f57dc8b5273ec75e20ae88e8427e560b72f4594bbb4

Image ID остальных сервисов сохранены в environment итогового JSON.

Проверка согласованности

Созданы:

  • корректное вложение, используемое сообщением;
  • вложение, у которого намеренно удалён оригинал;
  • старый S3-объект без метаданных;
  • свежий S3-объект без метаданных.

Для старого orphan выполнено реальное ожидание 65 секунд при тестовом grace period 60 секунд.

Перед каждым этапом создавался отдельный свежий orphan. Это исключило накопление времени предыдущих запусков Docker в возрасте проверяемого свежего объекта.

Этап Результат Время worker, с SQL S3
Dry-run без копии Обнаружены orphan и missing; изменений нет 0,490 13 6
Apply без копии Orphan удалён; missing остаётся нерешённым 0,600 13 7
Dry-run с копией Запланировано восстановление 0,262 11 5
Apply с копией Оригинал восстановлен и проверен 0,368 11 7
Повторный apply Оба оригинала существуют; изменений нет 0,190 11 4

needs_attention без резервной копии является ожидаемым результатом. Метаданные не удаляются для сокрытия проблемы.

Отказы и восстановление

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка API-реплики Другая реплика продолжает обслуживание Failover PASS; 74 успешные записи, 2 неудачные попытки Первая успешная запись через 1,833 с; подтверждённые данные сохранены
Restart стенда с volumes Сохраняются данные и сессия Persistence PASS Полное время восстановления отдельно не зафиксировано; потери проверяемых данных нет
Обрыв HTTP upload Удаляется временный файл Upload-abort PASS; последующие загрузки работают Точное время отдельно не сохранено
SIGKILL принимающего API Просроченный временный файл удаляется после запуска Crash-сценарий PASS Использовано искусственное старое mtime; полное ожидание штатного grace не измерялось
Ошибка БД после S3-записи Orphan удаляется последующей сверкой Проверка прошла Интервал очистки тестовый; точное время не сохранено
MinIO остановлен перед запуском reconciler Проход завершается без изменений EndpointConnectionError; только попытка head_bucket Ошибка обнаружена за 0,343 с; данные и сессия сохранены после запуска MinIO
PostgreSQL остановлен перед запуском reconciler S3 не изменяется OperationalError; операций S3 нет Ошибка обнаружена за 0,160 с; данные и сессия сохранены после запуска PostgreSQL
Зависимости восстановлены Сверка снова выполняется Удалён один старый orphan Проход занял 0,196 с
Повторная сверка после восстановления Нет дополнительных изменений Чистый повторный apply Проход занял 0,375 с

Время обнаружения ошибки worker не является временем полного восстановления инфраструктуры.

Память при конкурентных загрузках

Профиль: closed-loop, 10 клиентов, без автоматических повторов POST. Продолжительность — 30,344 с.

Изображение: PNG 6000×6000, 36 миллионов пикселей, 157 192 байта в сжатом виде.

Метрика Результат
Успешные загрузки 81
Ответы 429 661
Неожиданные ошибки 0
Успешные RPS 2,669
p50 успешных запросов 601,77 мс
p95 успешных запросов 2084,50 мс
p99 успешных запросов 4082,42 мс
OOM / OOM kill 0 / 0
Реплика Память до теста, MiB Наблюдаемый пик, MiB Пик cgroup за жизнь контейнера после теста, MiB
API 1 356,10 375,53 377,39
API 2 361,88 378,82 379,07

Примерно 89% запросов отклонены механизмом admission control. Это не успешные загрузки и не скрытые серверные ошибки.

Десять клиентов не означают десять одновременно работающих декодеров: число активных загрузок ограничено приложением.

Память измерялась по cgroup контейнера, а не только Java heap. Выборочный мониторинг мог пропустить короткие пики. Показатель lifetime peak включает запуск и предыдущую работу контейнера.

Нагрузка текстовых сообщений

Публичный make load выполнял closed-loop POST сообщений без автоматических повторов:

Метрика Результат
Concurrency 4
Продолжительность 30,102 с
Успешные запросы 841
Ошибки 0
Успешные RPS 27,938
p50 92,299 мс
p95 408,735 мс
p99 615,139 мс

Это измерение текстовых сообщений, а не пропускной способности upload. Задержки рассчитаны для успешных запросов. Closed-loop профиль не задаёт фиксированный внешний arrival rate и имеет ограничение coordinated omission.

Методика измерения стоимости обхода

Для каждого размера создан отдельный чат с 10, 100 или 1000 вложений.

Использован публичный fixture:

  • RGB PNG 320×200;
  • размер 111 817 байт;
  • SHA-256: 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75.

Всего загружено 1110 файлов, около 118,37 MiB оригиналов. Подготовка данных заняла 95,224 с и не включалась во время обхода.

После последней загрузки выполнено ожидание 65 секунд. Фоновая очистка API была отключена. Для каждого объёма выполнен один прогревочный и три измеряемых прохода. Порядок объёмов перемешивался с фиксированным seed 1729.

Все проходы выполнены в dry-run. В каждом подтверждено:

  • просмотрено ровно N объектов;
  • просмотрено ровно N записей метаданных;
  • все N объектов зарегистрированы;
  • все N оригиналов найдены при обходе метаданных;
  • свежих пропущенных объектов и занятых блокировок нет;
  • расхождений и операций записи/удаления нет.

После измерений проверены неизменность метаданных и сообщений, а также байты первого и последнего вложения каждого набора.

Результаты стоимости обхода

Вложения Worker min, с Worker median, с Worker max, с Медиана полного запуска, с SQL S3
10 0,381 0,413 0,604 9,580 53 12
100 1,484 1,949 2,003 10,885 503 102
1000 11,090 14,097 14,241 23,009 5004 1003

Во всех трёх повторах одного объёма количество вызовов было одинаковым.

При размере страницы 500 для текущего алгоритма и исправных старых вложений получены формулы:

  • SQL-вызовы: 5N + ceil(N / 500) + 2;
  • операции S3: N + ceil(N / 500) + 1.

Измерения полностью совпали с этим расчётом.

На каждый зарегистрированный старый объект приходятся два SQL-вызова в проходе S3: блокировка и проверка метаданных.

На каждую запись метаданных приходятся три SQL-вызова: чтение ключа, блокировка и повторное чтение строки. Дополнительно учитываются запросы страниц и глобальная блокировка.

В S3 выполняются проверка bucket, получение страниц списка и один HEAD на каждое вложение.

SQL-счётчик не включает служебные BEGIN/COMMIT. Счётчик S3 отражает вызовы операций SDK, а не измеренный сетевой трафик.

Вывод по гипотезе

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

Время worker увеличивается с объёмом данных, но не строго пропорционально: на него влияют постоянные расходы, кэширование и состояние локального стенда. Три повтора недостаточны для универсальной модели задержек.

Дополнительные расходы полного запуска составили примерно 8,882–9,224 с на проход. Они включают запуск Python-скрипта, обнаружение контейнеров, Docker и запуск worker.

Для небольших наборов эти расходы превышают время самой сверки. Для 1000 вложений медиана работы worker составила 14,097 с, а полного запуска — 23,009 с.