Archive the storage reconciler change

Track 2 of lab 4 is closed. One reconciler pass merges the sorted bucket
listing with keyset pages of attachments by object key, finds objects
without a row, ready rows without an object or with other bytes and
abandoned intents, deletes only old objects without a row after a
second look at the row and old intents under SKIP LOCKED, and puts
damaged ready rows into a reversible quarantine instead of deleting
them. On the stand the dry-run found exactly the 22 injected
discrepancies of seven classes, apply fixed the 18 fixable ones, the
repeat did nothing, and 75 passes during 3418 uploads lost no ready
attachment. A shallow pass costs 0.105 / 1.000 / 3.729 s for 1k / 10k /
30k objects at a flat 83 MiB, 95 % of it in the RustFS listing; --deep
is 4.3-5 times dearer per object.

For the defence: make reconcile-demo shows injection, dry-run, apply,
the repeat, quarantine through the API, healing, the held lock, a
stopped S3 and the run under uploads in about four minutes; the cost
matrix is evidence/reconcile/cost/summary.txt (make reconcile-cost
repeats it on a fresh stand in about seven).

The lab4-storage-reconciler spec is added and the quarantine rule of
lab4-attachments is updated in the main specs.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
This commit is contained in:
Artyom
2026-10-30 07:19:42 +03:00
co-authored by Claude Opus 5.5
parent 58cae16ef8
commit 81dd816df2
8 changed files with 106 additions and 1 deletions
@@ -1,2 +1,4 @@
schema: spec-driven
created: 2026-10-29
archived: 2026-10-30
lab: 4
+6 -1
View File
@@ -101,7 +101,7 @@
### Requirement: Метаданные и скачивание только участникам
`GET /api/v1/attachments/{attachment_id}` SHALL возвращать `200 Attachment` участнику чата вложения. `GET /api/v1/attachments/{attachment_id}/content` SHALL возвращать участнику `200` с исходными байтами, `Content-Type` вложения и `Content-Length`, через API, без redirect, вне зависимости от заголовка `Accept`. Параметр `variant` SHALL принимать только `original` (по умолчанию). Посторонний, неизвестный id и ещё не готовое вложение SHALL получать `404` с кодом `not_found`, не раскрывающим существование вложения; невалидный UUID и неизвестный `variant` — `400`. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`.
`GET /api/v1/attachments/{attachment_id}` SHALL возвращать `200 Attachment` участнику чата вложения. `GET /api/v1/attachments/{attachment_id}/content` SHALL возвращать участнику `200` с исходными байтами, `Content-Type` вложения и `Content-Length`, через API, без redirect, вне зависимости от заголовка `Accept`. Параметр `variant` SHALL принимать только `original` (по умолчанию). Посторонний, неизвестный id и ещё не готовое вложение SHALL получать `404` с кодом `not_found`, не раскрывающим существование вложения; невалидный UUID и неизвестный `variant` — `400`. Вложение, помещённое сверкой в карантин (capability `lab4-storage-reconciler`), SHALL отдавать метаданные как прежде, а `/content` SHALL отвечать `404` без обращения к S3, чтобы клиент не получил байты, расходящиеся с `sha256` метаданных. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`.
#### Scenario: Второй участник скачивает оригинал
@@ -123,6 +123,11 @@
- **WHEN** метаданные готового вложения есть, а объекта в bucket нет
- **THEN** `/content` отвечает `404`, событие пишется в журнал без ключа объекта
#### Scenario: Вложение в карантине
- **WHEN** сверка поместила вложение в карантин из-за расхождения байтов с метаданными
- **THEN** метаданные отвечают `200` с прежними полями, `/content` — `404` с кодом `not_found`
### Requirement: Порядок записи PostgreSQL и S3
Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи объекта и SHALL переводить вложение в готовое только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `201` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. Намерение и объект, оставшиеся после сбоя, SHALL удаляться компенсацией сразу или уборкой по истечении grace period (capability `lab4-upload-resilience`), поэтому объект без строки-намерения в bucket не остаётся.
@@ -0,0 +1,98 @@
# lab4-storage-reconciler Specification
## Purpose
Определяет сверку метаданных вложений в PostgreSQL с объектами bucket: какие расхождения она находит, что и при каких условиях исправляет, как защищены свежие и используемые вложения, что она сообщает и сколько стоит обход. Трассируется на трек 2 рубрики «5» `README.md`.
## Requirements
### Requirement: Отчёт без изменений по умолчанию
Сверка SHALL запускаться одноразовой командой стенда (`docker compose run --rm --no-deps reconciler [флаги]`) и без флагов SHALL работать в режиме `--dry-run`: читать обе стороны и ничего не менять. Режим `--apply` SHALL исправлять найденное по правилам этой capability. Результат SHALL выводиться в stdout одним документом JSON: режим, grace period, число просмотренных объектов и строк, найденное и исправленное по классам, примеры id вложений (или ключей объектов без строки), число запросов листинга, `HEAD`, `GET`, удалений и SQL, время прохода, процессорное время и пик RSS процесса. Отчёт и журнал SHALL NOT содержать ключей доступа S3, паролей и токенов. Код выхода `0` — проход завершён; `1` — проход или часть действий не выполнены из-за недоступной зависимости.
#### Scenario: Dry-run находит и ничего не меняет
- **WHEN** в стенде внедрено по нескольку расхождений каждого класса и запущена сверка без флагов
- **THEN** отчёт показывает каждое внедрённое расхождение в своём классе, а число объектов, строк и их статусов после прохода то же, что до него
#### Scenario: S3 недоступен
- **WHEN** сервис `s3` остановлен и запущена сверка
- **THEN** команда завершается с кодом `1` за ограниченное время и ничего не меняет в PostgreSQL
### Requirement: Объект без строки
Объект под префиксом вложений, для ключа которого нет строки `attachments`, SHALL считаться объектом без строки. При `--apply` сверка SHALL удалять его, только если его `LastModified` старше `--grace` плюс `--skew` и повторная проверка строки по ключу непосредственно перед удалением её не нашла. Объект моложе этого порога SHALL оставаться и попадать в отдельный класс свежих.
#### Scenario: Старый объект без строки удалён
- **WHEN** в bucket записан объект под префиксом вложений без строки, выдержана пауза больше grace period и запущен `--apply`
- **THEN** объект удалён, отчёт показывает одно исправление класса устаревших объектов без строки
#### Scenario: Свежий объект без строки сохранён
- **WHEN** объект без строки записан позже, чем за grace period до прохода `--apply`
- **THEN** объект остаётся в bucket, отчёт относит его к свежим
#### Scenario: Строка появилась во время прохода
- **WHEN** во время прохода, после листинга, появилась строка с ключом старого объекта
- **THEN** объект не удаляется, отчёт учитывает отказ от действия после повторной проверки
### Requirement: Готовое вложение без объекта или с другими байтами
Готовая строка, для которой нет объекта, у объекта другой размер или (в режиме `--deep`) другой SHA-256, SHALL относиться к классу `missing`, `size_mismatch` или `sha_mismatch`. Сверка SHALL NOT удалять такую строку и SHALL NOT удалять объект готовой строки. При `--apply` сверка SHALL помещать строку в карантин с причиной, предварительно повторно проверив объект запросом `HEAD` для `missing` и `size_mismatch`. Строка в карантине SHALL оставаться видимой в метаданных и в сообщениях, `/content` SHALL отвечать `404` (capability `lab4-attachments`). Если объект строки в карантине снова совпадает с метаданными (для `sha_mismatch` — только при проверке `--deep`), `--apply` SHALL снимать карантин.
#### Scenario: Объект вложения, на которое ссылается сообщение, удалён из bucket
- **WHEN** объект готового вложения, прикреплённого к сообщению, удалён напрямую в bucket и запущен `--apply`
- **THEN** строка вложения и ссылка сообщения сохранены, вложение в карантине с причиной `missing`, метаданные отвечают `200`, `/content` — `404`
#### Scenario: Байты подменены без изменения размера
- **WHEN** объект готового вложения перезаписан случайными байтами той же длины
- **THEN** проход без `--deep` расхождения не видит, проход с `--deep` относит строку к `sha_mismatch`, а `--apply --deep` помещает её в карантин
#### Scenario: Объект вернули
- **WHEN** объект вложения в карантине `missing` восстановлен в bucket теми же байтами и запущен `--apply`
- **THEN** карантин снят, `/content` снова отдаёт исходные байты
### Requirement: Брошенное намерение
Строка `pending`, созданная раньше чем `--grace` плюс `--skew` назад, SHALL при `--apply` удаляться вместе с объектом: сначала объект, затем строка, после повторной проверки под блокировкой строки, что она всё ещё `pending` и всё ещё старая. Строки `pending` моложе порога SHALL оставаться.
#### Scenario: Намерение после сбоя между записью объекта и фиксацией
- **WHEN** в PostgreSQL есть строка `pending` старше grace period и её объект в bucket
- **THEN** `--apply` удаляет объект и строку; свежая строка `pending` остаётся
### Requirement: Повторяемость и единственный проход
Повторный `--apply` сразу после полного SHALL выполнять ноль действий. Результат dry-run SHALL совпадать по классам с тем, что затем исправляет `--apply` на тех же данных. Одновременно SHALL выполняться не больше одного прохода: второй SHALL завершаться с кодом `0` и отметкой `skipped`, ничего не читая и не меняя.
#### Scenario: Повторный apply
- **WHEN** `--apply` запущен дважды подряд
- **THEN** второй отчёт показывает ноль исправлений во всех классах
#### Scenario: Два прохода одновременно
- **WHEN** проход уже выполняется и запущен второй
- **THEN** второй отвечает `skipped` и ничего не меняет
### Requirement: Сохранность свежих и используемых вложений
Сверка SHALL NOT удалять строку `ready`, объект строки `ready`, строку `pending` моложе grace period и объект моложе grace period. Под параллельной нагрузкой загрузок через API проходы `--apply` SHALL NOT приводить к потере готовых вложений: после нагрузки каждое вложение, получившее `201`, существует, готово и его объект совпадает с метаданными по размеру и SHA-256.
#### Scenario: Сверка во время загрузок
- **WHEN** клиенты непрерывно загружают вложения через LB, а проходы `--apply` запускаются друг за другом
- **THEN** число потерянных готовых вложений равно `0`, независимая проверка с хешированием всех объектов не находит расхождений, кроме внедрённых в карантине
### Requirement: Стоимость обхода
Обход без `--deep` SHALL требовать `⌈N / страница⌉` запросов листинга и столько же SQL-страниц на N объектов и строк, не делать `HEAD` и `GET` на согласованных данных и держать в памяти не больше страницы каждой стороны. Стоимость SHALL измеряться повторяемой командой на N = 1 000, 10 000 и 30 000 объектов с повторами.
#### Scenario: Матрица стоимости
- **WHEN** выполняется `make reconcile-cost`
- **THEN** для каждого N сохранены сырые отчёты не меньше трёх прогонов: время, процессорное время, число запросов листинга, SQL, `HEAD`, `GET`, пик RSS и чужая нагрузка CPU за окно прогона; прогоны с чужой нагрузкой выше порога отбракованы, сохранены отдельно и повторены