From 5b5f59aa3b52cb4e14c1b9d1bbd5d49ad8835306 Mon Sep 17 00:00:00 2001 From: roman Date: Sun, 1 Nov 2026 05:28:05 +0300 Subject: [PATCH] docs: propose track1-queue-overload Co-Authored-By: Claude Opus 5.5 --- KNOWN_ISSUES.md | 18 + QUESTIONS.md | 31 ++ .../track1-queue-overload/.openspec.yaml | 2 + .../changes/track1-queue-overload/design.md | 424 ++++++++++++++++++ .../changes/track1-queue-overload/proposal.md | 73 +++ .../specs/attachments/spec.md | 46 ++ .../specs/health/spec.md | 57 +++ .../specs/job-outbox/spec.md | 58 +++ .../specs/load-benchmark/spec.md | 344 ++++++++++++++ .../specs/message-broker/spec.md | 42 ++ .../specs/queue-overload/spec.md | 157 +++++++ .../specs/service-configuration/spec.md | 54 +++ .../specs/student-tests/spec.md | 172 +++++++ .../changes/track1-queue-overload/tasks.md | 147 ++++++ 14 files changed, 1625 insertions(+) create mode 100644 openspec/changes/track1-queue-overload/.openspec.yaml create mode 100644 openspec/changes/track1-queue-overload/design.md create mode 100644 openspec/changes/track1-queue-overload/proposal.md create mode 100644 openspec/changes/track1-queue-overload/specs/attachments/spec.md create mode 100644 openspec/changes/track1-queue-overload/specs/health/spec.md create mode 100644 openspec/changes/track1-queue-overload/specs/job-outbox/spec.md create mode 100644 openspec/changes/track1-queue-overload/specs/load-benchmark/spec.md create mode 100644 openspec/changes/track1-queue-overload/specs/message-broker/spec.md create mode 100644 openspec/changes/track1-queue-overload/specs/queue-overload/spec.md create mode 100644 openspec/changes/track1-queue-overload/specs/service-configuration/spec.md create mode 100644 openspec/changes/track1-queue-overload/specs/student-tests/spec.md create mode 100644 openspec/changes/track1-queue-overload/tasks.md diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index dffd9822..7690c195 100644 --- a/KNOWN_ISSUES.md +++ b/KNOWN_ISSUES.md @@ -147,6 +147,24 @@ `http-request set-timeout server` LB для `GET /attachments/…`. Не чинится в change `unit-of-work`: ручки вложений там без общего срока (решение 6). +## S3 на долго живущем стенде: лимит памяти при всплеске загрузок у границы байтов + +- **Где:** сервис `s3` (`docker-compose.yml`: лимит 512 МБ, `GOMEMLIMIT=400MiB`, + `-s3.concurrentUploadLimitMB=64`), SeaweedFS 4.48. Найдено пробой change + `track1-queue-overload` (design, Context, проект `q1probe`, 2026-11-01). +- **Что:** на стенде, который ~80 мин принимал пробы без пересоздания volume (~9 200 + заданий), `docker stats` показывал у S3 330–415 МиБ; при 12 загрузках 10 MiB в секунду + ядро его убило (`exit 137`, `OOMKilled: true`, один случай). На свежем стенде те же 12 и + 15 загрузок в секунду — 322–399 МиБ и `oom_kill` 0. Зависит ли это от числа объектов, + проба не проверяла. +- **Чем грозит:** пока S3 лежит, загрузка и скачивание — 503. На рабочем стенде его + возвращает `restart: unless-stopped`; в пробе (`restart: "no"`) все 229 незавершённых + заданий за ~85 с исчерпали бюджет: `failed`, `retry_exhausted`, возврат — `make replay`. + Принятая работа не потеряна, реестр её называет. +- **Предложение:** замерить рост памяти S3 с числом объектов (профиль с накоплением, без + пересоздания volume); при подтверждении — лимит 768 МБ или меньше `GOMEMLIMIT`. Метка + `make bench_queue` этого не покажет: её ячейки идут на свежих volume. + ## Остановка API при замороженном PostgreSQL дольше срока контейнера - **Где:** `src/main.py`, `await engine.dispose()` в lifespan без общего срока. Найдено diff --git a/QUESTIONS.md b/QUESTIONS.md index bdd58d28..d5a87e5e 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -44,6 +44,11 @@ (`docker ps -a --filter volume=<имя>`), затем `docker volume rm <имя>`. - На хосте 150 анонимных volumes. Чьи они, не проверялось, часть может быть чужой, поэтому `docker volume prune` без просмотра запускать не стоит. +- Остались volumes пробы стадии propose `track1-queue-overload`: + `q1probe_postgres_data`, `q1probe_rabbitmq_data`, `q1probe_s3_data` (контейнеров, + сетей и образов нет). При уборке автопроверка отказала в команде с `docker compose + … down -v`, поэтому прогон их не удалял. Удалить вручную: `docker volume rm + q1probe_postgres_data q1probe_rabbitmq_data q1probe_s3_data`. ## Перенос из лабы 4 @@ -216,3 +221,29 @@ ### Для пользователя Основная сессия приняла расхождения с первоначальной постановкой, потому что сама её сформулировала, а решения пользователя они не меняют: общий срок JSON-запроса (решение 6) и дешёвую проверку соединения при выдаче (решение 7). Условие для второго: `make service_test_db` проверяет обрыв соединения с подменённой проверкой, чтобы смена внутренних имён SQLAlchemy падала тестом. Цена паттерна на этом стенде, замер на коммите (`evidence/compare/unit-of-work-aa__unit-of-work-after.md` и `unit-of-work-before__unit-of-work-after.md`): потолок реплики на истории и отправке ниже, медианы −14,1 и −12,6 % от метки того же кода, снятой прямо перед «после» (ниже 18 ячеек из 18), −6,6 и −4,3 % от снятой позже (16 из 18). Один повтор на ячейку, две метки одного кода расходятся до 14–17 %: знак устойчив, точной величины нет. За оценку design (−1…−22 %) цена по ближней метке не вышла, число соединений то же. Рост CPU при 200/с (API +10,8 %) того же порядка, что расхождение двух прогонов одного кода (9,2 %). Вывод — `REPORT.md`. + +## track1-queue-overload + +Подробности и отвергнутые варианты — `openspec/changes/track1-queue-overload/design.md`; пробы — его раздел «Пробы» (проект compose `q1probe`, образ `git archive 5a97416`, файлы в scratchpad). Это пробы, а не результат: результат даст метка `evidence/queue/baseline/`. + +### Решения + +- **Граница принятой работы — предел незавершённых заданий (`queued` + `processing`), `[uploads] max_unfinished_jobs`, по умолчанию 250, 0 — без предела:** у предела загрузка получает 429 `rate_limited` с `Retry-After: 5`, сразу, без чтения тела и места. Без неё бэклог упирается только в диск: пробы показали, что брокер его не сдержит (200 000 сообщений — 106 МиБ анонимной памяти), а 202 отвечает всегда (решение 1). +- **Значение 250 — из потолка худшего класса:** PNG RGBA 40 Мпкс, 0,92 задания в секунду на 1 CPU: ожидание ~270 с, меньше порога потерянного сообщения 300 с; staging не больше ~2,4 ГиБ. Проверяется меткой, при другом числе worker предел другой (решение 2). +- **Предел один на стенд и мягкий:** считается в PostgreSQL, превышение — только загрузки в полёте, `реплик × (мест + ожидающих)`, на стенде 40. Жёсткий предел потребовал бы блокировки на фиксацию и компенсации записанного объекта. Не на чат и не на пользователя, и считает задания, а не байты: ограничения названы в отчёте. +- **Счёт — тремя существующими частичными индексами с `LIMIT` на группу:** 0,05–0,13 мс при любом бэклоге, под оборотом до ~1 мс; нового индекса и миграции нет. Счётчик одной строкой отвергнут пробой: −16…−49 % потолка оборота заданий. Проверка — в том же блоке, что членство: шаг с PostgreSQL не прибавляется, цепочка LB прежняя (решение 3). Цена на загрузку по прототипу: +0,9 мс p50, +0,8 мс CPU реплики, +0,4 мс CPU PostgreSQL; отказ — 1,9 и 0,3 мс. +- **Метрики очереди брокера — плагин `rabbitmq_prometheus` только в профиле:** `rabbitmqctl` стоит 0,52 с CPU в cgroup брокера на вызов и испортил бы замер (проба). На рабочем стенде плагина нет. +- **Истина о готовности — метаданные по HTTP после разбора очереди, а не живой опрос:** `updated_at` у `ready` не меняется, опрос нагружал бы API в замере. Счётчики очереди — `psql` сэмплера, только чтение. +- **Настройки метки:** (1, 1), (2, 2) по умолчанию, (4, 4), (2, 256), классы `s`, `m`, `lj`, `lp`; конкуренция сверх двух при 1 CPU на пробах не ускоряет, поэтому настоящее ускорение показывает блок второго worker. Значения по умолчанию меняются только по правилу решения 12, отдельным commit после метки. +- **Копии при большом prefetch в метку не входят:** опыт требует менять порог потерянного сообщения; проба — 188 копий на 150 заданий при пороге 15 с, эффект нулевой. +- **Профиль `uploads` и четыре прежних API стенда отказов — с выключенным пределом:** там задания копятся намеренно, предел мерил бы не то (решение 13). Пятый API — «узкий по заданиям». +- **Worker в профиле очереди перезапускается, как на рабочем стенде (`restart: unless-stopped`):** пробы — при (4, 4) на `lp` ядро может убить и процесс 1 (журнал ядра, `exit 137`), и с `restart: "no"` ячейка простаивала бы с ложными `stuck`. Перезапуски — столбец и пометка (решение 10). У S3 остаётся `"no"`: его гибель должна быть видна. +- **Блок приёма — `m`, 15/с, 45 с, с пределом по умолчанию:** пробы показали всю цепочку: S3, с ~10-й секунды 429 от мест, с ~35-й 429 от предела, а готовых/с падает с 2,9 до ~0,6. S3 — общий ресурс приёма и worker: гипотеза H9 (решения 4, 8, 12). +- **Время полной метки — ~2 ч 10 мин** при трёх повторах 19 конфигураций, `RESUME=1` как у серий: окна выбраны по пробам так, чтобы уложиться (решение 14). + +### Вопросы + +Вопросы преподавателю, переносятся в `REPORT.md` («Открытые вопросы преподавателю»). Прогон не останавливают: взята самая строгая трактовка, которая проходит публичные тесты, контракт и тесты не менялись. + +1. Предел незавершённых заданий: 429 или 503? Контракт называет 429 «ограничением частоты запросов», а здесь ограничено количество принятой работы; 503 в нём — «зависимость недоступна». Сделано: 429 `rate_limited` с `Retry-After` — как у занятых мест загрузки (вопрос 1 в отчёте), зависимости живы, и реплика остаётся готовой. Другой ответ меняет строку `DOMAIN_ERRORS` и сценарии. +2. Рубрика уровня 3 показывает «worker остановлен → upload 202», а трек 1 требует ограничить принятую работу. Как долго загрузка обязана отвечать 202 при остановленном worker? Сделано: пока незавершённых меньше предела (250); дальше 429, а текст, история, метаданные, готовые байты и `/health/ready` работают. Сценарий защиты грузит единицы файлов. Другой ответ — значение настройки. diff --git a/openspec/changes/track1-queue-overload/.openspec.yaml b/openspec/changes/track1-queue-overload/.openspec.yaml new file mode 100644 index 00000000..25002a8e --- /dev/null +++ b/openspec/changes/track1-queue-overload/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-01 diff --git a/openspec/changes/track1-queue-overload/design.md b/openspec/changes/track1-queue-overload/design.md new file mode 100644 index 00000000..37e6a9b2 --- /dev/null +++ b/openspec/changes/track1-queue-overload/design.md @@ -0,0 +1,424 @@ +# Design + +## Context + +Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. Контракт — `contracts/README.md` («Формат и ошибки», «Фоновая обработка»), `contracts/openapi.json` (у загрузки уже есть 429 с `Retry-After`), рубрика — `README.md`, «Трек 1», правила измерений — `COURSE.md` и `.claude/rules/bench.md`. Основа — design архива `2026-10-31-pipeline-reliability`, решение 8 (что мерить и откуда), и `2026-11-01-unit-of-work` (порты, блоки). + +### Код + +Состояние — `5a97416`: +- `AttachmentService.upload`: блок с членством; затем без БД 415 и 413; затем место загрузки и `_store`. Предела принятой работы нет: 429 — только от мест (4 + 16 на реплику); +- `src/worker/main.py`: `set_qos(prefetch)`, задача на доставку, `asyncio.Semaphore(concurrency)` вокруг `service.handle`; по умолчанию 2 и 2; процесс обработки на задание; пул PostgreSQL 2; +- `AttachmentRelayService`: `room = max_published_backlog − count_published()` (1000), «потерянные» — есть отмеченные старше 300 с и ноль готовых; +- частичные индексы `attachment_jobs`: `ix_attachment_jobs_outbox`, `ix_attachment_jobs_published`, `ix_attachment_jobs_lease` — покрывают всё незавершённое; +- `bench/`: `Stand.start_broker`, лимиты `BENCH_BROKER_*`, `BENCH_RELAY_*`, `BENCH_WORKER_*` описаны и не используются; сэмплер — режимы `list`, `scan`, `peak`; профиль `uploads` идёт без worker, и задания копятся. + +### Пробы (2026-11-01, scratchpad `track1/`, проект compose `q1probe`, образ `git archive 5a97416`) + +**Это пробы, а не результат:** один прогон на точку, часть — при соседней пробе; они нужны, чтобы выбрать методику, значения и пороги. Условия: arm64, Docker 29.9.2, ВМ 12 CPU / 7,75 ГиБ, рядом простаивали рабочий стенд и `domains-*`. Лимиты — рабочего стенда, worker 1 CPU / 1 ГБ без swap. Секреты — синтетические, `.env` и `config.toml` не подключались. Что осталось после проб — раздел «Migration Plan». + +**Кандидаты классов.** Файлы — Pillow образа, от зерна; процесс обработки — те же аргументы, что у `ImageRenderer`, 1 CPU, по одному, медиана пяти: + +| Файл | Млн пикс. | MiB | Стена / CPU, мс | VmHWM, МиБ | WebP, КиБ | +|---|---|---|---|---|---| +| JPEG 640 × 480, q85 | 0,31 | 0,10 | 208 / 200 | 31 | 82 | +| `s`: JPEG 1600 × 1200, q85 | 1,92 | 0,48 | 299 / 290 | 49 | 200 | +| PNG 1600 × 1200 | 1,92 | 3,77 | 342 / 330 | 53 | 221 | +| `m`: PNG RGB из шума 1024 × 3409 | 3,49 | 9,99 | 269 / 260 | 57 | 191 | +| `lj`: JPEG 8000 × 5000, q88 | 40 | 8,60 | 365 / 350 | 57 | 158 | +| JPEG прогрессивный, те же пиксели | 40 | 7,64 | 515 / 500 | 155 | 158 | +| PNG RGB 8000 × 5000, 4 значащих бита | 40 | 8,52 | 655 / 630 | 213 | 160 | +| `lp`: PNG RGBA 8000 × 5000, 4 значащих бита | 40 | 9,97 | 1025 / 1010 | 367 | 479 | + +Запуск процесса — около половины CPU малого файла: ~100 мс из 200 (проба `pipeline-reliability`: 90 мс на импорт Pillow и плагинов). Память решает формат, а не пиксели: 40 Мпкс — 57 МиБ у JPEG с `draft` и 367 МиБ у PNG RGBA. + +**Потолок worker.** Загрузки при остановленном worker, затем запуск, готовых в секунду по `finished_at`, 25–120 заданий: + +| Класс | (1, 1) | (2, 2) | (4, 4) | (8, 8) | Другие | +|---|---|---|---|---|---| +| 0,3 Мпкс | 4,33/с, 118 МиБ | 4,30, 142 | 3,41, 178 | 3,32, 253 | (2, 64): 4,03, 171 | +| `s` | 2,78, 147 | 2,96, 176 | 2,58, 283 | — | — | +| `m` | 2,48, 197 | 2,93, 261 | 2,63, 347 | 2,73, 591 | (2, 3): 2,39; (2, 8): 2,79 | +| `lj` | 1,91, 198 | 2,37, 249 | 2,13, 357 | 1,88, 494 | — | +| JPEG прогрессивный | — | 1,48, 401 | 1,57, 695 | — | — | +| `lp` | 0,81, 484 | 0,92, 842 | 0,89, **OOM ×10** | — | (3, 3): 0,81, **OOM ×4**; (2, 64): 0,84, 845 | + +`memory.peak` — на весь прогон. У `lp` при (3, 3) и (4, 4) ядро убивало процессы обработки, задания возвращались `render_killed` и все дошли до `ready` с попытками 29 и 35 на 25 заданий. CPU worker — 1 ядро на всём прогоне, кроме (1, 1), где часть времени ждут S3 и PostgreSQL: **потолок при 1 CPU — CPU, и конкуренция сверх двух его не поднимает, а удлиняет процесс** (`render_ms` p50 на 0,3 Мпкс: 213 → 424 → 1107 → 2108 мс). Цена задания: 0,24 с CPU на 0,3 Мпкс, 0,35 на `s` и `m`, 0,45 на `lj`, 1,13 на `lp`. + +**Открытая модель, настройка по умолчанию.** До окна — 15 с ниже потолка, окно перегрузки — 25 с, затем спад до нуля; контрольный поток 10 + 10 + 10 запросов в секунду: + +| Класс | λ, /с | Принято | Загрузка p50 / p95, мс | Готовых/с в окне | Пик незаверш. | Восстановление, с | До `ready` p50 / p95, с | Контроль p95: запись / чтение / скачивание, мс | CPU worker / S3 | +|---|---|---|---|---|---|---|---|---|---| +| `s` | 8 | 223, все 202 | 13 / 19 | 2,9 | 126 | 45,8 | 22 / 44 | 8 / 7 / 9 | 1,03 / 0,09 | +| `m` | 6 | 174, все 202 | 141 / 279 | 2,7 | 85 | 30,2 | 16 / 29 | 46 / 12 / 85 | 0,98 / 0,95 | +| `lj` | 6 | 169, все 202 | 112 / 197 | 2,2 | 98 | 43,9 | 23 / 42 | 57 / 11 / 43 | 1,02 / 0,68 | +| `lp` | 2,5 | 71, все 202 | 393 / 601 | 0,83 | 43 | 46,3 | 25 / 45 | 24 / 12 / 29 | 0,99 / 0,32 | +| `s`, (8, 8) | 8 | 224, все 202 | 15 / 25 | 2,0 | 156 | 76,7 | 41 / 75 | 17 / 14 / 18 | 0,98 / 0,13 | + +CPU — снимок `docker stats`. Очередь и задержка согласуются с простой моделью: p95 до `ready` ≈ пик незавершённых / throughput окна (отношение 0,86–1,01), восстановление — столько же (0,89–1,05); throughput в окне и при восстановлении один и тот же (провала нет). На `m` при 6/с S3 уже близко к своему 1 CPU (0,83–0,95): дальше упирается приём, а не worker. `outbox` держится на 0–2: relay не узкое место; `rabbitmq` в снимках занят только нашими вызовами `rabbitmqctl`. + +**Повтор на свежем стенде, окно 20 с, как в матрице.** До окна 10 с низкой λ; после разбора — окно той же низкой λ: + +| Класс, настройка | λ, /с | Принято | Загрузка p50 / p95, мс | Пик незаверш. | Восстановление, с | До `ready` в окне p50 / p95, с | p95 до окна / после, с | Контроль скачивания p95, мс | Пик worker, МиБ | +|---|---|---|---|---|---|---|---|---|---| +| `s`, (2, 2) | 8 | 176 | 13 / 19 | 99 | 32,9 | 17 / 31 | 0,62 / 0,58 | 7,5 | 174 | +| `m`, (2, 2) | 6 | 137 | 113 / 223 | 65 | 23,9 | 12 / 22 | 1,13 / 0,88 | 70 | 211 | +| `lp`, (2, 2) | 2,5 | 57 | 368 / 581 | 34 | 36,3 | 20 / 35 | 1,37 / 1,37 | 18 | 836 | +| `s`, (2, 256), старый стенд | 8 | 177 | 14 / 22 | 106 | 35,8 | 19 / 34 | 0,59 / — | 12,5 | 175 | + +Время до `ready` после разбора вернулось: отношение p95 — 0,78–1,00. У (2, 256) брокер всё окно показывает готовых 0 и неподтверждённых до 98; у (2, 2) готовых 91–163 при пике 99–170. + +**Память: `lp`, (4, 4), те же окна, 2,5/с.** Прогон — свежий стенд, кроме последнего: + +| Прогон | Завершений ядром | Заданий с повторной попыткой | Итог | +|---|---|---|---| +| 1 | 20 процессов обработки | 20 | все `ready`, разбор ~60 с | +| 2 | 44 | 26 | все `ready`, ~78 с | +| 3 | 0, `memory.peak` 1024 МиБ | 0 | все `ready`, ~42 с | +| 4 | 3 и **процесс 1 worker** | — | контейнер `exit 137`, `OOMKilled` на 20-й секунде | +| 5, старый стенд | не снято: контейнер пересоздан раньше разбора | — | те же признаки: контейнера нет на 24-й секунде, потребителей 0, через аренду 51 задание `queued`, ничего не потеряно | + +Журнал ядра прогона 4: за 1,2 мс убиты три процесса обработки (356, 233, 202 МиБ анонимной памяти) и следом процесс 1 (135 МиБ, тот же `oom_score_adj` 0): память ещё не вернулась, а других кандидатов уже нет. Значит, `oom_score_adj` у процесса обработки его не защитит: защита — конкуренция, которая помещается в лимит. На рабочем стенде worker вернётся сам (`restart: unless-stopped`), в `bench/` стоит `restart: "no"`, и ячейка зависла бы (решение 10). + +**Граница приёма: `m`, (2, 2), λ выше того, что принимают реплики и S3.** Свежий стенд; CPU — снимок `docker stats`: + +| λ, /с, окно | Ответы | Загрузка 202 p50 / p95, мс | Принято/с в окне | Готовых/с в окне | Пик незаверш. | Восстановление, с | До `ready` p95, с | Контроль p95: запись / чтение / скачивание, мс | CPU S3 / worker | +|---|---|---|---|---|---|---|---|---|---| +| 6, 20 с | 137 — 202 | 113 / 223 | 6,1 | 2,9 | 65 | 23,9 | 22 | 17 / 11 / 70 | 0,83 / 0,98 | +| 12, 20 с | 203 — 202, 20 — 429 | 3 320 / 5 333 | 9,4 | 0,56 | 170 | 59,9 | 58 | 31 / 22 / 384 | 0,97 / 0,07 | +| 15, 20 с | 207 — 202, 76 — 429 | 3 768 / 5 641 | 9,6 | 0,62 | 175 | 62,3 | 60 | 28 / 10 / 332 | 1,02 / 0,30 | +| 15, 40 с, предел 250 | 323 — 202, 202 — 429 `busy`, 57 — 429 `backlog` | 4 804 / 5 872 | 7,7 | 0,57 | **284** | 100,5 | 95 | 20 / 17 / 341 | 0,97 / 0,63 | + +5xx нет. Выше ~8–9,6 загрузок 10 MiB в секунду упирается CPU шлюза S3; места держат ответ 3–6 с и отказывают лишним (первый `busy` — на ~10-й секунде перегрузки), предел приходит на ~35-й, а превышение — 34 из 40 возможных загрузок в полёте. **S3 — общий ресурс приёма и worker:** пока приём занимает его, готовых/с падает с 2,9 до ~0,6 (worker ждёт S3, а не CPU), сразу после окна — снова 2,87/с. k6 с телом 10 MiB — до 2,1 ГиБ при 80 VU; VU, создаваемые на ходу, теряют итерации (33–36 недосланных). + +**Старый стенд: S3 убит ядром.** Один и тот же стенд ~80 мин принимал пробы (~9 200 заданий, volume не пересоздавался); S3 у него держал 330–415 МиБ при лимите 512 и `GOMEMLIMIT` 400 МиБ. При 12/с на `m` — `exit 137`, `OOMKilled`, 9 ответов 503 на загрузке; без него все 229 незавершённых заданий за ~85 с исчерпали бюджет: `failed`, `retry_exhausted`, `storage_unavailable`, возврат — `make replay`. Те же 12 и 15/с на свежем стенде: `oom_kill` 0, 322–399 МиБ (`memory.peak` 515 МиБ — с учётом страничного кэша). На рабочем стенде S3 вернулся бы сам, ячейки метки — на свежих volume; запись — `KNOWN_ISSUES.md`. + +**Цена проверки предела.** Схема стенда, 300 000 завершённых заданий, свой контейнер PostgreSQL 2 CPU / 1 ГБ, `pgbench -M prepared`, один клиент, задержка на запрос: + +| Незавершённых | `state IN (…)` без индекса: Parallel Seq Scan | Сумма трёх Index Only Scan | Сумма с `LIMIT 1001` на группу | +|---|---|---|---| +| ~0 | 10,8 мс | 0,045 мс | 0,047 мс | +| 1 000 | 10,6 | 0,081 | 0,092 | +| 5 000 | 11,4 | 0,233 | 0,135 | +| 25 000 | 11,7 | 0,959 | 0,129 | +| 125 000 | 15,9 | 4,876 | 0,130 | + +Новый частичный индекс `(id) WHERE state IN ('queued','processing')`: 4,8 МБ на 125 000 строк, полный счёт 5,3 мс, с `LIMIT` — 0,084 мс: выигрыша перед тремя существующими нет, а цена записи есть. Под оборотом 100 заданий в секунду (четыре транзакции жизни задания, в ~30 раз больше потолка, autovacuum по умолчанию, 26 000 мёртвых строк за 90 с, 1 020 незавершённых): 0,65–1,05 мс без роста; `Heap Fetches` — все незавершённые, карта видимости на живых страницах бесполезна, потому и граница по `LIMIT`. Счётчик одной строкой в транзакциях приёма и итога: читать 0,033 мс, но потолок оборота при 2 / 4 / 8 клиентах падает с 2003 / 2879 / 2567 до 1347 / 2055 / 1311 циклов задания в секунду (−29…−49 %, в другом прогоне −16…−24 %), задержка цикла +40…+96 %. + +**Прототип предела на копии кода** (образ `q1probe-gate`, решение 3 как есть; план — три Index Only Scan по трём индексам, 0,22 мс, у `_lease` `Heap Fetches` 173 на 2 живые строки до VACUUM). `s`, (2, 2), 1,5/с 10 с, затем 20/с 30 с: + +| Предел | Принято / 429 | Загрузка 202 p50 / p95, мс | Пик незаверш. | Восстановление, с | До `ready` p50 / p95, с | Контроль p95: запись / чтение / скачивание, мс | +|---|---|---|---|---|---|---| +| 250 | 349 / 265 | 14 / 161 | 250, плато до конца окна | 84,3 | 50 / 85 | 8,7 / 7,8 / 10,4 | +| 0 | 615 / 0 | 14 / 41 | 513, рост до конца окна | 173,2 | 87 / 165 | 9,0 / 7,5 / 10,4 | + +При пределе `p95 до ready` ровно `предел / потолок` (250 / 2,95 = 85 с). Превышения на этой интенсивности нет: загрузка `s` короче интервала между счётами. Хвост 161 мс — один прогон, причина не разбиралась; в опыте ниже его нет. + +**Цена проверки на загрузку и отказа.** Свежий стенд, 25 загрузок/с, тело 0,1 MiB (доля проверки наибольшая), worker, relay и уборщик остановлены, четыре круга по 16 с, реплики пересоздаются на каждое плечо; CPU — разность `cpu.stat` на запрос, медианы кругов: + +| | Загрузка p50 / p95 / p99, мс | CPU реплик, мс | CPU PostgreSQL, мс | +|---|---|---|---| +| Без проверки (предел 0) | 9,87 / 11,7 / 13,0 | 6,38 | 1,09 | +| С проверкой (предел 100 000: отказов нет, счёт до 4 400 строк) | 10,78 / 13,0 / 16,4 | 7,21 | 1,47 | +| Отказ у предела, 4 клиента без пауз, ~980 отказов/с | 3,7 / 4,7 / 5,7 | 1,89 | 0,27 | +| Отказ у предела, 16 клиентов, ~1 000 отказов/с | 14,5 / 27 / 58 | 1,90 | 0,32 | + +Проверка — **+0,9 мс p50, +0,8 мс CPU реплики, +0,4 мс CPU PostgreSQL на загрузку**; это оценка сверху: значение по умолчанию обрывает счёт на 250 строках на группу, а у файлов больше доля ещё меньше. Отказ втрое дешевле загрузки, пределы 5 и 250 при бэклоге 4 400 по цене неотличимы, потолок — CPU реплик. + +**Брокер.** Контейнер образа и лимитов стенда, предел памяти 400 МиБ, очередь без потребителя, сообщение 243 байта: + +| Что | Результат | +|---|---| +| Память на готовое сообщение | 1 000 / 50 000 / 200 000 сообщений: cgroup 173 / 180 / 257 МиБ, анонимная ~106 МиБ, память очереди 110–430 КиБ: классическая очередь держит в памяти ~1 000 сообщений, остальное на диске. До предела памяти лимитом `max_published_backlog` и пределом заданий не дойти | +| Неподтверждённые | prefetch 1 000 / 10 000: память очереди 1,1 / 11,5 МиБ: ~1,1 КиБ на сообщение, выдача за миллисекунды | +| Цена цикла выдача — ack, 20 000 сообщений | prefetch 1 — 5 836/с, 2 — 8 637/с, 8 — 16 147/с, 64 — 17 362/с: 0,17 мс против сотен мс задания: prefetch сверх конкуренции throughput на этих заданиях поднять нечем | +| Сработавший предел памяти (`set_vm_memory_high_watermark`) | публикация без подтверждения за 4 с, закрытие соединения издателя — по сроку; потребитель на своём соединении подтверждает 100 сообщений за 0,01 с | +| `consumer_timeout` | 30 мин: сообщение, выданное worker и не подтверждённое дольше, закрывает канал. Значит, `prefetch / потолок` должен быть меньше 30 мин | +| `rabbitmqctl list_queues` | 0,54 с, 0,52 с CPU в cgroup брокера на вызов: опрашивать им — портить CPU брокера в замере | +| Плагин `rabbitmq_prometheus` из файла `enabled_plugins` при старте, `collect_statistics_interval = 1000` | старт как без него, значения свежие за ~1 с; `/metrics/detailed?vhost=%2F&family=queue_coarse_metrics` — 2,4 КБ, 4,7 мс CPU на опрос; простой 0,0044 ядра, с опросом раз в секунду 0,0056; полный `/metrics` — 224 КБ, 33 мс. Чтение из bash образа PostgreSQL (`/dev/tcp`, HTTP/1.0, контейнер сэмплера): `ready=1234 unacked=0` при тех же значениях `rabbitmqctl list_queues` | + +**Большой prefetch** (`s`, 150 заданий накоплено при остановленном worker): + +| Опыт | (2, 2) | (2, 256) | +|---|---|---| +| Очередь через 10 с после запуска | готовых 120, неподтверждённых 2 | готовых **0**, неподтверждённых 122 | +| Второй worker через 10 с | 5,36/с, задания 92 + 58, всего 34,1 с | 2,94/с, задания **150 + 0**, всего 53,0 с | +| Порог потерянного 15 с вместо 300 с | копий 0 | копий **188** на 150 заданий: готовых ноль, а сообщения старше порога; все — `Skipped job message` `finished`, лишний эффект 0, время то же (51,8 с) | + +**Рестарты посреди перегрузки** (`s`, 8/с, 30 с, 255–257 принятых): KILL worker и запуск — все `ready`, две попытки у 2 заданий, восстановление 59,1 с (без рестарта по модели ~56), контроль p95 ≤ 10 мс; `docker restart` брокера — все `ready`, попыток сверх одной нет, 56,7 с; KILL брокера и запуск — то же, 56,6 с; загрузки — все 202. + +**Шум и цена стенда.** Три повтора `drain` при (2, 2) подряд: `s` (90 заданий) 3,02 / 3,05 / 3,02 готовых/с, пик 174 МиБ; `m` (60) 2,95 / 2,89 / 2,72, 209–215 МиБ; `lp` (30) 0,97 / 0,95 / 0,97, 831–838 МиБ: разброс throughput 1–8 %, памяти до 3 %. Свежий стенд: PostgreSQL и Valkey 1,9 с, миграции 2,5, брокер 3,7, S3 7,7, bootstrap 4,6, реплики, LB, relay, уборщик 0,7, готовность 1,2, пользователь и чат 0,9 — 20,5–25 с по шести запускам. + +### Что найдено до решений + +1. **Узкое место при 1 CPU — сам CPU worker,** а не брокер, relay, PostgreSQL или prefetch. Поэтому сравнение настроек при том же лимите покажет не рост, а цену: выше двух — та же скорость, вдвое больше памяти, вдвое дольше обработка задания. Настоящее ускорение — второй worker. +2. **Границу памяти задаёт формат:** конкуренция 3 уже не помещается в 1 ГБ на PNG RGBA 40 Мпкс и свободно помещается на JPEG тех же пикселей. Отсюда четыре класса, а не три. +3. **Брокер не копит и не сдерживает:** 200 000 сообщений — 106 МиБ анонимной памяти. Предел памяти брокера в этой системе — защита от чужого, а не сдерживание работы: без отдельного предела на входе бэклог упрётся только в диск. +4. **Большой prefetch не вреден для одного worker и вреден для всего остального:** очередь выглядит пустой, второй worker простаивает, появляются копии «потерянных». Это видно только особыми опытами, а не по throughput одного worker. +5. **Метрики очереди нельзя снимать `rabbitmqctl`:** 0,5 с CPU на вызов в cgroup брокера. +6. **Профиль `uploads` и `test_reconcile_under_load` копят задания:** первый без worker, второй 16 загрузок в секунду при потолке ~4/с. С пределом по умолчанию они мерили бы предел; это решение 13. +7. **У файлов на границе байтов первым упирается S3, и он общий:** выше ~8–9,6 загрузок/с клиент видит 429 от мест и ответ 3–6 с, а worker в это же время падает с 2,9 до ~0,6 готовых/с. Значит, «перестаёт ускоряться» — не только CPU worker: приём может отнять у обработки её ресурс, и предел заданий — единственное, что это останавливает. +8. **Нехватка памяти контейнера опаснее, чем выглядит:** ядро убивает процессы обработки сериями и доходит до процесса 1 worker (подтверждено журналом ядра в одном прогоне из пяти, ещё в одном — те же признаки). Настройка, которая не помещается в лимит, — это не только повторы, но и остановка всего worker до перезапуска и ожидание аренды. +9. **Короткая ячейка на свежем стенде не видит рост памяти S3 с накопленными объектами:** случай на старом стенде метка не воспроизведёт; ограничение названо (решение 12). + +## Goals / Non-Goals + +**Goals:** + +- Весь трек 1: ≥3 настройки на нескольких классах, throughput, очередь, p95 до `ready`, RSS, backpressure, ограничение принятой работы, восстановление, компромисс latency и ресурсов — с гипотезами до меток и повторяемой командой. +- Предел принятой работы без новой схемы и без лишнего шага с PostgreSQL. +- Прежние механизмы не меняются: места загрузки, цепочка сроков LB, outbox, аренда, fencing, сверка, `rolling_update`. + +**Non-Goals** (сознательно, сверх `proposal.md`): + +- смена значений `concurrency`, `prefetch` и лимитов контейнера заранее: решение после метки по правилу решения 12; +- ограничение по байтам и пикселям, предел на чат или пользователя (решение 1); +- замена процесса на задание forkserver: цена запуска названа пробой и меткой, замена — отдельное изменение; +- новая схема, новые индексы, новые значения `error_code`. + +## Decisions + +### 1. Граница принятой работы — предел незавершённых заданий, 429 + +Что считается: задания `queued` и `processing` — в том числе ожидающие следующей попытки и ещё не опубликованные. Именно эта работа уже обещана клиенту ответом 202, занимает staging и ждёт worker. `pending` не считается: его ответа ещё нет, он ограничен местами. `failed` и `succeeded` не считаются: работа кончилась, у `failed` staging держит срок хранения. + +Что видит клиент: 429 `rate_limited`, формат ошибки, `Retry-After`, сразу, без чтения тела и ожидания места. Ни строки, ни объекта. Это та же форма, что у занятых мест: клиент обязан уметь её и так. Повтор — новая загрузка: `Idempotency-Key` не нужен, отклонённая ничего не сохранила. + +**Контракт.** `contracts/openapi.json`: у `uploadAttachment` объявлены 429 с заголовком `Retry-After` — положительное целое, и 503 «Зависимость недоступна». `contracts/README.md`: «429 `rate_limited`», «Факультативный … rate limiting» не становится обязательным, но допустим. Рубрика трека прямо требует ограничения принятой работы. Противоречие одно, мягкое: 429 описан как «ограничение частоты запросов», а здесь ограничено количество работы; и уровень 3 говорит о 202 при остановленном worker. Строгая трактовка, которая проходит публичные тесты: у предела — 429, ниже него — 202 при любом состоянии брокера, relay и worker. `make test` и `tests/resilience.py` загружают единицы файлов. Вопросы преподавателю — `QUESTIONS.md`. Другой ответ меняет строку `DOMAIN_ERRORS` и сценарии. + +Почему не 503: зависимость жива, реплика готова, LB и монитор не должны видеть отказ; 503 смешал бы перегрузку с падением S3. + +| Вариант | Почему нет | +|---|---| +| Нет предела, копить до диска | рубрика; срок ожидания растёт без границы, рекомендовать нечего: проба 8/с против 3/с — +5 заданий в секунду, за час 18 000 заданий и 1,7 часа разбора | +| Возраст старейшего незавершённого | остановка worker дольше порога закрыла бы приём целиком: сценарий защиты «worker остановлен → 202» стал бы зависеть от часов; число принятого предсказуемо и объяснимо | +| Байты или пиксели в работе | точнее по ресурсам: `lp` стоит втрое дороже `s` при том же счёте. Но нужен `SUM` по строкам с чтением heap на каждую загрузку вместо счёта по индексу, а пикселей в строке нет; вместо этого предел выбран по худшему классу (решение 2), ограничение названо | +| Предел на чат или пользователя | справедливость, а не ограничение работы: нет индекса владельца у задания, новая схема; вне трека, ограничение названо | +| Ждать снижения счёта вместо отказа | работа уходит за секунды и минуты, держать соединение и место нельзя; для этого уже есть короткая очередь мест | +| Проверять после тела, перед `pending` | клиент передаёт 10 MiB ради отказа; реплика читает и считает SHA-256 зря | +| Жёсткий предел в транзакции `queued` | счёт под блокировкой на каждую фиксацию и компенсация записанного объекта ради точности ±40 из 250 | + +### 2. Значения: предел 250, `Retry-After` 5 + +**Предел 250.** Цель — ограничить срок, а не только число: ожидание при заполненном пределе = предел / потолок. Самый дорогой законный класс — `lp`, 0,92/с: 250 — это ~270 с. Сверху его ограничивает `[relay] republish_after_seconds` (300 с): ожидание в очереди короче порога потерянного сообщения, и копий не будет и при `prefetch` больше конкуренции. На остальных классах — 85–110 с. Объём staging при заполненном пределе — не больше 250 × 10 MiB ≈ 2,4 ГиБ плюс превышение. Значение — настройка `[uploads] max_unfinished_jobs` (`ge=0`, 0 — без предела): при другом числе worker предел другой, правило пересчёта — в `REPORT.md`. Правило и порог проверяет метка: гипотезы H4 и H5. Предел меньше `max_published_backlog` (1000): при значениях по умолчанию очередь брокера вмещает весь бэклог, а `max_published_backlog` остаётся страховкой на случай большего предела; менять его поводов нет (пробы: сообщение стоит брокеру меньше килобайта). + +**`Retry-After` 5** — константа `UPLOAD_BACKLOG_RETRY_AFTER_SECONDS` в `src/utils/constants.py`, рядом с `UPLOAD_RETRY_AFTER_SECONDS` (1 с): настройкой не заводится, между установками не различается. За 5 с worker завершает 4–15 заданий, повтор через секунду почти всегда получил бы тот же 429, а простоя не будет: при заполненном пределе работы на десятки секунд. Ровный повтор без случайной добавки — ограничение клиента, в ответе контракт добавки не предусматривает. + +### 3. Проверка в коде + +- **Порт и SQL:** `AbstractAttachmentJobRepository.count_unfinished(*, limit: int) -> int`: сумма трёх подзапросов «первые `limit` строк группы» по существующим частичным индексам, состояния — `literal(..., literal_execute=True)`, как у соседних выборок, иначе общий план — Seq Scan. Докстринг порта: «сумма не меньше `limit` тогда и только тогда, когда незавершённых не меньше `limit`»: счёт на группу обрывается на пределе, и цена не растёт с превышением. Один `execute` — правило `repo-layer.md`. Фейк `service-tests/fakes/repos.py`, строка `service-tests/repo_contract.py`, строка `test_status_is_a_constant_in_statement`. Миграции и нового индекса нет. +- **Сервис:** `AttachmentService.upload` в том же первом блоке единицы работы: `require_member` → 415 → 413 → `count_unfinished`. Проверки типа и размера переезжают внутрь блока: без соединения они не берут ничего (выдача ленивая, при попадании в кэш — ноль обменов), а блок на загрузке остаётся один. Поэтому **молчание реплики до тела прежнее** (`2 × request_timeout_seconds + wait_timeout_seconds` = 17 с < `timeout server` 30 с), цепочка LB и граница B уборщика не меняются. При `max_unfinished_jobs == 0` запроса нет. +- **Исключение:** `UploadBacklogFull` (`src/core/exceptions/attachment.py`), строка в `DOMAIN_ERRORS` (429 `rate_limited`) и `RETRY_AFTER` (`errors.py`), сообщение «Too many attachments are waiting for processing, retry later». +- **Журнал:** `info` «Rejected attachment» с `reason=backlog`, `unfinished`, `limit`, как у прочих отказов; «Started API» — `uploads_max_unfinished_jobs`. Метка сверяет число 429 с числом таких записей. +- **Что со временем отказа:** отказ не занимает места, поэтому посторонний поток 429 не вытесняет живые загрузки, а ожидающая в очереди мест загрузка не считается заново. + +**Превышение предела** — только в полёте: загрузка прошла счёт, ждёт место до 5 с и идёт до 30 с тела. На стенде 2 × (4 + 16) = 40, при замене реплик 60. Жёсткой границы нет намеренно (решение 1). + +**Смесь версий:** прежние реплики предел не считают; новая схема не нужна. Новый образ с прежним уборщиком и worker совместим. + +### 4. Цепочка сдерживания + +| Уровень | Что ограничивает | Значение | Что видит клиент | Где видно | +|---|---|---|---|---| +| Места загрузки реплики | память приёма, одновременные загрузки | 4 + 16, ожидание 5 с | 429, `Retry-After: 1` | журнал `busy`, k6 | +| **Предел заданий (новое)** | принятая работа, срок ожидания, staging | 250 | 429, `Retry-After: 5`, сразу | журнал `backlog`, k6, счёт незавершённых | +| Шлюз S3, 1 CPU, `concurrentUploadLimitMB` 64 — общий с worker | запись байтов приёма и обработки | 1 CPU, 64 МБ | загрузка дольше, до 3–6 с на `m`; за сроком вызова — 503; готовых/с падает | CPU S3, p95 загрузки, готовых/с в окне | +| Outbox | ничего: копит намерения | — | `queued` | `outbox`, возраст | +| `max_published_backlog` | очередь брокера | 1000 | `queued` | `published`, «Relay backlog is full» | +| Предел памяти брокера | издатель получает отказ по сроку | 400 МиБ | `queued` | журнал relay; пробы: нагрузкой не достигается | +| `prefetch` | выдача worker | 2 | `queued` | `messages_unacknowledged` | +| `concurrency` | работа в процессе | 2 | `processing` | `processing`, CPU | +| Лимиты процесса и контейнера | память и CPU на задание | 450 МиБ, 15 с CPU, 1 ГБ | дольше до `ready`; `failed` при исчерпании | `oom_kill`, `render_killed`, `failed` | + +Работа перестаёт **приниматься** на первых двух уровнях, перестаёт **ускоряться** — на CPU worker (`concurrency` сверх двух при 1 CPU) и, для тел у границы байтов, на CPU S3, причём там приём отнимает ресурс у обработки: предел заданий ограничивает и это. За входом клиент видит только дольше неизменный `queued`. Метка показывает это по уровням: ячейки матрицы — от outbox до `concurrency`, блок «приём» — S3, места и затем предел, блок «предел» — новый уровень отдельно. Предел памяти брокера и `max_published_backlog` при значениях по умолчанию нагрузкой не достигаются (пробы, решение 2): их работу доказывают прежние `test_broker_memory_alarm` и `test_published_backlog_limit`. + +### 5. Настройки и классы + +**Настройки** (`concurrency`, `prefetch`): (1, 1) — меньше памяти, простаивает на S3 и PostgreSQL; (2, 2) — значения по умолчанию; (4, 4) — больше конкуренции, чем CPU, и на `lp` больше памяти, чем лимит; (2, 256) — большой prefetch. Значение 256 больше любого бэклога ячейки: очередь брокера целиком уходит в один worker. + +**Классы** — `bench/make_images.py` в контейнере на образе стенда (`--network none`, Pillow образа, зерно `Profile.queue_image_seed` = 20261101, файлы проб), файлы — в `.work/`, размеры и SHA-256 — в паспорте, больше лимита контракта — отказ до стенда: + +| Класс | Файл | Зачем | λ низкая / высокая, /с | +|---|---|---|---| +| `s` | JPEG 1600 × 1200, q85 | мало пикселей: цена процесса и декодирования | 1,5 / 8 | +| `m` | PNG RGB из шума 1024 × 3409, IDAT zlib уровня 1, как тело 10 MiB профиля `uploads` | граница байтов: ввод-вывод, S3, SHA-256 | 1,5 / 6 | +| `lj` | JPEG 8000 × 5000, q88 | граница пикселей с `draft`: мало памяти | 1,2 / 6 | +| `lp` | PNG RGBA 8000 × 5000, значащие 4 бита на канал, плавная альфа | обе границы: больше всего памяти и CPU | 0,5 / 2,5 | + +Построение, как на пробе: канал — `Image.frombytes("L", …, random.Random(зерно).randbytes(…))` низкого разрешения, растянутый `BICUBIC` (64 ячейки по ширине), плюс такое же поле 512 ячеек, поделённое на 6, плюс плитка шума 512 × 512 амплитуды A, повторённая на всё поле (`ImageChops.add`); зёрна каналов — `зерно + номер`, `+ 10 + номер`, `+ 20 + номер`. `s`: зерно, A = 24, `subsampling="4:2:0"`. `lj`: зерно + 200, A = 24. `lp`: зерно + 200, без плитки, `point(v & 0xF0)` на каналах; альфа — поле 64 ячеек зерна + 300, `128 + v // 2`, тоже 4 бита; `compress_level=6`. `m`: `uploads.png_noise(3409, зерно + 3409)`. + +Ни один файл не тривиален для декодера: `lp` — настоящий inflate и Lanczos на 160 МБ пикселей и WebP с альфой 479 КиБ, `lj` — настоящий IDCT, `m` — масштабирование шума. Низкая λ — половина потолка настройки по умолчанию, высокая — 2–2,7 потолка, не выше того, что принимают реплики и S3. **Одна и та же λ для всех настроек класса:** сравниваются настройки при равной нагрузке. + +**Ячейки матрицы** — 12 конфигураций: (2, 2) и (4, 4) на всех четырёх классах; (1, 1) на `m` и `lp` (на классах с заметным вводом-выводом и большей памятью; `s` проба показала рядом с (2, 2)); (2, 256) на `s` и `lp` (самый короткий и самый длинный процесс). Вместе с блоками решения 8 — 19 конфигураций × 3 повтора = 57 ячеек, круги: на круге — перестановка всех конфигураций от зерна `Profile.order_seed`, первая ячейка круга не равна последней прошлого (`overload.plan_cells`, как `scaling.plan_cells`). Модуль называется `bench/overload.py`, а не `queue.py`: каталог скрипта стоит первым в `sys.path`, и `queue.py` затенил бы модуль stdlib, который импортируют `concurrent.futures` и `logging.handlers`. План — в `meta.json` до первой ячейки. + +### 6. Окна нагрузки + +Ячейка — свежий стенд (`kill`, `down -v`, затем `Stand.start`), пользователь и чат (`prepare.js`), разогрев: 12 файлов `s` до `ready` — они же готовые байты контрольного потока (`downloads.json`). Затем: + +| Окно | Длительность | Загрузки | Зачем | +|---|---|---|---| +| `before` | 10 с | низкая λ | задержка и ресурсы ниже потолка | +| `over` | 20 с (блоки предела и рестартов 25 с, приёма 45 с) | высокая λ | рост очереди | +| `recovery` | до нуля незавершённых, не дольше 420 с | нет | разбор очереди | +| `after` | 10 с | низкая λ | задержка вернулась | + +Открытая модель: `constant-arrival-rate` k6 (`bench/k6/queue.js`), сценарий на окно, `timeUnit: "10s"` для дробной λ. VU создаются заранее и не прибавляются (`queue_pre_vus`: окно `over` 20, у блока «приём» 80, окна ниже потолка 4): тело — `open` на VU, создание на ходу с телом 10 MiB теряет итерации (проба: 33–36 при 8 заранее и 60–80 пределе), а 80 VU — это уже ~2,7 ГиБ k6 при запасе ВМ. Ответ не повторяется: 429 — отказ, недосланные итерации — `dropped_iterations`, пометка. Строка на загрузку: `q,<окно>,<отправка мс>,<длительность мс>,<статус>,,,` в файл консоли, полнота — сверка с итерациями. Момент приёма — отправка + длительность по часам ВМ, как в профилях `failover` и `uploads`. + +Контрольный поток — готовый `bench/k6/background.js` (полнота `reconcile.line_problems`, остановка SIGINT): запись 10/с, чтение истории 10/с, скачивание готовых 5/с. Запущен до `before`, остановлен после `after`. Числа — ниже потолка API в разы: он меряет влияние перегрузки, а не нагружает. + +### 7. Метрики и определения + +**Очередь — три места и общий счёт.** Каждую секунду: + +| Поле | Что считаем | Откуда | +|---|---|---| +| `outbox` | `queued`, `published_at IS NULL`, срок наступил: relay ещё не передал | PostgreSQL | +| `waiting` | `queued`, `published_at IS NULL`, срок не наступил: пауза следующей попытки | PostgreSQL | +| `published` | `queued`, `published_at` есть: брокер подтвердил, никто не взял | PostgreSQL | +| `broker_ready` | `messages_ready`: лежит в брокере | метрики брокера | +| `broker_unacked` | `messages_unacknowledged`: выдано worker, не подтверждено | метрики брокера | +| `processing` | взято, идёт аренда | PostgreSQL | +| `prefetched` | `max(0, broker_unacked − processing)`: у worker, но ждёт места конкуренции | вычисляется | +| `unfinished` | `outbox + waiting + published + processing`: то, что считает предел | PostgreSQL | +| `oldest_s` | возраст старейшего незавершённого | PostgreSQL | +| `staging_ready` | `ready` с необнулённым `staging_key`: долг очистки | PostgreSQL | + +В строку ячейки — пики и значения на конце окна; в `timeline.csv` — посекундно. `queue_wait_ms` из журнала worker (от подтверждения брокером до взятия) — p50 и p95 по окнам: то, сколько задание провело собственно в очереди брокера и worker. + +**Throughput** — готовых в секунду: вложения с `updated_at` статуса `ready` в окне `over` и в окне `recovery`, делённые на длину окна. **Время до `ready`** — `updated_at` у `ready` минус момент ответа 202; p50, p95, p99 по окну прихода (`before`, `over`, `after`); для перцентилей `before` и `after` повторы сводятся вместе: заданий в них единицы и десятки. **Восстановление** — от последней загрузки окна `over` до нуля незавершённых. **`failed`** — по `error_code` и причине. + +**RSS и память:** `VmHWM` процесса 1 worker (`/proc/1/status`, `docker exec` в конце ячейки), `render_peak_kib` журнала — p50 и наибольший, `memory.peak`, наибольшие `memory.current` и `anon` контейнера, `oom_kill` (`memory.events`). `memory.peak` не нуждается в сбросе: контейнер новый в каждой ячейке; у перезапущенного worker — наибольшее по жизням (решение 10), `VmHWM` — последней жизни. **CPU и троттлинг** — ядер, доля и мс троттлинга (`cpu.stat`) worker, S3, PostgreSQL, реплик, relay, брокера, уборщика, LB по окнам, `reconcile.window_cpu`; CPU worker на задание — за всю ячейку. **Брокер:** наибольшая `memory.current` cgroup; сработавший предел памяти виден как отказ в журнале relay. + +**Журналы** (`docker logs`, только разбор, в метку не копируются): worker — «Started worker» (сверка настроек), «Started job attempt» (`queue_wait_ms`, `redelivered`), «Attachment became ready» (`render_ms`, `render_peak_kib`, `duration_ms`), «Retrying job», «Attachment failed», «Skipped job message»; relay — сумма `published`, `republished`, `recovered`, «Relay backlog is full»; реплики — «Rejected attachment» по `reason`; уборщик — «Finished staging cleanup pass». + +### 8. Блоки сверх матрицы + +| Блок | Конфигурация | Что меряет | Что ждём по пробе | +|---|---|---|---| +| `gate-on` | `s`, (2, 2), 20/с, 25 с, предел по умолчанию | плато незавершённых, 429, задержку | плато 250, 429 ~180, p95 до `ready` и восстановление ~85 с | +| `gate-off` | то же, `UPLOADS__MAX_UNFINISHED_JOBS=0` | рост без предела | пик ~430, p95 и восстановление ~145 с | +| `accept` | `m`, (2, 2), 15/с, 45 с, предел по умолчанию | цепочку приёма: S3, места, затем предел; что с worker | 429 `busy` с ~10-й секунды, `backlog` с ~35-й, S3 у 1 CPU до предела, ~0,6 готовых/с до него, пик 250–290 | +| `w2-p2` | `s`, (2, 2), второй worker в конце `over` | ускорение от ресурса | ~5,4/с вместо ~3/с | +| `w2-p256` | `s`, (2, 256), то же | простой второго worker | второй берёт 0 заданий | +| `kill-worker` | `s`, (2, 2), 8/с, 25 с, KILL и запуск в середине | не теряем, аренда | две попытки у 2 заданий | +| `restart-broker` | `s`, (2, 2), 8/с, 25 с, `compose restart` в середине | не теряем, outbox растёт на время рестарта | попыток сверх одной нет | + +Второй worker — `docker compose run -d --no-deps --name mtusi-bench-worker-2 worker` с тем же override; момент запуска — конец `over`, а не середина: новые сообщения во время `over` брокер делил бы поровну и смазывал бы опыт, а реальный ответ оператора на перегрузку — запуск после обнаружения. Базовая линия без второго worker — ячейки матрицы (`s`, (2, 2)) и (`s`, (2, 256)). Доля заданий второго — по его журналу. Лимиты те же, бюджет — решение 10. + +Копии при `prefetch` больше конкуренции (проба: 188 на 150 заданий при пороге 15 с) в метку не входят: опыт требует менять порог, а на значениях по умолчанию при пределе 250 бэклог короче порога. Механизм уже назван в `REPORT.md`, эффект нулевой, и его закрывает правило `prefetch = concurrency` решения 12. При (2, 256) в матрице число копий пишется как есть (ждём 0). + +### 9. Граница чёрного ящика + +Генератор — только HTTP через LB. **Истина о готовности — `GET /attachments/{id}`:** после окна `after` и разбора очереди `bench/k6/queue_sweep.js` запрашивает метаданные каждого принятого вложения (`shared-iterations`, ids из строк k6): статус, `error_code`, число вариантов, `updated_at`; у выборки (10 на ячейку, от зерна) скачивает оригинал и три варианта и сверяет SHA-256 с метаданными. Живой опрос не нужен: `updated_at` у `ready` не меняется после фиксации (`clear_staging_key` его не трогает, сценарий «Готовое вложение не откатывается»), а нагрузки опроса на API в замере не будет. Новые исключения из границы чёрного ящика, только у этого профиля и только на чтение: +- `psql \watch` сэмплера — счётчики задач выше и чтение SQL в конце ячейки: одно задание на вложение, три варианта на `ready`, попытки, причины (`pg_stat_*` не нужны). Данных и схемы оркестратор не меняет; +- метрики брокера по HTTP в сети стенда; +- журналы контейнеров, разбор без копирования. + +### 10. Стенд и сэмплер + +- **`bench/queue.compose.yml`** (статический, третий `-f` только у этого профиля): у `rabbitmq` — read-only файлы `bench/rabbitmq/enabled_plugins` и `bench/rabbitmq/91-bench.conf` (`collect_statistics_interval = 1000`). Порт 15692 — только сеть стенда: порты сброшены в `bench.compose.yml`. У прочих профилей и рабочего стенда плагина нет. Окружение настроек — `.work/variant.compose.yml`, как у `uploads`: `WORKER__CONCURRENCY`, `WORKER__PREFETCH`, `UPLOADS__MAX_UNFINISHED_JOBS`. +- **Перезапуск worker** — `restart: unless-stopped` в `queue.compose.yml`, как на рабочем стенде, а не `"no"` из `bench.compose.yml`: проба — ядро убивает процесс 1 при (4, 4) на `lp`, и без перезапуска ячейка простояла бы до срока окна с ложными `stuck`. Столбец `worker_restarts` — `.RestartCount`, пометка `worker_restart`. Перезапуск сбрасывает cgroup того же контейнера: `memory.peak` и наибольшая `anon` — наибольшее по жизням, `oom_kill` — сумма, CPU — разности внутри жизни. У S3 остаётся `"no"`: его гибель — аномалия, она должна быть видна пометкой `storage_down`, а не пережита. `docker kill` блока `kill-worker` демон считает ручной остановкой, запуск — явный `docker start`; успей он раньше — `start` ничего не меняет. +- **`Stand.start`** при `is_queue`: S3 и bootstrap, брокер, реплики и LB, relay, уборщик и worker `--no-deps`. Уборщик работает: иначе staging копился бы мимо рабочего поведения; плановая сверка выключена (`bench.compose.yml`). `Stand.stop()` и `leftovers()` — ещё `mtusi-bench-worker-2`, `mtusi-bench-images`. Перед `down` — `compose kill`: S3 иначе останавливается ~15 с. +- **`sampler.sh`, режим `queue`:** раз в секунду — обход cgroup, как `scan` (`cg`), `vm`, `lb`; новые строки `mp <нс> ` и `mq <нс> ` (`/dev/tcp/rabbitmq/15692`, HTTP/1.0, фильтр по имени очереди; брокер недоступен — `mq <нс> missing`). В фоне `psql \watch` — строка `jobs` с полями решения 7, один запрос в секунду на маленькой таблице свежего стенда. Контейнер: `--cgroupns host`, сеть стенда, `--env POSTGRES_PASSWORD`, 0,25 CPU / 128 МиБ. Разбор — `bench/overload.py`, `cg` и `vm` — `scaling.parse_samples`. Роли — `Stand.container_map()`: второй worker и контейнер после рестарта видны сами; сторож — тиков нет 3 с в нагрузке — отказ, как у `failover`. +- **Готовность к сравнению:** `limits` читаются у запущенных контейнеров, на все ячейки одни (кроме второго worker). Запись «Started worker» сверяется с ячейкой: расхождение — отказ. +- **Бюджет:** CPU реплики 2 + PostgreSQL 2 + LB 1 + Valkey 0,5 + S3 1 + брокер 1 + relay 0,25 + worker 1 (второй ещё 1) + уборщик 0,25 + сэмплер 0,25 = 9,25–10,25 из 12; память лимитов 5–6 ГиБ плюс k6 до ~2,7 ГиБ на блоке приёма из 7,75: занято по пробам ~3,5 ГиБ без k6, сумма лимитов до конца не выбирается. `vm_warnings` считает эти роли, сумма CPU больше ВМ — код 2 до стенда, как `level4_budget`. Посторонние контейнеры — в паспорт. + +### 11. Достоверность и шум + +**Пометки строки** (`flags`): `oom` — `oom_kill > 0`; `worker_restart` — ядро завершило процесс 1, контейнер перезапущен; `lost` — принято, а метаданных нет; `stuck` — не `ready` и не `failed` к концу; `duplicate` — заданий на вложение больше одного или вариантов не три; `sha_mismatch`; `not_recovered` — срок окна `recovery` вышел; `failed` — есть `failed`; `dropped` — недосланные итерации; `lb_down` — реплика выходила из LB; `host_swap`; `storage_down`. `lost`, `stuck`, `duplicate`, `sha_mismatch` дают ненулевой код команды в конце метки (ячейки сняты, отказ — на всю метку): замер, где система потеряла работу, — это результат, а не сбой команды, но зелёной метка быть не должна. `oom`, `worker_restart` и `failed` — результат настройки. + +**Шум.** Объявлено заранее: разброс — min–max трёх повторов одной конфигурации; разница двух конфигураций считается эффектом, только если их разбросы не пересекаются и разница медиан больше наибольшего разброса пары; иначе пишется «в пределах шума». На пробах разброс трёх повторов — 1–8 % по throughput и до 3 % по памяти («Шум и цена стенда»): допуски гипотез ниже шире него. Отдельной метки A/A нет: это умножило бы время, а настройка по умолчанию повторяется в каждом круге и служит опорой. + +**Хост** — `bench.md`: перед меткой рабочий стенд `make stop`, питание от сети. Прирост `Swapouts` за ячейку — пометка `host_swap`: настоящая помеха, такая метка переснимается под новым именем, если задетые ячейки входят в выводы; каталог метки не перезаписывается. Прочие предупреждения о хосте, явно не влияющие на замер, прогон не останавливают (указание пользователя 2026-10-31). + +### 12. Гипотезы, правило рекомендации и значения по умолчанию + +Записываются в `REPORT.md` и коммитятся раньше меток замера. Числа — из проб выше. Вердикт считает `bench/overload.py`, в сводке: «подтверждено», «нет», «нет данных». + +| № | Гипотеза | Подтверждено, если | +|---|---|---| +| H1 | Потолок при 1 CPU — CPU worker; конкуренция сверх двух его не поднимает | на всех классах медиана throughput окна `recovery` (4, 4) / (2, 2) ≤ 1,05; CPU worker в окне `over` при c ≥ 2 ≥ 0,85 ядра; на `m` и `lp` (1, 1) / (2, 2) ≤ 1,0 | +| H2 | Обработка задания дольше пропорционально конкуренции, память растёт на пик процесса | `duration_ms` p50 (4, 4) / (2, 2) ≥ 1,5 на всех классах; `memory.peak` (2, 2) < 1 ГБ без `oom` на всех классах; (4, 4) на `lp`: `memory.peak` ≥ 95 % лимита во всех повторах, `oom_kill` > 0 хотя бы в одном (пробы: в трёх прогонах из четырёх); (4, 4) на `lj`: без `oom`, пик ≤ 500 МиБ | +| H3 | Большой prefetch не меняет throughput одного worker и прячет очередь от брокера и второго worker | (2, 256) / (2, 2): throughput в [0,85; 1,15], p95 до `ready` в [0,8; 1,25] на `s` и `lp`; пик `broker_ready` ≤ 10 % пика незавершённых у (2, 256), ≥ 70 % у (2, 2); блок второго worker: доля второго среди заданий, завершённых после его запуска, ≥ 30 % при `prefetch` 2 и ≤ 5 % при 256, восстановление p256 / p2 ≥ 1,4 | +| H4 | Задержка под перегрузкой — это очередь | на всех ячейках матрицы без `oom` p95 до `ready` окна `over` в [0,8; 1,25] × пик незавершённых / throughput | +| H5 | Предел ограничивает принятую работу и срок ожидания | `gate-on`: пик незавершённых ≤ 290, 429 > 0, у всех `Retry-After` 5, 5xx нет, 429 = записи `backlog`; `gate-off`: пик ≥ 375; `gate-on` / `gate-off`: p95 до `ready` и восстановление ≤ 0,75; p95 до `ready` `gate-on` в [0,8; 1,25] × предел / throughput; загрузка `before` p50 `gate-on` − `gate-off` ≤ 3 мс (проба A/B: +0,9 мс) | +| H6 | Восстановление: система приходит в норму сама и никого не теряет | во всех ячейках `lost`, `stuck`, `duplicate`, `sha_mismatch` нет; восстановление ≤ 1,3 × пик незавершённых / throughput окна `over` (матрица без `oom`, предел); p95 `after` ≤ 1,5 × p95 `before` по конфигурации; `failed` только при `oom` и только `retry_exhausted` | +| H7 | Перегрузка очереди не задевает остальной API | во всех окнах всех ячеек, кроме `accept`: p95 записи и чтения ≤ 200 мс, скачивания ≤ 500 мс; 5xx контрольного потока нет; `lb_down` нет | +| H8 | Рестарты под перегрузкой не теряют работу | `kill-worker`: всё `ready`, заданий с повторной попыткой ≤ 2, очередь разобрана не позже большего из «конец `over` + 1,3 × пик / throughput» и «KILL + аренда 70 с + 15 с»; `restart-broker`: всё `ready`, заданий с повторной попыткой нет, 5xx на загрузке нет, восстановление ≤ 1,3 × пик / throughput + 15 с | +| H9 | Приём ограничен S3, местами и затем пределом, а не падением; S3 общий с worker | `accept`: первый 429 `busy` раньше первого `backlog`, оба есть, 5xx нет; CPU S3 в первые 30 с окна ≥ 0,85; принято за окно / длина окна ≥ 6/с (λ `m` в матрице); пик незавершённых ≤ 290; готовых/с в окне ≤ 1,5 при ≥ 2,4 в окне восстановления; контрольный поток: запись и чтение p95 ≤ 200 мс, скачивание ≤ 1 с, без 5xx | + +**Правило рекомендации** (считается в сводке, вывод — в `REPORT.md`): кандидат — настройка без `oom` и `failed` ни на одном классе, с throughput не ниже 90 % лучшей на каждом классе; из кандидатов — наименьшая конкуренция, а `prefetch` равен конкуренции: большему нечего добавить (H3). **Значения по умолчанию** меняются, только если рекомендация отличается от (2, 2), и выигрыш по throughput или памяти на каком-либо классе вне шума при том, что на остальных она не хуже в пределах шума; такая правка — отдельный commit после метки с повтором `make bench_queue_quick`, а не переснятие. По пробам ждём, что (2, 2) остаётся: (1, 1) теряет 12–15 % на `lp` и `m`, (4, 4) упирается в память. **Компромисс latency и ресурсов** — вывод из таблиц метки: что даёт память при той же скорости, что даёт CPU (второй worker), и при каких условиях поднимать конкуренцию: `concurrency ≤ min(CPU + доля ожидания, (лимит − база) / пик процесса)`. Формула — гипотеза в отчёте, её члены — числа метки. + +**Ограничения метода** — в отчёт дословно по метке: +- один хост и ВМ Docker Desktop (arm64, 12 CPU, 7,75 ГиБ): лимит 1 CPU — квота CFS, а не отдельное ядро; генератор и посторонние контейнеры на той же ВМ, доля их CPU видна по `vm`; +- один worker; второй — только в своём блоке и на классе, где S3 не узкое место: общая формула масштабирования не утверждается; +- ячейка — один класс, один файл на все загрузки: смесь размеров и разброс содержимого не мерятся; +- окна короткие, 20–45 с перегрузки: многочасовая перегрузка, autovacuum под длинным оборотом и рост WAL не мерятся, проба — только 90 с оборота; +- открытая модель без повторов: поток клиентов, послушно повторяющих после `Retry-After`, не мерится; отказ считается отказом; +- PostgreSQL, relay и брокер в этих интенсивностях не упираются: их предел трек не определяет; `max_published_backlog` и предел памяти брокера нагрузкой не достигаются (решение 4); +- одна нода S3, staging и конечный префикс на одном диске ВМ; ячейки — на свежем volume, поэтому рост памяти S3 с накопленными объектами не мерится (проба на старом стенде — `KNOWN_ISSUES.md`); +- выборки `before` и `after` малы на `lp`: повторы сводятся, p99 у малых выборок — только справочно; +- завершение процесса 1 ядром при (4, 4) на `lp` случайно (пробы: один подтверждённый случай и один по тем же признакам из пяти прогонов): его частота из трёх повторов не следует, метка показывает, что работа не теряется. + +### 13. Что ещё меняет предел + +- **Профиль `uploads`:** worker в нём нет, задания копятся; `.work/variant.compose.yml` всех его вариантов получает `UPLOADS__MAX_UNFINISHED_JOBS=0` (спек, сценарий «Предел заданий не участвует»). Прежние метки не сравниваются (они и так не сравнивались, решение 16 архива). +- **Стенд отказов:** у четырёх прежних API `UPLOADS__MAX_UNFINISHED_JOBS=0` (`run_failures.py`): `test_reconcile_under_load` — 16 загрузок/с против ~4/с, остановленные worker других проверок. Пятый API — «узкий по заданиям», `BACKLOG_ENV` = `UPLOADS__MAX_UNFINISHED_JOBS=3` → `FAULT_BACKLOG_BASE_URL`, `FAULT_BACKLOG_ENV`, фикстура `backlog_api`, `assert_backlog_stand`; `pytest -m fault` без него — отказ, как у остальных. +- **`make test_isolated`, `make student_test`, `driver.py`:** значение по умолчанию; единицы загрузок, `reconcile-stress` — `upload_ready` по очереди, замкнутый контур: предела не достигают. + +### 14. Файлы метки и цена + +`evidence/queue/<метка>/`: `meta.json` (профиль, образы, классы и SHA-256, план, лимиты, окружение, `host_state`), `cells.csv` (строка на ячейку, новые столбцы — только в конец; готовая строка — признак для `RESUME=1`), `timeline.csv` (посекундно, с отметками окон), `summary.md`, `throughput-by-setting.svg`, `p95-by-setting.svg`, `memory-by-setting.svg`, `backlog-gate.svg` (`plots.Svg`), `raw/<ячейка>-k6.json` (итоги k6 без токенов). `quick-queue-*` — в `.gitignore`. `RESUME=1` и блокировка — как у серий. + +**Время.** Ячейка матрицы: стенд с уборкой ~30 с, разогрев ~5, окна 10 + 20 + ~39 (среднее восстановление по пробам, `lp` при (4, 4) — 40–80 с) + 10, конец ~8 = ~122 с; 12 × 3 = 36 ячеек — ~73 мин. Блоки: `gate-off` ~240 с, `gate-on` ~175, `accept` ~210, `w2-*` ~100–115, `kill-worker` и `restart-broker` ~140–150, вместе 7 × 3 = 21 ячейка — ~57 мин. **Полная метка — чуть больше двух часов (~2 ч 10 мин)** плюс сборка и файлы классов ~1 мин; перезапуск worker с ожиданием аренды добавляет ячейке до 70 с. `queue_quick` — `s` (2, 2), `lp` (4, 4), предел с `UPLOADS__MAX_UNFINISHED_JOBS=40` и без него, `kill-worker`, `w2-p256`, по одному повтору, окна 5 + 10 + … + 5: ~11 мин. + +### 15. Сценарий защиты и документы + +**Защита:** шаг «для 5 — выбранный эксперимент» — `make bench_queue_quick` (~11 мин, заранее или на глазах) и разбор `evidence/queue/baseline/summary.md`: таблица настроек, плато предела, второй worker, рестарты. Новой команды драйвера нет: она повторяла бы профиль. + +**`REPORT.md`:** «Трек 1 уровня 5» в таблице критериев; раздел экспериментов с гипотезами (до метки), методикой, определениями, таблицами, выводами; «Сервисы и лимиты», «Открытые вопросы», «Ограничения»: снимаются записи «Дорогие файлы тратят CPU до лимита», «Отставание очистки staging», «Цена процесса на задание», «Ограничения принятой работы на входе API нет» — заменяются измеренным; новое ограничение — завершение процесса 1 worker ядром при конкуренции, которая не помещается в лимит. **Правила:** `bench.md` (раздел профиля), `worker.md`, `settings.md`, `api-contract.md`, `service-layer.md`, `repo-layer.md`, `logging.md`, `student-tests.md`; **`AGENTS.md`** — статус лабы, команды, карта кода; `config_example.toml`. `QUESTIONS.md` — раздел этого change, вопросы переносятся в `REPORT.md`. + +## Покрытие сценариев + +Сценарии спеков из `CAPABILITIES`; `fault` — `make failure_checks`, стенд с пятым API. + +| Capability, сценарий | Проверка | +|---|---| +| `queue-overload` «Предел достигнут», «Порядок проверок у предела», «Остальной API у предела», «Загрузки снова принимаются» | `test_backlog_limit`, fault | +| «Завершённые задания не считаются» | `test_backlog_ignores_finished`, fault | +| «Ожидание следующей попытки считается» | `test_backlog_counts_waiting_retry`, fault | +| «Предел при остановленных брокере и relay» | `test_backlog_without_broker`, fault | +| «Превышение ограничено» | `test_backlog_overshoot_bounded`, fault | +| «Предел выключен» | `test_backlog_off`, fault | +| «Работа копится там, где положено», «Приём упирается в места загрузки», «Сначала места, затем предел», «Контрольный поток под перегрузкой», «Бэклог уходит за измеренное время», «Никого не теряем», «Время до готовности вернулось», «Worker убит под перегрузкой», «Брокер перезапущен под перегрузкой» | исключения сверки (нужна открытая нагрузка, счётчики и рестарт контейнера): `make bench_queue` → `evidence/queue/baseline/summary.md` | +| `attachments` «Порядок проверок загрузки» | прежние тесты; новый шаг — `test_backlog_limit` | + +Вне сверки: `service-configuration` — `service-tests` (настройка), запись о старте — журнал пятого API в `test_backlog_limit`-наборе и `make run_docker`; `load-benchmark` — `make bench_queue_quick`, `make bench_uploads_quick`; `health`, `job-outbox`, `message-broker` — прежние тесты, текст уточнён. + +## Risks / Trade-offs + +- [Предел один на стенд: один клиент может занять его целиком] → ограничение названо; места загрузки ограничивают скорость такого клиента; справедливость — отдельная тема вне трека. +- [Счёт — по числу, а `lp` втрое дороже `s`] → значение выбрано по худшему классу, у мелких файлов предел консервативен; видно в таблицах. +- [Предел отклоняет загрузки при остановленном worker] → это и есть граница; текст, история, метаданные, готовые байты и `/health/ready` работают (сценарий), `make replay` не задействован; при длинном простое оператор видит `backlog` в журнале. +- [`Retry-After` без случайной добавки: клиенты могут повторять разом] → у них 5 с; отказ — один запрос к PostgreSQL, 1,9 мс CPU реплики и 0,3 мс PostgreSQL (проба), ~1 000 отказов/с на двух репликах; места не занимает. +- [Счёт идёт в первом блоке: загрузка, попавшая в кэш чата, теперь берёт соединение] → +0,9 мс p50, +0,8 мс CPU реплики и +0,4 мс PostgreSQL на самой дешёвой загрузке (проба A/B, оценка сверху); `[database]` срок прежний; шаг прежний, цепочка LB та же. +- [Приём на границе байтов отнимает S3 у worker: ~0,6 готовых/с вместо 2,9] → предел заданий останавливает это на 250, но не раньше ~35 с такой нагрузки; места и `concurrentUploadLimitMB` пока делят ресурс как есть. Отдельный приоритет обработки — вне трека, вывод — по метке. +- [Ядро может убить процесс 1 worker, если конкуренция не помещается в лимит] → работа не теряется, контейнер перезапускается, задания возвращаются по аренде (до 70 с); значение по умолчанию на всех классах помещается; правило подбора конкуренции — `worker.md`. +- [S3 на долго живущем стенде подходит к лимиту памяти] → вне метки, `KNOWN_ISSUES.md` с предложением; рабочий стенд перезапускает его сам, а бюджет задания переживает короткий рестарт. +- [Плагин метрик брокера только в профиле] → паспорт называет; простой + 0,1 % ядра, файлы конфигурации только у этого профиля; рабочий стенд не меняется. +- [Метка ~2 ч 10 мин на ноутбуке] → `caffeinate`, `RESUME=1`, предупреждения о хосте; порядок кругами размазывает дрейф хоста по конфигурациям. +- [Одна λ на все настройки: у (1, 1) и (4, 4) очередь больше] → это и меряется; `recovery` ограничен 420 с, `not_recovered` — пометка. +- [Малые выборки `before` и `after` у `lp`: 4–5 заданий] → повторы сводятся; вывод только с разницей больше разброса, в отчёте названо. +- [Заливка одним и тем же файлом класса] → дедупликации в приложении и в S3 нет; разнообразие контента не проверяется, это ограничение синтетики, названо. +- [Один worker и один хост: второй worker на той же ВМ, S3 один] → блок `w2-*` — на `s`, где S3 не узкое место (0,09 ядра); общая формула масштабирования не утверждается. + +## Migration Plan + +1. Шага оператора нет: секретов и схемы не прибавилось; существующий `config.toml` — значение по умолчанию. +2. Вперёд: `make rolling_update`. Смесь реплик безопасна: прежние предел не считают. +3. Откат: `make rolling_update COMMIT=<прежний> MIGRATE=0`. Данные не менялись. +4. После проб в scratchpad остаётся `track1/` (кандидаты, скрипты, журналы). Контейнеры, сети и образы проекта `q1probe` удалены. Остались его volumes `q1probe_postgres_data`, `q1probe_rabbitmq_data`, `q1probe_s3_data`: при уборке автопроверка отказала в команде с `docker compose … down -v`, обход не применялся; удалить вручную — `QUESTIONS.md`, «Для пользователя после прогона». + +## Open Questions + +Вопросы преподавателю — `QUESTIONS.md`, раздел `track1-queue-overload`: ни один не меняет подход и задачи; другой ответ меняет строку таблицы ошибок и сценарий. diff --git a/openspec/changes/track1-queue-overload/proposal.md b/openspec/changes/track1-queue-overload/proposal.md new file mode 100644 index 00000000..c210dc2f --- /dev/null +++ b/openspec/changes/track1-queue-overload/proposal.md @@ -0,0 +1,73 @@ +# Proposal + +## Why + +Лаба 5, уровень «5», трек 1 «Очередь под перегрузкой» (`README.md`, выбор пользователя): сравнить ≥3 настройки +concurrency и prefetch на разных размерах изображений, измерить throughput, queue lag, p95 времени до `ready` и RSS, +показать backpressure и ограничение количества принятой работы, доказать восстановление и объяснить компромисс latency +и ресурсов. Уровень 4 закрыт (`pipeline-reliability`, `unit-of-work`), но под перегрузкой конвейер пока только гипотеза, а +приём не ограничен ничем, кроме мест загрузки: 202 отвечает всегда, и бэклог в `attachment_jobs` растёт без предела. Третье +из трёх изменений пути к оценке 5. + +## What Changes + +- **Ограничение принятой работы на входе API.** Новая граница `[uploads] max_unfinished_jobs` (по умолчанию 250, 0 — без + предела): если незавершённых заданий (`queued` + `processing`) не меньше предела, загрузка получает 429 `rate_limited` с + `Retry-After: 5`, не занимая место загрузки и не читая тело; ни строки, ни объекта. Предел один на стенд (считается в + PostgreSQL), мягкий: превышение не больше загрузок в полёте. Проверка — одним запросом по существующим частичным индексам, в + том же шаге, что членство: новой таблицы, индекса и миграции нет, цепочка сроков LB прежняя. +- **BREAKING (внутри лабы, контракт и публичные тесты не меняются):** ответ на загрузку больше не безусловно 202 при отказе + брокера, relay или worker: они по-прежнему не влияют на ответ напрямую, но принятая работа копится, и у предела клиент получает + 429. Текст, история, метаданные, готовые байты и `/health/ready` от предела не зависят. +- **Профиль стенда `bench/`** `make bench_queue` (быстрая самопроверка `make bench_queue_quick`, метки + `evidence/queue/<метка>/`): открытая модель загрузок через LB с окном перегрузки выше потолка worker и спадом до нуля, настройки + concurrency и prefetch × классы изображений × 3 повтора на свежем стенде, контрольный поток JSON-ручек и готовых байтов, истина о + готовности — `GET /attachments/{id}`, очередь — в трёх местах (outbox, брокер, взятые worker), память и CPU worker и процессов + обработки, блоки предела, приёма, второго worker и рестартов под перегрузкой. +- **Гипотезы H1…H9 с порогами** — в `REPORT.md`, commit раньше меток замера. Компромисс latency и ресурсов, рекомендуемая настройка и + решение о значениях по умолчанию — вывод из метки, а не заранее. +- **Сценарий защиты:** шаг «для 5 — выбранный эксперимент» — `make bench_queue_quick` и разбор сводки метки. + +**Не входит:** трек 2; автомасштабирование; смена брокера; новые варианты изображений; изменения контракта; телеметрия лабы 6; +справедливость предела между пользователями и чатами (предел один на стенд, ограничение названо в `REPORT.md`); forkserver вместо +процесса на задание (пробы: ~0,2 с CPU на малом файле, вывод — по метке); приоритет обработки над приёмом в S3 (пробы: приём на границе байтов +отнимает S3 у worker, вывод — по метке); рост памяти S3 с накопленными объектами (проба на старом стенде: S3 убит ядром, `KNOWN_ISSUES.md`). + +Не меняются: `contracts/`, `tests/`, `README.md`, `COURSE.md`, `lab.json`, `CONTRIBUTING.md`, `MAINTAINERS.md`. + +Шага оператора нет: новых секретов нет, существующий `config.toml` остаётся рабочим, новое поле берёт значение по умолчанию. + +## Capabilities + +### New Capabilities + +- `queue-overload`: предел незавершённых заданий и что видит клиент у предела, цепочка сдерживания, работа API под перегрузкой, + восстановление после перегрузки, рестарты worker и брокера под перегрузкой. + +### Modified Capabilities + +- `attachments`: порядок проверок загрузки — новый шаг перед местом загрузки. +- `job-outbox`: приём не зависит от брокера напрямую, но ограничен пределом незавершённых заданий; ссылка из «Предела опубликованных + заданий». +- `message-broker`: брокер не критичен для приёма в пределах ограничения принятой работы. +- `health`: пояснение к некритичным зависимостям в тех же пределах. +- `service-configuration`: `[uploads] max_unfinished_jobs`, запись о старте API. +- `student-tests`: сверка покрытия `queue-overload`, пятый API стенда отказов («узкий по заданиям»), новое действие hook. +- `load-benchmark`: брокер, relay, worker и уборщик на стенде в новом профиле, требования «Профиль очереди» и «Очередь под перегрузкой в + отчёте»; профиль загрузок — без предела заданий. + +## Impact + +- **API:** коды и схемы контракта те же; 429 с `Retry-After` уже есть в `contracts/openapi.json` у загрузки. Трактовка — вопрос + преподавателю (`QUESTIONS.md`, `## track1-queue-overload`, переносится в `REPORT.md`). +- **Код:** `src/core/services/attachment.py`, `src/core/ports/attachment_job.py`, `src/core/repos/attachment_job.py`, + `src/core/exceptions/attachment.py`, `src/api/errors.py`, `src/config/settings.py`, `src/utils/constants.py`, `src/main.py`. Зависимостей + и миграций нет. +- **Тесты:** `service-tests/` (ветка сервиса, контракт repo), `student-tests/` (проверки отказов, `run_failures.py`, `fault_hook.py`, + `spec_coverage.py`). +- **Инструменты:** `bench/` (новые `overload.py`, `make_images.py`, `k6/queue.js`, `k6/queue_sweep.js`, `queue.compose.yml`, `rabbitmq/`; + `run.py`, `sampler.sh`), `Makefile`, `.gitignore`. +- **Документы:** `.claude/rules/` (`bench.md`, `worker.md`, `settings.md`, `api-contract.md`, `service-layer.md`, `logging.md`, `student-tests.md`, + `repo-layer.md`), `AGENTS.md`, `QUESTIONS.md`, `REPORT.md`, `config_example.toml`, evidence. +- **Ресурсы:** на запрос загрузки — один запрос к PostgreSQL: +0,9 мс p50, +0,8 мс CPU реплики и +0,4 мс CPU PostgreSQL на самой дешёвой загрузке (пробы A/B, + оценка сверху); полная метка замера ~2 ч 10 мин на хосте при остановленном рабочем стенде, быстрая самопроверка ~11 мин. diff --git a/openspec/changes/track1-queue-overload/specs/attachments/spec.md b/openspec/changes/track1-queue-overload/specs/attachments/spec.md new file mode 100644 index 00000000..f97ad99e --- /dev/null +++ b/openspec/changes/track1-queue-overload/specs/attachments/spec.md @@ -0,0 +1,46 @@ +## MODIFIED Requirements + +### Requirement: Порядок проверок загрузки + +Если у загрузки несколько ошибок, ответ SHALL определяться первой из +них по порядку: +1. 401 — нет действительной сессии; +2. 400 — неверный `chat_id` или `filename`; +3. 404 — чата нет или пользователь в нём не состоит; +4. 415 — `Content-Type` запроса; +5. 413 — `Content-Length` запроса; +6. 429 — незавершённых заданий не меньше предела (`queue-overload`, «Предел + незавершённых заданий»); +7. 429 — нет места для загрузки (требование «Одновременные загрузки + реплики»); +8. тело: 413 — прочитано больше лимита; 400 — тело не пришло за срок + (требование «Срок передачи тела») или клиент оборвал передачу; +9. 415 или 413 — содержимое: формат и целостность или число пикселей. + +Тело MUST NOT читаться, пока не пройдены проверки 1–7. Загрузка, +отклонённая на проверках 1–6, MUST NOT ждать места и занимать его. +Ошибка клиента MUST NOT давать 500. + +#### Scenario: Посторонний с большим файлом + +- **WHEN** Ева загружает 30 MiB в чат Алисы и Боба +- **THEN** ответ 404 `not_found`, а не 413 + +#### Scenario: Без сессии с опасным именем + +- **WHEN** загрузка без `Authorization` идёт с `filename` `a/b.png`, а + затем с допустимым именем +- **THEN** оба ответа 401 `unauthorized` с `WWW-Authenticate: Bearer` + +#### Scenario: Неверный тип и большой размер + +- **WHEN** участник загружает 30 MiB с `Content-Type: text/plain` +- **THEN** ответ 415 `unsupported_media_type` + +#### Scenario: Отказ раньше очереди + +- **WHEN** все места загрузки процесса заняты и очередь ожидания полна, + и посторонний загружает файл в чат, участник загружает 30 MiB с + `Content-Length` 31 457 280, а затем PNG с `Content-Type: text/plain` +- **THEN** ответы 404, 413 и 415 приходят сразу, без ожидания места, а + не 429 diff --git a/openspec/changes/track1-queue-overload/specs/health/spec.md b/openspec/changes/track1-queue-overload/specs/health/spec.md new file mode 100644 index 00000000..8b78a256 --- /dev/null +++ b/openspec/changes/track1-queue-overload/specs/health/spec.md @@ -0,0 +1,57 @@ +## MODIFIED Requirements + +### Requirement: Readiness + +`GET /health/ready` SHALL отвечать 200 с телом `{"status": "ok"}`, +когда сервис может безопасно обслуживать обязательные запросы, и 503 с +`code` `unavailable` в формате ошибки, когда не может. Критичная +зависимость — PostgreSQL: проверка SHALL выполнять запрос к нему с +коротким таймаутом при каждом обращении. + +Пять зависимостей не критичны, и их недоступность MUST NOT делать сервис +неготовым: +- Valkey — кэш: без него обязательные запросы обслуживаются из + PostgreSQL; +- S3 — хранилище байтов вложений: путь без вложений его не использует; +- брокер — доставка заданий: реплики API к нему не обращаются, загрузка отвечает + 202, а задания ждут в PostgreSQL; +- relay — публикация заданий: без него задания ждут в PostgreSQL; +- worker — фоновая обработка: без него загрузки ждут в очереди. + +Предел незавершённых заданий (`queue-overload`) на готовность MUST NOT влиять: реплика, которая +отвечает на загрузку 429, обслуживает остальные запросы и остаётся готовой. + +Проверка MUST NOT обращаться к S3 и брокеру и MUST NOT требовать +идентификации. Перечень критичных и некритичных зависимостей с причинами +SHALL быть в `REPORT.md`. + +#### Scenario: Сервис запущен + +- **WHEN** запуск сервиса завершён, PostgreSQL доступен, и клиент + запрашивает `GET /health/ready` +- **THEN** ответ 200, тело `{"status": "ok"}` + +#### Scenario: Хранилище не готово + +- **WHEN** PostgreSQL недоступен +- **THEN** ответ 503 с `code` `unavailable` в формате ошибки не позже + таймаута проверки, а `GET /health/live` при этом отвечает 200 + +#### Scenario: Кэш недоступен + +- **WHEN** Valkey остановлен, а PostgreSQL доступен +- **THEN** `GET /health/ready` отвечает 200 + +#### Scenario: Хранилище объектов недоступно + +- **WHEN** сервер S3 остановлен или заморожен (`docker pause`), а + PostgreSQL доступен +- **THEN** `GET /health/ready` и `GET /health/live` отвечают 200 быстрее + секунды: проверка к S3 не обращается + +#### Scenario: Брокер и worker недоступны + +- **WHEN** брокер остановлен или заморожен (`docker pause`), relay и worker + остановлены, а PostgreSQL доступен +- **THEN** `GET /health/ready` и `GET /health/live` отвечают 200 быстрее + секунды: проверка к брокеру не обращается diff --git a/openspec/changes/track1-queue-overload/specs/job-outbox/spec.md b/openspec/changes/track1-queue-overload/specs/job-outbox/spec.md new file mode 100644 index 00000000..359bca10 --- /dev/null +++ b/openspec/changes/track1-queue-overload/specs/job-outbox/spec.md @@ -0,0 +1,58 @@ +## MODIFIED Requirements + +### Requirement: Приём не зависит от брокера + +Реплики API MUST NOT обращаться к брокеру и MUST NOT получать его пароль. Ответ 202 на +загрузку SHALL означать, что оригинал записан в staging, а вложение `queued` и его +задание зафиксированы в PostgreSQL одной транзакцией (`attachments`, «Порядок +записи»). Зафиксированное задание без времени подтверждения брокером — это намерение: +оно уже не может потеряться, его SHALL довести до брокера relay. + +Ответ на загрузку MUST NOT зависеть от состояния брокера и relay напрямую: их отказ, +заморозка и остановка не меняют ни кода ответа, ни срока, в который он приходит. Косвенно +они на него влияют только через принятую работу: пока задания не завершаются, их число +растёт, и у предела незавершённых заданий загрузка получает 429 (`queue-overload`, «Предел +незавершённых заданий»). + +#### Scenario: Загрузка при остановленном брокере + +- **WHEN** брокер остановлен, и участник загружает настоящий PNG +- **THEN** ответ 202 быстрее секунды, вложение `queued`, его задание без времени + подтверждения брокером +- **AND** после запуска брокера вложение становится `ready` без действий клиента + +#### Scenario: Загрузка при замороженном брокере + +- **WHEN** контейнер брокера заморожен (`docker pause`), и участник загружает настоящий + PNG +- **THEN** ответ 202 быстрее секунды, а после разморозки вложение становится `ready` + +#### Scenario: Ответ не ждёт публикации + +- **WHEN** relay остановлен, и участник загружает настоящий PNG +- **THEN** ответ 202, в очереди нет сообщения этого задания, а метаданные — 200 со + `status` `queued` + +### Requirement: Предел опубликованных заданий + +Relay MUST NOT публиковать новые задания, пока заданий `queued` с подтверждением брокера не +меньше `[relay] max_published_backlog`: остальные ждут в PostgreSQL. Значение 0 — без предела. +Так длина очереди брокера ограничена настройкой, а накопление видно в PostgreSQL. Срабатывание +предела памяти брокера SHALL сдерживать публикацию так же: relay получает отказ по сроку, задания +ждут в PostgreSQL, а загрузки по-прежнему отвечают 202, пока не достигнут предел незавершённых +заданий. + +Ограничение принятой работы на входе API — другая граница: `queue-overload`, «Предел незавершённых +заданий». Здесь ограничена только доля принятой работы, которую видит брокер. + +#### Scenario: Очередь ограничена пределом + +- **WHEN** worker остановлен, relay работает с пределом 2, и участник загружает 5 файлов +- **THEN** каждый ответ 202, в очереди 2 сообщения, у остальных заданий нет времени подтверждения, + а после запуска worker все вложения становятся `ready` + +#### Scenario: Брокер сдерживает публикацию + +- **WHEN** сработал предел памяти брокера, и участник загружает файл +- **THEN** ответ 202 быстрее секунды, у задания нет времени подтверждения, журнал relay называет + отказ брокера, а после снятия предела вложение становится `ready` diff --git a/openspec/changes/track1-queue-overload/specs/load-benchmark/spec.md b/openspec/changes/track1-queue-overload/specs/load-benchmark/spec.md new file mode 100644 index 00000000..810d515c --- /dev/null +++ b/openspec/changes/track1-queue-overload/specs/load-benchmark/spec.md @@ -0,0 +1,344 @@ +## MODIFIED Requirements + +### Requirement: Фиксированный стенд + +Стенд SHALL состоять из балансировщика (LB), реплик приложения, +PostgreSQL и Valkey. В профилях загрузок и сверки к ним SHALL +добавляться S3 с его bootstrap, а в профиле сверки — разовые проходы процесса +уборщика. В профиле очереди к ним SHALL добавляться S3 с его bootstrap, брокер, relay, worker и +уборщик: этот профиль меряет обработку. Остальные профили брокер, relay и worker не запускают: они +меряют реплику, а реплика к брокеру не обращается. Число реплик SHALL +задаваться методикой, по умолчанию одна. Приложение SHALL запускаться в контейнерах из образа, +собранного из текущего checkout тем же `Dockerfile`. Исключения — профиль +поочерёдной замены и варианты «до» профилей загрузок и сверки. Они берут +образ commit, заданного методикой: образ собирается тем же `Dockerfile` +из файлов этого commit без изменения рабочего дерева. Профиль замены +заканчивается на образе текущего checkout. LB SHALL +запускаться из того же образа и с той же конфигурацией, что у рабочего +стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у +рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL +получает те же настройки образа плюс модуль записи планов, выключенный +вне снятия плана. S3 SHALL запускаться из того же образа и с теми же +аргументами сервера, что у рабочего стенда, а bucket и пользователей +создаёт тот же bootstrap. В профиле сверки к аргументам S3 добавляется +порт метрик шлюза: он слушает только loopback контейнера S3, и по нему +оркестратор считает запросы к S3. Брокер SHALL запускаться из того же образа и с той же +конфигурацией, что у рабочего стенда; в профиле очереди к ней добавляются плагин метрик и +интервал статистики в секунду: порт метрик доступен только в сети стенда, на хост не публикуется. В сериях трека 1 предел соединений +PostgreSQL (`max_connections`) — параметр конфигурации серии, по +умолчанию 100, как у образа. Схема БД SHALL применяться миграциями до +наполнения. + +Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека +1 — во всех прогонах одной конфигурации: +- у каждой реплики приложения — лимит CPU и памяти без swap, заданный + методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по + конфигурации); +- у LB, PostgreSQL, Valkey, S3, брокера, relay, worker и уборщика — свои лимиты CPU и памяти + без swap, заданные методикой; в серии трека 1 они одинаковы во всех + конфигурациях; у уборщика в управляемом опыте профиля сверки — другой + лимит CPU, тоже заданный методикой; +- у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без + swap, заданный методикой; в остальных профилях генератор без лимита. + +Буфер приёма сокетов реплик приложения SHALL быть ограничен так же, как +у рабочего стенда (`load-balancing`, «Загрузки через балансировщик»). +Значение SHALL записываться в паспорт. + +Образ контейнера в паспорте SHALL называться тем значением, по которому образы +контейнеров можно сравнивать: меткой манифеста compose, а у контейнера без неё — идентификатором +образа. + +Healthcheck образа приложения SHALL быть отключён: готовность реплик +проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки +приложения и хранилищ SHALL браться из методики стенда, а не из `.env` +и `config.toml` рабочего стенда. Пароли хранилищ, пароль брокера и секреты S3 +SHALL генерироваться на прогон. Генератор нагрузки SHALL работать в той же +docker-сети и обращаться к приложению через LB по имени сервиса, минуя +проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит +готовыми все реплики. + +#### Scenario: Лимиты в паспорте + +- **WHEN** прогон завершён +- **THEN** паспорт стенда содержит число реплик и лимиты CPU и памяти + реплики приложения, LB, PostgreSQL и Valkey, прочитанные у запущенных + контейнеров, и они одинаковы для всех размеров + +#### Scenario: Лимиты конфигурации серии + +- **WHEN** серия трека 1 завершена +- **THEN** паспорт по каждой конфигурации содержит число реплик, лимиты + CPU и памяти каждого контейнера стенда и генератора и предел + соединений PostgreSQL, прочитанные у запущенных контейнеров, и они + одинаковы во всех повторах конфигурации + +#### Scenario: Нехватка памяти + +- **WHEN** процесс приложения превысил лимит памяти и был убит +- **THEN** прогон помечен как проваленный из-за OOM, а не записан как + обычный результат + +#### Scenario: Настройки рабочего стенда не влияют + +- **WHEN** `.env` и `config.toml` рабочего стенда изменены или + отсутствуют +- **THEN** стенд запускается с теми же настройками приложения и + хранилищ, а окружение приложения в паспорте то же + +#### Scenario: Схема до наполнения + +- **WHEN** начинается наполнение размера +- **THEN** миграции применены до последней ревизии, и приложение + отвечает готовностью + +#### Scenario: Одна реплика за балансировщиком + +- **WHEN** профиль лабы 2 (`full`, `quick`, `restore`, + `restore_quick`) запущен с одной репликой +- **THEN** все запросы генератора проходят через LB, прогон завершается + с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и + разделы, что раньше + +#### Scenario: Образ прежнего commit + +- **WHEN** запускается профиль поочерёдной замены +- **THEN** реплики стартуют на образе commit из методики, схема — на + его последней ревизии, рабочее дерево не меняется, а commit и образы + до и после записаны в паспорт + +#### Scenario: S3 в профиле загрузок + +- **WHEN** запускается профиль загрузок +- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами + и лимитами, bootstrap завершился успешно, а образ и лимиты S3 и + ограничение буфера приёма реплики записаны в паспорт + +#### Scenario: Брокер в профиле загрузок + +- **WHEN** запускается профиль загрузок +- **THEN** брокер, relay и worker стенда не запущены, а загрузки отвечают 202: задания ждут в + PostgreSQL + +#### Scenario: S3 и уборщик в профиле сверки + +- **WHEN** запускается профиль сверки +- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами + и портом метрик только на loopback своего контейнера, bootstrap + завершился успешно, а аргументы S3, образы и лимиты S3 и уборщика + записаны в паспорт + +#### Scenario: Конвейер в профиле очереди + +- **WHEN** запускается профиль очереди +- **THEN** S3, брокер, relay, worker и уборщик запущены из образов рабочего стенда с его лимитами без swap, у worker — политика перезапуска + рабочего стенда, порт метрик брокера не опубликован на хосте, а образы, лимиты, значения конкуренции и prefetch и окружение worker и relay + записаны в паспорт + +### Requirement: Профиль загрузок + +Команда `make bench_uploads` (метка `UPLOADS_LABEL`, по умолчанию +`baseline`) SHALL на свежем стенде мерить память реплики при +одновременных загрузках вложений. Команда `make bench_uploads_quick` — +то же короче, метка `quick-uploads-…`, в git не идёт. Результаты SHALL +сохраняться в `evidence/uploads/<метка>/`. Занятая метка SHALL давать +отказ до запуска стенда. + +Стенд — LB и одна реплика с лимитами рабочего стенда (1 CPU, 512 МБ без +swap), PostgreSQL, Valkey и S3 с лимитами рабочего стенда. Брокер, relay и +worker не запускаются: задания ждут в PostgreSQL. Поэтому у всех вариантов предел +незавершённых заданий выключен (`queue-overload`): иначе он отклонял бы загрузки, и профиль мерил бы не память +приёма, а этот предел. + +Варианты кода: +- «до» — образ commit из методики; у лабы 5 это commit переноса лабы 4, в + нём места загрузки уже есть; +- «без лимита» — образ текущего checkout, мест загрузки больше, чем + клиентов, очереди нет; +- «с лимитом» — образ текущего checkout с параметрами загрузок по + умолчанию. + +Успешная загрузка — 202, а у варианта с образом commit до перехода на 202 — +201. Код успеха варианта SHALL быть в паспорте. Столбец успешных загрузок считает +код успеха варианта. + +Тела — настоящие PNG около 1 MiB и около 10 MiB, не больше лимита +контракта. Их строит оркестратор, детерминированно от зерна методики. + +Прогон — вариант × размер × число одновременных клиентов (1, 10, 20 и +40) × повтор. Повторов в полном профиле три. Каждый прогон SHALL идти на +новом контейнере реплики и новом volume S3. Клиенты загружают без пауз +окно, заданное методикой. На 429 клиент ждёт `Retry-After`, на прочие +ошибки — секунду. + +Для каждого прогона SHALL сохраняться: +- пик памяти реплики за окно — пик cgroup, сброшенный в начале окна, — + и память перед окном; +- наибольшие анонимная память и память буферов сокетов реплики; +- было ли завершение реплики из-за памяти; +- ответы по кодам, ошибка соединения — отдельным кодом; +- успешных загрузок в секунду, p50, p95 и p99 успешных; +- пик памяти S3 (в том числе анонимной) и LB. + +Прогон с завершением реплики из-за памяти SHALL помечаться `oom` и +записываться как результат варианта, а не как сбой команды. Следующий +прогон идёт на новой реплике. + +Граница чёрного ящика: генератор обращается к приложению только по HTTP +через LB, оркестратор управляет стендом через docker CLI. Сверх этого он +читает счётчики памяти cgroup контейнеров и пересоздаёт volume S3 с +bootstrap между прогонами. К bucket и объектам он не обращается. + +В паспорте метки SHALL быть: +- лимиты и образы, в том числе commit варианта «до»; +- окружение приложения каждого варианта без секретов; +- размеры и SHA-256 тел; +- версия ядра ВМ; +- ограничение буфера приёма сокетов реплики; +- состояние хоста. + +#### Scenario: Полный профиль + +- **WHEN** выполнен `make bench_uploads` +- **THEN** в `evidence/uploads/<метка>/` есть паспорт, таблица прогонов + (три варианта × два размера × четыре уровня × три повтора), сводка по + ячейкам с медианой и разбросом повторов и сырые итоги генератора, код + выхода 0 + +#### Scenario: Быстрый профиль + +- **WHEN** выполнен `make bench_uploads_quick` +- **THEN** за несколько минут проходят варианты «без лимита» и «с + лимитом» на 10 MiB при 1, 10 и 40 клиентах, по одному повтору, код + выхода 0, каталог метки в git не попадает, а успешные загрузки — 202 + +#### Scenario: Реплика убита из-за памяти + +- **WHEN** в прогоне реплику завершило ядро из-за памяти +- **THEN** прогон помечен `oom`, в таблице есть ответы по кодам до и + после завершения, следующий прогон идёт на новой реплике, а команда + не прерывается + +#### Scenario: Пик окна без памяти старта + +- **WHEN** реплика при старте заняла больше памяти, чем в окне прогона +- **THEN** пик прогона отражает только окно, а не старт процесса + +#### Scenario: Предел заданий не участвует + +- **WHEN** выполнен профиль загрузок, задания не обрабатываются, и их больше значения предела по умолчанию +- **THEN** ни один ответ 429 не вызван пределом незавершённых заданий: все 429 — от мест загрузки, а в паспорте вариантов предел равен 0 + +## ADDED Requirements + +### Requirement: Профиль очереди + +Команда `make bench_queue` (метка `QUEUE_LABEL`, по умолчанию `baseline`) SHALL мерить конвейер обработки вложений под перегрузкой. +Команда `make bench_queue_quick` — то же на части ячеек и с короткими окнами, метка `quick-queue-…`, в git не идёт. Результаты SHALL +сохраняться в `evidence/queue/<метка>/`. Занятая метка SHALL давать отказ до запуска стенда, кроме продолжения прерванной метки на том же +commit (`RESUME=1`), как у серий трека 1. + +Стенд — требование «Фиксированный стенд»: LB, две реплики, PostgreSQL, Valkey, S3, брокер, relay, worker и уборщик с лимитами рабочего стенда (worker +— 1 CPU и 1 ГБ без swap). Worker перезапускается по той же политике, что на рабочем стенде: настройка, которая не помещается в лимит памяти, может стоить завершения его +процесса 1 ядром, и ячейка показывает это, а не простаивает. Каждая ячейка — свежий стенд на новых volume. + +**Настройки** (конкуренция, prefetch): 1 и 1; 2 и 2 — значения по умолчанию; 4 и 4; 2 и 256 — большой prefetch. + +**Классы изображений** — настоящие файлы, детерминированно от зерна методики, ни один не тривиален для декодера, размер и SHA-256 — в паспорте: +- `s` — JPEG около 1,9 млн пикселей и 0,5 MiB; +- `m` — PNG из шума около 3,5 млн пикселей на границе байтов контракта; +- `lj` — JPEG на границе пикселей контракта, около 9 MiB; +- `lp` — PNG с альфа-каналом на границе пикселей и байтов контракта. + +**Ячейки матрицы** — настройка × класс × повтор, повторов три, круги с перестановкой от зерна, повтор одной ячейки не идёт подряд. План — в паспорте до первой +ячейки. Большой prefetch — на `s` и `lp`, конкуренция 1 — на `m` и `lp`, остальные — на всех классах. + +**Нагрузка ячейки** — открытая модель загрузок через LB, интенсивность задана методикой на класс и одинакова для всех настроек: окно ниже потолка worker; окно перегрузки +выше потолка; спад до нуля, пока незавершённых заданий нет; снова окно ниже потолка. Ответ не повторяется: 429 считается отказом. Рядом всё время идёт контрольный поток: +отправка текста, чтение истории и скачивание готовых вложений с постоянной интенсивностью. + +**Блоки сверх матрицы**, по три повтора, класс `s`, настройка по умолчанию, если не сказано иное: +- предел: предел незавершённых заданий по умолчанию и выключенный, перегрузка, которая его превышает; +- приём: класс `m`, интенсивность выше того, что принимают реплики и S3, окно перегрузки такой длины, что после мест загрузки срабатывает и предел незавершённых заданий; +- второй worker: в конце окна перегрузки запускается ещё один worker с теми же настройками, настройки 2 и 2 и 2 и 256; +- рестарты: посреди перегрузки worker завершён сигналом KILL и снова запущен; брокер перезапущен с сохранённым volume. + +Для каждой ячейки SHALL сохраняться: +- throughput — готовых вложений в секунду в окне перегрузки и в окне восстановления; +- очередь посекундно и её пики, в трёх местах: неопубликованные задания (outbox) и ждущие срока; очередь брокера — готовые и неподтверждённые сообщения, опубликованные и не + взятые задания; взятые worker — `processing` и выданные, но не взятые; +- возраст старейшего незавершённого задания, пик и посекундно; +- время от ответа 202 до `ready` по метаданным: p50, p95 и p99 по окнам прихода; +- время восстановления: от конца окна перегрузки до нуля незавершённых заданий; +- RSS: пик процесса worker, пик процесса обработки по его отчёту (p50 и наибольший), `memory.peak` и наибольшая анонимная память контейнера, завершения ядром из-за памяти, перезапуски контейнера worker; у перезапущенного контейнера — наибольшее и сумма по его жизням; +- CPU и троттлинг worker, S3, PostgreSQL, реплик, relay, брокера и уборщика по окнам; +- память брокера и наличие сработавшего предела памяти; +- ответы на загрузку по кодам, недосланные итерации, `failed` по кодам и причинам, попытки сверх одной, пропущенные сообщения по причинам; +- контрольный поток: число ответов, ошибки, p50, p95 и p99 по окнам. + +Граница чёрного ящика: генератор обращается к приложению только по HTTP через LB, истина о готовности — метаданные `GET /attachments/{id}`, запрошенные у каждого принятого +вложения после разбора очереди. Сверх этого оркестратор читает: счётчики cgroup; журналы worker, relay, реплик и уборщика; состояние заданий в PostgreSQL стенда — только для измерения; метрики очереди +брокера. Приложение он не импортирует. + +Достоверность: +- принятые вложения SHALL совпасть с вложениями стенда: потерянное или зависшее — пометка ячейки, у ячейки блока рестартов и матрицы — и ненулевой код команды в конце метки; +- второго набора вариантов и второго задания у вложения SHALL не быть, иначе так же; +- выборка оригиналов и вариантов SHALL скачиваться с SHA-256 из метаданных; +- k6 с недосланными итерациями, выгрузка хоста в swap и упавшее хранилище — пометки ячейки; +- конкуренция и prefetch в записи о старте worker SHALL совпасть с ячейкой, иначе отказ. + +В паспорте метки SHALL быть: лимиты и образы; значения конкуренции, prefetch и окружение worker и relay по ячейкам без секретов; классы и их параметры; интенсивности и окна; контрольный поток; план; версия ядра ВМ; +состояние хоста; посторонние контейнеры. + +Сводка SHALL давать по каждой ячейке медиану и разброс повторов, таблицы блоков, вывод по каждой гипотезе (требование «Очередь под перегрузкой в отчёте»), рекомендуемую настройку по её правилу и графики. + +#### Scenario: Полный профиль очереди + +- **WHEN** выполнен `make bench_queue` +- **THEN** в `evidence/queue/<метка>/` есть паспорт, таблица ячеек, посекундная шкала, сводка с выводами по гипотезам и графики, код выхода 0 + +#### Scenario: Быстрый профиль очереди + +- **WHEN** выполнен `make bench_queue_quick` +- **THEN** за несколько минут проходят ячейки перегрузки на двух классах, большой конкуренции на классе с наибольшей памятью, предела, второго worker и рестарта worker, код выхода 0, каталог метки в git не попадает + +#### Scenario: Вложение потеряно + +- **WHEN** на вложение ответили 202, а после разбора очереди метаданных нет или они не `ready` и не `failed` +- **THEN** ячейка помечена, число потерянных и зависших названо в сводке, а код команды в конце метки ненулевой + +#### Scenario: Завершение ядром из-за памяти + +- **WHEN** ядро завершает процесс обработки или процесс 1 worker по памяти контейнера +- **THEN** ячейка помечена `oom`, контейнер worker перезапускается сам, если завершён его процесс 1, число завершений, перезапусков и повторов записано как результат настройки, а не как сбой + команды, а принятые вложения дошли до `ready` или названного `failed` + +#### Scenario: Прерванная метка + +- **WHEN** длинный прогон прерван, и он запущен снова с `RESUME=1` на том же commit +- **THEN** готовые ячейки не снимаются заново, а незавершённая снимается с новой попыткой + +### Requirement: Очередь под перегрузкой в отчёте + +`REPORT.md` SHALL содержать по профилю очереди: +- гипотезы с числовыми порогами «подтверждено / нет», записанные и зафиксированные commit раньше меток замера; +- методику: стенд, лимиты, настройки, классы, интенсивности и окна, контрольный поток, повторы и как читается шум; +- определения: что считается очередью в трёх местах, throughput, время до `ready`, восстановление; +- таблицы результатов метки: throughput, очередь, p50, p95 и p99 времени до `ready`, RSS, `memory.peak`, CPU и троттлинг — по настройкам и классам; блоки предела, второго worker и рестартов; +- backpressure и ограничение принятой работы: где работа перестаёт приниматься и ускоряться и что видит клиент; +- восстановление: время, отсутствие потерянных, зависших и дублей эффекта, контрольный поток; +- вывод по каждой гипотезе, компромисс latency и ресурсов как вывод из данных, рекомендуемую настройку с условиями и решение о значениях по умолчанию с обоснованием; +- обоснование предела незавершённых заданий по измеренному потолку; +- ограничения: один хост, ВМ Docker Desktop, генератор на том же хосте, одна нода S3 на свежем volume, число worker, лимиты контейнеров, синтетические изображения. + +Числа в отчёт SHALL переноситься из сводки метки, а не пересчитываться вручную. Метка SHALL быть снята с закоммиченного кода, commit — в шапке. + +#### Scenario: Гипотезы очереди до прогонов + +- **WHEN** проверяющий смотрит историю `REPORT.md` и каталога метки +- **THEN** commit с гипотезами раньше commit с результатами метки + +#### Scenario: Выводы по метке очереди + +- **WHEN** проверяющий открывает раздел очереди в `REPORT.md` +- **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки, числа совпадают со сводкой, а рекомендуемая настройка следует из правила и таблиц diff --git a/openspec/changes/track1-queue-overload/specs/message-broker/spec.md b/openspec/changes/track1-queue-overload/specs/message-broker/spec.md new file mode 100644 index 00000000..c08fa34d --- /dev/null +++ b/openspec/changes/track1-queue-overload/specs/message-broker/spec.md @@ -0,0 +1,42 @@ +## MODIFIED Requirements + +### Requirement: Подтверждение публикации + +Relay SHALL считать сообщение принятым только после подтверждения брокера +(publisher confirm). Сообщение, которое брокеру некуда направить, отказ брокера, +обрыв соединения и истечение `[broker] publish_timeout_seconds` SHALL быть +ошибкой публикации: время подтверждения у задания не записывается, намерение остаётся в +PostgreSQL, и следующий проход публикует его снова. Исход публикации по сроку неизвестен, +поэтому сообщение может дойти дважды (`job-outbox`, «Relay публикует намерения»). +Отдельный вызов публикации MUST NOT зависать дольше этого срока. + +Брокер не критичен для обязательного пути и для приёма файлов: без него SHALL работать +загрузка (202, пока не достигнут предел незавершённых заданий — `queue-overload`), отправка +текста, история, метаданные, скачивание готового вложения и `/health/ready` (`health`, +«Readiness»). + +После возврата брокера публикация SHALL проходить без перезапуска процесса. + +#### Scenario: Брокер остановлен при загрузке + +- **WHEN** брокер остановлен, и участник загружает файл, отправляет текст, + читает метаданные готового вложения и скачивает его +- **THEN** загрузка — 202 быстрее секунды, отправка — 201, метаданные и скачивание — + 200, а новое вложение видно по API со `status` `queued` + +#### Scenario: Брокер завис + +- **WHEN** контейнер брокера заморожен (`docker pause`), и участник загружает файл +- **THEN** ответ 202 быстрее секунды, а после разморозки вложение становится `ready` с одним + набором вариантов, даже если сообщение, дошедшее после разморозки, опубликовано ещё раз + +#### Scenario: Брокер вернулся + +- **WHEN** брокер снова запущен, а relay и worker не перезапускались +- **THEN** вложение, принятое без брокера, и следующая загрузка становятся `ready` + +#### Scenario: Очередь удалена + +- **WHEN** worker остановлен, очередь заданий удалена мимо приложения, участник + дважды загружает файл, а затем worker запущен +- **THEN** обе загрузки — 202, очередь объявлена заново, и оба вложения становятся `ready` diff --git a/openspec/changes/track1-queue-overload/specs/queue-overload/spec.md b/openspec/changes/track1-queue-overload/specs/queue-overload/spec.md new file mode 100644 index 00000000..e88cd1fc --- /dev/null +++ b/openspec/changes/track1-queue-overload/specs/queue-overload/spec.md @@ -0,0 +1,157 @@ +## Purpose + +Поведение конвейера вложений под перегрузкой с лабы 5, трек 1: предел незавершённых заданий на входе API и что видит +клиент у предела, где и как сдерживается работа, что происходит с остальным API, восстановление после перегрузки и +рестарты worker и брокера под ней. Как это меряется — `load-benchmark`, «Профиль очереди». + +## ADDED Requirements + +### Requirement: Предел незавершённых заданий + +Незавершённое задание — задание в состоянии `queued` или `processing`, в том числе ожидающее следующей попытки или +неопубликованное. Загрузка, прошедшая проверки 1–5 (`attachments`, «Порядок проверок загрузки»), SHALL получать ответ 429 +`rate_limited` в формате ошибки с заголовком `Retry-After` — положительным целым числом секунд, если незавершённых заданий +стенда не меньше `[uploads] max_unfinished_jobs` (`service-configuration`, «Параметры загрузок»). Значение 0 — предела нет. + +Такая загрузка MUST NOT читать тело, занимать место загрузки и ждать его, MUST NOT оставлять ни метаданных, ни объекта. Ответ +SHALL приходить сразу: без ожидания освобождения работы. Клиент повторяет загрузку сам, после `Retry-After`: это новая загрузка, +она ничего не дублирует, потому что отклонённая ничего не сохранила. Балансировщик такой ответ не повторяет (`load-balancing`). + +Предел SHALL быть один на стенд: его считают по PostgreSQL все реплики, память процесса в подсчёте не участвует. Предел мягкий: +загрузки, которые уже прошли проверку и ещё не зафиксировали задание, могут превысить его, но не больше чем на число загрузок в +полёте: реплик × (`[uploads] max_concurrent` + `[uploads] max_waiting`). + +Проверка MUST NOT добавлять загрузке шаг с PostgreSQL сверх прежних: цепочка сроков пути загрузки в балансировщике не меняется. Её +цена MUST NOT расти с числом завершённых заданий и с превышением предела. + +Журнал реплики SHALL называть отказ: причина «предел заданий», предел и найденное число, без `filename`. + +#### Scenario: Предел достигнут + +- **WHEN** worker остановлен, предел равен K, и участник последовательно загружает настоящие PNG +- **THEN** первые загрузки до K незавершённых заданий получают 202, следующая — 429 `rate_limited` с `Retry-After` не меньше 1, + с непустыми `X-Request-Id` и `X-Instance-Id`, быстрее секунды, и нового вложения нет ни в PostgreSQL, ни в bucket + +#### Scenario: Загрузки снова принимаются + +- **WHEN** предел достигнут, worker запущен, и незавершённых заданий стало меньше предела +- **THEN** следующая загрузка получает 202, а все принятые раньше вложения становятся `ready` + +#### Scenario: Завершённые задания не считаются + +- **WHEN** незавершённых заданий нет, а вложений `ready` и `failed` больше предела +- **THEN** загрузка получает 202 + +#### Scenario: Ожидание следующей попытки считается + +- **WHEN** задание ждёт следующую попытку, её срок ещё не наступил, а незавершённых заданий вместе с ним столько же, сколько предел +- **THEN** загрузка получает 429 + +#### Scenario: Порядок проверок у предела + +- **WHEN** предел достигнут, и посторонний загружает файл в чат, участник загружает 30 MiB с `Content-Length` 31 457 280, а затем PNG с + `Content-Type: text/plain` +- **THEN** ответы 404, 413 и 415, а не 429 + +#### Scenario: Остальной API у предела + +- **WHEN** предел достигнут +- **THEN** отправка текста — 201, история — 200, метаданные и скачивание готового вложения — 200, сообщение со ссылкой на принятое + вложение — 201, а `/health/ready` — 200 + +#### Scenario: Предел при остановленных брокере и relay + +- **WHEN** брокер и relay остановлены, и участник загружает файлы до предела +- **THEN** загрузки до предела получают 202 быстрее секунды, следующая — 429, а после запуска брокера, relay и worker все принятые + вложения становятся `ready` + +#### Scenario: Превышение ограничено + +- **WHEN** незавершённых заданий нет, предел равен K, и участники одновременно загружают заметно больше K файлов +- **THEN** каждый ответ — 202 или 429, принятых не меньше K и не больше K плюс числа загрузок в полёте, и каждое принятое вложение + становится `ready` + +#### Scenario: Предел выключен + +- **WHEN** сервис запущен с `UPLOADS__MAX_UNFINISHED_JOBS=0`, worker остановлен, и участник загружает файлы +- **THEN** каждый ответ 202, сколько бы заданий ни ждало + +### Requirement: Сдерживание работы по уровням + +Работа под перегрузкой SHALL сдерживаться последовательно, и на каждом уровне SHALL быть видно, сколько её там: +- приём: места загрузки реплики и предел незавершённых заданий — клиент видит 429; +- outbox: задания, которые relay ещё не опубликовал, — в PostgreSQL; +- очередь брокера: не больше `[relay] max_published_backlog` опубликованных и не взятых заданий, остальные ждут в outbox; +- worker: брокер выдаёт не больше `[worker] prefetch` неподтверждённых сообщений, а взято в работу не больше `[worker] concurrency` заданий; +- процесс обработки: лимиты памяти и CPU на задание, лимит памяти контейнера worker. + +Сдерживание за входом клиент MUST NOT видеть иначе, чем дольше не меняющееся `queued`: ни одного кода ошибки оно не даёт. + +#### Scenario: Работа копится там, где положено + +- **WHEN** загрузки идут быстрее потолка worker, и предел незавершённых заданий не достигнут +- **THEN** в каждый момент заданий `processing` не больше `concurrency`, неподтверждённых сообщений не больше `prefetch`, заданий в очереди + брокера не больше предела опубликованных, а незавершённых заданий столько же, сколько принято и не завершено + +#### Scenario: Приём упирается в места загрузки + +- **WHEN** загрузки на границе байтов контракта идут быстрее, чем реплики и S3 успевают их принимать, а предел незавершённых заданий не достигнут +- **THEN** лишние загрузки получают 429 от мест загрузки, принятые — 202, ответов 5xx нет, а принято не меньше, чем при интенсивности ниже этой границы + +#### Scenario: Сначала места, затем предел + +- **WHEN** загрузки на границе байтов контракта идут быстрее, чем реплики и S3 успевают их принимать, столько времени, что незавершённых заданий набирается до предела +- **THEN** сначала лишние загрузки получают 429 от мест загрузки, затем — 429 от предела незавершённых заданий, журнал реплик называет обе причины, ответов 5xx нет, а незавершённых заданий не больше предела плюс загрузок в полёте + +### Requirement: API под перегрузкой + +Пока работа копится, остальной API SHALL обслуживаться: отправка сообщений, чтение истории, метаданные и скачивание готовых вложений +MUST NOT получать ответы 5xx из-за перегрузки очереди, а реплики API MUST NOT выводиться из балансировщика. Загрузка SHALL отвечать 202 или +429, а 5xx на ней — только при отказе S3 или PostgreSQL. + +#### Scenario: Контрольный поток под перегрузкой + +- **WHEN** загрузки идут быстрее потолка worker, но не быстрее, чем принимают реплики и S3, а рядом идёт постоянный поток отправки текста, чтения + истории и скачивания готовых вложений (`load-benchmark`, «Профиль очереди») +- **THEN** ответов 5xx контрольного потока нет, его p95 при отправке и чтении истории не больше 200 мс, при скачивании — не больше 500 мс, а все + реплики остаются в балансировщике + +### Requirement: Восстановление после перегрузки + +Восстановление — состояние после спада нагрузки, в котором незавершённых заданий нет, очередь брокера пуста, а время до `ready` новой работы +вернулось к значению до перегрузки. После снятия нагрузки конвейер SHALL приходить в него сам, без действий оператора. Каждое принятое вложение +(ответ 202) SHALL дойти до `ready` или названного `failed`: потерянных и зависших MUST NOT быть. Эффект MUST NOT дублироваться: на вложение одно +задание и по одному варианту каждого имени. Время восстановления SHALL быть измерено и не больше времени обработки накопленного при +потолке worker с запасом, заданным гипотезой (`load-benchmark`, «Очередь под перегрузкой в отчёте»). + +#### Scenario: Бэклог уходит за измеренное время + +- **WHEN** загрузки шли быстрее потолка worker, и нагрузка снята +- **THEN** незавершённых заданий становится ноль без действий оператора, очередь брокера пуста, время восстановления записано, а скорость обработки в окне + восстановления не ниже скорости в окне перегрузки с запасом разброса + +#### Scenario: Никого не теряем + +- **WHEN** нагрузка снята, и проверяющий по HTTP запрашивает метаданные каждого вложения, на которое ответили 202 +- **THEN** каждое `ready` с тремя вариантами или `failed` с `error_code`, зависших нет, а выборочные оригинал и варианты скачиваются с SHA-256 из метаданных + +#### Scenario: Время до готовности вернулось + +- **WHEN** очередь разобрана, и загрузки снова идут ниже потолка worker +- **THEN** p95 времени до `ready` новых вложений не больше чем в полтора раза выше p95 до перегрузки + +### Requirement: Рестарты под перегрузкой + +Остановка процессов конвейера под перегрузкой MUST NOT терять принятую работу и MUST NOT создавать второй набор вариантов. + +#### Scenario: Worker убит под перегрузкой + +- **WHEN** загрузки идут быстрее потолка worker, worker завершён сигналом KILL и снова запущен +- **THEN** каждое принятое вложение становится `ready`, новых попыток сверх взятых к моменту KILL не появилось, одна попытка на задание у остальных, а + взятые заканчиваются не позже срока аренды с запасом + +#### Scenario: Брокер перезапущен под перегрузкой + +- **WHEN** загрузки идут быстрее потолка worker, и брокер перезапущен с сохранённым volume +- **THEN** загрузки отвечают 202 и во время рестарта, каждое принятое вложение становится `ready`, сообщения в очереди после разбора нет, а счётчики + перезапусков relay и worker не изменились diff --git a/openspec/changes/track1-queue-overload/specs/service-configuration/spec.md b/openspec/changes/track1-queue-overload/specs/service-configuration/spec.md new file mode 100644 index 00000000..d2f7e2c8 --- /dev/null +++ b/openspec/changes/track1-queue-overload/specs/service-configuration/spec.md @@ -0,0 +1,54 @@ +## MODIFIED Requirements + +### Requirement: Параметры загрузок + +Ограничения загрузок вложений процесса API (capability `attachments`, +«Одновременные загрузки реплики», «Срок передачи тела»; capability `queue-overload`, «Предел +незавершённых заданий») SHALL задаваться в секции `[uploads]`: +- `max_concurrent` — сколько загрузок процесс обрабатывает одновременно, + по умолчанию 4; +- `max_waiting` — сколько загрузок может ждать места, по умолчанию 16; + 0 — без ожидания, загрузка без места сразу получает 429; +- `wait_timeout_seconds` — сколько секунд загрузка ждёт места, по + умолчанию 5; +- `body_timeout_seconds` — за сколько секунд после того, как загрузка + заняла место, должно прийти её тело, по умолчанию 30; +- `max_unfinished_jobs` — при каком числе незавершённых заданий стенда загрузка получает 429, + по умолчанию 250; 0 — без предела. + +`max_concurrent` SHALL быть целым не меньше 1, `max_waiting` и `max_unfinished_jobs` — целыми не +меньше 0, сроки — положительными числами. Иначе сервис MUST NOT +стартовать (требование «Некорректное значение останавливает запуск»). +Значения SHALL одинаково действовать в консоли и в docker. Разовая +подмена SHALL работать через окружение `UPLOADS__*` без правки файлов. +Запись журнала о старте API SHALL называть все пять значений. + +Значения по умолчанию и их обоснование SHALL быть описаны в `REPORT.md`: +- бюджет памяти реплики: интерпретатор, хэши паролей и места загрузок в + лимите контейнера; +- сроки пути загрузки в балансировщике (`load-balancing`, «Загрузки + через балансировщик»); +- предел незавершённых заданий: измеренный потолок worker на худшем классе изображений, срок + ожидания и объём staging при заполненном пределе. + +#### Scenario: Параметры загрузок по умолчанию + +- **WHEN** сервис запущен без секции `[uploads]` и без переменных + `UPLOADS__*` +- **THEN** запись журнала о старте называет 4 места, 16 ожидающих, + ожидание 5 с, срок тела 30 с и предел 250 незавершённых заданий + +#### Scenario: Подмена параметров загрузок окружением + +- **WHEN** сервис запущен с `UPLOADS__MAX_CONCURRENT=1` и + `UPLOADS__MAX_WAITING=0`, а файлы не менялись +- **THEN** вторая одновременная загрузка, пока первая не закончилась, + сразу получает 429 + +#### Scenario: Неверный параметр загрузок + +- **WHEN** сервис запускается с `UPLOADS__MAX_CONCURRENT=0`, + `UPLOADS__MAX_WAITING=-1`, `UPLOADS__MAX_UNFINISHED_JOBS=-1` или + `UPLOADS__BODY_TIMEOUT_SECONDS=abc` +- **THEN** сервис не стартует, в журнале — ошибка проверки настроек с + именем поля diff --git a/openspec/changes/track1-queue-overload/specs/student-tests/spec.md b/openspec/changes/track1-queue-overload/specs/student-tests/spec.md new file mode 100644 index 00000000..765670d0 --- /dev/null +++ b/openspec/changes/track1-queue-overload/specs/student-tests/spec.md @@ -0,0 +1,172 @@ +## MODIFIED Requirements + +### Requirement: Покрытие сценариев основных спеков + +Для каждого сценария основных спеков `api-conventions`, +`identification`, `sessions`, `users`, `chats`, `messages`, +`pagination`, `data-storage`, `chat-cache`, `health`, `idempotency`, с +лабы 4 `attachments` и `storage-consistency` и с лабы 5 +`attachment-processing`, `message-broker`, `job-outbox` и `queue-overload`, который воспроизводится +по HTTP против работающего сервера, в том числе на стенде отказов, +SHALL быть тест. Из имени или описания теста SHALL быть понятно, какой +capability и сценарий он проверяет. Сценарий, который проверяет тест +отказа, SHALL считаться покрытым, хотя `make student_test` этот тест +не выполняет; итог сверки SHALL называть, сколько сценариев покрыто +проверками отказов. Сценарии, которые по HTTP не воспроизвести, SHALL +быть перечислены с причиной и способом проверки. + +#### Scenario: Сверка покрытия + +- **WHEN** проверяющий берёт любой сценарий перечисленных спеков +- **THEN** находится проверяющий его тест либо запись в списке + исключений с причиной + +#### Scenario: Сценарий отказа в сверке + +- **WHEN** выполняется `make student_test` +- **THEN** сверка считает сценарии проверок отказов покрытыми, не + требует для них исключений и печатает их число + +### Requirement: Проверки отказов на отдельном стенде + +Сценарии отказов SHALL проверяться автоматически одной командой +`make failure_checks`: +- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при + запросе с токеном»; +- `data-storage`: «Сбой при добавлении участников», «БД остановлена», + «БД вернулась», «Соединения исчерпаны»; +- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище + объектов недоступно», «Брокер и worker недоступны»; +- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся», + «Очистка кэша»; +- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке», + «Ключ после срока», «Повтор после failed вложения»; +- `api-conventions`: «Лимит одновременных загрузок»; +- `messages`: «Вложение в обработке», «Вложение стало failed после отправки»; +- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего + не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не + видна», «Сбой записи метаданных», «Фиксация задания не удалась», «Фиксация ready не + удалась», «Исход фиксации неизвестен», «Брокер не подтвердил задание», «Обрыв + передачи тела», «Отказ раньше + очереди», «Все места заняты», «Очередь ожидания полна», «Ожидание места», «Место + освобождается», «Медленный клиент», «Медленная передача в срок», «Потерянный + оригинал», «Загрузка после простоя S3», «Скачивание до готовности», «Отсутствующий + вариант»; +- `attachment-processing`: все сценарии, которым нужны остановка worker, relay, брокера или + S3, сбой внутри обработки, запуск worker с другими параметрами или команда replay; +- `message-broker`: все сценарии, которые не названы исключениями сверки покрытия; +- `job-outbox`: все сценарии; +- `storage-consistency`: все сценарии; +- `queue-overload`: все сценарии требования «Предел незавершённых заданий». + +Команда SHALL: +- собрать образ из рабочего дерева; +- поднять отдельный стенд со своими PostgreSQL, Valkey, S3 и брокером, применить + миграции и bootstrap S3; +- запустить пять API. У первых четырёх предел незавершённых заданий выключен: проверки копят + задания при остановленном worker и под нагрузкой, и предел отклонял бы загрузки чужих проверок: + - с настройками по умолчанию; + - «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом + из одного соединения; + - «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в + очереди, коротким сроком ожидания места и коротким сроком тела; + - «с коротким сроком S3» — со сроком вызова S3 в одну секунду: простой + дольше срока вызова в проверке длится полторы секунды, а не шесть; + - «узкий по заданиям» — с малым пределом незавершённых заданий. + + Значения «узких» API и API с коротким сроком S3 SHALL передаваться + проверкам, и проверки SHALL сверять с ними стенд; +- запустить уборщика с коротким grace, интервалом и сроком хранения staging, сравнимыми со + временем теста, без плановой сверки, и передать их значения + проверкам. Grace при этом SHALL проходить проверку границы живой + загрузки (`service-configuration`, «Параметры уборщика»). Сверку + проверки запускают сами, и плановая сверка не меняет стенд у них за + спиной; +- запустить relay с короткими паузой и порогом потерянного сообщения и передать их значения + проверкам; +- запустить worker с короткими сроками и малым числом попыток, сравнимыми со + временем теста, и передать их значения проверкам; +- выполнить проверки отказов; +- удалить стенд вместе с его данными при любом исходе. + +Hook стенда отказов SHALL уметь: +- сообщить вложения стенда в PostgreSQL с их статусами, `id` последнего + вложения в статусе «загружается» и `id` вложений с потерянным + оригиналом; +- сообщить задание вложения: идентификатор, состояние, число начатых попыток, число + попыток до последнего replay, причину последней ошибки, время следующей попытки, срок + аренды и время подтверждения брокером, а также записи аудита replay; +- сообщить число незавершённых заданий стенда; +- сообщить, у каких вложений есть объект в конечном префиксе и в staging bucket + стенда, и сколько у вложения объектов вариантов, — по самим объектам, а не по + каталогам хранилища, и SHA-256 объекта по ключу; +- внедрить отказ PostgreSQL: + - при записи метаданных загрузки с заданным `filename`; + - при фиксации её `queued`, и задержать такую фиксацию; + - при фиксации `ready` с заданным `filename`, и задержать такую фиксацию: оператор + перевода и сам COMMIT; + - при пометке потерянного оригинала такого вложения; + - задержать запись времени подтверждения брокером у задания вложения с заданным + `filename`; +- дождаться, пока COMMIT задержан в PostgreSQL; +- убить и снова запустить обычный API стенда; +- остановить, убить, заморозить и запустить брокер, relay и worker стенда, заморозить процесс 1 + контейнера worker сигналом и убить контейнер, запустить отдельный worker или relay с заданными + значениями `WORKER__*` и `RELAY__*` и убрать его; +- сообщить состояние очереди: сообщений, готовых, неподтверждённых, потребителей, + устойчива ли она; +- прочитать сообщение из очереди без подтверждения, добавить в очередь сообщение + и удалить очередь; включить и снять предел памяти брокера; +- убить процесс обработки в контейнере worker и сообщить имена переменных его окружения; +- внести расхождения хранилищ: + - записать объект в bucket стенда мимо API и удалить объект мимо API — + только под префиксами вложений и staging базы стенда; + - удалить метаданные вложения, изменить в них размер, SHA-256, ключ staging и время + следующей попытки, сдвинуть их время в прошлое и вернуть вложение в статус «загружается» без + задания; + - удалить метаданные варианта; +- выполнить разовую сверку — без изменений или с `--apply`, с заданным + пределом изменений, стратегией обхода, глубиной, пределом скорости и сроком хранения + staging — и вернуть её записи и код выхода; +- выполнить команду replay с заданным выбором и вернуть её записи и код выхода; +- остановить и запустить уборщика стенда, а также запустить отдельного + уборщика с коротким интервалом плановой сверки на заданное время и + вернуть его журнал. + +Других сведений о хранилищах проверки вложений не получают. Объекты без +метаданных проверка находит сравнением двух списков: вложений и +объектов. Ключи доступа S3 и пароль брокера hook не получает и не печатает: объект +мимо API и сообщение в очередь записывает процесс в контейнере стенда своими ключами. + +Порты PostgreSQL, Valkey, S3 и брокера этого стенда MUST NOT публиковаться на +хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш, +хранилище объектов, брокер и контейнеры MUST NOT затрагиваться. Код выхода +SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка. +Параллельный запуск двух прогонов не поддерживается: уборка хвоста в +начале второго удаляет стенд первого. + +Точек внедрения сбоя в коде приложения MUST NOT быть: сбои внедряются снаружи, средствами стенда. + +#### Scenario: Успешный прогон + +- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks` +- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и + volumes стенда отказов после команды нет, а у контейнеров рабочего + стенда прежнее время старта, и рабочий API отвечает + +#### Scenario: Упавшая проверка + +- **WHEN** во время `make failure_checks` падает хотя бы одна проверка +- **THEN** код выхода ненулевой, журналы API, уборщика, relay и worker стенда отказов + выведены, стенд отказов удалён + +#### Scenario: Прерывание + +- **WHEN** `make failure_checks` прерван Ctrl+C +- **THEN** стенд отказов остановлен и удалён вместе с volumes + +#### Scenario: Хвост прошлого прогона + +- **WHEN** контейнеры или volumes стенда отказов остались от прогона, + убитого без уборки +- **THEN** следующий `make failure_checks` удаляет их и начинает заново diff --git a/openspec/changes/track1-queue-overload/tasks.md b/openspec/changes/track1-queue-overload/tasks.md new file mode 100644 index 00000000..0839b1fe --- /dev/null +++ b/openspec/changes/track1-queue-overload/tasks.md @@ -0,0 +1,147 @@ +# Tasks + +Как строить — `design.md` (дальше «решение N»), что должно получиться — дельты в `specs/`. Перед первым файлом слоя прочитать его правило: `settings.md`, `api-contract.md`, `api-layer.md`, `service-layer.md`, `repo-layer.md`, `service-tests.md`, `student-tests.md`, `logging.md`, `bench.md`, `docker.md`, `worker.md`. + +**Граница коммита.** Группы 1–7 — код, тесты, инструменты и правила: проверяются на рабочем дереве, агент apply не коммитит и в `evidence/` не пишет. Группа 8 — гипотезы в `REPORT.md` и коммит кода: основная сессия, **раньше любой метки замера**. Группа 9 — метка и отчёт на закоммиченном коде (`bench.md`, «Измеренное состояние — commit»). + +**Шага оператора нет.** Новых секретов нет, `config.toml` читается как есть. Руками `.env` не читать и не править. + +**Ожидаемо красное**, остальное разбирается по AGENTS.md: +- между задачами 4.6 и 4.7 — сверка покрытия: «marker points to unknown scenario», sync раньше тестов дал бы обратное; +- `test_exclusion_evidence_exists` — по `evidence/queue/baseline/summary.md`, пока метка не снята (группа 9); падать он должен только по этому файлу. + +Решения по ходу работы — design, новый раздел «Уточнения apply»; вопросы и решения без пользователя — `QUESTIONS.md`, `## track1-queue-overload`; дефект, найденный попутно, — `KNOWN_ISSUES.md`. Сервисы — только на портах и `self.uow` (`service-layer.md`), новый метод repo — порт, SQL, фейк и строка контракта. + +## 1. Настройка и ответ 429 + +- [ ] 1.1 `Uploads.max_unfinished_jobs: int = Field(default=250, ge=0)` с комментарием (`src/config/settings.py`), строка в `config_example.toml` (`[uploads]`), `uploads_max_unfinished_jobs` в записи «Started API» (`src/main.py`). + + Проверка: `uv run python -c "from src.config import settings; print(settings.uploads.max_unfinished_jobs)"` — 250; `UPLOADS__MAX_UNFINISHED_JOBS=-1` — ошибка проверки с именем поля. +- [ ] 1.2 Константа `UPLOAD_BACKLOG_RETRY_AFTER_SECONDS = 5` с обоснованием решения 2 (`src/utils/constants.py`), `UploadBacklogFull` (`src/core/exceptions/attachment.py`, реэкспорт), строки в `DOMAIN_ERRORS` и `RETRY_AFTER` (`src/api/errors.py`). + + Проверка: тест задачи 3.2 видит 429 `rate_limited` и `Retry-After: 5`; `make service_test`. + +## 2. Счёт незавершённых + +- [ ] 2.1 `count_unfinished(*, limit: int) -> int` по решению 3: порт с докстрингом-контрактом («сумма не меньше `limit` тогда и только тогда…»), `SqlAlchemyAttachmentJobRepository` — сумма трёх `SELECT count(*) FROM (SELECT … LIMIT :limit)` по условиям трёх частичных индексов, состояния `literal_execute`, один `execute`; фейк в `service-tests/fakes/repos.py`. + + Проверка: `service-tests/unit/test_architecture.py` зелёный; `EXPLAIN` на базе стенда — три Index Only Scan по `ix_attachment_jobs_outbox`, `ix_attachment_jobs_published`, `ix_attachment_jobs_lease`, без Seq Scan. +- [ ] 2.2 `check_count_unfinished` в `service-tests/repo_contract.py`: `queued` без отметки, с отметкой и со сроком, `processing` считаются; `succeeded` и `failed` — нет; решение «не меньше предела» верно при счётах ниже, на и выше предела, в том числе когда одна группа больше предела. Строка `count_unfinished` в `test_status_is_a_constant_in_statement`. + + Проверка: `make service_test`, `make service_test_db`. + +## 3. Сервис загрузки + +- [ ] 3.1 `AttachmentService.upload` по решению 3: 415, 413 и счёт — в первом блоке единицы работы, после `require_member`; при `max_unfinished_jobs == 0` запроса нет; `info` «Rejected attachment» `reason=backlog`, `unfinished`, `limit`; докстринг — новый порядок. `_store` и места — без изменений. + + Проверка: `make lint`; `driver.py lb-upload-timeouts` — без изменений (цепочка та же). +- [ ] 3.2 Быстрые тесты `service-tests/unit/test_attachment_service.py`: у предела — `UploadBacklogFull`, тело не читается, место не занято, строк и объектов нет; ниже предела и при 0 — загрузка идёт; при 0 метод не вызывается (`database.events`); порядок: посторонний, тип и `Content-Length` раньше предела. `settings.uploads.max_unfinished_jobs` — в `fixed_settings` `unit/conftest.py`. + + Проверка: `make service_test` — зелёный; временная регрессия (убрать проверку) делает новые тесты красными. + +## 4. Проверки отказов + +- [ ] 4.1 `student-tests/run_failures.py` по решению 13: `UPLOADS__MAX_UNFINISHED_JOBS=0` у четырёх прежних API, пятый `<проект>-api-backlog` с `BACKLOG_ENV` (`UPLOADS__MAX_UNFINISHED_JOBS=3`), `FAULT_BACKLOG_BASE_URL`, `FAULT_BACKLOG_ENV`, журнал при падении, уборка. `conftest.py`: фикстура `backlog_api`, отказ `pytest -m fault` без адреса. + + Проверка: `make failure_checks FAULT_ARGS='-k upload_slots_busy'` — поднимаются пять API, прежний тест зелёный. +- [ ] 4.2 `fault_hook.py`: действие `unfinished-jobs` (число заданий `queued` и `processing`); `test_failures.py`: `assert_backlog_stand`, помощник «дождаться нуля незавершённых» при работающем worker. + + Проверка: `make failure_checks FAULT_ARGS='-k backlog'` выводит число. +- [ ] 4.3 `test_backlog_limit` (fault) — сценарии `queue-overload` «Предел достигнут», «Порядок проверок у предела», «Остальной API у предела», «Загрузки снова принимаются»: worker остановлен, незавершённых ноль, `sample.png` до K: 202, следующая — 429, `assert_error(resp, 429)`, `Retry-After` 5, быстрее секунды, `attachment-ids` и `object-ids` те же; посторонний, 30 MiB по `Content-Length`, `text/plain` — 404, 413, 415; текст, история, метаданные и байты готового, сообщение со ссылкой на принятое, `/health/ready` — без ошибок; запуск worker, ноль незавершённых — 202 и все `ready`. + + Проверка: `make failure_checks FAULT_ARGS='-k test_backlog_limit'` зелёный; на временной регрессии (`DOMAIN_ERRORS` без строки, 400) — красный. +- [ ] 4.4 `test_backlog_ignores_finished`: `ready` и `failed` больше K, незавершённых ноль — 202. `test_backlog_counts_waiting_retry`: задание со сроком следующей попытки в будущем (`set-next-attempt`) считается: 429; срок снят — обрабатывается. `test_backlog_without_broker`: брокер и relay остановлены — 202 быстрее секунды до K, затем 429; после запуска брокера, relay и worker все `ready`. + + Проверка: `make failure_checks FAULT_ARGS='-k backlog'`. +- [ ] 4.5 `test_backlog_overshoot_bounded`: worker остановлен, 40 клиентов за `threading.Barrier` (больше мест и очереди реплики) по малому PNG: ответы 202 или 429, 5xx нет; принято не меньше K и не больше K + (`max_concurrent` + `max_waiting`) реплики; запуск worker — все `ready`. `test_backlog_off`: обычный API при K незавершённых и больше — 202. + + Проверка: `make failure_checks FAULT_ARGS='-k backlog'`. +- [ ] 4.6 Прочее: `images` и `contract.py` без изменений, если хватает; маркеры `@pytest.mark.spec("queue-overload", …)` на всех тестах; прежние тесты не правятся (решение 13). + + Проверка: `uv run pytest student-tests --collect-only -q -m fault` видит новые тесты; `git diff --stat student-tests/` — только новые тесты, `run_failures.py`, `conftest.py`, `fault_hook.py`, `spec_coverage.py`. +- [ ] 4.7 Сверка покрытия: `queue-overload` в `CAPABILITIES`; исключения девяти сценариев (нужны открытая нагрузка, счётчики и рестарт контейнера) со ссылкой `evidence/queue/baseline/summary.md` и командой `make bench_queue`; sync всех дельт в основные спеки (`/opsx:sync`): сверка читает только `openspec/specs/`. + + Проверка: `make student_test` — сверка: нет ни «no test», ни «marker points»; `test_exclusion_evidence_exists` называет только `evidence/queue/baseline/summary.md`. + +## 5. Стенд `bench/` + +- [ ] 5.1 `bench/make_images.py` по решению 5: stdlib и Pillow образа, зерно из аргумента, файлы `s`, `m`, `lj`, `lp`, JSON с размерами и SHA-256 на stdout; больше 10 485 760 байт или 40 млн пикселей — код 1. `Stand.make_images` — контейнер `mtusi-bench-images` на образе стенда, `--network none`, запись в `.work/`. Построение и зерно — решение 5. + + Проверка: дважды подряд — те же SHA-256; размеры в границах; `python -m src.worker.render` на каждом — код 0; `make_images` не импортирует `src`. +- [ ] 5.2 `bench/overload.py` (`--selftest`, только stdlib, без docker; не `queue.py`: затенил бы модуль stdlib) по решениям 5–8 и 11–12: план кругами `plan_cells`; разбор строк `q,…`, `qs,…`, `qv,…`, строк `jobs`, `mq`, `mp` и журналов контейнеров (записи — по `event`); окна, throughput, время до `ready`, очередь, пики; жизни контейнера: сброс счётчиков cgroup после перезапуска (решение 10); 429 по причинам из журнала реплик и моменты первого `busy` и первого `backlog`; строка `cells.csv` (`CELL_FIELDS`, в том числе `worker_restarts`) и посекундная `timeline.csv`; пометки решения 11; вердикты H1–H9 по таблице решения 12 («подтверждено», «нет», «нет данных»); правило рекомендации; `render_summary` и графики на `plots.Svg`. Новая метрика — столбец в конце. + + Проверка: `uv run python bench/overload.py --selftest` покрывает: план без повтора подряд, окна на границе, `updated_at` в микросекундах, потерянное и зависшее вложение, `oom`, перезапуск контейнера посреди ячейки (наибольшее и сумма по жизням), каждый вердикт в обе стороны и «нет данных», рекомендацию (2, 2) и другую. +- [ ] 5.3 `bench/k6/queue.js` по решению 6 (сценарии окон `constant-arrival-rate`, `timeUnit: "10s"`, VU заранее `queue_pre_vus` без прибавления, 429 не повторяется, строка `q,…` с `Retry-After`, порог итераций для сверки строк) и `bench/k6/queue_sweep.js` по решению 9 (`shared-iterations`, ids из `.work/`, строка `qs,…` на вложение, у выборки — SHA-256 оригинала и вариантов, строка `qv,…`). Идентификация — как в `uploads.js`. + + Проверка: `make bench_queue_quick` (задача 5.7): число строк `q,…` равно итерациям; выборка сошлась. +- [ ] 5.4 `bench/sampler.sh`, режим `queue` по решению 10; `bench/queue.compose.yml` (плагин брокера, `restart: unless-stopped` у worker), `bench/rabbitmq/enabled_plugins`, `bench/rabbitmq/91-bench.conf`. Режимы `list`, `scan`, `peak` и их разбор не меняются. + + Проверка: `uv run python bench/scaling.py --selftest`, `uv run python bench/resources.py --selftest`; на стенде строки `mq` идут раз в секунду, `missing` при остановленном брокере; значение совпадает с `rabbitmqctl list_queues`; порт 15692 не опубликован на хосте; `docker inspect` контейнера worker — политика `unless-stopped`, контейнеров других профилей — прежняя; разбор перезапуска — `--selftest` задачи 5.2 (завершение ядром случайно, по команде его не вызвать: `docker kill` демон считает ручной остановкой и не перезапускает). +- [ ] 5.5 `bench/run.py`: `Profile` (`queue_*`, `is_queue`), профили `queue` и `queue_quick` по решениям 5, 6, 8, 14; `Stand.start` при `is_queue` и `queue.compose.yml`; `leftovers`, `stop`, `vm_warnings`, `limits` — новые роли и `mtusi-bench-worker-2`, `mtusi-bench-images`; `compose kill` перед `down`; бюджет CPU — код 2 до стенда; каталог `evidence/queue/<метка>/`; `--resume` у `is_queue` (`resume_problems`, готовая строка `cells.csv`). + + Проверка: `make bench_uploads_quick` и `make bench_quick` — код 0, паспорт без изменений, кроме `.work/variant.compose.yml` у `uploads` (задача 5.8); `make bench_queue` на чужой занятой метке — код 2. +- [ ] 5.6 `Bench.run_queue` и `queue_cell`: разогрев, сэмплер, контрольный `background.js` (остановка SIGINT, `reconcile.line_problems`), `queue.js`, ожидание нуля незавершённых по строкам `jobs` со сроком, окно `after`, `queue_sweep.js`, чтение SQL, журналы (сверка «Started worker» с ячейкой — отказ при расхождении), строка `cells.csv`; блоки решения 8: пределы, приём (15/с, 45 с, причины 429 из журнала реплик), второй worker в конце `over`, KILL worker и рестарт брокера посреди `over`; сторож сэмплера; код команды по пометкам решения 11. Секреты в метку не попадают: `raw/` — только итоги k6, журналы не копируются. + + Проверка: `make bench_queue_quick`; в каталоге метки нет значений паролей и токенов (`meta.json` — через фильтр `SECRET_ENV_MARKS`, `raw/` — только итоги k6, журналы не копируются); прерывание Ctrl+C — стенд удалён, метка «незавершена»; `RESUME=1` — готовые ячейки не снимаются. +- [ ] 5.7 `Makefile`: `bench_queue [QUEUE_LABEL=...] [RESUME=1]`, `bench_queue_quick` (метка `quick-queue-<время>`), `$(KEEP_AWAKE)`, комментарии в стиле соседних; `.gitignore`: `evidence/queue/quick-*/`. + + Проверка: `make bench_queue_quick` — код 0 за ~11 мин, все вердикты посчитаны (на коротких окнах часть — «нет данных»), `git status` не видит каталога метки. +- [ ] 5.8 Профиль `uploads` по решению 13: `UPLOADS__MAX_UNFINISHED_JOBS=0` в override всех вариантов, `app_env` в паспорте. + + Проверка: `make bench_uploads_quick` — код 0, все 429 — от мест (`reason=busy`), ни одного `backlog`. + +## 6. Правила и карта кода + +- [ ] 6.1 `.claude/rules/`: `bench.md` — раздел «Профиль очереди», таблица инструментов, новая роль в «что не меняется», граница чёрного ящика; `worker.md` — правило concurrency и prefetch: `concurrency ≤ min(CPU + ожидание, (лимит − база) / пик)`, `prefetch = concurrency`, ограничения `prefetch / потолок` (30 мин, 300 с), завершение процесса 1 ядром при превышении лимита и перезапуск, ссылка на метку; `settings.md`, `api-contract.md` (таблица кодов, порядок проверок), `service-layer.md`, `repo-layer.md`, `logging.md`, `student-tests.md` (пятый API, hook, тесты), `run-modes.md` по необходимости. + + Проверка: `grep -n "max_unfinished_jobs\|UploadBacklogFull\|bench_queue" .claude/rules/*.md` находит правила; новых утверждений о числах метки нет: они — в `REPORT.md`. +- [ ] 6.2 `AGENTS.md`: статус лабы и change, инвариант предела (уровень 5), команды `make bench_queue`, `make bench_queue_quick`, карта кода: `bench/overload.py`, `make_images.py`, `queue.compose.yml`, `k6/queue*.js`, `evidence/queue/`, `count_unfinished`; в `KNOWN_ISSUES.md` теперь девять открытых записей (запись о памяти S3 добавлена стадией propose). + + Проверка: `graphify update .` без ошибок; команды из таблицы существуют (`make -n bench_queue_quick`). +- [ ] 6.3 `.claude/skills/run-mtusi-messenger/SKILL.md` — строка о `make bench_queue_quick` для защиты. `QUESTIONS.md` — решения apply. + + Проверка: `make check`; `make lint`. + +## 7. Регресс на рабочем дереве + +- [ ] 7.1 `make lint`, `make check`, `make validate PYTHON=.venv/bin/python`, `make service_test`, `make service_test_db`. + + Проверка: всё зелёное; `tests/`, `contracts/`, `README.md`, `lab.json` без изменений (`git status`). +- [ ] 7.2 Рабочий стенд на дереве: `make run_docker`, `make test`, `make student_test`; `make test_isolated`. + + Проверка: `PASS: lab5`; красное только `test_exclusion_evidence_exists` по метке группы 9. +- [ ] 7.3 Полный `make failure_checks` (рабочий стенд остановлен: `make stop`). + + Проверка: все проверки зелёные, число и время — в отчёт apply; `crash markers 0`. +- [ ] 7.4 `make bench_queue_quick`, `make bench_uploads_quick`, `make bench_rollout_quick`. + + Проверка: код 0 у всех, очередь поднимается и опускается на шкале, у `kill-worker` две попытки у взятых, нет `lost`, `stuck`, `duplicate`. + +## 8. Гипотезы до меток (основная сессия) + +- [ ] 8.1 `REPORT.md`, новый раздел «Очередь под перегрузкой»: гипотезы H1–H9 с порогами из решения 12, методика, определения решения 7, правило рекомендации. Числа метки — пока нет. Вопросы из `QUESTIONS.md` — в «Открытые вопросы преподавателю». + + Проверка: раздел называет порог у каждой гипотезы; `make lint`. +- [ ] 8.2 Коммит кода, правил и гипотез на ветке `feat/track1-queue-overload`. + + Проверка: `git status` чист; commit с гипотезами раньше первой метки в `git log`. + +## 9. Метка и отчёт (после коммита, основная сессия) + +Снимать на закоммиченном коде, дерево чистое, рабочий стенд `make stop`, питание от сети, давления на память нет (`bench.md`). + +- [ ] 9.1 `make bench_queue` (метка `baseline`, ~2 ч 10 мин). Прерывание — `RESUME=1`. + + Проверка: код 0; `meta.json`: `git.dirty` false, `host_state`, план 57 ячеек; `swapouts_delta` 0 или пометка разобрана: настоящая помеха — переснять под новой меткой. +- [ ] 9.2 Коммит метки. `make student_test` на рабочем стенде после `make run_docker`. + + Проверка: `test_exclusion_evidence_exists` зелёный. +- [ ] 9.3 `REPORT.md`, раздел «Очередь под перегрузкой»: таблицы из `summary.md` — throughput, очередь, p50, p95, p99 до `ready`, RSS, `memory.peak`, CPU и троттлинг по настройкам и классам; блоки; backpressure и ограничение принятой работы (таблица решения 4 с числами метки); восстановление; вывод по каждой гипотезе; компромисс latency и ресурсов; рекомендация и решение о значениях по умолчанию; обоснование предела по измеренному потолку; S3 как общий ресурс приёма и worker; завершение процесса 1 ядром; ограничения метода, в том числе память S3 на долго живущем стенде (`KNOWN_ISSUES.md`). «Трек 1 уровня 5» в таблице критериев; разделы «Сервисы», «Ограничения», «Следующие шаги», «Ответы на вопросы защиты» — по изменениям; шаг защиты. + + Проверка: числа совпадают с `summary.md` метки; `make lint`, `make check`, `openspec validate track1-queue-overload --strict`. +- [ ] 9.4 Если правило решения 12 меняет значения по умолчанию — отдельный commit значения, `make bench_queue_quick`, строка в отчёте. Иначе — запись в отчёте, что значения оставлены, и почему. + + Проверка: `git log` называет шаг; `make test`. +- [ ] 9.5 Коммит отчёта основной сессией. + + Проверка: `git status` чист, шапка отчёта называет commit метки.