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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
d2744bc1ac
commit
148868bdfb
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-29
|
||||
@@ -0,0 +1,89 @@
|
||||
## Context
|
||||
|
||||
После уровня «4» (архив `2026-10-29-add-lab4-upload-resilience`) у каждой загрузки есть строка-намерение до записи объекта, компенсация сразу и уборка `pending` старше `UPLOAD_GRACE_SECONDS` в каждой реплике. Инвариант «пока объект существует, существует и строка с его ключом» держится при нормальной работе, но ничто не проверяет его со стороны bucket и ничто не проверяет, что у готовой строки есть объект с теми же байтами. Ключ объекта — `attachments/<uuid>`, `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/` не видны сверке] → сервер пишет только под префиксом; остальное — чужие данные, не трогаем.
|
||||
@@ -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`.
|
||||
@@ -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`
|
||||
@@ -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
|
||||
@@ -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`
|
||||
Reference in New Issue
Block a user