# 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/`. 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/БД оставляет цикл работающим для повторной попытки. ```sh make -f student.mk reconcile # просмотр, без изменения БД и S3 make -f student.mk reconcile-apply # применить безопасные исправления # Полные отчёты фонового процесса: docker compose logs reconciler ``` Dry-run не пишет наблюдения, не меняет статусы и не удаляет файлы. Он не обещает, что последующий apply увидит ровно то же состояние: apply перепроверяет всё заново. Другой фоновый процесс может менять данные одновременно с dry-run. Для спокойного просмотра без фоновой очистки: ```sh 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 наружу не публикуются. ## Методика и доказательства ```sh 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](evidence/lab4-research/results.png) Усы на графике — min/max трёх запусков, не доверительный интервал. Указанная RAM — максимум отсчётов, а не доказанный абсолютный пик между ними.