From 148868bdfbd5bacfd8026e55065a835ee1869da9 Mon Sep 17 00:00:00 2001 From: Artyom Date: Thu, 29 Oct 2026 03:05:42 +0300 Subject: [PATCH] Propose the storage reconciler as an openspec change Track 2 of grade 5: a one-off reconciler that merges the sorted bucket listing with keyset pages of the attachments table, so a pass is linear in time and holds one page per side in memory. It finds objects without a row, ready rows without an object or with another size or digest, and abandoned intents; by default it only reports, with --apply it deletes old orphans after a row recheck, drops stale intents object first, and quarantines broken ready rows instead of deleting them, so referenced attachments survive and a restored object heals. A quarantined attachment answers 404 on its content. An advisory lock keeps a single pass at a time. The design states the hypotheses on correctness and on the cost of a pass, the reproducible method behind make reconcile-demo and make reconcile-cost, and the acceptance criteria. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27 --- .../.openspec.yaml | 2 + .../add-lab4-storage-reconciler/design.md | 89 +++++++++++++++++ .../add-lab4-storage-reconciler/proposal.md | 29 ++++++ .../specs/lab4-attachments/spec.md | 30 ++++++ .../specs/lab4-storage-reconciler/spec.md | 98 +++++++++++++++++++ .../add-lab4-storage-reconciler/tasks.md | 43 ++++++++ 6 files changed, 291 insertions(+) create mode 100644 openspec/changes/add-lab4-storage-reconciler/.openspec.yaml create mode 100644 openspec/changes/add-lab4-storage-reconciler/design.md create mode 100644 openspec/changes/add-lab4-storage-reconciler/proposal.md create mode 100644 openspec/changes/add-lab4-storage-reconciler/specs/lab4-attachments/spec.md create mode 100644 openspec/changes/add-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md create mode 100644 openspec/changes/add-lab4-storage-reconciler/tasks.md diff --git a/openspec/changes/add-lab4-storage-reconciler/.openspec.yaml b/openspec/changes/add-lab4-storage-reconciler/.openspec.yaml new file mode 100644 index 00000000..5c99d6d7 --- /dev/null +++ b/openspec/changes/add-lab4-storage-reconciler/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-29 diff --git a/openspec/changes/add-lab4-storage-reconciler/design.md b/openspec/changes/add-lab4-storage-reconciler/design.md new file mode 100644 index 00000000..1e067309 --- /dev/null +++ b/openspec/changes/add-lab4-storage-reconciler/design.md @@ -0,0 +1,89 @@ +## Context + +После уровня «4» (архив `2026-10-29-add-lab4-upload-resilience`) у каждой загрузки есть строка-намерение до записи объекта, компенсация сразу и уборка `pending` старше `UPLOAD_GRACE_SECONDS` в каждой реплике. Инвариант «пока объект существует, существует и строка с его ключом» держится при нормальной работе, но ничто не проверяет его со стороны bucket и ничто не проверяет, что у готовой строки есть объект с теми же байтами. Ключ объекта — `attachments/`, `object_key text COLLATE "C" UNIQUE` (миграция `0003`): порядок индекса байтовый, как у листинга S3. Ключ API S3 уже имеет `ListBucket`, `GetObject`, `DeleteObject` (нужное сверке) и не имеет прав на bucket и IAM. + +Изменение затрагивает только зону `attachments`; `messaging` не трогается, связь с сообщениями держит внешний ключ `message_attachments → attachments ON DELETE RESTRICT`. + +## Goals / Non-Goals + +**Goals:** +- Один проход находит все расхождения пяти классов и исправляет только то, что безопасно исправить без потери данных, повторный проход ничего не делает. +- Время прохода линейно по N, память не зависит от N. +- Каждое утверждение трека воспроизводится командой `make` против стенда с сырыми отчётами в `evidence/reconcile/`. + +**Non-Goals:** +- Восстановление байтов: второго источника байтов нет, сверка только помечает. +- Запуск по расписанию (cron/systemd/фоновая задача API) — задача эксплуатации; повторяемость обеспечивает одна команда. +- Сверка незавершённых multipart: сервер ими не пользуется, их удаляет lifecycle-правило bucket через сутки. + +## Decisions + +### D1. Слияние двух отсортированных потоков вместо поиска по одной стороне + +Проход одновременно читает листинг `ListObjectsV2(Prefix="attachments/", MaxKeys=page)` (S3 отдаёт ключи в байтовом порядке UTF-8) и страницы keyset + +```sql +SELECT … FROM attachments WHERE object_key > $1 ORDER BY object_key LIMIT $2 +``` + +(`Index Scan` по `attachments_object_key_key`, сортировка `COLLATE "C"` совпадает с порядком S3). Обработка — слияние: для каждой строки сначала все объекты с меньшим ключом (объекты без строки), затем равный ключ (пара) или его отсутствие (строка без объекта); после строк — оставшиеся объекты. Получаем O(N) по времени, `⌈N/page⌉` запросов листинга и столько же SQL, в памяти — по странице каждой стороны. Стоит это зависимостью от одинакового порядка сторон: без `COLLATE "C"` или с ключами другого формата слияние разойдётся (ключи назначает сервер, формат фиксирован). + +Отвергнуто: `HEAD` на каждую строку (N запросов к S3 и нет обнаружения объектов без строки); загрузка всего листинга в множество (память O(N)); `pg_dump`/`rc ls` и сравнение файлов (не исправляет и не повторяемо в одну команду). + +### D2. Классы и действия + +| Класс | Условие | `--apply` | +| --- | --- | --- | +| `orphan_stale` | объект без строки, `LastModified < now − grace − skew` | повторный `SELECT … WHERE object_key=$1`; строки нет → `DeleteObject` | +| `orphan_fresh` | объект без строки моложе порога | ничего | +| `missing` | `ready`, объекта нет | `HEAD`: 404 → карантин `missing` | +| `size_mismatch` | `ready`, `Size ≠ size_bytes` | `HEAD`: размер всё ещё другой → карантин | +| `sha_mismatch` | `--deep`: SHA-256 потока ≠ `sha256` | карантин | +| `pending_stale` | `pending`, `created_at < now − grace − skew` | `SELECT … FOR UPDATE SKIP LOCKED`, всё ещё `pending` и старая → `DeleteObject`, `DELETE … AND status='pending'` | +| `pending_fresh` | `pending` моложе порога | ничего | +| `quarantined` | уже в карантине и всё ещё расходится | ничего | +| `healed` | в карантине, объект снова совпал (для `sha_mismatch` — только при `--deep`) | снять карантин | + +Каждое действие предваряется повторной проверкой той стороны, которую оно затрагивает: между листингом и действием могла пройти загрузка, уборка API или ручное исправление. Отказ после проверки учитывается в отчёте (`rechecked`). Ошибка зависимости в одном действии считается (`errors`), проход идёт дальше; ошибка листинга или страницы прерывает проход (код `1`). + +### D3. Карантин вместо удаления, его видимое действие + +Миграция `0004` добавляет `quarantine_reason text CHECK (… IN ('missing','size_mismatch','sha_mismatch'))` и `quarantined_at timestamptz` (оба NULL или оба заданы). Колонки допускают NULL, `ADD COLUMN` без значения по умолчанию только меняет каталог — совместимо с работающей версией (expand). Готовая строка не удаляется никогда: на неё могут ссылаться сообщения (`ON DELETE RESTRICT` — последний рубеж на уровне БД), а пропавший объект может вернуться из копии. Агрегат `Attachment` получает значение `quarantine: Quarantine | None`. `OpenAttachment` для вложения в карантине отвечает `404` без запроса к S3 и пишет `attachment.quarantined`: клиент не получит байты, расходящиеся с `sha256`. Метаданные не меняются (`updated_at` тоже), поэтому контракт не затронут. Получаем обратимость: `healed` снимает карантин. Стоит это одной колонкой в `SELECT` и ветвью в скачивании. + +### D4. Grace, skew и защита свежего + +Порог `now − grace − skew`: `grace` (по умолчанию 3600 с, минимум 60) перекрывает жизнь загрузки (`REQUEST_TIMEOUT_SECONDS` 8 с плюс отложенный `PUT` 6 с) и уборку API (900 с), `skew` (по умолчанию 60 с) — расхождение часов сервера S3 (`LastModified`) и процесса сверки. Порядок записи уровня «3» (строка до объекта) делает объект без строки возможным только после сбоя или чужой записи; свежий объект без строки — это идущая загрузка, увиденная между страницами, и он не трогается. Готовые строки и их объекты не удаляются ни при каких условиях (D2). Порог для `pending` тот же, по `created_at`. + +### D5. Один проход — `pg_try_advisory_lock` + +Проход берёт сессионную блокировку `pg_try_advisory_lock(20260004)` на отдельном соединении на всё время работы (вне транзакции — `idle_in_transaction_session_timeout` не мешает). Не взял — отчёт `skipped`, код `0`. Транзакционная блокировка отвергнута: проход длится минуты, транзакция на это время держала бы снимок и упиралась в таймаут простоя. С уборкой API сверка не конфликтует: обе удаляют `pending` под `SKIP LOCKED` и проверяют статус после блокировки. + +### D6. Глубокая проверка + +`--deep` для каждой пары с совпавшим размером запускает потоковый `GetObject` и SHA-256 кусками по 64 KiB в задаче `TaskGroup`; число задач в полёте ограничено `--deep-concurrency` (8). Память — O(concurrency × кусок), время — O(суммарного объёма). Действия из задач идут в своих UoW (фабрика UoW), чтобы не делить одно соединение. + +### D7. Где живёт код + +- Домен: `Quarantine` (StrEnum) и поле агрегата. +- Приложение: команда `ReconcileStorage`, `StorageReconciler` и отчёт `Reconciliation` в `attachments/application/reconcile.py`; порты `ObjectStorage.listing/stat` и `StoredObject`, `AttachmentRepository.page_after/by_key/claim/mark`, `SingleRun`. +- Инфраструктура: адаптер S3 (пагинатор `list_objects_v2`, `head_object`), адаптер PostgreSQL (keyset, `SKIP LOCKED`, `UPDATE` карантина), `PostgresSingleRun`. +- Точка входа: `attachments/entrypoints/reconcile.py` (`python -m messenger.attachments.entrypoints.reconcile`): argparse → команда, сборка адаптеров без dishka (как `migrate.py`: контейнер приложения требует связей зон, которые сверке не нужны), JSON отчёта в stdout, журнал в stderr (платформенный логгер получает параметр потока). Отдельной зоны и каталога точек входа нет, `main.py` не меняется. +- Стенд: сервис `reconciler` (образ API, профиль `reconcile`, `entrypoint` — модуль, `command: ["--dry-run"]`, ключ API S3 и `database_url`, `read_only`, 1 CPU / 256 MiB, `cpuset` из переменной для замеров). Права ключа API уже достаточны — отдельный ключ не заводится. + +### D8. Гипотеза, методика, критерии + +**Гипотеза H1 (корректность).** Слияние находит каждое внедрённое расхождение в его классе (dry-run = внедрённому), `--apply` исправляет ровно найденное исправимое, повторный `--apply` — 0 действий; свежие объекты и намерения, готовые и используемые вложения не удаляются, в том числе во время загрузок. + +**Гипотеза H2 (стоимость).** Время прохода без `--deep` растёт линейно (`t(100k)/t(10k) ≈ 10 ± 30 %`) и определяется числом страниц листинга; запросов листинга и SQL — `⌈N/1000⌉`, `HEAD`/`GET` — 0; пик RSS одинаков для 1k и 100k (разница < 10 %). `--deep` на порядок дороже на объект и линеен по объёму. + +**Методика.** `make reconcile-demo` (`scripts/reconcile_track.py demo`): наполнение через API (вложения, часть в сообщениях) → снимок готовых по независимой проверке `scripts/reconcile_check.py` (SQL + `rc`, вне API) → внедрение `scripts/reconcile-inject.sh` на обеих сторонах (объект без строки, удалённый объект в том числе у используемого вложения, другой размер, подмена байтов той же длины, `pending` без объекта и с объектом, старых) → пауза больше grace → ещё свежие объекты без строки и свежий `pending` → `--dry-run --deep` → `--apply --deep` дважды → проверка инвариантов, API-проверки карантина и восстановление объекта (`healed`) → проходы `--apply` в цикле во время загрузок через LB → проверка `--deep` с `--expect-ready`. `make reconcile-cost` (`scripts/reconcile_track.py cost`): снимок `docker stats` всех контейнеров хоста, закрепление `cpuset` у `s3`, `postgres` и `reconciler`, наполнение до N = 1 000, 10 000, 100 000 (`student-tests/tools/seed_storage.py` в образе API: параллельные `PutObject` и `COPY`), по 3 прогона dry-run на точку (страница 1000), `--deep` для 1k и 10k, страница 100 на 10k. Метрики — из отчёта сверки (время, запросы, RSS) и время контейнера. + +**Критерии.** H1: все проверки `demo` истинны (`ok: true`), `lost_ready = 0`. H2: соотношения выше на медианах трёх прогонов. + +## Risks / Trade-offs + +- [Порядок ключей S3 и PostgreSQL разойдётся на нестандартных ключах] → `COLLATE "C"` на колонке, ключи назначает сервер; тест адаптера проверяет лексикографический порядок листинга RustFS. +- [Расхождение часов S3 и сверки больше `skew`] → один хост; `skew` настраивается; удаление дополнительно требует повторной проверки строки. +- [Сверка во время бэкапа/восстановления одной стороны пометит много строк] → карантин обратим (`healed`), строки не удаляются; dry-run перед apply. +- [`--deep` на большом bucket долгий и грузит S3] → отдельный флаг, ограниченная параллельность, запускать реже. +- [Объекты вне префикса `attachments/` не видны сверке] → сервер пишет только под префиксом; остальное — чужие данные, не трогаем. diff --git a/openspec/changes/add-lab4-storage-reconciler/proposal.md b/openspec/changes/add-lab4-storage-reconciler/proposal.md new file mode 100644 index 00000000..753f6fd0 --- /dev/null +++ b/openspec/changes/add-lab4-storage-reconciler/proposal.md @@ -0,0 +1,29 @@ +## Why + +Уровень «4» убирает только то, что началось со строки-намерения: компенсация и уборка `pending`. Расхождения после ручных правок, восстановления одной стороны из копии или порчи диска — объект без строки, готовая строка без объекта, другой размер или байты — никто не находит. Трек 2 рубрики `README.md` («5»): повторяемый reconciler для orphan/missing объектов и метаданных, внедрение ошибок на обеих сторонах, обнаружение и безопасное исправление с dry-run и повторным запуском, доказательство, что свежие и используемые вложения не удаляются, и стоимость обхода. Закрывает заявленный трек «5» и его раздел в `REPORT.md`. + +## What Changes + +- Одноразовая команда сверки PostgreSQL ↔ S3 (сервис `reconciler` под профилем compose `reconcile`), по умолчанию `--dry-run`; `--apply` исправляет. Один проход: слияние отсортированного листинга bucket и страниц таблицы `attachments` по ключу объекта — время O(N), память O(страница); `--deep` дополнительно хеширует каждый объект потоком. +- Классы: объект без строки (старше grace — удаляется после повторной проверки строки, моложе — остаётся), готовая строка без объекта, другой размер, другой SHA-256 (помещаются в карантин, строки не удаляются), `pending` старше grace (объект, затем строка), карантин, который снова сошёлся (снимается). Одновременный запуск двух проходов исключён блокировкой PostgreSQL. Отчёт — JSON со счётчиками и стоимостью обхода. +- Карантин: миграция `0004` добавляет причину и время карантина; `/content` вложения в карантине отвечает `404`, метаданные не меняются. +- Обвязка: внедрение ошибок на обеих сторонах, независимая проверка инвариантов вне API, сценарий трека и матрица стоимости — `make reconcile-demo` и `make reconcile-cost`. + +## Capabilities + +### New Capabilities +- `lab4-storage-reconciler`: сверка метаданных вложений с объектами S3 — классы расхождений, dry-run и apply, повторяемость, защита свежих и используемых вложений, единственный одновременный проход, отчёт и стоимость обхода. + +### Modified Capabilities +- `lab4-attachments`: «Метаданные и скачивание только участникам» — `/content` вложения в карантине отвечает `404`. + +## Impact + +- Код: зона `attachments` (домен — причина карантина; приложение — сверка и порты листинга, `HEAD`, страниц по ключу; адаптеры S3 и PostgreSQL; точка входа CLI), журнал платформы может писать в stderr; миграция `0004_attachment_quarantine.sql` (аддитивная). +- Стенд: `compose.yaml` (сервис `reconciler`, закрепление CPU для замеров), `Makefile`, `scripts/` (внедрение ошибок, проверка инвариантов, сценарий трека), инструмент наполнения хранилища в `student-tests/tools/`. +- Тесты: `student-tests/api` (сверка), `student-tests/adapters` (листинг и `HEAD` против RustFS). +- Отчёт: раздел трека 2, `evidence/reconcile/`. + +## Non-goals + +Периодический запуск по расписанию, восстановление байтов из резервной копии, удаление вложений пользователем, сверка незавершённых multipart (их удаляет lifecycle-правило bucket), presigned upload (трек 1), `202 queued` и варианты (лаба 5) — Out of scope `openspec/config.yaml`. diff --git a/openspec/changes/add-lab4-storage-reconciler/specs/lab4-attachments/spec.md b/openspec/changes/add-lab4-storage-reconciler/specs/lab4-attachments/spec.md new file mode 100644 index 00000000..e783a166 --- /dev/null +++ b/openspec/changes/add-lab4-storage-reconciler/specs/lab4-attachments/spec.md @@ -0,0 +1,30 @@ +## MODIFIED Requirements + +### 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`. Вложение, помещённое сверкой в карантин (capability `lab4-storage-reconciler`), SHALL отдавать метаданные как прежде, а `/content` SHALL отвечать `404` без обращения к S3, чтобы клиент не получил байты, расходящиеся с `sha256` метаданных. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`. + +#### Scenario: Второй участник скачивает оригинал + +- **WHEN** второй участник чата запрашивает `/content` загруженного вложения с `Accept: application/json` +- **THEN** ответ `200`, `Content-Type: image/png`, байты совпадают с загруженными, SHA-256 равен `sha256` метаданных + +#### Scenario: Посторонний + +- **WHEN** пользователь вне чата запрашивает метаданные или `/content` +- **THEN** оба ответа `404` с кодом `not_found` + +#### Scenario: Неизвестный вариант + +- **WHEN** запрошен `/content?variant=thumbnail` +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Объект пропал из хранилища + +- **WHEN** метаданные готового вложения есть, а объекта в bucket нет +- **THEN** `/content` отвечает `404`, событие пишется в журнал без ключа объекта + +#### Scenario: Вложение в карантине + +- **WHEN** сверка поместила вложение в карантин из-за расхождения байтов с метаданными +- **THEN** метаданные отвечают `200` с прежними полями, `/content` — `404` с кодом `not_found` diff --git a/openspec/changes/add-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md b/openspec/changes/add-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md new file mode 100644 index 00000000..dd607a17 --- /dev/null +++ b/openspec/changes/add-lab4-storage-reconciler/specs/lab4-storage-reconciler/spec.md @@ -0,0 +1,98 @@ +## Purpose + +Определяет сверку метаданных вложений в PostgreSQL с объектами bucket: какие расхождения она находит, что и при каких условиях исправляет, как защищены свежие и используемые вложения, что она сообщает и сколько стоит обход. Трассируется на трек 2 рубрики «5» `README.md`. + +## ADDED 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 и 100 000 объектов с повторами. + +#### Scenario: Матрица стоимости + +- **WHEN** выполняется `make reconcile-cost` +- **THEN** для каждого N сохранены сырые отчёты не меньше трёх прогонов: время, число запросов листинга, SQL, `HEAD`, `GET` и пик RSS diff --git a/openspec/changes/add-lab4-storage-reconciler/tasks.md b/openspec/changes/add-lab4-storage-reconciler/tasks.md new file mode 100644 index 00000000..93f27b0a --- /dev/null +++ b/openspec/changes/add-lab4-storage-reconciler/tasks.md @@ -0,0 +1,43 @@ +## 1. Схема и миграции + +- [ ] 1.1 `0004_attachment_quarantine.sql`: `quarantine_reason` с `CHECK`, `quarantined_at`, согласованность пары +- [ ] 1.2 Проверка группы: `make student-test` (`test_migrations.py`: повтор без изменений) + +## 2. Зона `attachments`: домен и приложение + +- [ ] 2.1 Домен: `Quarantine`, поле `quarantine` агрегата +- [ ] 2.2 Порты: `StoredObject`, `ObjectStorage.listing/stat`, `AttachmentRepository.page_after/by_key/claim/mark`, `SingleRun`; команда `ReconcileStorage` +- [ ] 2.3 `StorageReconciler`: слияние потоков, классы, повторные проверки, действия, `--deep` под ограничением, отчёт `Reconciliation` +- [ ] 2.4 `OpenAttachment`: карантин → `404` без S3 +- [ ] 2.5 Проверка группы: `make lint` + +## 3. Зона `attachments`: адаптеры и точка входа + +- [ ] 3.1 Адаптер S3: листинг страницами, `HEAD`; адаптер PostgreSQL: колонка карантина, keyset, по ключу, `SKIP LOCKED`, `UPDATE` карантина, `PostgresSingleRun` +- [ ] 3.2 Платформа: поток журнала настраивается +- [ ] 3.3 CLI `messenger.attachments.entrypoints.reconcile`: флаги, сборка адаптеров, JSON в stdout, коды выхода +- [ ] 3.4 Проверка группы: API-тесты сверки против одноразового PostgreSQL (каждый класс в dry-run без изменений, apply и повтор = 0, свежее и используемое сохранены, строка появилась после листинга, карантин и `404`, `healed`, `--deep`, занятая блокировка); тест адаптера против RustFS (порядок листинга, страницы, `HEAD`) + +## 4. Стенд + +- [ ] 4.1 `compose.yaml`: сервис `reconciler` (профиль `reconcile`), `cpuset` из переменных у `s3`, `postgres`, `reconciler`; `.env.example` +- [ ] 4.2 Цели `make reconcile ARGS=…`, `make reconcile-demo`, `make reconcile-cost` +- [ ] 4.3 Проверка группы: `docker compose config --quiet`, `make up`, `make reconcile` + +## 5. Обвязка трека + +- [ ] 5.1 `scripts/reconcile-inject.sh` и `scripts/reconcile_check.py` из заготовки +- [ ] 5.2 `student-tests/tools/seed_storage.py`: наполнение N объектов и строк в образе API +- [ ] 5.3 `scripts/reconcile_track.py`: `demo` (внедрение, dry-run, apply ×2, безопасность, `healed`, нагрузка) и `cost` (снимок хоста, закрепление CPU, матрица N × режим × 3) +- [ ] 5.4 Проверка группы: `make check` (Python 3.9, JSON), `make lint` + +## 6. Измерения + +- [ ] 6.1 `make reconcile-demo` на чистом стенде → `evidence/reconcile/` +- [ ] 6.2 `make reconcile-cost` на чистом стенде → `evidence/reconcile/cost/` +- [ ] 6.3 Проверка группы: критерии H1 и H2 из `design.md` + +## 7. Отчёт + +- [ ] 7.1 `REPORT.md`: раздел трека 2 (гипотеза, методика, результаты, ограничения, выводы), строки трека в таблице доказательств и отказов; `AGENTS.md` +- [ ] 7.2 Проверка группы: `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`