Reject uploads with 429 at [uploads] max_unfinished_jobs, counted by the existing partial indexes in the membership block. Add the bench_queue profile, hypotheses H1-H9 and the fifth failure-stand API. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
24 KiB
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_settingsunit/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-After5, быстрее секунды,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.dirtyfalse,host_state, план 57 ячеек;swapouts_delta0 или пометка разобрана: настоящая помеха — переснять под новой меткой. -
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 метки.