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

208 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/БД оставляет цикл работающим для повторной попытки.
```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 — максимум отсчётов, а не доказанный абсолютный пик между ними.