74 lines
8.4 KiB
Markdown
74 lines
8.4 KiB
Markdown
# 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 мин.
|