28 KiB
storage-consistency Specification
Purpose
Согласованность метаданных вложений в PostgreSQL и объектов в S3 с лабы 4. Здесь описано:
- уборщик незавершённых загрузок: что и когда он убирает;
- безопасный grace period;
- поведение уборщика при отказах хранилищ;
- сверка bucket и БД (трек 2, change
track2-reconciler): классы расхождений, разовый и плановый проход, правила безопасности, предел изменений, потерянный оригинал и отказы хранилищ во время сверки.
Стоимость обхода и стратегии сверки описывает change
track2-reconcile-cost.
Requirements
Requirement: Уборщик незавершённых загрузок
Незавершённую загрузку SHALL убирать уборщик — отдельный процесс стенда
(capability container-run), а не реплики API. Незавершённая загрузка —
вложение, которое осталось в статусе «загружается» (capability
attachments, «Порядок записи»).
Уборщик SHALL проходить по незавершённым загрузкам не реже чем раз в
[cleaner] interval_seconds. Каждую загрузку, метаданные которой
записаны раньше чем [cleaner] pending_grace_seconds назад (grace
period), он SHALL убирать по шагам:
- пометить её метаданные как убираемые и зафиксировать пометку (требование «Безопасность уборки»);
- удалить объект по ключу из её метаданных; отсутствие объекта — не ошибка;
- только после подтверждённого удаления объекта — удалить метаданные.
Каждый шаг SHALL быть безопасно повторяемым: проход, прерванный на любом шаге, доводит следующий. После уборки у вложения не остаётся ни метаданных, ни объекта. Объект вложения без метаданных уборка MUST NOT оставлять: метаданные удаляются последними.
Ограничение называется в REPORT.md. Объект может остаться без
метаданных, если процесс API заморожен дольше grace посреди записи
объекта. После разморозки он дописывает объект уже убранной загрузки, а
удалить его не может: запись объекта завершилась для API ошибкой по
сроку, или не удалось удаление при компенсации. Такой объект находит и
удаляет сверка bucket и БД (требование «Сверка bucket и БД»), когда он
старше grace. На стенде это происходит не позже следующей плановой
сверки (требование «Плановая сверка»).
Scenario: Зависшая загрузка убрана
- WHEN загрузка оборвалась после записи метаданных: S3 был
остановлен или заморожен на время записи объекта, либо PostgreSQL
отказал при фиксации
ready. С записи метаданных прошло больше grace, S3 и PostgreSQL доступны - THEN ни метаданных, ни объекта этого вложения нет, а в bucket нет объектов вложений без метаданных
Scenario: Объект без фиксации убран
- WHEN объект вложения записан в S3, а процесс API убит до фиксации
ready - THEN до истечения grace есть и метаданные в статусе «загружается», и объект, а после него нет ни того, ни другого, и в bucket нет объектов вложений без метаданных
Requirement: Безопасность уборки
Уборщик MUST NOT трогать готовые вложения (ready) ни в каком возрасте.
Незавершённую загрузку моложе grace он тоже MUST NOT трогать.
Grace SHALL быть больше наибольшего времени, за которое живая загрузка
проходит путь от записи метаданных до фиксации ready. Это два шага с
PostgreSQL и запись объекта, у каждого свой срок (capability
service-configuration, «Параметры уборщика»). Возраст загрузки
отсчитывается от записи её метаданных по часам приложения. Ожидание
места загрузки, чтение тела и проверка изображения (capability
attachments, «Одновременные загрузки реплики», «Срок передачи тела»)
SHALL идти до записи метаданных и в эту границу не входят: очередь
загрузок и медленный клиент её не удлиняют.
Загрузка, которая длится дольше grace (процесс API заморожен), и уборщик SHALL исключать друг друга на одном вложении. Исходов два:
- вложение стало
readyвместе с объектом, и уборщик его не трогает; - уборщик начал его уборку, а загрузка отвечает 503
unavailableи удаляет записанный ею объект.
До удаления объекта уборщик SHALL помечать метаданные вложения как
убираемые и фиксировать пометку отдельно. Помеченное вложение MUST NOT
становиться ready. Поэтому сбой уборки после удаления объекта не даёт
вложения ready без объекта: загрузка отвечает 503, а уборку доводит
следующий проход. Сбой — например, не удалось удалить метаданные, или
S3 выполнил удаление уже после срока вызова. Вложение ready без
объекта MUST NOT появляться ни при каком порядке этих действий.
Ограничение называется в REPORT.md. Пока идёт поочерёдная замена
реплик API, реплики прежней версии пометку не проверяют. Для их
загрузок, переживших grace, это свойство не гарантировано.
Scenario: Загрузка дольше grace
- WHEN загрузка записала объект, а к переводу в
readyеё метаданным уже больше grace, и уборщик убирает их, пока загрузка ждёт перевода - THEN ответ 503
unavailable, а не 201 и не 500, нет ни метаданных, ни объекта этого вложения, а в bucket нет объектов вложений без метаданных
Scenario: Сбой уборки после удаления объекта
- WHEN загрузка ждёт перевода в
ready, её метаданным больше grace, а уборщик удалил её объект, но удалить метаданные не смог: PostgreSQL отказал - THEN ответ загрузки 503
unavailable, а не 201, метаданные в статусе «загружается», и вложенияreadyбез объекта нет - AND когда удаление метаданных снова проходит, уборщик доводит уборку, и в bucket нет объектов вложений без метаданных
Scenario: Свежая загрузка не тронута
- WHEN незавершённой загрузке меньше grace, а уборщик за это время сделал несколько проходов
- THEN её метаданные в статусе «загружается» на месте, и убираются они только после истечения grace
Scenario: Готовые вложения не тронуты
- WHEN готовому вложению больше grace, и уборщик всё это время работал, в том числе убирал незавершённые загрузки
- THEN метаданные вложения — 200 в статусе
ready, а байты скачиваются с тем же SHA-256
Scenario: Ожидание места не входит в возраст загрузки
- WHEN загрузка ждала места, пока его держала другая загрузка того же процесса, и обе завершились 201
- THEN время записи метаданных ожидавшей (
created_at) позже перевода вreadyтой, что держала место (updated_at)
Requirement: Уборка при отказах хранилищ
Уборщик MUST NOT удалять метаданные незавершённой загрузки, пока удаление её объекта не подтверждено. Это касается и отказа S3: недоступен, не ответил за срок вызова, отказал в доступе или bucket нет. Промах чтения объекта не основание удалять метаданные: отсутствие объекта уборщик выясняет только подтверждённым удалением.
При отказе S3 проход SHALL прерываться на первой же загрузке и повторяться через интервал. При недоступной PostgreSQL проход SHALL пропускаться. В обоих случаях уборщик SHALL продолжать работу без перезапуска и доводить уборку, когда хранилище вернулось.
Scenario: S3 недоступен во время уборки
- WHEN незавершённой загрузке больше grace, а S3 остановлен
- THEN её метаданные остаются, пока S3 недоступен, а после возврата S3 уборщик без перезапуска убирает их и объект не позже следующего прохода
Scenario: БД недоступна во время уборки
- WHEN PostgreSQL останавливается и снова запускается, пока уборщик работает и незавершённая загрузка ещё моложе grace
- THEN после возврата PostgreSQL и истечения grace уборщик без перезапуска убирает эту загрузку
Requirement: Сверка bucket и БД
Сверка SHALL сравнивать объекты вложений в bucket — ключи с префиксом
<имя базы>/attachments/ — с метаданными вложений той же базы в
PostgreSQL и находить расхождения шести классов:
- объект без метаданных — объект с ключом вида
<база>/attachments/<id>/original, на который не ссылается ни одна строка и дляidкоторого строки нет; - метаданные без объекта — вложение
ready, объекта по ключу из его метаданных в bucket нет; - другой размер — вложение
ready, размер объекта не равенsize_bytes; - зависшая загрузка — вложение в статусе «загружается» старше grace, то же, что убирает уборщик (требование «Уборщик незавершённых загрузок»);
- оригинал вернулся — оригинал вложения помечен потерянным (требование «Потерянный оригинал»), а объект снова есть с тем же размером;
- чужой объект — объект под префиксом вложений, ключа такого вида
API не пишет, либо ключ вида
<id>/original, у строки которого другой ключ.
Сверку SHALL выполнять процесс уборщика, а не реплики API: разовым
проходом (make reconcile или команда сверки в контейнере уборщика) и
плановым (требование «Плановая сверка»). Разовый проход по умолчанию
SHALL ничего не менять (dry-run). С --apply он SHALL исправлять:
- объект без метаданных — удалить объект;
- метаданные без объекта и другой размер — пометить оригинал вложения потерянным;
- зависшую загрузку — убрать тем же порядком, что уборщик;
- вернувшийся оригинал — снять пометку.
Чужой объект сверка MUST NOT удалять: он попадает только в отчёт.
Отчёт SHALL называть по каждому расхождению класс, ключ объекта, id
вложения, если он известен, и возраст. Итог прохода SHALL называть:
- сколько объектов и строк просмотрено;
- сколько расхождений найдено и исправлено по классам;
- сколько объектов и строк пропущено как свежие;
- сколько вложений уже помечены потерянными.
После успешного исправления повторный проход SHALL не находить ни одного исправимого расхождения.
Код выхода разового прохода:
- 0 — расхождений нет: dry-run их не нашёл,
--applyисправил все, и чужих объектов нет; - 3 — расхождения остались: их нашёл dry-run,
--applyотказался по пределу изменений или в bucket есть чужие объекты; - 1 — проход прерван отказом хранилища, ошибкой или сигналом;
- 2 — неверная конфигурация.
Scenario: Расхождения с обеих сторон найдены
- WHEN всё это старше grace, и выполняется сверка без
--apply:- в bucket мимо API записан объект вложения;
- у готового вложения удалён объект;
- у неиспользуемого готового вложения удалены метаданные;
- у другого в метаданных изменён размер;
- загрузка оборвалась между записью объекта и фиксацией
ready
- THEN отчёт называет каждое расхождение его классом, ключом и возрастом, код выхода 3, а в PostgreSQL и в bucket ничего не изменилось
Scenario: Исправление расхождений
- WHEN после этого выполняется сверка с
--apply - THEN результат такой:
- объекты без метаданных удалены;
- зависшей загрузки нет — ни метаданных, ни объекта;
- оба вложения с потерянным оригиналом помечены, их метаданные на месте;
- код выхода 0
Scenario: Повторная сверка
- WHEN сразу после исправления сверка выполняется ещё раз
- THEN ни одного из этих расхождений в отчёте нет, а код выхода соответствует отчёту: 0, если расхождений в нём нет
Requirement: Безопасность сверки
Сверка MUST NOT удалять:
- метаданные вложений, кроме уборки зависшей загрузки;
- объект, на который ссылаются метаданные, в любом статусе;
- объект с ключом вида
<id>/original, если строка этогоidесть.
Вложение, на которое ссылается сообщение, MUST NOT терять из-за сверки ни метаданные, ни объект, ни ссылку в истории. Если его оригинал потерян, сверка его только помечает.
Свежее сверка MUST NOT трогать и не считает расхождением:
- объект, записанный или изменённый в S3 меньше grace назад;
- вложение, метаданные которого записаны или переведены в
readyменьше grace назад.
Grace — тот же, что у уборщика (capability service-configuration,
«Параметры уборщика»).
Каждое расхождение SHALL перепроверяться в PostgreSQL и в S3 непосредственно перед действием:
- объект без метаданных — строки с этим ключом или
idпо-прежнему нет, объект на месте и старше grace; - метаданные без объекта и другой размер — вложение по-прежнему
readyс тем же ключом, а объекта по ключу нет или его размер другой; - вернувшийся оригинал — пометка на месте, объект того же размера.
Не подтвердилось — действие не выполняется. Отсутствие объекта MUST NOT считаться подтверждённым, пока не проверено, что bucket на месте. Иначе удалённый bucket выглядел бы как потеря всех оригиналов.
Предел изменений: если за проход нужно удалить объекты, пометить
оригиналы или снять пометки больше чем у [reconciler] max_changes
вложений, сверка с --apply MUST NOT выполнять ни одно из этих
изменений. Она пишет ошибку с числом изменений и пределом и завершается
кодом 3. Разовый проход SHALL принимать больший предел аргументом.
Уборка зависших загрузок пределом не ограничена.
Сверка, уборщик и две сверки одновременно SHALL не мешать друг другу:
- каждое действие безопасно повторять;
- зависшую загрузку сверка убирает тем же порядком и под той же блокировкой, что уборщик.
Объекты других баз и ключи вне префикса вложений своей базы сверка MUST NOT читать и менять.
Scenario: Свежие не тронуты
- WHEN в bucket мимо API записан объект вложения, у готового
вложения удалён объект, обоим меньше grace, и выполняется сверка с
--apply - THEN объект на месте, вложение не помечено, а отчёт считает их свежими, а не расхождениями
Scenario: Используемое вложение не удаляется
- WHEN у вложения, на которое ссылается сообщение, удалён объект,
ему больше grace, и выполняется сверка с
--apply - THEN результат такой:
- вложение помечено потерянным;
- его метаданные — 200;
- история чата по-прежнему отдаёт его
idв сообщении; - ни одна строка вложений не удалена
Scenario: Чужой объект не удаляется
- WHEN под префиксом вложений базы лежит объект с ключом, которого
API не пишет, ему больше grace, и выполняется сверка с
--apply - THEN объект на месте, отчёт называет его чужим, код выхода 3
Scenario: Предел изменений
- WHEN расхождений, которые сверка исправила бы, больше предела, и
выполняется сверка с
--apply - THEN ни один объект не удалён, ни одно вложение не помечено, ошибка называет число изменений и предел, код выхода 3
- AND с пределом не меньше их числа повтор исправляет все
Scenario: Сверка под нагрузкой
- WHEN выполняются все условия:
- участники дольше grace загружают вложения и отправляют сообщения с ними;
- в это время сверка с
--applyповторяется раз в несколько секунд; - в стенде есть внесённые расхождения
- THEN внесённые расхождения исправлены, каждое вложение, загрузка
которого ответила 201, скачивается с тем же SHA-256, а каждое
сообщение отдаёт свои
attachment_ids
Requirement: Потерянный оригинал
Если сверка подтвердила, что объекта готового вложения нет или его
размер другой, она SHALL пометить оригинал вложения потерянным и
записать время пометки в метаданные. Сверка не удаляет ни метаданные, ни
ссылки сообщений, ни объект другого размера. Байты сверка не
восстанавливает: их нет нигде. Что видит API для помеченного вложения —
capability attachments, «Скачивание оригинала».
Пометка MUST NOT менять поля вложения в ответах API, в том числе
status и updated_at. Пометку SHALL снимать сверка с --apply, когда
объект по ключу вложения снова есть и его размер равен size_bytes.
Scenario: Оригинал вернулся
- WHEN оригинал вложения помечен потерянным, затем те же байты
записаны в bucket под его ключом, и выполняется сверка с
--apply - THEN пометка снята, байты вложения скачиваются — 200 с тем же SHA-256, а следующий проход не находит расхождений по этому вложению
Requirement: Сверка при отказах хранилищ
Если S3 недоступен, не ответил за срок вызова, отказал в доступе или bucket нет, либо недоступна PostgreSQL, проход сверки SHALL прерываться на первом же отказе. Новых изменений после отказа он не делает. Код выхода разового прохода — 1. Плановая сверка повторяется через свой интервал без перезапуска процесса.
Изменения, сделанные до отказа, остаются верными. Каждое действие сверки — отдельный безопасный шаг, поэтому прерванный проход SHALL доводить следующий.
Scenario: S3 недоступен во время сверки
- WHEN в стенде есть расхождения старше grace, S3 остановлен, и
выполняется сверка с
--apply - THEN код выхода 1, ни один объект не удалён, ни одно вложение не помечено
- AND после возврата S3 повтор исправляет все расхождения
Scenario: Прерванная сверка доводится повтором
- WHEN сверка с
--applyпрерывается отказом PostgreSQL на пометке одного из вложений - THEN код выхода 1
- AND когда PostgreSQL снова принимает запись, повтор исправляет оставшиеся расхождения, и следующий проход их не находит
Requirement: Плановая сверка
Процесс уборщика SHALL сам выполнять сверку с исправлением, без разового прохода:
- при старте;
- затем не реже чем раз в
[reconciler] interval_seconds; - с пределом изменений из настроек.
Значение 0 выключает плановую сверку. Плановая и разовая сверки — один и тот же проход с теми же правилами безопасности.
Ограничение называется в REPORT.md. Пока идёт проход сверки, уборка
зависших загрузок ждёт его конца. Объект без метаданных на стенде живёт
не дольше суммы grace, интервала сверки и прохода.
Scenario: Плановая сверка без команды
- WHEN у готового вложения старше grace удалён объект, а уборщик работает с коротким интервалом сверки
- THEN не позже интервала с запасом вложение помечено потерянным без разового прохода, а в журнале уборщика есть итог сверки