Files
mtusi2026lab4/LAB4_RECONCILIATION.md
T
2026-11-12 19:38:03 +03:00

17 KiB
Raw Blame History

Lab4, трек 2: согласованность PostgreSQL и S3

Задача и гипотеза

S3 PUT и PostgreSQL COMMIT не образуют общую транзакцию. При сбоях возможны: объект без Attachment, зависший pending без объекта и Attachment с потерянным оригиналом. Гипотеза: устойчивый журнал намерений, общая блокировка на ключ и повторяемая сверка устраняют бесхозные объекты, сохраняя свежие, активные и используемые вложения. Время обхода ожидается примерно линейным по числу ключей.

Что хранится в БД

  • attachments — опубликованные вложения. Наличие записи защищает оригинал, даже если вложение ещё не использовано в сообщении.
  • upload_intents — ключ, время регистрации и состояние pending, committed или abandoned. Это внутренний журнал, не публичные статусы Attachment.
  • storage_findings — наблюдения orphan/missing, время обнаружения/последней проверки/закрытия и отпечаток объекта для диагностики.
  • attachments.storage_missing_since — внутренняя отметка о потере оригинала.

Миграция 008 добавляет эти данные без изменения предыдущих вложений. Старые Attachment защищаются и без журнала. Наличие строки журнала само по себе не защищает мусор навсегда: старые pending проверяются и закрываются.

Загрузка и транзакции

  1. Проверить пользователя, чат, имя, размер, MIME, структуру и число пикселей. До S3 файл находится во временном ограниченном хранилище; считать SHA-256.
  2. Назначить уникальный originals/<uuid>.
  3. В отдельной транзакции взять advisory lock на ключ, записать pending и COMMIT.
  4. В HTTP-транзакции взять ту же блокировку, повторно проверить pending.
  5. Выполнить S3 PUT, удерживая блокировку.
  6. Одним COMMIT сохранить Attachment и перевести журнал в committed.
  7. Только после COMMIT вернуть 201 ready.

Блокировка pg_advisory_xact_lock вычисляется по стабильному хешу object key; она действует до конца транзакции и освобождается PostgreSQL при разрыве соединения. Reconciler использует pg_try_advisory_xact_lock: занятый ключ пропускается, а не задерживает весь обход. Случайная коллизия хеша только сериализует независимые ключи, но не разрешает удаление используемого объекта.

При неизвестном результате COMMIT файл сразу не удаляется. Журнал и последующая проверка Attachment позволяют разобрать исход без риска удалить уже подтверждённый оригинал. При обрыве HTTP до этапа S3 PUT постоянного объекта ещё нет.

Алгоритм сверки

Область действия — только настроенный S3_BUCKET и originals/ либо более узкий префикс. Другие bucket и префиксы не перечисляются. ListObjectsV2 читается лениво постранично; приложение не собирает весь список в RAM. Записи БД читаются порциями по 200 с продолжением по ключу.

Для каждого объекта:

  1. Попробовать взять блокировку; занят — пропустить.
  2. Проверить Attachment заново под блокировкой. Есть запись — сохранить.
  3. Проверить актуальный S3 HEAD и pending, зафиксировать наблюдение.
  4. Если объект или намерение свежие — сохранить.
  5. Иначе закрыть существующее намерение как abandoned, удалить бесхозный объект, закрыть наблюдение и COMMIT.

Запас RECONCILE_GRACE_SECONDS=300 — один настраиваемый период, без второго ожидания после первого обнаружения. Он проверяется относительно времени изменения S3-объекта и создания намерения. Он не заменяет блокировку и не является lease: сколько бы ни длилась активная загрузка, занятый ключ пропускается.

Старые pending без Attachment и без S3-объекта переводятся в abandoned. Отложенный загрузчик повторно проверяет состояние и не публикует закрытую попытку. Незавершённые multipart parts не видны в ListObjectsV2. SDK пытается отменить неудачный multipart; дополнительно MinIO настроен на expiry незавершённых загрузок через 24 часа с проверкой раз в час. Объекты целиком по этим настройкам не удаляются.

Обратный проход проверяет S3 HEAD для каждого Attachment:

  • Подтверждённое NoSuchKey/NoSuchObject отмечается как missing. Метаданные, сообщения и связи сохраняются. API отвечает 503 на чтение такого вложения; новые сообщения с ним получают 409. Повтор ранее подтверждённого сообщения с прежним Idempotency-Key сохраняет прежний результат.
  • Если отсутствовавший объект появился снова, проверяются размер и фактический SHA-256 при ограниченном чтении. Совпали — отметка снимается. ETag не считается SHA-256.
  • AccessDenied, пропавший bucket, timeout и другие ошибки прерывают проход; они не интерпретируются как отсутствие всех файлов.

Отдельный проход закрывает оставшиеся orphan-наблюдения, если S3 DELETE выполнился, но его ответ или последующий COMMIT потерялись. Повтор удаления безопасен. Reconciler не восстанавливает потерянные байты из метаданных: для восстановления нужна копия исходного файла. Он безопасно изолирует потерю и проверяет восстановление.

Запуск и наблюдение

Compose запускает отдельный reconciler: apply каждые 300 секунд, grace 300 секунд. Процесс пишет JSON: режим, область обхода, действия, ограниченную выборку ключей, время, число SQL statements, HTTP-запросы S3 по операциям и пик RSS процесса. Healthcheck этого контейнера проверяет жизнь процесса; результаты проходов — в JSON. Сбой обслуживания S3/БД оставляет цикл работающим для повторной попытки.

make -f student.mk reconcile          # просмотр, без изменения БД и S3
make -f student.mk reconcile-apply    # применить безопасные исправления
# Полные отчёты фонового процесса:
docker compose logs reconciler

Dry-run не пишет наблюдения, не меняет статусы и не удаляет файлы. Он не обещает, что последующий apply увидит ровно то же состояние: apply перепроверяет всё заново. Другой фоновый процесс может менять данные одновременно с dry-run. Для спокойного просмотра без фоновой очистки:

docker compose stop reconciler
docker compose run --rm --no-deps reconciler python -m src.maintenance.reconcile
# После просмотра восстановить периодическую работу:
docker compose up -d reconciler

Права доступа

Bootstrap с MinIO owner credentials создаёт приватный bucket и двух отдельных пользователей. Декларативные политики находятся в infra/s3/api-policy.json и infra/s3/reconciler-policy.json; Dockerfile копирует их в образ. Python-сценарий явно выполняет подготовку bucket и настройку каждого пользователя. В API-контейнерах owner/reconciler credentials переопределены пустыми значениями; в reconciler нет owner/API credentials.

Роль Права
API ListBucket/GetBucketLocation своего bucket; GetObject/PutObject и multipart операции только в originals/; нет DeleteObject
Reconciler ListBucket/GetBucketLocation/GetBucketVersioning своего bucket; GetObject/DeleteObject только в originals/; нет PutObject и admin прав
Bootstrap Создание bucket, пользователей и политик; доступен только как отдельная завершающаяся задача

MINIO_ROOT_* должны сохранять прежние credentials владельца при обновлении существующего volume. S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY теперь относятся к отдельному API-пользователю. Значения по умолчанию предназначены для локального учебного стенда. Консоль выключена, порты S3 наружу не публикуются.

Методика и доказательства

make -f student.mk test-reconciliation
make -f student.mk test-upload-memory PYTHON=.venv/bin/python
make -f student.mk test
make -f student.mk test-attachments PYTHON=.venv/bin/python

tests/reconciliation.py использует отдельную UUID-схему PostgreSQL и приватный UUID-bucket MinIO; при завершении удаляет только собственные тестовые ресурсы. Проверяет реальные PUT/HEAD/GET/DELETE, процесс, аварийно завершающий настоящий код загрузки после PUT, ошибку COMMIT, отказ PUT, занятую блокировку, свежий файл, публикацию между dry-run и apply, missing, неправильное и правильное восстановление, потерянный ответ DELETE, AccessDenied и отказ БД. Snapshot доказывает отсутствие изменений при dry-run. Отдельно проверяются развёрнутые S3-права API/reconciler.

Стоимость обхода измеряется на 10, 100 и 1005 объектах, по три прогона; 1005 объектов проверяют переход между страницами ListObjectsV2. Используется dry-run по свежим бесхозным объектам: на объект приходится HEAD и примерно пять SQL statements. Размер объекта почти не влияет на этот профиль, поскольку его байты не читаются. Hash-проверка восстановленного missing имеет отдельную стоимость чтения исходника. Точные результаты — evidence/lab4-final-reconciliation.txt.

Локальное исследование не доказывает ту же скорость на удалённых сервисах: RTT, объём bucket и задержки СУБД могут существенно изменить время. Текущий обход последовательный; пакетная сверка могла бы уменьшить число SQL round trips.

Эксперимент памяти временно задаёт 5 принимаемых загрузок на каждую из двух API- реплик; декодирование изображений ограничено одним потоком на реплику. Запускает 10 одновременных загрузок для двух размеров PNG, проверяет SHA-256 и скачивание, измеряет cgroup memory.current каждые 20 мс, включая tmpfs. После теста восстанавливает обычную настройку параллелизма. Короткие пики между измерениями могут быть пропущены; эти два размера не доказывают worst case для изображения в 40 млн пикселей.

Границы безопасности

Поддерживается один неверсионируемый bucket. CLI отказывается работать с Enabled или Suspended versioning: там нужны отдельный учёт версий и политика delete markers. Все штатные писатели должны соблюдать протокол блокировок. Прямая административная перезапись/удаление S3-объекта одновременно со сверкой обходят эту координацию. Не обещается автоматическое восстановление БД/S3 из backup или защита от потери всего Docker host. Согласованность S3-провайдера, расхождение часов и допустимый срок pending нужно учитывать при переносе; будущие временные метки консервативно задерживают очистку. Журнал и закрытые наблюдения пока сохраняются без автоматического удаления истории.

Итоговые измерения

Все 16 этапов make -f student.mk verify-lab4 завершились с exit code 0. Интеграционный набор сверки содержит 15 проверок, включая отказ DELETE до удаления и прямой unsigned GET существующего объекта с результатом 403.

Объектов Медиана 3 обходов, с LIST HEAD SQL statements
10 0.0181 1 10 53
100 0.1559 1 100 503
1005 1.9679 2 1005 5028

Оба профиля по 10 одновременных загрузок завершились без отказов: 20 ответов 201, все SHA-256 и скачанные оригиналы совпали. Пики RAM: 124.71 / 128.91 MiB при 512 MiB на реплику. Размеры PNG: 197105 и 4923446 байт. Обычный UPLOAD_CONCURRENCY=1 восстановлен.

При замороженной PostgreSQL уже выполнявшаяся история вернула 503 за 5.0988 с, readiness — за 2.1109 с. После unpause восстановились 200 без рестарта API. Пустой стенд дошёл до миграции 008; API build --no-cache занял 32.829 с. Временный проект, volumes и его теги образов удалены; действующие данные сохранены.

Измеренная стоимость обхода и память API

Усы на графике — min/max трёх запусков, не доверительный интервал. Указанная RAM — максимум отсчётов, а не доказанный абсолютный пик между ними.