diff --git a/openspec/changes/add-lab4-storage-reconciler/.openspec.yaml b/openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/.openspec.yaml similarity index 58% rename from openspec/changes/add-lab4-storage-reconciler/.openspec.yaml rename to openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/.openspec.yaml index 5c99d6d7..82282c46 100644 --- a/openspec/changes/add-lab4-storage-reconciler/.openspec.yaml +++ b/openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/.openspec.yaml @@ -1,2 +1,4 @@ schema: spec-driven created: 2026-10-29 +archived: 2026-10-30 +lab: 4 diff --git a/openspec/changes/add-lab4-storage-reconciler/design.md b/openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/design.md similarity index 100% rename from openspec/changes/add-lab4-storage-reconciler/design.md rename to openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/design.md diff --git a/openspec/changes/add-lab4-storage-reconciler/proposal.md b/openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/proposal.md similarity index 100% rename from openspec/changes/add-lab4-storage-reconciler/proposal.md rename to openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/proposal.md diff --git a/openspec/changes/add-lab4-storage-reconciler/specs/lab4-attachments/spec.md b/openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/specs/lab4-attachments/spec.md similarity index 100% rename from openspec/changes/add-lab4-storage-reconciler/specs/lab4-attachments/spec.md rename to openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/specs/lab4-attachments/spec.md diff --git a/openspec/changes/add-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md b/openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md similarity index 100% rename from openspec/changes/add-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md rename to openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md diff --git a/openspec/changes/add-lab4-storage-reconciler/tasks.md b/openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/tasks.md similarity index 100% rename from openspec/changes/add-lab4-storage-reconciler/tasks.md rename to openspec/changes/archive/2026-10-30-add-lab4-storage-reconciler/tasks.md diff --git a/openspec/specs/lab4-attachments/spec.md b/openspec/specs/lab4-attachments/spec.md index c981e3b7..aac57811 100644 --- a/openspec/specs/lab4-attachments/spec.md +++ b/openspec/specs/lab4-attachments/spec.md @@ -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 не остаётся. diff --git a/openspec/specs/lab4-storage-reconciler/spec.md b/openspec/specs/lab4-storage-reconciler/spec.md new file mode 100644 index 00000000..5a10ae8c --- /dev/null +++ b/openspec/specs/lab4-storage-reconciler/spec.md @@ -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 за окно прогона; прогоны с чужой нагрузкой выше порога отбракованы, сохранены отдельно и повторены +