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

8.4 KiB
Raw Blame History

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