docs: propose track1-queue-overload

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-01 05:28:05 +03:00
co-authored by Claude Opus 5.5
parent 5a97416679
commit 5b5f59aa3b
14 changed files with 1625 additions and 0 deletions
+18
View File
@@ -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 без общего срока. Найдено
+31
View File
@@ -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` работают. Сценарий защиты грузит единицы файлов. Другой ответ — значение настройки.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-01
@@ -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,<окно>,<отправка мс>,<длительность мс>,<статус>,<Retry-After>,<X-Instance-Id>,<id>` в файл консоли, полнота — сверка с итерациями. Момент приёма — отправка + длительность по часам ВМ, как в профилях `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 <нс> <id12> <memory.peak> <anon> <oom_kill>` и `mq <нс> <ready> <unacked>` (`/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`: ни один не меняет подход и задачи; другой ответ меняет строку таблицы ошибок и сценарий.
@@ -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 мин.
@@ -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
@@ -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 быстрее
секунды: проверка к брокеру не обращается
@@ -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`
@@ -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** у каждой гипотезы есть вывод со ссылкой на ячейки сводки, числа совпадают со сводкой, а рекомендуемая настройка следует из правила и таблиц
@@ -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`
@@ -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 не изменились
@@ -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** сервис не стартует, в журнале — ошибка проверки настроек с
именем поля
@@ -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` удаляет их и начинает заново
@@ -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 метки.