# 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 мин.