Files
mtusi2026lab4/REPORT.md
T

25 KiB
Raw Blame History

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

  • Автор, группа: Сергей Возжин, БПИ2301.
  • Целевая оценка: 5; выбран трек 2 — согласованность PostgreSQL и S3.
  • Commit/PR: #70
  • Использованные источники: контракт репозитория, документация Docker Compose, Chainguard Images, MinIO SDK и Pillow.
  • Библиотеки: FastAPI, Uvicorn, SQLAlchemy, asyncpg, Alembic, redis-py, MinIO Python SDK, Pillow, Argon2, pytest.
  • Помощь ИИ: OpenAI Codex использовался для плана, реализации, тестов и оформления отчёта; результат проверен исполняемыми тестами.

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

Требуются Docker Engine с Compose v2, Python 3.9+ для публичных тестов и свободный host-порт 8080. Проверенный стенд: Apple M4 Pro, 12 CPU cores, 24 GB RAM, Docker Desktop; API на Python 3.13.15.

Закреплённые компоненты:

  • python:3.13.15-slim;
  • postgres:17.4-alpine;
  • redis:7.4.2-alpine;
  • haproxy:3.2.26-alpine;
  • Chainguard MinIO RELEASE.2026-10-23T20-06-51Z, OCI index digest sha256:3c60a2a8c4d33409a9bc7a623a7fcbfb4605adc3d89422d2f53b3f673a6e5597;
  • Chainguard MinIO Client, вариант latest-dev, OCI index digest sha256:39768db4c3fa811bc8f2e2a3e0add8ea391648b1c980de179985e1c353dc1805 (mc --version сообщает upstream build marker DEVELOPMENT.GOGET).

Готовые образы MinIO и mc скачиваются из реестра Chainguard cgr.dev; в Compose оба образа закреплены по OCI digest. Сервис s3 использует минимальный образ minio и в учебном стенде запускается с user: "0", чтобы иметь доступ к Docker volume /data; его порты на host не публикуются. Для одноразового s3-bootstrap используется образ minio-client с shell и sed, необходимыми для создания bucket, отдельного пользователя API и bucket-scoped policy.

Создать локальную конфигурацию и заменить синтетические пароли, не добавляя .env в Git:

cp .env.example .env

S3_BUCKET допускает изменение: bootstrap при каждом запуске заново применяет ограниченную policy с текущим именем bucket. MINIO_ROOT_* получает только MinIO и bootstrap; API получает отдельные S3_ACCESS_KEY_ID и S3_SECRET_ACCESS_KEY. Access key и secret считаются параметрами первоначальной инициализации пользователя MinIO; их ротация требует явной операторской процедуры, а не изменения .env на работающем volume.

Проверить конфигурацию, собрать образы, применить миграции и дождаться готовности:

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
docker compose --env-file .env ps

migrate выполняет alembic upgrade head отдельно и однократно. s3-bootstrap идемпотентно создаёт приватный bucket, отдельного пользователя API и bucket-scoped policy. Две API-реплики стартуют только после миграции, Redis и успешного bootstrap. Единственная публичная точка входа — http://localhost:8080; API, PostgreSQL, Redis, S3 API и административная консоль MinIO наружу не публикуются.

Основные проверки:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make check
make validate PYTHON=.venv/bin/python
make test
make test-attachments PYTHON=.venv/bin/python
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose --env-file .env up -d --wait --wait-timeout 60 api lb
make test-attachment-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose --env-file .env up -d --wait --wait-timeout 60 api lb
scripts/check-private-bucket.sh
scripts/check-s3-outage.sh
.venv/bin/python scripts/measure-upload-memory.py --concurrency 10 --uploads 30
make reconcile-dry
make benchmark-reconciler

Исправления следует сначала просмотреть через make reconcile-dry. Изменяющий данные make reconcile-apply запускается оператором только после проверки dry-run. make benchmark-reconciler по умолчанию создаёт 100, 1000 и 10000 изолированных пар metadata/object, выполняет по три dry-run для каждого размера и удаляет тестовые данные. Набор и число повторов меняются через SIZES="..." и RUNS=...; старый одиночный параметр SIZE=... также поддерживается.

Каждый failover-тест намеренно оставляет выбранную API-реплику остановленной, поэтому между сценариями и после последнего сценария она явно восстанавливается указанной командой docker compose up.

Безопасная остановка с сохранением данных:

docker compose --env-file .env down

Намеренное необратимое удаление учебных данных выполняет только оператор:

docker compose --env-file .env down -v

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

HTTP client
    |
    v
HAProxy :8080
    |
    +-- round-robin --> API replica 1 --+--> PostgreSQL: metadata
    |                                  +--> Redis: sessions
    +-- round-robin --> API replica 2 --+--> private MinIO: original bytes

Из lab3 сохранены две взаимозаменяемые API-реплики, HAProxy, общие PostgreSQL/Redis, Bearer-сессии, X-Instance-Id, общая идемпотентность сообщений, readiness и failover hooks.

В lab4 добавлены:

  • MinIO и persistent s3_data volume;
  • таблицы attachments и message_attachments;
  • синхронный binary upload PNG/JPEG;
  • авторизованные metadata/download endpoints;
  • attachment_ids в сообщениях и в области сравнения идемпотентного body;
  • компенсационное удаление объекта и безопасный cleanup старых orphan-объектов;
  • повторяемый reconciler метаданных PostgreSQL и оригиналов S3.

PostgreSQL является источником истины для метаданных. В БД не хранятся bytes изображения. MinIO хранит оригинал по серверному ключу originals/<UUID>. Пользовательский filename хранится только как метаданные и не используется в object key или пути файловой системы.

Upload и лимиты

API сначала проверяет сессию, доступ к чату, filename и заявленный MIME. Тело читается чанками в SpooledTemporaryFile: до 1 MiB находится в памяти, затем временно сбрасывается на ephemeral disk API. Как только суммарный размер становится больше 10 MiB, запрос отклоняется с 413; превысивший лимит чанк в spool не записывается. Постоянной локальной копии нет.

Pillow определяет реальный PNG/JPEG, проверяет совпадение MIME, размеры до декодирования пикселей и целостность изображения через verify(). Максимум — 10 485 760 bytes и 40 000 000 пикселей. Пустой, повреждённый или чужой формат возвращает 415; превышение лимита bytes/pixels — 413.

S3-вызовы выполняются вне event loop. HTTP client S3 имеет ограниченные connect/read timeout и retry. Readiness проверяет PostgreSQL, Redis и существование bucket.

Транзакционная граница PostgreSQL/S3

Атомарной транзакции между S3 и PostgreSQL нет. Для синхронного 201 ready выбран порядок:

  1. Полностью проверить ограниченный файл.
  2. Выполнить S3 PUT.
  3. Выполнить транзакцию INSERT метаданных.
  4. Вернуть 201 только после успешного завершения обоих шагов.

Если PUT не удался, метаданные не создаются. Если PUT прошёл, а транзакция БД упала, API выполняет best-effort S3 DELETE. Unit-тест с внедрённой ошибкой БД подтверждает компенсацию.

Если компенсационное удаление также не удалось, остаётся orphan без метаданных. CLI находит такие объекты:

docker compose --env-file .env run --rm --no-deps api \
  python -m app.tools.cleanup_orphans --dry-run --grace-seconds 3600

docker compose --env-file .env run --rm --no-deps api \
  python -m app.tools.cleanup_orphans --apply --grace-seconds 3600

По умолчанию используется grace period один час; CLI запрещает значения меньше 60 секунд. Объекты с существующими метаданными и свежие orphan-объекты не удаляются. Сначала используется --dry-run, затем осознанный --apply.

Reconciler PostgreSQL/S3 — трек 2

Гипотеза эксперимента: полный снимок PostgreSQL и listing MinIO дадут линейную асимптотику O(N) по времени и памяти. На диапазоне 100–10000 согласованных пар рост времени не должен становиться сверхлинейным; абсолютные значения зависят от Docker-host и прогрева, поэтому для каждой точки используются три последовательных запуска и медиана.

Расширенный reconciler запускается внутри API-контейнера, где уже есть те же настройки и ограниченные S3 credentials, что у приложения:

docker compose exec -T api \
  python -m app.tools.reconcile_attachments --dry-run --grace-seconds 3600
docker compose exec -T api \
  python -m app.tools.reconcile_attachments --apply --grace-seconds 3600

Он читает снимок всех attachments и список originals/, после чего различает:

  • orphan: объект S3 есть, но ни одной строки с таким object_key нет;
  • missing: строка в состоянии ready есть, а оригинала S3 нет;
  • корректную пару: присутствуют обе стороны;
  • свежее расхождение: возраст меньше grace period, изменять его нельзя.

В --dry-run выводятся WOULD_DELETE_ORPHAN и WOULD_MARK_MISSING, но записи и объекты не меняются. В --apply старый orphan удаляется, а missing-метаданные сохраняются и переходят в status=failed, error_code=original_missing. Сообщение и связь с вложением не удаляются. Повторный --apply ничего не делает: orphan уже отсутствует, а failed больше не считается ожидающим оригинал состоянием. При этом строка failed по-прежнему защищает внезапно появившийся объект с тем же ключом от удаления как orphan.

Grace period защищает upload, который ещё выполняется, и запрещён ниже 60 секунд. Используемые сообщением вложения не имеют особого исключения: любой известный PostgreSQL ключ защищён одинаково, поэтому корректный оригинал связанного сообщения не удаляется. Content для failed возвращает 409, а привязать такое вложение к новому сообщению нельзя.

Начальные снимки могут устареть во время apply. Поэтому перед удалением orphan reconciler повторно проверяет отсутствие object_key в PostgreSQL, перед маркировкой missing выполняет HEAD/stat объекта, а SQL UPDATE дополнительно сравнивает id, object_key, status и исходный updated_at. Гонки логируются как SKIP_* и учитываются в race_protected. Общей транзакции между PostgreSQL и S3 всё равно нет: остаётся узкое TOCTOU-окно между последней проверкой и действием. Полностью закрыть его можно только протоколом состояний/ lease или запретом параллельного восстановления на время apply.

Операции между двумя хранилищами всё ещё не образуют общей транзакции. Если apply прервётся, уже выполненное безопасное удаление orphan не требует отката, условный SQL UPDATE меняет только всё ещё ready строки, а повторный запуск завершает оставшуюся работу.

Доступ и идемпотентность

Метаданные и content доступны любому участнику чата. Неизвестный объект и запрос постороннего одинаково возвращают 404. Download идёт через API без redirect. Публичный ответ не раскрывает object key, endpoint или credentials.

Сообщение принимает 0–10 уникальных attachment_ids. Все вложения должны быть ready и относиться к тому же чату. Пустой текст допустим только с вложением. Сравнение идемпотентного запроса включает упорядоченный список attachment ID; отсутствие поля и [] считаются одинаковыми.

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

Критерий README Команда/сценарий Наблюдаемый результат Доказательство
Offline/OpenAPI make check; make validate PYTHON=.venv/bin/python оба PASS evidence/results.md
Публичный smoke make test PASS: lab4 public API scenario evidence/results.md
Негативные сценарии make test-attachments PYTHON=.venv/bin/python 12 passed tests/test_attachments.py, evidence/results.md
Компенсация S3/БД unit-тест с ошибкой repository S3 DELETE вызван для загруженного ключа; 1 passed tests/test_attachment_compensation.py
Private bucket scripts/check-private-bucket.sh anonymous GET получил 403 evidence/results.md
Недоступность S3 scripts/check-s3-outage.sh readiness вернул структурированный 503; стенд восстановлен evidence/results.md
Persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh прежние token, metadata и bytes доступны после restart PostgreSQL/Redis/MinIO/API evidence/results.md
Общий lab3 failover make test-failover ACTION_SCRIPT=scripts/stop-one.sh 111 записей, 1 переходная ошибка, восстановление 2,333 с, файл сохранён evidence/results.md
Точный attachment failover make test-attachment-failover ACTION_SCRIPT=scripts/stop-one.sh загрузившая реплика остановлена, download через другую за 3,912 с, SHA-256 совпал evidence/results.md
Concurrency/RAM scripts/measure-upload-memory.py --concurrency 10 --uploads 30 30/30 upload, обе реплики, пики 68,50/68,33 MiB evidence/upload-memory.json
Идемпотентный bootstrap повторный запуск docker compose up после restart/failover bootstrap повторно завершился с code 0 evidence/results.md
Cleanup dry-run cleanup_orphans --dry-run --grace-seconds 60 164 известных объекта, удалено 0 evidence/results.md
Reconciler fault injection реальный PostgreSQL + MinIO: orphan, missing, fresh и три конкурентных изменения apply исправляет только подтверждённые расхождения; свежие/изменённые данные защищены; повторный apply — 0 действий tests/test_reconciler_integration.py, evidence/results.md
Полный тестовый стенд изолированный Compose, все pytest 17 passed evidence/results.md
Стоимость обхода SIZES="100 1000 10000" RUNS=3 make benchmark-reconciler медианы: 80,712 / 227,467 / 1733,545 мс; Python peak 2,62 / 4,21 / 8,08 MB evidence/results.md

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

Проверяемые ожидания:

  • остановка загрузившей API-реплики не меняет файл и не лишает вторую реплику доступа;
  • restart обязательных хранилищ с volumes сохраняет метаданные, bytes и сессию;
  • недоступность S3 наблюдаема как 503, а не 500;
  • 10 параллельных upload не приводят к неограниченному росту RAM.

Профиль upload: 30 запросов, concurrency 10, fixture 111 817 bytes, closed-loop, без retry. Получено 30 успешных upload за 0,382 с; максимальная latency 0,300 с; задействованы обе API-реплики. Пиковая наблюдаемая RAM: 68,50 MiB и 68,33 MiB при лимите 256 MiB на реплику.

Fault injection reconciler выполняется на настоящих PostgreSQL и MinIO. Тест создаёт старую ready строку без объекта, объект без строки и корректное вложение, уже связанное с сообщением. Дополнительно он восстанавливает missing-объект, изменяет updated_at другой missing-строки и создаёт metadata для orphan уже после получения начальных снимков, а также проверяет настоящий свежий orphan. Управляемые часы имитируют истечение grace period без минутного ожидания. Apply исправляет только подтверждённые расхождения; свежий объект и все три конкурентно изменённые сущности защищены. Повторный apply не повторяет исправления, связь сообщения сохраняется.

Воспроизводимый benchmark для каждого размера удаляет прежнюю фикстуру, создаёт одинаковое число строк attachments и объектов MinIO, выполняет три полных dry-run и удаляет данные.

Пар metadata/object Время, мс (три запуска) Медиана, мс Медианный peak Python allocations
100 78,847; 80,712; 82,781 80,712 2 620 657 bytes
1 000 232,254; 227,467; 226,264 227,467 4 205 016 bytes
10 000 1701,005; 1792,955; 1733,545 1733,545 8 075 853 bytes

Измерение включает запрос PostgreSQL, listing MinIO и сравнение снимков; подготовка и очистка в elapsed_ms не входят. Результат согласуется с гипотезой O(N): после заметной фиксированной стоимости время и память монотонно растут, на исследованном диапазоне нет признаков сверхлинейного взрыва. Это не доказательство для production-масштаба: измеряется Python tracemalloc, а не RSS контейнера, и полный снимок всё равно требует памяти O(N).

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Restart API + PostgreSQL + Redis + MinIO token, metadata и bytes сохраняются persistence PASS потерь нет
Остановка API в общем failover вторая реплика продолжает чтение/запись 111 записей, 1 краткая ошибка 2,333 с; потерь и дублей нет
Остановка загрузившей API файл скачивается через другую SHA-256 совпал, разные instance ID 3,912 с; потерь нет
Остановка MinIO readiness сообщает отказ зависимости структурированный 503, после запуска readiness восстановился потерь нет

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

Стенд выдерживает остановку одной API-реплики и штатный restart контейнеров с сохранёнными volumes. Он не выдерживает потерю Docker-host, единственного HAProxy, PostgreSQL, Redis или MinIO volume. Несколько API-процессов не делают единственные хранилища высокодоступными.

Upload синхронный, поэтому клиент ждёт S3 и PostgreSQL. SpooledTemporaryFile ограничивает RAM одной загрузки, но временный disk API должен иметь достаточный объём и отдельную квоту в production. Reconciler загружает полный список объектов и строк БД в память, поэтому его стоимость O(N), а для большого bucket нужны страничный/потоковый обход, метрики, checkpoint и плановый запуск.

Chainguard-образы зафиксированы по digest, поэтому обновляются только явно. Стенд изолирован учебной сетью. Перед production-развёртыванием потребовались бы непривилегированный UID с корректными правами на volume, TLS, внешний secret manager, HA хранилищ, аудит и резервное копирование.

Presigned upload, worker, thumbnail и варианты изображений намеренно не реализованы: для выбранного трека 2 они не требуются.