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

717 lines
54 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.
# 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** объект по этому ключу на месте, а журнал уборщика называет ключ