From 568ff6643eeeabc74f65f33c7cb0506ad6653894 Mon Sep 17 00:00:00 2001 From: Artyom Date: Fri, 30 Oct 2026 09:54:40 +0300 Subject: [PATCH] Archive the storage reconciler hardening change A pass releases the quarantine only after the object hashes to the row again, reads exactly ceil(N/page) SQL pages, publishes audit.attachment_discarded reason=reconcile for the intents it drops, is assembled by dishka with the same storage provider as the API and ends any failure as reconcile.failed with exit code 1. The demo passes 13 of 13 checks, and the cost matrix up to 100k confirms the request counts and the constant memory of H2 and refutes its linear time at 100k (19.6 instead of 10 +- 30 %, the RustFS listing page grows from 91 to 197 ms). student-test (348), test, persistence and failover pass on the stand. The requirements are synced into lab4-storage-reconciler. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27 --- .../.openspec.yaml | 2 ++ .../design.md | 0 .../proposal.md | 0 .../specs/lab4-storage-reconciler/spec.md | 0 .../tasks.md | 8 ++++---- .../specs/lab4-storage-reconciler/spec.md | 20 ++++++++++++++----- 6 files changed, 21 insertions(+), 9 deletions(-) rename openspec/changes/{harden-lab4-storage-reconciler => archive/2026-10-30-harden-lab4-storage-reconciler}/.openspec.yaml (58%) rename openspec/changes/{harden-lab4-storage-reconciler => archive/2026-10-30-harden-lab4-storage-reconciler}/design.md (100%) rename openspec/changes/{harden-lab4-storage-reconciler => archive/2026-10-30-harden-lab4-storage-reconciler}/proposal.md (100%) rename openspec/changes/{harden-lab4-storage-reconciler => archive/2026-10-30-harden-lab4-storage-reconciler}/specs/lab4-storage-reconciler/spec.md (100%) rename openspec/changes/{harden-lab4-storage-reconciler => archive/2026-10-30-harden-lab4-storage-reconciler}/tasks.md (89%) diff --git a/openspec/changes/harden-lab4-storage-reconciler/.openspec.yaml b/openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/.openspec.yaml similarity index 58% rename from openspec/changes/harden-lab4-storage-reconciler/.openspec.yaml rename to openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/.openspec.yaml index 4bfa6709..7756d6b7 100644 --- a/openspec/changes/harden-lab4-storage-reconciler/.openspec.yaml +++ b/openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/.openspec.yaml @@ -1,2 +1,4 @@ schema: spec-driven created: 2026-10-30 +archived: 2026-10-30 +lab: 4 diff --git a/openspec/changes/harden-lab4-storage-reconciler/design.md b/openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/design.md similarity index 100% rename from openspec/changes/harden-lab4-storage-reconciler/design.md rename to openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/design.md diff --git a/openspec/changes/harden-lab4-storage-reconciler/proposal.md b/openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/proposal.md similarity index 100% rename from openspec/changes/harden-lab4-storage-reconciler/proposal.md rename to openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/proposal.md diff --git a/openspec/changes/harden-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md b/openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md similarity index 100% rename from openspec/changes/harden-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md rename to openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md diff --git a/openspec/changes/harden-lab4-storage-reconciler/tasks.md b/openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/tasks.md similarity index 89% rename from openspec/changes/harden-lab4-storage-reconciler/tasks.md rename to openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/tasks.md index 44c8c728..11aa7c60 100644 --- a/openspec/changes/harden-lab4-storage-reconciler/tasks.md +++ b/openspec/changes/archive/2026-10-30-harden-lab4-storage-reconciler/tasks.md @@ -20,10 +20,10 @@ ## 4. Измерения -- [ ] 4.1 `make reconcile-demo` на чистом стенде → `evidence/reconcile/` -- [ ] 4.2 `make reconcile-cost` на чистом стенде (1k, 10k, 30k, 100k) → `evidence/reconcile/cost/`; прошлая серия → `cost-b191623/` -- [ ] 4.3 Проверка группы: H1 и H2 (формулировка `148868b`) по сырым отчётам +- [x] 4.1 `make reconcile-demo` на чистом стенде → `evidence/reconcile/` +- [x] 4.2 `make reconcile-cost` на чистом стенде (1k, 10k, 30k, 100k) → `evidence/reconcile/cost/`; прошлая серия → `cost-b191623/` +- [x] 4.3 Проверка группы: H1 и H2 (формулировка `148868b`) по сырым отчётам ## 5. Проверка -- [ ] 5.1 `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` +- [x] 5.1 `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` diff --git a/openspec/specs/lab4-storage-reconciler/spec.md b/openspec/specs/lab4-storage-reconciler/spec.md index 5a10ae8c..7481229d 100644 --- a/openspec/specs/lab4-storage-reconciler/spec.md +++ b/openspec/specs/lab4-storage-reconciler/spec.md @@ -5,7 +5,7 @@ ## 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` — проход или часть действий не выполнены из-за недоступной зависимости. +Сверка 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` — проход или часть действий не выполнены из-за недоступной зависимости или любой другой ошибки прохода; ошибка прохода SHALL записываться в журнал событием `reconcile.failed` с типом ошибки, без трассировки в stdout. #### Scenario: Dry-run находит и ничего не меняет @@ -17,6 +17,11 @@ - **WHEN** сервис `s3` остановлен и запущена сверка - **THEN** команда завершается с кодом `1` за ограниченное время и ничего не меняет в PostgreSQL +#### Scenario: Ошибка, не являющаяся недоступностью + +- **WHEN** проход прерывается ошибкой зависимости другого рода (например, отменой оператора PostgreSQL по `statement_timeout`) +- **THEN** журнал содержит `reconcile.failed` с типом ошибки, stdout пуст, код выхода `1` + ### Requirement: Объект без строки Объект под префиксом вложений, для ключа которого нет строки `attachments`, SHALL считаться объектом без строки. При `--apply` сверка SHALL удалять его, только если его `LastModified` старше `--grace` плюс `--skew` и повторная проверка строки по ключу непосредственно перед удалением её не нашла. Объект моложе этого порога SHALL оставаться и попадать в отдельный класс свежих. @@ -38,7 +43,7 @@ ### 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 снимать карантин. +Готовая строка, для которой нет объекта, у объекта другой размер или (в режиме `--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`). Объект каждой строки в карантине, размер которого снова совпадает с метаданными, проход SHALL читать и хешировать потоком и без `--deep`; `--apply` SHALL снимать карантин только если совпали и размер, и SHA-256. Объект той же длины с другими байтами SHALL оставлять строку в карантине. #### Scenario: Объект вложения, на которое ссылается сообщение, удалён из bucket @@ -55,14 +60,19 @@ - **WHEN** объект вложения в карантине `missing` восстановлен в bucket теми же байтами и запущен `--apply` - **THEN** карантин снят, `/content` снова отдаёт исходные байты +#### Scenario: Вернули другие байты той же длины + +- **WHEN** под ключом вложения в карантине `missing` записаны случайные байты той же длины и запущен `--apply` без `--deep` +- **THEN** вложение остаётся в карантине, `/content` отвечает `404`, отчёт показывает один `GET` на эту строку + ### Requirement: Брошенное намерение -Строка `pending`, созданная раньше чем `--grace` плюс `--skew` назад, SHALL при `--apply` удаляться вместе с объектом: сначала объект, затем строка, после повторной проверки под блокировкой строки, что она всё ещё `pending` и всё ещё старая. Строки `pending` моложе порога SHALL оставаться. +Строка `pending`, созданная раньше чем `--grace` плюс `--skew` назад, SHALL при `--apply` удаляться вместе с объектом: сначала объект, затем строка, после повторной проверки под блокировкой строки, что она всё ещё `pending` и всё ещё старая. Каждое такое удаление SHALL записываться в журнал аудита событием `audit.attachment_discarded` с причиной `reconcile`. Строки `pending` моложе порога SHALL оставаться. #### Scenario: Намерение после сбоя между записью объекта и фиксацией - **WHEN** в PostgreSQL есть строка `pending` старше grace period и её объект в bucket -- **THEN** `--apply` удаляет объект и строку; свежая строка `pending` остаётся +- **THEN** `--apply` удаляет объект и строку, журнал содержит `audit.attachment_discarded` с причиной `reconcile`; свежая строка `pending` остаётся ### Requirement: Повторяемость и единственный проход @@ -89,7 +99,7 @@ ### Requirement: Стоимость обхода -Обход без `--deep` SHALL требовать `⌈N / страница⌉` запросов листинга и столько же SQL-страниц на N объектов и строк, не делать `HEAD` и `GET` на согласованных данных и держать в памяти не больше страницы каждой стороны. Стоимость SHALL измеряться повторяемой командой на N = 1 000, 10 000 и 30 000 объектов с повторами. +Обход без `--deep` SHALL требовать `⌈N / страница⌉` запросов листинга и столько же SQL-страниц на N объектов и строк (одну SQL-страницу, если строк нет), не делать `HEAD` и `GET` на согласованных данных и держать в памяти не больше страницы каждой стороны. Стоимость SHALL измеряться повторяемой командой на N = 1 000, 10 000, 30 000 и 100 000 объектов с повторами, в том числе с `--deep`; повторный запуск SHALL заменять сырые отчёты прошлой серии, а не смешиваться с ними. #### Scenario: Матрица стоимости