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