Files
mtusi2026lab5/openspec/changes/track1-queue-overload/proposal.md
T
2026-11-01 05:28:05 +03:00

74 lines
8.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 мин.