docs: propose track2-reconciler

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-22 17:06:14 +03:00
co-authored by Claude Opus 5.5
parent 5f4b9ff61c
commit c13df14f36
12 changed files with 2119 additions and 0 deletions
+124
View File
@@ -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_<db>/` и чужой 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).
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-22
@@ -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` на
`<bucket>/*`. 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` только на ресурсе `<bucket>/*` | списка нет (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, в списке объекта нет, пустой каталог `<id>/` в список не попадает |
| 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_<db>/`, `.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:::<bucket>"],
"Condition": {"StringLike": {"s3:prefix": ["<база>/attachments/*"]}}}
```
Чтение и удаление на `<bucket>/*` — как были.
- Префикс 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_<db>/`) и проверочные объекты, а сверке они не
нужны. *Альтернатива:* `s3:ListBucket` на ресурсе `<bucket>/*`. По пробе
списка не даёт. *Альтернатива:* сузить по префиксу и чтение с удалением.
Отложена: проверки 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/<uuid в нижнем регистре>/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 из окружения контейнера пишет объект мимо приложения. Ключ — только под `<FAULT_DATABASE>/attachments/`, символы `[A-Za-z0-9._/-]` |
| `delete-object <ключ>` | `weed shell fs.rm /buckets/<bucket>/<ключ>` — мимо шлюза S3, с той же проверкой ключа |
| `delete-row <id>`, `set-size <id> <байт>`, `age-row <id> <секунд>` | psql: удалить строку (неиспользуемого вложения), изменить `size_bytes`, сдвинуть `created_at` и `updated_at` назад вместе. CHECK и непомеченность `pending` сохраняются |
| `lost-ids` | `id` строк с `lost_at` |
| `fail-attachments mark <filename>` | новый режим: `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=<n>`, код 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-<uuid>`) → ждать 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=<g>
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` «Потерянный оригинал» и
тест. Классы, правила безопасности, схема и задачи сверки не меняются.
@@ -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`.
@@ -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, что у ответа на
загрузку
@@ -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, а
в журнале — итог сверки с причиной прерывания «остановка» и запись об
остановке уборщика
@@ -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` без секрета
@@ -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** уборщик не стартует, в журнале — ошибка проверки настроек с
именем поля
@@ -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`
@@ -0,0 +1,290 @@
## ADDED Requirements
### Requirement: Сверка bucket и БД
Сверка SHALL сравнивать объекты вложений в bucket — ключи с префиксом
`<имя базы>/attachments/` — с метаданными вложений той же базы в
PostgreSQL и находить расхождения шести классов:
- **объект без метаданных** — объект с ключом вида
`<база>/attachments/<id>/original`, на который не ссылается ни одна
строка и для `id` которого строки нет;
- **метаданные без объекта** — вложение `ready`, объекта по ключу из его
метаданных в bucket нет;
- **другой размер** — вложение `ready`, размер объекта не равен
`size_bytes`;
- **зависшая загрузка** — вложение в статусе «загружается» старше grace,
то же, что убирает уборщик (требование «Уборщик незавершённых
загрузок»);
- **оригинал вернулся** — оригинал вложения помечен потерянным
(требование «Потерянный оригинал»), а объект снова есть с тем же
размером;
- **чужой объект** — объект под префиксом вложений, ключа такого вида
API не пишет, либо ключ вида `<id>/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 удалять:
- метаданные вложений, кроме уборки зависшей загрузки;
- объект, на который ссылаются метаданные, в любом статусе;
- объект с ключом вида `<id>/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 нет объектов вложений без метаданных
@@ -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` удаляет их и начинает заново
+398
View File
@@ -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/<bucket>/<ключ>`.
Ключ у обоих — только под `<FAULT_DATABASE>/attachments/`, символы
`[A-Za-z0-9._/-]`, иначе код 2;
- `delete-row`, `set-size`, `age-row`, `lost-ids` — psql, значения
только переменными psql;
- `fail-attachments mark <filename>` — отдельный триггер `BEFORE UPDATE
OF lost_at`. Его снимает `clear-fail-attachments`, прежние режимы
новой колонки не касаются;
- `reconcile dry-run|apply [<предел>]`: `compose_run` проекта,
записи процесса и строка `exit_code=<n>`, код 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` — префикс `<namespace>/attachments/`;
- `parse_original_key` — `UUID` для ключа вида `<id>/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`.