From c13df14f36ff9e2e58dc45c5f335850d06568306 Mon Sep 17 00:00:00 2001 From: roman Date: Thu, 22 Oct 2026 17:06:14 +0300 Subject: [PATCH] docs: propose track2-reconciler Co-Authored-By: Claude Opus 5.5 --- PLAN.md | 124 +++ .../changes/track2-reconciler/.openspec.yaml | 2 + openspec/changes/track2-reconciler/design.md | 722 ++++++++++++++++++ .../changes/track2-reconciler/proposal.md | 146 ++++ .../specs/attachments/spec.md | 58 ++ .../specs/graceful-shutdown/spec.md | 36 + .../specs/object-storage/spec.md | 159 ++++ .../specs/service-configuration/spec.md | 38 + .../specs/service-logging/spec.md | 44 ++ .../specs/storage-consistency/spec.md | 290 +++++++ .../specs/student-tests/spec.md | 102 +++ openspec/changes/track2-reconciler/tasks.md | 398 ++++++++++ 12 files changed, 2119 insertions(+) create mode 100644 openspec/changes/track2-reconciler/.openspec.yaml create mode 100644 openspec/changes/track2-reconciler/design.md create mode 100644 openspec/changes/track2-reconciler/proposal.md create mode 100644 openspec/changes/track2-reconciler/specs/attachments/spec.md create mode 100644 openspec/changes/track2-reconciler/specs/graceful-shutdown/spec.md create mode 100644 openspec/changes/track2-reconciler/specs/object-storage/spec.md create mode 100644 openspec/changes/track2-reconciler/specs/service-configuration/spec.md create mode 100644 openspec/changes/track2-reconciler/specs/service-logging/spec.md create mode 100644 openspec/changes/track2-reconciler/specs/storage-consistency/spec.md create mode 100644 openspec/changes/track2-reconciler/specs/student-tests/spec.md create mode 100644 openspec/changes/track2-reconciler/tasks.md diff --git a/PLAN.md b/PLAN.md index 06c6f713..551c7949 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1108,3 +1108,127 @@ apply»; вопрос 1 открыт — сделано 429, как по умо `student-tests/contract.py`, ожидания `test_upload_slots_busy` и `test_rejections_before_queue`, сценарии спеков `attachments` и `api-conventions`, правило `api-contract.md`. + +### track2-reconciler + +#### Решения + +Приняты 2026-10-22 в `/opsx:propose`, подробности — design change +`track2-reconciler`. Пробы — design, Context: проект compose `rcprobe`, +SeaweedFS и PostgreSQL на tmpfs, bootstrap проекта. + +1. **Сверка — часть уборщика** (решение 1): + - команда `python -m src.cleaner reconcile [--apply] [--max-changes + N]`, по умолчанию dry-run; цель `make reconcile [APPLY=1]`; + - плановая сверка в сервисе `cleaner` — при старте и раз в + `[reconciler] interval_seconds` (3600 с), с исправлением; + - `--once` — как было. + + Отвергнуты: + - отдельный сервис и пользователь S3 `reconciler`: второй процесс и + два секрета ради почти пустого разделения прав; + - сверка только вручную: PUT-зомби жил бы до запуска. + + С уборщиком на строках `pending` сверка не спорит: убирает их его + процедурой (`FOR UPDATE SKIP LOCKED` и пометка), а объект строки любого + статуса не удаляет никогда. +2. **Права S3** (решение 2). `cleaner-objects` получает `s3:ListBucket` + с условием `s3:prefix` `<база>/attachments/*`, префикс bootstrap берёт + из `POSTGRES_DB` (`S3_CLEANER_LIST_PREFIX`). Проба: SeaweedFS 4.48 + условие соблюдает — весь bucket, `test_/` и чужой bucket дают 403. + Нового пользователя и секретов нет. `make s3_check` получает строки + списка ключом уборщика. +3. **Проход** (решение 3): + - страницы LIST по 1000; + - на страницу — одно выражение к БД по `id` (по тексту ключа — только + для нестандартных ключей: по пробе в 15 раз дороже); + - множество увиденных ключей, затем keyset строк `ready` по `id`. + + Слияние отсортированных потоков отвергнуто: порядок списка SeaweedFS — + обход каталогов, а не порядок байтов (проба). Действия — только после + классификации, каждое с перепроверкой в БД и HEAD. +4. **Безопасность** (решение 4): + - grace уборщика по `LastModified` объекта и времени строки; + - удаляются только объекты без строки и зависшие загрузки; + - чужие ключи — только отчёт и код 3; + - отсутствие объекта не подтверждается без проверки bucket; + - предел `[reconciler] max_changes` (100): больше — ни одного + изменения, код 3. +5. **Потерянный оригинал** (решение 5) — колонка `attachments.lost_at`. + `status` и `updated_at` не меняются. Ответы API: + - скачивание помеченного — 404 без обращения к S3, до пометки — 500, + как было; + - метаданные — 200; + - ссылка в сообщении — 201. + + Это вариант по умолчанию до ответа на вопрос 1 ниже. Статус + `lost`/`failed` отвергнут: контракт лабы 4 знает только `ready`. +6. **Миграция** (решение 6) — `ADD COLUMN lost_at` с `SET LOCAL + lock_timeout`. По пробе это только каталог: 0,36 мс. Смеси версий не + хуже, чем до change. Порядок обновления: + - вперёд — `s3-bootstrap`, `make rolling_update`, затем уборщик; + - откат — сначала уборщик. +7. **Коды разового прохода** (решение 8): 0 — расхождений нет, 3 — + остались (в том числе чужой объект или отказ по пределу), 1 — + прерван, 2 — конфигурация. +8. **Стенд отказов** (решения 9, 11): + - плановая сверка выключена (`RECONCILER__INTERVAL_SECONDS=0`); + - сверку запускает hook; + - новые действия hook: объект мимо API, удаление объекта, строки и + размера, сдвиг времени строки, `lost-ids`, `fail-attachments mark`, + `reconcile`, `stop|start cleaner`, `run-cleaner`; + - восемь тестов отказов, ~+3 мин; объекты без строки ждут grace, а + строки состаривает hook. +9. **Evidence** (решение 12), `evidence/reconcile/`: + - `cycle.md` — драйвер `reconcile-cycle`: dry-run, apply, повтор = 0, + возврат оригинала; + - `stress.md` — `reconcile-stress`; + - `service.md`. + + Плюс `evidence/s3/cleaner-list.md` и `evidence/migrations/lost-at.md`. +10. **Граница с `track2-reconcile-cost`** (решение 13). Здесь — одна + стратегия «батч» и поверхностная сверка (наличие и размер). Там: + - HEAD на строку; + - глубокая сверка SHA-256; + - ограничение скорости; + - профиль `reconcile` стенда `bench/`; + - гипотезы 1–4. + + Гипотезу 5 проверяет стресс этого change. +11. **Запись `KNOWN_ISSUES.md` о bootstrap после удаления bucket — + воспроизведена и объяснена** (design, Context; решение 14). Причина — + не имя bucket, а слоты томов: + - `-volume.max=0` даёт на tmpfs 4 ГБ три слота; + - после удаления коллекции их занимают тома коллекции по умолчанию; + - PUT получает «no free volumes left», 500. + + На 16 ГБ повтор bootstrap прошёл за 2 с. У рабочего стенда 403 + свободных слота. Reconciler bucket не создаёт, поэтому запись не + чинится. В apply её текст переписывается, запись остаётся открытой. + +#### Вопросы + +1. **Вопрос преподавателю.** Что отвечает API лабы 4 на вложение, + оригинал которого потерян, после того как сверка это подтвердила? + Объекта в bucket нет или он другого размера, байтов не восстановить. + + Контракт неоднозначен: + - `contracts/openapi.json`: у `Attachment.status` в лабе 4 одно + значение — `ready`, `failed` и 409 появляются с лабы 5; + - `contracts/README.md`: «Отсутствующий вариант ready-объекта — 404», + «404 — объекта нет или он чужой» и «Неожиданное исключение — 500». + + Варианты: + - (а) **по умолчанию:** метаданные — 200 как раньше (`ready`, + `error_code=null`), байты — 404 `not_found`, как отсутствующий + вариант, ссылка в новом сообщении — 201. До пометки байты — 500: + непредвиденное расхождение; + - (б) вложение целиком как незавершённое: метаданные, байты и ссылка + — 404; + - (в) байты — 500 и после пометки: пометка только для отчёта. + + Ответ (б) или (в) меняет только ветку `open_content` и выборку + вложений сообщения, сценарий `attachments` «Потерянный оригинал», тест + `test_reconcile_finds_and_fixes` и `REPORT.md`. Классы, правила + безопасности, схема и задачи сверки не меняются (design, Open + Questions). diff --git a/openspec/changes/track2-reconciler/.openspec.yaml b/openspec/changes/track2-reconciler/.openspec.yaml new file mode 100644 index 00000000..7cc41bb5 --- /dev/null +++ b/openspec/changes/track2-reconciler/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-22 diff --git a/openspec/changes/track2-reconciler/design.md b/openspec/changes/track2-reconciler/design.md new file mode 100644 index 00000000..780e482a --- /dev/null +++ b/openspec/changes/track2-reconciler/design.md @@ -0,0 +1,722 @@ +# Design + +## Context + +Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. + +### Код + +Состояние после `upload-memory` (`5f4b9ff`): + +- **Уборщик.** `python -m src.cleaner [--once]` (`src/cleaner/main.py`): + - свой engine (пул 1) и клиент S3 с ключами пользователя `cleaner`; + - цикл «проход → ожидание `[cleaner] interval_seconds` или сигнала», + проверка grace > B = 17 с при старте; + - коды 0/1/2. + + Проход — `AttachmentCleanupService.clean_stale_pending`: кандидаты + keyset по частичному индексу, каждая строка в два шага под `FOR UPDATE + SKIP LOCKED` — пометка, затем объект и строка одной транзакцией. + Объект без строки и строку `ready` без объекта он не ищет. +- **Права S3 уборщика** (`infra/s3/bootstrap.sh`, политика + `cleaner-objects`): только `s3:GetObject` и `s3:DeleteObject` на + `/*`. Bootstrap и `make s3_check` проверяют, что список + объектов ключом уборщика — 403. Спек `object-storage` («Ограниченные + учётные данные уборщика») прямо запрещает ему список. +- **Клиент S3** (`ObjectStorage`) умеет `put`, `head`, `open`, `delete`, + списка у него нет. `_call` всегда передаёт `Key`. Удалённый bucket у + HEAD неотличим от отсутствующего ключа, правило — `PLAN.md`, + `s3-storage`, вопрос 4. +- **Скачивание** (`AttachmentService.open_content`): нет объекта или + другой размер — `error` «Attachment content is missing» / «…size + differs» и 500 (`AttachmentContentMissing`). Строка не меняется. +- **Схема `attachments`:** + - `status IN ('pending', 'ready')`; + - уникальный `object_key` — индекс `uq_attachments_object_key`; + - частичный индекс `pending`; + - CHECK `updated_at >= created_at`. + + Колонки пометки нет. Чтение и вставка перечисляют свои колонки + (`_ATTACHMENT_COLUMNS`), поэтому новая колонка прежнему коду не мешает. +- **Тесты.** Стенд отказов запускает уборщика с grace 20 с и интервалом + 1 с. Hook умеет `attachment-ids`, `object-ids` (`fs.tree`), + `fail-attachments …`, `kill-api` / `start-api`. Сверка покрытия + требует тест или исключение для каждого сценария `storage-consistency`. + +### Пробы (2026-10-22, scratchpad, проект compose `rcprobe`) + +Стенд пробы: +- SeaweedFS тем же образом и аргументами, что `s3`, данные на tmpfs; +- PostgreSQL 18.6 на tmpfs; +- клиент botocore в образе `mtusi-messenger:lab4`; +- bootstrap — сам `infra/s3/bootstrap.sh` проекта (read-only). + +Volumes не создавались. Проект удалён, список volumes и сетей совпал с +исходным (155 и 17). + +| Проверка | Результат | +|---|---| +| Ключ уборщика с текущей политикой: список bucket, с префиксом и без, v1 и v2, HEAD bucket | 403 `AccessDenied`; HEAD отсутствующего ключа — 404, GET — `NoSuchKey` | +| `s3:ListBucket` на `arn:aws:s3:::messenger` | список своего bucket — 200, чужого — 403, HEAD bucket — 200, запись — 403 | +| `s3:ListBucket` с `Condition: StringLike s3:prefix messenger/attachments/*` | префикс `messenger/attachments/` — 200, весь bucket и `test_messenger/` — 403, HEAD bucket — 403, чужой bucket — 403. Условие SeaweedFS 4.48 соблюдает. Постраничный список под этим условием (3 страницы по 1000) — полный | +| `s3:ListBucket` только на ресурсе `/*` | списка нет (403), как в AWS | +| ListObjectsV2, 2 503 и 20 003 ключа под префиксом, MaxKeys 1000 | 3 и 21 страница, 0,31 с и ~2,0 с (~0,1 мс на ключ); `LastModified` с точностью до секунды, UTC; `Size`, `ETag`; токен продолжения — последний ключ открытым текстом | +| Порядок списка на соседях `aaa/…`, `aaa-x`, `aaa.y/…`, `aaa0` | порядок обхода каталогов: `aaa/original`, `aaa/zzz`, затем `aaa-x`. Это не порядок байтов: в нём `aaa-x` < `aaa.y/…` < `aaa/…`. Страницы по одному ключу совпали с одной страницей без пропусков и повторов | +| `weed shell fs.rm` объекта в `/buckets/…` | HEAD — 404, в списке объекта нет, пустой каталог `/` в список не попадает | +| bucket удалён (`s3.bucket.delete`) | список с префиксом — 404 `NoSuchBucket`, GET — `NoSuchBucket`, HEAD объекта — 404, как отсутствующий ключ | +| PostgreSQL, 21 000 строк (20 000 `ready`), общий план | `ALTER TABLE … ADD COLUMN lost_at timestamptz` — 0,36 мс (только каталог). Страница 1000 ключей `object_key = ANY($1) OR id = ANY($2)` — Bitmap OR двух индексов, 6–7 мс: часть по `uq_attachments_object_key` — 5,6–6,2 мс (сравнение текста), часть по `pk_attachments` — 0,3–0,4 мс; один `object_key = ANY` — 6 мс. Обход `ready` keyset по `id` (`status`, `lost_at`, `updated_at` — фильтр) — Index Scan `pk_attachments`, 1000 строк за 0,4–0,6 мс | + +### Запись `KNOWN_ISSUES.md` о bootstrap после удаления bucket + +Воспроизведена на пробе и объяснена: дело в слотах томов, а не в +повторном имени bucket. + +| Стенд | Слотов томов | После `s3.bucket.delete` и повторного bootstrap | +|---|---|---| +| tmpfs 4 ГБ | 3 из 3 заняты | «bucket created», затем «FAILED: api key wait (code 500)» дважды подряд. В журнале S3 — «No writable volumes and no free volumes left for collection:messenger» | +| tmpfs 16 ГБ | 15 | «bucket created», проверки прошли за 2 с | + +Почему так: +- сервер запущен с `-volume.max=0`, и число слотов считается по + свободному месту / 1 ГиБ; +- удаление bucket удаляет томá его коллекции, но на маленьком диске + слоты занимают тома коллекции по умолчанию (журналы filer); +- новых томов для `messenger` выделить некуда. + +У рабочего стенда volume на диске ВМ: 417 слотов, 403 свободны (`weed +shell volume.list`, только чтение). Там удаление bucket и повтор +bootstrap этим не падают. Решение 14. + +### Рабочий стенд перед change + +Только чтение: 2 019 строк `ready`, 2 019 файлов `original` (`fs.tree`), +строк `ready` без объекта и объектов без строки — 0, `pending` — 0. + +## Goals / Non-Goals + +**Goals:** + +- Пункт трека 2 о reconciler (`PLAN.md`, этап 5): обе стороны, + dry-run, `--apply`, повтор = 0, стресс с проверкой SHA-256. +- Ни при каком порядке действий сверка не удаляет подтверждённое, + используемое и свежее (гипотеза 5). +- Остаточные риски `upload-consistency` закрыты автоматически. PUT-зомби + убирает плановая сверка. Строку `ready` без объекта она помечает, и + API отвечает по контракту, а не 500. +- Смешанные версии при `make rolling_update` не хуже, чем до change. + +**Non-Goals:** + +- Стоимость обхода, стратегии и ограничение скорости — + `track2-reconcile-cost` (решение 13). +- Восстановление байтов потерянного оригинала: их нет нигде. +- Сверка других префиксов bucket (`test_/`, `.s3-check/`) и чужих + баз. +- Новые статусы вложения. Контракт лабы 4 знает только `ready`. +- Исправление записи `KNOWN_ISSUES.md` о bootstrap: reconciler bucket не + создаёт (решение 14). + +## Decisions + +### 1. Сверка — часть уборщика + +Пакет `src/cleaner/` и сервис compose `cleaner` вырастают в reconciler, +как и задумано (`PLAN.md`, решение 7; design `upload-consistency`, +решение 12): +- `python -m src.cleaner` (сервис) — прежний цикл уборки, плюс плановая + сверка (решение 9); +- `python -m src.cleaner --once` — один проход уборки, как раньше; +- `python -m src.cleaner reconcile [--apply] [--max-changes N]` — разовая + сверка, по умолчанию dry-run. В compose — `docker compose run --rm + --no-deps cleaner reconcile …` (точка входа уже `python -m + src.cleaner`). Цель Makefile — `make reconcile [APPLY=1] + [MAX_CHANGES=N]`; +- сервис `AttachmentReconcileService(db_scope, storage)` + (`src/core/services/attachment_reconcile.py`), метод `reconcile(*, + older_than, apply, max_changes, page_size, batch_size, + stop_requested)`. Зависшие загрузки он отдаёт + `AttachmentCleanupService` (решение 7). + +Как уборщик и сверка не мешают друг другу на строках `pending`: +- внутри процесса проходы идут по очереди, одновременно не бывают; +- между процессами (сервис и разовый `run`) сверка трогает строку + `pending` только процедурой уборщика — тот же `FOR UPDATE SKIP LOCKED` + и пометка; +- объект строки `pending` правило «объект без метаданных» не видит: + строка на него ссылается; +- пометку потерянного оригинала получает только строка `ready`, а её + уборщик не выбирает никогда; +- все действия безопасно повторять, поэтому и две сверки разом ничего + не ломают: удаление объекта и условный `UPDATE` идемпотентны. + +*Альтернатива:* отдельная точка входа `python -m src.reconciler`, свой +сервис и пользователь S3 `reconciler`. Отвергнута: +- два процесса с доступом к одной базе, ещё два секрета, пользователь в + bootstrap и строки `make s3_check` — ради разделения, которое почти + ничего не даёт. У уборщика и так есть ключи всех объектов в БД, чтение + и удаление любого объекта bucket. Список по префиксу своей базы + (решение 2) добавляет к этому мало; +- плановой сверке всё равно нужен долгоживущий процесс, а он уже есть. + +*Альтернатива:* только ручная сверка, без плановой. Отвергнута: PUT-зомби +жил бы до ручного запуска, и остаточный риск `upload-consistency` остался +бы «навсегда» (решение 9). *Альтернатива:* фоновая задача реплик API. +Запрещена (AGENTS.md). *Альтернатива:* lifecycle-правила S3. Отвергнуты: +S3 не знает строк БД. + +### 2. Права S3: список по префиксу вложений своей базы + +Политика `cleaner-objects` получает второй оператор (проба — +Context): + +```json +{"Effect": "Allow", "Action": ["s3:ListBucket"], + "Resource": ["arn:aws:s3:::"], + "Condition": {"StringLike": {"s3:prefix": ["<база>/attachments/*"]}}} +``` + +Чтение и удаление на `/*` — как были. + +- Префикс bootstrap получает в `S3_CLEANER_LIST_PREFIX: + ${POSTGRES_DB:?…}/attachments/` (окружение `s3-bootstrap` в + `docker-compose.yml`). Это не секрет. Скрипт проверяет его по + `^[a-z0-9_]+/attachments/$` и подставляет в JSON только проверенное + значение. На стенде отказов и в `bench/` (`POSTGRES_DB=bench`) префикс + берётся тем же путём. Уборщику его не передают: свой префикс он строит + из `settings.database.name`, как ключи объектов. +- Проверки `apply`: + - ключ уборщика получает 200 на список с префиксом; + - 403 на список всего bucket — так же, как сейчас «cleaner key list is + not denied». +- Режим `check` (`make s3_check`), строки ключа уборщика: + - «cleaner key list attachments prefix» — 200; + - «cleaner key list objects» без префикса — 403, как было; + - «cleaner key list other prefix» (`.s3-check/`) — 403; + - «cleaner key list other bucket» — 403, как было. +- Порядок обновления. Bootstrap только расширяет права и у API ничего не + забирает (`balancer.md`). Новый уборщик со старой политикой получает + `AccessDenied` на списке: проход сверки прерван, `error` «Object + storage denied access», уборка работает. Поэтому вперёд — сначала + `docker compose up -d s3-bootstrap` (решение 6). + +*Альтернатива:* `s3:ListBucket` без условия. Отвергнута: уборщик видел бы +ключи других баз (`test_/`) и проверочные объекты, а сверке они не +нужны. *Альтернатива:* `s3:ListBucket` на ресурсе `/*`. По пробе +списка не даёт. *Альтернатива:* сузить по префиксу и чтение с удалением. +Отложена: проверки bootstrap удаляют ключом уборщика свои объекты под +`.s3-bootstrap/` и `.s3-check/`, их пришлось бы переделать. Ключи +объектов уборщик и так берёт из БД своей базы. + +### 3. Классы и проход сверки + +Классы — спек `storage-consistency`, «Сверка bucket и БД». Порог +`older_than = utcnow() − [cleaner] pending_grace_seconds` один на +проход, по часам приложения, как у уборщика. Проход: + +1. **S3 → БД.** Страницы ListObjectsV2 по префиксу `<база>/attachments/` + (`[reconciler] page_size`, до 1000). + - Ключ вида `<база>/attachments//original` + (`attachment_object_repo.parse_original_key`) даёт `id`. Остальные + ключи — «нестандартные». + - На страницу — одно выражение к БД: `id = ANY(:ids) OR object_key = + ANY(:keys)`. Здесь `ids` — из стандартных ключей, `keys` — только + нестандартные, обычно их нет. По пробе выборка по `id` в 15 раз + дешевле выборки по тексту ключа. + - Классификация без новых вызовов S3: + - строка `id` с тем же ключом. `pending` — пропуск, это дело + уборщика. `ready` без пометки: размер равен — порядок; другой — + кандидат «другой размер», если строка старше порога, иначе + «свежая». `ready` с пометкой: размер равен — кандидат «оригинал + вернулся», иначе «уже помечено»; + - строка `id` с другим ключом — «чужой объект»; + - строки нет: `LastModified` раньше порога — кандидат «объект без + метаданных», иначе «свежий объект»; + - нестандартный ключ — строка с таким `object_key` есть: как у + строки выше, иначе «чужой объект». + - Каждый ключ попадает в множество `seen`. +2. **БД → S3.** Keyset по `id` по всем строкам `ready` (`[reconciler] + page_size` строк, Index Scan `pk_attachments` — проба). + - Строка без пометки старше порога, ключа которой нет в `seen`, — + кандидат «метаданные без объекта». + - Моложе порога — «свежая». + - С пометкой — «уже помечено», если оригинал не вернулся на шаге 1. +3. **Зависшие загрузки** — решение 7. +4. **Перепроверка** каждого кандидата непосредственно перед решением, в + обоих режимах (решение 4). +5. **Предел изменений**, затем действия, если `--apply` (решения 4 и + 8). + +Действия начинаются, только когда классификация закончена. Отказ +хранилища на шагах 1–4 прерывает проход без единого изменения. + +Почему множество, а не слияние двух отсортированных потоков. Порядок +списка SeaweedFS — обход каталогов, а не порядок байтов (проба). Слияние +с `ORDER BY object_key COLLATE "C"` на нестандартных ключах разошлось бы +и дало бы ложные расхождения в обе стороны. Цена множества — память +O(N): ~150 байт на ключ, при 100 тыс. объектов ~15 МБ при лимите +уборщика 256 МБ. Замер — `track2-reconcile-cost`. + +Почему гонка двух снимков (списка и строк) не даёт ложных расхождений: +- **объект без метаданных.** API пишет строку до PUT (порядок записи + `attachments`). Если объект попал в список, строка его загрузки уже + зафиксирована и видна выборке, которая идёт после списка. Её нет, + только если её убрал уборщик, — тогда объект и правда лишний; +- **метаданные без объекта.** Строки моложе порога не проверяются. + Строка старше порога стала `ready` раньше начала прохода, а её объект + записан ещё раньше. Объекты `ready` никто, кроме сбоя, не удаляет, + поэтому список их видит. Перепроверка HEAD отсекает и неполный ответ + списка. + +*Альтернатива:* HEAD на каждую строку вместо множества — стратегия +следующего change (гипотеза 2). *Альтернатива:* временная таблица ключей +в PostgreSQL и anti-join. Отвергнута: одна долгая транзакция противоречит +`idle_in_transaction_session_timeout` и сроку шага 6 с. + +### 4. Правила безопасности + +Свойства — спек «Безопасность сверки». Как они держатся: + +- **Что можно удалить.** Удаление объекта — только у класса «объект без + метаданных». Удаление строки — только у зависшей загрузки процедурой + уборщика. Строки `ready`, используемые вложения (FK + `message_attachments` и так не даст удалить строку) и объекты, на + которые ссылается строка, не попадают ни в один удаляющий класс. +- **Свежее.** + - Объект: по `LastModified` S3 (часы ВМ, точность — секунда). + - Строка `ready`: по `updated_at` — время перевода в `ready`. + - Строка `pending`: по `created_at`, как у уборщика. + + Grace общий с уборщиком, его проверка границы живой загрузки (17 с) + остаётся. +- **Перепроверка непосредственно перед решением:** + - объект без метаданных: выборка строки по `id` или по ключу + (`find_attachment_reference`) — нет; HEAD — объект есть и старше + порога. Перед самим DELETE выборка строки — ещё раз. Выборка страницы + ищет стандартные ключи только по `id` (решение 3), поэтому строку с + чужим `id`, которая ссылается на этот ключ (изменённые метаданные), + находит именно перепроверка. Такой объект — «чужой объект», и он не + удаляется; + - метаданные без объекта и другой размер: `get_attachment` — `ready`, + без пометки, тот же ключ; HEAD — объекта нет или размер другой; + - оригинал вернулся: пометка на месте, HEAD — размер равен; + - не подтвердилось — кандидат выбывает без записи о расхождении. +- **Bucket на месте.** Перед подтверждением отсутствия объектов — + список с префиксом и `MaxKeys=1`. HEAD bucket при условной политике — + 403, проба. Удалённый bucket даёт `NoSuchBucket`, и проход прерван. + Пустой, пересозданный bucket проходит проверку, но тогда кандидатов + больше предела, и действует он. +- **Предел изменений.** Число подтверждённых удалений объектов, пометок + и снятий пометок сравнивается с `max_changes` (100 или аргумент). + Больше — ни одного из этих изменений: `error`, код 3. Уборка зависших + загрузок пределом не ограничена: уборщик делает её и без сверки. Предел + защищает от сверки с «чужой» базой — пустой или восстановленной из + старой копии, при живом bucket — и от пустого bucket. +- **Чужой объект** — только отчёт и код 3. Удалять то, чего API не + пишет, опасно: в лабе 5 под префиксом появятся варианты, а оператор + мог положить копию сам. +- **Объект без метаданных удаляется в любой момент после порога.** + Объект зомби-загрузки удаляет и её компенсация. Два DELETE одного + ключа безопасны. + +*Альтернатива:* пометить строку перед действием, как уборщик. Не нужна: +сверка не удаляет строк, а пометка потери — один условный `UPDATE`. +*Альтернатива:* относительный предел (доля объектов). Отвергнут: на +маленьком стенде он слишком мал, на большом слишком велик. Абсолютный +предел понятнее оператору, и его легко поднять аргументом. + +### 5. Потерянный оригинал и ответы API + +- **Пометка** — новая колонка `attachments.lost_at timestamptz NULL`: + время, когда сверка подтвердила потерю. `status` и `updated_at` не + меняются. Поэтому ответ метаданных прежний, `error_code` — `null`, как + требует контракт для `ready`. + - `mark_lost`: `UPDATE … SET lost_at = :now WHERE id = :id AND status + = 'ready' AND lost_at IS NULL AND object_key = :key RETURNING id`; + - `clear_lost`: `… SET lost_at = NULL WHERE id = :id AND lost_at IS NOT + NULL AND object_key = :key`. +- **API** (спек `attachments`, «Скачивание оригинала»): + - скачивание помеченного — 404 `not_found` без обращения к S3, запись + `info` «Attachment content is lost»; + - непомеченного без объекта — 500, как было; + - метаданные — 200, как было; + - ссылка в новом сообщении — 201, как на любое `ready`. + + `get_attachment` и DTO получают `lost_at`. `get_attachments` и + `MessageService` не меняются. + +Почему так. В контракте лабы 4 у `Attachment.status` одно значение — +`ready` (`contracts/openapi.json`), поэтому метаданные не могут сказать +«потеряно». Для байтов контракт даёт «Отсутствующий вариант +ready-объекта — 404» (`contracts/README.md`). 500 — «неожиданное +исключение», а после сверки потеря уже ожидаема. Но прочтения возможны +разные, поэтому это вопрос преподавателю (Open Questions; `PLAN.md`, +`### track2-reconciler`). Ответ «иначе» меняет только `open_content` и +выборку вложений сообщения, спек `attachments` и тесты. Классы, правила +и проход сверки от него не зависят. + +*Альтернатива:* статус `lost` или `failed` в CHECK. Отвергнута: +- контракт лабы 4 его не знает; +- замена CHECK и прежние реплики упали бы на неизвестном значении enum + при `make rolling_update`. + +*Альтернатива:* удалить метаданные потерянного вложения, если оно не +используется. Отвергнута: «строку без объекта не восстановить, reconciler +её находит и помечает» (`PLAN.md`, «Трек 5»). Подтверждённое вложение не +удаляется (гипотеза 5), а клиент с его `id` получил бы 404 на метаданные +без объяснения. *Альтернатива:* отдельная таблица находок. Отвергнута: +лишнее соединение в чтении вложения. Отчёт и так в журнале. + +### 6. Схема и смешанные версии + +Ревизия поверх `739b8f04d5fb`: +- первой строкой `op.execute("SET LOCAL lock_timeout = '2s'")` + (`migrations.md`: `ACCESS EXCLUSIVE` на рабочую таблицу); +- затем `add_column('attachments', Column('lost_at', DateTime(timezone= + True), nullable=True))` — только каталог, 0,36 мс на пробе; +- `downgrade` — `drop_column` с тем же `lock_timeout`. + +Модель — `lost_at: Mapped[datetime | None]`. Индекса нет: сверка +просматривает все строки `ready`, API читает по `id`. CHECK «помечено +только `ready`» не добавляется. Для существующей таблицы это `NOT VALID` +или скан под блокировкой, а пометку и так ставит только условный +`UPDATE`. + +| Смесь | Что происходит | По сравнению с «до change» | +|---|---|---| +| новая схема + прежние реплики (`5f4b9ff`) | колонку не читают, у помеченного без объекта — 500 | так же | +| новый уборщик + прежние реплики | пометки ставятся, прежние реплики их не видят (500); объекты без строки удаляются безопасно — порядок записи прежних версий тот же, строка до PUT, с change `attachments` | не хуже | +| прежний уборщик + новые реплики | сверки нет, пометок нет | так же | +| новый уборщик + прежняя политика S3 | проход сверки прерван `AccessDenied` (`error`), уборка работает | не хуже | +| новый уборщик на прежней схеме | уборка работает; сверка падает на `lost_at`, `error` «Reconcile pass failed», процесс живёт | не хуже; порядок ниже не даёт такой смеси | + +Порядок обновления: +1. вперёд — `docker compose up -d s3-bootstrap` (политика со списком); +2. затем `make rolling_update` (миграция, затем реплики); +3. затем `docker compose up -d --no-deps cleaner`. + +Откат — сначала уборщик (`docker compose stop cleaner` или прежний +образ), потом `make rolling_update COMMIT=<прежний> MIGRATE=0`. +Колонка и пометки остаются, прежнему коду они не мешают, а после +возврата вперёд снова действуют. + +### 7. Зависшие загрузки в сверке + +- Dry-run: кандидаты — `attachment_repo.get_stale_pending` страницами + `[cleaner] batch_size`. Каждый — запись с `id`, ключом и возрастом. + Ничего не меняется. +- `--apply`: `AttachmentCleanupService.clean_stale_pending(older_than=…, + batch_size=…, stop_requested=…)` — тот же код, что у сервиса уборки: + пометка, затем объект и строка одной транзакцией под блокировкой. + Число убранных — в итог сверки. +- Порядок действий `--apply`: зависшие загрузки → объекты без метаданных + → пометки → снятия пометок. Остановка (`stop_requested`) проверяется + между действиями. + +*Альтернатива:* сверка зависшие загрузки только называет. Отвергнута: +без работающего уборщика `--apply` не довёл бы стенд до «повтор = 0», а +общий код ничего не стоит. + +### 8. Отчёт, журнал и коды выхода + +- **DTO** (`dto.md`): + - `ReconcileFindingDTO`: `kind`, `object_key`, `attachment_id`, + `age_seconds`, `size_bytes`, `stored_size`; + - `ReconcilePassDTO`: `apply`, `listed_objects`, `checked_rows`, + `found` и `fixed` по классам, `fresh_objects`, `fresh_rows`, + `lost_known`, `refused`, `interrupted_by`, `duration_ms`. + + `ReconcileFinding` — `StrEnum` в `enums/attachment.py`: + `orphan_object`, `missing_object`, `size_mismatch`, `stale_pending`, + `restored_object`, `unknown_object`. Строки репозитория — + `AttachmentFullDTO`, у него новое поле `lost_at` со значением по + умолчанию. Отдельный тип не нужен. +- **Журнал** (дельта `service-logging`, модуль + `attachment_reconcile_service`): + - находка — `warning` «Found storage discrepancy»; + - исправленная — `info` «Fixed storage discrepancy» с `action` + (`deleted_object`, `marked_lost`, `cleared_lost`, `removed_pending`); + - итог — «Finished reconcile pass» (`info` или `warning`); + - предел — `error` «Reconcile changes exceed limit»; + - отдельные записи — первые `RECONCILE_FINDINGS_LOGGED_MAX` (1000, + `constants.py`), в итоге — сколько осталось без записи. +- **Отчёт разового прохода** — те же JSON-записи в stdout. Отдельного + формата нет: hook и драйвер разбирают записи `Found` / `Fixed` / + `Finished`. +- **Коды** разового прохода (спек): 0 / 3 / 1 / 2. Код 3 — и при чужом + объекте: он требует внимания оператора, хотя сверка его не тронет. + Прерванный сигналом разовый проход — 1, сервис — 0 (дельта + `graceful-shutdown`). + +### 9. Плановая сверка + +- В цикле сервиса после прохода уборки проверяется срок плановой сверки + (`loop.time()` против следующего срока): + - первая сверка — при старте; + - следующая — через `[reconciler] interval_seconds` (3600 с) после + конца предыдущей; + - 0 — без плановой сверки. + + Это тот же `reconcile(apply=True, max_changes=[reconciler] + max_changes)`. Непредвиденная ошибка — `error` с traceback, процесс + живёт, как у уборки. +- Граница. Объект без метаданных живёт не дольше grace + интервал + + проход: ~15 + 60 мин + секунды. Цена на рабочем стенде (2 тыс. + объектов) — меньше секунды в час. При 100 тыс. — порядка минуты под + лимитом 0,25 CPU: разбор XML списка botocore — Python. Замер и выбор + интервала — `track2-reconcile-cost`. +- Стенд отказов — `RECONCILER__INTERVAL_SECONDS: "0"` в + `failures.compose.yml`. Иначе плановая сверка исправляла бы + расхождения, которые тест внёс и ещё проверяет. Плановую сверку + проверяет отдельный уборщик с интервалом 1 с (решение 11). `bench/` + уборщика не запускает. У описанного в `bench.compose.yml` уборщика — + тоже 0: профиль сверки `track2-reconcile-cost` задаст интервал сам. + +*Альтернатива:* плановая сверка только с dry-run. Отвергнута: зомби +оставались бы до ручного `--apply`. Предел и перепроверки делают +автоматическое исправление безопасным. *Альтернатива:* первая сверка +через интервал после старта. Отвергнута: частые пересоздания уборщика +(`make run_docker`, обновление) откладывали бы её бесконечно. + +### 10. Настройки + +Секция `[reconciler]` (класс `Reconciler`, дельта +`service-configuration`): +- `interval_seconds` — float, ≥ 0, 3600; +- `page_size` — int, 1–1000, 1000; +- `max_changes` — int, ≥ 1, 100. + +Разовая подмена — `RECONCILER__*`. Grace — `[cleaner] +pending_grace_seconds`, одна ручка «свежести» на всю согласованность. Его +проверка при старте уже есть и действует и на `reconcile`. Запись +«Started cleaner» называет три новых значения и режим — сервис, `--once` +или `reconcile` с `apply`. Строки — в `config_example.toml`. + +*Альтернатива:* свой `grace_seconds` у сверки. Отвергнута: две ручки +«свежести» разошлись бы. Для объектов без строки граница B не нужна, но +меньший grace ничего не даёт, кроме риска. + +### 11. Внедрение ошибок и тесты отказов + +**Новые действия hook** (`fault_hook.py`, только stdlib, ключи S3 hook не +получает): + +| Действие | Что делает | +|---|---| +| `put-object <ключ>` | тело из stdin. `docker exec -i <проект>-api python -c …` — botocore образа с ключами API из окружения контейнера пишет объект мимо приложения. Ключ — только под `/attachments/`, символы `[A-Za-z0-9._/-]` | +| `delete-object <ключ>` | `weed shell fs.rm /buckets//<ключ>` — мимо шлюза S3, с той же проверкой ключа | +| `delete-row `, `set-size <байт>`, `age-row <секунд>` | psql: удалить строку (неиспользуемого вложения), изменить `size_bytes`, сдвинуть `created_at` и `updated_at` назад вместе. CHECK и непомеченность `pending` сохраняются | +| `lost-ids` | `id` строк с `lost_at` | +| `fail-attachments mark ` | новый режим: `UPDATE`, который ставит `lost_at` строке с этим `filename`, падает с 08006. Отдельный триггер `BEFORE UPDATE OF lost_at`, чтобы прежние режимы и их функция не зависели от новой колонки; `clear-fail-attachments` снимает и его | +| `reconcile dry-run\|apply [<предел>]` | `docker compose -p … run --rm --no-deps -T cleaner reconcile [--apply] [--max-changes N]`: печатает записи процесса и строку `exit_code=`, код hook — 0 | +| `stop\|start cleaner` | сервис уборщика стенда (`start` — `up -d --wait --no-recreate`) | +| `run-cleaner <секунд>` | отдельный уборщик `<проект>-cleaner-scheduled` (`run -d`, `RECONCILER__INTERVAL_SECONDS=1`) на N секунд, затем `docker stop` и его журнал; `run_failures.py` убирает его вместе с остальными | + +Объекты нельзя состарить: `LastModified` ставит S3. Поэтому тест с +объектом без метаданных ждёт G + 1 с. Строки состаривает `age-row`, и +там ждать не нужно. + +**Тесты** (маркер `fault`; G = 20 с — grace стенда): + +| Тест | Сценарии | Ход | +|---|---|---| +| `test_reconcile_finds_and_fixes` | `storage-consistency` «Расхождения с обеих сторон найдены», «Исправление расхождений», «Повторная сверка»; `attachments` «Потерянный оригинал» | `with outage(stop cleaner)` → вложения A (в сообщении), B, C → `put-object` O (стандартный ключ), `delete-object` A, `delete-row` B, `set-size` C, загрузка P с `fail-attachments commit` (строка `pending` и объект) → ждать G + 1 → dry-run: у своих ключей и `id` — свои классы, `exit_code` 3, списки строк, объектов и `lost-ids` прежние, A — 500 → apply: O и объект B убраны, у P нет ни строки, ни объекта, A и C в `lost-ids`, A — 404, метаданные A равны ответу загрузки → повтор dry-run: своих расхождений нет, код соответствует записям | +| `test_reconcile_keeps_fresh_used_and_unknown` | «Свежие не тронуты», «Используемое вложение не удаляется», «Чужой объект не удаляется» | U1 в сообщении — `age-row` и `delete-object`; чужой X (`…/attachments/x-`) → ждать G + 1 → свежие: U2 с удалённым объектом и F (`put-object`) → apply: F и X на месте, U2 не помечено, U1 помечено, метаданные U1 — 200, история отдаёт U1, строк не убыло, X — «чужой», код 3 → уборка X и F через hook | +| `test_reconcile_restored_original` | «Оригинал вернулся» | R: `age-row`, `delete-object`, apply → помечено → `put-object` R теми же байтами → apply → пометки нет, байты — 200 с тем же SHA-256 | +| `test_reconcile_change_limit` | «Предел изменений» | L1–L3: `age-row`, `delete-object` → apply с пределом 2: код 3, `error` называет число не меньше 3 и предел 2, `lost-ids` без L → apply с пределом 100 → помечены все три | +| `test_reconcile_object_storage_stopped` | «S3 недоступен во время сверки» | M: `age-row`, `delete-object` → `with outage(stop s3)`: apply — код 1, M не помечено → после возврата apply помечает | +| `test_reconcile_interrupted_by_database` | «Прерванная сверка доводится повтором» | N1 (filename f), N2: `age-row`, `delete-object` → `fail-attachments mark f` → apply — код 1 → снять триггер → apply → оба помечены → dry-run без них | +| `test_reconcile_under_load` | «Сверка под нагрузкой» | внесены 2 объекта без строки и 2 потери (`age-row`); 4 потока ~G + 15 с загружают ~100 KiB PNG из шума и отправляют сообщения со свежими `id`; поток сверки — apply раз в 3 с. В конце: внесённые исправлены, каждое 201-вложение скачивается с тем же SHA-256, каждое сообщение отдаёт свои `attachment_ids`, новые `lost-ids` (разность до и после) — только внесённые | +| `test_scheduled_reconcile` | «Плановая сверка без команды» | S: `age-row`, `delete-object` → `run-cleaner 6` → в журнале «Finished reconcile pass», S в `lost-ids` | + +Тесты фильтруют записи сверки по своим `id` и ключам. Остатки прежних +тестов (их строки `pending`) могут попасть в отчёт и в код выхода, +поэтому код сверяется с записями того же прохода, а не с числом. +Уборщик стенда остановлен только в первом тесте и только на его окно +(`with outage`). Новые тесты добавляют к `make failure_checks` около +2,5–3 мин. + +**Красный прогон до кода.** Новые тесты против прежнего кода — `5f4b9ff`, +команды `reconcile` нет. Падают все восемь: hook возвращает код 2 +команды и ошибку разбора аргументов. Это доказательство, что тесты +проверяют новое поведение. Сверка покрытия: новые сценарии +`storage-consistency` и `attachments` синхронизируются в основные спеки в +apply, как в прежних changes (`spec_coverage.py` читает только +`openspec/specs/`). + +### 12. Драйвер и evidence + +Драйвер скилла (stdlib, Python 3.9), только стенд с LB. Разовая сверка — +`docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS= +cleaner reconcile …`, как у `upload-consistency`. + +- **`reconcile-cycle`** → `evidence/reconcile/cycle.md`: + 1. исходный dry-run с grace по умолчанию: 0 расхождений, иначе код 2, + «стенд не сведён — `make reconcile`»; + 2. синтетические участники и вложения через LB; + 3. расхождения: + - объект без строки — `docker compose exec -T api python -c …` с + ключами реплики; + - удалённые объекты — `weed shell fs.rm`; + - удалённая строка, изменённый размер — psql; + - обрыв между объектом и фиксацией — временный триггер `commit` на + уникальный `filename` рабочей базы, снимается в `finally` и в + начале следующего прогона; + - чужой объект; + 4. ожидание grace прогона (30 с), затем dry-run: таблица «класс → ключ + → `id` → возраст», снимки строк и объектов до и после совпали; + 5. байты потерянного — 500; + 6. `--apply`: таблица исправлений; байты — 404, метаданные — 200; + история отдаёт `id`; + 7. повтор: исправимых 0, остался чужой. Его удаление оператором — шаг + драйвера, затем повтор — код 0. Свежий объект не тронут, а после + grace удалён; + 8. возврат оригинала: «оригинал вернулся», байты — 200 с тем же + SHA-256. + + Код 1 при любом расхождении. Токенов и секретов в выводе нет. +- **`reconcile-stress`** → `evidence/reconcile/stress.md`: + 1. предусловие — dry-run с grace 20 с без расхождений (иначе код 2); + 2. внесённые расхождения; + 3. N клиентов M секунд загружают и отправляют через LB, поток сверки — + `--apply` с grace 20 с раз в ~3 с; + 4. в конце — таблица: загрузки по кодам, сообщения, проходы и + исправления по классам, скачивания с несовпавшим SHA-256 — 0, + сообщения с недоступным вложением — 0, повтор — 0. + + Это проверка корректности: тихий хост не нужен, паспорт хоста не + снимается. +- **Остальное evidence:** + - `evidence/reconcile/service.md` — запись о старте с параметрами + сверки, плановая сверка при старте, `docker compose stop cleaner` во + время сверки при `pause s3` (время и код), отказ старта с + `RECONCILER__PAGE_SIZE=5000`; + - `evidence/s3/cleaner-list.md` — bootstrap с новой политикой, `make + s3_check` со строками списка, окружение `s3-bootstrap` в `docker + compose config`; + - `evidence/migrations/lost-at.md` — ревизия с нуля, повтор, откат, + снова `upgrade`, `--sql` с `lock_timeout`; + - `evidence/tests/` — `make failure_checks`, `make student_test` через + LB, `make test_isolated`. + + Регресс: `make bench_rollout_quick` (замена `e1161f7` → новая + ревизия), `bench_failover_quick`, `bench_restore_quick`, `bench_quick`. +- **`REPORT.md`:** + - раздел «Сверка хранилищ (трек 2)» — классы, правила, предел, права + S3, ответы API, вопрос преподавателю; + - строки таблицы доказательств уровня «5»; + - ограничения (Risks ниже); + - ответ на вопрос защиты «PUT прошёл, COMMIT нет» дополняется: зомби + убирает сверка. + +### 13. Граница с `track2-reconcile-cost` + +| Здесь | В `track2-reconcile-cost` | +|---|---| +| одна стратегия: страницы LIST + одно выражение к БД на страницу, множество ключей, HEAD — только перепроверка найденного | `--strategy head` — HEAD на строку и выборка на объект (гипотеза 2) | +| поверхностная сверка: наличие и размер из LIST | `--deep [--sample N]` — SHA-256 чтением объекта, класс «другой SHA-256» (гипотеза 3) | +| `[reconciler] page_size`, `interval_seconds`, `max_changes` | ограничение скорости обхода и его влияние на p95 фоновой нагрузки (гипотеза 4); выбор интервала по замеру | +| в итоге прохода — `listed_objects`, `checked_rows`, `duration_ms` | профиль `reconcile` стенда `bench/`: N = 10k / 100k мимо API, доли расхождений, k6, сэмплер, 3 повтора, A/A, графики (гипотеза 1) | +| стресс `--apply` под загрузками — корректность (гипотеза 5) | выводы по гипотезам 1–5 и ограничения в `REPORT.md` | + +### 14. Запись `KNOWN_ISSUES.md` о bootstrap + +Причина найдена (Context): слоты томов на маленьком диске, а не +повторное имя bucket. Reconciler bucket не создаёт и не удаляет. На +`NoSuchBucket` он прерывает проход без изменений, поэтому чинить запись +этому change не нужно. + +В apply запись переписывается: +- причина; +- условие — диск, на котором `-volume.max=0` даёт мало слотов: tmpfs + проб, а не volume стендов проекта; +- проба на 16 ГБ; +- предложение на будущее — `-master.volumeSizeLimitMB` меньше 1024 или + явный `-volume.max` на маленьких дисках. + +Запись остаётся открытой. + +## Risks / Trade-offs + +- **[Источник истины — PostgreSQL: база из старой копии или пустая при + живом bucket]** → объекты новых вложений станут «объектами без + метаданных», и до предела изменений сверка их удалит. По истине БД это + верно. Опасно восстановление базы в живую (`pg_restore` поверх) при + работающем уборщике: удалились бы объекты строк, которые ещё не + восстановлены. Митигация: + - предел 100; + - grace по объекту на старые объекты не действует. Поэтому правило в + `REPORT.md` и `docker.md`: на время восстановления базы уборщик + останавливают (`docker compose stop cleaner`), после — сначала `make + reconcile` (dry-run). +- **[Чужой объект живёт, пока его не удалит оператор]** → код 3 и + `warning` на каждом проходе плановой сверки — видно в журнале. Удалять + непонятное опаснее. +- **[Повреждение того же размера не видно]** → поверхностная сверка + сравнивает только размер. SHA-256 — глубокая сверка следующего change. + Скачивание отдаёт такие байты и сейчас: API сверяет только размер. +- **[Память O(N) на ключи списка]** → ~15 МБ на 100 тыс. объектов при + лимите уборщика 256 МБ. Замер — следующий change. +- **[Плановая сверка задерживает уборку зависших загрузок на время + прохода]** → на рабочем стенде — меньше секунды. На 100 тыс. — порядка + минуты при grace 15 мин. Ограничение — в спеке и `REPORT.md`. +- **[Пометка по ложному «нет объекта»]** при неполном списке S3 → HEAD + перепроверяет каждый кандидат и проверяет bucket. Остаток — bucket + пересоздан пустым или подменён между перепроверкой и `UPDATE`. Тогда + пометка верна: объекта правда нет. Она снимается сама, если объект + вернётся. +- **[Две сверки одновременно]** — плановая и разовая → действия + идемпотентны, отчёты могут разойтись в числах `fixed`. Блокировки + нет: проходу пришлось бы держать соединение пула уборщика всё время. +- **[Часы]** → `LastModified` — часы ВМ (S3), порог — часы контейнера + уборщика, это одни часы. Точность `LastModified` — секунда, при grace + 900 с это ничтожно. `updated_at` строк пишут реплики. Консольный API на + macOS расходится на секунды — меньше grace. +- **[Ответ API для потерянного оригинала — трактовка контракта]** → + вопрос преподавателю. Ответ меняет одну ветку `open_content`, сценарий + и тест. +- **[Старый образ уборщика после `make rolling_update`]** → сверки нет, + как до change. Порядок обновления — решение 6, строка в `balancer.md`. +- **[Тесты отказов дольше на ~3 мин]** → объекты нельзя состарить, ждать + grace (20 с) нужно только тестам объектов без метаданных. Остальные + состаривают строки. + +## Migration Plan + +1. Hook, стенд отказов и тесты раньше кода; красный прогон на нынешнем + коде (`5f4b9ff`). +2. Настройки `[reconciler]`, enum и DTO, константа предела записей. +3. Модель и ревизия `lost_at`: с нуля, повтор, откат, снова `upgrade`, + `--sql`. +4. Клиент S3 (список, время объекта), repo, `AttachmentService` (404), + сервис сверки, пакет `src/cleaner/` (команда, плановая сверка, коды). +5. Bootstrap (политика, префикс, проверки), compose (`s3-bootstrap`), + `config_example.toml`, `Makefile` (`reconcile`), `bench/`. +6. Sync дельт в основные спеки и правка Purpose `storage-consistency` + («Сверку … добавят следующие changes» → сверка есть), полный `make + failure_checks`. +7. Драйвер, правила, AGENTS.md, `KNOWN_ISSUES.md`, `PLAN.md`; регресс; + commit после подтверждения; evidence; `REPORT.md`. + +На рабочем стенде — `make run_docker`: bootstrap обновит политику, +`migrate` добавит колонку, реплики и уборщик пересоздаются. Без простоя +— порядок решения 6. Первая плановая сверка — при старте нового +уборщика. По Context расхождений на стенде нет, ожидается итог без +находок. + +Откат — по решению 6. Пометки остаются в колонке. Политика со списком +прежнему уборщику не мешает. + +## Open Questions + +- **Ответ API на потерянный оригинал — вопрос преподавателю** (`PLAN.md`, + `### track2-reconciler` → «Вопросы», п. 1). Контракт лабы 4 знает + только `status=ready`. Есть три близких правила: «Отсутствующий вариант + ready-объекта — 404», «404 — объекта нет или он чужой», «Неожиданное + исключение — 500». По умолчанию до ответа (решение 5): + - метаданные — 200; + - байты — 404 после пометки, 500 до неё; + - ссылка — 201. + + Ответ меняет ветку `open_content` (и выборку вложений сообщения, если + ссылку тоже запретить), сценарий `attachments` «Потерянный оригинал» и + тест. Классы, правила безопасности, схема и задачи сверки не меняются. diff --git a/openspec/changes/track2-reconciler/proposal.md b/openspec/changes/track2-reconciler/proposal.md new file mode 100644 index 00000000..191dcb63 --- /dev/null +++ b/openspec/changes/track2-reconciler/proposal.md @@ -0,0 +1,146 @@ +# Proposal + +## Why + +Уровень «5», трек 2 «Согласованность двух хранилищ» (`README.md`): +нужен повторяемый reconciler для объектов без метаданных и метаданных +без объектов. Ошибки вносятся с обеих сторон, reconciler их находит и +безопасно исправляет, с dry-run и повторным запуском. Свежие и +используемые вложения он не удаляет. Сейчас уборщик идёт только от строк +`pending`, и остаточные риски `upload-consistency` никто не находит +(`REPORT.md`, «Ограничения»): +- объект без строки — PUT-зомби после уборки, если компенсация не + удалась; +- строка `ready` без объекта — откат шага 2 уборщика при `mark_ready` + прежней версии во время замены реплик. + +Объект, удалённый мимо API, сейчас даёт 500 при каждом скачивании. + +## What Changes + +- **Сверка bucket и БД** — новый проход процесса уборщика. Он сравнивает + объекты под `<база>/attachments/` с метаданными той же базы. Классы + расхождений: + - объект без метаданных; + - метаданные `ready` без объекта; + - другой размер; + - зависшая загрузка; + - вернувшийся оригинал; + - чужой объект (ключ, которого API не пишет). +- **Разовый проход** — `python -m src.cleaner reconcile` (`make + reconcile`). По умолчанию это dry-run: отчёт по каждому расхождению + (класс, ключ, `id`, возраст) и итог по классам. С `--apply`: + - объект без метаданных удаляется; + - метаданные без объекта или с другим размером помечаются «оригинал + потерян»; + - зависшая загрузка убирается порядком уборщика; + - с вернувшегося оригинала пометка снимается; + - чужой объект попадает только в отчёт. + + Коды выхода: 0 — расхождений нет, 3 — остались, 1 — проход прерван, + 2 — конфигурация. Повтор после исправления находит 0. +- **Плановая сверка** в сервисе `cleaner`: при старте и раз в + `[reconciler] interval_seconds` (3600 с, 0 — выключена), с + исправлением. Так объект без строки живёт не дольше grace + интервал, + а не до ручного запуска. +- **Безопасность:** + - grace уборщика (900 с) по времени объекта в S3 и по времени + метаданных; + - перепроверка в БД и в S3 непосредственно перед каждым действием; + - объект, на который ссылается строка, и строки `ready` не удаляются + никогда; + - используемое вложение только помечается; + - отсутствие объекта не подтверждается без bucket; + - предел изменений за проход `[reconciler] max_changes` (100): больше + — ни одного изменения и код 3. +- **Потерянный оригинал.** Колонка `attachments.lost_at`, миграция + только расширяет схему. Скачивание помеченного вложения — 404 + `not_found` вместо 500. Метаданные — 200, как раньше, ссылка в + сообщении — как раньше. Неоднозначность контракта — вопрос + преподавателю (`PLAN.md`), это вариант по умолчанию. +- **Права S3 пользователя `cleaner`**: `s3:ListBucket` только с + префиксом `<база>/attachments/` (условие `s3:prefix`, проверено на + SeaweedFS 4.48). Список всего bucket, других префиксов и bucket-ов — + 403. Bootstrap и `make s3_check` проверяют это. +- **Тесты отказов** (`make failure_checks`). Hook вносит расхождения: + - объект мимо API; + - удалённый объект; + - удалённая или изменённая строка; + - обрыв загрузки между записью объекта и фиксацией. + + Ещё hook запускает разовую сверку и уборщика с плановой сверкой. + Проверки: dry-run, apply, повтор, свежие и используемые, чужой + объект, предел, отказы S3 и БД, прерванный apply, сверка под + нагрузкой. +- **Драйвер и evidence** `evidence/reconcile/`: + - `reconcile-cycle` на рабочем стенде — dry-run, apply, повтор = 0, + возврат оригинала; + - `reconcile-stress` — `--apply` под одновременными загрузками и + отправками, затем каждое подтверждённое вложение скачивается с тем + же SHA-256; + - процесс сервиса, права S3, миграция. + +Не входит — `track2-reconcile-cost`. Здесь одна стратегия: страницы +LIST по 1000 ключей и один запрос к БД на страницу, а точечные HEAD — +только для перепроверки найденного. Сверка поверхностная: наличие и +размер из LIST. Следующий change добавит: +- стратегию «HEAD на строку» (гипотеза 2); +- глубокую сверку SHA-256, выборочную или полную, и класс «другой + SHA-256» (гипотеза 3); +- ограничение скорости обхода (гипотеза 4); +- профиль `reconcile` стенда `bench/`, замеры, графики и выводы по + гипотезам 1–4. + +Гипотезу 5 («ничего подтверждённого не удалено») проверяет стресс этого +change. Ещё не входят presigned upload, превью и 202 (лаба 5), отчёт и +PR (этап 7). + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +- `storage-consistency`: новые требования — сверка bucket и БД, её + безопасность, потерянный оригинал, отказы хранилищ во время сверки, + плановая сверка; у уборщика объект без строки больше не остаётся + навсегда. +- `attachments`: скачивание потерянного оригинала — 404, до пометки — + 500. +- `object-storage`: список объектов у пользователя уборщика только по + префиксу вложений своей базы, его проверка в bootstrap и `make + s3_check`, список объектов в клиенте. +- `service-configuration`: секция `[reconciler]`. +- `service-logging`: журнал сверки и запись о потерянном оригинале. +- `graceful-shutdown`: остановка уборщика посреди сверки. +- `student-tests`: действия hook для расхождений и сверки, уборщик + стенда отказов без плановой сверки. + +## Impact + +- Код: + - новый `src/core/services/attachment_reconcile.py`; + - `src/core/repos/attachment.py` и `attachment_object.py` — выборки, + пометка, список объектов; + - `src/infra/s3/client.py` — список страницами, время объекта; + - `src/cleaner/` — команда `reconcile`, плановая сверка, коды выхода; + - `src/core/services/attachment.py` — 404 потерянного оригинала; + - `src/config/settings.py` — `[reconciler]`; + - DTO и enum, модель `Attachment` и ревизия alembic. +- Стенд: `infra/s3/bootstrap.sh`, `docker-compose.yml` (префикс списка у + `s3-bootstrap`), `config_example.toml`, `Makefile` (`reconcile`), + `student-tests/failures.compose.yml`. +- Тесты: `student-tests/test_failures.py`, `fault_hook.py`, + `run_failures.py`. +- Документы: скилл `run-mtusi-messenger` (`reconcile-cycle`, + `reconcile-stress`, строки `s3-check`). Правила `service-layer.md`, + `repo-layer.md`, `dto.md`, `infra.md`, `migrations.md`, `docker.md`, + `settings.md`, `logging.md`, `run-modes.md`, `api-contract.md`, + `student-tests.md`, `balancer.md`. Ещё AGENTS.md, `REPORT.md`, + `PLAN.md` и `KNOWN_ISSUES.md` — запись о bootstrap: причина найдена + пробой, design, Context. +- Регресс: `make failure_checks` дольше ~3 мин, `make s3_check` (новые + строки), быстрые профили `bench/` (`bench_rollout_quick` — новая + миграция), `make test_isolated`, `make test-persistence`. diff --git a/openspec/changes/track2-reconciler/specs/attachments/spec.md b/openspec/changes/track2-reconciler/specs/attachments/spec.md new file mode 100644 index 00000000..70551366 --- /dev/null +++ b/openspec/changes/track2-reconciler/specs/attachments/spec.md @@ -0,0 +1,58 @@ +## MODIFIED Requirements + +### Requirement: Скачивание оригинала + +`GET /api/v1/attachments/{attachment_id}/content` SHALL отвечать 200 с +байтами оригинала без изменений: их размер и SHA-256 равны `size_bytes` +и `sha256` вложения. Заголовки ответа: +- `Content-Type` — `content_type` вложения без параметров; +- `Content-Length` — размер оригинала; +- `X-Content-Type-Options: nosniff`. + +Байты SHALL отдавать API, ответ MUST NOT быть перенаправлением. +Параметр `variant` SHALL принимать только `original`, это и значение по +умолчанию. Любое другое значение — 400 `invalid_request`. Ключ объекта, +адрес и учётные данные S3 MUST NOT попадать ни в тело, ни в заголовки +ответов API. + +Если у готового вложения нет объекта в S3 или его размер не равен +`size_bytes`, а сверка хранилищ это ещё не подтвердила, это +непредвиденное расхождение. Скачивание SHALL отвечать 500 +`internal_error` без деталей, причина пишется в журнал. Если сверка уже +пометила оригинал потерянным (capability `storage-consistency`, +«Потерянный оригинал»), скачивание SHALL отвечать участнику 404 +`not_found`, как отсутствующий вариант готового объекта, — без +обращения к S3. Метаданные такого вложения SHALL отвечать 200 тем же +`Attachment`, что и до пометки. Ссылка на него в новом сообщении +принимается, как на любое готовое вложение. Когда сверка снимает +пометку, скачивание снова отдаёт байты. + +#### Scenario: Побайтный оригинал + +- **WHEN** Боб скачивает PNG и JPEG, загруженные Алисой +- **THEN** каждый ответ 200, не перенаправление, байты совпадают с + загруженными, `Content-Type` — `image/png` и `image/jpeg`, + `Content-Length` равен размеру, есть `X-Content-Type-Options: nosniff` + +#### Scenario: Вариант original + +- **WHEN** участник скачивает вложение с `variant=original`, а затем с + `variant=thumbnail` и с пустым `variant` +- **THEN** первый ответ 200 с теми же байтами, остальные — 400 + `invalid_request` + +#### Scenario: Без следов хранилища в ответе + +- **WHEN** участник загружает вложение, читает метаданные и скачивает + байты +- **THEN** в телах ответов нет полей вне схемы контракта, а в + заголовках нет `Location` и заголовков `x-amz-*` + +#### Scenario: Потерянный оригинал + +- **WHEN** объект готового вложения удалён мимо API, затем сверка с + `--apply` пометила его оригинал потерянным +- **THEN** скачивание до сверки — 500 `internal_error`, после неё — 404 + `not_found` +- **AND** метаданные и до, и после — 200 с тем же JSON, что у ответа на + загрузку diff --git a/openspec/changes/track2-reconciler/specs/graceful-shutdown/spec.md b/openspec/changes/track2-reconciler/specs/graceful-shutdown/spec.md new file mode 100644 index 00000000..9a9617ba --- /dev/null +++ b/openspec/changes/track2-reconciler/specs/graceful-shutdown/spec.md @@ -0,0 +1,36 @@ +## MODIFIED Requirements + +### Requirement: Остановка уборщика + +По SIGTERM уборщик незавершённых загрузок (capability +`storage-consistency`) SHALL довести текущий шаг уборки загрузки до +конца или до отката и больше новых шагов не начинать. Загрузка, +остановленная между шагами, остаётся в состоянии, из которого её +доводит следующий проход. + +Так же — во время сверки bucket и БД. Текущий вызов S3 или шаг с +PostgreSQL доводится до конца или до отката. Новые страницы списка и +новые действия не начинаются. Сверку, прерванную сигналом, доводит +следующий проход, как прерванную отказом. + +Затем сервис уборщика SHALL выйти с кодом 0 раньше срока остановки +контейнера (10 с), а не по SIGKILL. Разовый проход сверки, прерванный +сигналом, SHALL выходить с кодом 1: проход не завершён. Сигнал во время +старта процесса SHALL завершать его с кодом 0 без traceback, как у API +(требование «Остановка во время старта»). Остановка SHALL быть видна в +журнале записью об остановке уборщика. + +#### Scenario: docker stop уборщика + +- **WHEN** выполняется `docker compose stop cleaner` для работающего + уборщика +- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а + в журнале есть запись об остановке + +#### Scenario: docker stop во время сверки + +- **WHEN** `docker compose stop cleaner` выполняется, пока идёт проход + сверки, а вызов S3 в нём ждёт ответа +- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а + в журнале — итог сверки с причиной прерывания «остановка» и запись об + остановке уборщика diff --git a/openspec/changes/track2-reconciler/specs/object-storage/spec.md b/openspec/changes/track2-reconciler/specs/object-storage/spec.md new file mode 100644 index 00000000..c06a476d --- /dev/null +++ b/openspec/changes/track2-reconciler/specs/object-storage/spec.md @@ -0,0 +1,159 @@ +## MODIFIED Requirements + +### Requirement: Ограниченные учётные данные уборщика + +У уборщика (capability `storage-consistency`) SHALL быть свои учётные +данные S3, отдельные от учётных данных API и административных. +Пользователю уборщика SHALL быть разрешены только: +- чтение и удаление объектов своего bucket; +- список объектов своего bucket с префиксом вложений своей базы, + `<имя базы>/attachments/`, — для сверки bucket и БД. + +Префикс задаёт bootstrap по имени базы стенда. + +Пользователю уборщика MUST NOT быть разрешены: +- запись объектов; +- список объектов без этого префикса или с другим префиксом, в том числе + с префиксом другой базы; +- операции с bucket: создание, удаление, политика, ACL; +- публичный ACL объекта; +- управление учётными записями; +- любой доступ к другим bucket. + +Ключи уборщика MUST NOT передаваться репликам API. Уборщик MUST NOT +получать ключи API, административные ключи S3 и ключ подписи. + +#### Scenario: Работа уборщика с объектами + +- **WHEN** ключом API записан объект, а ключом уборщика он прочитан, + удалён и удалён ещё раз, и запрошен список объектов с префиксом + вложений базы +- **THEN** чтение отдаёт те же байты, оба удаления успешны, объекта + после них нет, а список отвечает 200 + +#### Scenario: Запрещённые операции уборщика + +- **WHEN** ключом уборщика запрашиваются: + - запись объекта; + - список объектов всего bucket и с префиксом, не принадлежащим + вложениям его базы; + - создание и удаление bucket, политика и ACL bucket; + - публичный ACL объекта; + - объект другого bucket и его список +- **THEN** каждый запрос получает 403, а bucket и его доступ не + меняются + +### Requirement: Проверка приватности вне API + +Приватность bucket и права ключей API и уборщика SHALL проверяться без +участия приложения двумя способами. + +1. Каждый запуск bootstrap: + - ключ API записывает и читает проверочный объект и получает отказ на + список и на создание bucket; + - ключ уборщика читает и удаляет этот объект. Он получает отказ на + запись и на список всего bucket, а список с префиксом вложений своей + базы у него проходит; + - аноним получает отказ на чтение существующего объекта и на список. + + При нарушении bootstrap завершается с ненулевым кодом, и реплики API + не стартуют. +2. Отдельная команда `make s3_check` на запущенном стенде. Она + повторяет проверки bootstrap и добавляет: + - анонимные запросы с хоста и из сети стенда; + - запросы ключей API и уборщика к чужому bucket; + - административные запросы ключей API и уборщика; + - запись ключом уборщика; + - его список всего bucket и с чужим префиксом — отказ, с префиксом + вложений своей базы — 200. + +Команда SHALL печатать по каждой проверке ожидаемый и полученный код +ответа без секретов. При любом нарушении код выхода SHALL быть +ненулевым. Свои проверочные объекты и bucket команда SHALL удалять. + +#### Scenario: Проверка командой + +- **WHEN** на запущенном стенде выполняется `make s3_check` +- **THEN** каждая проверка напечатана с полученным кодом ответа, в том + числе проверки списка ключом уборщика по своему и чужому префиксу, код + выхода 0, а проверочных объектов и bucket после команды нет + +#### Scenario: Bucket стал публичным + +- **WHEN** на bucket открыт анонимный доступ на чтение, например + административной командой мимо bootstrap +- **THEN** `make s3_check` завершается с ненулевым кодом и называет + нарушенную проверку, а следующий запуск bootstrap снова закрывает + доступ + +### Requirement: Клиент хранилища в приложении + +Процессы приложения SHALL обращаться к S3 с учётными данными своей роли +из секции `[s3]`: реплики API — ключами пользователя API, уборщик — +ключами пользователя уборщика. Клиент SHALL уметь: +- записать объект; +- прочитать его потоком; +- получить метаданные; +- удалить объект; +- перечислить объекты с заданным префиксом страницами, с размером и + временем изменения каждого объекта. + +Удаление отсутствующего объекта — не ошибка. Каждый вызов, в том числе +каждая страница списка, SHALL быть ограничен сроком из настроек. После +отказа или истечения срока вызов MUST NOT повторяться автоматически. + +Ошибкой недоступности, которую API отдаёт как 503 `unavailable` в +формате контракта, SHALL заканчиваться вызов, если S3: +- недоступен; +- не ответил за срок; +- отклонил учётные данные; +- отказал ключу в доступе или не нашёл bucket. + +Такой вызов MUST NOT давать 500 или зависать. Отсутствующий объект SHALL +отличаться от недоступности. Отсутствующий bucket MUST NOT выдаваться +за отсутствующий объект у записи, чтения, удаления и списка: список без +bucket — ошибка, а не пустая страница. После возврата S3 вызовы SHALL +проходить без перезапуска приложения. Соединения с S3 SHALL открываться +при первом вызове, а при остановке сервиса клиент SHALL закрываться. + +Ключ объекта SHALL начинаться с имени базы PostgreSQL процесса и `/`. +Так объекты прогона на временной базе (`make test_isolated`) отделены +от объектов рабочей базы. + +#### Scenario: S3 остановлен + +- **WHEN** S3 остановлен, и приложение записывает объект +- **THEN** вызов за доли секунды завершается ошибкой недоступности, без + повторов + +#### Scenario: S3 завис + +- **WHEN** контейнер S3 заморожен (`docker pause`), и приложение + записывает объект +- **THEN** вызов завершается ошибкой недоступности не позже срока + вызова + +#### Scenario: S3 вернулся + +- **WHEN** S3 снова доступен, а приложение не перезапускалось +- **THEN** следующий вызов проходит + +#### Scenario: Объекта нет + +- **WHEN** приложение читает ключ, которого в bucket нет +- **THEN** клиент сообщает, что объекта нет, а не недоступность S3 + +#### Scenario: Bucket нет + +- **WHEN** bucket приложения удалён мимо bootstrap, и приложение + записывает, читает или удаляет объект либо запрашивает список объектов +- **THEN** каждый вызов завершается ошибкой недоступности, а не + сообщением «объекта нет» и не пустым списком, и в журнале есть запись + уровня `error` + +#### Scenario: Учётные данные отклонены + +- **WHEN** секрет API у приложения не совпадает с секретом на сервере + S3 +- **THEN** вызов завершается ошибкой недоступности, а в журнале есть + запись уровня `error` без секрета diff --git a/openspec/changes/track2-reconciler/specs/service-configuration/spec.md b/openspec/changes/track2-reconciler/specs/service-configuration/spec.md new file mode 100644 index 00000000..1112766e --- /dev/null +++ b/openspec/changes/track2-reconciler/specs/service-configuration/spec.md @@ -0,0 +1,38 @@ +## ADDED Requirements + +### Requirement: Параметры сверки + +Параметры сверки bucket и БД (capability `storage-consistency`) SHALL +задаваться в секции `[reconciler]`: +- `interval_seconds` — пауза между плановыми сверками процесса + уборщика, по умолчанию 3600; 0 — без плановой сверки; +- `page_size` — сколько ключей сверка берёт одной страницей списка S3 + и сколько строк одним запросом к PostgreSQL, по умолчанию 1000, не + больше 1000; +- `max_changes` — предел изменений за проход, по умолчанию 100. + +`interval_seconds` SHALL быть неотрицательным числом, `page_size` и +`max_changes` — целыми не меньше 1. Иначе уборщик MUST NOT стартовать +(требование «Некорректное значение останавливает запуск»). + +Отдельного grace у сверки нет: она берёт `[cleaner] +pending_grace_seconds` и его проверку границы живой загрузки +(требование «Параметры уборщика»). Разовая подмена SHALL работать через +окружение `RECONCILER__*` без правки файлов. Разовый проход SHALL +принимать предел изменений и аргументом команды. Значения по умолчанию +и их обоснование SHALL быть описаны в `REPORT.md`. Реплики API секцию +`[reconciler]` не используют. + +#### Scenario: Параметры сверки по умолчанию + +- **WHEN** уборщик запущен без секции `[reconciler]` и без переменных + `RECONCILER__*` +- **THEN** запись о его старте называет интервал сверки 3600 с, + страницу 1000 и предел изменений 100 + +#### Scenario: Неверный параметр сверки + +- **WHEN** уборщик запускается с `RECONCILER__PAGE_SIZE=5000`, + `RECONCILER__MAX_CHANGES=0` или `RECONCILER__INTERVAL_SECONDS=-1` +- **THEN** уборщик не стартует, в журнале — ошибка проверки настроек с + именем поля diff --git a/openspec/changes/track2-reconciler/specs/service-logging/spec.md b/openspec/changes/track2-reconciler/specs/service-logging/spec.md new file mode 100644 index 00000000..2970d8fc --- /dev/null +++ b/openspec/changes/track2-reconciler/specs/service-logging/spec.md @@ -0,0 +1,44 @@ +## ADDED Requirements + +### Requirement: Журнал сверки + +Сверка bucket и БД (capability `storage-consistency`) SHALL писать в +журнал процесса уборщика JSON-записи в формате этой capability, в каждой +— `instance_id` процесса. Записи: +- запись о старте уборщика дополнительно называет интервал сверки, + размер страницы и предел изменений; +- каждое найденное расхождение — класс, ключ объекта, `id` вложения, + если он известен, возраст, размеры объекта и метаданных, если они + разные. Уровень `warning`, если расхождение осталось, и `info`, если + проход с `--apply` его исправил, с названием действия; +- итог прохода — режим, сколько объектов и строк просмотрено, сколько + найдено и исправлено по классам, сколько свежих и уже помеченных, + длительность и причина прерывания. Уровень `info`, если расхождений не + осталось, иначе `warning`; +- превышение предела изменений — `error` с числом изменений и пределом; +- отказ S3 или PostgreSQL — `warning`, непредвиденная ошибка — `error` с + traceback. + +Если расхождений за проход больше тысячи, отдельными записями SHALL +писаться только первые, а итог SHALL называть, сколько осталось без +записи. Скачивание потерянного оригинала реплика API SHALL писать +записью уровня `info` с `id` вложения и ключом объекта, а не `error`. +Записи сверки MUST NOT содержать ключи доступа и секреты S3, ключ +подписи, подписи запросов, `filename` вложений и байты объектов. + +#### Scenario: Журнал разового прохода + +- **WHEN** сверка находит объект без метаданных и метаданные без + объекта, а затем исправляет их с `--apply` +- **THEN** результат такой: + - в журнале dry-run — две записи `warning` с классом, ключом и + возрастом и итог `warning`; + - в журнале прохода с `--apply` — две записи `info` с действием и + итог `info`; + - секретов S3 и `filename` в журнале нет + +#### Scenario: Предел изменений в журнале + +- **WHEN** сверка с `--apply` отказывается исправлять из-за предела +- **THEN** в журнале запись `error` с числом изменений и пределом, а + итог прохода — `warning` diff --git a/openspec/changes/track2-reconciler/specs/storage-consistency/spec.md b/openspec/changes/track2-reconciler/specs/storage-consistency/spec.md new file mode 100644 index 00000000..2a1c5ed0 --- /dev/null +++ b/openspec/changes/track2-reconciler/specs/storage-consistency/spec.md @@ -0,0 +1,290 @@ +## ADDED Requirements + +### Requirement: Сверка bucket и БД + +Сверка SHALL сравнивать объекты вложений в bucket — ключи с префиксом +`<имя базы>/attachments/` — с метаданными вложений той же базы в +PostgreSQL и находить расхождения шести классов: +- **объект без метаданных** — объект с ключом вида + `<база>/attachments//original`, на который не ссылается ни одна + строка и для `id` которого строки нет; +- **метаданные без объекта** — вложение `ready`, объекта по ключу из его + метаданных в bucket нет; +- **другой размер** — вложение `ready`, размер объекта не равен + `size_bytes`; +- **зависшая загрузка** — вложение в статусе «загружается» старше grace, + то же, что убирает уборщик (требование «Уборщик незавершённых + загрузок»); +- **оригинал вернулся** — оригинал вложения помечен потерянным + (требование «Потерянный оригинал»), а объект снова есть с тем же + размером; +- **чужой объект** — объект под префиксом вложений, ключа такого вида + API не пишет, либо ключ вида `/original`, у строки которого + другой ключ. + +Сверку SHALL выполнять процесс уборщика, а не реплики API: разовым +проходом (`make reconcile` или команда сверки в контейнере уборщика) и +плановым (требование «Плановая сверка»). Разовый проход по умолчанию +SHALL ничего не менять (dry-run). С `--apply` он SHALL исправлять: +- объект без метаданных — удалить объект; +- метаданные без объекта и другой размер — пометить оригинал вложения + потерянным; +- зависшую загрузку — убрать тем же порядком, что уборщик; +- вернувшийся оригинал — снять пометку. + +Чужой объект сверка MUST NOT удалять: он попадает только в отчёт. + +Отчёт SHALL называть по каждому расхождению класс, ключ объекта, `id` +вложения, если он известен, и возраст. Итог прохода SHALL называть: +- сколько объектов и строк просмотрено; +- сколько расхождений найдено и исправлено по классам; +- сколько объектов и строк пропущено как свежие; +- сколько вложений уже помечены потерянными. + +После успешного исправления повторный проход SHALL не находить ни одного +исправимого расхождения. + +Код выхода разового прохода: +- 0 — расхождений нет: dry-run их не нашёл, `--apply` исправил все, и + чужих объектов нет; +- 3 — расхождения остались: их нашёл dry-run, `--apply` отказался по + пределу изменений или в bucket есть чужие объекты; +- 1 — проход прерван отказом хранилища, ошибкой или сигналом; +- 2 — неверная конфигурация. + +#### Scenario: Расхождения с обеих сторон найдены + +- **WHEN** всё это старше grace, и выполняется сверка без `--apply`: + - в bucket мимо API записан объект вложения; + - у готового вложения удалён объект; + - у неиспользуемого готового вложения удалены метаданные; + - у другого в метаданных изменён размер; + - загрузка оборвалась между записью объекта и фиксацией `ready` +- **THEN** отчёт называет каждое расхождение его классом, ключом и + возрастом, код выхода 3, а в PostgreSQL и в bucket ничего не + изменилось + +#### Scenario: Исправление расхождений + +- **WHEN** после этого выполняется сверка с `--apply` +- **THEN** результат такой: + - объекты без метаданных удалены; + - зависшей загрузки нет — ни метаданных, ни объекта; + - оба вложения с потерянным оригиналом помечены, их метаданные на + месте; + - код выхода 0 + +#### Scenario: Повторная сверка + +- **WHEN** сразу после исправления сверка выполняется ещё раз +- **THEN** ни одного из этих расхождений в отчёте нет, а код выхода + соответствует отчёту: 0, если расхождений в нём нет + +### Requirement: Безопасность сверки + +Сверка MUST NOT удалять: +- метаданные вложений, кроме уборки зависшей загрузки; +- объект, на который ссылаются метаданные, в любом статусе; +- объект с ключом вида `/original`, если строка этого `id` есть. + +Вложение, на которое ссылается сообщение, MUST NOT терять из-за сверки +ни метаданные, ни объект, ни ссылку в истории. Если его оригинал +потерян, сверка его только помечает. + +Свежее сверка MUST NOT трогать и не считает расхождением: +- объект, записанный или изменённый в S3 меньше grace назад; +- вложение, метаданные которого записаны или переведены в `ready` меньше + grace назад. + +Grace — тот же, что у уборщика (capability `service-configuration`, +«Параметры уборщика»). + +Каждое расхождение SHALL перепроверяться в PostgreSQL и в S3 +непосредственно перед действием: +- объект без метаданных — строки с этим ключом или `id` по-прежнему + нет, объект на месте и старше grace; +- метаданные без объекта и другой размер — вложение по-прежнему `ready` + с тем же ключом, а объекта по ключу нет или его размер другой; +- вернувшийся оригинал — пометка на месте, объект того же размера. + +Не подтвердилось — действие не выполняется. Отсутствие объекта MUST NOT +считаться подтверждённым, пока не проверено, что bucket на месте. Иначе +удалённый bucket выглядел бы как потеря всех оригиналов. + +Предел изменений: если за проход нужно удалить объекты, пометить +оригиналы или снять пометки больше чем у `[reconciler] max_changes` +вложений, сверка с `--apply` MUST NOT выполнять ни одно из этих +изменений. Она пишет ошибку с числом изменений и пределом и завершается +кодом 3. Разовый проход SHALL принимать больший предел аргументом. +Уборка зависших загрузок пределом не ограничена. + +Сверка, уборщик и две сверки одновременно SHALL не мешать друг другу: +- каждое действие безопасно повторять; +- зависшую загрузку сверка убирает тем же порядком и под той же + блокировкой, что уборщик. + +Объекты других баз и ключи вне префикса вложений своей базы сверка MUST +NOT читать и менять. + +#### Scenario: Свежие не тронуты + +- **WHEN** в bucket мимо API записан объект вложения, у готового + вложения удалён объект, обоим меньше grace, и выполняется сверка с + `--apply` +- **THEN** объект на месте, вложение не помечено, а отчёт считает их + свежими, а не расхождениями + +#### Scenario: Используемое вложение не удаляется + +- **WHEN** у вложения, на которое ссылается сообщение, удалён объект, + ему больше grace, и выполняется сверка с `--apply` +- **THEN** результат такой: + - вложение помечено потерянным; + - его метаданные — 200; + - история чата по-прежнему отдаёт его `id` в сообщении; + - ни одна строка вложений не удалена + +#### Scenario: Чужой объект не удаляется + +- **WHEN** под префиксом вложений базы лежит объект с ключом, которого + API не пишет, ему больше grace, и выполняется сверка с `--apply` +- **THEN** объект на месте, отчёт называет его чужим, код выхода 3 + +#### Scenario: Предел изменений + +- **WHEN** расхождений, которые сверка исправила бы, больше предела, и + выполняется сверка с `--apply` +- **THEN** ни один объект не удалён, ни одно вложение не помечено, + ошибка называет число изменений и предел, код выхода 3 +- **AND** с пределом не меньше их числа повтор исправляет все + +#### Scenario: Сверка под нагрузкой + +- **WHEN** выполняются все условия: + - участники дольше grace загружают вложения и отправляют сообщения с + ними; + - в это время сверка с `--apply` повторяется раз в несколько секунд; + - в стенде есть внесённые расхождения +- **THEN** внесённые расхождения исправлены, каждое вложение, загрузка + которого ответила 201, скачивается с тем же SHA-256, а каждое + сообщение отдаёт свои `attachment_ids` + +### Requirement: Потерянный оригинал + +Если сверка подтвердила, что объекта готового вложения нет или его +размер другой, она SHALL пометить оригинал вложения потерянным и +записать время пометки в метаданные. Сверка не удаляет ни метаданные, ни +ссылки сообщений, ни объект другого размера. Байты сверка не +восстанавливает: их нет нигде. Что видит API для помеченного вложения — +capability `attachments`, «Скачивание оригинала». + +Пометка MUST NOT менять поля вложения в ответах API, в том числе +`status` и `updated_at`. Пометку SHALL снимать сверка с `--apply`, когда +объект по ключу вложения снова есть и его размер равен `size_bytes`. + +#### Scenario: Оригинал вернулся + +- **WHEN** оригинал вложения помечен потерянным, затем те же байты + записаны в bucket под его ключом, и выполняется сверка с `--apply` +- **THEN** пометка снята, байты вложения скачиваются — 200 с тем же + SHA-256, а следующий проход не находит расхождений по этому вложению + +### Requirement: Сверка при отказах хранилищ + +Если S3 недоступен, не ответил за срок вызова, отказал в доступе или +bucket нет, либо недоступна PostgreSQL, проход сверки SHALL прерываться +на первом же отказе. Новых изменений после отказа он не делает. Код +выхода разового прохода — 1. Плановая сверка повторяется через свой +интервал без перезапуска процесса. + +Изменения, сделанные до отказа, остаются верными. Каждое действие +сверки — отдельный безопасный шаг, поэтому прерванный проход SHALL +доводить следующий. + +#### Scenario: S3 недоступен во время сверки + +- **WHEN** в стенде есть расхождения старше grace, S3 остановлен, и + выполняется сверка с `--apply` +- **THEN** код выхода 1, ни один объект не удалён, ни одно вложение не + помечено +- **AND** после возврата S3 повтор исправляет все расхождения + +#### Scenario: Прерванная сверка доводится повтором + +- **WHEN** сверка с `--apply` прерывается отказом PostgreSQL на пометке + одного из вложений +- **THEN** код выхода 1 +- **AND** когда PostgreSQL снова принимает запись, повтор исправляет + оставшиеся расхождения, и следующий проход их не находит + +### Requirement: Плановая сверка + +Процесс уборщика SHALL сам выполнять сверку с исправлением, без +разового прохода: +- при старте; +- затем не реже чем раз в `[reconciler] interval_seconds`; +- с пределом изменений из настроек. + +Значение 0 выключает плановую сверку. Плановая и разовая сверки — один +и тот же проход с теми же правилами безопасности. + +Ограничение называется в `REPORT.md`. Пока идёт проход сверки, уборка +зависших загрузок ждёт его конца. Объект без метаданных на стенде живёт +не дольше суммы grace, интервала сверки и прохода. + +#### Scenario: Плановая сверка без команды + +- **WHEN** у готового вложения старше grace удалён объект, а уборщик + работает с коротким интервалом сверки +- **THEN** не позже интервала с запасом вложение помечено потерянным + без разового прохода, а в журнале уборщика есть итог сверки + +## MODIFIED Requirements + +### Requirement: Уборщик незавершённых загрузок + +Незавершённую загрузку SHALL убирать уборщик — отдельный процесс стенда +(capability `container-run`), а не реплики API. Незавершённая загрузка — +вложение, которое осталось в статусе «загружается» (capability +`attachments`, «Порядок записи»). + +Уборщик SHALL проходить по незавершённым загрузкам не реже чем раз в +`[cleaner] interval_seconds`. Каждую загрузку, метаданные которой +записаны раньше чем `[cleaner] pending_grace_seconds` назад (grace +period), он SHALL убирать по шагам: +1. пометить её метаданные как убираемые и зафиксировать пометку + (требование «Безопасность уборки»); +2. удалить объект по ключу из её метаданных; отсутствие объекта — не + ошибка; +3. только после подтверждённого удаления объекта — удалить метаданные. + +Каждый шаг SHALL быть безопасно повторяемым: проход, прерванный на +любом шаге, доводит следующий. После уборки у вложения не остаётся ни +метаданных, ни объекта. Объект вложения без метаданных уборка MUST NOT +оставлять: метаданные удаляются последними. + +Ограничение называется в `REPORT.md`. Объект может остаться без +метаданных, если процесс API заморожен дольше grace посреди записи +объекта. После разморозки он дописывает объект уже убранной загрузки, а +удалить его не может: запись объекта завершилась для API ошибкой по +сроку, или не удалось удаление при компенсации. Такой объект находит и +удаляет сверка bucket и БД (требование «Сверка bucket и БД»), когда он +старше grace. На стенде это происходит не позже следующей плановой +сверки (требование «Плановая сверка»). + +#### Scenario: Зависшая загрузка убрана + +- **WHEN** загрузка оборвалась после записи метаданных: S3 был + остановлен или заморожен на время записи объекта, либо PostgreSQL + отказал при фиксации `ready`. С записи метаданных прошло больше grace, + S3 и PostgreSQL доступны +- **THEN** ни метаданных, ни объекта этого вложения нет, а в bucket нет + объектов вложений без метаданных + +#### Scenario: Объект без фиксации убран + +- **WHEN** объект вложения записан в S3, а процесс API убит до фиксации + `ready` +- **THEN** до истечения grace есть и метаданные в статусе + «загружается», и объект, а после него нет ни того, ни другого, и в + bucket нет объектов вложений без метаданных diff --git a/openspec/changes/track2-reconciler/specs/student-tests/spec.md b/openspec/changes/track2-reconciler/specs/student-tests/spec.md new file mode 100644 index 00000000..f427682f --- /dev/null +++ b/openspec/changes/track2-reconciler/specs/student-tests/spec.md @@ -0,0 +1,102 @@ +## MODIFIED Requirements + +### Requirement: Проверки отказов на отдельном стенде + +Сценарии отказов SHALL проверяться автоматически одной командой +`make failure_checks`: +- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при + запросе с токеном»; +- `data-storage`: «Сбой при добавлении участников», «БД остановлена», + «БД вернулась», «Соединения исчерпаны»; +- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище + объектов недоступно»; +- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся», + «Очистка кэша»; +- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке», + «Ключ после срока»; +- `api-conventions`: «Лимит одновременных загрузок»; +- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего + не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не + видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв + передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь + ожидания полна», «Ожидание места», «Место освобождается», «Медленный + клиент», «Медленная передача в срок», «Потерянный оригинал»; +- `storage-consistency`: все сценарии. + +Команда SHALL: +- собрать образ из рабочего дерева; +- поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить + миграции и bootstrap S3; +- запустить три API: + - с настройками по умолчанию; + - «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом + из одного соединения; + - «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в + очереди, коротким сроком ожидания места и коротким сроком тела. Их + значения SHALL передаваться проверкам; +- запустить уборщика с коротким grace и интервалом, сравнимыми со + временем теста, без плановой сверки, и передать их значения + проверкам. Grace при этом SHALL проходить проверку границы живой + загрузки (`service-configuration`, «Параметры уборщика»). Сверку + проверки запускают сами, и плановая сверка не меняет стенд у них за + спиной; +- выполнить проверки отказов; +- удалить стенд вместе с его данными при любом исходе. + +Hook стенда отказов SHALL уметь: +- сообщить вложения стенда в PostgreSQL с их статусами, `id` последнего + вложения в статусе «загружается» и `id` вложений с потерянным + оригиналом; +- сообщить, у каких вложений есть объект в bucket стенда, — по самим + объектам, а не по каталогам хранилища; +- внедрить отказ PostgreSQL: + - при записи метаданных загрузки с заданным `filename`; + - при фиксации её `ready`, и задержать такую фиксацию; + - при пометке потерянного оригинала такого вложения; +- убить и снова запустить обычный API стенда; +- внести расхождения хранилищ: + - записать объект в bucket стенда мимо API и удалить объект мимо API — + только под префиксом вложений базы стенда; + - удалить метаданные вложения, изменить в них размер и сдвинуть их + время в прошлое; +- выполнить разовую сверку — без изменений или с `--apply`, с заданным + пределом изменений — и вернуть её записи и код выхода; +- остановить и запустить уборщика стенда, а также запустить отдельного + уборщика с коротким интервалом плановой сверки на заданное время и + вернуть его журнал. + +Других сведений о хранилищах проверки вложений не получают. Объекты без +метаданных проверка находит сравнением двух списков: вложений и +объектов. Ключи доступа S3 hook не получает и не печатает: объект мимо +API записывает процесс в контейнере стенда своими ключами. + +Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на +хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш, +хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода +SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка. +Параллельный запуск двух прогонов не поддерживается: уборка хвоста в +начале второго удаляет стенд первого. + +#### Scenario: Успешный прогон + +- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks` +- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и + volumes стенда отказов после команды нет, а у контейнеров рабочего + стенда прежнее время старта, и рабочий API отвечает + +#### Scenario: Упавшая проверка + +- **WHEN** во время `make failure_checks` падает хотя бы одна проверка +- **THEN** код выхода ненулевой, журналы API и уборщика стенда отказов + выведены, стенд отказов удалён + +#### Scenario: Прерывание + +- **WHEN** `make failure_checks` прерван Ctrl+C +- **THEN** стенд отказов остановлен и удалён вместе с volumes + +#### Scenario: Хвост прошлого прогона + +- **WHEN** контейнеры или volumes стенда отказов остались от прогона, + убитого без уборки +- **THEN** следующий `make failure_checks` удаляет их и начинает заново diff --git a/openspec/changes/track2-reconciler/tasks.md b/openspec/changes/track2-reconciler/tasks.md new file mode 100644 index 00000000..cd99625e --- /dev/null +++ b/openspec/changes/track2-reconciler/tasks.md @@ -0,0 +1,398 @@ +# Tasks + +Как строить — `design.md` (дальше «решение N»), что должно получиться — +дельты в `specs/`. Порядок — design, Migration Plan, но тесты и hook +пишутся первыми: так красный прогон снимается без checkout и stash. +Перед первым файлом слоя прочитать его правило: `service-layer.md`, +`repo-layer.md`, `dto.md`, `infra.md`, `migrations.md`, `logging.md`, +`settings.md`, `run-modes.md`, `docker.md`, `balancer.md`, +`student-tests.md`, `api-contract.md`, `bench.md`. + +Commit делает основная сессия после подтверждения пользователя +(`bench.md`, «Измеренное состояние — commit»). Evidence — только с +закоммиченного кода. Временные проекты compose, их volumes, сети и +образы убираются сразу после проверки. Список volumes сверяется с +исходным: `docker volume ls -q | sort | shasum`. Volumes +`mtusi-lab4_postgres_data` и `mtusi-lab4_s3_data` не удаляются никогда. + +Вопрос преподавателю об ответе API на потерянный оригинал открыт +(`PLAN.md`, `### track2-reconciler` → «Вопросы», п. 1). Строится вариант +по умолчанию: метаданные — 200, байты — 404 после пометки и 500 до неё, +ссылка — 201. Ответ «иначе» меняет задачи 5.1 и 1.3 (тест «Потерянный +оригинал») и сценарий `attachments`, остальное — нет. + +Ожидаемо красное по ходу работы, остальное разбирается по AGENTS.md: +- между задачами 1.3 и 9.1 сверка покрытия в `make student_test` падает + на маркерах новых сценариев («marker points to unknown scenario»); +- до задачи 12.2 — `test_exclusion_evidence_exists` не меняется: + исключений этот change не добавляет. + +## 1. Hook, стенд отказов, тесты и красный прогон + +- [ ] 1.1 `student-tests/fault_hook.py` по решению 11 (только stdlib, + синтаксис 3.9, docstring — новые действия): + - `put-object <ключ>`: тело из stdin, `docker exec -i <проект>-api + python -c …` — botocore образа с ключами API из окружения + контейнера; + - `delete-object <ключ>`: `weed shell fs.rm /buckets//<ключ>`. + Ключ у обоих — только под `/attachments/`, символы + `[A-Za-z0-9._/-]`, иначе код 2; + - `delete-row`, `set-size`, `age-row`, `lost-ids` — psql, значения + только переменными psql; + - `fail-attachments mark ` — отдельный триггер `BEFORE UPDATE + OF lost_at`. Его снимает `clear-fail-attachments`, прежние режимы + новой колонки не касаются; + - `reconcile dry-run|apply [<предел>]`: `compose_run` проекта, + записи процесса и строка `exit_code=`, код hook — 0; + - `stop|start cleaner`; + - `run-cleaner <секунд>`: контейнер `<проект>-cleaner-scheduled` с + `RECONCILER__INTERVAL_SECONDS=1`, затем `docker stop`, журнал и + `docker rm`. + + Ключей и секретов hook не печатает и не получает. Проверка: `make + lint`; поведение — 1.4 и группа 9. +- [ ] 1.2 Стенд отказов: + - `failures.compose.yml`: у `cleaner` — `RECONCILER__INTERVAL_SECONDS: + "0"` с комментарием (решение 9); + - `run_failures.py`: `<проект>-cleaner-scheduled` — в списке уборки и + журналов при падении; строка `start cleaner` называет и интервал + сверки. + + Проверка: `make failure_checks FAULT_ARGS='-k readiness'` — стенд + поднят и убран, контейнеров и volumes проекта отказов после команды + нет. +- [ ] 1.3 Тесты в `student-tests/test_failures.py` по таблице решения 11 + — восемь тестов с маркерами `fault` и `spec`: + - `test_reconcile_finds_and_fixes`; + - `test_reconcile_keeps_fresh_used_and_unknown`; + - `test_reconcile_restored_original`; + - `test_reconcile_change_limit`; + - `test_reconcile_object_storage_stopped`; + - `test_reconcile_interrupted_by_database`; + - `test_reconcile_under_load`; + - `test_scheduled_reconcile`. + + Как устроены: + - помощники разбора записей сверки (`Found` / `Fixed` / `Finished`, + `exit_code`) — в начале раздела; + - фильтр — по своим `id` и ключам; + - код выхода сверяется с записями того же прохода (решение 11); + - объекты без строки ждут G + 1 с, остальные — `age-row`; + - остановки — `with outage(...)`; + - клиенты потоков — со сроком 30 с. +- [ ] 1.4 Красный прогон до кода групп 2–7: `make failure_checks + FAULT_ARGS='-k reconcile'` на нынешнем коде (`5f4b9ff`). Ожидаемо + падают все восемь: команды `reconcile` нет (argparse — код 2), колонки + `lost_at` нет (`lost-ids` — ошибка hook). Число упавших и причины — в + tasks при прогоне и в разделе красного прогона + `evidence/tests/failure-checks.md` (задача 12.6). Рабочий стенд не + трогается. + +## 2. Настройки, константы, enum и DTO + +- [ ] 2.1 Секция `[reconciler]` по решению 10 и дельте + `service-configuration`: + - класс `Reconciler` в `src/config/settings.py`: `interval_seconds` + (float, ≥ 0, 3600), `page_size` (int, 1–1000, 1000), `max_changes` + (int, ≥ 1, 100); + - поле `reconciler` в `Settings`; + - строки с комментариями в `config_example.toml`. + + Проверка: `uv run python -c "from src.config import settings; + print(settings.reconciler)"` — значения по умолчанию; + `RECONCILER__PAGE_SIZE=5000`, `RECONCILER__MAX_CHANGES=0` и + `RECONCILER__INTERVAL_SECONDS=-1` — ошибка проверки называет поле. +- [ ] 2.2 Типы по решению 8 и `dto.md`: + - `ReconcileFinding` (`StrEnum`) в `src/schemas/enums/attachment.py`; + - `ReconcileFindingDTO`, `ReconcilePassDTO` в + `src/schemas/dataclasses/attachment.py`; + - `AttachmentFullDTO.lost_at: datetime | None = None` — последним + полем; + - `RECONCILE_FINDINGS_LOGGED_MAX = 1000` в `src/utils/constants.py`; + - реэкспорт в `__init__.py` по алфавиту. + + Проверка: `make lint`. + +## 3. Схема + +- [ ] 3.1 Колонка `lost_at` по решению 6: + - модель `Attachment` — `lost_at: Mapped[datetime | None]` + (`DateTime(timezone=True)`); + - ревизия поверх `739b8f04d5fb`: первой строкой `SET LOCAL lock_timeout + = '2s'`, `add_column`; `downgrade` — `drop_column` с тем же сроком. + + Проверка на временной базе (`createdb` в контейнере `postgres`, + `DATABASE__NAME` в окружении, затем `DROP DATABASE`): + - `upgrade` с нуля → повтор без изменений → `downgrade -1` → + `upgrade`; + - `uv run alembic upgrade head --sql` — `SET LOCAL lock_timeout` перед + `ALTER TABLE attachments ADD COLUMN lost_at`; + - `\d attachments` — колонка `timestamptz` без значения по умолчанию. + + Вывод — для evidence 12.5. + +## 4. Клиент S3 и repo + +- [ ] 4.1 `src/infra/s3/client.py` по решению 3 и дельте + `object-storage`: + - `StoredObjectInfo.last_modified` (из LIST и HEAD); + - страница списка `list_page(prefix, *, token, max_keys)` — + `list_objects_v2`, результат — ключи с размером и временем плюс токен + продолжения; + - вызов без `Key` в `_call` (общий срок и перевод ошибок); + - `NoSuchBucket` и `AccessDenied` на списке — `ObjectStorageUnavailable` + с прежними записями `error`. + + Проверка: `make lint`; поведение — 4.4 и группа 9. +- [ ] 4.2 `src/core/repos/attachment_object.py`: + - `list_originals` — префикс `/attachments/`; + - `parse_original_key` — `UUID` для ключа вида `/original` в нижнем + регистре, иначе `None`; + - `head_original`; + - `probe_originals` — список с `MaxKeys=1`: bucket на месте и список + разрешён. + + Проверка: `make lint`. +- [ ] 4.3 `src/core/repos/attachment.py` по решениям 3–5 (одно выражение + на функцию, `repo-layer.md`): + - `_ATTACHMENT_COLUMNS` + `lost_at`; + - выборка страницы по `id = ANY(:ids) OR object_key = ANY(:keys)`; + - keyset строк `ready` по `id`; + - `find_attachment_reference(id, key)`; + - `mark_lost` и `clear_lost` — условный `UPDATE … RETURNING id`. + + Проверка: `make lint`; на временной базе с ≥ 10 000 строк `ready` — + `EXPLAIN (ANALYZE, BUFFERS)` выборки страницы (Bitmap OR по + `pk_attachments` и `uq_attachments_object_key` или только pk при + пустом `keys`) и keyset (Index Scan `pk_attachments`). Итог — в + design, «Уточнения apply». +- [ ] 4.4 Проверка клиента и repo на временном проекте compose. Как в + пробе design, Context: SeaweedFS на tmpfs и bootstrap группы 8.1. Ключ + уборщика: + - список своего префикса страницами по 1000 — все ключи и + `LastModified`; + - весь bucket и чужой префикс — `ObjectStorageUnavailable` («denied + access»); + - удалённый bucket — `ObjectStorageUnavailable` («bucket is missing»), + а не пустая страница. + + Проект и его ресурсы убраны. + +## 5. API: потерянный оригинал + +- [ ] 5.1 `AttachmentService.open_content` по решению 5 и дельте + `attachments`: `lost_at` задан — `info` «Attachment content is lost» + (`attachment_id`, `object_key`) и `AttachmentNotFound` до обращения к + S3. Без пометки и без объекта — 500, как было. Метаданные и + `MessageService` не меняются. Проверка: `make lint`; тесты 1.3 + «Потерянный оригинал»; `make test_isolated` — прежние тесты + вложений зелёные. + +## 6. Сервис сверки + +- [ ] 6.1 `AttachmentReconcileService(db_scope, storage)` в + `src/core/services/attachment_reconcile.py` по решениям 3, 4, 7 и 8: + - шаги «S3 → БД», «БД → S3», зависшие загрузки; + - перепроверка и проверка bucket до решения; + - предел изменений; + - действия по порядку решения 7; + - `stop_requested` между страницами и действиями; + - итог — `ReconcilePassDTO`; + - записи журнала по дельте `service-logging` и не больше + `RECONCILE_FINDINGS_LOGGED_MAX` записей находок; + - уборка зависших — через `AttachmentCleanupService`. + + Проверка: `make lint`; поведение — группа 9. + +## 7. Процесс уборщика + +- [ ] 7.1 `src/cleaner/main.py` (и `__main__.py`, если нужно) по + решениям 1, 8 и 9: + - команда `reconcile [--apply] [--max-changes N]` (`N` ≥ 1), коды + 0 / 3 / 1 / 2; + - общая подготовка с сервисом: проверка grace, сигналы, + `early_stop.disarm()`, engine, клиент S3; + - плановая сверка в цикле сервиса (при старте, затем через + `[reconciler] interval_seconds`, 0 — нет); + - «Started cleaner» с параметрами сверки и режимом; + - `--once` — как было. + + Проверка без стенда: + - `RECONCILER__PAGE_SIZE=5000 uv run python -m src.cleaner reconcile` — + «Invalid cleaner settings» с `reconciler.page_size`, код 2; + - `CLEANER__PENDING_GRACE_SECONDS=17 … reconcile` — код 2 до обращения + к хранилищам; + - `… reconcile --max-changes 0` — ошибка аргумента, код 2; + - `make lint`. + +## 8. Стенд + +- [ ] 8.1 Права S3 по решению 2 и дельте `object-storage`: + - `infra/s3/bootstrap.sh`: `S3_CLEANER_LIST_PREFIX` (проверка + `^[a-z0-9_]+/attachments/$`, иначе «FAILED» и код 1); + - политика `cleaner-objects` с `s3:ListBucket` и условием `s3:prefix`; + - проверки `apply` — список префикса 200, всего bucket 403; + - строки режима `check` — свой префикс 200, без префикса 403, чужой + префикс 403, чужой bucket 403; + - шапка скрипта; + - `docker-compose.yml`: `S3_CLEANER_LIST_PREFIX: + ${POSTGRES_DB:?…}/attachments/` у `s3-bootstrap`. + + Проверка на временном проекте compose — tmpfs, синтетические секреты, + bootstrap проекта: + - первый запуск и повтор дважды — код 0; + - неверный префикс — код 1 и шаг в сообщении; + - строки `check` с ожидаемыми кодами. + + Затем на рабочем стенде `docker compose up -d s3-bootstrap` и `make + s3_check` — код 0, строки списка ключом уборщика есть. Проект пробы + убран, volumes сверены. +- [ ] 8.2 `Makefile`: цель `reconcile` (`$(DC) run --rm --no-deps cleaner + reconcile`, `APPLY=1` → `--apply`, `MAX_CHANGES=N` → `--max-changes N`) + с комментарием в стиле файла. Проверка: `make -n reconcile APPLY=1 + MAX_CHANGES=5` печатает команду с обоими флагами, `make -n reconcile` + — без них. +- [ ] 8.3 `bench/`: bootstrap профиля `uploads` получает префикс из + `bench.env` (`POSTGRES_DB=bench`). Секретов не прибавилось, + `compose_env` не меняется. В `bench.compose.yml` у описанного + `cleaner` — `RECONCILER__INTERVAL_SECONDS: "0"`: профиль сверки + `track2-reconcile-cost` включит её сам. Проверка: `make + bench_uploads_quick` — код 0 (bootstrap с префиксом прошёл), метка + `quick-*` в git не идёт. + +## 9. Спеки и проверки отказов + +- [ ] 9.1 Sync дельт в основные спеки — все семь capability, как в + прежних changes: сверка покрытия читает только `openspec/specs/`. + Purpose `storage-consistency` — без «добавят следующие changes»: сверка + описана. Проверка: + - `openspec validate track2-reconciler --strict`; + - `make student_test` через LB — `test_coverage.py` зелёный, сверка + называет новые сценарии `storage-consistency` и `attachments` + покрытыми проверками отказов. +- [ ] 9.2 Полный `make failure_checks` на дереве после групп 2–8: все + проверки зелёные (прежние 37 и новые 8), журнал PostgreSQL стенда без + признаков аварии, стенд отказов удалён, `StartedAt` рабочего стенда + прежний. Время прогона — в tasks. Два прогона одновременно не + запускать (`student-tests.md`). + +## 10. Драйвер скилла + +- [ ] 10.1 `driver.py reconcile-cycle` по решению 12 — только стенд с LB, + без LB код 2. Шаги: + - исходный dry-run; + - внесение расхождений с обеих сторон; + - ожидание grace прогона 30 с; + - dry-run со снимками до и после; + - 500 до сверки, `--apply`, 404 и 200 после; + - повтор, удаление чужого объекта, повтор с кодом 0; + - свежий объект после grace; + - возврат оригинала. + + Триггер `commit` — на уникальный `filename`, снимается в `finally` и в + начале следующего прогона. Таблицы без токенов и секретов, код 1 при + расхождении. Проверка: прогон на рабочем стенде (`--port 8090`) — код + 0; повторный прогон — снова 0, и исходный dry-run не находит остатков + прошлого. +- [ ] 10.2 `driver.py reconcile-stress [--seconds S] [--clients N]` по + решению 12. Шаги: + - предусловие — dry-run с grace 20 с, иначе код 2; + - внесённые расхождения; + - загрузки и отправки через LB, поток `--apply` раз в ~3 с; + - итоговая таблица и сверка SHA-256 каждого 201. + + Проверка: прогон на рабочем стенде — код 0, несовпадений 0. +- [ ] 10.3 `SKILL.md` скилла: обе команды, их evidence и что они меняют + на стенде (синтетические вложения, помеченные потерянными, остаются в + рабочей базе). Строки `s3-check` приходят из bootstrap, разбор не + меняется — проверить вывод `make s3_check`. + +## 11. Правила и документы + +- [ ] 11.1 Правила: + - `service-layer.md` — сервис сверки, порядок действий, ветка 404; + - `repo-layer.md` — новые функции; + - `dto.md` — `lost_at`, DTO сверки, enum; + - `infra.md` — список клиента, `last_modified`, префикс; + - `migrations.md` — ревизия `lost_at`; + - `docker.md` — политика `cleaner-objects`, `S3_CLEANER_LIST_PREFIX`, + уборщик на время восстановления БД; + - `settings.md` — `[reconciler]`; + - `logging.md` — журнал сверки; + - `run-modes.md` — команда `reconcile`, плановая сверка, коды; + - `api-contract.md` — 404 потерянного оригинала и вопрос; + - `student-tests.md` — действия hook, тесты, интервал сверки 0 на + стенде отказов; + - `balancer.md` — порядок обновления (решение 6). + + Проверка: в каждом правиле — ссылка на design этого change. +- [ ] 11.2 AGENTS.md: + - абзац инвариантов «Лаба 4, сверка» (что удаляется и что никогда, + grace, предел, права S3, 404); + - карта кода — `attachment_reconcile.py`, новые функции repo, команда + уборщика; + - таблица команд — `make reconcile`, `driver.py reconcile-cycle`, + `reconcile-stress`; + - вступление — change в архиве, когда он будет заархивирован. +- [ ] 11.3 `KNOWN_ISSUES.md`, запись «Bootstrap после удаления bucket», + по решению 14: причина (слоты томов на маленьком диске, `-volume.max=0`), + проба на 4 и 16 ГБ, стенды проекта не затронуты, предложение. Запись + остаётся открытой. + +## 12. Прогоны и evidence + +- [ ] 12.1 Commit кода (основная сессия, после подтверждения). Затем + рабочий стенд по порядку решения 6: + - `docker compose up -d s3-bootstrap`; + - `make rolling_update`; + - `docker compose up -d --no-deps cleaner`. + + Проверка: + - журнал уборщика — плановая сверка при старте без находок; + - `make reconcile` — код 0; + - `make test BASE_URL=http://localhost:8090`; + - `make student_test BASE_URL=http://localhost:8090`; + - `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make + test-failover ACTION_SCRIPT=scripts/stop-one.sh` для обеих реплик — + с `BASE_URL` LB; + - `make s3_check`. +- [ ] 12.2 `evidence/reconcile/cycle.md` — вывод `driver.py --port 8090 + reconcile-cycle` с датой и commit. +- [ ] 12.3 `evidence/reconcile/stress.md` — вывод `driver.py --port 8090 + reconcile-stress`. +- [ ] 12.4 `evidence/reconcile/service.md`: + - «Started cleaner» с параметрами сверки; + - плановая сверка при старте; + - `docker compose stop cleaner` во время сверки при `docker compose + pause s3` — время, код 0, записи прерывания и остановки; затем + `unpause`; + - отказ старта с `RECONCILER__PAGE_SIZE=5000`; + - коды разового прохода 0 и 3. +- [ ] 12.5 Остальное evidence: + - `evidence/s3/cleaner-list.md` — bootstrap с новой политикой, `make + s3_check`, окружение `s3-bootstrap` в `docker compose config`; + - `evidence/migrations/lost-at.md` — вывод 3.1 и `make rolling_update` + 12.1 с ревизией до и после. +- [ ] 12.6 `evidence/tests/`: + - `failure-checks.md` — полный прогон и раздел красного прогона 1.4; + - `student-test-lb.md`; + - вывод `make test_isolated`. +- [ ] 12.7 Регресс: + - `make bench_quick`; + - `bench_failover_quick`; + - `bench_rollout_quick` (замена `e1161f7` → новая ревизия под + нагрузкой, ошибок 0, сообщений = ключей); + - `bench_restore_quick`; + - `make test_isolated` — код 0 у каждой. + + Метки `quick-*` в git не идут. +- [ ] 12.8 `REPORT.md`: + - раздел «Сверка хранилищ (трек 2, change `track2-reconciler`)» — + классы, проход, правила безопасности, предел, права S3, ответы API + и вопрос преподавателю, плановая сверка; + - строки таблицы доказательств уровня «5» с командами и путями + evidence; + - ограничения из design, Risks; + - дополнение ответа на вопрос защиты «PUT прошёл, COMMIT нет». + + `PLAN.md` — строка этапа 5 и решения apply в `### track2-reconciler`.