forked from mtusi2026/mtusi2026lab2
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:
co-authored by
Claude Opus 5.5
parent
58cae16ef8
commit
81dd816df2
+2
@@ -1,2 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-29
|
||||
archived: 2026-10-30
|
||||
lab: 4
|
||||
@@ -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 за окно прогона; прогоны с чужой нагрузкой выше порога отбракованы, сохранены отдельно и повторены
|
||||
|
||||
Reference in New Issue
Block a user