feat: add reconcile strategies, deep check, rate limit and cost profile

- reconcile --strategy head, --deep (checksum_mismatch), restore needs the same SHA-256
- [reconciler] max_objects_per_second (2000), pause interrupted by signal
- --apply stops rechecks once the limit is exceeded (unchecked)
- pass cost in the summary: S3 objects and requests, bytes, DB sessions, phases
- S3 client counters, cleaner exits with os._exit after main()
- fault tests, hook args, driver reconcile-signal --pace
- bench profile reconcile / reconcile_quick: fill outside the API, gateway metrics, background load
- sync spec deltas, rules, AGENTS.md, PLAN.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-23 04:52:56 +03:00
co-authored by Claude Opus 5.5
parent dcdfe5f2e4
commit 8d4cf7eebf
41 changed files with 5344 additions and 441 deletions
+104 -4
View File
@@ -99,6 +99,7 @@ change `s3-storage`, решение 9): старт стенда перечисл
| `run.py` (профили `failover`, `failover_quick`), `failover.py`, `resources.py`, `sampler.sh` (режим `scan`), `k6/failover.js`, `k6/retry.js` | `make bench_failover`, `make bench_failover_quick` | две реплики с лимитами рабочего стенда, постоянная интенсивность записи с ключом и чтения, каждая реплика в каждом режиме (`stop`, `kill`, `pause`) с возвратом: посекундная шкала, время обнаружения и восстановления, сверка записей, CPU и память каждого компонента по окнам фазы; результаты — `evidence/failover/<метка>/` |
| `run.py` (профили `rollout`, `rollout_quick`), `rollout.py`, `resources.py`, `sampler.sh` (режим `scan`), `k6/failover.js`, `k6/retry.js`, `scripts/rolling-update.sh` | `make bench_rollout`, `make bench_rollout_quick` | две реплики с лимитами рабочего стенда на образе прежнего commit, та же постоянная нагрузка, посреди неё — поочерёдная замена на образ текущего checkout: посекундная шкала с ответами старых и новых реплик, шаги по каждой реплике, контейнеры, образы и ревизия схемы до и после, сверка записей, CPU и память каждого компонента по окнам замены; результаты — `evidence/rollout/<метка>/` |
| `run.py` (профили `uploads`, `uploads_quick`), `uploads.py`, `sampler.sh` (режим `peak`), `k6/uploads.js`, `k6/prepare.js` | `make bench_uploads [UPLOADS_LABEL=…]`, `make bench_uploads_quick` | память реплики при одновременных загрузках вложений (change `upload-memory`): одна реплика 1 CPU / 512 МБ без swap, S3 рабочего стенда, варианты «до» / «без лимита» / «с лимитом», тела PNG ~1 и ~10 MiB, 1 / 10 / 20 / 40 клиентов; пик `memory.peak` окна, OOM, ответы по кодам, загрузок/с и p50/p95/p99; результаты — `evidence/uploads/<метка>/` |
| `run.py` (профили `reconcile`, `reconcile_quick`), `reconcile.py`, `fill_objects.py`, `sampler.sh` (режим `scan`), `k6/background.js`, `k6/prepare.js` | `make bench_reconcile [RECONCILE_LABEL=…]`, `make bench_reconcile_quick` | стоимость сверки bucket и БД (change `track2-reconcile-cost`): наполнение мимо API (`\copy` и PUT в S3), разовые проходы уборщика — стратегии `batch` и `head`, глубокая, CPU уборщика, предел скорости, фоновая нагрузка, отказ по пределу «до» и «после»; счёт сверки против метрик шлюза S3, CPU и память за окно прохода; результаты — `evidence/reconcile/<метка>/` |
| `run.py` (профили `scaling_*`), `scaling.py`, `sampler.sh`, `k6/mixed.js` | `make bench_scaling SERIES=a\|b\|pool\|ab\|db\|db4`, `make bench_scaling_quick`, `SERIES=db_quick` | серии трека 1: конфигурации реплик и лимитов, на каждую ячейку — свежий стенд, открытая модель, фиксированные уровни и поиск R* по SLO, посекундный сэмплер контейнеров, ВМ, LB и PostgreSQL; результаты — `evidence/bench/<метка>/` |
| `plots.py` | `make bench_plots LABELS="…"` | графики SVG и сводка серий (R* от числа реплик, p95 от интенсивности, CPU по компонентам, точка насыщения) — `evidence/plots/<PLOTS>/` |
| `compare.py` | `make bench_compare` | дельта двух меток стенда (ячейки матрицы или общие конфигурации серий), эффект или шум |
@@ -158,10 +159,15 @@ change `s3-storage`, решение 9): старт стенда перечисл
поля в паспорте не имеют. Там же исправлено: контейнер сэмплера (образ
PostgreSQL) удаляется с `-v`, иначе каждый запуск оставлял анонимный
volume `/var/lib/postgresql`;
- **S3** — запускает только профиль `uploads`: образ, аргументы и
лимиты рабочего стенда (`BENCH_S3_*`, 1 CPU / 512 МБ, swap = память),
bucket `bench` (`bench.env`) и пользователи — тот же `s3-bootstrap`;
override `s3` нужен compose и в остальных профилях;
- **S3** — запускают только профили `uploads` и `reconcile`: образ,
аргументы и лимиты рабочего стенда (`BENCH_S3_*`, 1 CPU / 512 МБ, swap =
память; у `reconcile` — ещё порт метрик шлюза на loopback), bucket
`bench` (`bench.env`) и пользователи — тот же `s3-bootstrap`; override
`s3` нужен compose и в остальных профилях;
- **уборщик** — запускает только профиль `reconcile` разовыми проходами:
лимиты `BENCH_CLEANER_*` (`cleaner_cpus` 0,25, `cleaner_memory` 256m —
рабочего стенда, без swap) compose требует при разборе у всех профилей;
окружение реплик (`stand.app_env`) они не меняют;
- **PostgreSQL `max_connections`:** 100, как у образа (`-c
max_connections` в override); у серий — из конфигурации ячейки,
лимиты конфигурации в паспорте (`limits.<конфигурация>`);
@@ -375,6 +381,100 @@ docker — `bench/uploads.py` (`--selftest`).
рабочий стенд остановлен (`make stop`), гипотезы H1–H4 закоммичены
раньше метки.
## Профиль сверки (`reconcile`)
Спек `load-benchmark`, «Профиль сверки» и «Стоимость сверки в отчёте»;
design change `track2-reconcile-cost`, решения 1–3, 7–13. Методика — поля
`Profile` (`reconcile_*`, `cleaner_*`) в `run.py`, модель набора, план,
разбор, вердикты и сводка без docker — `bench/reconcile.py`
(`--selftest`), загрузчик объектов — `bench/fill_objects.py`, фоновая
нагрузка — `bench/k6/background.js`.
- **Стенд:** LB, две реплики 1 CPU / 512 МБ, PostgreSQL 2 / 1 ГБ, Valkey
0,5 / 128 МБ, S3 и `s3-bootstrap` рабочего стенда; к аргументам S3
добавлен `-metricsPort=9327` (override `.work/s3-metrics.compose.yml`
из `command` сервиса `s3` по `docker compose config` того же стенда —
списка аргументов в двух местах нет). Порт слушает loopback контейнера
S3, из сети стенда недоступен; **у прочих профилей и рабочего стенда его
нет**. Сэмплер `scan` с интервалом 0,5 с (`reconcile_sample_interval_s`)
на этап, k6 без лимита.
- **Проход** — разовый уборщик `docker compose run -d --name
mtusi-bench-reconcile-<n> --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30
cleaner reconcile …` (лимиты `BENCH_CLEANER_*` в `bench.compose.yml` —
0,25 CPU / 256 МБ без swap, в управляемом опыте `BENCH_CLEANER_CPUS=1`
на вызов), затем `docker wait`, журнал, `docker inspect` и `docker rm`
при любом исходе. Вариант «до» — тот же вызов с override
`.work/cleaner-before.compose.yml` (`image: mtusi-messenger:bench-from`,
`Profile.reconcile_before` — `7f4e626`, последний commit до change;
`git archive` → тег `bench-from`, проверка commit до стенда — код 2, как
у `rollout_from`; смена при переходе в лабу 5 — так же). Тег стенда не
меняется.
- **Этапы полной метки:** A — свежий стенд, 1 000 × 1 MiB, `batch`,
`deep`, `deep-fast`; B — свежий, 10 000 × 4 KiB, `batch`, `head`,
`deep`; C — тот же, +20 000, `batch`, `head`; D — тот же, +70 000,
`batch` и блок под нагрузкой `stand`, `stand-unlimited`,
`fast-unlimited`, `fast-limited`; S4 — свежий, 10 000 согласованных и
1 000, затем 10 000 строк `ready` без объектов, `before` и `after`
(`--apply --max-changes 100`, у `after` — без предела скорости). Три
повтора кругами внутри группы (`reconcile.plan_passes`), план — в
`meta.json` до первого прохода. Ячейки без нагрузки — dry-run без
предела скорости. `reconcile_quick` — один стенд 2 000 × 4 KiB, все
виды по одному проходу, окна 5 с, S4 с 300 кандидатами на своём свежем
стенде.
- **Набор** (решение 2): объект `i` — `id` UUID v4 из SHA-256
`<зерно>:<i>`, содержимое — повторённый SHA-256 `<зерно>:<i>:c`, класс —
`i mod 400` (0 — объект без строки, 1 — строка без объекта, 2 — размер
в строке на байт больше, 3 — зависшая загрузка `pending` с объектом);
строки — читаемый чат и его владелец из `prepare.js`, `created_at` =
`updated_at` = сутки назад. Проходы этапа — через grace + 2 с после
последнего PUT. Каждый проход сверяет `found` по классам,
`listed_objects` и `checked_rows` с моделью (`reconcile.model`):
расхождение — отказ команды с проходом, классом и обоими числами.
- **Граница чёрного ящика** — новые исключения, только у этого профиля и
только на свежем стенде `mtusi-bench`:
- метаданные набора — `\copy attachments (…) FROM STDIN` через `docker
exec -i … psql` (данные стенда, схему не трогает; файла CSV нет —
строки генерирует `reconcile.rows_csv`);
- объекты — `bench/fill_objects.py` в контейнере `mtusi-bench-fill` на
образе стенда (botocore образа, `src` не импортируется, `bench/` на
чтение, ключи API — `docker run -e <имя>` без значения в argv, три
процесса × 24 потока);
- метрики шлюза S3 — `docker exec mtusi-bench-s3 wget` на loopback до
и после прохода; `pg_stat_database` — psql до и после;
- проход — процесс уборщика из образа, результат — его записи
«Started cleaner», «Finished reconcile pass», «Reconcile changes
exceed limit» (`raw/<проход>-cleaner.json`; записи о расхождениях —
числом).
`mtusi-bench-fill` и `mtusi-bench-reconcile-*` — в остатках стенда и в
уборке `Stand.stop()`.
- **Счёт S3:** шлюз считает HEAD типом GET, поэтому `LIST = list`,
`GET = head + get`, `DELETE = delete`; в ячейках без нагрузки неравенство
— пометка `count_mismatch` (строка остаётся).
- **Ресурсы:** окно прохода — `[t − duration_ms, t]`, `t` — время записи
«Finished reconcile pass» (часы ВМ); CPU уборщика (по `id` контейнера
прохода), S3, PostgreSQL, реплик и LB — по отсчётам сэмплера; память
уборщика — выборка у начала окна и наибольшая за жизнь контейнера.
- **Фоновая нагрузка (H4):** один k6 `background.js` на блок — 300
скачиваний (5 000 согласованных вложений от зерна, `.work/downloads.json`),
50 записей и 50 чтений истории в секунду; тихие окна 30 с перед первым
проходом и после каждого; окна «до» и «после» — по старту и выходу
контейнера, окно прохода — по итогу. k6 останавливается `pkill -INT -f
background.js` в контейнере k6 (итог он пишет и тогда); строк `bg,…`
столько же, сколько итераций сценариев, иначе отказ. `r` = p95 прохода
/ p95 тихих, `a` = p95 до / p95 после; 5xx — пометка `bg_5xx`.
- **Сравнение:** все варианты — внутри одной метки; второй метки A/A нет
(шум — разброс повторов и `a`). `make bench_compare` метки сверки не
сравнивает: он читает `evidence/bench/`, у сверки другая методика.
- **Результаты:** `evidence/reconcile/<метка>/` — `meta.json` (раздел
`reconcile`: план, этапы и модели, commit и образы «до», аргументы S3,
CPU уборщика, фоновая нагрузка; `limits.cleaner` по CPU), `passes.csv`
(строка на проход, новые столбцы — в конец), `windows.csv`, `summary.md`
(таблицы, S4, вердикты H1–H4 и S4), `cost-by-n.svg`, `requests-by-n.svg`,
`background-p95.svg`, `raw/`. `quick-reconcile-*` — в `.gitignore`.
- **Время:** полная метка ~50 мин, быстрая ~6 мин. Замер для отчёта —
`make bench_reconcile` на тихом хосте, рабочий стенд остановлен (`make
stop`), гипотезы H1–H4 закоммичены раньше метки.
## Серии трека 1 (`scaling_*`)
Доказательство уровня «5», трек 1 «Цена масштабирования» (design change
+5 -1
View File
@@ -313,7 +313,11 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t
уборщика нет; разовый проход — `docker compose run --rm --no-deps
cleaner --once`. Стенд отказов запускает его с grace 20 с, интервалом
1 с и без плановой сверки (`RECONCILER__INTERVAL_SECONDS: "0"`,
`student-tests.md`), `bench/` описывает (тоже с 0), но не запускает.
`student-tests.md`), `bench/` описывает (тоже с 0) и запускает только
разовыми проходами профиля сверки (`bench.md`, «Профиль сверки»). Выход
процесса — `os._exit` после `main()` (`src/cleaner/__main__.py`):
финализация интерпретатора при 0,25 CPU — до 1,5 с (design change
`track2-reconcile-cost`, «Уточнения apply», п. 14).
С change `track2-reconciler` сервис ещё и сверяет bucket с БД — при
старте и раз в `[reconciler] interval_seconds` (3600 с); разовая
сверка — `make reconcile [APPLY=1] [MAX_CHANGES=N]` (`docker compose
+11
View File
@@ -56,3 +56,14 @@ paths:
`ReconcileFindingDTO` (класс, ключ, `id`, возраст, размеры) и
`ReconcilePassDTO` (итог прохода; `found` и `fixed` — неизменяемые
отображения `MappingProxyType`, а не `dict`: DTO frozen).
- Стоимость сверки (design change `track2-reconcile-cost`, решения 8 и
15): `ReconcileFinding.CHECKSUM_MISMATCH` (`checksum_mismatch`) и
`ReconcileStrategy` (`batch`, `head`) в `enums/attachment.py`;
`ReconcilePassDTO` — новые поля в конце со значениями по умолчанию:
`strategy`, `deep`, `max_objects_per_second`, `storage_objects`,
`s3_requests` и `phase_ms` (`MappingProxyType`, по умолчанию пустой —
`field(default_factory=…)`), `read_bytes`, `db_sessions`, `unchecked`;
`ReconcileFindingDTO.sha256: bytes | None = None` — SHA-256 строки для
перепроверки прочитанного объекта, в журнал не попадает. Снимок
счётчиков клиента S3 `StorageStats` — тип `src/infra/s3`, не DTO
слоёв.
+11 -2
View File
@@ -219,12 +219,21 @@ paths:
префикс). Нет bucket — `ObjectStorageUnavailable` («bucket is
missing»), а не пустая страница: у списка и 404 без тела считается
отсутствующим bucket; отказ в списке — «denied access».
`StoredObjectInfo.last_modified` — из списка и HEAD (часы S3,
точность — секунда), у `open` — `None`. Порядок списка SeaweedFS —
`StoredObjectInfo.last_modified` — из списка, HEAD и GET (часы S3,
точность — секунда). Порядок списка SeaweedFS —
обход каталогов, а не порядок байтов: сверка не сливает
отсортированные потоки, а собирает множество ключей. Префикс —
только `<namespace>/attachments/` (repo): политика уборщика другие
префиксы запрещает;
- счётчики клиента (design change `track2-reconcile-cost`, решение 8):
попытки вызовов по операциям — в `_call` до вызова, в том числе
неудачные (`OPERATION_NAMES`: `list`, `head`, `get`, `delete`, `put`),
ключи страниц — в `list_page`, прочитанные байты — в `_read_chunk`.
`stats()` — неизменяемый снимок `StorageStats` (`calls` —
`MappingProxyType`); стоимость прохода сверка считает разностью
снимков. На поведение, сроки и перевод ошибок счётчики не влияют.
`open` отдаёт и `last_modified` (GET), чтобы глубокая сверка `head`
проверяла свежесть без HEAD;
- адресация `path`: `bucket.s3` Docker DNS не разрешает;
простаивающее соединение aiohttp закрывает через
`S3_KEEPALIVE_TIMEOUT_SECONDS` (15 с), раньше шлюза (120 с);
+11 -1
View File
@@ -201,7 +201,17 @@ paths:
`fresh_rows`, `lost_known`, `refused`, `unlogged`, `interrupted_by`,
`duration_ms`): `info`, если ничего не осталось, иначе `warning`;
- предел — `error` «Reconcile changes exceed limit» (`changes`,
`max_changes`);
`max_changes`, с change `track2-reconcile-cost` — `unchecked`;
`changes` после раннего отказа — `max_changes + 1`, нижняя граница);
- стоимость прохода (change `track2-reconcile-cost`, решения 8 и 15):
записи прохода связаны полями `strategy` и `deep`; итог ещё называет
`max_objects_per_second`, `storage_objects`, `s3_requests` (`list`,
`head`, `get`, `delete`), `read_bytes`, `db_sessions`, `unchecked`,
`phase_ms` (`list`, `rows`, `stale`, `recheck`, `act`) — ключи
постоянные, значения числа; «Started cleaner» — ещё
`reconcile_max_objects_per_second`, а у разового прохода
`reconcile_strategy` и `reconcile_deep` (у сервиса — `null`). SHA-256
объектов и строк в записях нет;
- непредвиденная ошибка — `error` «Reconcile pass failed» с traceback
(`cleaner`); «Started cleaner» с change называет ещё `mode`,
`reconcile_interval_seconds`, `reconcile_page_size`,
+13 -1
View File
@@ -137,7 +137,19 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n
уборки и времени до сверки. Пока идёт сверка, уборка ждёт;
- SIGTERM во время сверки: текущий вызов S3 или шаг с БД доводится,
новые страницы и действия не начинаются, итог — `interrupted_by:
stop`; сервис выходит с кодом 0, разовый проход — с 1.
stop`; сервис выходит с кодом 0, разовый проход — с 1. Паузу предела
скорости сигнал прерывает сразу (куски по 0,2 с): остановка — не
позже секунды (`driver.py reconcile-signal --pace`). Для этого
`src/cleaner/__main__.py` после `main()` выходит `os._exit(code)`
(stdout и stderr сброшены, клиенты закрыты): финализация
интерпретатора при 0,25 CPU — 0,8–1,5 с (design change
`track2-reconcile-cost`, «Уточнения apply», п. 14);
- с change `track2-reconcile-cost` (решения 4–6) у разового прохода ещё
`--strategy {batch,head}` (по умолчанию `batch`), `--deep` и
`--max-objects-per-second R` (≥ 0, иначе ошибка argparse, код 2; без
аргумента — `[reconciler] max_objects_per_second`); `make reconcile
STRATEGY=head DEEP=1 RATE=R`. Плановая сверка — всегда `batch`, без
глубокой, предел из настроек.
- Непредвиденная ошибка прохода — `error` с traceback, процесс живёт
до следующего прохода; отказ S3 или PostgreSQL — `warning`, без
перезапуска (решение 5).
+42 -3
View File
@@ -180,9 +180,48 @@ paths:
объект»: без HEAD, без пометки и без уборки; HEAD, пометка, снятие и
DELETE ещё раз проверяют префикс (design change `track2-reconciler`,
«Уточнения apply», п. 19). Отказ S3 или БД — `interrupted_by`, после
сигнала — `stop`; `stop_requested()` (`_check_stop`) — перед каждым
вызовом S3 и шагом с БД: остановка ждёт не больше одного вызова (п.
20);
сигнала — `stop`; `stop_requested()` (`_Pass.check_stop`) — перед
каждым вызовом S3 и шагом с БД: остановка ждёт не больше одного вызова
(п. 20);
- стоимость сверки (design change `track2-reconcile-cost`, решения
4–8): `reconcile(…, strategy, deep, max_objects_per_second, …)`.
Параметры, счётчики и находки прохода — `_Pass`, вызовы S3 — свои
обёртки сервиса (`_list_page`, `_probe`, `_head`, `_read`, `_delete`):
сигнал до вызова, предел скорости после;
- `strategy=head` — только разовый проход: шаг S3 → БД — выборка
строки на объект (`get_attachments_for_objects` с одним элементом),
пара «строка — объект» с тем же ключом пропускается; шаг БД → S3 —
HEAD на строку своей базы (с `deep` у непомеченной строки старше
grace — сразу GET). Множества `seen` нет. Классификация пары —
общая `_row_with_object`, строки без объекта — `_row_without_object`:
расхождения те же, что у `batch`;
- `deep` — GET и SHA-256 потоком (`open_original`, блоки клиента,
`hashlib`) у строки `ready` без пометки, старше grace, с объектом
того же размера, не моложе grace; класс `checksum_mismatch` — в
`LIMITED_KINDS` и `ACTION_ORDER` (пометка), не в `NEEDS_BUCKET`.
«Оригинал вернулся» и «другой SHA-256» (`NEEDS_READ`) перепроверка и
действие подтверждают заново прочитанным объектом: размер и SHA-256
строки (`ReconcileFindingDTO.sha256`). Без `deep` вернувшийся объект
тоже читается — пометку снимает только тот же SHA-256; другой —
`lost_known`;
- предел скорости — после каждого вызова S3 (`_pace`): затронуто
(`_touched` — ключи страниц и HEAD/GET/DELETE, разность
`storage.stats()` с начала) больше `R × время с начала прохода` —
`asyncio.sleep` кусками ≤ `RECONCILE_PACE_STEP_SECONDS` (0,2 с) с
проверкой сигнала. Пауза после вызова, а не перед следующим: тогда и
последний вызов прохода не обгоняет предел (design, «Уточнения
apply»). DELETE шага уборки зависшей — тоже: `_pace` после
`remove_stale_pending`;
- ранний отказ: с `apply` в `_recheck_all`, как только подтверждённых
классов `LIMITED_KINDS` больше `max_changes`, остальные кандидаты
этих классов не перепроверяются, а считаются в `unchecked`; `_act`
отказывает тем же условием (`changes` = `max_changes + 1`). Dry-run
перепроверяет всех;
- счёт сеансов — обёртка `db_scope` сервиса (`self.db_scope` считает
и вызывает фабрику), её же получает внутренний
`AttachmentCleanupService`; длительность шагов — `_Pass.phase` (`list`,
`rows`, `stale`, `recheck`, `act`). Плановая сверка — `batch`, без
`deep`, предел из настроек (`src/cleaner/main.py`);
- `MessageService.send_message(..., attachment_ids)`: членство →
`get_attachments` (все найдены, чат этого сообщения, `ready`; иначе
`AttachmentNotFound` до захвата ключа) → хэш → ключ → сообщение →
+13
View File
@@ -241,6 +241,19 @@ pending_grace_seconds` и его проверка при старте (одна
`reconcile_page_size`, `reconcile_max_changes` и `mode`. Стенд отказов и
`bench/` — `RECONCILER__INTERVAL_SECONDS: "0"`.
С change `track2-reconcile-cost` (решение 6) ещё `max_objects_per_second`
(float, `ge=0`, 2000; 0 — без предела) — предел скорости прохода:
объектов S3 в секунду в среднем от начала прохода (ключи страниц списка,
HEAD, GET, DELETE). Разовая подмена — `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; проход 100k на лимите стенда — с ~30 до ~65 с, на
рабочем стенде (2–3 тыс. объектов) — ~1,5 с в час; граница нагрузки на
S3 не зависит от CPU уборщика. Проверка выбора — метка профиля сверки
(`bench.md`), итог — `REPORT.md`. «Started cleaner» называет
`reconcile_max_objects_per_second`.
`.env.example` skeleton lab2 предлагает «логические» имена: `APP_HOST`,
`APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`,
`SESSION_STORE`, `CACHE_URL_FILE`; шапка шаблона просит сопоставить их
+34 -1
View File
@@ -289,6 +289,37 @@ paths:
первом раунде (загрузки 4, 8, 3: 503 `unavailable`, в журнале API —
`put_object` `ReadTimeoutError` за 1 мс); после правки — 1 passed,
~16 с (`evidence/tests/failure-checks.md`);
- с change `track2-reconcile-cost` (design, решение 14) — стоимость
сверки, тоже проверки отказов, в конце `test_failures.py`:
- hook: `reconcile dry-run|apply [<предел>] [--strategy batch|head]
[--deep] [--max-objects-per-second R]` — каждый аргумент по списку
(`reconcile_options`: стратегия из двух, R — неотрицательное число,
повтор флага — отказ), иначе код 2 hook; команде передаются как есть.
`run_reconcile(stand, mode, limit, options=…)` в тестах;
- тесты: `test_reconcile_head_strategy_same_findings` (расхождения как в
`…_finds_and_fixes`, уборщик стоит; dry-run `batch` и `head` — свои
классы и ключи, весь отчёт, `found`, `listed_objects`, `checked_rows` и
коды равны, у `head` больше HEAD и сеансов; затем apply — стенд без
внесённого), `test_reconcile_deep_checksum` (A в сообщении
перезаписано другими байтами того же размера, `age-row`, G + 1:
поверхностная A не называет, `--deep` — `checksum_mismatch`,
`read_bytes`, код 3, ничего не изменилось, SHA-256 обоих тел в журнале
нет; `--deep --apply` — пометка, 404 / 200),
`test_reconcile_restore_needs_same_bytes` (помечено → другие байты
того же размера, G + 1: apply пометку не снимает, 404 → те же байты,
G + 1: снята, 200 с тем же SHA-256), `test_reconcile_rate_limit`
(восемь загрузок и одна потеря, уборщик стоит; dry-run с пределом 0 и
с R = max(5, ⌈объектов / 4⌉): `duration_ms ≥ 1000 × storage_objects /
R × 0,95`, без предела короче, находки и коды равны),
`test_reconcile_limit_stops_rechecks` (6 потерь, apply с пределом 2:
код 3, `changes` = 3, `unchecked` ≥ 3, ни одной пометки; dry-run
называет все шесть, `unchecked` 0; apply 100 — помечены). Байты
«того же размера» — `same_size_bytes(data, seed=…)` от зерна теста;
- красный прогон на `7f4e626` (тесты и hook из рабочего дерева): упали
все пять — новые аргументы — ошибка argparse (код 2; у `head` пустой
отчёт, у предела скорости нет итога), у глубокой нет поля `deep`,
пометку снимал другой объект того же размера, `changes` 7 вместо 3
(`evidence/tests/failure-checks.md`);
- исключения сверки: «Принявшая реплика остановлена» — `driver.py
attachment-failover` → `evidence/attachments/failover.md`; «Байты не в
БД и не на диске API» — `driver.py attachment-storage` →
@@ -379,7 +410,9 @@ paths:
С change `track2-reconciler` — без плановой сверки
(`RECONCILER__INTERVAL_SECONDS: "0"`, строка `start cleaner` называет
и её интервал), а `<проект>-cleaner-scheduled` hook `run-cleaner`
убирается вместе с API. Прогон — ~10 мин (с change
убирается вместе с API. Прогон — ~13 мин (с change
`track2-reconcile-cost` — 54 проверки, pytest ~760 с: пять тестов
стоимости сверки ~3,5 мин, из них ожидание grace — 4 × 21 с; с change
`fix-upload-put-flake` — 49 проверок, pytest ~550–570 с: тест простоя S3
~17 с, остальное — разброс хоста; до него 48 проверок, pytest ~535 с;
до правок по verify `track2-reconciler` — 45 и ~460 с;
+2 -1
View File
@@ -126,7 +126,7 @@ python3 $D stop
| `upload-consistency` | только стенд с LB: спеки `attachments` «Порядок записи» и `storage-consistency` (design change `upload-consistency`, решение 11). Синтетические Алиса, Боб и чат; готовое вложение R. Шаги: (1) `docker compose pause s3` → загрузка через LB — 503 за ~5 с → `unpause` в `finally`; новая строка `pending` по psql (`id`, статус, возраст, ключ); (2) триггер «фиксация `ready` падает» (SQLSTATE 08006) на рабочей базе только для уникального `filename` прогона → загрузка 503 → строка `pending`, объекта уже нет (компенсация), триггер снят (`finally`, и остаток прошлого прогона — в начале); (3) метаданные, байты и сообщение со ссылкой на обе строки — 404; (4) после grace прогона 30 с — `docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once`, его JSON-вывод; (5) psql и `weed shell fs.tree` (файлы `original`, а не каталоги) — ни строк, ни объектов обеих загрузок, объектов без строки под префиксом рабочей базы нет; R скачивается с тем же SHA-256. Таблица «проверка → ожидаемо → получено» без токенов и секретов; код 1 при расхождении, без LB — код 2. ~45 с. Вывод — `evidence/attachments/consistency.md` |
| `reconcile-cycle` | только стенд с LB: спеки `storage-consistency` (сверка bucket и БД) и `attachments` «Потерянный оригинал» (design change `track2-reconciler`, решение 12). (1) исходный dry-run с grace по умолчанию — расхождений нет, иначе код 2; (2) синтетические Алиса, Боб, чат, вложения A (в сообщении), B, C; (3) объект O без строки и чужой ключ X — `docker exec` реплики (botocore образа её ключами), объект A удалён (`weed shell fs.rm`), строка B удалена и размер C изменён (psql), P — триггер COMMIT на уникальный `filename` (503, строка `pending` и объект); (4) после grace 30 с dry-run: таблица «класс → действие → ключ → `id` → возраст», снимки строк, объектов и пометок до и после совпали; (5) байты A — 500; (6) свежий F, `--apply`: O, B удалены, A, C помечены, P убрана, F не тронут, байты A — 404, метаданные A — 200 и равны ответу загрузки, история отдаёт A; (7) повтор — только чужой X, код 3; оператор удаляет X — код 0; после grace F удалён; (8) A возвращён теми же байтами — «оригинал вернулся», байты 200 с тем же SHA-256, итоговый dry-run — код 0. Таблица «проверка → ожидаемо → получено» без токенов; код 1 при расхождении, без LB — код 2. ~2 мин. Вывод — `evidence/reconcile/cycle.md` |
| `reconcile-stress [--seconds S] [--clients N]` | только стенд с LB: «Сверка под нагрузкой». Предусловие — dry-run с grace 20 с без расхождений (иначе код 2); два объекта без строки и два вложения без объекта; N клиентов (4) S секунд (40, больше grace) загружают PNG ~100 KiB из шума и отправляют сообщения, поток сверки — `--apply` с grace 20 с раз в ~3 с, затем ещё один проход. Итог: загрузки по кодам, сообщения, коды проходов, исправления по классам; проверки — внесённые исправлены (объекты удалены, новые пометки — ровно внесённые), каждое 201 скачивается с тем же SHA-256, каждое сообщение отдаёт своё вложение, ни одного прерванного прохода, повтор dry-run — код 0. Проверка корректности, не замер. Вывод — `evidence/reconcile/stress.md` |
| `reconcile-signal` | только не рабочий проект compose (выбор — окружением `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`; `mtusi-lab4` — отказ, код 2): спек `graceful-shutdown`, разовый проход сверки, прерванный сигналом, — код 1 (design change `track2-reconciler`, «Уточнения apply», п. 23). Нужны запущенные `s3` и образ уборщика, LB и реплики не нужны. `docker compose pause s3` → `run -d --no-deps --name <проект>-reconcile-signal cleaner reconcile --apply` → через секунду после «Started cleaner» `docker stop` → код контейнера и журнал → `rm`, `unpause s3` в `finally`. Записи процесса (событие, уровень, операция, `interrupted_by`, `exit_code`) и таблица: код 1, `interrupted_by: stop`, «Stopped cleaner» с `exit_code` 1, записей «Fixed» 0, остановка быстрее 10 с; код 1 при расхождении. ~10 с. Вывод — раздел `evidence/reconcile/service.md` |
| `reconcile-signal` | только не рабочий проект compose (выбор — окружением `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`; `mtusi-lab4` — отказ, код 2): спек `graceful-shutdown`, разовый проход сверки, прерванный сигналом, — код 1 (design change `track2-reconciler`, «Уточнения apply», п. 23). Нужны запущенные `s3` и образ уборщика, LB и реплики не нужны. `docker compose pause s3` → `run -d --no-deps --name <проект>-reconcile-signal cleaner reconcile --apply` → через секунду после «Started cleaner» `docker stop` → код контейнера и журнал → `rm`, `unpause s3` в `finally`. Записи процесса (событие, уровень, операция, `interrupted_by`, `exit_code`) и таблица: код 1, `interrupted_by: stop`, «Stopped cleaner» с `exit_code` 1, записей «Fixed» 0, остановка быстрее 10 с; код 1 при расхождении. ~10 с. `--pace` (design change `track2-reconcile-cost`, решение 14): вместо `pause s3` — 8 объектов пробы под `<база>/attachments/pace-signal-*` мимо API (`docker compose run --rm --no-deps -T --entrypoint python api -`: botocore образа ключами API из окружения контейнера), `cleaner reconcile --max-objects-per-second 1` (dry-run), `docker stop` через 2 с после «Started cleaner» — во время паузы предела скорости; ожидание — код 1, `interrupted_by: stop`, «Stopped cleaner» с `exit_code` 1, остановка ≤ 1 с; объекты пробы удаляются в `finally`. Нужен ещё сервис `api` в конфигурации проекта (реплики не нужны). Вывод — раздел `evidence/reconcile/service.md` |
| `s3-idle [--rounds 3] [--downloads 10] [--puts 12] [--size-mib 4] [--pause-ms 0.5]` | только стенд с LB: спеки `object-storage` «Вызов после простоя» и `attachments` «Загрузка после простоя S3» (design change `fix-upload-put-flake`, решение 4). Проба клиента S3 в первой работающей реплике `api`: `docker exec -i <реплика> python -` со скриптом из stdin — код, настройки и ключи образа, ключи в драйвер не попадают; uvloop, если есть. Два варианта по очереди, у каждого свой `ObjectStorage` и пул: `image` (как в образе) и `reference` (прежний `read_timeout` aiohttp = `[s3] timeout_seconds`, подменой `AioConfig` при создании клиента). Раунд: `--downloads` одновременных скачиваний объекта `--size-mib` MiB через `open` / `iter_chunks` с паузой `--pause-ms` после блока 64 KiB, простой `[s3] timeout_seconds + 0,5` с, `--puts` PUT по 128 KiB по одному. Таблица по раундам: `read_timeout` клиента, скачивания с тем же SHA-256, соединения пула со взведённым сроком чтения после скачиваний (`armed`) и с сохранённым исключением после простоя (`broken`) — закрытые поля aiohttp `_conns`, `_read_timeout_handle`, `_exception`, нет их — «n/a», тогда судят только по PUT; PUT прошло и упало, у упавших — цепочка исключений и мс; каждый записанный объект читается обратно (размер и SHA-256). Объекты — под `<база>/.s3-idle-probe/<uuid>/` (сверка этот префикс не читает), удаляются в `finally` отдельным клиентом; затем `weed shell fs.tree` — файлов пробы 0. Код 0 — у `image` ни испорченного соединения, ни упавшего PUT, ни расхождения байтов, все раунды пройдены и файлов не осталось; 1 — иначе (эталон может падать: так видно механизм); 2 — нет реплики или консольный процесс драйвера. Пул API не трогает (отдельный процесс), но на время команды берёт ~100 MiB и CPU реплики — без нагрузки на стенд. ~40 с при 3 раундах и `timeout_seconds` 5. Вывод — `evidence/s3/idle-connection.md` |
| `lb-upload-timeouts [--config F] [--image ТЕГ]` | без стенда (рабочий стенд и проекты compose не трогает): спек `load-balancing` «Загрузки через балансировщик» и «Ошибки балансировщика в формате контракта» (design change `upload-memory`, решение 7). `haproxy -c` конфигурации F (по умолчанию `infra/haproxy/haproxy.cfg`) в закреплённом образе LB из `docker-compose.yml`, затем временная сеть `mtusi-lbto-<метка>`: заглушка реплики на образе API (по умолчанию `mtusi-messenger:lab4`, asyncio stdlib) под сетевым именем `api` и HAProxy с F и `API_PORT=8080` на свободном `127.0.0.1`; ожидание `UP` заглушки по `/health/ready` через LB. Пять случаев параллельно, у каждого своё соединение и свой `case` в строке запроса: заглушка молчит 12 с до чтения тела загрузки 10 MiB и после него — 201 от заглушки; 12 с на `GET /api/v1/users/me` — 504 LB через ~10 с; 32 с на пути загрузки — 504 LB через ~30 с; клиент отправил половину тела и молчит — 400 LB через ~30 с (`timeout client`). Ошибки LB — `application/json`, ровно `{"error": {"code", "message", "request_id"}}`, `code` по статусу, `request_id` = `X-Request-Id`. Таблица «случай → ожидаемо → получено → время», код 1 при расхождении. Сеть и контейнеры (метка `mtusi.lb-upload-timeouts`) удаляются при любом исходе, в том числе по Ctrl+C, SIGTERM, SIGHUP. ~35 с. На `haproxy.cfg` до change (`git archive f894040 infra/haproxy/haproxy.cfg \| tar -x -C <каталог>`, `--config <каталог>/infra/haproxy/haproxy.cfg`) — код 1: 502 и 504 через 10 с на пути загрузки, 400 в HTML. Вывод — `evidence/uploads/lb-timeouts.md` |
| `stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3]` | спек `graceful-shutdown` «Остановка во время старта»: контейнеры образа (по умолчанию `mtusi-messenger:lab4`) с лимитами реплики (1 CPU / 512 МиБ без swap), без сети и `config.toml`; `docker stop --timeout 10` через паузу после `docker run` и сразу по строке «Started server process». По потоку `docker events` и журналу: «сигнал через», время `docker stop`, «выход после сигнала», код выхода, этап (`import` / `server-start` / `running`), кто остановил (`early` / `uvicorn`). Код 0 — каждая попытка с кодом 0 и `docker stop` ≤ 1 с, есть `import`, остановленный ранним обработчиком, и `running`. Проекты compose не трогает, свои контейнеры удаляет по метке `mtusi.stop-at-start`. Вывод — `evidence/failover/stop-at-start.md` |
@@ -184,6 +184,7 @@ make reconcile APPLY=1 [MAX_CHANGES=N] # то же с исправлени
python3 $D --port 8080 reconcile-cycle # расхождения с обеих сторон: dry-run, --apply, 404/200, повтор = 0, возврат оригинала; ~2 мин
python3 $D --port 8080 reconcile-stress # --apply раз в 3 с под загрузками 4 клиентов 40 с: все 201 скачиваются с тем же SHA-256
COMPOSE_PROJECT_NAME=<временный> python3 $D reconcile-signal # pause s3 + docker stop разового --apply: код 1, interrupted_by stop; не на mtusi-lab4
COMPOSE_PROJECT_NAME=<временный> python3 $D reconcile-signal --pace # docker stop во время паузы предела скорости: код 1, ≤ 1 с
python3 $D --port 8080 s3-idle # клиент S3 после скачиваний и простоя: у образа 0 испорченных соединений и упавших PUT, эталон портит; ~40 с
python3 $D lb-upload-timeouts # сроки LB пути загрузки на заглушке: 201 после 12 с молчания, 504 через 10/30 с, 400 в формате контракта; ~35 с
docker compose logs --no-log-prefix cleaner | tail -3 # уборщик: Started cleaner (60/900/100), проходы, отказы
+176 -33
View File
@@ -119,7 +119,12 @@
--apply, через секунду после «Started cleaner» docker stop;
interrupted_by stop, «Stopped cleaner» с exit_code 1, остановка
быстрее stop_grace_period 10 с; S3 размораживается в finally;
код 1 при расхождении
код 1 при расхождении. --pace (change track2-reconcile-cost):
вместо pause s3 — объекты пробы мимо API (botocore в одноразовом
контейнере api его ключами), reconcile --max-objects-per-second
1, docker stop через 2 с после «Started cleaner» во время паузы
предела скорости — остановка не дольше секунды; объекты
удаляются в finally
s3-idle [--rounds 3] [--downloads 10] [--puts 12] [--size-mib 4]
[--pause-ms 0.5] только стенд с LB: спеки object-storage
«Вызов после простоя» и attachments «Загрузка после простоя
@@ -3644,15 +3649,81 @@ RS_START_TIMEOUT_S = 30
RS_AFTER_START_S = 1.0
# stop_grace_period уборщика в docker-compose.yml: дольше — был бы SIGKILL
RS_STOP_LIMIT_S = 10
# режим --pace (design change track2-reconcile-cost, решение 14): пауза
# предела скорости вместо замороженного S3. Объекты под префиксом вложений
# с ключом, которого API не пишет (чужие для сверки): при пределе 1 объект/с
# проход после страницы списка ждёт столько секунд, сколько ключей
RS_PACE_OBJECTS = 8
RS_PACE_RATE = "1"
RS_PACE_AFTER_START_S = 2.0
# остановка во время паузы — не позже секунды после сигнала
RS_PACE_STOP_LIMIT_S = 1.0
# объекты пробы — botocore в одноразовом контейнере сервиса api его
# ключами из окружения (как put-object hook стенда отказов); в argv и
# вывод ключи не попадают
RS_PACE_OBJECTS_PY = r"""
import os, sys
import botocore.session
from botocore.config import Config
s3 = botocore.session.get_session().create_client(
"s3",
endpoint_url=f"http://{os.environ['S3__HOST']}:{os.environ['S3__PORT']}",
region_name="us-east-1",
aws_access_key_id=os.environ["S3__ACCESS_KEY_ID"],
aws_secret_access_key=os.environ["S3__SECRET_ACCESS_KEY"],
config=Config(s3={"addressing_style": "path"}),
)
bucket = os.environ["S3__BUCKET"]
prefix = os.environ["DATABASE__NAME"] + "/attachments/pace-signal-"
for i in range(int(sys.argv[2])):
key = f"{prefix}{i}"
if sys.argv[1] == "put":
s3.put_object(Bucket=bucket, Key=key, Body=b"pace", ContentType="image/png")
else:
s3.delete_object(Bucket=bucket, Key=key)
print(f"{sys.argv[1]} {sys.argv[2]} objects")
"""
def cmd_reconcile_signal() -> int:
def rfc3339_ns(text: str) -> int:
"""`2026-10-23T01:33:32.338748123Z` (Docker) → наносекунды эпохи;
без `fromisoformat`: Python 3.9 не принимает `Z` и наносекунды."""
base, _, rest = text.strip().partition(".")
digits = "".join(ch for ch in rest if ch.isdigit())
moment = datetime.strptime(base.rstrip("Z"), "%Y-%m-%dT%H:%M:%S")
seconds = int(moment.replace(tzinfo=UTC).timestamp())
return seconds * 10**9 + int((digits + "0" * 9)[:9])
def rs_pace_objects(action: str) -> None:
"""`put` или `delete` объектов пробы режима `--pace`."""
compose(
"run",
"--rm",
"--no-deps",
"-T",
"--entrypoint",
"python",
"api",
"-",
action,
str(RS_PACE_OBJECTS),
stdin=RS_PACE_OBJECTS_PY,
)
def cmd_reconcile_signal(*, pace: bool = False) -> int:
"""Спек `graceful-shutdown`, разовый проход сверки, прерванный сигналом,
— код 1: на стенде проекта compose из окружения (`COMPOSE_PROJECT_NAME`
и др., рабочий `mtusi-lab4` — отказ, код 2) `docker compose pause s3`,
`run -d --no-deps cleaner reconcile --apply`, через секунду после
«Started cleaner» — `docker stop`; S3 размораживается в `finally`.
Таблица и записи процесса без секретов; код 1 при расхождении."""
`pace` — вместо замороженного S3 пауза предела скорости: объекты пробы,
`reconcile --max-objects-per-second 1` (dry-run), `docker stop` через
2 с после «Started cleaner», остановка не дольше секунды; объекты
удаляются в `finally`. Таблица и записи процесса без секретов; код 1
при расхождении."""
try:
config = json.loads(compose("config", "--format", "json"))
except (RuntimeError, ValueError) as e:
@@ -3661,8 +3732,8 @@ def cmd_reconcile_signal() -> int:
project = str(config.get("name", ""))
if project == RS_WORKING_PROJECT:
print(
"reconcile-signal pauses S3: run it on a temporary stand "
f"(COMPOSE_PROJECT_NAME), not {RS_WORKING_PROJECT}",
"reconcile-signal pauses S3 or adds probe objects: run it on a "
f"temporary stand (COMPOSE_PROJECT_NAME), not {RS_WORKING_PROJECT}",
)
return 2
services = config.get("services", {})
@@ -3676,21 +3747,23 @@ def cmd_reconcile_signal() -> int:
subprocess.run(["docker", "rm", "-f", name], capture_output=True)
started = False
took = -1.0
after_signal = -1.0
exit_code = ""
logs = ""
compose("pause", "s3")
print(f"{project}: s3 paused")
if pace:
rs_pace_objects("put")
print(f"{project}: {RS_PACE_OBJECTS} probe objects put")
args = ["reconcile", "--max-objects-per-second", RS_PACE_RATE]
after_start, limit = RS_PACE_AFTER_START_S, RS_PACE_STOP_LIMIT_S
waiting = "the rate limit pause"
else:
compose("pause", "s3")
print(f"{project}: s3 paused")
args = ["reconcile", "--apply"]
after_start, limit = RS_AFTER_START_S, float(RS_STOP_LIMIT_S)
waiting = "paused S3"
try:
compose(
"run",
"-d",
"--no-deps",
"--name",
name,
"cleaner",
"reconcile",
"--apply",
)
compose("run", "-d", "--no-deps", "--name", name, "cleaner", *args)
deadline = time.monotonic() + RS_START_TIMEOUT_S
while time.monotonic() < deadline:
logs = docker_logs(name)
@@ -3699,28 +3772,68 @@ def cmd_reconcile_signal() -> int:
break
time.sleep(0.2)
if started:
time.sleep(RS_AFTER_START_S)
print("docker stop while reconcile waits for paused S3")
time.sleep(after_start)
print(f"docker stop while reconcile waits for {waiting}")
# момент сигнала — событие kill Docker (часы ВМ, как FinishedAt):
# время docker stop включает ещё разбор контейнера демоном
events = subprocess.Popen(
[
"docker",
"events",
"--filter",
f"container={name}",
"--filter",
"event=kill",
"--format",
"{{.TimeNano}}",
],
stdout=subprocess.PIPE,
stderr=subprocess.DEVNULL,
text=True,
)
time.sleep(0.3)
began = time.monotonic()
subprocess.run(["docker", "stop", name], capture_output=True)
took = time.monotonic() - began
exit_code = subprocess.run(
["docker", "inspect", "-f", "{{.State.ExitCode}}", name],
capture_output=True,
text=True,
check=False,
).stdout.strip()
time.sleep(0.3)
events.terminate()
kill_lines = (events.communicate()[0] or "").split()
exit_code, finished_at = (
subprocess.run(
[
"docker",
"inspect",
"-f",
"{{.State.ExitCode}}|{{.State.FinishedAt}}",
name,
],
capture_output=True,
text=True,
check=False,
).stdout.strip()
+ "|"
).split("|")[:2]
if kill_lines and finished_at:
after_signal = (
rfc3339_ns(finished_at) - int(kill_lines[0])
) / 1e9
logs = docker_logs(name)
finally:
subprocess.run(["docker", "rm", "-f", name], capture_output=True)
compose("unpause", "s3")
print(f"{project}: s3 unpaused")
if pace:
rs_pace_objects("delete")
print(f"{project}: probe objects deleted")
else:
compose("unpause", "s3")
print(f"{project}: s3 unpaused")
records = []
for line in logs.splitlines():
if line.startswith("{"):
with contextlib.suppress(json.JSONDecodeError):
records.append(json.loads(line))
shown = ("event", "level", "mode", "operation", "error_type")
shown += ("reconcile_max_objects_per_second", "listed_objects")
shown += ("storage_objects", "max_objects_per_second")
shown += ("duration_ms", "interrupted_by", "exit_code", "timestamp")
print("== records of the one-off reconcile")
for record in records:
@@ -3734,7 +3847,11 @@ def cmd_reconcile_signal() -> int:
stopped = [
item for item in records if item.get("event") == "Stopped cleaner"
]
print(f"docker stop took {took:.1f} s, exit code {exit_code or '-'}")
print(
f"docker stop took {took:.1f} s, container exited "
f"{after_signal:.2f} s after the kill event, exit code "
f"{exit_code or '-'}",
)
rows = [
("Started cleaner (mode reconcile)", "yes", yes(started)),
("exit code", "1", exit_code),
@@ -3754,14 +3871,39 @@ def cmd_reconcile_signal() -> int:
str(len(rc_events(records, RC_FIXED))),
),
(
f"docker stop faster than {RS_STOP_LIMIT_S} s",
f"exited within {limit:g} s after the signal"
if pace
else f"docker stop faster than {limit:g} s",
"yes",
yes(0 <= took < RS_STOP_LIMIT_S),
yes(0 <= after_signal <= limit if pace else 0 <= took < limit),
),
]
if pace:
rate = next(
(
item.get("reconcile_max_objects_per_second")
for item in records
if item.get("event") == "Started cleaner"
),
None,
)
rows.insert(
1,
(
"Started cleaner reconcile_max_objects_per_second",
RS_PACE_RATE,
"-" if rate is None else f"{float(rate):g}",
),
)
return report_reconcile(
rows,
passed="one-off reconcile stopped by SIGTERM: exit 1, nothing changed",
passed=(
"one-off reconcile stopped by SIGTERM during the rate limit "
"pause: exit 1 within a second"
if pace
else "one-off reconcile stopped by SIGTERM: exit 1, nothing "
"changed"
),
)
@@ -4999,7 +5141,8 @@ def main() -> int:
stress = sub.add_parser("reconcile-stress")
stress.add_argument("--seconds", type=float, default=40)
stress.add_argument("--clients", type=int, default=4)
sub.add_parser("reconcile-signal")
signal_cmd = sub.add_parser("reconcile-signal")
signal_cmd.add_argument("--pace", action="store_true")
idle_s3 = sub.add_parser("s3-idle")
idle_s3.add_argument("--rounds", type=int, default=3)
idle_s3.add_argument("--downloads", type=int, default=10)
@@ -5113,7 +5256,7 @@ def main() -> int:
clients=args.clients,
)
if args.cmd == "reconcile-signal":
return cmd_reconcile_signal()
return cmd_reconcile_signal(pace=args.pace)
if args.cmd == "s3-idle":
return cmd_s3_idle(
port,
+2
View File
@@ -38,6 +38,8 @@ evidence/failover/quick-*/
evidence/rollout/quick-*/
# make bench_uploads_quick: то же для профиля загрузок
evidence/uploads/quick-*/
# make bench_reconcile_quick: то же для профиля сверки
evidence/reconcile/quick-reconcile-*/
# сравнения пробных меток
evidence/compare/*quick-*
# make bench_plots на пробных метках
+36 -14
View File
@@ -41,7 +41,14 @@ LB пути загрузки 30 с, дренаж замены 90 с, профи
S3 нет срока чтения aiohttp (он переживал ответ и портил соединение в
пуле), срок — только `asyncio.timeout` вызова и блока; четвёртый API
стенда отказов со сроком S3 1 с (`test_upload_after_idle_s3`), проба
`driver.py s3-idle`. План работ, решения и
`driver.py s3-idle`. Стоимость сверки (трек 2) — change
`track2-reconcile-cost` (активный,
`openspec/changes/track2-reconcile-cost/`): стратегия «HEAD на строку» и
глубокая сверка (класс «другой SHA-256», пометку снимает только тот же
SHA-256) в разовом проходе, предел скорости `[reconciler]
max_objects_per_second` (2000 объектов S3/с), отказ по пределу без
лишних перепроверок, стоимость прохода в его итоге, профиль `reconcile`
стенда `bench/`. План работ, решения и
трек «5» — `PLAN.md`. Из лабы 2: PostgreSQL
как источник истины, вход по Basic → Bearer-сессия, Valkey — кэш
карточек чатов. Из лабы 3: HAProxy перед ≥2 репликами API
@@ -55,7 +62,8 @@ S3 нет срока чтения aiohttp (он переживал ответ и
`profile-resources`). Changes лаб 2 и 3 и `s3-storage`, `attachments`,
`upload-consistency`, `upload-memory`, `track2-reconciler`,
`fix-upload-put-flake` лабы 4 — в
`openspec/changes/archive/`, активных нет, спеки синхронизированы
`openspec/changes/archive/`, активный — `track2-reconcile-cost` (его
дельты уже синхронизированы в основные спеки), спеки синхронизированы
(новые capability: с `s3-storage` —
`object-storage`, с `attachments` — `attachments`, с
`upload-consistency` — `storage-consistency`); в `KNOWN_ISSUES.md` три открытые записи (bootstrap после удаления
@@ -180,7 +188,16 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
201 (вопрос преподавателю, `PLAN.md`). Уборщику разрешён список только
с префиксом `<база>/attachments/` (`S3_CLEANER_LIST_PREFIX` у
bootstrap). На время восстановления базы уборщик останавливают
(`docker.md`).
(`docker.md`). С change `track2-reconcile-cost`: проход затрагивает в
среднем не больше `[reconciler] max_objects_per_second` (2000; 0 — без
предела) объектов S3 в секунду, паузу прерывает сигнал; разовый проход
— ещё `--strategy head` (выборка строки на объект, HEAD на строку, без
множества ключей) и `--deep` (GET и SHA-256: «другой SHA-256» помечается
потерянным), плановая — всегда `batch`, поверхностная; «оригинал
вернулся» — только тот же SHA-256; с `--apply`, как только
подтверждённых изменений больше предела, остальные кандидаты не
перепроверяются (`unchecked`); итог называет стоимость — объекты и
запросы S3, байты, сеансы, длительность шагов (`service-layer.md`).
- Лаба 4, память загрузок (change `upload-memory`): память загрузок
реплики ограничена числом мест, а не числом клиентов. Место берётся
после проверок 401/400/404/415/413 и до чтения тела, держится до
@@ -374,10 +391,12 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
| `driver.py --port <LB> upload-consistency` | согласованность БД и S3 на рабочем стенде (~45 с): загрузка при `pause` S3 и со сбоем фиксации `ready` (триггер на `filename` прогона) — 503, строки `pending` не видны, компенсация удалила объект; `cleaner --once` с grace 30 с убирает обе, объектов без строки нет, готовое вложение цело; `evidence/attachments/consistency.md` |
| `driver.py lb-upload-timeouts [--config F]` | сроки LB пути загрузки без стенда (~35 с): `haproxy -c`, временная сеть, HAProxy закреплённого образа с F (по умолчанию `infra/haproxy/haproxy.cfg`) и заглушка реплики `api` на образе API; молчание 12 с до и после тела загрузки — 201, 12 с на другом пути — 504 через ~10 с, 32 с на пути загрузки — 504 через ~30 с, клиент молчит посреди тела — 400 в формате контракта; уборка при любом исходе, код 1 при расхождении; `evidence/uploads/lb-timeouts.md` |
| `driver.py --port <LB> s3-idle [--rounds 3]` | клиент S3 после простоя (~40 с, change `fix-upload-put-flake`): проба в реплике стенда (`docker exec -i … python -`, код и ключи образа), варианты «образ» и «эталон» с прежним `read_timeout` aiohttp; раунд — 10 одновременных медленных скачиваний 4 MiB, простой срока вызова + 0,5 с, 12 PUT; взведённые и испорченные соединения пула, PUT прошло и упало (цепочка ошибки, мс), чтение обратно; объекты под `<база>/.s3-idle-probe/` удаляются в `finally`; код 0 — у образа ни порчи, ни упавших PUT, 1 — иначе, 2 — нет стенда; `evidence/s3/idle-connection.md` |
| `make reconcile [APPLY=1] [MAX_CHANGES=N]` | разовая сверка bucket и БД в контейнере уборщика (`docker compose run --rm --no-deps cleaner reconcile [--apply] [--max-changes N]`): по умолчанию dry-run — записи «Found storage discrepancy» по классам и итог; `APPLY=1` — исправить; 0 — расхождений нет, 3 — остались (чужие объекты, отказ по пределу), 1 — прервана, 2 — конфигурация |
| `make reconcile [APPLY=1] [MAX_CHANGES=N] [STRATEGY=head] [DEEP=1] [RATE=R]` | разовая сверка bucket и БД в контейнере уборщика (`docker compose run --rm --no-deps cleaner reconcile [--apply] [--max-changes N] [--strategy batch\|head] [--deep] [--max-objects-per-second R]`): по умолчанию dry-run — записи «Found storage discrepancy» по классам и итог со стоимостью прохода; `APPLY=1` — исправить; `STRATEGY=head` — HEAD на строку, `DEEP=1` — SHA-256 содержимого, `RATE` — предел скорости (0 — без него); 0 — расхождений нет, 3 — остались (чужие объекты, отказ по пределу), 1 — прервана, 2 — конфигурация |
| `driver.py --port <LB> reconcile-cycle` | сверка на рабочем стенде (~2 мин): исходный dry-run без расхождений (иначе код 2), расхождения с обеих сторон, dry-run без изменений, 500 → `--apply` → 404 и 200, повтор, удаление чужого объекта, свежий объект после grace, возврат оригинала; `evidence/reconcile/cycle.md` |
| `driver.py --port <LB> reconcile-stress [--seconds S] [--clients N]` | `--apply` раз в ~3 с под загрузками и отправками N клиентов S секунд (4 × 40 с): внесённое исправлено, каждое 201 скачивается с тем же SHA-256, повтор — 0; `evidence/reconcile/stress.md` |
| `driver.py reconcile-signal` | только не рабочий проект compose (`COMPOSE_PROJECT_NAME` и др., `mtusi-lab4` — код 2): `pause s3`, разовый `reconcile --apply` отдельным контейнером, `docker stop` через секунду после «Started cleaner» — код 1, `interrupted_by: stop`, «Stopped cleaner» с `exit_code` 1, быстрее 10 с; `unpause` в `finally`; `evidence/reconcile/service.md` |
| `driver.py reconcile-signal [--pace]` | только не рабочий проект compose (`COMPOSE_PROJECT_NAME` и др., `mtusi-lab4` — код 2): `pause s3`, разовый `reconcile --apply` отдельным контейнером, `docker stop` через секунду после «Started cleaner» — код 1, `interrupted_by: stop`, «Stopped cleaner» с `exit_code` 1, быстрее 10 с; `unpause` в `finally`. `--pace` (change `track2-reconcile-cost`) — вместо `pause s3` объекты пробы мимо API и `reconcile --max-objects-per-second 1`, `docker stop` через 2 с во время паузы предела скорости — остановка ≤ 1 с; объекты удаляются в `finally`; `evidence/reconcile/service.md` |
| `make bench_reconcile [RECONCILE_LABEL=...]` | трек 2, стоимость сверки (~50 мин, метка `baseline`; change `track2-reconcile-cost`): стенд `mtusi-bench` с LB, двумя репликами, PostgreSQL, Valkey и S3 с лимитами рабочего стенда, порт метрик шлюза S3 на loopback; наполнение мимо API (`\copy` метаданных, PUT объектов загрузчиком `bench/fill_objects.py`), 1 000 × 1 MiB и 10k → 30k → 100k × 4 KiB с 0,25 % расхождений каждого класса; разовые проходы уборщика (0,25 CPU / 256 МБ, управляемый опыт — 1 CPU): `batch`, `head`, глубокая, фоновая нагрузка с пределом скорости и без, отказ по пределу на образе `Profile.reconcile_before` (`7f4e626`) и checkout; 3 повтора, найденное сверяется с моделью (иначе отказ), счёт сверки — с метриками шлюза; `evidence/reconcile/<метка>/` (`passes.csv`, `windows.csv`, `summary.md` с H1–H4 и S4, SVG). Перед запуском — проверка хоста (`bench.md`), рабочий стенд — `make stop` |
| `make bench_reconcile_quick` | то же на 2 000 × 4 KiB, по одному проходу каждого вида, окна 5 с, S4 с 300 кандидатами (~4 мин), метка `quick-reconcile-<время>`, в git не идёт |
| `docker compose run --rm --no-deps cleaner --once` | разовый проход уборщика незавершённых загрузок (grace — `[cleaner]` или `-e CLEANER__PENDING_GRACE_SECONDS=…`, не меньше 18 с): 0 — проход дошёл до конца, 1 — прерван отказом, 2 — неверная конфигурация; журнал сервиса — `docker compose logs --no-log-prefix cleaner` |
| `make lb_stats` | слоты HAProxy: адрес, состояние проверки (`DRAIN`, `MAINT` при замене), запросы, повторы, перенаправления (CSV статистики изнутри контейнера LB) |
| `make rolling_update [COMMIT=...] [MIGRATE=0]` | поочерёдная замена реплик без простоя (`scripts/rolling-update.sh`, `balancer.md`): сборка из рабочего дерева (или файлов `COMMIT` через `git archive`), миграции один раз, затем по одной — новая `healthy` и `UP` в LB, старая `drain` → запросов в полёте 0 → `maint` → stop → rm → слот `ready`. Нужен штатный стенд (`make replicas`) без слотов LB в ручном `drain` / `maint` (иначе код 2 и команда `set server … state ready`); сбой и Ctrl+C — `API_REPLICAS` готовых реплик, повтор доводит; `MIGRATE=0` — откат на прежний образ (после него `docker compose up` без сборки не запускать: `migrate` прежнего образа упадёт на новой ревизии) |
@@ -423,8 +442,8 @@ src/
__main__.py # python -m src: early_stop.install() до импорта приложения → main.main()
main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run
cleaner/__main__.py # python -m src.cleaner [--once]: early_stop.install("cleaner") до импорта → main(); неверные настройки — запись без значений и код 2
cleaner/main.py # уборщик незавершённых загрузок: проверка grace > 2 × request_timeout + s3 timeout (иначе код 2), свой engine и клиент S3, цикл с интервалом и плановой сверкой (при старте и раз в [reconciler] interval_seconds), SIGTERM — довести текущий шаг и выйти 0, --once — коды 0/1/2; reconcile [--apply] [--max-changes N] — разовая сверка, коды 0/3/1/2
config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds, [uploads] max_concurrent 4, max_waiting 16, wait_timeout_seconds 5, body_timeout_seconds 30 (места загрузок процесса API), [cleaner] interval_seconds 60, pending_grace_seconds 900, batch_size 100, [reconciler] interval_seconds 3600, page_size 1000, max_changes 100
cleaner/main.py # уборщик незавершённых загрузок: проверка grace > 2 × request_timeout + s3 timeout (иначе код 2), свой engine и клиент S3, цикл с интервалом и плановой сверкой (при старте и раз в [reconciler] interval_seconds), SIGTERM — довести текущий шаг и выйти 0, --once — коды 0/1/2; reconcile [--apply] [--max-changes N] [--strategy batch|head] [--deep] [--max-objects-per-second R] — разовая сверка, коды 0/3/1/2; плановая — batch, поверхностная, предел скорости из настроек
config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds, [uploads] max_concurrent 4, max_waiting 16, wait_timeout_seconds 5, body_timeout_seconds 30 (места загрузок процесса API), [cleaner] interval_seconds 60, pending_grace_seconds 900, batch_size 100, [reconciler] interval_seconds 3600, page_size 1000, max_changes 100, max_objects_per_second 2000 (предел скорости сверки; 0 — без него)
api/
routers/health.py # /health/live, /health/ready: вне версии, без идентификации
routers/v1/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py); attachment.py — один роутер с двумя префиксами: загрузка (тело через request.stream(), схема — openapi_extra, строгий UTF-8 filename по scope["query_string"]), метаданные, байты StreamingResponse
@@ -442,7 +461,7 @@ src/
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией
services/attachment.py # AttachmentService(db_scope, cache, storage, slots): загрузка (проверки → место загрузки, 429 → тело со счётчиком и сроком в BytesIO, 400 по сроку → структура и SHA-256 в потоке над getvalue() → del → pending → PUT тем же BytesIO → ready; сбой ready до COMMIT или пропавшая строка — удаление объекта и 503; место — до ответа), метаданные, отдача потоком
services/attachment_cleanup.py # AttachmentCleanupService(db_scope, storage): проход уборщика — кандидаты keyset, каждая строка в два шага (remove_stale_pending): блокировка и пометка (commit) → блокировка, DELETE объекта и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO
services/attachment_reconcile.py # AttachmentReconcileService(db_scope, storage): сверка bucket и БД — S3 → БД (страницы списка, выборка на страницу, множество ключей), БД → S3 (keyset ready; ключ строки вне префикса вложений — чужой объект без HEAD), зависшие, перепроверка в БД и HEAD (bucket — probe), сигнал — перед каждым вызовом хранилища, предел изменений, действия с apply (зависшие шагом уборщика → объекты без строки → пометки → снятия); журнал Found / Fixed / Finished; ReconcilePassDTO
services/attachment_reconcile.py # AttachmentReconcileService(db_scope, storage): сверка bucket и БД — S3 → БД (страницы списка, выборка на страницу, множество ключей), БД → S3 (keyset ready; ключ строки вне префикса вложений — чужой объект без HEAD), зависшие, перепроверка в БД и HEAD (bucket — probe), сигнал — перед каждым вызовом хранилища, предел изменений, действия с apply (зависшие шагом уборщика → объекты без строки → пометки → снятия); журнал Found / Fixed / Finished; ReconcilePassDTO. С change track2-reconcile-cost: strategy head (выборка строки на объект, HEAD на строку, без множества), deep (GET и SHA-256 потоком, checksum_mismatch; «оригинал вернулся» — тот же SHA-256), предел скорости после каждого вызова S3 (_pace, куски 0,2 с с сигналом), ранний отказ по пределу (unchecked), счёт сеансов обёрткой db_scope, стоимость в итоге (storage_objects, s3_requests, read_bytes, db_sessions, phase_ms)
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва и срока тела (UploadTimedOut), 429 занятых мест (UploadsBusy), 500 пропавшего объекта
infra/
early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog
@@ -456,7 +475,7 @@ src/
db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit; attachment.py — Attachment (частичный индекс pending по (created_at, id), lost_at — пометка потерянного оригинала) и MessageAttachment (порядок position, FK без каскада)
cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск
cache/instance.py # глобал cache процесса API
s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put (поток read/seek/tell и size) / head / open (чтение блоками) / delete / list_page (ListObjectsV2 по префиксу, нет bucket — ошибка), срок на вызов и блок — единственный срок клиента (read_timeout aiohttp выключен: переживал ответ и портил соединение в пуле, change fix-upload-put-flake), ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo (с last_modified), StoredObject, StoredObjectPage
s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put (поток read/seek/tell и size) / head / open (чтение блоками) / delete / list_page (ListObjectsV2 по префиксу, нет bucket — ошибка), срок на вызов и блок — единственный срок клиента (read_timeout aiohttp выключен: переживал ответ и портил соединение в пуле, change fix-upload-put-flake), ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo (с last_modified, у open — тоже), StoredObject, StoredObjectPage; счётчики попыток по операциям, ключей списка и прочитанных байт — stats() → StorageStats (change track2-reconcile-cost)
s3/instance.py # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan
schemas/
dataclasses/<domain>.py # DTO между repo → service → api
@@ -480,20 +499,22 @@ student-tests/ # black-box тесты по HTTP (уровень 4)
test_failures.py # проверки отказов (маркер fault): только make failure_checks
run_isolated.py # make test_isolated: образ на временной базе test_<db>, уборка базы и префикса test_<db>/ в S3 (weed shell fs.rm, затем проверка fs.ls: код 0 weed shell успеха не значит; префикс только из проверенного имени) (stdlib)
run_failures.py # make failure_checks: стенд <рабочий>-failures (Postgres, Valkey, S3 + bootstrap, уборщик с grace 20 с и интервалом 1 с без плановой сверки → FAULT_CLEANER_*, FAULT_RECONCILER_INTERVAL_S; уборщик с плановой сверкой <проект>-cleaner-scheduled убирается вместе с API), четыре API (обычный, «тесный», «узкий по загрузкам» с UPLOADS_ENV → FAULT_UPLOADS_BASE_URL / FAULT_UPLOADS_ENV, «с коротким сроком S3» с S3_ENV → FAULT_S3_BASE_URL / FAULT_S3_ENV), pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), журналы API и уборщика при падении, уборка (stdlib)
fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников, сообщений и вложений (fail-attachments insert|ready|stall|commit|outlive|undeletable: сбой вставки, перевода в ready до и на COMMIT, задержка, строка «старше grace» с ожиданием уборщика, неудаляемая строка), заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions, attachment-ids, last-pending, object-ids (файлы original по fs.tree), kill-api / start-api; расхождения и сверка (change track2-reconciler): put-object (тело — stdin, botocore в контейнере API его ключами) / delete-object (weed fs.rm) только под <база>/attachments/, delete-row, set-size, age-row, set-key (object_key строки под <база>/), lost-ids, fail-attachments mark, reconcile dry-run|apply [предел] (записи и exit_code=), stop|start cleaner, run-cleaner <с> (stdlib)
fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников, сообщений и вложений (fail-attachments insert|ready|stall|commit|outlive|undeletable: сбой вставки, перевода в ready до и на COMMIT, задержка, строка «старше grace» с ожиданием уборщика, неудаляемая строка), заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions, attachment-ids, last-pending, object-ids (файлы original по fs.tree), kill-api / start-api; расхождения и сверка (change track2-reconciler): put-object (тело — stdin, botocore в контейнере API его ключами) / delete-object (weed fs.rm) только под <база>/attachments/, delete-row, set-size, age-row, set-key (object_key строки под <база>/), lost-ids, fail-attachments mark, reconcile dry-run|apply [предел] [--strategy batch|head] [--deep] [--max-objects-per-second R] (аргументы по списку, записи и exit_code=), stop|start cleaner, run-cleaner <с> (stdlib)
failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, S3, LB), уборщик с CLEANER__* 20 / 1, RECONCILER__INTERVAL_SECONDS 0 и restart "no", stop_grace_period 2 с у S3, healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster)
bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling / bench_uploads (с S3)
run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json; профиль uploads (S3 и bootstrap на стенде, на прогон — новый volume S3 и реплика с окружением варианта через .work/variant.compose.yml, образ «до» — тег bench-from, сэмплер peak), в паспорте всех профилей stand.api_tcp_rmem и docker.kernel
run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json; профиль uploads (S3 и bootstrap на стенде, на прогон — новый volume S3 и реплика с окружением варианта через .work/variant.compose.yml, образ «до» — тег bench-from, сэмплер peak), в паспорте всех профилей stand.api_tcp_rmem и docker.kernel; профиль reconcile (S3 с портом метрик через .work/s3-metrics.compose.yml, наполнение \copy и загрузчиком, разовые проходы mtusi-bench-reconcile-<n> с лимитом CPU варианта, «до» — .work/cleaner-before.compose.yml, метрики шлюза и pg_stat_database до и после, блок H4 с k6 background.js, отказ по пределу S4)
scaling.py # серии трека 1 без docker: лестница и автомат поиска R*, разбор итога k6 и строк сэмплера, агрегаты окна, вердикт SLO и брака генератора, признаки узкого места (THRESHOLDS), предельный CPU на запрос, сводка серии; --selftest
plots.py # make bench_plots: SVG на stdlib (R* от числа реплик, p95 от интенсивности, CPU по компонентам) и сводка с точкой насыщения; render_series — графики в каталоге метки
sampler.sh # сэмплер (только в контейнере mtusi-bench-sampler на образе PostgreSQL, --cgroupns host): режим list (серии) — cpu.stat, память и PSI заданных контейнеров, /proc/stat и PSI ВМ, статистика HAProxy, psql \watch по pg_stat_activity / database / wal / io; режим scan (failover, rollout) — обход cgroup всех контейнеров и /proc/stat, без сети, psql и LB; режим peak (uploads) — сброс memory.peak реплики, S3 и LB через свой дескриптор (perl), чтение пика в конце окна, выборка current / anon / sock / oom_kill раз в 0,2 с (--user 0, cgroupfs rw, без сети)
uploads.py # профиль uploads без docker: тела PNG из шума от зерна, план кругами, разбор строк k6 и сэмплера peak, строка runs.csv, пометки oom / host_swap / peak_sampled / s3_down, summary.md (медиана и min–max по ячейкам, сценарии спеков, H1–H4); --selftest
reconcile.py # профиль reconcile без docker (change track2-reconcile-cost): модель набора (id, содержимое и класс по номеру и зерну, строки CSV для \copy, ожидаемое по классам), план кругами, разбор записей уборщика, метрик шлюза S3, строк bg k6 и сэмплера, окна и r / a H4, passes.csv и windows.csv, вердикты H1–H4 и S4, summary.md и SVG (plots.Svg); --selftest
fill_objects.py # загрузчик объектов профиля reconcile: только в контейнере mtusi-bench-fill на образе стенда (botocore образа, bench/ на чтение, ключи API из окружения), процессы × потоки PUT по модели reconcile.py
resources.py # ресурсы профилей failover и rollout без docker: интервалы контейнеров (сброс при новой cgroup, заморозка, новые контейнеры с момента запуска), окна, CPU / троттлинг / память по компонентам и ВМ, CPU на запрос в установившихся окнах, resources.csv / samples.csv, разделы summary.md; --selftest
failover.py # профиль failover без docker: строки k6 о запросах, статистика и журнал HAProxy, события Docker, посекундная шкала, величины фазы, summary.md
rollout.py # профиль rollout без docker: строки скрипта замены, события контейнеров проекта, состояния слотов LB (UP, drain, maint, ready), шаги по репликам, шкала со старыми и новыми ответами, окна до / во время / после, summary.md
bench.compose.yml # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain; s3 (лимиты BENCH_S3_*, swap = память) запускает только профиль uploads, cleaner описан (mtusi-bench-cleaner, без порта), но профили его не запускают; буфер приёма реплики — sysctls основного compose
bench.compose.yml # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain; s3 (лимиты BENCH_S3_*, swap = память) запускают профили uploads и reconcile, cleaner (mtusi-bench-cleaner, без порта, лимиты BENCH_CLEANER_* без swap) — только разовыми проходами профиля reconcile; буфер приёма реплики — sysctls основного compose
bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей и секретов S3: их генерирует run.py)
k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом), mixed (ступень серии трека 1: ramping-arrival-rate 70/20/10, тег окна, распределение по X-Instance-Id, досрочный выход), uploads (constant-vus загрузок тела из /work, пауза Retry-After на 429 и 1 с на прочие ошибки, строка на запрос, WARMUP — одна загрузка); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы
k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом), mixed (ступень серии трека 1: ramping-arrival-rate 70/20/10, тег окна, распределение по X-Instance-Id, досрочный выход), uploads (constant-vus загрузок тела из /work, пауза Retry-After на 429 и 1 с на прочие ошибки, строка на запрос, WARMUP — одна загрузка), background (профиль reconcile: constant-arrival-rate скачиваний, записи и чтения истории, строка bg на запрос, остановка SIGINT); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы
compare.py # make bench_compare: дельта двух меток (ячейки матрицы или общие конфигурации серий), уровень шума, эффект или шум; отказ при разной методике, в том числе метке без LB и серии против матрицы
ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд, с --series — серии трека 1
migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose; 739b8f04d5fb — частичный индекс pending CONCURRENTLY в autocommit_block; 5c3e1f0a9b7d — attachments.lost_at (NULL, SET LOCAL lock_timeout)
@@ -510,7 +531,8 @@ docker-compose.yml # проект mtusi-lab4: postgres, valkey, s3 (Se
config_example.toml, .env.example
evidence/attachments/ # change attachments: smoke.md, failover.md (driver.py attachment-failover stop и kill), storage.md (driver.py attachment-storage), slow-transfer.md (10 MiB через LB дольше 6 с); change upload-consistency: consistency.md (driver.py upload-consistency и журналы API и уборщика), cleaner-process.md (старт, отказ конфигурации, остановка, окно 0, рестарт хранилищ, отказ S3 во время прохода)
evidence/s3/ # change s3-storage: bootstrap.md (первый запуск, повтор, смена секрета, ошибка шага, до bootstrap), privacy.md (make s3_check, нарушение и исправление, порты, секреты по сервисам), grpc-admin.md (gRPC шлюза без токена), restart.md (restart.sh и SIGKILL S3), client.md (операции, pause/stop, неверный секрет, журнал), memory.md (20 × 10 MiB PUT); change upload-consistency: cleaner-key.md (пользователь уборщика в bootstrap, смена секрета, make s3_check с ключом уборщика, секреты по сервисам); change track2-reconciler: cleaner-list.md (bootstrap с политикой списка по префиксу, неверный префикс, make s3_check со строками списка уборщика, окружение s3-bootstrap)
evidence/reconcile/ # change track2-reconciler: cycle.md (driver.py reconcile-cycle), stress.md (driver.py reconcile-stress), service.md (Started cleaner с параметрами сверки, плановая сверка при старте, docker stop во время сверки при pause s3, код 1 разового прохода по сигналу — driver.py reconcile-signal, отказ старта на RECONCILER__*, коды 3 и 0)
evidence/reconcile/ # change track2-reconciler: cycle.md (driver.py reconcile-cycle), stress.md (driver.py reconcile-stress), service.md (Started cleaner с параметрами сверки, плановая сверка при старте, docker stop во время сверки при pause s3, код 1 разового прохода по сигналу — driver.py reconcile-signal, отказ старта на RECONCILER__*, коды 3 и 0; с change track2-reconcile-cost — остановка во время паузы предела скорости, driver.py reconcile-signal --pace)
evidence/reconcile/<метка>/ # результаты make bench_reconcile (change track2-reconcile-cost): meta.json (раздел reconcile: план, этапы и модели, commit и образы «до», аргументы S3), passes.csv, windows.csv, summary.md (H1–H4 и S4), cost-by-n.svg, requests-by-n.svg, background-p95.svg, raw/ (записи уборщика по проходам, итог k6 блока H4)
evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции; лаба 4: pending-index.md (ревизия 739b8f04d5fb с нуля, повтор, откат, EXPLAIN общего плана кандидатов уборщика на рабочей базе с откатом, rollout_quick), lost-at.md (ревизия 5c3e1f0a9b7d колонки lost_at: с нуля, повтор, откат, --sql с lock_timeout, make rolling_update с ревизией до и после)
evidence/auth/ # passwords-and-tokens.md — driver.py auth-storage на стенде текущей лабы: Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump (исключения сверки покрытия)
+28 -3
View File
@@ -210,11 +210,15 @@ s3_check:
# разовая сверка bucket и БД в контейнере уборщика (образ собирает
# make run_docker): по умолчанию dry-run — отчёт без изменений; APPLY=1 —
# исправить, MAX_CHANGES=N — предел изменений прохода вместо [reconciler]
# max_changes. Код 0 — расхождений нет, 3 — остались, 1 — прерван, 2 —
# конфигурация (design change track2-reconciler, решения 1 и 8)
# max_changes; STRATEGY=head — HEAD на строку вместо страниц, DEEP=1 —
# глубокая (SHA-256 содержимого), RATE=R — предел скорости, объектов S3 в
# секунду (0 — без предела) вместо [reconciler] max_objects_per_second.
# Код 0 — расхождений нет, 3 — остались, 1 — прерван, 2 — конфигурация
# (design change track2-reconciler, решения 1 и 8; track2-reconcile-cost,
# решения 4–6)
.PHONY: reconcile
reconcile:
$(DC) run --rm --no-deps cleaner reconcile$(if $(filter 1,$(APPLY)), --apply)$(if $(MAX_CHANGES), --max-changes $(MAX_CHANGES))
$(DC) run --rm --no-deps cleaner reconcile$(if $(filter 1,$(APPLY)), --apply)$(if $(MAX_CHANGES), --max-changes $(MAX_CHANGES))$(if $(STRATEGY), --strategy $(STRATEGY))$(if $(filter 1,$(DEEP)), --deep)$(if $(RATE), --max-objects-per-second $(RATE))
# -------------------------
@@ -363,6 +367,27 @@ bench_uploads:
bench_uploads_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile uploads_quick --label quick-uploads-$(shell date -u +%Y%m%dT%H%M%SZ)
RECONCILE_LABEL ?= baseline
# трек 2 «5» лабы 4: стоимость сверки bucket и БД на стенде mtusi-bench
# (HAProxy, две реплики, PostgreSQL, Valkey и S3 с лимитами рабочего
# стенда, разовые проходы уборщика 0,25 CPU / 256 МБ, в управляемом опыте
# 1 CPU): наполнение мимо API, этапы 1 000 × 1 MiB и 10k → 30k → 100k ×
# 4 KiB, стратегии batch и head, глубокая сверка, фоновая нагрузка с
# пределом скорости и без, отказ по пределу на образе до change
# (Profile.reconcile_before) и checkout, 3 повтора; ~50 мин; результат —
# evidence/reconcile/$(RECONCILE_LABEL)/ (design change track2-reconcile-cost)
.PHONY: bench_reconcile
bench_reconcile:
$(KEEP_AWAKE) uv run python bench/run.py --profile reconcile --label $(RECONCILE_LABEL)
# то же коротко (самопроверка): 2 000 × 4 KiB, по одному проходу каждого
# вида, окна под нагрузкой по 5 с, отказ по пределу с 300 кандидатами,
# ~6 мин; в git не идёт
.PHONY: bench_reconcile_quick
bench_reconcile_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile reconcile_quick --label quick-reconcile-$(shell date -u +%Y%m%dT%H%M%SZ)
SCALING_LABEL ?= scaling-$(SERIES)
# уровень 5, трек 1 «Цена масштабирования»: серия на стенде mtusi-bench —
+46
View File
@@ -1515,6 +1515,52 @@ compose `rccost`, тот же `docker-compose.yml`, образ рабочего
— на `7f4e626`. Остановку во время паузы предела проверяет `driver.py
reconcile-signal --pace` → `evidence/reconcile/service.md`.
Решения apply (2026-10-23, `/opsx:apply` без пользователя; подробно —
design, «Уточнения apply», пп. 1–13):
13. Пауза предела скорости — после каждого вызова S3: иначе последний
вызов прохода предел не ограничивал бы (п. 1).
14. GET отдаёт `last_modified`, находка несёт SHA-256 строки; глубокая и
свежесть, вернувшийся объект с другим SHA-256 — `lost_known` (пп. 2–5).
15. Hook и тесты: позиционный предел и флаги по одному разу; тест предела
скорости — своя потеря и остановленный уборщик (пп. 6–7).
16. Быстрый профиль — два свежих стенда (S4 — свой), k6 блока H4
останавливается `pkill -INT`, длительности — 0,01 мс (пп. 8–9).
17. Память в H1 и H2 — наклон и рост пика от N, а не прирост прохода:
постоянная часть прохода ~14 МиБ (п. 10).
18. Модель сверяется в каждом проходе (`found`, `listed_objects`,
`checked_rows`), окно шага списка — справочно (пп. 11–12).
19. `reconcile-signal --pace` — объекты пробы, иначе на пустом bucket
паузы нет; остановка — от события `kill` до `FinishedAt` (п. 13).
Проверка на временном проекте `rcpace` (tmpfs, без портов): до правки
п. 14 — 1,16 с (FAIL), после — 0,22 с, код драйвера 0; режим без
`--pace` — PASS (4,6 с при замороженном S3). Проект убран: volumes
155, сети 17.
20. Уборщик выходит `os._exit` после `main()`: финализация
интерпретатора при 0,25 CPU — 0,8–1,5 с, остановка по сигналу иначе
больше секунды (п. 14).
21. Красный прогон 1.3 (`make failure_checks FAULT_ARGS='-k "head_strategy
or deep_checksum or restore_needs or rate_limit or limit_stops"'`,
код `7f4e626`, тесты из дерева): 5 failed за 117 с — `head` и предел
скорости — argparse (пустой отчёт, нет итога), глубокая — нет поля
`deep`, восстановление — пометку снял другой объект того же размера,
предел — `changes` 7 вместо 3. Затем все 16 тестов сверки на дереве —
16 passed за 500 с.
22. `make bench_reconcile_quick` на дереве (хост тихий: все контейнеры,
включая рабочий стенд и `domains-*`, остановлены пользователем; дерево
грязное): первый — код 0 за 3 мин 39 с, после правок пп. 16–17 —
код 0 за 3 мин 30 с (быстрее оценки design ~6 мин). 9 проходов,
найденное = внесённому, `count_mismatch` нет, 5xx фона нет, строки k6
= итерациям; volumes 155, сети 17, тег `bench-from` снят. Во втором у
проходов 1 CPU (0,3 и 1,1 с) CPU уборщика не посчитан — окно короче
отсчёта сэмплера в конце жизни контейнера; исправлено
(`reconcile.window_cpu` — по охватывающим отсчётам).
23. Регресс `bench/`: `make bench_quick` — complete 18/18 за 3 мин 26 с,
`make bench_uploads_quick` — complete 6/6 за 4 мин 9 с (у «без лимита»
при 40 × 10 MiB — OOM, как у метки `baseline`); `--selftest`
`uploads`, `resources`, `scaling`, `failover`, `rollout`,
`reconcile` — код 0.
#### Вопросы
Нет. Вопрос 1 раздела `### track2-reconciler` (ответ API на потерянный
+13 -6
View File
@@ -62,12 +62,13 @@ services:
memswap_limit: ${BENCH_S3_MEMORY:?run make bench}
# уборщик незавершённых загрузок (design change upload-consistency,
# решение 9) описан, как s3, и тоже не запускается: старт стенда
# перечисляет сервисы, реплики — с --no-deps. Если его всё же запустят —
# образ стенда, без config.toml рабочего стенда, без перезапуска и без
# плановой сверки bucket и БД: профиль сверки (change
# track2-reconcile-cost) задаст её интервал сам (design change
# track2-reconciler, решение 9)
# решение 9) описан, как s3; сервис не запускается: старт стенда
# перечисляет сервисы, реплики — с --no-deps. Профиль сверки (change
# track2-reconcile-cost, решения 1 и 3) запускает его разовыми проходами
# `docker compose run --name mtusi-bench-reconcile-<n> cleaner reconcile`.
# Образ стенда, без config.toml рабочего стенда, без перезапуска и без
# плановой сверки bucket и БД; лимиты BENCH_CLEANER_* без swap — рабочего
# стенда, в управляемом опыте — CPU варианта
cleaner:
container_name: mtusi-bench-cleaner
image: mtusi-messenger:bench
@@ -75,6 +76,12 @@ services:
volumes: !reset []
environment:
RECONCILER__INTERVAL_SECONDS: "0"
deploy:
resources:
limits:
cpus: ${BENCH_CLEANER_CPUS:?run make bench}
memory: ${BENCH_CLEANER_MEMORY:?run make bench}
memswap_limit: ${BENCH_CLEANER_MEMORY:?run make bench}
migrate:
image: mtusi-messenger:bench
+116
View File
@@ -0,0 +1,116 @@
"""Загрузчик объектов профиля сверки: прямой PUT в S3 стенда мимо API.
Работает только в контейнере `mtusi-bench-fill` на образе стенда
(`mtusi-messenger:bench`): botocore образа, `src` не импортируется, каталог
`bench/` смонтирован только на чтение, номера, ключи и содержимое объектов
— генератор набора `bench/reconcile.py` (design change
`track2-reconcile-cost`, решение 3). Ключи пользователя API — окружение
контейнера (`S3__ACCESS_KEY_ID`, `S3__SECRET_ACCESS_KEY`: `docker run -e
<имя>` без значения в argv); в вывод они не попадают.
Объекты — номера диапазона [--start, --end), у которых по модели набора
есть объект; несколько процессов по нескольку потоков, у каждого процесса
свой клиент. Вывод — одна строка `fill: <объектов> objects, <PUT/с>
put/s, <с> s`; ошибка любого PUT — код 1.
"""
import argparse
import os
import sys
import time
from concurrent.futures import ThreadPoolExecutor
from multiprocessing import Pool
from pathlib import Path
from typing import Any
sys.path.insert(0, str(Path(__file__).resolve().parent))
import reconcile # noqa: E402
KEY_ENV = ("S3__ACCESS_KEY_ID", "S3__SECRET_ACCESS_KEY")
def client(endpoint: str, threads: int) -> Any:
import botocore.session
from botocore.config import Config
session = botocore.session.get_session()
return session.create_client(
"s3",
endpoint_url=endpoint,
region_name="us-east-1",
aws_access_key_id=os.environ[KEY_ENV[0]],
aws_secret_access_key=os.environ[KEY_ENV[1]],
config=Config(
s3={"addressing_style": "path"},
retries={"total_max_attempts": 3},
max_pool_connections=threads,
),
)
def put_chunk(job: tuple[dict[str, Any], list[int]]) -> int:
"""Один процесс: свой клиент, потоки по номерам; число записанных."""
args, indices = job
s3 = client(args["endpoint"], args["threads"])
def put(index: int) -> None:
attachment_id = reconcile.object_id(args["seed"], index)
s3.put_object(
Bucket=args["bucket"],
Key=reconcile.object_key(args["namespace"], attachment_id),
Body=reconcile.content(args["seed"], index, args["size"]),
ContentType=reconcile.CONTENT_TYPE,
)
with ThreadPoolExecutor(max_workers=args["threads"]) as pool:
for _ in pool.map(put, indices):
pass
return len(indices)
def main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--endpoint", required=True)
parser.add_argument("--bucket", required=True)
parser.add_argument("--namespace", required=True)
parser.add_argument("--seed", type=int, required=True)
parser.add_argument("--start", type=int, required=True)
parser.add_argument("--end", type=int, required=True)
parser.add_argument("--size", type=int, required=True)
parser.add_argument("--force", choices=(reconcile.FORCE_OK,))
parser.add_argument("--processes", type=int, default=3)
parser.add_argument("--threads", type=int, default=24)
args = parser.parse_args(argv)
if not Path("/.dockerenv").exists():
print("fill: run only in the bench container", flush=True)
return 2
if any(not os.environ.get(name) for name in KEY_ENV):
print(f"fill: {' and '.join(KEY_ENV)} are required", flush=True)
return 2
indices = reconcile.object_indices(args.start, args.end, args.force)
parts = [indices[i :: args.processes] for i in range(args.processes)]
shared = {
key: getattr(args, key)
for key in ("endpoint", "bucket", "namespace", "seed", "size")
}
shared["threads"] = args.threads
started = time.monotonic()
try:
with Pool(args.processes) as pool:
done = sum(pool.map(put_chunk, [(shared, p) for p in parts if p]))
except Exception as exc:
# без текста исключения botocore: в нём может быть адрес и заголовки
print(f"fill: put failed ({type(exc).__name__})", flush=True)
return 1
seconds = time.monotonic() - started
print(
f"fill: {done} objects, {done / seconds if seconds else 0:.0f} "
f"put/s, {seconds:.1f} s",
flush=True,
)
return 0 if done == len(indices) else 1
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
+125
View File
@@ -0,0 +1,125 @@
// Фоновая нагрузка профиля сверки (design change track2-reconcile-cost,
// решение 10): открытая модель, три сценария constant-arrival-rate через
// LB — скачивания оригиналов вложений набора (`/work/downloads.json` от
// run.py; читатель фикстуры — владелец и участник чата набора), запись
// сообщений в чат записи и чтение его первой страницы истории. Каждый
// запрос — строка «bg,<d|w|r>,<отправка мс>,<длительность мс>,<статус>» в
// файл консоли k6; run.py делит их на окна до, во время и после прохода
// сверки и сверяет число строк с итерациями сценариев. Оркестратор
// останавливает прогон сигналом SIGINT, когда блок проходов закончен:
// итог (handleSummary) k6 пишет и тогда.
import exec from "k6/execution";
import http from "k6/http";
import { SharedArray } from "k6/data";
import {
API,
PAGE_LIMIT,
SUMMARY_THRESHOLDS,
SUMMARY_TREND_STATS,
WORK_DIR,
authHeaders,
messageHeaders,
summaryFiles,
syntheticText,
} from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const ids = new SharedArray(
"downloads",
() => JSON.parse(open(`${WORK_DIR}/downloads.json`)),
);
const DURATION = __ENV.DURATION || "1h";
const PRE_VUS = Number(__ENV.PRE_VUS || 100);
const MAX_VUS = Number(__ENV.MAX_VUS || 600);
const TIMEOUT = __ENV.TIMEOUT || "15s";
const READER = authHeaders(fixture.tokens[fixture.readerId]);
const WRITE_URL = `${API}/chats/${fixture.writeChatId}/messages`;
function scenario(fn, rate) {
return {
executor: "constant-arrival-rate",
exec: fn,
rate,
timeUnit: "1s",
duration: DURATION,
preAllocatedVUs: PRE_VUS,
maxVUs: MAX_VUS,
gracefulStop: "5s",
};
}
export const options = {
scenarios: {
download: scenario("download", Number(__ENV.DOWNLOAD_RATE)),
write: scenario("write", Number(__ENV.WRITE_RATE)),
read: scenario("read", Number(__ENV.READ_RATE)),
},
summaryTrendStats: SUMMARY_TREND_STATS,
// пороги всегда выполняются: подметрики итераций по сценариям попадают
// в итог, и run.py сверяет с ними число строк о запросах
thresholds: {
...SUMMARY_THRESHOLDS,
"iterations{scenario:download}": ["count>=0"],
"iterations{scenario:write}": ["count>=0"],
"iterations{scenario:read}": ["count>=0"],
},
};
// длительность — по монотонным таймингам k6 (как в failover.js), с точностью
// 0,01 мс: p95 чтения истории — единицы миллисекунд, и целые мс огрубляли
// бы отношение r; без ответа (status 0) — разность часов
function report(kind, start, res) {
const t = res.timings;
const measured = t.blocked + t.connecting + t.tls_handshaking + t.duration;
const duration = Math.max(
0,
Math.round((res.status === 0 ? Date.now() - start : measured) * 100) / 100,
);
console.log(`bg,${kind},${start},${duration},${res.status}`);
}
export function download() {
const n = exec.scenario.iterationInTest;
const id = ids[n % ids.length];
const start = Date.now();
const res = http.get(`${API}/attachments/${id}/content`, {
headers: READER,
responseType: "none",
timeout: TIMEOUT,
responseCallback: http.expectedStatuses(200),
});
report("d", start, res);
}
export function write() {
const n = exec.scenario.iterationInTest;
const sender = fixture.memberIds[n % fixture.memberIds.length];
const start = Date.now();
const res = http.post(
WRITE_URL,
JSON.stringify({ text: syntheticText("bg", n) }),
{
headers: messageHeaders(fixture.tokens[sender]),
responseType: "none",
timeout: TIMEOUT,
responseCallback: http.expectedStatuses(201),
},
);
report("w", start, res);
}
export function read() {
const start = Date.now();
const res = http.get(`${WRITE_URL}?limit=${PAGE_LIMIT}`, {
headers: READER,
responseType: "none",
timeout: TIMEOUT,
responseCallback: http.expectedStatuses(200),
});
report("r", start, res);
}
export function handleSummary(data) {
return summaryFiles(data);
}
+1908
View File
File diff suppressed because it is too large Load Diff
+1015 -12
View File
File diff suppressed because it is too large Load Diff
+4
View File
@@ -117,3 +117,7 @@ page_size = 1000
# предел изменений за проход: больше — ни одного изменения и код 3;
# разовый проход принимает больший аргументом --max-changes
max_changes = 100
# предел скорости прохода: объектов S3 в секунду (ключи страниц списка,
# HEAD, GET, DELETE) в среднем от начала прохода; 0 — без предела;
# разовый проход принимает другой аргументом --max-objects-per-second
max_objects_per_second = 2000
@@ -785,6 +785,78 @@ change» → описано в нём.
доказательств;
- `PLAN.md`.
### Уточнения apply
Решения, принятые в `/opsx:apply` без пользователя (он недоступен), — то
же в `PLAN.md`, `### track2-reconcile-cost`, «Решения apply».
1. **Пауза предела — после вызова S3, а не перед следующим** (решение 6).
Перед вызовом остаётся проверка сигнала. Пауза «до следующего» не
ограничивала бы последний вызов прохода: проход из одной страницы
списка не ждал бы вовсе, и сценарий «Скорость прохода ограничена»
(длительность ≥ объектов / предел) не выполнялся бы. Средняя скорость
от начала прохода та же; DELETE шага уборки — `_pace` после
`remove_stale_pending`.
2. **`StoredObjectInfo.last_modified` и у `open` (GET)** (решения 4–5):
глубокая сверка `head` читает объект сразу, без HEAD, и свежесть
объекта проверяет по `LastModified` ответа GET. Поведение вызова не
меняется — в метаданных одно поле больше.
3. **`ReconcileFindingDTO.sha256`** — SHA-256 строки в находке: по нему
действие (`_fix`) сверяет заново прочитанный объект без лишней выборки
строки. В журнал не попадает (`_record` перечисляет поля сам).
4. **Глубокая сверка и свежесть** (решение 5): строка моложе grace —
`fresh_rows`, объект моложе grace — `fresh_objects`, ни тот, ни другой
не читается; объект исчез или изменил размер после списка — без
находки (следующий проход). Обе стратегии считают одинаково.
5. **Вернувшийся объект с другим SHA-256** — `lost_known` (пометка на
месте), а не находка: отчёт его вернувшимся не называет.
6. **Hook** (решение 14): предел изменений — первым позиционным
аргументом, флаги — по одному разу; иначе код 2.
7. **Тест предела скорости**: восемь загрузок (объектов хватает и на
свежем стенде, `-k rate_limit`), своя потеря оригинала — сравнение
своих находок; уборщик стенда стоит на время двух проходов, иначе
зависшая загрузка соседнего теста могла бы стать «старше grace» между
ними.
8. **Быстрый профиль — два свежих стенда**, а не один (решение 1): S4 на
стенде с внесёнными классами убрал бы зависшие загрузки первым же
`--apply`, и найденное у «до» и «после» разошлось бы с моделью.
Цена — ~40 с.
9. **Остановка k6 блока H4** — `docker exec mtusi-bench-k6 pkill -INT -f
background.js`: по SIGINT k6 завершает сценарии и пишет итог; строки
`bg,…` сверяются с итерациями так же, как у `failover`. Длительность —
с точностью 0,01 мс: p95 чтения истории — единицы миллисекунд, и целые
мс огрубляли `r` (быстрый профиль: `r` чтения 3,0 из 1 и 3 мс).
10. **Память в H1 и H2** (решение 12): выборка «в начале прохода» по
отсчётам 0,5 с ловит процесс до прогрева клиентов (быстрый профиль:
44–89 МиБ, рост ~14 МиБ на 2 000 объектов — постоянная часть, не
множество). Поэтому H1 — наклон пика памяти `batch` между наименьшим и
наибольшим N (Б на ключ), H2 — рост пика `head` между N; прирост
прохода на объект остаётся столбцом `passes.csv`. Гипотезы в
`REPORT.md` записаны в этой форме до метки.
11. **Каждый проход сверяет с моделью** ещё `listed_objects` и
`checked_rows`, не только первый проход этапа; S4 — без ожидания grace:
у его объектов есть строки, свежесть на находки не влияет.
12. **Окно шага списка** (решение 10, справочно) — строка `list` в
`windows.csv`, в вердикт не входит.
13. **`driver.py reconcile-signal --pace`** кладёт 8 объектов пробы под
`<база>/attachments/pace-signal-*` (botocore в одноразовом контейнере
`api` его ключами): на пустом bucket временного стенда проход не
затронул бы ни одного объекта и не ждал бы. Объекты удаляются в
`finally`. Остановка меряется от события `kill` Docker до
`State.FinishedAt` (оба — часы ВМ); время `docker stop` (CLI и разбор
контейнера демоном) печатается рядом.
14. **Выход уборщика без финализации интерпретатора** (спек
`graceful-shutdown`, «docker stop во время паузы предела скорости»).
Проба на временном стенде: пауза прерывается за ~0,2 с после сигнала
(«Stopped cleaner» через 0,18 с), но процесс выходил ещё через
0,8–1,5 с — финализация модулей botocore и SQLAlchemy при 0,25 CPU (у
обычного прохода без сигнала — те же ~0,8 с). Итог — 1,16–1,5 с, больше
секунды спека. `src/cleaner/__main__.py` после `main()` сбрасывает
stdout и stderr и выходит `os._exit(code)`: engine и клиент S3 к этому
моменту закрыты, записи уже в stdout. После правки — 0,22 с от сигнала
до выхода. Ошибки argparse и непредвиденные исключения выходят как
раньше (до `os._exit` не доходят).
## Risks / Trade-offs
- **[Предел 2000/с удлиняет плановый проход вдвое]** → на 100k с ~30 до
+26 -26
View File
@@ -37,7 +37,7 @@ Evidence и метка — только с закоммиченного кода
## 1. Hook, тесты и красный прогон
- [ ] 1.1 `student-tests/fault_hook.py` (только stdlib, синтаксис 3.9),
- [x] 1.1 `student-tests/fault_hook.py` (только stdlib, синтаксис 3.9),
действие `reconcile dry-run|apply [<предел>]` по решению 14:
- необязательные `--strategy head`, `--deep` и
`--max-objects-per-second R`;
@@ -47,7 +47,7 @@ Evidence и метка — только с закоммиченного кода
- docstring hook называет новые аргументы.
Проверка: `make lint`; поведение — задача 1.3.
- [ ] 1.2 `student-tests/test_failures.py`, маркер `fault`, пять тестов по
- [x] 1.2 `student-tests/test_failures.py`, маркер `fault`, пять тестов по
таблице решения 14 с `@pytest.mark.spec("storage-consistency", …)` на
каждый новый сценарий:
- `test_reconcile_head_strategy_same_findings`;
@@ -60,7 +60,7 @@ Evidence и метка — только с закоммиченного кода
записями того же прохода (`Reconcile.assert_code_matches`), как тесты
`track2-reconciler`. Байты «другие того же размера» — свои для каждого
теста, от зерна. Проверка: задача 1.3.
- [ ] 1.3 Красный прогон до кода групп 2–4 (дерево с 1.1–1.2, код
- [x] 1.3 Красный прогон до кода групп 2–4 (дерево с 1.1–1.2, код
`7f4e626`):
```
@@ -74,7 +74,7 @@ Evidence и метка — только с закоммиченного кода
## 2. Настройки, enum и DTO
- [ ] 2.1 `src/config/settings.py`, класс `Reconciler`:
- [x] 2.1 `src/config/settings.py`, класс `Reconciler`:
`max_objects_per_second: float = Field(default=2000, ge=0)` с
комментарием о единице и 0 (решение 6, дельта
`service-configuration`). Ещё строка в `config_example.toml`.
@@ -84,7 +84,7 @@ Evidence и метка — только с закоммиченного кода
- `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`:
- [x] 2.2 `src/schemas/enums/attachment.py`:
- `ReconcileFinding.CHECKSUM_MISMATCH = "checksum_mismatch"` с
комментарием;
- `ReconcileStrategy` (`batch`, `head`).
@@ -98,7 +98,7 @@ Evidence и метка — только с закоммиченного кода
## 3. Счётчики клиента S3
- [ ] 3.1 `src/infra/s3/client.py` по решению 8:
- [x] 3.1 `src/infra/s3/client.py` по решению 8:
- `ObjectStorage` считает попытки вызовов по операциям (`list`,
`head`, `get`, `delete`, `put`) в `_call`, ключи страниц — в
`list_page`, прочитанные байты — в `_read_chunk`;
@@ -112,7 +112,7 @@ Evidence и метка — только с закоммиченного кода
## 4. Сервис сверки и процесс уборщика
- [ ] 4.1 `AttachmentReconcileService.reconcile(…, strategy, deep,
- [x] 4.1 `AttachmentReconcileService.reconcile(…, strategy, deep,
max_objects_per_second, …)` по решениям 6, 8 и 15:
- темп перед каждым вызовом S3 рядом с `_check_stop`. Счёт затронутых
объектов — дельта `storage.stats()` от начала прохода, ожидание —
@@ -124,7 +124,7 @@ Evidence и метка — только с закоммиченного кода
Проверка: тесты `…_rate_limit` и `…_head_strategy_same_findings`
(поле `db_sessions`) зелёные в задаче 5.2.
- [ ] 4.2 Ранний отказ по пределу по решению 7:
- [x] 4.2 Ранний отказ по пределу по решению 7:
- в `_recheck_all` при `apply`, как только подтверждённых классов под
пределом (вместе с `checksum_mismatch`) больше `max_changes`,
остальные кандидаты этих классов не перепроверяются и идут в
@@ -134,7 +134,7 @@ Evidence и метка — только с закоммиченного кода
Проверка: `…_limit_stops_rechecks` и прежние
`test_reconcile_change_limit`, `…_limit_keeps_cleanup` — зелёные (5.2).
- [ ] 4.3 Глубокая сверка по решению 5:
- [x] 4.3 Глубокая сверка по решению 5:
- с `--deep` — GET и SHA-256 потоком (`open_original`, блоки клиента)
у строк `ready` без пометки, старше grace и того же размера;
- класс `checksum_mismatch` — в `LIMITED_KINDS` (пометка под
@@ -146,7 +146,7 @@ Evidence и метка — только с закоммиченного кода
Проверка: `…_deep_checksum`, `…_restore_needs_same_bytes`,
`test_reconcile_restored_original` — зелёные (5.2).
- [ ] 4.4 Стратегия `head` по решению 4:
- [x] 4.4 Стратегия `head` по решению 4:
- шаг S3 → БД — выборка строки на объект (`get_attachments_for_objects`
с одним элементом); строки с тем же ключом пропускаются;
- шаг БД → S3 — HEAD на строку своей базы (с `--deep` — GET);
@@ -155,7 +155,7 @@ Evidence и метка — только с закоммиченного кода
Проверка: `…_head_strategy_same_findings` зелёный (5.2); на 10k в
задаче 6.7 `found` равен внесённому.
- [ ] 4.5 `src/cleaner/main.py`:
- [x] 4.5 `src/cleaner/main.py`:
- аргументы `reconcile` — `--strategy {batch,head}`, `--deep`,
`--max-objects-per-second R` (≥ 0, иначе ошибка argparse, код 2);
- плановая сверка — `batch`, без `--deep`, предел из настроек;
@@ -168,7 +168,7 @@ Evidence и метка — только с закоммиченного кода
## 5. Спеки и проверки отказов
- [ ] 5.1 Sync дельт в основные спеки — все шесть capability, как в
- [x] 5.1 Sync дельт в основные спеки — все шесть capability, как в
прежних changes. Purpose `storage-consistency` правится руками:
«стоимость обхода и стратегии описывает change» → описаны в этом
change. Проверка:
@@ -177,21 +177,21 @@ Evidence и метка — только с закоммиченного кода
покрытия без «unknown scenario»;
- новые сценарии `storage-consistency` считаются покрытыми проверками
отказов.
- [ ] 5.2 Полный `make failure_checks` на дереве после групп 2–4: все
- [x] 5.2 Полный `make failure_checks` на дереве после групп 2–4: все
проверки зелёные (49 прежних и 5 новых), журнал PostgreSQL без
признаков аварии, стенд отказов убран. Проверка: код 0, число и время в
выводе (ожидаемо дольше на ~1,5–2 мин).
## 6. Профиль `reconcile` стенда `bench/`
- [ ] 6.1 `bench/bench.compose.yml`, сервис `cleaner`: лимиты
- [x] 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) по решениям
- [x] 6.2 `bench/reconcile.py` (только stdlib, без docker) по решениям
2, 10–13:
- модель набора: `id`, содержимое и класс по номеру, строки CSV для
`\copy`, ожидаемые числа по этапам;
@@ -204,7 +204,7 @@ Evidence и метка — только с закоммиченного кода
- `--selftest` на синтетических журналах, метриках и строках.
Проверка: `uv run python bench/reconcile.py --selftest` — код 0.
- [ ] 6.3 `bench/fill_objects.py` по решению 3:
- [x] 6.3 `bench/fill_objects.py` по решению 3:
- работает только в контейнере на образе стенда, botocore образа, `src`
не импортирует;
- генератор набора — из `reconcile.py` (`/bench` только на чтение);
@@ -213,7 +213,7 @@ Evidence и метка — только с закоммиченного кода
- печатает число объектов и PUT/с, ошибка PUT — код 1.
Проверка: задача 6.7 — `listed_objects` равно модели.
- [ ] 6.4 `bench/k6/background.js` по решению 10:
- [x] 6.4 `bench/k6/background.js` по решению 10:
- три сценария `constant-arrival-rate` (скачивания из
`/work/downloads.json`, запись в чат записи, чтение его первой
страницы);
@@ -223,7 +223,7 @@ Evidence и метка — только с закоммиченного кода
Проверка: задача 6.7 — число строк равно итерациям итога k6, ответов
5xx нет.
- [ ] 6.5 `bench/run.py`, профили `reconcile` и `reconcile_quick` (поля
- [x] 6.5 `bench/run.py`, профили `reconcile` и `reconcile_quick` (поля
`Profile.reconcile_*` — целиком в `meta.json`) и `Bench.run_reconcile`
по решениям 1–3, 7–10, 13:
- S3 запускается у профилей загрузок и сверки;
@@ -247,13 +247,13 @@ Evidence и метка — только с закоммиченного кода
- строка хода на каждый проход.
Проверка — задача 6.7.
- [ ] 6.6 `Makefile`: цели `bench_reconcile [RECONCILE_LABEL=…]` и
- [x] 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` на дереве (шумный хост допустим).
- [x] 6.7 `make bench_reconcile_quick` на дереве (шумный хост допустим).
Проверка:
- код 0, все виды проходов;
- `found` равен внесённому;
@@ -264,14 +264,14 @@ Evidence и метка — только с закоммиченного кода
`mtusi-messenger:bench*`, которые профиль снимает сам).
Записать время и итог в `PLAN.md` (решения apply).
- [ ] 6.8 Регресс `bench/` после правок старта стенда: `make
- [x] 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) по
- [x] 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»;
@@ -284,7 +284,7 @@ Evidence и метка — только с закоммиченного кода
## 8. Правила и документы
- [ ] 8.1 Правила:
- [x] 8.1 Правила:
- `bench.md` — раздел «Профиль сверки (`reconcile`)» и строка таблицы
инструментов. Исключения границы: наполнение данных стенда `\copy`,
загрузчик в контейнере, метрики шлюза на loopback, разовые проходы
@@ -300,7 +300,7 @@ Evidence и метка — только с закоммиченного кода
- `dto.md` — enum и поля DTO.
Проверка: правила не противоречат design и дельтам.
- [ ] 8.2 AGENTS.md:
- [x] 8.2 AGENTS.md:
- абзац о лабе — change `track2-reconcile-cost`;
- таблица команд: `bench_reconcile`, `bench_reconcile_quick`, аргументы
`make reconcile`, `reconcile-signal --pace`;
@@ -311,10 +311,10 @@ Evidence и метка — только с закоммиченного кода
ранний отказ.
Проверка: все пути в AGENTS.md существуют.
- [ ] 8.3 `PLAN.md`, раздел `### track2-reconcile-cost` — решения apply
- [x] 8.3 `PLAN.md`, раздел `### track2-reconcile-cost` — решения apply
(«Решения») и вопросы, если появятся. Проверка: раздел есть, ссылки на
design.
- [ ] 8.4 `make lint`, `make check`, `make validate
- [x] 8.4 `make lint`, `make check`, `make validate
PYTHON=.venv/bin/python`, `openspec validate track2-reconcile-cost
--strict`. Проверка: все — код 0.
+12 -2
View File
@@ -203,8 +203,10 @@ SIGTERM и SIGINT, пришедшие процессу сервиса во вр
Так же — во время сверки bucket и БД. Текущий вызов S3 или шаг с
PostgreSQL доводится до конца или до отката. Новые страницы списка и
новые действия не начинаются. Сверку, прерванную сигналом, доводит
следующий проход, как прерванную отказом.
новые действия не начинаются. Ожидание из-за предела скорости сверки
(capability `storage-consistency`, «Скорость сверки») сигнал прерывает
сразу: остановка не ждёт конца паузы. Сверку, прерванную сигналом,
доводит следующий проход, как прерванную отказом.
Затем сервис уборщика SHALL выйти с кодом 0 раньше срока остановки
контейнера (10 с), а не по SIGKILL. Разовый проход сверки, прерванный
@@ -227,3 +229,11 @@ PostgreSQL доводится до конца или до отката. Новы
- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а
в журнале — итог сверки с причиной прерывания «остановка» и запись об
остановке уборщика
#### Scenario: docker stop во время паузы предела скорости
- **WHEN** `docker stop` выполняется для разового прохода сверки, пока
тот ждёт из-за предела скорости
- **THEN** контейнер останавливается не позже чем через секунду после
сигнала, код выхода 1, а в журнале — итог сверки с причиной прерывания
«остановка» и запись об остановке уборщика
+181 -11
View File
@@ -68,13 +68,14 @@ run_dev` / `make run_docker`). После завершения, в том чис
### Requirement: Фиксированный стенд
Стенд SHALL состоять из балансировщика (LB), реплик приложения,
PostgreSQL и Valkey. В профиле загрузок к ним SHALL добавляться S3 с
его bootstrap. Число реплик SHALL задаваться методикой, по умолчанию
PostgreSQL и Valkey. В профилях загрузок и сверки к ним SHALL
добавляться S3 с его bootstrap, а в профиле сверки — ещё разовые проходы
процесса уборщика. Число реплик SHALL задаваться методикой, по умолчанию
одна. Приложение SHALL запускаться в контейнерах из образа, собранного
из текущего checkout тем же `Dockerfile`. Исключения — профиль
поочерёдной замены и вариант «до» профиля загрузок. Они берут образ
commit, заданного методикой: образ собирается тем же `Dockerfile` из
файлов этого commit без изменения рабочего дерева. Профиль замены
поочерёдной замены и варианты «до» профилей загрузок и сверки. Они берут
образ commit, заданного методикой: образ собирается тем же `Dockerfile`
из файлов этого commit без изменения рабочего дерева. Профиль замены
заканчивается на образе текущего checkout. LB SHALL
запускаться из того же образа и с той же конфигурацией, что у рабочего
стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у
@@ -82,18 +83,22 @@ commit, заданного методикой: образ собирается
получает те же настройки образа плюс модуль записи планов, выключенный
вне снятия плана. S3 SHALL запускаться из того же образа и с теми же
аргументами сервера, что у рабочего стенда, а bucket и пользователей
создаёт тот же bootstrap. В сериях трека 1 предел соединений PostgreSQL
(`max_connections`) — параметр конфигурации серии, по умолчанию 100, как
у образа. Схема БД SHALL применяться миграциями до наполнения.
создаёт тот же 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 они одинаковы во всех
конфигурациях;
- у LB, PostgreSQL, Valkey, S3 и уборщика — свои лимиты CPU и памяти без
swap, заданные методикой; в серии трека 1 они одинаковы во всех
конфигурациях; у уборщика в управляемом опыте профиля сверки — другой
лимит CPU, тоже заданный методикой;
- у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без
swap, заданный методикой; в остальных профилях генератор без лимита.
@@ -166,6 +171,14 @@ docker-сети и обращаться к приложению через LB п
и лимитами, bootstrap завершился успешно, а образ и лимиты S3 и
ограничение буфера приёма реплики записаны в паспорт
#### Scenario: S3 и уборщик в профиле сверки
- **WHEN** запускается профиль сверки
- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами
и портом метрик только на loopback своего контейнера, bootstrap
завершился успешно, а аргументы S3, образы и лимиты S3 и уборщика
записаны в паспорт
### Requirement: Сценарии нагрузки
Стенд SHALL поддерживать два сценария с синтетическими данными
@@ -1946,3 +1959,160 @@ bootstrap между прогонами. К bucket и объектам он не
- **WHEN** проверяющий открывает раздел загрузок в `REPORT.md`
- **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки
метки, а числа совпадают со сводкой
### 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** у каждой гипотезы есть вывод со ссылкой на ячейки сводки
метки, а числа совпадают со сводкой
+15 -9
View File
@@ -473,30 +473,36 @@ grace SHALL быть описаны в `REPORT.md`.
- `page_size` — сколько ключей сверка берёт одной страницей списка S3
и сколько строк одним запросом к PostgreSQL, по умолчанию 1000, не
больше 1000;
- `max_changes` — предел изменений за проход, по умолчанию 100.
- `max_changes` — предел изменений за проход, по умолчанию 100;
- `max_objects_per_second` — предел скорости прохода: сколько объектов
S3 он затрагивает в секунду (capability `storage-consistency`,
«Скорость сверки»), по умолчанию 2000; 0 — без ограничения.
`interval_seconds` SHALL быть неотрицательным числом, `page_size` и
`max_changes` — целыми не меньше 1. Иначе уборщик MUST NOT стартовать
(требование «Некорректное значение останавливает запуск»).
`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]` не используют.
принимать предел изменений и предел скорости и аргументами команды.
Значения по умолчанию и их обоснование SHALL быть описаны в
`REPORT.md`. Реплики API секцию `[reconciler]` не используют.
#### Scenario: Параметры сверки по умолчанию
- **WHEN** уборщик запущен без секции `[reconciler]` и без переменных
`RECONCILER__*`
- **THEN** запись о его старте называет интервал сверки 3600 с,
страницу 1000 и предел изменений 100
страницу 1000, предел изменений 100 и предел скорости 2000 объектов в
секунду
#### Scenario: Неверный параметр сверки
- **WHEN** уборщик запускается с `RECONCILER__PAGE_SIZE=5000`,
`RECONCILER__MAX_CHANGES=0` или `RECONCILER__INTERVAL_SECONDS=-1`
`RECONCILER__MAX_CHANGES=0`, `RECONCILER__INTERVAL_SECONDS=-1` или
`RECONCILER__MAX_OBJECTS_PER_SECOND=-1`
- **THEN** уборщик не стартует, в журнале — ошибка проверки настроек с
именем поля
+27 -9
View File
@@ -180,16 +180,24 @@ traceback и `request_id` запроса.
журнал процесса уборщика JSON-записи в формате этой capability, в каждой
— `instance_id` процесса. Записи:
- запись о старте уборщика дополнительно называет интервал сверки,
размер страницы и предел изменений;
размер страницы, предел изменений и предел скорости, а у разового
прохода — ещё стратегию обхода и глубину;
- каждое найденное расхождение — класс, ключ объекта, `id` вложения,
если он известен, возраст, размеры объекта и метаданных, если они
разные. Уровень `warning`, если расхождение осталось, и `info`, если
проход с `--apply` его исправил, с названием действия;
- итог прохода — режим, сколько объектов и строк просмотрено, сколько
найдено и исправлено по классам, сколько свежих и уже помеченных,
длительность и причина прерывания. Уровень `info`, если расхождений не
осталось, иначе `warning`;
- превышение предела изменений — `error` с числом изменений и пределом;
- итог прохода — режим, стратегия, глубина, предел скорости, сколько
объектов и строк просмотрено, сколько найдено и исправлено по классам,
сколько свежих и уже помеченных, сколько кандидатов не перепроверено,
длительность и причина прерывания. Ещё итог называет стоимость
прохода: сколько объектов S3 он затронул, запросы к S3 по операциям
(список, запрос метаданных, чтение, удаление), сколько байтов объектов
прочитано, сколько было сеансов с PostgreSQL и длительность каждого
шага прохода. Уровень `info`, если расхождений не осталось, иначе
`warning`;
- превышение предела изменений — `error` с пределом, числом
подтверждённых изменений и числом кандидатов, которых проход не
перепроверял;
- отказ S3 или PostgreSQL — `warning`, непредвиденная ошибка — `error` с
traceback.
@@ -198,7 +206,8 @@ traceback и `request_id` запроса.
записи. Скачивание потерянного оригинала реплика API SHALL писать
записью уровня `info` с `id` вложения и ключом объекта, а не `error`.
Записи сверки MUST NOT содержать ключи доступа и секреты S3, ключ
подписи, подписи запросов, `filename` вложений и байты объектов.
подписи, подписи запросов, `filename` вложений, байты объектов и их
SHA-256.
#### Scenario: Журнал разового прохода
@@ -214,5 +223,14 @@ traceback и `request_id` запроса.
#### Scenario: Предел изменений в журнале
- **WHEN** сверка с `--apply` отказывается исправлять из-за предела
- **THEN** в журнале запись `error` с числом изменений и пределом, а
итог прохода — `warning`
- **THEN** в журнале запись `error` с пределом, числом подтверждённых
изменений и числом неперепроверенных кандидатов, а итог прохода —
`warning`
#### Scenario: Стоимость прохода в итоге
- **WHEN** выполняется разовая сверка с `--strategy head` и `--deep`
- **THEN** итог называет эту стратегию, глубину и предел скорости,
затронутые объекты S3, запросы к S3 по операциям, прочитанные байты,
сеансы с PostgreSQL и длительность каждого шага, а секретов S3,
`filename` и SHA-256 объектов в журнале нет
+141 -22
View File
@@ -9,10 +9,10 @@
- поведение уборщика при отказах хранилищ;
- сверка bucket и БД (трек 2, change `track2-reconciler`): классы
расхождений, разовый и плановый проход, правила безопасности, предел
изменений, потерянный оригинал и отказы хранилищ во время сверки.
Стоимость обхода и стратегии сверки описывает change
`track2-reconcile-cost`.
изменений, потерянный оригинал и отказы хранилищ во время сверки;
- стоимость обхода (change `track2-reconcile-cost`): стратегии обхода,
глубокая сверка и класс «другой SHA-256», предел скорости, отказ по
пределу без лишних перепроверок и стоимость прохода в его итоге.
## Requirements
@@ -168,7 +168,7 @@ S3 выполнил удаление уже после срока вызова.
Сверка SHALL сравнивать объекты вложений в bucket — ключи с префиксом
`<имя базы>/attachments/` — с метаданными вложений той же базы в
PostgreSQL и находить расхождения шести классов:
PostgreSQL и находить расхождения семи классов:
- **объект без метаданных** — объект с ключом вида
`<база>/attachments/<id>/original`, на который не ссылается ни одна
строка и для `id` которого строки нет;
@@ -176,12 +176,15 @@ PostgreSQL и находить расхождения шести классов:
метаданных в bucket нет;
- **другой размер** — вложение `ready`, размер объекта не равен
`size_bytes`;
- **другой SHA-256** — вложение `ready`, размер объекта равен
`size_bytes`, а SHA-256 его содержимого не равен SHA-256 из
метаданных. Этот класс ищет только глубокая сверка;
- **зависшая загрузка** — вложение в статусе «загружается» старше grace,
то же, что убирает уборщик (требование «Уборщик незавершённых
загрузок»);
- **оригинал вернулся** — оригинал вложения помечен потерянным
(требование «Потерянный оригинал»), а объект снова есть с тем же
размером;
размером и тем же SHA-256;
- **чужой объект** — то, что сверка не меняет и оставляет оператору:
- объект под префиксом вложений, ключа такого вида API не пишет;
- объект с ключом вида `<id>/original`, у строки которого другой ключ
@@ -194,8 +197,8 @@ PostgreSQL и находить расхождения шести классов:
плановым (требование «Плановая сверка»). Разовый проход по умолчанию
SHALL ничего не менять (dry-run). С `--apply` он SHALL исправлять:
- объект без метаданных — удалить объект;
- метаданные без объекта и другой размер — пометить оригинал вложения
потерянным;
- метаданные без объекта, другой размер и другой SHA-256 — пометить
оригинал вложения потерянным;
- зависшую загрузку — убрать тем же порядком, что уборщик;
- вернувшийся оригинал — снять пометку.
@@ -203,12 +206,38 @@ SHALL ничего не менять (dry-run). С `--apply` он SHALL испр
ведут к нему, — помечать или убирать: чужой объект попадает только в
отчёт.
Разовый проход SHALL принимать стратегию обхода:
- по умолчанию — страницы списка объектов и одно обращение к PostgreSQL
на страницу. Ключи списка сверка запоминает, а строки `ready`
сравнивает с ними;
- `--strategy head` — для каждого объекта списка отдельное обращение к
PostgreSQL, для каждой строки `ready` — запрос метаданных её объекта в
S3. Ключей списка сверка не запоминает.
Обе стратегии SHALL находить на одних данных одни и те же расхождения
тех же классов и подчиняться одним правилам безопасности (требование
«Безопасность сверки»).
По умолчанию сверка поверхностная: наличие и размер объекта, байты она
не читает. С `--deep` разовый проход SHALL ещё читать каждый объект
вложения `ready` того же размера, которому больше grace, и сравнивать
SHA-256 его содержимого с метаданными. Плановая сверка глубокой не
бывает (требование «Плановая сверка»).
Отчёт SHALL называть по каждому расхождению класс, ключ объекта, `id`
вложения, если он известен, и возраст. Итог прохода SHALL называть:
вложения, если он известен, и возраст. Исключение — кандидаты, которых
проход с `--apply` не перепроверял после отказа по пределу (требование
«Безопасность сверки»): итог называет их число. Итог прохода SHALL
называть:
- стратегию, глубину и предел скорости (требование «Скорость сверки»);
- сколько объектов и строк просмотрено;
- сколько расхождений найдено и исправлено по классам;
- сколько объектов и строк пропущено как свежие;
- сколько вложений уже помечены потерянными.
- сколько вложений уже помечены потерянными;
- сколько кандидатов не перепроверено;
- стоимость прохода: сколько объектов S3 он затронул, запросы к S3 по
операциям, сколько байтов объектов прочитано, сколько было сеансов с
PostgreSQL и сколько длился каждый шаг прохода.
После успешного исправления повторный проход SHALL не находить ни одного
исправимого расхождения.
@@ -249,6 +278,27 @@ SHALL ничего не менять (dry-run). С `--apply` он SHALL испр
- **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 удалять:
@@ -274,7 +324,10 @@ Grace — тот же, что у уборщика (capability `service-configura
нет, объект на месте и старше grace;
- метаданные без объекта и другой размер — вложение по-прежнему `ready`
с тем же ключом, а объекта по ключу нет или его размер другой;
- вернувшийся оригинал — пометка на месте, объект того же размера.
- другой SHA-256 — вложение по-прежнему `ready` с тем же ключом, объект
того же размера, а SHA-256 заново прочитанного содержимого другой;
- вернувшийся оригинал — пометка на месте, объект того же размера и
того же SHA-256 заново прочитанного содержимого.
Не подтвердилось — действие не выполняется. Отсутствие объекта MUST NOT
считаться подтверждённым, пока не проверено, что bucket на месте. Иначе
@@ -283,9 +336,15 @@ Grace — тот же, что у уборщика (capability `service-configura
Предел изменений: если за проход нужно удалить объекты, пометить
оригиналы или снять пометки больше чем у `[reconciler] max_changes`
вложений, сверка с `--apply` MUST NOT выполнять ни одно из этих
изменений. Она пишет ошибку с числом изменений и пределом и завершается
кодом 3. Разовый проход SHALL принимать больший предел аргументом.
Уборка зависших загрузок пределом не ограничена.
изменений. Как только подтверждённых таких изменений больше предела, она
SHALL перестать перепроверять остальных кандидатов этих классов: отказ
уже решён, а каждая перепроверка — обращения к PostgreSQL и S3, пока
уборка зависших загрузок ждёт. Она пишет ошибку с пределом и числом
подтверждённых изменений, которое больше предела, и завершается кодом
3. Итог называет, сколько кандидатов не перепроверено. Сверка без
`--apply` перепроверяет каждого кандидата. Разовый проход SHALL
принимать больший предел аргументом. Уборка зависших загрузок пределом
не ограничена.
Сверка, уборщик и две сверки одновременно SHALL не мешать друг другу:
- каждое действие безопасно повторять;
@@ -326,9 +385,19 @@ NOT читать и менять. Вложение, в метаданных ко
- **WHEN** расхождений, которые сверка исправила бы, больше предела, и
выполняется сверка с `--apply`
- **THEN** ни один объект не удалён, ни одно вложение не помечено,
ошибка называет число изменений и предел, код выхода 3
ошибка называет предел и число подтверждённых изменений больше него,
код выхода 3
- **AND** с пределом не меньше их числа повтор исправляет все
#### Scenario: Отказ по пределу без лишних перепроверок
- **WHEN** расхождений, которые сверка исправила бы, вдвое больше
предела, и выполняется сверка с `--apply`
- **THEN** ошибка называет предел и число подтверждённых изменений — на
одно больше предела, итог называет остальных кандидатов
неперепроверенными, ни одно вложение не помечено, код выхода 3
- **AND** сверка без `--apply` называет каждое из этих расхождений
#### Scenario: Предел не останавливает уборку зависших
- **WHEN** загрузка оборвалась между записью объекта и фиксацией `ready`
@@ -371,16 +440,20 @@ NOT читать и менять. Вложение, в метаданных ко
### Requirement: Потерянный оригинал
Если сверка подтвердила, что объекта готового вложения нет или его
размер другой, она SHALL пометить оригинал вложения потерянным и
записать время пометки в метаданные. Сверка не удаляет ни метаданные, ни
ссылки сообщений, ни объект другого размера. Байты сверка не
Если сверка подтвердила, что объекта готового вложения нет, его размер
другой или — у глубокой сверки — SHA-256 его содержимого другой, она
SHALL пометить оригинал вложения потерянным и записать время пометки в
метаданные. Сверка не удаляет ни метаданные, ни ссылки сообщений, ни
объект другого размера или другого содержимого. Байты сверка не
восстанавливает: их нет нигде. Что видит API для помеченного вложения —
capability `attachments`, «Скачивание оригинала».
Пометка MUST NOT менять поля вложения в ответах API, в том числе
`status` и `updated_at`. Пометку SHALL снимать сверка с `--apply`, когда
объект по ключу вложения снова есть и его размер равен `size_bytes`.
объект по ключу вложения снова есть, его размер равен `size_bytes`, а
SHA-256 содержимого — SHA-256 из метаданных. Чтобы это проверить, сверка
читает такой объект и без `--deep`. Объект того же размера с другим
содержимым пометку MUST NOT снимать.
#### Scenario: Оригинал вернулся
@@ -389,6 +462,16 @@ capability `attachments`, «Скачивание оригинала».
- **THEN** пометка снята, байты вложения скачиваются — 200 с тем же
SHA-256, а следующий проход не находит расхождений по этому вложению
#### Scenario: Вернулся другой объект того же размера
- **WHEN** оригинал вложения помечен потерянным, затем под его ключом
записаны другие байты того же размера, и выполняется сверка с
`--apply`
- **THEN** пометка на месте, скачивание — 404, а отчёт не называет это
вложение вернувшимся
- **AND** после записи тех же байтов, что были загружены, сверка с
`--apply` снимает пометку
### Requirement: Сверка при отказах хранилищ
Если S3 недоступен, не ответил за срок вызова, отказал в доступе или
@@ -423,14 +506,17 @@ bucket нет, либо недоступна PostgreSQL, проход сверк
разового прохода:
- при старте;
- затем не реже чем раз в `[reconciler] interval_seconds`;
- с пределом изменений из настроек.
- с пределом изменений и пределом скорости из настроек;
- стратегией по умолчанию и без глубокой сверки.
Значение 0 выключает плановую сверку. Плановая и разовая сверки — один
и тот же проход с теми же правилами безопасности.
Ограничение называется в `REPORT.md`. Пока идёт проход сверки, уборка
зависших загрузок ждёт его конца. Объект без метаданных на стенде живёт
не дольше суммы grace, интервала сверки и прохода.
не дольше суммы grace, интервала сверки и прохода. С пределом скорости
по умолчанию проход длится не меньше секунды на каждые 2000 затронутых
объектов S3 (требование «Скорость сверки»).
#### Scenario: Плановая сверка без команды
@@ -438,3 +524,36 @@ bucket нет, либо недоступна PostgreSQL, проход сверк
работает с коротким интервалом сверки
- **THEN** не позже интервала с запасом вложение помечено потерянным
без разового прохода, а в журнале уборщика есть итог сверки
### 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
+2 -1
View File
@@ -418,7 +418,8 @@ Hook стенда отказов SHALL уметь:
- удалить метаданные вложения, изменить в них размер и сдвинуть их
время в прошлое;
- выполнить разовую сверку — без изменений или с `--apply`, с заданным
пределом изменений — и вернуть её записи и код выхода;
пределом изменений, стратегией обхода, глубиной и пределом скорости —
и вернуть её записи и код выхода;
- остановить и запустить уборщика стенда, а также запустить отдельного
уборщика с коротким интервалом плановой сверки на заданное время и
вернуть его журнал.
+11 -1
View File
@@ -30,4 +30,14 @@ if __name__ == "__main__":
)
sys.exit(2)
sys.exit(main())
code = main()
# engine и клиент S3 закрыты, «Stopped cleaner» записан: выход без
# финализации интерпретатора. При 0,25 CPU она длится 0,8–1,5 с (модули
# botocore, SQLAlchemy), и остановка по сигналу во время паузы предела
# скорости не укладывалась бы в секунду (design change
# track2-reconcile-cost, «Уточнения apply», п. 14)
import os
sys.stdout.flush()
sys.stderr.flush()
os._exit(code)
+72 -9
View File
@@ -1,8 +1,10 @@
"""Уборщик незавершённых загрузок и сверка bucket и БД.
`python -m src.cleaner [--once]` — сервис уборки; `python -m src.cleaner
reconcile [--apply] [--max-changes N]` — разовая сверка, по умолчанию
dry-run (design change `track2-reconciler`, решение 1).
reconcile [--apply] [--max-changes N] [--strategy batch|head] [--deep]
[--max-objects-per-second R]` — разовая сверка, по умолчанию dry-run
(design change `track2-reconciler`, решение 1; стратегия, глубина и
предел скорости — design change `track2-reconcile-cost`, решения 4–6).
Отдельный процесс стенда, а не задача реплик API (design change
`upload-consistency`, решения 2, 4, 5). Свои engine (пул из
@@ -23,6 +25,7 @@ dry-run (design change `track2-reconciler`, решение 1).
import argparse
import asyncio
import math
import signal
from contextlib import AbstractAsyncContextManager, suppress
from datetime import timedelta
@@ -42,6 +45,7 @@ from src.infra.db.scope import session_scope
from src.infra.logger import AbstractLogger, get_logger
from src.infra.s3 import create_object_storage
from src.schemas import dataclasses
from src.schemas.enums import ReconcileStrategy
from src.utils.utc import utcnow
logger: AbstractLogger = get_logger().bind(module="cleaner")
@@ -77,6 +81,16 @@ def _positive_int(value: str) -> int:
return number
def _non_negative_float(value: str) -> float:
try:
number = float(value)
except ValueError:
raise argparse.ArgumentTypeError("must be a number") from None
if not math.isfinite(number) or number < 0:
raise argparse.ArgumentTypeError("must be a non-negative number")
return number
def _parse_args(argv: list[str] | None) -> argparse.Namespace:
parser = argparse.ArgumentParser(
prog="python -m src.cleaner",
@@ -105,6 +119,25 @@ def _parse_args(argv: list[str] | None) -> argparse.Namespace:
default=None,
help="change limit of the pass (default: [reconciler] max_changes)",
)
reconcile.add_argument(
"--strategy",
choices=[item.value for item in ReconcileStrategy],
default=ReconcileStrategy.BATCH.value,
help="batch: list pages and one database query per page; head: a "
"database query per object and HEAD per ready row",
)
reconcile.add_argument(
"--deep",
action="store_true",
help="read objects and compare their SHA-256 with the metadata",
)
reconcile.add_argument(
"--max-objects-per-second",
type=_non_negative_float,
default=None,
help="S3 objects per second, 0 - no limit "
"(default: [reconciler] max_objects_per_second)",
)
return parser.parse_args(argv)
@@ -115,11 +148,10 @@ def main(argv: list[str] | None = None) -> int:
run(
mode=MODE_RECONCILE,
apply=args.apply,
max_changes=(
settings.reconciler.max_changes
if args.max_changes is None
else args.max_changes
),
max_changes=args.max_changes,
strategy=ReconcileStrategy(args.strategy),
deep=args.deep,
max_objects_per_second=args.max_objects_per_second,
),
)
return asyncio.run(run(mode=MODE_ONCE if args.once else MODE_SERVICE))
@@ -130,12 +162,24 @@ async def run(
mode: str,
apply: bool = True,
max_changes: int | None = None,
strategy: ReconcileStrategy = ReconcileStrategy.BATCH,
deep: bool = False,
max_objects_per_second: float | None = None,
) -> int:
"""Проверка grace, затем проходы уборки до сигнала (или один с
`--once`) с плановой сверкой — или одна разовая сверка."""
`--once`) с плановой сверкой — или одна разовая сверка. Стратегия и
глубина — только у разовой сверки; плановая — `batch`, поверхностная,
предел скорости из настроек (design change `track2-reconcile-cost`,
решения 4–6)."""
cleaner = settings.cleaner
reconciler = settings.reconciler
limit = reconciler.max_changes if max_changes is None else max_changes
rate = (
reconciler.max_objects_per_second
if max_objects_per_second is None
else max_objects_per_second
)
once_pass = mode == MODE_RECONCILE
bound = live_upload_bound_seconds(settings)
if cleaner.pending_grace_seconds <= bound:
# до engine и клиента S3: ни одного обращения к хранилищам
@@ -193,7 +237,10 @@ async def run(
reconcile_interval_seconds=reconciler.interval_seconds,
reconcile_page_size=reconciler.page_size,
reconcile_max_changes=limit,
reconcile_apply=apply if mode == MODE_RECONCILE else None,
reconcile_max_objects_per_second=rate,
reconcile_apply=apply if once_pass else None,
reconcile_strategy=strategy.value if once_pass else None,
reconcile_deep=deep if once_pass else None,
database_host=settings.database.host,
database_port=settings.database.port,
database_name=settings.database.name,
@@ -207,6 +254,9 @@ async def run(
reconcile,
apply=apply,
max_changes=limit,
strategy=strategy,
deep=deep,
max_objects_per_second=rate,
stop=stop,
)
exit_code = _reconcile_exit_code(result)
@@ -255,10 +305,17 @@ async def _serve(
pause = cleaner.interval_seconds
if next_reconcile is not None and not stop.is_set():
if loop.time() >= next_reconcile:
# плановая — стратегия по умолчанию, поверхностная, пределы
# из настроек
await _reconcile_once(
reconcile,
apply=True,
max_changes=settings.reconciler.max_changes,
strategy=ReconcileStrategy.BATCH,
deep=False,
max_objects_per_second=(
settings.reconciler.max_objects_per_second
),
stop=stop,
)
next_reconcile = loop.time() + interval
@@ -296,6 +353,9 @@ async def _reconcile_once(
*,
apply: bool,
max_changes: int,
strategy: ReconcileStrategy,
deep: bool,
max_objects_per_second: float,
stop: asyncio.Event,
) -> dataclasses.ReconcilePassDTO | None:
"""Проход сверки; `None` — непредвиденная ошибка: `error` с
@@ -310,6 +370,9 @@ async def _reconcile_once(
max_changes=max_changes,
page_size=settings.reconciler.page_size,
batch_size=settings.cleaner.batch_size,
strategy=strategy,
deep=deep,
max_objects_per_second=max_objects_per_second,
stop_requested=stop.is_set,
)
except Exception as e:
+4
View File
@@ -280,6 +280,10 @@ class Reconciler(BaseModel):
page_size: int = Field(default=1000, ge=1, le=1000)
# предел изменений за проход: больше — ни одного изменения и код 3
max_changes: int = Field(default=100, ge=1)
# предел скорости прохода: объектов S3 в секунду в среднем от начала
# прохода (ключи страниц списка, HEAD, GET, DELETE); 0 — без предела
# (design change `track2-reconcile-cost`, решение 6)
max_objects_per_second: float = Field(default=2000.0, ge=0)
class Settings(BaseSettings):
File diff suppressed because it is too large Load Diff
+2
View File
@@ -1,5 +1,6 @@
from src.infra.s3.client import (
ObjectStorage,
StorageStats,
StoredObject,
StoredObjectInfo,
StoredObjectPage,
@@ -8,6 +9,7 @@ from src.infra.s3.client import (
__all__ = [
"ObjectStorage",
"StorageStats",
"StoredObject",
"StoredObjectInfo",
"StoredObjectPage",
+51 -3
View File
@@ -26,6 +26,13 @@ bucket и БД процессом уборщика (design change `track2-reconc
решение 3): страница — один вызов со сроком, нет bucket — ошибка, а не
пустая страница.
Счётчики клиента (design change `track2-reconcile-cost`, решение 8):
попытки вызовов по операциям (`list`, `head`, `get`, `delete`, `put` —
считаются до вызова, в том числе неудачные), ключи страниц списка и
прочитанные байты объектов. `stats()` отдаёт неизменяемый снимок
`StorageStats`; стоимость прохода сверка считает разностью снимков.
Поведение вызовов, сроки и перевод ошибок от счётчиков не зависят.
В журнал — адрес, bucket, ключ объекта, размер, длительность и класс
ошибки; ключей доступа, секрета и подписи там нет. Логгеры botocore,
aiobotocore и aiohttp стоят на WARNING (`src/infra/logger.py`): на DEBUG
@@ -34,10 +41,12 @@ botocore пишет заголовки с подписью.
import asyncio
import time
from collections.abc import AsyncIterator
from collections import Counter
from collections.abc import AsyncIterator, Mapping
from contextlib import AsyncExitStack, asynccontextmanager
from dataclasses import dataclass
from datetime import datetime
from types import MappingProxyType
from typing import Any, BinaryIO
import aiohttp
@@ -88,12 +97,33 @@ TRANSLATED_ERRORS: tuple[type[Exception], ...] = (
)
# размер блока чтения объекта по умолчанию
DEFAULT_CHUNK_BYTES = 64 * 1024
# имя операции botocore → имя в счётчиках клиента
OPERATION_NAMES = MappingProxyType(
{
"list_objects_v2": "list",
"head_object": "head",
"get_object": "get",
"delete_object": "delete",
"put_object": "put",
},
)
@dataclass(frozen=True, slots=True)
class StorageStats:
"""Снимок счётчиков клиента с его создания: `calls` — попытки вызовов
по операциям (`list`, `head`, `get`, `delete`, `put`), `listed_keys` —
ключи страниц списка, `read_bytes` — прочитанные байты объектов."""
calls: Mapping[str, int]
listed_keys: int
read_bytes: int
@dataclass(frozen=True, slots=True)
class StoredObjectInfo:
"""Метаданные объекта в bucket. `last_modified` — время записи по часам
S3 (точность — секунда), из списка и HEAD; у `open` его нет."""
S3 (точность — секунда), из списка, HEAD и GET."""
key: str
size: int
@@ -176,6 +206,19 @@ class ObjectStorage:
self._client: Any = None
self._exit_stack: AsyncExitStack | None = None
self._lock = asyncio.Lock()
self._calls: Counter[str] = Counter()
self._listed_keys = 0
self._read_bytes = 0
def stats(self) -> StorageStats:
"""Неизменяемый снимок счётчиков клиента с его создания."""
return StorageStats(
calls=MappingProxyType(
{name: self._calls[name] for name in OPERATION_NAMES.values()},
),
listed_keys=self._listed_keys,
read_bytes=self._read_bytes,
)
async def start(self) -> None:
"""Создать клиент заранее, при старте процесса."""
@@ -244,6 +287,7 @@ class ObjectStorage:
if token is not None:
params["ContinuationToken"] = token
response = await self._call("list_objects_v2", None, **params)
self._listed_keys += len(response.get("Contents", ()))
objects = tuple(
StoredObjectInfo(
key=item["Key"],
@@ -273,6 +317,7 @@ class ObjectStorage:
key=key,
size=response["ContentLength"],
content_type=response.get("ContentType"),
last_modified=response.get("LastModified"),
)
try:
yield StoredObject(info, body, self)
@@ -342,6 +387,7 @@ class ObjectStorage:
"""Вызов клиента со сроком и переводом ошибок. `key=None` — вызов
над bucket без ключа (список), в журнал тогда — `prefix`."""
client = await self._get_client()
self._calls[OPERATION_NAMES.get(operation, operation)] += 1
started = time.monotonic()
if key is not None:
params["Key"] = key
@@ -383,7 +429,7 @@ class ObjectStorage:
started = time.monotonic()
try:
async with asyncio.timeout(self._timeout_seconds):
return await body.read(chunk_bytes)
chunk = await body.read(chunk_bytes)
except TRANSLATED_ERRORS as e:
failure = self._failure(
e,
@@ -394,6 +440,8 @@ class ObjectStorage:
if failure is None:
raise
raise failure from e
self._read_bytes += len(chunk)
return chunk
def _failure(
self,
+33 -3
View File
@@ -1,9 +1,19 @@
from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
from dataclasses import dataclass
from dataclasses import dataclass, field
from datetime import datetime
from types import MappingProxyType
from uuid import UUID
from src.schemas.enums import AttachmentStatus, ImageType, ReconcileFinding
from src.schemas.enums import (
AttachmentStatus,
ImageType,
ReconcileFinding,
ReconcileStrategy,
)
def _empty_mapping() -> Mapping[str, int]:
return MappingProxyType({})
@dataclass(frozen=True, slots=True)
@@ -65,7 +75,9 @@ class ReconcileFindingDTO:
`attachment_id` — если известен (из ключа или строки), `age_seconds` —
возраст объекта (`LastModified`) или строки (`updated_at` у ready,
`created_at` у pending). `size_bytes` и `stored_size` — размеры строки и
объекта, если известны оба.
объекта, если известны оба. `sha256` — SHA-256 оригинала из строки:
по нему перепроверка и действие сверяют прочитанный объект (design
change `track2-reconcile-cost`, решение 5); в журнал не попадает.
"""
kind: ReconcileFinding
@@ -74,6 +86,7 @@ class ReconcileFindingDTO:
age_seconds: int
size_bytes: int | None = None
stored_size: int | None = None
sha256: bytes | None = None
@dataclass(frozen=True, slots=True)
@@ -86,6 +99,14 @@ class ReconcilePassDTO:
сколько расхождений не записано отдельными записями,
`interrupted_by` — причина прерывания (`object_storage`, `database`,
`stop`) или `None`.
Стоимость прохода (design change `track2-reconcile-cost`, решения 8 и
15): `strategy`, `deep` и `max_objects_per_second` (0 — без предела);
`storage_objects` — затронутые объекты S3 (ключи страниц списка, HEAD,
GET, DELETE), `s3_requests` — вызовы S3 по операциям, `read_bytes` —
прочитанные байты объектов, `db_sessions` — сеансы с PostgreSQL,
`unchecked` — кандидаты, которых `--apply` не перепроверял после
решённого отказа по пределу, `phase_ms` — длительность шагов прохода.
"""
apply: bool
@@ -101,6 +122,15 @@ class ReconcilePassDTO:
unlogged: int
interrupted_by: str | None
duration_ms: int
strategy: ReconcileStrategy = ReconcileStrategy.BATCH
deep: bool = False
max_objects_per_second: float = 0
storage_objects: int = 0
s3_requests: Mapping[str, int] = field(default_factory=_empty_mapping)
read_bytes: int = 0
db_sessions: int = 0
unchecked: int = 0
phase_ms: Mapping[str, int] = field(default_factory=_empty_mapping)
@dataclass(frozen=True, slots=True)
+2
View File
@@ -3,6 +3,7 @@ from .attachment import (
ImageType,
ReconcileAction,
ReconcileFinding,
ReconcileStrategy,
)
from .settings import RunModeEnum
@@ -11,5 +12,6 @@ __all__ = [
"ImageType",
"ReconcileAction",
"ReconcileFinding",
"ReconcileStrategy",
"RunModeEnum",
]
+15
View File
@@ -38,6 +38,21 @@ class ReconcileFinding(StrEnum):
# ключ под префиксом вложений, которого API не пишет, или ключ строки
# другого вида
UNKNOWN_OBJECT = "unknown_object"
# строка ready, объект того же размера, а SHA-256 содержимого другой;
# ищет только глубокая сверка (design change `track2-reconcile-cost`,
# решение 5)
CHECKSUM_MISMATCH = "checksum_mismatch"
class ReconcileStrategy(StrEnum):
"""Стратегия обхода сверки (design change `track2-reconcile-cost`,
решение 4). `batch` — страница списка и одно выражение к БД на
страницу, ключи списка в множестве; `head` — выборка строки на объект
списка и HEAD на строку `ready`, без множества. Плановая сверка — только
`batch`."""
BATCH = "batch"
HEAD = "head"
class ReconcileAction(StrEnum):
+4
View File
@@ -83,6 +83,10 @@ ATTACHMENT_ORIGINAL_SUFFIX = "original"
# записями журнала; остальные — только числом в итоге (design change
# `track2-reconciler`, решение 8)
RECONCILE_FINDINGS_LOGGED_MAX = 1000
# пауза предела скорости сверки — кусками не дольше этого, с проверкой
# сигнала между ними: остановка не ждёт конца паузы (design change
# `track2-reconcile-cost`, решение 6)
RECONCILE_PACE_STEP_SECONDS = 0.2
# секунды в Retry-After ответа 429, когда места загрузки процесса заняты:
# за секунду реплика доводит несколько загрузок (7–8,5 по 10 MiB), а повтор
# через LB уходит на следующую реплику (design change `upload-memory`,
+53 -7
View File
@@ -82,11 +82,18 @@
`attachments/`, символы [A-Za-z0-9._/-]
lost-ids `id` вложений с потерянным оригиналом
(lost_at задан)
reconcile dry-run|apply [<предел>]
reconcile dry-run|apply [<предел>] [--strategy batch|head] [--deep]
[--max-objects-per-second R]
разовая сверка (`docker compose run --rm
--no-deps -T cleaner reconcile [--apply]
[--max-changes N]`): записи процесса и
строка `exit_code=<n>`; код hook — 0
[--max-changes N] …`): стратегия обхода,
глубокая сверка и предел скорости (R —
неотрицательное число, 0 — без предела)
проверяются по списку и передаются команде
как есть (design change
`track2-reconcile-cost`, решение 14);
записи процесса и строка `exit_code=<n>`;
код hook — 0
stop|start cleaner сервис уборщика стенда
run-cleaner <секунд> отдельный уборщик
`<FAULT_PROJECT>-cleaner-scheduled` с
@@ -421,6 +428,10 @@ client.put_object(Bucket=s3.bucket, Key=sys.argv[1], Body=body)
# символы ключа объекта, который hook пишет или удаляет мимо API
OBJECT_KEY_RE = re.compile(r"^[A-Za-z0-9._/-]+$")
RECONCILE_MODES = {"dry-run": (), "apply": ("--apply",)}
# стратегии обхода и предел скорости сверки (change track2-reconcile-cost):
# неотрицательное число, целое или с дробной частью
RECONCILE_STRATEGIES = ("batch", "head")
RATE_PATTERN = re.compile(r"[0-9]+(\.[0-9]+)?")
# плановая сверка отдельного уборщика: раз в секунду
SCHEDULED_CLEANER_ENV = "RECONCILER__INTERVAL_SECONDS=1"
SCHEDULED_CLEANER_MAX_S = 60
@@ -817,12 +828,47 @@ def row_change(project: str, sql: str, attachment_id: str, value: str) -> str:
return ""
def reconcile_options(args: list[str]) -> list[str]:
"""Аргументы сверки после режима: необязательный предел изменений
первым, затем `--strategy batch|head`, `--deep`,
`--max-objects-per-second R`. Каждый — по списку разрешённых, иначе
код 2 hook."""
usage = (
"reconcile dry-run|apply [<max changes>] [--strategy batch|head] "
"[--deep] [--max-objects-per-second R]"
)
options: list[str] = []
rest = list(args)
if rest and not rest[0].startswith("--"):
if not rest[0].isdigit() or int(rest[0]) < 1:
raise HookError(usage)
options += ["--max-changes", str(int(rest.pop(0)))]
seen: set[str] = set()
while rest:
name = rest.pop(0)
if name in seen:
raise HookError(usage)
seen.add(name)
if name == "--deep":
options.append(name)
elif name == "--strategy" and rest and rest[0] in RECONCILE_STRATEGIES:
options += [name, rest.pop(0)]
elif name == "--max-objects-per-second" and rest:
value = rest.pop(0)
if not RATE_PATTERN.fullmatch(value):
raise HookError(usage)
options += [name, value]
else:
raise HookError(usage)
return options
def reconcile(project: str, mode: str, args: list[str]) -> str:
"""Разовая сверка в одноразовом контейнере уборщика стенда: записи
процесса и строка `exit_code=<n>`."""
if mode not in RECONCILE_MODES or len(args) > 1:
raise HookError("reconcile dry-run|apply [<max changes>]")
limit = ("--max-changes", str(int(args[0]))) if args else ()
if mode not in RECONCILE_MODES:
raise HookError("reconcile dry-run|apply [<max changes>] [options]")
options = reconcile_options(args)
result = compose_run(
project,
"run",
@@ -832,7 +878,7 @@ def reconcile(project: str, mode: str, args: list[str]) -> str:
"cleaner",
"reconcile",
*RECONCILE_MODES[mode],
*limit,
*options,
)
lines = [*result.stdout.splitlines(), *result.stderr.splitlines()]
return "\n".join([*lines, f"exit_code={result.returncode}"])
+288 -3
View File
@@ -20,12 +20,14 @@ change `fix-upload-put-flake`.
import hashlib
import json
import math
import os
import random
import statistics
import threading
import time
import uuid
from collections.abc import Callable, Collection, Iterator
from collections.abc import Callable, Collection, Iterator, Sequence
from concurrent.futures import ThreadPoolExecutor
from contextlib import contextmanager
from dataclasses import dataclass
@@ -1670,10 +1672,14 @@ def run_reconcile(
stand: Stand,
mode: str,
limit: int | None = None,
*,
options: Sequence[str] = (),
) -> Reconcile:
"""Разовая сверка hook: `dry-run` или `apply`, с пределом изменений."""
"""Разовая сверка hook: `dry-run` или `apply`, с пределом изменений;
`options` — стратегия, глубина и предел скорости (change
`track2-reconcile-cost`) как аргументы команды."""
args = [mode] if limit is None else [mode, str(limit)]
lines = stand("reconcile", *args).splitlines()
lines = stand("reconcile", *args, *options).splitlines()
assert lines and lines[-1].startswith("exit_code="), lines[-5:]
records = []
for line in lines[:-1]:
@@ -2292,3 +2298,282 @@ def test_scheduled_reconcile(
assert passes, log[-2000:]
assert any(item["apply"] for item in passes), passes
assert scheduled["id"] in lost_ids(stand)
# ---------------------------------------------------------------------------
# Стоимость сверки (change track2-reconcile-cost, design, решение 14):
# стратегия HEAD, глубокая сверка и класс «другой SHA-256», снятие пометки
# только при том же SHA-256, предел скорости, отказ по пределу без лишних
# перепроверок. Аргументы сверки hook передаёт команде как есть
# ---------------------------------------------------------------------------
HEAD_STRATEGY = ("--strategy", "head")
DEEP = ("--deep",)
NO_RATE_LIMIT = ("--max-objects-per-second", "0")
# сколько вложений загружает тест предела скорости: объектов в bucket
# заведомо хватает на несколько секунд прохода
RATE_UPLOADS = 8
# во сколько раз проход с пределом длиннее числа объектов на предел
# (допуск на округление `duration_ms`)
RATE_SLACK = 0.95
def same_size_bytes(data: bytes, *, seed: int) -> bytes:
"""Другие байты того же размера, от зерна теста."""
other = random.Random(seed).randbytes(len(data))
assert other != data
return other
def findings(run: Reconcile) -> set[tuple[str, str]]:
"""Все расхождения прохода: класс и ключ объекта."""
return {(item["kind"], item["object_key"]) for item in run.events(FOUND)}
@pytest.mark.spec("storage-consistency", "Стратегия HEAD находит то же")
def test_reconcile_head_strategy_same_findings(
api: Api,
stand: Stand,
alice: Actor,
chat: dict[str, Any],
) -> None:
"""Те же расхождения, что в `test_reconcile_finds_and_fixes`: dry-run
стратегией по умолчанию и `--strategy head` называют одно и то же, а
HEAD-проход дороже по запросам к S3 и сеансам PostgreSQL."""
data = images.sample_png()
# уборщик стенда стоит: зависшую загрузку P не уберут между проходами
with outage(stand, "stop", "cleaner"):
a, b, c = (api.upload(alice, chat["id"], data) for _ in range(3))
api.send_message(alice, chat["id"], "", attachment_ids=[a["id"]])
orphan = str(uuid.uuid4())
keys = {"o": object_key(orphan), "b": object_key(b["id"])}
put_object(stand, keys["o"], data)
stand("delete-object", object_key(a["id"]))
stand("delete-row", b["id"])
stand("set-size", c["id"], str(len(data) + 1))
filename = fault_filename()
before = attachment_rows(stand)
stand("fail-attachments", "commit", filename)
try:
resp = upload_raw(api, alice, chat, data, filename=filename)
assert_error(resp, 503)
finally:
stand("clear-fail-attachments")
(pending,) = new_ids(before, attachment_rows(stand))
time.sleep(OBJECT_AGE_WAIT_S)
ids = {a["id"], c["id"], pending}
expected = {
keys["o"]: "orphan_object",
keys["b"]: "orphan_object",
a["id"]: "missing_object",
c["id"]: "size_mismatch",
pending: "stale_pending",
}
snapshot = (attachment_rows(stand), stored_ids(stand), lost_ids(stand))
batch = run_reconcile(stand, "dry-run")
head = run_reconcile(stand, "dry-run", options=HEAD_STRATEGY)
assert batch.kinds(FOUND, ids=ids, keys=keys.values()) == expected
assert head.kinds(FOUND, ids=ids, keys=keys.values()) == expected
# не только свои: весь отчёт и итог по классам одинаковы
assert findings(head) == findings(batch)
for field in ("found", "listed_objects", "checked_rows"):
assert head.finished[field] == batch.finished[field], field
assert head.exit_code == batch.exit_code == 3
assert (batch.finished["strategy"], head.finished["strategy"]) == (
"batch",
"head",
)
assert (
head.finished["s3_requests"]["head"]
> batch.finished["s3_requests"]["head"]
), (head.finished, batch.finished)
assert head.finished["db_sessions"] > batch.finished["db_sessions"]
after = (attachment_rows(stand), stored_ids(stand), lost_ids(stand))
assert after == snapshot
# стенд — без внесённых расхождений для следующих тестов
fixed = run_reconcile(stand, "apply")
assert set(fixed.kinds(FIXED, ids=ids, keys=keys.values())) == set(
expected,
)
@pytest.mark.spec(
"storage-consistency",
"Другой SHA-256 находит глубокая сверка",
)
def test_reconcile_deep_checksum(
api: Api,
stand: Stand,
alice: Actor,
chat: dict[str, Any],
) -> None:
data = images.png_noise(64, 48, seed=11)
a = api.upload(alice, chat["id"], data)
api.send_message(alice, chat["id"], "", attachment_ids=[a["id"]])
other = same_size_bytes(data, seed=11)
# объект перезаписан мимо API байтами того же размера
put_object(stand, object_key(a["id"]), other)
stand("age-row", a["id"], str(AGED_S))
time.sleep(OBJECT_AGE_WAIT_S)
snapshot = (attachment_rows(stand), stored_ids(stand), lost_ids(stand))
shallow = run_reconcile(stand, "dry-run")
assert not shallow.about(FOUND, ids={a["id"]})
assert shallow.finished["deep"] is False
deep = run_reconcile(stand, "dry-run", options=DEEP)
assert deep.kinds(FOUND, ids={a["id"]}) == {a["id"]: "checksum_mismatch"}
assert deep.finished["deep"] is True
assert deep.finished["read_bytes"] >= len(data), deep.finished
assert deep.finished["s3_requests"]["get"] >= 1, deep.finished
assert deep.exit_code == 3
after = (attachment_rows(stand), stored_ids(stand), lost_ids(stand))
assert after == snapshot
# SHA-256 объектов в журнале нет
journal = json.dumps(deep.records)
for body in (data, other):
assert hashlib.sha256(body).hexdigest() not in journal
applied = run_reconcile(stand, "apply", options=DEEP)
(record,) = applied.about(FIXED, ids={a["id"]})
assert (record["kind"], record["action"]) == (
"checksum_mismatch",
"marked_lost",
)
assert a["id"] in lost_ids(stand)
assert_lost_content(api, alice, a, aged=True)
@pytest.mark.spec(
"storage-consistency",
"Вернулся другой объект того же размера",
)
@pytest.mark.spec("storage-consistency", "Оригинал вернулся")
def test_reconcile_restore_needs_same_bytes(
api: Api,
stand: Stand,
alice: Actor,
chat: dict[str, Any],
) -> None:
data = images.png_noise(64, 48, seed=13)
restored = api.upload(alice, chat["id"], data)
ids = {restored["id"]}
lose_original(stand, restored)
marked = run_reconcile(stand, "apply")
assert marked.kinds(FIXED, ids=ids) == {restored["id"]: "missing_object"}
assert restored["id"] in lost_ids(stand)
# под ключом — другие байты того же размера: пометка остаётся
put_object(
stand,
object_key(restored["id"]),
same_size_bytes(data, seed=13),
)
time.sleep(OBJECT_AGE_WAIT_S)
wrong = run_reconcile(stand, "apply")
assert not wrong.about(FIXED, ids=ids)
assert all(
record["kind"] != "restored_object"
for record in wrong.about(FOUND, ids=ids)
)
assert restored["id"] in lost_ids(stand)
assert_lost_content(api, alice, restored, aged=True)
# те же байты, что были загружены: пометка снята
put_object(stand, object_key(restored["id"]), data)
time.sleep(OBJECT_AGE_WAIT_S)
cleared = run_reconcile(stand, "apply")
(record,) = cleared.about(FIXED, ids=ids)
assert (record["kind"], record["action"]) == (
"restored_object",
"cleared_lost",
)
assert restored["id"] not in lost_ids(stand)
assert_content(
api.attachment_content(alice, restored["id"]),
data,
"image/png",
)
again = run_reconcile(stand, "dry-run")
assert not again.about(FOUND, ids=ids)
@pytest.mark.spec("storage-consistency", "Скорость прохода ограничена")
@pytest.mark.spec("storage-consistency", "Без ограничения скорости")
def test_reconcile_rate_limit(
api: Api,
stand: Stand,
alice: Actor,
chat: dict[str, Any],
) -> None:
"""Предел на четверть объектов прохода: проход длится не меньше
объектов на предел, находки и код — как без предела."""
data = images.sample_png()
for _ in range(RATE_UPLOADS):
api.upload(alice, chat["id"], data)
lost = api.upload(alice, chat["id"], data)
ids = {lost["id"]}
lose_original(stand, lost)
# уборщик стенда стоит: между проходами стенд не меняется
with outage(stand, "stop", "cleaner"):
free = run_reconcile(stand, "dry-run", options=NO_RATE_LIMIT)
rate = max(5, math.ceil(free.finished["storage_objects"] / 4))
limited = run_reconcile(
stand,
"dry-run",
options=("--max-objects-per-second", str(rate)),
)
assert free.finished["max_objects_per_second"] == 0
assert limited.finished["max_objects_per_second"] == rate
objects = limited.finished["storage_objects"]
assert objects >= RATE_UPLOADS, limited.finished
assert (
limited.finished["duration_ms"] >= 1000 * objects / rate * RATE_SLACK
), limited.finished
assert free.finished["duration_ms"] < limited.finished["duration_ms"]
expected = {lost["id"]: "missing_object"}
assert free.kinds(FOUND, ids=ids) == expected
assert limited.kinds(FOUND, ids=ids) == expected
assert free.exit_code == limited.exit_code == 3
# стенд — без внесённой потери
applied = run_reconcile(stand, "apply")
assert applied.kinds(FIXED, ids=ids) == expected
@pytest.mark.spec(
"storage-consistency",
"Отказ по пределу без лишних перепроверок",
)
def test_reconcile_limit_stops_rechecks(
api: Api,
stand: Stand,
alice: Actor,
chat: dict[str, Any],
) -> None:
limit = 2
batch = [
api.upload(alice, chat["id"], images.sample_png()) for _ in range(6)
]
ids = {item["id"] for item in batch}
for item in batch:
lose_original(stand, item)
refused = run_reconcile(stand, "apply", limit)
assert refused.exit_code == 3
(error,) = refused.events(LIMIT_EXCEEDED)
assert error["level"] == "error"
# отказ решён на третьем подтверждённом: остальные не перепроверены
assert error["changes"] == limit + 1, error
assert error["max_changes"] == limit
assert error["unchecked"] >= len(batch) - (limit + 1), error
assert refused.finished["unchecked"] == error["unchecked"]
assert refused.finished["refused"] is True
assert not refused.about(FIXED, ids=ids)
assert not ids & lost_ids(stand)
# dry-run перепроверяет каждого и называет все шесть
dry = run_reconcile(stand, "dry-run")
assert dry.kinds(FOUND, ids=ids) == dict.fromkeys(ids, "missing_object")
assert dry.finished["unchecked"] == 0
applied = run_reconcile(stand, "apply", 100)
assert set(applied.kinds(FIXED, ids=ids)) == ids
assert ids <= lost_ids(stand)