docs: propose track2-reconcile-cost
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-23
|
||||
@@ -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 строки `<зерно>:<i>`;
|
||||
- содержимое — повторённый SHA-256 строки `<зерно>:<i>: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-<n> --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,<d|w|r>,<отправка мс>,<длительность мс>,<статус>`
|
||||
в файл консоли 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.
|
||||
@@ -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` — без изменений.
|
||||
@@ -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, а в журнале — итог сверки с причиной прерывания
|
||||
«остановка» и запись об остановке уборщика
|
||||
@@ -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** у каждой гипотезы есть вывод со ссылкой на ячейки сводки
|
||||
метки, а числа совпадают со сводкой
|
||||
@@ -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** уборщик не стартует, в журнале — ошибка проверки настроек с
|
||||
именем поля
|
||||
@@ -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 объектов в журнале нет
|
||||
@@ -0,0 +1,369 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Сверка bucket и БД
|
||||
|
||||
Сверка SHALL сравнивать объекты вложений в bucket — ключи с префиксом
|
||||
`<имя базы>/attachments/` — с метаданными вложений той же базы в
|
||||
PostgreSQL и находить расхождения семи классов:
|
||||
- **объект без метаданных** — объект с ключом вида
|
||||
`<база>/attachments/<id>/original`, на который не ссылается ни одна
|
||||
строка и для `id` которого строки нет;
|
||||
- **метаданные без объекта** — вложение `ready`, объекта по ключу из его
|
||||
метаданных в bucket нет;
|
||||
- **другой размер** — вложение `ready`, размер объекта не равен
|
||||
`size_bytes`;
|
||||
- **другой SHA-256** — вложение `ready`, размер объекта равен
|
||||
`size_bytes`, а SHA-256 его содержимого не равен SHA-256 из
|
||||
метаданных. Этот класс ищет только глубокая сверка;
|
||||
- **зависшая загрузка** — вложение в статусе «загружается» старше grace,
|
||||
то же, что убирает уборщик (требование «Уборщик незавершённых
|
||||
загрузок»);
|
||||
- **оригинал вернулся** — оригинал вложения помечен потерянным
|
||||
(требование «Потерянный оригинал»), а объект снова есть с тем же
|
||||
размером и тем же SHA-256;
|
||||
- **чужой объект** — то, что сверка не меняет и оставляет оператору:
|
||||
- объект под префиксом вложений, ключа такого вида API не пишет;
|
||||
- объект с ключом вида `<id>/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 удалять:
|
||||
- метаданные вложений, кроме уборки зависшей загрузки;
|
||||
- объект, на который ссылаются метаданные, в любом статусе;
|
||||
- объект с ключом вида `<id>/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 в метаданных другой ключ под префиксом
|
||||
вложений, объекта по нему нет, а объект `<X>/original` на месте;
|
||||
- готовое вложение Y ссылается на ключ `<Z>/original`, строки Z нет, и
|
||||
объекты `<Y>/original` и `<Z>/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
|
||||
@@ -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` удаляет их и начинает заново
|
||||
@@ -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-<n>` с лимитом 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_<db>/` убраны.
|
||||
|
||||
Проверка: числа и 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.
|
||||
Reference in New Issue
Block a user