Files
mtusi2026lab4/openspec/specs/storage-consistency/spec.md
T
ricoromaandClaude Opus 5.5 87c48b940b fix: address upload-consistency verify findings
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>
2026-10-21 21:27:47 +03:00

10 KiB
Raw Blame History

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 убирать по шагам:

  1. пометить её метаданные как убираемые и зафиксировать пометку (требование «Безопасность уборки»);
  2. удалить объект по ключу из её метаданных; отсутствие объекта — не ошибка;
  3. только после подтверждённого удаления объекта — удалить метаданные.

Каждый шаг 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 уборщик без перезапуска убирает эту загрузку