From dcdfe5f2e4139bc9e60889106f505023ec660930 Mon Sep 17 00:00:00 2001 From: roman Date: Fri, 23 Oct 2026 03:47:27 +0300 Subject: [PATCH] docs: propose track2-reconcile-cost Co-Authored-By: Claude Opus 5.5 --- PLAN.md | 94 ++ .../track2-reconcile-cost/.openspec.yaml | 2 + .../changes/track2-reconcile-cost/design.md | 863 ++++++++++++++++++ .../changes/track2-reconcile-cost/proposal.md | 127 +++ .../specs/graceful-shutdown/spec.md | 46 + .../specs/load-benchmark/spec.md | 274 ++++++ .../specs/service-configuration/spec.md | 44 + .../specs/service-logging/spec.md | 62 ++ .../specs/storage-consistency/spec.md | 369 ++++++++ .../specs/student-tests/spec.md | 108 +++ .../changes/track2-reconcile-cost/tasks.md | 383 ++++++++ 11 files changed, 2372 insertions(+) create mode 100644 openspec/changes/track2-reconcile-cost/.openspec.yaml create mode 100644 openspec/changes/track2-reconcile-cost/design.md create mode 100644 openspec/changes/track2-reconcile-cost/proposal.md create mode 100644 openspec/changes/track2-reconcile-cost/specs/graceful-shutdown/spec.md create mode 100644 openspec/changes/track2-reconcile-cost/specs/load-benchmark/spec.md create mode 100644 openspec/changes/track2-reconcile-cost/specs/service-configuration/spec.md create mode 100644 openspec/changes/track2-reconcile-cost/specs/service-logging/spec.md create mode 100644 openspec/changes/track2-reconcile-cost/specs/storage-consistency/spec.md create mode 100644 openspec/changes/track2-reconcile-cost/specs/student-tests/spec.md create mode 100644 openspec/changes/track2-reconcile-cost/tasks.md diff --git a/PLAN.md b/PLAN.md index d15eaed6..8296fbe6 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1426,3 +1426,97 @@ Change вне сводной таблицы, до `track2-reconcile-cost`: ис **Ответ пользователя 2026-10-23:** полную метку не переснимать, `evidence/uploads/baseline/` остаётся. В apply — точечная проба памяти PUT и `make bench_uploads_quick` (tasks 4.4). + +### track2-reconcile-cost + +#### Решения + +Приняты 2026-10-23 в `/opsx:propose`, подробности — design change +`track2-reconcile-cost`. Пробы — design, Context: временный проект +compose `rccost`, тот же `docker-compose.yml`, образ рабочего стенда +(`7f4e626`), PostgreSQL и S3 на volumes `rccost_*` — удалены по имени. +После пробы volumes, сети и образы — как до неё (155 / 17 / 24). Во время +пробы работали `domains-*`, поэтому задержки шумные, а счётчики точные. + +1. **Профиль `reconcile`** (решение 1): + - `make bench_reconcile` — **~50 мин**, `make bench_reconcile_quick` — + **~6 мин**; + - результаты — `evidence/reconcile/<метка>/`; + - этапы: A — 1k × 1 MiB, свежий стенд; B — 10k × 4 KiB, свежий; + C — 30k и D — 100k, тот же набор растёт; S4 — свежий стенд; + - три повтора кругами. + + Полная метка — отдельная точка commit после commit гипотез, на тихом + хосте: основная сессия останавливает `domains-*` на ~50 мин. +2. **Набор** (решение 2): + - N = 10k / 30k / 100k объектов по 4 KiB и 1k по 1 MiB; + - расхождения — по 0,25 % на класс (без метаданных, без объекта, + другой размер, зависшая загрузка), класс по номеру объекта; + - grace проходов — 30 с. + + Отвергнуты: 10k и 100k без средней точки, 1M, доли 0 % и 10 %, + случайные позиции. +3. **Наполнение мимо API** (решение 3): + - строки — `\copy` через stdin psql стенда; + - объекты — загрузчик `bench/fill_objects.py` в контейнере на образе + стенда, botocore и ключи API, ~1 750 PUT/с, упор в S3. + + Проход сверки — разовый уборщик, его результат — его журнал. Это новое + исключение границы чёрного ящика — только у профиля сверки. +4. **Стратегия `--strategy head`** (решение 4): выборка строки на объект + и HEAD на строку, без множества ключей. Только разовый проход; + плановая — `batch`. Проба: ~5,15 мс на объект против 0,30 у `batch` + (~17×). +5. **Глубокая сверка `--deep` — по требованию** (решение 5): + - SHA-256 потоком; + - новый класс `checksum_mismatch`, с `--apply` — пометка потерянного + оригинала; + - «оригинал вернулся» теперь требует того же SHA-256 во всех режимах. + + Выборочная глубокая в плановой отвергнута. Проба: предел глубокой на + лимите стенда — CPU уборщика, а не S3 (уточнение гипотезы 3). +6. **Предел скорости `[reconciler] max_objects_per_second`, по умолчанию + 2000** (решение 6): + - считаются объекты S3: ключи списка, HEAD, GET, DELETE; + - пауза прерывается сигналом; + - разовый проход принимает `--max-objects-per-second`, `make + reconcile` — `RATE`. + + 2000/с — ~0,2 ядра S3 на списке. Плановый проход 100k — ~65 с вместо + ~30. +7. **S4 — ранний отказ по пределу** (решение 7). Выбран порог + «подтверждено больше предела» с отдельным счётчиком `unchecked` в + итоге. Он действует у любого `--apply`, dry-run перепроверяет всех. + Проба на текущем коде: +5,3 мс на кандидата, +53 с при 10 000 + кандидатов. Отвергнуты отказ по числу неподтверждённых кандидатов и + ранний отказ только у плановой сверки. Замер — ячейки S4 на образе + `7f4e626` и на checkout. +8. **Счёт запросов** (решение 8): + - внутренний: счётчики клиента S3 по операциям и байтам, сеансы БД + обёрткой `db_scope` — в итоге прохода; + - внешний — только в метке: метрики шлюза `-metricsPort` на loopback, + только у S3 профиля сверки (override генерирует `run.py`) — и + `pg_stat_database`. Проба: шлюз считает HEAD типом GET, совпало до + запроса. + + Отвергнуты `pg_stat_statements` и порт метрик у рабочего стенда. +9. **Фоновая нагрузка и порог H4** (решение 10): + - 300 скачиваний, 50 записей и 50 чтений истории в секунду; + - тихие окна по 30 с до и после прохода; + - порог — медиана `p95(проход) / p95(окна)` ≤ 1,5 у `stand`, + `stand-unlimited`, `fast-limited`; + - контраст: `fast-unlimited` (1 CPU без предела) > 1,5 (проба: ×2,2); + - A/A окон вне [1/1,5; 1,5] — «не различимо». +10. **A/A и сравнение меток** (решение 11): A/A — внутри метки (разброс + повторов, окна до и после). Второй метки и `make bench_compare` нет. +11. **Гипотезы H1–H4 и ожидание S4** (решение 12) уточнены по пробе. Они + идут в `REPORT.md` отдельным commit до метки. +12. **Пять тестов отказов** и аргументы hook (решение 14). Красный прогон + — на `7f4e626`. Остановку во время паузы предела проверяет `driver.py + reconcile-signal --pace` → `evidence/reconcile/service.md`. + +#### Вопросы + +Нет. Вопрос 1 раздела `### track2-reconciler` (ответ API на потерянный +оригинал) открыт и касается и класса «другой SHA-256». Ответ меняет ту +же ветку `open_content`, а не решения этого change. diff --git a/openspec/changes/track2-reconcile-cost/.openspec.yaml b/openspec/changes/track2-reconcile-cost/.openspec.yaml new file mode 100644 index 00000000..f56fe139 --- /dev/null +++ b/openspec/changes/track2-reconcile-cost/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-23 diff --git a/openspec/changes/track2-reconcile-cost/design.md b/openspec/changes/track2-reconcile-cost/design.md new file mode 100644 index 00000000..491f5aa2 --- /dev/null +++ b/openspec/changes/track2-reconcile-cost/design.md @@ -0,0 +1,863 @@ +# Design + +## Context + +Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. + +### Код + +Состояние на `7f4e626`: + +- **Сверка** (`AttachmentReconcileService.reconcile`, design change + `track2-reconciler`, решения 3, 4, 7, 8) — одна стратегия: + - страницы ListObjectsV2 по 1000 ключей; + - на страницу одно выражение к БД по `id`; + - множество ключей `seen`, затем keyset строк `ready`; + - зависшие загрузки; + - перепроверка каждого кандидата: выборка в БД и HEAD; + - предел, затем действия. + + Сверка поверхностная: наличие и размер из списка. Байты не читаются. + SHA-256 оригинала лежит в `attachments.sha256` (32 байта), но его никто + не сверяет. «Оригинал вернулся» сравнивает только размер. +- **Предел изменений** (`_act`): отказ решается после перепроверки всех + кандидатов. Замечание S4 verify `track2-reconciler` — `PLAN.md`, раздел + 6. +- **Итог прохода** называет классы, свежие, помеченные и длительность. + Сколько было запросов к S3 и PostgreSQL, не знает никто. +- **Клиент S3** (`ObjectStorage`) счётчиков не ведёт. `open` читает тело + блоками по 64 KiB со сроком на блок. +- **Уборщик**: лимиты рабочего стенда — 0,25 CPU / 256 МБ, пул БД 1, + `pool_pre_ping`. Разовый проход — `docker compose run --rm --no-deps + cleaner reconcile [--apply] [--max-changes N]`. +- **Стенд `bench/`.** S3 запускает только профиль `uploads`. Уборщик + описан в `bench.compose.yml` (интервал сверки 0), но профили его не + запускают. Есть: + - сэмплер `scan` — cgroup всех контейнеров, без сети; + - `resources.py` — окна и агрегаты CPU и памяти; + - сборка образа прежнего commit `build_from` (`git archive`); + - строки k6 на запрос в файл консоли (`k6/failover.js`). + + Скрипты на хосте — только stdlib, приложение не импортируется + (`bench.md`). + +### Пробы (2026-10-23, scratchpad, проект compose `rccost`) + +Стенд пробы: +- тот же `docker-compose.yml` с override без портов и `config.toml`; +- образ рабочего стенда, код `7f4e626`; +- PostgreSQL и S3 на named volumes `rccost_*`, удалены по имени после + пробы; +- у S3 те же аргументы плюс `-metricsPort` — порт метрик шлюза; +- две реплики, LB, уборщик с лимитами рабочего стенда. + +Наполнение мимо API: +- строки — `psql \copy … FROM STDIN` из генератора на stdlib; +- объекты — PUT загрузчиком на botocore образа API ключами пользователя + API; +- класс объекта — по `i mod 400`, по 0,25 % на класс. + +На хосте всё время пробы работали контейнеры `domains-*`, поэтому +задержки шумные. Счётчики точные. После пробы volumes, сети и образы — +как до неё (155 / 17 / 24). + +| Проверка | Результат | +|---|---| +| Наполнение | строки: 10k — 0,25 с, 90k — ~2 с. Объекты 4 KiB: один процесс × 32 потока — 635 PUT/с (S3 0,38 ядра); три процесса × 24 — ~1 750 PUT/с, S3 0,88 ядра — упор в S3 (90k за 52 с). Объекты 1 MiB: 113 PUT/с | +| Batch, dry-run, 0,25 CPU, без фоновой нагрузки | 10k — 3,0 с; 100k — 30,6 / 29,7 / 29,3 с: 0,30 мс на объект при обоих N. Уборщик — 0,24–0,25 ядра (упор в свой лимит CPU), S3 — 0,35–0,43, PostgreSQL — 0,02–0,03. Найдено ровно внесённое (25 и 250 на класс) | +| Память уборщика | ~97 MiB к началу прохода (импорт и модели botocore; старт до прохода — 5–6 с при 0,25 CPU), пик 111,6 MiB на 100k: ~150 Б на ключ множества | +| Метрики шлюза S3 (`SeaweedFS_s3_request_total`) | проход 100k: LIST +101 (100 страниц и проба bucket), GET +750 — HEAD шлюз считает типом GET: 500 × 200 и 250 × 404. Совпало с ожидаемым до запроса | +| PostgreSQL (`pg_stat_database`) | транзакций ≈ 2 × сеансов сверки: `pool_pre_ping` даёт свою | +| «HEAD на строку» (скрипт пробы клиентом и repo проекта в контейнере уборщика, 20k) | выборка строки на объект — 2,67 мс, HEAD на строку — 2,48 мс: ~5,15 мс на объект, в ~17 раз дороже batch. Упор в CPU уборщика (0,62–0,66 мс CPU на вызов) | +| Глубокая (GET и SHA-256, 0,25 CPU) | 4 KiB — 2,5–2,9 мс на объект; 1 MiB — 10,5 мс (95 MiB/с), уборщик 0,25 ядра, S3 0,19 — упор в CPU уборщика, а не в S3 | +| Уборщик 1 CPU | batch 100k — 13,1 с (S3 0,65 ядра: теперь упор в список шлюза); HEAD — 0,69 мс (1 447/с); глубокая 1 MiB — 4,8 мс (208 MiB/с, S3 0,39) | +| CPU S3 на объект | ключ списка — 0,085–0,11 мс; HEAD — 0,25–0,32 мс; GET 4 KiB — ~0,5 мс; GET 1 MiB — 1,9–2,0 мс | +| S4 на текущем коде (100k и ещё 10 000 строк `ready` без объектов) | dry-run — 83,1 с против 29,7 (+53 с, 5,3 мс на кандидата: выборка и HEAD при 0,25 CPU); `--apply` отказал по пределу (10 750 > 100) через 86,1 с, по пути убрав 250 зависших | +| Фоновая нагрузка 50 скачиваний + 50 записей + 50 чтений в секунду | p95 во время batch, HEAD и глубокой (0,25 и 1 CPU) не выше окон без прохода (8 против 10–11 мс) | +| То же, 300 скачиваний/с (реплики ~0,55 ядра, S3 ~0,18, PostgreSQL ~0,14) | окна без прохода — p95 скачиваний 10 и 6 мс. Batch с 1 CPU без предела — 22 мс (×2,2–2,75), запись — 18, чтение — 12. Batch с 0,25 CPU — 9 мс (без эффекта). Ещё одно окно без прохода дало 93 мс — помеха хоста | + +### Что проба меняет в гипотезах `PLAN.md` + +- **Гипотеза 3.** «Упирается в чтение S3» на лимитах рабочего стенда + неверно: глубокую сверку ограничивает CPU уборщика (0,25). S3 занят на + 0,19 ядра. +- **Гипотеза 4.** Эффект зависит от CPU уборщика. Его лимит 0,25 сам + держит нагрузку на S3. Без предела скорости эффект виден, только если у + уборщика больше CPU. Поэтому опыт с 1 CPU — управляемый (решение 10). + +Уточнённые гипотезы — решение 12. + +## Goals / Non-Goals + +**Goals:** + +- Пункт трека 2 «измерить стоимость обхода» (`README.md`). Повторяемая + метка с гипотезами, записанными до неё, результатами и ограничениями. +- Стратегии и глубина — настоящие ветки кода с теми же правилами + безопасности, а не прототипы пробы. +- Предел скорости и ранний отказ по пределу (S4) выбраны по замеру и + проверены меткой. +- Счёт запросов сверки сверяется с независимым счётчиком S3. +- Полная метка — не дольше часа: её снимают на тихом хосте, и основная + сессия на это время останавливает чужие контейнеры. + +**Non-Goals:** + +- Распараллеливание прохода (несколько вызовов S3 одновременно): проход + последовательный, как в `track2-reconciler`. Ускорение не цель, цель — + измерить и ограничить. +- Выборочная глубокая сверка в плановой (решение 5). +- Перенос метрик шлюза S3 в рабочий стенд: порт метрик — только у S3 + профиля сверки (решение 8). +- Сравнение меток командой `make bench_compare` (решение 11). +- `REPORT.md` целиком, чистый clone, PR (этап 7 `PLAN.md`). + +## Decisions + +### 1. Профиль `reconcile`: этапы, ячейки, длительность + +Команды: `make bench_reconcile [RECONCILE_LABEL=…]` (метка `baseline` по +умолчанию) и `make bench_reconcile_quick` (метка `quick-reconcile-<время>`, +в `.gitignore`). Результаты — `evidence/reconcile/<метка>/`, рядом с +evidence `track2-reconciler`, как `evidence/uploads/`. Проход сверки — +разовый уборщик в контейнере, «ячейка» — его вариант на одних данных. + +Полная метка: + +| Этап | Стенд | Набор | Ячейки, по 3 повтора | +|---|---|---|---| +| A | свежий | 1 000 × 1 MiB | `batch`; `deep`; `deep-fast` (уборщик 1 CPU) | +| B | свежий | 10 000 × 4 KiB | `batch`; `head`; `deep` | +| C | тот же, +20 000 | 30 000 × 4 KiB | `batch`; `head` | +| D | тот же, +70 000 | 100 000 × 4 KiB | `batch`; фоновая нагрузка: `stand` (0,25 CPU, предел 2000/с), `stand-unlimited` (0,25 CPU, 0), `fast-unlimited` (1 CPU, 0), `fast-limited` (1 CPU, 2000/с) | +| S4 | свежий | 10 000 чистых × 4 KiB + 1 000, затем ещё 9 000 строк `ready` без объектов | `--apply --max-changes 100`: `before` (образ `7f4e626`) и `after` (checkout), при 1 000 и 10 000 кандидатов | + +Порядок и правила: +- Ячейки без фоновой нагрузки — dry-run без предела скорости + (`--max-objects-per-second 0`): там меряется естественная цена. +- Повторы — кругами: в каждом круге ячейки этапа в перестановке от зерна + (`order_seed`), как у `uploads`. План — в `meta.json` до первого + прохода. +- Dry-run ничего не меняет, поэтому повторы идут на одних данных без + перезаливки. +- `--apply` есть только в S4, где проход отказывает по пределу и тоже + ничего не меняет. Зависших загрузок в наборе S4 нет, поэтому отказ не + трогает и их. + +Ожидаемая длительность (по пробе, с запасом на старт контейнеров ~6 с на +проход; хост тихий): + +| Часть | Время | +|---|---| +| сборка образов checkout и `7f4e626` (кэш слоёв) | ~2 мин | +| A: стенд, 1 GiB объектов, ожидание grace, 9 проходов | ~2,5 мин | +| B: стенд, 10k, 9 проходов (HEAD ~55 с, глубокая ~30 с) | ~6 мин | +| C: +20k, 6 проходов (HEAD ~160 с) | ~10 мин | +| D: +70k, 3 прохода batch и 12 проходов под нагрузкой с окнами по 30 с | ~20 мин | +| S4: стенд, 12 проходов (`before` при 10 000 — ~60 с) | ~6,5 мин | +| **итого** | **~50 мин** (оценка 45–55) | + +Быстрый профиль: один свежий стенд, 2 000 × 4 KiB. +- По одному проходу `batch`, `head` и `deep`. +- Четыре варианта под нагрузкой с окнами по 5 с. +- S4 с 300 кандидатами: `before` и `after`. + +Итого **~6 мин**, из них ~1–1,5 мин — сборка образа `7f4e626` при +первом запуске. + +*Альтернатива:* один свежий стенд на каждое N, как матрица лабы 2. +Отвергнута: 100k пришлось бы наливать трижды (наполнение и ожидание +grace — ~2 мин на этап). Набор только растёт, и классы задаются номером +объекта (решение 2), поэтому этапы B–D сравнимы. *Альтернатива:* HEAD на +100k. Отвергнута: ~515 с на проход, 26 мин на три повтора. HEAD +линеен по построению (вызов на объект), и 10k с 30k это показывают. +*Альтернатива:* глубокая сверка на 100k по 4 KiB. Отвергнута: ~250 с на +проход. Её цена на объект от N не зависит, а цену байтов даёт этап A. + +### 2. Набор данных и доли расхождений + +- **Размеры.** N = 10 000, 30 000, 100 000 объектов по 4 KiB — одна + кривая от N из трёх точек. Отдельно 1 000 объектов по 1 MiB — цена + байтов у глубокой сверки. Цена списка и HEAD от размера объекта не + зависит, а у чтения два слагаемых: ~2,5 мс на вызов и ~8 мс на MiB при + 0,25 CPU (проба). Их и разделяют два размера. +- **Доли.** По 0,25 % от N на класс, 1 % всего: объект без метаданных, + метаданные без объекта, другой размер, зависшая загрузка. Класс — по + `i mod 400` (0, 1, 2, 3), остальные объекты согласованы. Расхождения + разбросаны по всему пространству ключей равномерно, а ожидаемое число + по классам при любом N известно точно. +- **Объект `i`:** + - `id` — UUID v4 из SHA-256 строки `<зерно>:`; + - содержимое — повторённый SHA-256 строки `<зерно>::c`, обрезанный + до размера; + - `Content-Type: image/png`. Сверка формат не проверяет. Скачивание + API тоже: оно сверяет только размер, и синтетические байты фоновой + нагрузке подходят. +- **Строки:** + - чат и владелец — читаемый чат и пользователь фикстуры `prepare.js`; + - SHA-256 — от того же содержимого; + - `created_at` = `updated_at` = время наполнения минус сутки, то есть + старше grace; + - зависшая загрузка — `pending` с тем же временем. +- **Grace проходов** — `CLEANER__PENDING_GRACE_SECONDS=30`. Это больше + границы живой загрузки (17 с), и проверку при старте он проходит. + Объекты старше grace становятся сами: проходы этапа начинаются через + grace + 2 с после последнего PUT. С grace 900 с каждый этап ждал бы + 15 мин. +- **Проверка набора.** Первый dry-run этапа сверяет итог с моделью: + - `listed_objects` равно числу объектов; + - `checked_rows` равно числу строк `ready`; + - `found` по классам равно внесённому. + + Каждый следующий проход сверяет `found` так же. Расхождение — отказ + команды с ячейкой, классом и обоими числами (спек `load-benchmark`, + «Найдено не то, что внесено»). + +*Альтернатива:* N = 10k и 100k (как в `PLAN.md`). Отвергнута: по двум +точкам линейность не отличить от `a + b·N` с изгибом. *Альтернатива:* +N = 1M. Отвергнута: наполнение ~10 мин, проход ~5 мин при 0,25 CPU, +метка — часы. Предел по памяти выводится из наклона (~150 Б на ключ), +решение 12, H1. *Альтернатива:* доля 0 %. Отвергнута: без кандидатов нет +перепроверок, а проверке набора нечего сравнивать. *Альтернатива:* доля +10 %. Отвергнута: перепроверка (10k × 5,3 мс ≈ 53 с на 100k) перекрыла +бы цену обхода (~30 с). Цену перепроверки отдельно меряет S4. +*Альтернатива:* случайные позиции расхождений. Отвергнута: ожидаемые +числа стали бы оценкой, а не точным значением. + +### 3. Наполнение мимо API и граница чёрного ящика + +- **Пользователи и чат** — `k6/prepare.js` через LB, как у остальных + профилей. +- **Метаданные** — оркестратор передаёт CSV в `docker exec -i + mtusi-bench-postgres psql … -c "\copy attachments (…) FROM STDIN"`. + Генерирует строки `bench/reconcile.py` (stdlib), файла CSV нет. Новое + исключение границы: до сих пор оркестратор менял в PostgreSQL только + служебное (обслуживание, планы в откатываемой транзакции). Это данные + стенда, схему он не трогает. +- **Объекты** — загрузчик `bench/fill_objects.py`. Он работает только в + контейнере на образе стенда (`mtusi-messenger:bench`), как + `sampler.sh` — только в своём: + - botocore образа, `src` загрузчик не импортирует; + - каталог `bench/` смонтирован только на чтение, генератор набора — из + `reconcile.py`; + - ключи пользователя API передаются окружением `docker run -e <имя>` + без значения в argv; + - три процесса по 24 потока: упор в S3, ~1 750 PUT/с по пробе. + + Контейнер называется `mtusi-bench-fill` и входит в список остатков + стенда. +- **Проход сверки** — `docker compose run -d --name + mtusi-bench-reconcile- --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 + cleaner reconcile …`, затем `docker wait`, журнал и `docker rm`. + Результат прохода — его собственные JSON-записи «Started cleaner», + «Finished reconcile pass» и «Reconcile changes exceed limit»: это выход + приложения, как ответ HTTP для k6. Вариант `before` — тот же вызов с + override `.work/cleaner-before.compose.yml` (`image: + mtusi-messenger:bench-from`). Тег стенда не меняется, и ошибка не + оставит реплики на чужом образе. +- **Измерение мимо приложения** — по образцу статистики LB: + - метрики шлюза S3 — `docker exec mtusi-bench-s3 wget -qO- + http://127.0.0.1:<порт>/metrics` до и после прохода (решение 8); + - `pg_stat_database` — psql до и после прохода; + - cgroup — сэмплер. +- **Расхождения S4** — строки `ready` без объектов. Их пишет оркестратор + тем же `\copy`. + +*Альтернатива:* наполнение через API. Отвергнута: +- 100k загрузок — минуты под 4 местами загрузки на реплику; +- расхождения всё равно вносятся мимо API; +- содержимое объектов не управляется. + +*Альтернатива:* `weed filer.copy` / HTTP filer изнутри контейнера S3. +Отвергнута: в обход шлюза S3 объекты получили бы не тот путь +метаданных, что у PUT приложения, а файлы пришлось бы сначала создать в +контейнере. *Альтернатива:* загрузчик на хосте. Отвергнута: на хосте — +только stdlib (`bench.md`), подписи SigV4 там нет, а порт S3 стенда на +хост не публикуется. + +### 4. Стратегия «HEAD на строку» + +`reconcile --strategy head` — только разовый проход. Стратегия по +умолчанию (`batch`) не меняется. + +- **S3 → БД.** Те же страницы списка. На каждый ключ — своя выборка + строки: стандартный ключ — по `id`, нестандартный — по `object_key` + (`get_attachments_for_objects` с одним элементом). Здесь + классифицируются только объекты без строки (объект без метаданных, + чужой объект) и свежие объекты. Строку с тем же ключом этот шаг + пропускает: её объект проверит HEAD. +- **БД → S3.** Тот же keyset строк `ready`. На каждую строку своей базы + — HEAD её ключа: + - объекта нет — метаданные без объекта; + - размер другой — другой размер; + - строка помечена, а размер равен — кандидат «оригинал вернулся»; + - иначе — согласовано. + + Свежесть — те же правила. Ключ строки вне префикса — чужой объект без + HEAD, как в `batch`. +- **Без множества `seen`:** память O(страницы), а не O(N). +- Зависшие, перепроверка, предел и действия — общие со стратегией + `batch`. + +Почему те же расхождения. Каждая пара «объект — строка» классифицируется +теми же правилами. `batch` находит «строку без объекта» как «ключа нет +среди увиденных», `head` — как «HEAD ответил 404». На неизменных данных +итог один и тот же. Это проверяет тест отказов «Стратегия HEAD находит +то же», а метка сверяет `found` на каждом проходе. Если между списком и +HEAD объект удалили, `head` найдёт «метаданные без объекта», а `batch` +не найдёт до следующего прохода. Оба исхода безопасны: перепроверка +общая. + +Плановая сверка — всегда `batch`. Стратегия `head` остаётся в коде как +вариант для оператора: проход без памяти на множество, когда N за +пределом памяти уборщика (решение 12, H1 и H2). + +*Альтернатива:* только HEAD на строку, без списка. Отвергнута: объекты +без метаданных без списка не найти. *Альтернатива:* стратегия как +настройка `[reconciler] strategy`. Отвергнута: плановой сверке нужен +только `batch`, а лишняя ручка — путь сломать плановую сверку +конфигурацией. *Альтернатива:* удалить `head` после замера. Отвергнута: +это единственный проход с памятью O(1) от N, его цена измерена и +названа в отчёте. + +### 5. Глубокая сверка по требованию + +`reconcile --deep` — только разовый проход, с любой стратегией. + +- **Что читается.** Каждая строка `ready` без пометки, старше grace, у + которой объект того же размера. В `batch` размер известен из страницы + списка, в `head` вместо HEAD сразу идёт GET. Объект читается + `ObjectStorage.open` блоками по 64 KiB со сроком на блок, SHA-256 + считается потоком (`hashlib`). Память — один блок. +- **Класс `checksum_mismatch`** («другой SHA-256»). С `--apply` — пометка + потерянного оригинала, как у другого размера. Он входит в классы под + пределом. Перепроверка и проверка перед пометкой заново читают объект + и сравнивают SHA-256. Это дорого только для найденных, а их мало. +- **Снятие пометки.** «Оригинал вернулся» теперь требует того же SHA-256 + во всех режимах, не только с `--deep`. Перепроверка и проверка перед + снятием читают объект. Это один-два GET на помеченное вложение с + объектом того же размера — их единицы. Без этого поверхностная сверка + сняла бы пометку, которую поставила глубокая (размер же равен). Кроме + того, оператор мог вернуть не тот файл того же размера, и API отдавал + бы чужие байты. +- **Что видит API.** Скачивание помеченного — 404, метаданные — 200, как + у любого потерянного оригинала (спек `attachments`, «Скачивание + оригинала»). Вопрос преподавателю об ответе на потерянный оригинал + (`PLAN.md`, `### track2-reconciler`, вопрос 1) касается и этого + класса. Ответ «иначе» меняет ту же ветку `open_content`. +- **Плановая сверка глубокой не бывает.** На 100k объектов по 1 MiB + глубокий проход — ~17 мин при 0,25 CPU (~10,5 мс на объект), то есть + CPU уборщика на всё время прохода. Порча внутри SeaweedFS (ошибка CRC + иглы тома) даёт ошибку чтения, а не другие байты. Глубокая сверка + ловит другое: объект перезаписали мимо API байтами того же размера. + +*Альтернатива:* выборочная глубокая сверка в плановой (K объектов за +проход). Отвергнута: +- случайная выборка ловит редкий класс с вероятностью K/N за проход; +- детерминированное покрытие требует хранить, что уже проверено, — это + миграция; +- плановая сверка стала бы непредсказуемо дороже. + +По требованию оператор запускает её, когда есть причина: после +инцидента или восстановления. *Альтернатива:* ETag S3 вместо чтения. +Отвергнута: ETag шлюза — MD5 того, что шлюз получил. Перезаписанный +объект получает новый ETag, а сравнивать его не с чем: MD5 в метаданных +нет, а его колонка — миграция. *Альтернатива:* сумма SHA-256 от S3 +(`x-amz-checksum-sha256`). Отвергнута: поддержку в SeaweedFS 4.48 никто +не проверял, и её пришлось бы передавать при каждой загрузке. + +### 6. Предел скорости `[reconciler] max_objects_per_second` + +- **Что считается.** Объекты S3, которые проход затронул: + - каждый ключ страницы списка, в том числе проба bucket (`MaxKeys=1`); + - каждый HEAD, GET и DELETE. + + Обращения к PostgreSQL не считаются: у сверки они дешёвые, PostgreSQL + за проход — 0,02–0,1 ядра по пробе. +- **Как.** Перед каждым вызовом S3 сверка проверяет сигнал (как + сейчас) и темп. Если затронуто больше, чем `R × (время с начала + прохода)`, она ждёт, пока средняя скорость не опустится до R. Ждёт + кусками по 0,2 с с проверкой сигнала: остановка не ждёт паузы (спек + `graceful-shutdown`). Счёт берётся из счётчиков клиента S3 (решение + 8), поэтому DELETE уборки зависших загрузок тоже считаются. +- **Где задаётся.** `[reconciler] max_objects_per_second` — float ≥ 0, по + умолчанию 2000, 0 — без предела. Разовая подмена — + `RECONCILER__MAX_OBJECTS_PER_SECOND`. У разового прохода — ещё + `--max-objects-per-second R`, у `make reconcile` — `RATE=R`. Плановая + сверка берёт значение из настроек. +- **Почему 2000.** CPU шлюза на ключ списка — 0,085–0,11 мс (проба). + 2000 ключей в секунду — ~0,2 ядра S3 из 1. Естественная скорость + `batch` на лимите стенда — ~6 000 ключей/с в шаге списка и ~3 400/с в + среднем за проход. Предел удлиняет проход 100k с ~30 с до ~65 с: шаг + списка — не меньше 50 с, шаг строк без S3 — как был. На рабочем стенде + (2–3 тыс. объектов) — ~1,5 с в час. Зато граница + нагрузки на S3 не зависит от того, сколько CPU дали уборщику. Проба + показала: с 1 CPU без предела p95 скачиваний вырос в 2,2 раза. Метка + проверяет это H4 (решение 10). +- **HEAD и глубокая сверка.** Объект у них дороже для S3: HEAD ~0,3 мс, + GET 4 KiB ~0,5 мс, GET 1 MiB ~2 мс CPU шлюза. При 2000/с шлюз + перегрузили бы, но на 0,25 CPU уборщик даёт только ~400 вызовов в + секунду. Предел для них на быстром уборщике — `REPORT.md` по замеру + метки: CPU S3 на объект каждой ячейки. + +*Альтернатива:* пауза между страницами (`page_pause_seconds`). +Отвергнута: она не ограничивает HEAD и GET, и у каждой стратегии значила +бы разное. *Альтернатива:* запросов S3 в секунду. Отвергнута: страница +списка — один запрос на 1000 ключей, а HEAD — запрос на объект. Для +`batch` такой предел не ограничивал бы ничего. *Альтернатива:* байтов в +секунду. Отвергнута как единственная ручка: обход без чтения она не +ограничивает. Как вторая ручка — лишняя: глубокая сверка по требованию, +и её темп задаёт тот же аргумент. *Альтернатива:* доля времени S3 (пауза +пропорционально длительности вызова). Отвергнута: длительность вызова +включает разбор XML в самом уборщике, а время прохода по такой ручке +заранее не посчитать. *Альтернатива:* только лимит CPU контейнера. +Отвергнута: он неявный, меняется вместе с лимитом и не виден в +настройках сверки. Опыт `fast-unlimited` показывает, что будет без +предела. + +### 7. Отказ по пределу без лишних перепроверок (S4) + +Выбран вариант «порог „подтверждено больше предела“ и отдельный счётчик +в итоге» из `PLAN.md`, раздел 6. Он действует у любого `--apply`, не +только у плановой сверки. + +- В `_recheck_all` при `apply` сверка считает подтверждённых классов под + пределом (`LIMITED_KINDS` и `checksum_mismatch`). Как только их больше + `max_changes`, она прекращает перепроверять кандидатов этих классов, а + каждого оставшегося считает в `unchecked`. Зависшие загрузки и чужие + объекты перепроверки не требуют и проходят как раньше. +- `_act` отказывает по тому же условию. Запись `error` «Reconcile + changes exceed limit» называет `changes` = `max_changes + 1`, + `max_changes` и `unchecked`. Итог — `unchecked`, код 3. Уборка + зависших — как раньше. +- Dry-run перепроверяет всех и называет каждое расхождение. После + отказа оператор запускает dry-run (`docker.md`: «сначала `make + reconcile`»). + +Почему так. Отказ решён, как только подтверждённых `max_changes + 1`: +остальные кандидаты исход не меняют, и их перепроверка — только цена. +Проба: +5,3 мс на кандидата при 0,25 CPU. При 10 000 кандидатов — +53 с +к проходу. В сценарии, ради которого предел есть, — пустая база при +живом bucket, 100k объектов — это ~9 мин каждой плановой сверки, и всё +это время уборка зависших ждёт. После правки — `max_changes + 1` +перепроверок, ~0,5 с. Отказ при этом обоснован всегда: подтверждено +больше предела, а не «кандидатов много». + +Цена — два инварианта ослаблены только для отказавшего `--apply`: +- ошибка называет нижнюю границу числа изменений; +- неперепроверенные кандидаты не названы поимённо, только числом. + +Спек `storage-consistency` уточнён в обоих местах. + +*Альтернатива:* решать отказ по числу кандидатов до перепроверки +(вариант «перепроверка после решения о пределе»). Отвергнута: кандидаты +не подтверждены. Гонка с загрузками или неполный список дали бы +ложный отказ, и сверка не исправила бы и то, что исправить можно. +*Альтернатива:* ранний отказ только у плановой сверки. Отвергнута: один +и тот же `--apply` вёл бы себя по-разному. Разовый `--apply` платил бы +полную цену, хотя полный отчёт у оператора и так есть — dry-run. +*Альтернатива:* оставить как есть. Отвергнута по замеру выше. + +Замер — ячейки S4 (решение 1): `before` на образе `7f4e626` +(`Profile.reconcile_before`, `git archive`, проверка commit до стенда, +как у `uploads_before`) и `after`, оба `--apply --max-changes 100`, у +`after` — `--max-objects-per-second 0`. У прежнего кода предела скорости +нет, и сравнение должно быть честным. + +### 8. Счёт запросов S3 и PostgreSQL + +- **Внутренний счёт — в итоге прохода.** + - `ObjectStorage` ведёт счётчики попыток вызовов по операциям (`list`, + `head`, `get`, `delete`, `put`), ключей страниц списка и прочитанных + байтов. `stats()` отдаёт неизменяемый снимок. + - Сверка берёт снимки в начале и в конце прохода. Счёт на стороне + клиента ловит и DELETE уборки зависших, и пробу bucket. + - Сеансы PostgreSQL сверка считает обёрткой своего `db_scope`. Ту же + обёртку получает её `AttachmentCleanupService`: шаги уборки входят в + счёт. + - Итог прохода называет `s3_requests` по операциям, `storage_objects` + (затронутые объекты S3 — решение 6), `read_bytes`, `db_sessions` и + `phase_ms` — длительность шагов `list`, `rows`, `stale`, `recheck`, + `act`. +- **Внешний счёт в метке.** + - S3: `SeaweedFS_s3_request_total` по типам до и после прохода. + `-metricsPort` слушает `-metricsIp`, а по умолчанию это `-ip.bind`, + то есть `127.0.0.1`. Проба: порт 9327 слушает только loopback, из + сети стенда недоступен. + - Флаг есть только у S3 профиля сверки. Override + `.work/s3-metrics.compose.yml` генерирует `run.py`: берёт `command` + сервиса `s3` из `docker compose config` того же стенда и дописывает + флаг. Списка аргументов в двух местах нет, расхождения с рабочим + стендом тоже. Аргументы — в паспорте. + - Шлюз считает HEAD типом GET. Поэтому сверка счётчиков — `LIST = + list`, `GET = head + get`, `DELETE = delete`. + - В ячейках без фоновой нагрузки равенство обязательно. Иначе — + пометка `count_mismatch`: строка остаётся, а вывод H1–H2 называет + пометку. + - PostgreSQL: `pg_stat_database` (транзакции, `tup_returned`, + `tup_fetched`, `blks_hit`, `blks_read`) до и после прохода. + Равенства с сеансами нет: `pool_pre_ping` даёт свою транзакцию, а + проверки LB `SELECT 1` раз в секунду. Это справочный счёт рядом с + CPU PostgreSQL. + +*Альтернатива:* только внутренний счёт. Отвергнута: гипотеза 2 — о +числе запросов, и её подтверждение не должно держаться на самоотчёте +испытуемого. *Альтернатива:* только внешний. Отвергнута: в ячейках с +фоновой нагрузкой метрики смешивают API и сверку. Оператору нужна цена +прохода и на рабочем стенде, где порта метрик нет. *Альтернатива:* +`pg_stat_statements`. Отвергнута: +- нужен `shared_preload_libraries` и `CREATE EXTENSION` в базе стенда — + это смена настроек PostgreSQL для всех профилей и объект в схеме, + видимый приложению; +- выражения `get_attachment` у API и сверки одинаковые. + +*Альтернатива:* журнал аудита шлюза. Отвергнута: SeaweedFS пишет его во +fluentd, а это ещё один сервис. *Альтернатива:* порт метрик и у рабочего +стенда. Отложена: это изменение S3 рабочего стенда ради замера, хотя +`make s3_check` порт на loopback и принял бы. Место ему — лаба 6, сбор +метрик. + +### 9. Ресурсы прохода + +- Сэмплер `scan` (`sampler.sh`) работает весь этап с интервалом 0,5 с + (`Profile.reconcile_sample_interval_s`). Проход 10k длится ~3 с, и + интервала в 1 с мало. +- **Окно прохода** — по часам ВМ: `[t_end − duration_ms, t_end]`, где + `t_end` — время записи «Finished reconcile pass». +- **CPU за окно.** S3, PostgreSQL, реплик, LB и уборщика — агрегаты + `resources.py` по окну. Уборщик — по полному `id` контейнера прохода: + роль `cleaner` по метке сервиса compose. +- **Память уборщика.** В начале прохода — выборка у начала окна, пик — + наибольшая выборка за жизнь контейнера. Прирост — их разность: это + множество ключей и кандидаты. + +*Альтернатива:* `memory.peak` cgroup и сэмплер `peak` (как у `uploads`). +Отвергнута: cgroup разового контейнера исчезает с его выходом, и +прочитать пик после прохода нельзя, а выборки раз в 0,5 с проход +длиной в секунды хватает. *Альтернатива:* `ru_maxrss` процесса в итоге +прохода. Отвергнута: у долгоживущего сервиса это пик за всю жизнь, а не +за проход. Внешний замер тоже не должен держаться на самоотчёте. + +### 10. Фоновая нагрузка и порог H4 + +- **Сценарий** `bench/k6/background.js`, открытая модель, три сценария + `constant-arrival-rate`: + - скачивания — 300/с. Вложения — выборка 5 000 согласованных объектов + набора от зерна, `.work/downloads.json` от `run.py`. Скачивает + читатель фикстуры: он владелец и участник чата набора; + - запись сообщений — 50/с, в чат записи; + - чтение первой страницы истории чата записи — 50/с. + + Строка на запрос — `bg,,<отправка мс>,<длительность мс>,<статус>` + в файл консоли k6, как `fo,…` у `failover`. Число строк сверяется с + итерациями из итога k6. Нагрузка по пробе: реплики ~0,55 ядра каждая + (около половины потолка, как у `failover`), S3 ~0,18, PostgreSQL ~0,14. + Загрузок в фоне нет: они меняли бы набор во время проходов. +- **Окна.** Один запуск k6 на весь блок H4 этапа D. Перед первым + проходом и после каждого — 30 с без прохода. Окно «до» прохода i — + тихое окно перед стартом его контейнера, окно «после» — тихое окно + после выхода. Старт контейнера (импорт, ~5 с) в окна не входит: S3 и + API он не трогает. +- **Мера.** По каждому сценарию и окну — p50, p95, p99, число ответов и + ошибок. Влияние прохода — `r = p95(окно прохода) / p95(окна до и после + вместе)`. Шум — `a = p95(до) / p95(после)` (A/A). +- **Предел скорости в вариантах:** `stand` и `fast-limited` — 2000/с + (по умолчанию), `stand-unlimited` и `fast-unlimited` — 0. +- **Порог — до метки, в commit гипотез:** + - **держится:** медиана `r` по трём повторам ≤ 1,5 для каждого из трёх + сценариев. Это у вариантов `stand`, `stand-unlimited` и + `fast-limited`; + - **контраст:** у `fast-unlimited` медиана `r` скачиваний > 1,5. Иначе + метод эффекта не видит, и H4 — «не проверена», а не «подтверждена»; + - **шум:** медиана `a` по сценарию вне [1/1,5; 1,5] — вывод «не + различимо на этом хосте»; + - ответы 5xx фоновой нагрузки — пометка прохода, при них H4 не + подтверждается. +- Дополнительно, без вердикта, — p95 окна шага списка (`phase_ms.list` + от начала прохода). В этом шаге у `batch` нагружен S3. + +*Альтернатива:* фон 50 + 50 + 50/с. Отвергнута: проба не увидела эффекта +даже у HEAD и глубокой с 1 CPU. В окнах прохода p95 был даже ниже, чем +без него, и порог мерил бы шум. *Альтернатива:* поиск интенсивности +до насыщения S3 (как R* трека 1). Отвергнута: минуты на каждый этап и +другой вопрос — ёмкость, а не влияние прохода. *Альтернатива:* +абсолютный порог (+20 мс). Отвергнута: при p95 ~10 мс даже двукратный +рост (22 мс в пробе) остался бы под порогом. *Альтернатива:* H4 с HEAD и +глубокой. Отвергнута для метки: это разовые операции оператора, а их +цену для S3 дают ячейки без нагрузки (CPU S3 на объект, решение 6). +Глубокий проход 100k идёт ~250 с, три повтора — ещё 13 мин. + +### 11. A/A и сравнение меток + +- Все сравнения — внутри одной метки, на одних данных, в одной сессии + хоста (`bench.md`: «Варианты сравниваются внутри одной метки»): + стратегии, глубина, CPU уборщика, предел, `before` / `after`. +- Шум ячеек без нагрузки — разброс трёх повторов. Отличие засчитывается, + только если разбросы не пересекаются (правило `bench_compare`). + Ожидаемые отличия — в разы (17× у HEAD), а разброс повторов batch по + пробе — 3 %. +- Шум H4 — A/A окон до и после (решение 10). +- **Второй метки A/A нет.** Она удвоила бы время тихого хоста (~50 мин) + и сравнивала бы разные сессии хоста — это хуже, чем окна внутри одной. +- **`make bench_compare` метки сверки не сравнивает.** Он читает + `evidence/bench/`, а метки сверки лежат в `evidence/reconcile/`: + команда отказывает с «not found» и кодом 2. Методики разные, и так и + должно быть. Быстрая метка с полной не сравнивается — у них разные N. + +*Альтернатива:* отдельная метка `reconcile-aa`. Отвергнута выше. +*Альтернатива:* научить `compare.py` меткам сверки. Отвергнута: «до» и +«после» здесь одна метка (ячейки S4), а других сравнений change не +требует. + +### 12. Гипотезы (текст для commit гипотез) + +Числа — из проб (Context), а не из метки. Вывод по метке пишется после +неё. Если он расходится с гипотезой, гипотеза названа опровергнутой. + +- **H1 — линейность (`batch`, dry-run, 0,25 CPU, без предела):** + - цена на объект (`duration_ms / N`) при 10k, 30k и 100k различается + не больше чем на 20 % (проба: 0,30 мс при 10k и 100k); + - S3: ⌈N / 1000⌉ страниц списка, одна проба bucket и HEAD только у + кандидатов (0,75 % N в наборе метки); + - сеансов PostgreSQL — по одному на страницу списка, на страницу строк + `ready` и на выборку зависших, плюс по одному на кандидата, кроме + зависших; + - прирост памяти уборщика за проход — не больше 300 Б на ключ (проба: + ~150). Отсюда предел `batch` при 256 МБ — порядка миллиона ключей. +- **H2 — `batch` против HEAD на строку (10k и 30k):** + - на обход `batch` делает ≈ 3 запроса на 1000 объектов (страница + списка, выборка страницы, страница строк), HEAD — ≈ 2 на объект + (выборка на объект и HEAD на строку). Перепроверка кандидатов у + стратегий общая. С ней при 1 % расхождений — ~18 против ~2 000 + запросов к S3 и PostgreSQL на 1000 объектов; + - время на объект у HEAD больше в 10 раз и более (проба: ~17×); + - память HEAD-прохода от N не растёт: прирост ≤ 5 MiB при 10k и 30k. +- **H3 — поверхностная против глубокой:** + - глубокая на 4 KiB дороже `batch` по времени на объект не меньше чем + в 5 раз (проба: ~9×), с GET на каждую строку; + - на 1 MiB время на объект больше, чем на 4 KiB, на 5 мс и более на + MiB (проба: ~8 мс при 0,25 CPU); + - на лимите стенда предел глубокой — CPU уборщика (≥ 90 % лимита), а + не S3 (≤ 50 % ядра); + - с 1 CPU у уборщика она быстрее не меньше чем в 1,5 раза. + + Вывод, который проверяется: глубокая — по требованию, не в плановой. +- **H4 — влияние на фоновую нагрузку (100k, `batch`)** — порог решения + 10: `stand`, `stand-unlimited` и `fast-limited` — медиана `r` ≤ 1,5 по + всем трём сценариям; `fast-unlimited` — `r` скачиваний > 1,5 (проба: + 2,2–2,75). +- **S4 — цена отказа по пределу (ожидание, не гипотеза трека).** Проход + без кандидатов — ячейка `batch` этапа B, тот же N = 10k: + - `before` длиннее него примерно на D × 5 мс: +5 с при 1 000 и +50 с + при 10 000; + - `after` — не больше чем на 1 с, запросов HEAD — не больше + `max_changes + 1`; + - отказ, код 3 и неизменность данных — у обоих. + +Гипотеза 5 («ничего подтверждённого не удалено») закрыта стрессом +`track2-reconciler` (`evidence/reconcile/stress.md`). Новые ветки +покрывают тесты отказов (решение 14). + +### 13. Файлы метки, сводка, графики + +- `meta.json`: + - профиль целиком (поля `reconcile_*`), план, образы, `before_commit`; + - аргументы S3 и порт метрик; + - лимиты контейнеров; + - модель набора по этапам: N, размеры, доли, зерно; + - фоновая нагрузка; + - `host_state`, `other_containers`, `docker.kernel`. +- `passes.csv` — строка на проход: + - этап, ячейка, вариант, повтор, стратегия, глубина, CPU уборщика, + предел; + - N объектов и строк, внесено и найдено по классам; + - длительность и шаги, цена на объект; + - запросы S3 сверки и по метрикам, сеансы и счётчики PostgreSQL, + байты, `unchecked`; + - CPU уборщика, S3, PostgreSQL, реплик и LB за окно, память уборщика; + - код выхода и пометки. + + Новые столбцы — только в конец (`bench.md`). +- `windows.csv` — строка на проход × окно × сценарий: границы, ответы, + ошибки, p50, p95, p99. +- `summary.md`: + - паспорт; + - таблицы по этапам (медиана и min–max ячейки); + - S4 до и после; + - строки H1–H4 и S4 с числами и вердиктом. +- SVG — `plots.Svg` из `bench/plots.py`, stdlib: + - `cost-by-n.svg` — время прохода от N у `batch` и `head`, точки + глубокой; + - `requests-by-n.svg` — запросы S3 и сеансы PostgreSQL от N, + логарифмическая шкала; + - `background-p95.svg` — `r` по вариантам и сценариям с линией порога + и полосой A/A. +- `raw/<проход>-cleaner.json` — записи «Started», «Finished» и + «exceed limit». Записи «Found» — только числом, их до тысячи на проход. +- `raw/h4-k6.json` — итог k6 блока H4. +- Разбор и сводка — `bench/reconcile.py` без docker, `--selftest` на + синтетических журналах, метриках и строках k6, как у `uploads.py`. + +`make bench_plots` не меняется: он строит графики серий трека 1 по +нескольким меткам. + +### 14. Тесты отказов и evidence + +**Hook** (`fault_hook.py`): `reconcile dry-run|apply [<предел>] +[--strategy head] [--deep] [--max-objects-per-second R]`. Аргументы +проверяются по списку и передаются команде как есть. Тело `put-object` +— любые байты, в том числе того же размера. Новых действий нет. + +**Тесты** (маркер `fault`, G = 20 с — grace стенда отказов): + +| Тест | Сценарии `storage-consistency` | Ход | +|---|---|---| +| `test_reconcile_head_strategy_same_findings` | «Стратегия HEAD находит то же» | расхождения как в `…_finds_and_fixes` → ждать G + 1 → dry-run `batch` и `head`: свои находки по классам и ключам равны, коды равны, у `head` `s3_requests.head` и `db_sessions` больше | +| `test_reconcile_deep_checksum` | «Другой SHA-256 находит глубокая сверка» | A в сообщении → `put-object` A другими байтами того же размера, `age-row` → ждать G + 1 → dry-run: A нет; `--deep`: A — `checksum_mismatch`, `read_bytes` > 0, код 3, `lost-ids` прежние → `--deep --apply`: A помечено, байты — 404, метаданные — 200 | +| `test_reconcile_restore_needs_same_bytes` | «Вернулся другой объект того же размера», «Оригинал вернулся» | R помечено (`age-row`, `delete-object`, apply) → `put-object` других байтов того же размера → ждать G + 1 → apply: R в `lost-ids`, 404 → `put-object` исходных байтов → ждать G + 1 → apply: пометки нет, 200 с тем же SHA-256 | +| `test_reconcile_rate_limit` | «Скорость прохода ограничена», «Без ограничения скорости» | dry-run с R = max(5, ⌈объектов / 4⌉) и с 0: при R `duration_ms` ≥ 1000 × `storage_objects` / R × 0,95, без предела проход короче; находки и код одинаковы | +| `test_reconcile_limit_stops_rechecks` | «Отказ по пределу без лишних перепроверок» | 6 вложений: `age-row`, `delete-object` → apply с пределом 2: код 3, `changes` = 3, `unchecked` ≥ 3, ни одно не помечено → dry-run: все 6 названы → apply 100: все помечены | + +`test_reconcile_change_limit` не меняется: при L1–L3 и пределе 2 на +третьем подтверждённом `changes` = 3, как он и ждёт (`≥ 3`). + +**Красный прогон до кода** на `7f4e626`: новые аргументы — ошибка +argparse (код 2), `test_reconcile_restore_needs_same_bytes` — пометка +снята по размеру. Падают все пять. Это доказательство, что тесты +проверяют новое поведение (`evidence/tests/failure-checks.md`). + +**Сверка покрытия.** Новые сценарии `storage-consistency` +синхронизируются в основные спеки в apply, как в прежних changes: +`spec_coverage.py` читает только `openspec/specs/`. Purpose спека +`storage-consistency` правится руками: «стоимость обхода описывает +change» → описано в нём. + +**Evidence:** +- `evidence/reconcile/service.md`, новый раздел «Остановка во время + паузы предела скорости». `driver.py reconcile-signal --pace`: тот же + драйвер, вместо `pause s3` — `--max-objects-per-second 1`, `docker + stop` через 2 с после «Started cleaner». Ожидание: код 1, + `interrupted_by: stop`, остановка ≤ 1 с после сигнала. Спек + `graceful-shutdown` в сверку покрытия не входит. +- `evidence/tests/` — полный `make failure_checks` и красный прогон, + `make test_isolated`. +- Метка `evidence/reconcile/baseline/`. + +### 15. Журнал и настройки + +- «Started cleaner»: `reconcile_max_objects_per_second`. У разового + прохода — ещё `reconcile_strategy` и `reconcile_deep`. +- «Finished reconcile pass» — поля решения 8 и `strategy`, `deep`, + `max_objects_per_second`, `unchecked`. Ключи `s3_requests` и + `phase_ms` — постоянные строки, значения — числа. SHA-256 объектов в + записях нет (дельта `service-logging`). +- «Reconcile changes exceed limit»: плюс `unchecked`. +- `ReconcileFinding.CHECKSUM_MISMATCH = "checksum_mismatch"`; + `ReconcileStrategy` (`batch`, `head`) — `StrEnum` в + `enums/attachment.py`. +- `ReconcilePassDTO` — новые поля в конце со значениями по умолчанию, + отображения — `MappingProxyType` (`dto.md`). +- `config_example.toml` — строка `max_objects_per_second`. Правило + `settings.md` — поле и обоснование 2000. +- `make reconcile [APPLY=1] [MAX_CHANGES=N] [STRATEGY=head] [DEEP=1] + [RATE=R]`. + +### 16. Точки commit в apply + +Как во всех changes лабы. Commit делает основная сессия после +подтверждения (`bench.md`, «Измеренное состояние — commit»): + +1. **Код:** тесты и hook, красный прогон, сверка, клиент, настройки, + CLI, стенд `bench/` (профили, загрузчик, сценарий k6, разбор, + `--selftest`), `make bench_reconcile_quick` на дереве, правила и + AGENTS.md, синхронизация спеков, полный `make failure_checks`, `make + lint`. +2. **Гипотезы:** раздел `REPORT.md` с H1–H4 и ожиданием S4 (решение 12) + и методикой — отдельным commit раньше метки. Спек `load-benchmark`, + «Гипотезы сверки до прогонов». +3. **Метка:** `make bench_reconcile` с закоммиченного кода, на тихом + хосте: основная сессия останавливает `domains-*` на ~50 мин, затем + поднимает. Каталог метки — отдельным commit. +4. **Evidence и отчёт:** + - `evidence/reconcile/service.md` (пауза предела); + - `evidence/tests/`; + - выводы по метке и ограничения в `REPORT.md`, строки таблицы + доказательств; + - `PLAN.md`. + +## Risks / Trade-offs + +- **[Предел 2000/с удлиняет плановый проход вдвое]** → на 100k с ~30 до + ~65 с, на рабочем стенде — ~1,5 с в час. Уборка зависших ждёт прохода, + grace — 900 с. Метка проверяет, нужен ли предел на лимитах стенда + (`stand-unlimited`). Если нет, `REPORT.md` скажет, что он страхует + быстрый уборщик. +- **[Порог H4 против шума задержек хоста]** → в пробе на шумном хосте + тихие окна различались в 1,67 раза, и одно дало 93 мс. Метка + снимается на тихом хосте, решает медиана трёх повторов. A/A окон до и + после каждого прохода делает вывод «не различимо», если шум больше + порога. Контраст `fast-unlimited` проверяет, что метод эффект видит. +- **[Подмена гипотез пробой]** → гипотезы уточнены по пробе на шумном + хосте до метки (как в `upload-memory`). Метка — проверка на тихом + хосте. Расхождение с ней пишется опровержением, а не правкой + гипотезы. +- **[Счёт сверки — самоотчёт испытуемого]** → в ячейках без нагрузки он + сверяется с метриками шлюза (решение 8). Проба: совпало до запроса. +- **[Порт метрик S3 только в профиле сверки]** → это отличие аргументов + S3 от рабочего стенда. Оно в спеке `load-benchmark` и в паспорте, как + `auto_explain` у PostgreSQL. На путь запросов метрики не влияют. +- **[Проход `head` и глубокий занимают CPU уборщика на минуты]** → это + разовые операции оператора. Время на объект в метке и рекомендация + предела — в `REPORT.md`. Уборщик стенда (сервис) на время разового + прохода не останавливается: это другой контейнер. +- **[Синтетические объекты]** → 4 KiB и 1 MiB вместо настоящих PNG. Цена + списка и HEAD от размера не зависит, а у глубокой — два слагаемых по + двум размерам. Ограничение — в `REPORT.md`. +- **[Глубокая сверка помечает «чужие байты» потерянными]** → скачивание + становится 404 вместо отдачи не тех байтов. Если это законная замена + оператором, оператор возвращает исходные байты, и пометка снимается. + Вопрос преподавателю об ответе на потерянный оригинал касается и этого + класса. +- **[Снятие пометки читает объект]** → один-два GET на помеченное + вложение с объектом того же размера в каждом проходе. Таких единицы. +- **[Ранний отказ называет нижнюю границу изменений]** → ошибка + называет `changes` = предел + 1 и `unchecked`. Точное число даёт + dry-run, и порядок действий оператора не меняется. +- **[Наполнение мимо API пишет в данные стенда]** → новое исключение + границы чёрного ящика, только у профиля сверки, только на свежем + стенде `mtusi-bench`. Схему оно не меняет. Описано в `bench.md` и в + спеке. +- **[Метка ~50 мин требует тихого хоста]** → основная сессия + останавливает `domains-*` и поднимает после. Быстрый профиль (~6 мин) + проверяет стенд и на шумном хосте. Выводы опираются на точные счётчики, + байты, время и p95 метки на тихом хосте. + +## Migration Plan + +1. Тесты отказов и hook — раньше кода. Красный прогон на `7f4e626`. +2. Enum, DTO, настройка `max_objects_per_second`, счётчики клиента S3. +3. Сервис сверки: темп, ранний отказ, глубокая, `head`, стоимость в + итоге. CLI уборщика, `make reconcile`, `config_example.toml`. +4. Синхронизация дельт в основные спеки, Purpose `storage-consistency`. + Полный `make failure_checks`. +5. Стенд `bench/`: override уборщика, `reconcile.py` с `--selftest`, + `fill_objects.py`, `k6/background.js`, профили в `run.py`, цели + `Makefile`, `.gitignore`. `make bench_reconcile_quick` на дереве и + регресс быстрых профилей. +6. Драйвер `reconcile-signal --pace`, правила, AGENTS.md, `PLAN.md`. +7. Commit кода, затем commit гипотез, метка, commit метки, evidence и + отчёт (решение 16). + +Рабочий стенд: новый код уборщика — `docker compose up -d --no-deps +cleaner` или `make run_docker`, решает основная сессия. Миграции нет. Новый +уборщик с прежними репликами совместим: пометку `checksum_mismatch` +прежние реплики читают как любой `lost_at` — 404. Прежний уборщик с новыми +репликами — как до change. + +Откат — прежний образ уборщика. Пометки остаются в `lost_at`. + +## Open Questions + +Нет. Вопрос преподавателю об ответе на потерянный оригинал (`PLAN.md`, +`### track2-reconciler`, вопрос 1) открыт и касается класса «другой +SHA-256». Ответ меняет ту же ветку `open_content`, а не этот change. diff --git a/openspec/changes/track2-reconcile-cost/proposal.md b/openspec/changes/track2-reconcile-cost/proposal.md new file mode 100644 index 00000000..64e0f12e --- /dev/null +++ b/openspec/changes/track2-reconcile-cost/proposal.md @@ -0,0 +1,127 @@ +# Proposal + +## Why + +Уровень «5», трек 2 «Согласованность двух хранилищ» (`README.md`) +требует ещё и «гипотезу, повторяемую методику, результаты и ограничения; +измерить стоимость обхода». Сверка bucket и БД уже есть (change +`track2-reconciler`): одна стратегия, поверхностная проверка, без +ограничения скорости. Сколько она стоит при росте числа объектов и +мешает ли рабочему трафику — пока не измерено. Гипотезы 1–4 трека +(`PLAN.md`, «Трек 5») не проверены. + +Verify `track2-reconciler` передал сюда замечание S4. При массовом +расхождении `--apply` перепроверяет каждого кандидата и только потом +отказывает по пределу. Проба этого change: 10 000 лишних кандидатов +добавляют к проходу ~53 с, всё это время уборка зависших загрузок ждёт. + +## What Changes + +- **Стратегия «HEAD на строку»** — `reconcile --strategy head`, только + разовый проход. Для каждого объекта списка — своя выборка строки, для + каждой строки `ready` — HEAD её объекта, без множества ключей в памяти. + Расхождения и правила безопасности те же, что у стратегии по умолчанию + (страница списка и одно выражение к БД на страницу). Плановая сверка + остаётся на стратегии по умолчанию. +- **Глубокая сверка по требованию** — `reconcile --deep`. Сверка читает + объект и сравнивает его SHA-256 с метаданными. Новый класс «другой + SHA-256»: с `--apply` такой оригинал помечается потерянным, как при + другом размере. Плановая сверка глубокой не бывает. Пометку + «оригинал вернулся» сверка снимает, только если у объекта и тот же + размер, и тот же SHA-256. Раньше хватало размера. +- **Ограничение скорости** — `[reconciler] max_objects_per_second`. По + умолчанию 2000, 0 — без ограничения. Это предел того, сколько объектов + S3 проход затрагивает в секунду: ключи страниц списка, HEAD, GET и + DELETE. Разовый проход принимает предел аргументом. Пауза ограничения + прерывается сигналом остановки. +- **Отказ по пределу без лишних перепроверок (S4).** С `--apply` сверка + перестаёт перепроверять кандидатов классов под пределом, как только + подтверждённых больше `max_changes`. Отказ к этому моменту уже решён. + Итог называет, сколько кандидатов не перепроверено. Dry-run по-прежнему + перепроверяет и называет каждое расхождение. +- **Итог прохода называет стоимость:** + - стратегию, глубину и предел скорости; + - запросы S3 по операциям и прочитанные байты — по счётчикам клиента + S3; + - сеансы с PostgreSQL; + - длительность по шагам прохода. +- **Профиль `reconcile` стенда `bench/`** — `make bench_reconcile` + (~50 мин) и `make bench_reconcile_quick` (~6 мин), результаты — в + `evidence/reconcile/<метка>/`. Что в нём: + - наполнение мимо API: метаданные — запись в PostgreSQL стенда, + объекты — прямой PUT в S3 стенда; + - N = 10k / 30k / 100k объектов по 4 KiB и 1k объектов по 1 MiB, + расхождения — по 0,25 % каждого класса; + - стратегии, глубина, лимит CPU уборщика и предел скорости; + - фоновая нагрузка k6 с заранее заданным порогом p95; + - цена отказа по пределу на образе до change и после; + - три повтора, A/A внутри метки; + - счётчики запросов сверки сверяются с метриками шлюза S3; + - сэмплер, сводка с выводами по гипотезам 1–4 и графики. +- **Тесты отказов**: те же расхождения у стратегии HEAD, другой SHA-256, + возврат объекта с другим содержимым, предел скорости, отказ по пределу + без лишних перепроверок. Hook передаёт сверке новые аргументы. +- **Отчёт:** гипотезы — отдельным commit до метки, выводы и ограничения + — после неё. Строки таблицы доказательств уровня «5». + +Не входит: +- сводка всего отчёта, чистый clone и PR (этап 7 `PLAN.md`); +- остальные записи `KNOWN_ISSUES.md`; +- выборочная глубокая сверка в плановой (отвергнута, design); +- presigned upload, превью и 202 (лаба 5). + +Гипотезу 5 («ничего подтверждённого не удалено») закрыл стресс change +`track2-reconciler`. Новые ветки сверки покрывают тесты отказов этого +change. + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +- `storage-consistency`: стратегия HEAD, глубокая сверка и класс «другой + SHA-256», ограничение скорости, отказ по пределу без лишних + перепроверок, снятие пометки только при том же SHA-256, плановая + сверка — стратегия по умолчанию, поверхностная, с пределом скорости + из настроек. +- `service-configuration`: `[reconciler] max_objects_per_second`. +- `service-logging`: стоимость прохода в итоге сверки, новые поля + записей о старте и о пределе изменений. +- `graceful-shutdown`: остановка уборщика во время паузы ограничения + скорости. +- `student-tests`: hook запускает сверку со стратегией, глубиной и + пределом скорости. +- `load-benchmark`: профиль сверки, S3 и уборщик в его стенде, стоимость + сверки в отчёте. + +## Impact + +- Код: + - `src/core/services/attachment_reconcile.py` — стратегия HEAD, + глубокая сверка, темп, ранний отказ по пределу, стоимость в итоге; + - `src/infra/s3/client.py` — счётчики вызовов по операциям, ключей + списка и прочитанных байт; + - `src/cleaner/main.py` — аргументы `--strategy`, `--deep`, + `--max-objects-per-second`; + - `src/config/settings.py` — поле `max_objects_per_second`; + - DTO и enum. + + Миграции нет: SHA-256 и `lost_at` уже в схеме. +- Стенд `bench/`: + - `run.py` — профили `reconcile` и `reconcile_quick`; + - новые `reconcile.py` (разбор, сводка, графики, `--selftest`), + `fill_objects.py` (загрузчик объектов в контейнере на образе + приложения) и `k6/background.js`; + - `bench.compose.yml` — лимиты уборщика без swap. +- Прочее: `Makefile` (`bench_reconcile`, `bench_reconcile_quick`, + аргументы `make reconcile`), `config_example.toml`, `.gitignore`. +- Тесты: `student-tests/test_failures.py`, `fault_hook.py`. +- Документы: скилл `run-mtusi-messenger` (`reconcile-signal --pace`). + Правила `bench.md`, `service-layer.md`, `infra.md`, `settings.md`, + `logging.md`, `run-modes.md`, `student-tests.md`, `dto.md`. Ещё + AGENTS.md, `REPORT.md` и `PLAN.md`. +- Регресс: `make failure_checks` дольше на ~1–2 мин. Быстрые профили + `bench/` и `make test_isolated` — без изменений. diff --git a/openspec/changes/track2-reconcile-cost/specs/graceful-shutdown/spec.md b/openspec/changes/track2-reconcile-cost/specs/graceful-shutdown/spec.md new file mode 100644 index 00000000..8d2d897b --- /dev/null +++ b/openspec/changes/track2-reconcile-cost/specs/graceful-shutdown/spec.md @@ -0,0 +1,46 @@ +## MODIFIED Requirements + +### Requirement: Остановка уборщика + +По SIGTERM уборщик незавершённых загрузок (capability +`storage-consistency`) SHALL довести текущий шаг уборки загрузки до +конца или до отката и больше новых шагов не начинать. Загрузка, +остановленная между шагами, остаётся в состоянии, из которого её +доводит следующий проход. + +Так же — во время сверки bucket и БД. Текущий вызов S3 или шаг с +PostgreSQL доводится до конца или до отката. Новые страницы списка и +новые действия не начинаются. Ожидание из-за предела скорости сверки +(capability `storage-consistency`, «Скорость сверки») сигнал прерывает +сразу: остановка не ждёт конца паузы. Сверку, прерванную сигналом, +доводит следующий проход, как прерванную отказом. + +Затем сервис уборщика 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, а + в журнале — итог сверки с причиной прерывания «остановка» и запись об + остановке уборщика + +#### Scenario: docker stop во время паузы предела скорости + +- **WHEN** `docker stop` выполняется для разового прохода сверки, пока + тот ждёт из-за предела скорости +- **THEN** контейнер останавливается не позже чем через секунду после + сигнала, код выхода 1, а в журнале — итог сверки с причиной прерывания + «остановка» и запись об остановке уборщика diff --git a/openspec/changes/track2-reconcile-cost/specs/load-benchmark/spec.md b/openspec/changes/track2-reconcile-cost/specs/load-benchmark/spec.md new file mode 100644 index 00000000..73da8e77 --- /dev/null +++ b/openspec/changes/track2-reconcile-cost/specs/load-benchmark/spec.md @@ -0,0 +1,274 @@ +## MODIFIED Requirements + +### Requirement: Фиксированный стенд + +Стенд SHALL состоять из балансировщика (LB), реплик приложения, +PostgreSQL и Valkey. В профилях загрузок и сверки к ним SHALL +добавляться S3 с его bootstrap, а в профиле сверки — ещё разовые проходы +процесса уборщика. Число реплик SHALL задаваться методикой, по умолчанию +одна. Приложение SHALL запускаться в контейнерах из образа, собранного +из текущего checkout тем же `Dockerfile`. Исключения — профиль +поочерёдной замены и варианты «до» профилей загрузок и сверки. Они берут +образ commit, заданного методикой: образ собирается тем же `Dockerfile` +из файлов этого commit без изменения рабочего дерева. Профиль замены +заканчивается на образе текущего checkout. LB SHALL +запускаться из того же образа и с той же конфигурацией, что у рабочего +стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у +рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL +получает те же настройки образа плюс модуль записи планов, выключенный +вне снятия плана. S3 SHALL запускаться из того же образа и с теми же +аргументами сервера, что у рабочего стенда, а bucket и пользователей +создаёт тот же bootstrap. В профиле сверки к аргументам S3 добавляется +порт метрик шлюза: он слушает только loopback контейнера S3, и по нему +оркестратор считает запросы к S3. В сериях трека 1 предел соединений +PostgreSQL (`max_connections`) — параметр конфигурации серии, по +умолчанию 100, как у образа. Схема БД SHALL применяться миграциями до +наполнения. + +Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека +1 — во всех прогонах одной конфигурации: +- у каждой реплики приложения — лимит CPU и памяти без swap, заданный + методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по + конфигурации); +- у LB, PostgreSQL, Valkey, S3 и уборщика — свои лимиты CPU и памяти без + swap, заданные методикой; в серии трека 1 они одинаковы во всех + конфигурациях; у уборщика в управляемом опыте профиля сверки — другой + лимит CPU, тоже заданный методикой; +- у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без + swap, заданный методикой; в остальных профилях генератор без лимита. + +Буфер приёма сокетов реплик приложения SHALL быть ограничен так же, как +у рабочего стенда (`load-balancing`, «Загрузки через балансировщик»). +Значение SHALL записываться в паспорт. + +Healthcheck образа приложения SHALL быть отключён: готовность реплик +проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки +приложения и хранилищ SHALL браться из методики стенда, а не из `.env` +и `config.toml` рабочего стенда. Пароли хранилищ и секреты S3 SHALL +генерироваться на прогон. Генератор нагрузки SHALL работать в той же +docker-сети и обращаться к приложению через LB по имени сервиса, минуя +проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит +готовыми все реплики. + +#### Scenario: Лимиты в паспорте + +- **WHEN** прогон завершён +- **THEN** паспорт стенда содержит число реплик и лимиты CPU и памяти + реплики приложения, LB, PostgreSQL и Valkey, прочитанные у запущенных + контейнеров, и они одинаковы для всех размеров + +#### Scenario: Лимиты конфигурации серии + +- **WHEN** серия трека 1 завершена +- **THEN** паспорт по каждой конфигурации содержит число реплик, лимиты + CPU и памяти каждого контейнера стенда и генератора и предел + соединений PostgreSQL, прочитанные у запущенных контейнеров, и они + одинаковы во всех повторах конфигурации + +#### Scenario: Нехватка памяти + +- **WHEN** процесс приложения превысил лимит памяти и был убит +- **THEN** прогон помечен как проваленный из-за OOM, а не записан как + обычный результат + +#### Scenario: Настройки рабочего стенда не влияют + +- **WHEN** `.env` и `config.toml` рабочего стенда изменены или + отсутствуют +- **THEN** стенд запускается с теми же настройками приложения и + хранилищ, а окружение приложения в паспорте то же + +#### Scenario: Схема до наполнения + +- **WHEN** начинается наполнение размера +- **THEN** миграции применены до последней ревизии, и приложение + отвечает готовностью + +#### Scenario: Одна реплика за балансировщиком + +- **WHEN** профиль лабы 2 (`full`, `quick`, `restore`, + `restore_quick`) запущен с одной репликой +- **THEN** все запросы генератора проходят через LB, прогон завершается + с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и + разделы, что раньше + +#### Scenario: Образ прежнего commit + +- **WHEN** запускается профиль поочерёдной замены +- **THEN** реплики стартуют на образе commit из методики, схема — на + его последней ревизии, рабочее дерево не меняется, а commit и образы + до и после записаны в паспорт + +#### Scenario: S3 в профиле загрузок + +- **WHEN** запускается профиль загрузок +- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами + и лимитами, bootstrap завершился успешно, а образ и лимиты S3 и + ограничение буфера приёма реплики записаны в паспорт + +#### Scenario: S3 и уборщик в профиле сверки + +- **WHEN** запускается профиль сверки +- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами + и портом метрик только на loopback своего контейнера, bootstrap + завершился успешно, а аргументы S3, образы и лимиты S3 и уборщика + записаны в паспорт + +## ADDED Requirements + +### Requirement: Профиль сверки + +Команда `make bench_reconcile` (метка `RECONCILE_LABEL`, по умолчанию +`baseline`) SHALL на свежем стенде мерить стоимость прохода сверки +bucket и БД (capability `storage-consistency`). Команда `make +bench_reconcile_quick` — то же на малом наборе и одним повтором, метка +`quick-reconcile-…`, в git не идёт. Результаты SHALL сохраняться в +`evidence/reconcile/<метка>/`. Занятая метка SHALL давать отказ до +запуска стенда. + +Стенд — LB, две реплики, PostgreSQL, Valkey и S3 с лимитами рабочего +стенда (требование «Фиксированный стенд»). Проход сверки — разовый +процесс уборщика из образа приложения с лимитами рабочего стенда +(0,25 CPU, 256 МБ без swap), в управляемом опыте — с 1 CPU. Grace +проходов — короткий, заданный методикой, но больше границы живой +загрузки (capability `service-configuration`, «Параметры уборщика»). + +Данные — синтетические вложения одного чата: +- 10 000, 30 000 и 100 000 объектов по 4 KiB — один набор, который + растёт между этапами; +- 1 000 объектов по 1 MiB — на отдельном стенде, для цены чтения байтов. + +Расхождения SHALL вноситься при наполнении, по 0,25 % от числа объектов +каждого класса: объект без метаданных, метаданные без объекта, другой +размер, зависшая загрузка. Класс объекта SHALL определяться его номером, +а содержимое — номером и зерном методики. + +Граница чёрного ящика: +- пользователи и чат создаются через API; +- метаданные вложений оркестратор пишет в PostgreSQL стенда, объекты — + прямой записью в S3 стенда ключами пользователя API; +- проход сверки — процесс уборщика из образа приложения, его результат — + журнал этого процесса; +- фоновая нагрузка — генератор по HTTP через LB; +- сверх этого оркестратор читает счётчики cgroup контейнеров, метрики + шлюза S3 на loopback его контейнера и счётчики PostgreSQL. + +Приложение оркестратор не импортирует. + +Проходы: +- без фоновой нагрузки и без предела скорости: + - стратегия по умолчанию на всех размерах набора; + - стратегия HEAD на 10 000 и 30 000 объектов; + - глубокая сверка на 10 000 объектов по 4 KiB и на объектах по 1 MiB; + - глубокая сверка с уборщиком 1 CPU на объектах по 1 MiB; +- с фоновой нагрузкой, на 100 000 объектов, стратегия по умолчанию: + - лимит CPU рабочего стенда с пределом скорости по умолчанию и без + предела; + - 1 CPU без предела и с пределом по умолчанию. + + Фоновая нагрузка идёт с постоянной интенсивностью, заданной методикой: + скачивания вложений набора, запись сообщений и чтение истории. До и + после каждого прохода — окна без прохода; +- отказ по пределу: `--apply` с пределом изменений 100, когда + кандидатов 1 000 и 10 000, — на образе до change и на образе текущего + checkout. + +Каждый проход повторяется три раза, повторы одной ячейки не идут подряд. +Варианты сравниваются внутри одной метки, на одних данных и в одной +сессии хоста. Шум — разброс повторов ячейки, а у проходов с фоновой +нагрузкой ещё отношение p95 окон до и после прохода (A/A). + +Для каждого прохода SHALL сохраняться: +- итог прохода из журнала уборщика — длительность и длительность шагов, + просмотренные объекты и строки, найденные расхождения по классам, + затронутые объекты S3, запросы к S3 по операциям, прочитанные байты, + сеансы с PostgreSQL, неперепроверенные кандидаты, код выхода; +- запросы к S3 по метрикам шлюза и счётчики PostgreSQL за проход; +- CPU уборщика, S3 и PostgreSQL за проход; +- память уборщика в начале прохода и её пик; +- у проходов с фоновой нагрузкой — по каждому сценарию в окне прохода и + в окнах до и после: число ответов, ошибки, p50, p95 и p99. + +Достоверность: +- найденные расхождения SHALL по каждому классу совпадать с внесёнными. + Иначе команда завершается ненулевым кодом: замер на неверных данных — + не результат; +- в проходах без фоновой нагрузки запросы к S3 по счётчикам сверки SHALL + совпадать с метриками шлюза, иначе проход помечается; +- ответ 5xx фоновой нагрузки — пометка прохода. + +В паспорте метки SHALL быть: +- лимиты и образы, в том числе commit варианта «до»; +- аргументы S3; +- размеры набора, размеры объектов, доли расхождений и зерно; +- grace проходов и предел скорости по умолчанию; +- фоновая нагрузка; +- версия ядра ВМ; +- состояние хоста и посторонние контейнеры. + +Сводка SHALL давать по каждой ячейке медиану и разброс повторов, вывод +по каждой гипотезе (требование «Стоимость сверки в отчёте») и графики: +длительность и запросы прохода от размера набора по стратегиям, p95 +фоновой нагрузки по вариантам. + +#### Scenario: Полный профиль сверки + +- **WHEN** выполнен `make bench_reconcile` +- **THEN** в `evidence/reconcile/<метка>/` есть паспорт, таблица проходов + со всеми ячейками по три повтора, таблица окон фоновой нагрузки, + сводка с выводами по гипотезам и графики, код выхода 0 + +#### Scenario: Быстрый профиль сверки + +- **WHEN** выполнен `make bench_reconcile_quick` +- **THEN** за несколько минут проходят все виды проходов на малом наборе + по одному повтору, код выхода 0, каталог метки в git не попадает + +#### Scenario: Найдено не то, что внесено + +- **WHEN** проход нашёл в каком-то классе не столько расхождений, + сколько внесено +- **THEN** команда завершается ненулевым кодом, называет класс, ячейку и + оба числа и удаляет стенд + +#### Scenario: Счётчики сверки и метрики S3 + +- **WHEN** завершён проход без фоновой нагрузки +- **THEN** в строке прохода запросы к S3 по счётчикам сверки равны + запросам по метрикам шлюза, а при различии строка помечена + +### Requirement: Стоимость сверки в отчёте + +`REPORT.md` SHALL содержать по профилю сверки: +- гипотезы и ожидание, записанные и зафиксированные commit до первого + прохода метки: + - о линейности прохода; + - о цене стратегии HEAD; + - о цене глубокой сверки; + - о влиянии на фоновую нагрузку с порогом p95; + - ожидаемую цену отказа по пределу; +- методику: стенд, лимиты, данные и граница наполнения, ячейки, фоновую + нагрузку, повторы и A/A; +- таблицы результатов метки по ячейкам: + - длительность и цена на объект; + - запросы к S3 и PostgreSQL, байты, CPU и память; + - p95 фоновой нагрузки по вариантам; + - цена отказа по пределу до и после change; +- выводы по каждой гипотезе, обоснование предела скорости по умолчанию + и рекомендации для стратегии HEAD и глубокой сверки; +- ограничения: один хост, ВМ Docker Desktop, генератор на том же хосте, + одна нода S3, синтетические объекты двух размеров. + +Числа в отчёт SHALL переноситься из сводки метки, а не пересчитываться +вручную. + +#### Scenario: Гипотезы сверки до прогонов + +- **WHEN** проверяющий смотрит историю `REPORT.md` и каталога метки +- **THEN** commit с гипотезами раньше commit с результатами метки + +#### Scenario: Выводы по метке сверки + +- **WHEN** проверяющий открывает раздел стоимости сверки в `REPORT.md` +- **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки + метки, а числа совпадают со сводкой diff --git a/openspec/changes/track2-reconcile-cost/specs/service-configuration/spec.md b/openspec/changes/track2-reconcile-cost/specs/service-configuration/spec.md new file mode 100644 index 00000000..09507819 --- /dev/null +++ b/openspec/changes/track2-reconcile-cost/specs/service-configuration/spec.md @@ -0,0 +1,44 @@ +## MODIFIED Requirements + +### Requirement: Параметры сверки + +Параметры сверки bucket и БД (capability `storage-consistency`) SHALL +задаваться в секции `[reconciler]`: +- `interval_seconds` — пауза между плановыми сверками процесса + уборщика, по умолчанию 3600; 0 — без плановой сверки; +- `page_size` — сколько ключей сверка берёт одной страницей списка S3 + и сколько строк одним запросом к PostgreSQL, по умолчанию 1000, не + больше 1000; +- `max_changes` — предел изменений за проход, по умолчанию 100; +- `max_objects_per_second` — предел скорости прохода: сколько объектов + S3 он затрагивает в секунду (capability `storage-consistency`, + «Скорость сверки»), по умолчанию 2000; 0 — без ограничения. + +`interval_seconds` и `max_objects_per_second` 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 и предел скорости 2000 объектов в + секунду + +#### Scenario: Неверный параметр сверки + +- **WHEN** уборщик запускается с `RECONCILER__PAGE_SIZE=5000`, + `RECONCILER__MAX_CHANGES=0`, `RECONCILER__INTERVAL_SECONDS=-1` или + `RECONCILER__MAX_OBJECTS_PER_SECOND=-1` +- **THEN** уборщик не стартует, в журнале — ошибка проверки настроек с + именем поля diff --git a/openspec/changes/track2-reconcile-cost/specs/service-logging/spec.md b/openspec/changes/track2-reconcile-cost/specs/service-logging/spec.md new file mode 100644 index 00000000..93f23dce --- /dev/null +++ b/openspec/changes/track2-reconcile-cost/specs/service-logging/spec.md @@ -0,0 +1,62 @@ +## MODIFIED Requirements + +### Requirement: Журнал сверки + +Сверка bucket и БД (capability `storage-consistency`) SHALL писать в +журнал процесса уборщика JSON-записи в формате этой capability, в каждой +— `instance_id` процесса. Записи: +- запись о старте уборщика дополнительно называет интервал сверки, + размер страницы, предел изменений и предел скорости, а у разового + прохода — ещё стратегию обхода и глубину; +- каждое найденное расхождение — класс, ключ объекта, `id` вложения, + если он известен, возраст, размеры объекта и метаданных, если они + разные. Уровень `warning`, если расхождение осталось, и `info`, если + проход с `--apply` его исправил, с названием действия; +- итог прохода — режим, стратегия, глубина, предел скорости, сколько + объектов и строк просмотрено, сколько найдено и исправлено по классам, + сколько свежих и уже помеченных, сколько кандидатов не перепроверено, + длительность и причина прерывания. Ещё итог называет стоимость + прохода: сколько объектов S3 он затронул, запросы к S3 по операциям + (список, запрос метаданных, чтение, удаление), сколько байтов объектов + прочитано, сколько было сеансов с PostgreSQL и длительность каждого + шага прохода. Уровень `info`, если расхождений не осталось, иначе + `warning`; +- превышение предела изменений — `error` с пределом, числом + подтверждённых изменений и числом кандидатов, которых проход не + перепроверял; +- отказ S3 или PostgreSQL — `warning`, непредвиденная ошибка — `error` с + traceback. + +Если расхождений за проход больше тысячи, отдельными записями SHALL +писаться только первые, а итог SHALL называть, сколько осталось без +записи. Скачивание потерянного оригинала реплика API SHALL писать +записью уровня `info` с `id` вложения и ключом объекта, а не `error`. +Записи сверки MUST NOT содержать ключи доступа и секреты S3, ключ +подписи, подписи запросов, `filename` вложений, байты объектов и их +SHA-256. + +#### Scenario: Журнал разового прохода + +- **WHEN** сверка находит объект без метаданных и метаданные без + объекта, а затем исправляет их с `--apply` +- **THEN** результат такой: + - в журнале dry-run — две записи `warning` с классом, ключом и + возрастом и итог `warning`; + - в журнале прохода с `--apply` — две записи `info` с действием и + итог `info`; + - секретов S3 и `filename` в журнале нет + +#### Scenario: Предел изменений в журнале + +- **WHEN** сверка с `--apply` отказывается исправлять из-за предела +- **THEN** в журнале запись `error` с пределом, числом подтверждённых + изменений и числом неперепроверенных кандидатов, а итог прохода — + `warning` + +#### Scenario: Стоимость прохода в итоге + +- **WHEN** выполняется разовая сверка с `--strategy head` и `--deep` +- **THEN** итог называет эту стратегию, глубину и предел скорости, + затронутые объекты S3, запросы к S3 по операциям, прочитанные байты, + сеансы с PostgreSQL и длительность каждого шага, а секретов S3, + `filename` и SHA-256 объектов в журнале нет diff --git a/openspec/changes/track2-reconcile-cost/specs/storage-consistency/spec.md b/openspec/changes/track2-reconcile-cost/specs/storage-consistency/spec.md new file mode 100644 index 00000000..5c9a4ea5 --- /dev/null +++ b/openspec/changes/track2-reconcile-cost/specs/storage-consistency/spec.md @@ -0,0 +1,369 @@ +## MODIFIED Requirements + +### Requirement: Сверка bucket и БД + +Сверка SHALL сравнивать объекты вложений в bucket — ключи с префиксом +`<имя базы>/attachments/` — с метаданными вложений той же базы в +PostgreSQL и находить расхождения семи классов: +- **объект без метаданных** — объект с ключом вида + `<база>/attachments//original`, на который не ссылается ни одна + строка и для `id` которого строки нет; +- **метаданные без объекта** — вложение `ready`, объекта по ключу из его + метаданных в bucket нет; +- **другой размер** — вложение `ready`, размер объекта не равен + `size_bytes`; +- **другой SHA-256** — вложение `ready`, размер объекта равен + `size_bytes`, а SHA-256 его содержимого не равен SHA-256 из + метаданных. Этот класс ищет только глубокая сверка; +- **зависшая загрузка** — вложение в статусе «загружается» старше grace, + то же, что убирает уборщик (требование «Уборщик незавершённых + загрузок»); +- **оригинал вернулся** — оригинал вложения помечен потерянным + (требование «Потерянный оригинал»), а объект снова есть с тем же + размером и тем же SHA-256; +- **чужой объект** — то, что сверка не меняет и оставляет оператору: + - объект под префиксом вложений, ключа такого вида API не пишет; + - объект с ключом вида `/original`, у строки которого другой ключ + или на который ссылается строка другого `id`; + - ключ вне префикса вложений своей базы в метаданных вложения: объект + по такому ключу сверка не читает. + +Сверку SHALL выполнять процесс уборщика, а не реплики API: разовым +проходом (`make reconcile` или команда сверки в контейнере уборщика) и +плановым (требование «Плановая сверка»). Разовый проход по умолчанию +SHALL ничего не менять (dry-run). С `--apply` он SHALL исправлять: +- объект без метаданных — удалить объект; +- метаданные без объекта, другой размер и другой SHA-256 — пометить + оригинал вложения потерянным; +- зависшую загрузку — убрать тем же порядком, что уборщик; +- вернувшийся оригинал — снять пометку. + +Чужой объект сверка MUST NOT удалять, а вложение, метаданные которого +ведут к нему, — помечать или убирать: чужой объект попадает только в +отчёт. + +Разовый проход SHALL принимать стратегию обхода: +- по умолчанию — страницы списка объектов и одно обращение к PostgreSQL + на страницу. Ключи списка сверка запоминает, а строки `ready` + сравнивает с ними; +- `--strategy head` — для каждого объекта списка отдельное обращение к + PostgreSQL, для каждой строки `ready` — запрос метаданных её объекта в + S3. Ключей списка сверка не запоминает. + +Обе стратегии SHALL находить на одних данных одни и те же расхождения +тех же классов и подчиняться одним правилам безопасности (требование +«Безопасность сверки»). + +По умолчанию сверка поверхностная: наличие и размер объекта, байты она +не читает. С `--deep` разовый проход SHALL ещё читать каждый объект +вложения `ready` того же размера, которому больше grace, и сравнивать +SHA-256 его содержимого с метаданными. Плановая сверка глубокой не +бывает (требование «Плановая сверка»). + +Отчёт SHALL называть по каждому расхождению класс, ключ объекта, `id` +вложения, если он известен, и возраст. Исключение — кандидаты, которых +проход с `--apply` не перепроверял после отказа по пределу (требование +«Безопасность сверки»): итог называет их число. Итог прохода SHALL +называть: +- стратегию, глубину и предел скорости (требование «Скорость сверки»); +- сколько объектов и строк просмотрено; +- сколько расхождений найдено и исправлено по классам; +- сколько объектов и строк пропущено как свежие; +- сколько вложений уже помечены потерянными; +- сколько кандидатов не перепроверено; +- стоимость прохода: сколько объектов S3 он затронул, запросы к S3 по + операциям, сколько байтов объектов прочитано, сколько было сеансов с + PostgreSQL и сколько длился каждый шаг прохода. + +После успешного исправления повторный проход 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, если расхождений в нём нет + +#### Scenario: Стратегия HEAD находит то же + +- **WHEN** в стенде те же расхождения, что в сценарии «Расхождения с + обеих сторон найдены», и выполняются сверка без `--apply` со + стратегией по умолчанию и с `--strategy head` +- **THEN** оба отчёта называют одни и те же расхождения тех же классов с + теми же ключами, коды выхода равны, а итог стратегии HEAD называет + больше запросов к S3 и сеансов с PostgreSQL + +#### Scenario: Другой SHA-256 находит глубокая сверка + +- **WHEN** объект готового вложения перезаписан мимо API байтами того же + размера, вложению и объекту больше grace, и выполняется сверка без + `--apply` — сначала без `--deep`, затем с `--deep` +- **THEN** поверхностная сверка это вложение расхождением не считает, а + глубокая называет его классом «другой SHA-256», и её итог называет + прочитанные байты; код выхода 3, а в PostgreSQL и в bucket ничего не + изменилось +- **AND** сверка с `--deep --apply` помечает оригинал потерянным: + скачивание — 404, метаданные — 200 + +### Requirement: Безопасность сверки + +Сверка MUST NOT удалять: +- метаданные вложений, кроме уборки зависшей загрузки; +- объект, на который ссылаются метаданные, в любом статусе; +- объект с ключом вида `/original`, если строка этого `id` есть. + +Вложение, на которое ссылается сообщение, MUST NOT терять из-за сверки +ни метаданные, ни объект, ни ссылку в истории. Если его оригинал +потерян, сверка его только помечает. + +Свежее сверка MUST NOT трогать и не считает расхождением: +- объект, записанный или изменённый в S3 меньше grace назад; +- вложение, метаданные которого записаны или переведены в `ready` меньше + grace назад. + +Grace — тот же, что у уборщика (capability `service-configuration`, +«Параметры уборщика»). + +Каждое расхождение SHALL перепроверяться в PostgreSQL и в S3 +непосредственно перед действием: +- объект без метаданных — строки с этим ключом или `id` по-прежнему + нет, объект на месте и старше grace; +- метаданные без объекта и другой размер — вложение по-прежнему `ready` + с тем же ключом, а объекта по ключу нет или его размер другой; +- другой SHA-256 — вложение по-прежнему `ready` с тем же ключом, объект + того же размера, а SHA-256 заново прочитанного содержимого другой; +- вернувшийся оригинал — пометка на месте, объект того же размера и + того же SHA-256 заново прочитанного содержимого. + +Не подтвердилось — действие не выполняется. Отсутствие объекта MUST NOT +считаться подтверждённым, пока не проверено, что bucket на месте. Иначе +удалённый bucket выглядел бы как потеря всех оригиналов. + +Предел изменений: если за проход нужно удалить объекты, пометить +оригиналы или снять пометки больше чем у `[reconciler] max_changes` +вложений, сверка с `--apply` MUST NOT выполнять ни одно из этих +изменений. Как только подтверждённых таких изменений больше предела, она +SHALL перестать перепроверять остальных кандидатов этих классов: отказ +уже решён, а каждая перепроверка — обращения к PostgreSQL и S3, пока +уборка зависших загрузок ждёт. Она пишет ошибку с пределом и числом +подтверждённых изменений, которое больше предела, и завершается кодом +3. Итог называет, сколько кандидатов не перепроверено. Сверка без +`--apply` перепроверяет каждого кандидата. Разовый проход 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** расхождений, которые сверка исправила бы, вдвое больше + предела, и выполняется сверка с `--apply` +- **THEN** ошибка называет предел и число подтверждённых изменений — на + одно больше предела, итог называет остальных кандидатов + неперепроверенными, ни одно вложение не помечено, код выхода 3 +- **AND** сверка без `--apply` называет каждое из этих расхождений + +#### Scenario: Предел не останавливает уборку зависших + +- **WHEN** загрузка оборвалась между записью объекта и фиксацией `ready` + больше grace назад, расхождений, которые сверка исправила бы, больше + предела, и выполняется сверка с `--apply` +- **THEN** код выхода 3, ни одно вложение не помечено, а зависшей + загрузки нет — ни метаданных, ни объекта + +#### Scenario: Объект, на который ссылается строка, не удаляется + +- **WHEN** всё это старше grace, и выполняется сверка с `--apply`: + - у готового вложения X в метаданных другой ключ под префиксом + вложений, объекта по нему нет, а объект `/original` на месте; + - готовое вложение Y ссылается на ключ `/original`, строки Z нет, и + объекты `/original` и `/original` на месте +- **THEN** результат такой: + - все три объекта на месте, отчёт называет их чужими, код выхода 3; + - X помечено потерянным: объекта по его ключу нет; + - Y не помечено: объект по его ключу есть + +#### Scenario: Ключ вне префикса вложений не трогается + +- **WHEN** у готового вложения и у зависшей загрузки старше grace в + метаданных ключ вне префикса вложений своей базы, и выполняется сверка + с `--apply` +- **THEN** отчёт называет оба чужими, код выхода 3, вложение не помечено, + а метаданные зависшей загрузки и объекты обоих под префиксом вложений + на месте + +#### Scenario: Сверка под нагрузкой + +- **WHEN** выполняются все условия: + - участники дольше grace загружают вложения и отправляют сообщения с + ними; + - в это время сверка с `--apply` повторяется раз в несколько секунд; + - в стенде есть внесённые расхождения +- **THEN** внесённые расхождения исправлены, каждое вложение, загрузка + которого ответила 201, скачивается с тем же SHA-256, а каждое + сообщение отдаёт свои `attachment_ids` + +### Requirement: Потерянный оригинал + +Если сверка подтвердила, что объекта готового вложения нет, его размер +другой или — у глубокой сверки — SHA-256 его содержимого другой, она +SHALL пометить оригинал вложения потерянным и записать время пометки в +метаданные. Сверка не удаляет ни метаданные, ни ссылки сообщений, ни +объект другого размера или другого содержимого. Байты сверка не +восстанавливает: их нет нигде. Что видит API для помеченного вложения — +capability `attachments`, «Скачивание оригинала». + +Пометка MUST NOT менять поля вложения в ответах API, в том числе +`status` и `updated_at`. Пометку SHALL снимать сверка с `--apply`, когда +объект по ключу вложения снова есть, его размер равен `size_bytes`, а +SHA-256 содержимого — SHA-256 из метаданных. Чтобы это проверить, сверка +читает такой объект и без `--deep`. Объект того же размера с другим +содержимым пометку MUST NOT снимать. + +#### Scenario: Оригинал вернулся + +- **WHEN** оригинал вложения помечен потерянным, затем те же байты + записаны в bucket под его ключом, и выполняется сверка с `--apply` +- **THEN** пометка снята, байты вложения скачиваются — 200 с тем же + SHA-256, а следующий проход не находит расхождений по этому вложению + +#### Scenario: Вернулся другой объект того же размера + +- **WHEN** оригинал вложения помечен потерянным, затем под его ключом + записаны другие байты того же размера, и выполняется сверка с + `--apply` +- **THEN** пометка на месте, скачивание — 404, а отчёт не называет это + вложение вернувшимся +- **AND** после записи тех же байтов, что были загружены, сверка с + `--apply` снимает пометку + +### Requirement: Плановая сверка + +Процесс уборщика SHALL сам выполнять сверку с исправлением, без +разового прохода: +- при старте; +- затем не реже чем раз в `[reconciler] interval_seconds`; +- с пределом изменений и пределом скорости из настроек; +- стратегией по умолчанию и без глубокой сверки. + +Значение 0 выключает плановую сверку. Плановая и разовая сверки — один +и тот же проход с теми же правилами безопасности. + +Ограничение называется в `REPORT.md`. Пока идёт проход сверки, уборка +зависших загрузок ждёт его конца. Объект без метаданных на стенде живёт +не дольше суммы grace, интервала сверки и прохода. С пределом скорости +по умолчанию проход длится не меньше секунды на каждые 2000 затронутых +объектов S3 (требование «Скорость сверки»). + +#### Scenario: Плановая сверка без команды + +- **WHEN** у готового вложения старше grace удалён объект, а уборщик + работает с коротким интервалом сверки +- **THEN** не позже интервала с запасом вложение помечено потерянным + без разового прохода, а в журнале уборщика есть итог сверки + +## ADDED Requirements + +### Requirement: Скорость сверки + +Проход сверки SHALL в среднем от своего начала затрагивать не больше +`[reconciler] max_objects_per_second` объектов S3 в секунду. Одним +объектом считаются каждый ключ страницы списка, запрос метаданных +объекта, чтение и удаление объекта. Обгоняя предел, проход ждёт, и +ожидание MUST NOT задерживать остановку по сигналу (capability +`graceful-shutdown`, «Остановка уборщика»). Значение 0 — без +ограничения. + +Разовый проход SHALL принимать предел аргументом, плановая сверка берёт +его из настроек. Обращения к PostgreSQL предел не ограничивает. +Найденные расхождения, исправления, правила безопасности и код выхода +от предела MUST NOT зависеть. + +Как выбран предел по умолчанию и какой предел нужен стратегии HEAD и +глубокой сверке, SHALL быть описано в `REPORT.md` по замеру профиля +сверки (capability `load-benchmark`, «Профиль сверки»). + +#### Scenario: Скорость прохода ограничена + +- **WHEN** выполняется сверка без `--apply` с пределом скорости, при + котором проход затрагивает объектов S3 на несколько секунд +- **THEN** проход длится не меньше, чем число затронутых объектов S3 из + итога, делённое на предел, а отчёт называет те же расхождения и код + выхода тот же, что у прохода без предела + +#### Scenario: Без ограничения скорости + +- **WHEN** тот же проход выполняется с пределом 0 +- **THEN** он не ждёт: проход короче, чем с пределом, а итог называет + предел 0 diff --git a/openspec/changes/track2-reconcile-cost/specs/student-tests/spec.md b/openspec/changes/track2-reconcile-cost/specs/student-tests/spec.md new file mode 100644 index 00000000..a9eb7ffc --- /dev/null +++ b/openspec/changes/track2-reconcile-cost/specs/student-tests/spec.md @@ -0,0 +1,108 @@ +## MODIFIED Requirements + +### Requirement: Проверки отказов на отдельном стенде + +Сценарии отказов SHALL проверяться автоматически одной командой +`make failure_checks`: +- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при + запросе с токеном»; +- `data-storage`: «Сбой при добавлении участников», «БД остановлена», + «БД вернулась», «Соединения исчерпаны»; +- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище + объектов недоступно»; +- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся», + «Очистка кэша»; +- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке», + «Ключ после срока»; +- `api-conventions`: «Лимит одновременных загрузок»; +- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего + не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не + видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв + передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь + ожидания полна», «Ожидание места», «Место освобождается», «Медленный + клиент», «Медленная передача в срок», «Потерянный оригинал», «Загрузка + после простоя S3»; +- `storage-consistency`: все сценарии. + +Команда SHALL: +- собрать образ из рабочего дерева; +- поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить + миграции и bootstrap S3; +- запустить четыре API: + - с настройками по умолчанию; + - «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом + из одного соединения; + - «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в + очереди, коротким сроком ожидания места и коротким сроком тела; + - «с коротким сроком S3» — со сроком вызова S3 в одну секунду: простой + дольше срока вызова в проверке длится полторы секунды, а не шесть. + + Значения «узкого» API и API с коротким сроком S3 SHALL передаваться + проверкам, и проверки SHALL сверять с ними стенд; +- запустить уборщика с коротким grace и интервалом, сравнимыми со + временем теста, без плановой сверки, и передать их значения + проверкам. Grace при этом SHALL проходить проверку границы живой + загрузки (`service-configuration`, «Параметры уборщика»). Сверку + проверки запускают сами, и плановая сверка не меняет стенд у них за + спиной; +- выполнить проверки отказов; +- удалить стенд вместе с его данными при любом исходе. + +Hook стенда отказов SHALL уметь: +- сообщить вложения стенда в PostgreSQL с их статусами, `id` последнего + вложения в статусе «загружается» и `id` вложений с потерянным + оригиналом; +- сообщить, у каких вложений есть объект в bucket стенда, — по самим + объектам, а не по каталогам хранилища; +- внедрить отказ PostgreSQL: + - при записи метаданных загрузки с заданным `filename`; + - при фиксации её `ready`, и задержать такую фиксацию; + - при пометке потерянного оригинала такого вложения; +- убить и снова запустить обычный API стенда; +- внести расхождения хранилищ: + - записать объект в bucket стенда мимо API и удалить объект мимо API — + только под префиксом вложений базы стенда; + - удалить метаданные вложения, изменить в них размер и сдвинуть их + время в прошлое; +- выполнить разовую сверку — без изменений или с `--apply`, с заданным + пределом изменений, стратегией обхода, глубиной и пределом скорости — + и вернуть её записи и код выхода; +- остановить и запустить уборщика стенда, а также запустить отдельного + уборщика с коротким интервалом плановой сверки на заданное время и + вернуть его журнал. + +Других сведений о хранилищах проверки вложений не получают. Объекты без +метаданных проверка находит сравнением двух списков: вложений и +объектов. Ключи доступа S3 hook не получает и не печатает: объект мимо +API записывает процесс в контейнере стенда своими ключами. + +Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на +хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш, +хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода +SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка. +Параллельный запуск двух прогонов не поддерживается: уборка хвоста в +начале второго удаляет стенд первого. + +#### Scenario: Успешный прогон + +- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks` +- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и + volumes стенда отказов после команды нет, а у контейнеров рабочего + стенда прежнее время старта, и рабочий API отвечает + +#### Scenario: Упавшая проверка + +- **WHEN** во время `make failure_checks` падает хотя бы одна проверка +- **THEN** код выхода ненулевой, журналы API и уборщика стенда отказов + выведены, стенд отказов удалён + +#### Scenario: Прерывание + +- **WHEN** `make failure_checks` прерван Ctrl+C +- **THEN** стенд отказов остановлен и удалён вместе с volumes + +#### Scenario: Хвост прошлого прогона + +- **WHEN** контейнеры или volumes стенда отказов остались от прогона, + убитого без уборки +- **THEN** следующий `make failure_checks` удаляет их и начинает заново diff --git a/openspec/changes/track2-reconcile-cost/tasks.md b/openspec/changes/track2-reconcile-cost/tasks.md new file mode 100644 index 00000000..74b532d3 --- /dev/null +++ b/openspec/changes/track2-reconcile-cost/tasks.md @@ -0,0 +1,383 @@ +# Tasks + +Как строить — `design.md` (дальше «решение N»), что должно получиться — +дельты в `specs/`. Порядок — design, Migration Plan. Тесты и hook +пишутся первыми: так красный прогон снимается на коде `7f4e626` без +checkout и stash. Перед первым файлом слоя прочитать его правило: +`service-layer.md`, `repo-layer.md`, `dto.md`, `infra.md`, +`logging.md`, `settings.md`, `run-modes.md`, `docker.md`, +`student-tests.md`, `bench.md`. + +**Точки commit** (решение 16). Commit делает основная сессия после +подтверждения (`bench.md`, «Измеренное состояние — commit»): +1. код — группа 9.1; +2. гипотезы — группа 9.2, раньше метки; +3. метка — группа 10; +4. evidence и отчёт — группа 11. + +Evidence и метка — только с закоммиченного кода. + +**Уборка.** Временные проекты compose, их volumes, сети и образы +убираются сразу после проверки. Сначала `docker compose down` без `-v`, +затем `docker volume rm` по именам своих volumes. Число volumes, сетей и +образов сверяется с исходным. Volumes `mtusi-lab4_postgres_data` и +`mtusi-lab4_s3_data` не удаляются никогда. Контейнеры `domains-*` и +`.env` не трогаются. + +**Ожидаемо красное по ходу работы**, остальное разбирается по AGENTS.md: +- между задачами 1.2 и 5.1 сверка покрытия `make student_test` падает + на маркерах новых сценариев («marker points to unknown scenario»); +- новых исключений сверки change не добавляет, поэтому + `test_exclusion_evidence_exists` не меняется. + +Вопрос преподавателю об ответе на потерянный оригинал открыт (`PLAN.md`, +`### track2-reconciler`, вопрос 1). Класс «другой SHA-256» помечается +так же, как другой размер. Ответ «иначе» меняет только ветку +`open_content`, сценарий `attachments` и ожидания тестов 1.2. + +## 1. Hook, тесты и красный прогон + +- [ ] 1.1 `student-tests/fault_hook.py` (только stdlib, синтаксис 3.9), + действие `reconcile dry-run|apply [<предел>]` по решению 14: + - необязательные `--strategy head`, `--deep` и + `--max-objects-per-second R`; + - каждое проверяется по списку разрешённых: стратегия — `batch` или + `head`, R — неотрицательное число. Иначе код 2 hook; + - аргументы передаются `reconcile` в контейнере уборщика как есть; + - docstring hook называет новые аргументы. + + Проверка: `make lint`; поведение — задача 1.3. +- [ ] 1.2 `student-tests/test_failures.py`, маркер `fault`, пять тестов по + таблице решения 14 с `@pytest.mark.spec("storage-consistency", …)` на + каждый новый сценарий: + - `test_reconcile_head_strategy_same_findings`; + - `test_reconcile_deep_checksum`; + - `test_reconcile_restore_needs_same_bytes` (ещё и «Оригинал вернулся»); + - `test_reconcile_rate_limit` (оба сценария скорости); + - `test_reconcile_limit_stops_rechecks`. + + Тесты фильтруют записи сверки по своим `id` и ключам и сверяют код с + записями того же прохода (`Reconcile.assert_code_matches`), как тесты + `track2-reconciler`. Байты «другие того же размера» — свои для каждого + теста, от зерна. Проверка: задача 1.3. +- [ ] 1.3 Красный прогон до кода групп 2–4 (дерево с 1.1–1.2, код + `7f4e626`): + + ``` + make failure_checks FAULT_ARGS='-k "head_strategy or deep_checksum or restore_needs or rate_limit or limit_stops"' + ``` + + Ожидание: падают все пять — ошибка argparse (код 2) у новых аргументов, + снятие пометки по размеру у `…_restore_needs_same_bytes`, `changes` > 3 + у `…_limit_stops_rechecks`. Вывод сохранить в scratchpad для evidence + 11.2. Проверка: 5 failed с этими причинами, стенд отказов убран. + +## 2. Настройки, enum и DTO + +- [ ] 2.1 `src/config/settings.py`, класс `Reconciler`: + `max_objects_per_second: float = Field(default=2000, ge=0)` с + комментарием о единице и 0 (решение 6, дельта + `service-configuration`). Ещё строка в `config_example.toml`. + Проверка: + - `uv run python -c "from src.config import settings; + print(settings.reconciler.max_objects_per_second)"` — 2000.0; + - `RECONCILER__MAX_OBJECTS_PER_SECOND=-1 uv run python -m src.cleaner + reconcile` — «Invalid cleaner settings» с `loc` поля и код 2 до + обращения к хранилищам. +- [ ] 2.2 `src/schemas/enums/attachment.py`: + - `ReconcileFinding.CHECKSUM_MISMATCH = "checksum_mismatch"` с + комментарием; + - `ReconcileStrategy` (`batch`, `head`). + + `src/schemas/dataclasses/attachment.py`, `ReconcilePassDTO` — новые + поля в конце со значениями по умолчанию (решения 8 и 15): `strategy`, + `deep`, `max_objects_per_second`, `storage_objects`, `s3_requests`, + `read_bytes`, `db_sessions`, `unchecked`, `phase_ms`. Отображения — + `MappingProxyType`. Экспорт — в `__init__.py` по алфавиту (`dto.md`). + Проверка: `make lint`, импорт `src.schemas` без ошибок. + +## 3. Счётчики клиента S3 + +- [ ] 3.1 `src/infra/s3/client.py` по решению 8: + - `ObjectStorage` считает попытки вызовов по операциям (`list`, + `head`, `get`, `delete`, `put`) в `_call`, ключи страниц — в + `list_page`, прочитанные байты — в `_read_chunk`; + - `stats()` отдаёт снимок `StorageStats` (frozen, отображение — + `MappingProxyType`); + - поведение вызовов, сроки и перевод ошибок не меняются; + - docstring модуля называет счётчики. + + Проверка: `make lint`. Совпадение с метриками шлюза — задача 6.7 (без + пометки `count_mismatch`). + +## 4. Сервис сверки и процесс уборщика + +- [ ] 4.1 `AttachmentReconcileService.reconcile(…, strategy, deep, + max_objects_per_second, …)` по решениям 6, 8 и 15: + - темп перед каждым вызовом S3 рядом с `_check_stop`. Счёт затронутых + объектов — дельта `storage.stats()` от начала прохода, ожидание — + кусками ≤ 0,2 с с проверкой сигнала; + - обёртка `db_scope` со счётом сеансов, её же получает внутренний + `AttachmentCleanupService`; + - `phase_ms` шагов `list`, `rows`, `stale`, `recheck`, `act`; + - поля стоимости в DTO и в «Finished reconcile pass». + + Проверка: тесты `…_rate_limit` и `…_head_strategy_same_findings` + (поле `db_sessions`) зелёные в задаче 5.2. +- [ ] 4.2 Ранний отказ по пределу по решению 7: + - в `_recheck_all` при `apply`, как только подтверждённых классов под + пределом (вместе с `checksum_mismatch`) больше `max_changes`, + остальные кандидаты этих классов не перепроверяются и идут в + `unchecked`; + - «Reconcile changes exceed limit» с `unchecked`; + - dry-run перепроверяет всех. + + Проверка: `…_limit_stops_rechecks` и прежние + `test_reconcile_change_limit`, `…_limit_keeps_cleanup` — зелёные (5.2). +- [ ] 4.3 Глубокая сверка по решению 5: + - с `--deep` — GET и SHA-256 потоком (`open_original`, блоки клиента) + у строк `ready` без пометки, старше grace и того же размера; + - класс `checksum_mismatch` — в `LIMITED_KINDS` (пометка под + пределом), в `NEEDS_BUCKET` — нет: объект есть. Перепроверка и + проверка перед пометкой заново читают объект; + - «оригинал вернулся» во всех режимах подтверждается тем же SHA-256: + перепроверка и проверка перед `clear_lost`; + - `read_bytes` в итоге. SHA-256 в журнал не пишется. + + Проверка: `…_deep_checksum`, `…_restore_needs_same_bytes`, + `test_reconcile_restored_original` — зелёные (5.2). +- [ ] 4.4 Стратегия `head` по решению 4: + - шаг S3 → БД — выборка строки на объект (`get_attachments_for_objects` + с одним элементом); строки с тем же ключом пропускаются; + - шаг БД → S3 — HEAD на строку своей базы (с `--deep` — GET); + - множества `seen` нет; + - зависшие, перепроверка, предел и действия — общие. + + Проверка: `…_head_strategy_same_findings` зелёный (5.2); на 10k в + задаче 6.7 `found` равен внесённому. +- [ ] 4.5 `src/cleaner/main.py`: + - аргументы `reconcile` — `--strategy {batch,head}`, `--deep`, + `--max-objects-per-second R` (≥ 0, иначе ошибка argparse, код 2); + - плановая сверка — `batch`, без `--deep`, предел из настроек; + - «Started cleaner» с `reconcile_max_objects_per_second`, а у разового + прохода — ещё с `reconcile_strategy` и `reconcile_deep`. + + `Makefile`, цель `reconcile` — `STRATEGY=head`, `DEEP=1`, `RATE=R`. + Проверка: `make -n reconcile STRATEGY=head DEEP=1 RATE=5` печатает + аргументы; `--max-objects-per-second -1` — код 2. + +## 5. Спеки и проверки отказов + +- [ ] 5.1 Sync дельт в основные спеки — все шесть capability, как в + прежних changes. Purpose `storage-consistency` правится руками: + «стоимость обхода и стратегии описывает change» → описаны в этом + change. Проверка: + - `openspec validate --specs` без ошибок; + - `make student_test` против временного или рабочего стенда — сверка + покрытия без «unknown scenario»; + - новые сценарии `storage-consistency` считаются покрытыми проверками + отказов. +- [ ] 5.2 Полный `make failure_checks` на дереве после групп 2–4: все + проверки зелёные (49 прежних и 5 новых), журнал PostgreSQL без + признаков аварии, стенд отказов убран. Проверка: код 0, число и время в + выводе (ожидаемо дольше на ~1,5–2 мин). + +## 6. Профиль `reconcile` стенда `bench/` + +- [ ] 6.1 `bench/bench.compose.yml`, сервис `cleaner`: лимиты + `BENCH_CLEANER_CPUS` / `BENCH_CLEANER_MEMORY` в + `deploy.resources.limits` и `memswap_limit` — без swap, как у + остальных. `compose_env` в `run.py` их задаёт: `Profile.cleaner_cpus` + 0,25 и `cleaner_memory` 256m — лимиты рабочего стенда. Проверка: в + `docker compose config` стенда у `cleaner` 0,25 / 256 МиБ и swap = + памяти; прежние профили не меняются (паспорт `stand.app_env` тот же). +- [ ] 6.2 `bench/reconcile.py` (только stdlib, без docker) по решениям + 2, 10–13: + - модель набора: `id`, содержимое и класс по номеру, строки CSV для + `\copy`, ожидаемые числа по этапам; + - план этапов и ячеек кругами от `order_seed`; + - разбор записей уборщика, метрик шлюза и строк `bg,…` k6; + - окна и `r` / `a` H4; + - строки `passes.csv` и `windows.csv`; + - вердикты H1–H4 и S4; + - `summary.md`, SVG через `plots.Svg`; + - `--selftest` на синтетических журналах, метриках и строках. + + Проверка: `uv run python bench/reconcile.py --selftest` — код 0. +- [ ] 6.3 `bench/fill_objects.py` по решению 3: + - работает только в контейнере на образе стенда, botocore образа, `src` + не импортирует; + - генератор набора — из `reconcile.py` (`/bench` только на чтение); + - ключи API — из окружения, `docker run -e <имя>` без значения; + - `--processes`, `--threads`, диапазон номеров и размер объекта; + - печатает число объектов и PUT/с, ошибка PUT — код 1. + + Проверка: задача 6.7 — `listed_objects` равно модели. +- [ ] 6.4 `bench/k6/background.js` по решению 10: + - три сценария `constant-arrival-rate` (скачивания из + `/work/downloads.json`, запись в чат записи, чтение его первой + страницы); + - строка `bg,…` на запрос в файл консоли; + - идентификация — `lib.js`, отправка — `messageHeaders`; + - интенсивности, длительность и VU — из окружения. + + Проверка: задача 6.7 — число строк равно итерациям итога k6, ответов + 5xx нет. +- [ ] 6.5 `bench/run.py`, профили `reconcile` и `reconcile_quick` (поля + `Profile.reconcile_*` — целиком в `meta.json`) и `Bench.run_reconcile` + по решениям 1–3, 7–10, 13: + - S3 запускается у профилей загрузок и сверки; + - override `.work/s3-metrics.compose.yml` из `command` сервиса `s3` + `docker compose config` с `-metricsPort`; + - наполнение: строки — `\copy` через stdin psql, объекты — контейнер + `mtusi-bench-fill`, ожидание grace + 2 с после последнего PUT; + - разовые проходы `mtusi-bench-reconcile-` с лимитом CPU варианта + через окружение compose; `before` — с override образа + `bench-from`; + - снимки метрик S3 и `pg_stat_database` до и после прохода; + - сэмплер `scan` 0,5 с на этап; + - блок H4: один k6 на блок, тихие окна 30 с; + - S4 на свежем стенде: строки без объектов `\copy`; + - сверка `found` с моделью — отказ команды; `count_mismatch` — + пометка; + - проверка commit `reconcile_before` до стенда — код 2, как у + `uploads_before`; + - `mtusi-bench-fill` и `mtusi-bench-reconcile-*` — в остатках стенда и + уборке; + - строка хода на каждый проход. + + Проверка — задача 6.7. +- [ ] 6.6 `Makefile`: цели `bench_reconcile [RECONCILE_LABEL=…]` и + `bench_reconcile_quick` под `$(KEEP_AWAKE)`, с комментариями о + длительности (~50 и ~6 мин). `.gitignore` — + `evidence/reconcile/quick-reconcile-*`. Проверка: `make -n + bench_reconcile` и `make -n bench_reconcile_quick` печатают команды + `run.py`. +- [ ] 6.7 `make bench_reconcile_quick` на дереве (шумный хост допустим). + Проверка: + - код 0, все виды проходов; + - `found` равен внесённому; + - нет `count_mismatch`, нет 5xx фона; + - в `summary.md` — строки H1–H4 и S4, SVG открываются; + - время ~6 мин; + - после — volumes, сети и образы как до запуска (кроме тегов + `mtusi-messenger:bench*`, которые профиль снимает сам). + + Записать время и итог в `PLAN.md` (решения apply). +- [ ] 6.8 Регресс `bench/` после правок старта стенда: `make + bench_uploads_quick` и `make bench_quick` — код 0. `--selftest` + `uploads.py`, `resources.py`, `scaling.py`, `failover.py` — код 0. + Проверка: коды и строки хода без ошибок. + +## 7. Драйвер скилла + +- [ ] 7.1 `driver.py reconcile-signal --pace` (stdlib, Python 3.9) по + решению 14: + - вместо `pause s3` — разовый `reconcile --max-objects-per-second 1`; + - `docker stop` через 2 с после «Started cleaner»; + - ожидание: код 1, «Finished reconcile pass» с `interrupted_by: stop`, + «Stopped cleaner» с `exit_code` 1, остановка ≤ 1 с после сигнала; + - только не рабочий проект compose, как сейчас. + + `SKILL.md` называет режим. Проверка: запуск на временном проекте — + код 0 драйвера, затем уборка проекта. + +## 8. Правила и документы + +- [ ] 8.1 Правила: + - `bench.md` — раздел «Профиль сверки (`reconcile`)» и строка таблицы + инструментов. Исключения границы: наполнение данных стенда `\copy`, + загрузчик в контейнере, метрики шлюза на loopback, разовые проходы + уборщика и их журнал; порт метрик только у S3 профиля сверки; + `bench_compare` к меткам сверки не применяется; + - `service-layer.md` — стратегии, глубокая, темп, ранний отказ, счёт + сеансов; + - `infra.md` — счётчики клиента S3 и `stats()`; + - `settings.md` — `max_objects_per_second` и обоснование 2000; + - `logging.md` — поля «Started», «Finished» и «exceed limit»; + - `run-modes.md` — аргументы `reconcile`; + - `student-tests.md` — пять тестов, аргументы hook, красный прогон; + - `dto.md` — enum и поля DTO. + + Проверка: правила не противоречат design и дельтам. +- [ ] 8.2 AGENTS.md: + - абзац о лабе — change `track2-reconcile-cost`; + - таблица команд: `bench_reconcile`, `bench_reconcile_quick`, аргументы + `make reconcile`, `reconcile-signal --pace`; + - карта кода: `bench/reconcile.py`, `fill_objects.py`, + `k6/background.js`, сервис сверки, клиент S3; + - карта evidence: `evidence/reconcile/<метка>/`; + - правило «Лаба 4, сверка» — предел скорости, стратегии, глубокая, + ранний отказ. + + Проверка: все пути в AGENTS.md существуют. +- [ ] 8.3 `PLAN.md`, раздел `### track2-reconcile-cost` — решения apply + («Решения») и вопросы, если появятся. Проверка: раздел есть, ссылки на + design. +- [ ] 8.4 `make lint`, `make check`, `make validate + PYTHON=.venv/bin/python`, `openspec validate track2-reconcile-cost + --strict`. Проверка: все — код 0. + +## 9. Commit кода и гипотезы + +- [ ] 9.1 Commit кода — точка 1 (основная сессия, после подтверждения: + `git status`, `git diff --stat`, предложенное сообщение). Рабочий стенд + для evidence этого change не нужен. Новый код уборщика на нём — по + решению основной сессии (design, Migration Plan). Проверка: дерево + чистое, hash commit записан в `PLAN.md` при следующем commit. +- [ ] 9.2 Гипотезы H1–H4, ожидание S4 и методика (решение 12) — в + `REPORT.md`, раздел «Стоимость сверки: гипотезы (change + `track2-reconcile-cost`)». Это отдельный commit — точка 2, раньше + метки. Проверка: в `git log` commit гипотез после commit кода и до + commit метки. + +## 10. Метка + +- [ ] 10.1 `make bench_reconcile` с закоммиченного кода на тихом хосте: + - рабочий стенд — `make stop`, `domains-*` основная сессия + останавливает на ~50 мин и потом поднимает; + - проверка хоста — `bench.md`, «Результаты»; + - затем commit каталога метки — точка 3. + + Проверка: + - `dirty: false`, нет `host_warnings` и `other_containers`; + - все ячейки, по три повтора; + - `found` равен внесённому, нет `count_mismatch` и 5xx фона; + - в `summary.md` — вердикты H1–H4 и S4. + + Расхождение с гипотезой — не повод править гипотезу: вывод + «опровергнута» пишется в `REPORT.md`. + +## 11. Evidence и отчёт + +- [ ] 11.1 `evidence/reconcile/service.md`, раздел «Остановка во время + паузы предела скорости» — вывод `driver.py reconcile-signal --pace` + (задача 7.1) с закоммиченного кода: команда, дата, commit. Проверка: + код 1, `interrupted_by: stop`, остановка ≤ 1 с. +- [ ] 11.2 `evidence/tests/`: + - `failure-checks.md` — полный `make failure_checks` с закоммиченного + кода и красный прогон задачи 1.3; + - `make test_isolated` — зелёный, база и префикс `test_/` убраны. + + Проверка: числа и commit в файлах, `test_exclusion_evidence_exists` + зелёный. +- [ ] 11.3 `REPORT.md` (спек `load-benchmark`, «Стоимость сверки в + отчёте»): + - раздел «Стоимость сверки: результаты метки `baseline`» — паспорт, + таблицы по этапам, H4 и S4 из `summary.md`, вывод по каждой гипотезе + со ссылкой на ячейки сводки; + - выбор предела 2000 по метке и рекомендации для `head` и глубокой — + CPU S3 на объект; + - «Сверка хранилищ»: стратегия `head`, глубокая и класс «другой + SHA-256», снятие пометки по SHA-256, предел скорости, ранний отказ, + стоимость в итоге; + - строки таблицы доказательств уровня «5»; + - «Ограничения»: один хост, ВМ, генератор на том же хосте, одна нода + S3, синтетические объекты двух размеров, лимит CPU уборщика. + + Проверка: числа совпадают со сводкой метки, ссылки `evidence/…` + существуют. +- [ ] 11.4 `PLAN.md`: строка 6 сводной таблицы — commit кода, гипотез и + метки, evidence; раздел `### track2-reconcile-cost` дополнен. Затем + commit evidence и отчёта — точка 4. Проверка: дерево чистое после + commit.