Files
mtusi2026lab6/openspec/specs/storage-consistency/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e.
Contracts, public tests and evidence of lab 5 are not carried over.
The compose project, image and CI prefix are renamed to lab6; the first
broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the
OpenSpec changes of lab 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:46:56 +03:00

54 KiB
Raw Blame History

storage-consistency Specification

Purpose

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

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

Requirements

Requirement: Уборщик незавершённых загрузок

Незавершённую загрузку SHALL убирать уборщик — отдельный процесс стенда (capability container-run), а не реплики API. Незавершённая загрузка — вложение, которое осталось в статусе «загружается» (capability attachments, «Порядок записи»): на него ещё не ответили 202.

Уборщик SHALL проходить по незавершённым загрузкам не реже чем раз в [cleaner] interval_seconds. Каждую загрузку, метаданные которой записаны раньше чем [cleaner] pending_grace_seconds назад (grace period), он SHALL убирать по шагам:

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

Каждый шаг SHALL быть безопасно повторяемым: проход, прерванный на любом шаге, доводит следующий. После уборки у вложения не остаётся ни метаданных, ни объекта. Объект вложения без метаданных уборка MUST NOT оставлять: метаданные удаляются последними.

Ограничение называется в REPORT.md. Объект может остаться без метаданных, если процесс API заморожен дольше grace посреди записи объекта. После разморозки он дописывает объект уже убранной загрузки, а удалить его не может: запись объекта завершилась для API ошибкой по сроку, или не удалось удаление при компенсации. Такой объект находит и удаляет сверка bucket и БД (требование «Сверка bucket и БД»): под конечным префиксом — когда он старше grace, в staging — когда он старше срока хранения staging, на стенде — не позже следующей плановой сверки (требование «Плановая сверка»).

Scenario: Зависшая загрузка убрана

  • WHEN загрузка оборвалась после записи метаданных: S3 был остановлен или заморожен на время записи объекта, либо PostgreSQL отказал при фиксации queued. С записи метаданных прошло больше grace, S3 и PostgreSQL доступны
  • THEN ни метаданных, ни объекта этого вложения нет, а в bucket нет объектов вложений без метаданных

Scenario: Объект без фиксации убран

  • WHEN объект вложения записан в staging, а процесс API убит до фиксации queued
  • THEN до истечения grace есть и метаданные в статусе «загружается», и объект, а после него нет ни того, ни другого, и в bucket нет объектов вложений без метаданных

Scenario: Загрузка без подтверждения брокера убрана

  • WHEN реплика прежней версии на время замены не дождалась подтверждения брокера, отменила задание, вернула вложение в статус «загружается» и ответила 503, и с записи метаданных прошло больше grace
  • THEN ни метаданных, ни объекта staging этого вложения нет, а задания у него нет

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

Уборщик MUST NOT убирать принятые вложения (queued, processing, ready, failed) ни в каком возрасте: на них уже ответили 202, и это либо текущая работа, либо её итог. Их объекты staging и failed с частично записанными объектами подчиняются требованию «Очистка staging». Незавершённую загрузку моложе grace он тоже MUST NOT трогать.

Grace SHALL быть больше наибольшего времени, за которое живая загрузка проходит путь от записи метаданных до фиксации queued. Это два шага с PostgreSQL и запись объекта, у каждого свой срок (capability service-configuration, «Параметры уборщика»). Возраст загрузки отсчитывается от записи её метаданных по часам приложения. Ожидание места загрузки, чтение тела и проверка изображения (capability attachments, «Одновременные загрузки реплики», «Срок передачи тела») SHALL идти до записи метаданных и в эту границу не входят: очередь загрузок и медленный клиент её не удлиняют.

Загрузка, которая длится дольше grace (процесс API заморожен), и уборщик SHALL исключать друг друга на одном вложении. Исходов два:

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

До удаления объекта уборщик SHALL помечать метаданные вложения как убираемые и фиксировать пометку отдельно. Помеченное вложение MUST NOT становиться queued. Поэтому сбой уборки после удаления объекта не даёт принятого вложения без объекта: загрузка отвечает 503, а уборку доводит следующий проход. Сбой — например, не удалось удалить метаданные, или S3 выполнил удаление уже после срока вызова. Принятое вложение без объекта staging MUST NOT появляться ни при каком порядке этих действий.

Ограничение называется в REPORT.md. Пока идёт поочерёдная замена реплик API, реплики прежней версии пометку не проверяют. Для их загрузок, переживших grace, это свойство не гарантировано.

Scenario: Загрузка дольше grace

  • WHEN загрузка записала объект, а к переводу в queued её метаданным уже больше grace, и уборщик убирает их, пока загрузка ждёт перевода
  • THEN ответ 503 unavailable, а не 202 и не 500, нет ни метаданных, ни объекта этого вложения, а в bucket нет объектов вложений без метаданных

Scenario: Сбой уборки после удаления объекта

  • WHEN загрузка ждёт перевода в queued, её метаданным больше grace, а уборщик удалил её объект, но удалить метаданные не смог: PostgreSQL отказал
  • THEN ответ загрузки 503 unavailable, а не 202, метаданные в статусе «загружается», и принятого вложения без объекта нет
  • AND когда удаление метаданных снова проходит, уборщик доводит уборку, и в bucket нет объектов вложений без метаданных

Scenario: Свежая загрузка не тронута

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

Scenario: Готовые вложения не тронуты

  • WHEN готовому вложению больше grace, и уборщик всё это время работал, в том числе убирал незавершённые загрузки и объекты staging
  • THEN метаданные вложения — 200 в статусе ready, а байты оригинала и вариантов скачиваются с теми же SHA-256

Scenario: Текущая работа не тронута

  • WHEN worker остановлен, у вложений в queued, processing и failed возраст больше grace, но у failed меньше срока хранения staging, и уборщик всё это время работает
  • THEN их метаданные и объекты staging на месте, а после запуска worker вложение в queued становится ready

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

  • WHEN загрузка ждала места, пока его держала другая загрузка того же процесса, и обе завершились 202
  • THEN время записи метаданных ожидавшей (created_at) позже перевода в queued той, что держала место (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/ и <имя базы>/staging/ — с метаданными вложений той же базы в PostgreSQL и находить расхождения восьми классов:

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

Объект варианта, у id которого строка есть, расхождением не считается, в каком бы состоянии ни было вложение. Объект staging, на который ссылается строка, — текущая работа или дело очистки staging (требование «Очистка staging»): сверка его MUST NOT читать и менять. Наличие и размер объектов вариантов сверка не проверяет; это ограничение SHALL быть в REPORT.md.

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

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

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

Разовый проход SHALL принимать стратегию обхода:

  • по умолчанию — страницы списка объектов и одно обращение к PostgreSQL на страницу. Ключи списка сверка запоминает, а строки ready сравнивает с ними;
  • --strategy head — для каждого объекта списка отдельное обращение к PostgreSQL, для каждой строки ready — запрос метаданных её объекта в S3. Ключей списка сверка не запоминает.

Обе стратегии SHALL находить на одних данных одни и те же расхождения тех же классов и подчиняться одним правилам безопасности (требование «Безопасность сверки»). Каждое вложение ready сверка SHALL сравнивать с объектом по ключу из его метаданных, чей бы id ни стоял в этом ключе: строку, которая ссылается на <Z>/original другого вложения, сверка проверяет так же, как строку со своим ключом.

По умолчанию сверка поверхностная: наличие и размер объекта, байты она не читает. С --deep разовый проход SHALL ещё читать каждый объект вложения ready того же размера, которому больше grace, и сравнивать SHA-256 его содержимого с метаданными. Плановая сверка глубокой не бывает (требование «Плановая сверка»).

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

  • стратегию, глубину и предел скорости (требование «Скорость сверки»);
  • сколько объектов и строк просмотрено, объекты staging — отдельным числом;
  • сколько расхождений найдено и исправлено по классам;
  • сколько объектов и строк пропущено как свежие;
  • сколько вложений уже помечены потерянными;
  • сколько кандидатов не перепроверено;
  • стоимость прохода: сколько объектов S3 он затронул, запросы к S3 по операциям, сколько байтов объектов прочитано, сколько было сеансов с PostgreSQL и сколько длился каждый шаг прохода.

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

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

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

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

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

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

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

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

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

Scenario: Стратегия HEAD находит то же

  • WHEN в стенде те же расхождения, что в сценарии «Расхождения с обеих сторон найдены», и выполняются сверка без --apply со стратегией по умолчанию и с --strategy head
  • THEN оба отчёта называют одни и те же расхождения тех же классов с теми же ключами, коды выхода равны, а итог стратегии HEAD называет больше запросов к S3 и сеансов с PostgreSQL

Scenario: Другой SHA-256 находит глубокая сверка

  • WHEN объект готового вложения перезаписан мимо API байтами того же размера, вложению и объекту больше grace, и выполняется сверка без --apply — сначала без --deep, затем с --deep
  • THEN поверхностная сверка это вложение расхождением не считает, а глубокая называет его классом «другой SHA-256», и её итог называет прочитанные байты; код выхода 3, а в PostgreSQL и в bucket ничего не изменилось
  • AND сверка с --deep --apply помечает оригинал потерянным: скачивание — 404, метаданные — 200

Scenario: Строка ссылается на объект другого id

  • WHEN всё это старше grace, и выполняются сверки без --apply с --deep — стратегией по умолчанию и --strategy head:
    • готовое вложение Y1 ссылается на ключ <Z1>/original, строки Z1 нет, а объект по этому ключу другого размера, чем у Y1;
    • готовое вложение Y2 ссылается на ключ <Z2>/original, строки Z2 нет, а объект по этому ключу того же размера с другими байтами
  • THEN оба отчёта называют Y1 классом «другой размер», Y2 — «другой SHA-256», а объекты <Z1>/original, <Z2>/original, <Y1>/original и <Y2>/original — чужими; код выхода 3
  • AND сверка с --deep --apply помечает Y1 и Y2 потерянными, а все четыре объекта на месте

Scenario: Объекты вариантов своих вложений

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

Scenario: Объект варианта без метаданных

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

Scenario: Объект staging без метаданных

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

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

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

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

Вложение в queued, processing или failed сверка MUST NOT помечать потерянным и считать зависшей загрузкой: объекта конечного префикса у него может не быть, это текущая работа или её итог.

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

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

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

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

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

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

Объект другого размера или другого SHA-256, изменённый меньше grace назад, — свежий и при перепроверке: расхождение не подтверждено.

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

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

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

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

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

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

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

Scenario: Недавно перезаписанный объект не тронут

  • WHEN у двух готовых вложений старше grace объекты меньше grace назад перезаписаны мимо API — у одного байтами другого размера, у другого другими байтами того же размера, — и выполняются сверка с --deep --apply и сверка с --deep --strategy head без --apply
  • THEN ни одно вложение не помечено и не названо расхождением, а итоги считают оба объекта свежими
  • AND когда объектам больше grace, сверка с --deep называет первое классом «другой размер», второе — «другой SHA-256»

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

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

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

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

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

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

Scenario: Отказ по пределу без лишних перепроверок

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

Scenario: Предел не останавливает уборку зависших

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

Scenario: Объект, на который ссылается строка, не удаляется

  • WHEN всё это старше grace, и выполняется сверка с --apply:
    • у готового вложения X в метаданных другой ключ под префиксом вложений, объекта по нему нет, а объект <X>/original на месте;
    • готовое вложение Y ссылается на ключ <Z>/original, строки Z нет, и объекты <Y>/original и <Z>/original на месте
  • THEN результат такой:
    • все три объекта на месте, отчёт называет их чужими, код выхода 3;
    • X помечено потерянным: объекта по его ключу нет;
    • Y не помечено: объект по его ключу есть

Scenario: Ключ вне префикса вложений не трогается

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

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

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

Scenario: Текущая работа не считается расхождением

  • WHEN worker остановлен, вложения в queued, processing и failed старше grace, их объекты в staging старше срока хранения, у одного из них уже есть объект конечного ключа, и выполняется сверка с --apply
  • THEN ни одно из них не названо расхождением и не помечено потерянным, а их метаданные, объекты staging и этот объект конечного ключа на месте, код выхода от них не зависит

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

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

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

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

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

Scenario: Вернулся другой объект того же размера

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

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, интервала сверки и прохода. С пределом скорости по умолчанию проход длится не меньше секунды на каждые 2000 затронутых объектов S3 (требование «Скорость сверки»).

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

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

Requirement: Скорость сверки

Проход сверки SHALL в среднем от своего начала затрагивать не больше [reconciler] max_objects_per_second объектов S3 в секунду. Одним объектом считаются каждый ключ страницы списка, запрос метаданных объекта, чтение и удаление объекта. Обгоняя предел, проход ждёт, и ожидание MUST NOT задерживать остановку по сигналу (capability graceful-shutdown, «Остановка уборщика»). Значение 0 — без ограничения.

Разовый проход SHALL принимать предел аргументом, плановая сверка берёт его из настроек. Обращения к PostgreSQL предел не ограничивает. Найденные расхождения, исправления, правила безопасности и код выхода от предела MUST NOT зависеть.

Как выбран предел по умолчанию и какой предел нужен стратегии HEAD и глубокой сверке, SHALL быть описано в REPORT.md по замеру профиля сверки (capability load-benchmark, «Профиль сверки»).

Scenario: Скорость прохода ограничена

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

Scenario: Без ограничения скорости

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

Requirement: Очистка staging

Объекты staging SHALL убирать уборщик; worker и реплики API их не удаляют. Не реже чем раз в [cleaner] interval_seconds он SHALL:

  • у вложения ready — удалить объект staging: результат уже безопасно зафиксирован;
  • у вложения failed, которое не менялось дольше [cleaner] staging_retention_seconds (срок хранения, имя skeleton STAGING_RETENTION_SECONDS), — удалить объекты конечного оригинала и вариантов, которые успела записать прежняя попытка, затем объект staging.

После удаления ключ staging в метаданных SHALL очищаться: replay такого вложения невозможен (attachment-processing, «Реестр failed и replay»). Метаданные вложения MUST NOT удаляться: на него могут ссылаться сообщения.

Вложение в queued и processing — текущая работа: его объекты MUST NOT удаляться ни в каком возрасте. Удаляется только ключ под префиксом staging своей базы: ключ другого вида уборщик оставляет и называет в журнале. Шаг одного вложения SHALL быть безопасно повторяемым: сбой между удалением объекта и записью в PostgreSQL оставляет ключ в метаданных, а следующий проход удаляет отсутствующий объект без ошибки. При отказе S3 или PostgreSQL проход SHALL прерываться, как уборка незавершённых загрузок (требование «Уборка при отказах хранилищ»), и доводиться следующим.

Срок хранения и его обоснование SHALL быть описаны в REPORT.md.

Scenario: Staging готового вложения убран

  • WHEN вложение стало ready
  • THEN не позже следующего прохода уборщика с запасом объекта staging нет, ключ staging в метаданных пуст, а оригинал и варианты скачиваются с теми же SHA-256

Scenario: Staging неудачного вложения хранится до срока

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

Scenario: Срок хранения прошёл

  • WHEN вложение стало failed после записи конечного оригинала и вариантов, и его возраст больше срока хранения
  • THEN не позже следующего прохода уборщика с запасом ни объекта staging, ни конечного оригинала, ни объектов вариантов нет, а метаданные — 200 с status failed и тем же error_code

Scenario: Текущая работа не убирается

  • WHEN worker остановлен, а вложению в queued больше срока хранения
  • THEN его объект staging на месте, а после запуска worker вложение становится ready

Scenario: Очистка при отказе S3

  • WHEN вложение стало ready, S3 заморожен (docker pause), уборщик делает несколько проходов, и участник отправляет сообщение со ссылкой на это вложение
  • THEN отправка — 201 быстрее секунды: очистка её не держит, ключ staging в метаданных на месте, уборщик работает без перезапуска, а после разморозки S3 не позже следующего прохода с запасом объекта staging нет

Scenario: Ключ staging другого вида не удаляется

  • WHEN у готового вложения в метаданных ключ staging вне префикса staging своей базы
  • THEN объект по этому ключу на месте, а журнал уборщика называет ключ