Files
mtusi2026lab4/openspec/specs/storage-consistency/spec.md
T

28 KiB
Raw Blame History

storage-consistency Specification

Purpose

Согласованность метаданных вложений в PostgreSQL и объектов в S3 с лабы 4. Здесь описано:

  • уборщик незавершённых загрузок: что и когда он убирает;
  • безопасный grace period;
  • поведение уборщика при отказах хранилищ;
  • сверка bucket и БД (трек 2, change track2-reconciler): классы расхождений, разовый и плановый проход, правила безопасности, предел изменений, потерянный оригинал и отказы хранилищ во время сверки.

Стоимость обхода и стратегии сверки описывает change track2-reconcile-cost.

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 и БД (требование «Сверка bucket и БД»), когда он старше grace. На стенде это происходит не позже следующей плановой сверки (требование «Плановая сверка»).

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, «Параметры уборщика»). Возраст загрузки отсчитывается от записи её метаданных по часам приложения. Ожидание места загрузки, чтение тела и проверка изображения (capability attachments, «Одновременные загрузки реплики», «Срок передачи тела») SHALL идти до записи метаданных и в эту границу не входят: очередь загрузок и медленный клиент её не удлиняют.

Загрузка, которая длится дольше 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

Scenario: Ожидание места не входит в возраст загрузки

  • WHEN загрузка ждала места, пока его держала другая загрузка того же процесса, и обе завершились 201
  • THEN время записи метаданных ожидавшей (created_at) позже перевода в ready той, что держала место (updated_at)

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 уборщик без перезапуска убирает эту загрузку

Requirement: Сверка bucket и БД

Сверка SHALL сравнивать объекты вложений в bucket — ключи с префиксом <имя базы>/attachments/ — с метаданными вложений той же базы в PostgreSQL и находить расхождения шести классов:

  • объект без метаданных — объект с ключом вида <база>/attachments/<id>/original, на который не ссылается ни одна строка и для id которого строки нет;
  • метаданные без объекта — вложение ready, объекта по ключу из его метаданных в bucket нет;
  • другой размер — вложение ready, размер объекта не равен size_bytes;
  • зависшая загрузка — вложение в статусе «загружается» старше grace, то же, что убирает уборщик (требование «Уборщик незавершённых загрузок»);
  • оригинал вернулся — оригинал вложения помечен потерянным (требование «Потерянный оригинал»), а объект снова есть с тем же размером;
  • чужой объект — объект под префиксом вложений, ключа такого вида API не пишет, либо ключ вида <id>/original, у строки которого другой ключ.

Сверку SHALL выполнять процесс уборщика, а не реплики API: разовым проходом (make reconcile или команда сверки в контейнере уборщика) и плановым (требование «Плановая сверка»). Разовый проход по умолчанию SHALL ничего не менять (dry-run). С --apply он SHALL исправлять:

  • объект без метаданных — удалить объект;
  • метаданные без объекта и другой размер — пометить оригинал вложения потерянным;
  • зависшую загрузку — убрать тем же порядком, что уборщик;
  • вернувшийся оригинал — снять пометку.

Чужой объект сверка MUST NOT удалять: он попадает только в отчёт.

Отчёт SHALL называть по каждому расхождению класс, ключ объекта, id вложения, если он известен, и возраст. Итог прохода SHALL называть:

  • сколько объектов и строк просмотрено;
  • сколько расхождений найдено и исправлено по классам;
  • сколько объектов и строк пропущено как свежие;
  • сколько вложений уже помечены потерянными.

После успешного исправления повторный проход SHALL не находить ни одного исправимого расхождения.

Код выхода разового прохода:

  • 0 — расхождений нет: dry-run их не нашёл, --apply исправил все, и чужих объектов нет;
  • 3 — расхождения остались: их нашёл dry-run, --apply отказался по пределу изменений или в bucket есть чужие объекты;
  • 1 — проход прерван отказом хранилища, ошибкой или сигналом;
  • 2 — неверная конфигурация.

Scenario: Расхождения с обеих сторон найдены

  • WHEN всё это старше grace, и выполняется сверка без --apply:
    • в bucket мимо API записан объект вложения;
    • у готового вложения удалён объект;
    • у неиспользуемого готового вложения удалены метаданные;
    • у другого в метаданных изменён размер;
    • загрузка оборвалась между записью объекта и фиксацией ready
  • THEN отчёт называет каждое расхождение его классом, ключом и возрастом, код выхода 3, а в PostgreSQL и в bucket ничего не изменилось

Scenario: Исправление расхождений

  • WHEN после этого выполняется сверка с --apply
  • THEN результат такой:
    • объекты без метаданных удалены;
    • зависшей загрузки нет — ни метаданных, ни объекта;
    • оба вложения с потерянным оригиналом помечены, их метаданные на месте;
    • код выхода 0

Scenario: Повторная сверка

  • WHEN сразу после исправления сверка выполняется ещё раз
  • THEN ни одного из этих расхождений в отчёте нет, а код выхода соответствует отчёту: 0, если расхождений в нём нет

Requirement: Безопасность сверки

Сверка MUST NOT удалять:

  • метаданные вложений, кроме уборки зависшей загрузки;
  • объект, на который ссылаются метаданные, в любом статусе;
  • объект с ключом вида <id>/original, если строка этого id есть.

Вложение, на которое ссылается сообщение, MUST NOT терять из-за сверки ни метаданные, ни объект, ни ссылку в истории. Если его оригинал потерян, сверка его только помечает.

Свежее сверка MUST NOT трогать и не считает расхождением:

  • объект, записанный или изменённый в S3 меньше grace назад;
  • вложение, метаданные которого записаны или переведены в ready меньше grace назад.

Grace — тот же, что у уборщика (capability service-configuration, «Параметры уборщика»).

Каждое расхождение SHALL перепроверяться в PostgreSQL и в S3 непосредственно перед действием:

  • объект без метаданных — строки с этим ключом или id по-прежнему нет, объект на месте и старше grace;
  • метаданные без объекта и другой размер — вложение по-прежнему ready с тем же ключом, а объекта по ключу нет или его размер другой;
  • вернувшийся оригинал — пометка на месте, объект того же размера.

Не подтвердилось — действие не выполняется. Отсутствие объекта MUST NOT считаться подтверждённым, пока не проверено, что bucket на месте. Иначе удалённый bucket выглядел бы как потеря всех оригиналов.

Предел изменений: если за проход нужно удалить объекты, пометить оригиналы или снять пометки больше чем у [reconciler] max_changes вложений, сверка с --apply MUST NOT выполнять ни одно из этих изменений. Она пишет ошибку с числом изменений и пределом и завершается кодом 3. Разовый проход SHALL принимать больший предел аргументом. Уборка зависших загрузок пределом не ограничена.

Сверка, уборщик и две сверки одновременно SHALL не мешать друг другу:

  • каждое действие безопасно повторять;
  • зависшую загрузку сверка убирает тем же порядком и под той же блокировкой, что уборщик.

Объекты других баз и ключи вне префикса вложений своей базы сверка MUST NOT читать и менять.

Scenario: Свежие не тронуты

  • WHEN в bucket мимо API записан объект вложения, у готового вложения удалён объект, обоим меньше grace, и выполняется сверка с --apply
  • THEN объект на месте, вложение не помечено, а отчёт считает их свежими, а не расхождениями

Scenario: Используемое вложение не удаляется

  • WHEN у вложения, на которое ссылается сообщение, удалён объект, ему больше grace, и выполняется сверка с --apply
  • THEN результат такой:
    • вложение помечено потерянным;
    • его метаданные — 200;
    • история чата по-прежнему отдаёт его id в сообщении;
    • ни одна строка вложений не удалена

Scenario: Чужой объект не удаляется

  • WHEN под префиксом вложений базы лежит объект с ключом, которого API не пишет, ему больше grace, и выполняется сверка с --apply
  • THEN объект на месте, отчёт называет его чужим, код выхода 3

Scenario: Предел изменений

  • WHEN расхождений, которые сверка исправила бы, больше предела, и выполняется сверка с --apply
  • THEN ни один объект не удалён, ни одно вложение не помечено, ошибка называет число изменений и предел, код выхода 3
  • AND с пределом не меньше их числа повтор исправляет все

Scenario: Сверка под нагрузкой

  • WHEN выполняются все условия:
    • участники дольше grace загружают вложения и отправляют сообщения с ними;
    • в это время сверка с --apply повторяется раз в несколько секунд;
    • в стенде есть внесённые расхождения
  • THEN внесённые расхождения исправлены, каждое вложение, загрузка которого ответила 201, скачивается с тем же SHA-256, а каждое сообщение отдаёт свои attachment_ids

Requirement: Потерянный оригинал

Если сверка подтвердила, что объекта готового вложения нет или его размер другой, она SHALL пометить оригинал вложения потерянным и записать время пометки в метаданные. Сверка не удаляет ни метаданные, ни ссылки сообщений, ни объект другого размера. Байты сверка не восстанавливает: их нет нигде. Что видит API для помеченного вложения — capability attachments, «Скачивание оригинала».

Пометка MUST NOT менять поля вложения в ответах API, в том числе status и updated_at. Пометку SHALL снимать сверка с --apply, когда объект по ключу вложения снова есть и его размер равен size_bytes.

Scenario: Оригинал вернулся

  • WHEN оригинал вложения помечен потерянным, затем те же байты записаны в bucket под его ключом, и выполняется сверка с --apply
  • THEN пометка снята, байты вложения скачиваются — 200 с тем же SHA-256, а следующий проход не находит расхождений по этому вложению

Requirement: Сверка при отказах хранилищ

Если S3 недоступен, не ответил за срок вызова, отказал в доступе или bucket нет, либо недоступна PostgreSQL, проход сверки SHALL прерываться на первом же отказе. Новых изменений после отказа он не делает. Код выхода разового прохода — 1. Плановая сверка повторяется через свой интервал без перезапуска процесса.

Изменения, сделанные до отказа, остаются верными. Каждое действие сверки — отдельный безопасный шаг, поэтому прерванный проход SHALL доводить следующий.

Scenario: S3 недоступен во время сверки

  • WHEN в стенде есть расхождения старше grace, S3 остановлен, и выполняется сверка с --apply
  • THEN код выхода 1, ни один объект не удалён, ни одно вложение не помечено
  • AND после возврата S3 повтор исправляет все расхождения

Scenario: Прерванная сверка доводится повтором

  • WHEN сверка с --apply прерывается отказом PostgreSQL на пометке одного из вложений
  • THEN код выхода 1
  • AND когда PostgreSQL снова принимает запись, повтор исправляет оставшиеся расхождения, и следующий проход их не находит

Requirement: Плановая сверка

Процесс уборщика SHALL сам выполнять сверку с исправлением, без разового прохода:

  • при старте;
  • затем не реже чем раз в [reconciler] interval_seconds;
  • с пределом изменений из настроек.

Значение 0 выключает плановую сверку. Плановая и разовая сверки — один и тот же проход с теми же правилами безопасности.

Ограничение называется в REPORT.md. Пока идёт проход сверки, уборка зависших загрузок ждёт его конца. Объект без метаданных на стенде живёт не дольше суммы grace, интервала сверки и прохода.

Scenario: Плановая сверка без команды

  • WHEN у готового вложения старше grace удалён объект, а уборщик работает с коротким интервалом сверки
  • THEN не позже интервала с запасом вложение помечено потерянным без разового прохода, а в журнале уборщика есть итог сверки