Mark a stale pending row in its own committed transaction before the cleaner deletes the object, and let mark_ready promote only unmarked rows, so a cleaner rollback after the object delete can no longer leave a ready attachment without its object. Add fault checks for an unknown COMMIT outcome, an upload outliving the grace period and a cleaner failure after the object delete; fix the cleaner entrypoint in rules. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
10 KiB
storage-consistency Specification
Purpose
Согласованность метаданных вложений в PostgreSQL и объектов в S3 с лабы 4. Здесь описано:
- уборщик незавершённых загрузок: что и когда он убирает;
- безопасный grace period;
- поведение уборщика при отказах хранилищ.
Сверку bucket и БД (трек 2) добавят следующие changes.
Requirements
Requirement: Уборщик незавершённых загрузок
Незавершённую загрузку SHALL убирать уборщик — отдельный процесс стенда
(capability container-run), а не реплики API. Незавершённая загрузка —
вложение, которое осталось в статусе «загружается» (capability
attachments, «Порядок записи»).
Уборщик SHALL проходить по незавершённым загрузкам не реже чем раз в
[cleaner] interval_seconds. Каждую загрузку, метаданные которой
записаны раньше чем [cleaner] pending_grace_seconds назад (grace
period), он SHALL убирать по шагам:
- пометить её метаданные как убираемые и зафиксировать пометку (требование «Безопасность уборки»);
- удалить объект по ключу из её метаданных; отсутствие объекта — не ошибка;
- только после подтверждённого удаления объекта — удалить метаданные.
Каждый шаг SHALL быть безопасно повторяемым: проход, прерванный на любом шаге, доводит следующий. После уборки у вложения не остаётся ни метаданных, ни объекта. Объект вложения без метаданных уборка MUST NOT оставлять: метаданные удаляются последними.
Ограничение называется в REPORT.md. Объект может остаться без
метаданных, если процесс API заморожен дольше grace посреди записи
объекта и после разморозки дописал объект уже убранной загрузки, а
удалить его не смог: запись объекта завершилась для API ошибкой по
сроку, или не удалось удаление при компенсации. Такой объект находит
только сверка bucket и БД (трек 2).
Scenario: Зависшая загрузка убрана
- WHEN загрузка оборвалась после записи метаданных: S3 был
остановлен или заморожен на время записи объекта, либо PostgreSQL
отказал при фиксации
ready. С записи метаданных прошло больше grace, S3 и PostgreSQL доступны - THEN ни метаданных, ни объекта этого вложения нет, а в bucket нет объектов вложений без метаданных
Scenario: Объект без фиксации убран
- WHEN объект вложения записан в S3, а процесс API убит до фиксации
ready - THEN до истечения grace есть и метаданные в статусе «загружается», и объект, а после него нет ни того, ни другого, и в bucket нет объектов вложений без метаданных
Requirement: Безопасность уборки
Уборщик MUST NOT трогать готовые вложения (ready) ни в каком возрасте.
Незавершённую загрузку моложе grace он тоже MUST NOT трогать.
Grace SHALL быть больше наибольшего времени, за которое живая загрузка
проходит путь от записи метаданных до фиксации ready. Это два шага с
PostgreSQL и запись объекта, у каждого свой срок (capability
service-configuration, «Параметры уборщика»). Возраст загрузки
отсчитывается от записи её метаданных по часам приложения.
Загрузка, которая длится дольше grace (процесс API заморожен), и уборщик SHALL исключать друг друга на одном вложении. Исходов два:
- вложение стало
readyвместе с объектом, и уборщик его не трогает; - уборщик начал его уборку, а загрузка отвечает 503
unavailableи удаляет записанный ею объект.
До удаления объекта уборщик SHALL помечать метаданные вложения как
убираемые и фиксировать пометку отдельно. Помеченное вложение MUST NOT
становиться ready. Поэтому сбой уборки после удаления объекта не даёт
вложения ready без объекта: загрузка отвечает 503, а уборку доводит
следующий проход. Сбой — например, не удалось удалить метаданные, или
S3 выполнил удаление уже после срока вызова. Вложение ready без
объекта MUST NOT появляться ни при каком порядке этих действий.
Ограничение называется в REPORT.md. Пока идёт поочерёдная замена
реплик API, реплики прежней версии пометку не проверяют. Для их
загрузок, переживших grace, это свойство не гарантировано.
Scenario: Загрузка дольше grace
- WHEN загрузка записала объект, а к переводу в
readyеё метаданным уже больше grace, и уборщик убирает их, пока загрузка ждёт перевода - THEN ответ 503
unavailable, а не 201 и не 500, нет ни метаданных, ни объекта этого вложения, а в bucket нет объектов вложений без метаданных
Scenario: Сбой уборки после удаления объекта
- WHEN загрузка ждёт перевода в
ready, её метаданным больше grace, а уборщик удалил её объект, но удалить метаданные не смог: PostgreSQL отказал - THEN ответ загрузки 503
unavailable, а не 201, метаданные в статусе «загружается», и вложенияreadyбез объекта нет - AND когда удаление метаданных снова проходит, уборщик доводит уборку, и в bucket нет объектов вложений без метаданных
Scenario: Свежая загрузка не тронута
- WHEN незавершённой загрузке меньше grace, а уборщик за это время сделал несколько проходов
- THEN её метаданные в статусе «загружается» на месте, и убираются они только после истечения grace
Scenario: Готовые вложения не тронуты
- WHEN готовому вложению больше grace, и уборщик всё это время работал, в том числе убирал незавершённые загрузки
- THEN метаданные вложения — 200 в статусе
ready, а байты скачиваются с тем же SHA-256
Requirement: Уборка при отказах хранилищ
Уборщик MUST NOT удалять метаданные незавершённой загрузки, пока удаление её объекта не подтверждено. Это касается и отказа S3: недоступен, не ответил за срок вызова, отказал в доступе или bucket нет. Промах чтения объекта не основание удалять метаданные: отсутствие объекта уборщик выясняет только подтверждённым удалением.
При отказе S3 проход SHALL прерываться на первой же загрузке и повторяться через интервал. При недоступной PostgreSQL проход SHALL пропускаться. В обоих случаях уборщик SHALL продолжать работу без перезапуска и доводить уборку, когда хранилище вернулось.
Scenario: S3 недоступен во время уборки
- WHEN незавершённой загрузке больше grace, а S3 остановлен
- THEN её метаданные остаются, пока S3 недоступен, а после возврата S3 уборщик без перезапуска убирает их и объект не позже следующего прохода
Scenario: БД недоступна во время уборки
- WHEN PostgreSQL останавливается и снова запускается, пока уборщик работает и незавершённая загрузка ещё моложе grace
- THEN после возврата PostgreSQL и истечения grace уборщик без перезапуска убирает эту загрузку