Files
mtusi2026lab5/openspec/changes/track1-queue-overload/tasks.md
T

29 KiB
Raw Blame History

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/baseline2/summary.md, пока метка не снята (группа 10); падать он должен только по этому файлу и файлам вне change, что снимаются на финальном шаге лабы.

Решения по ходу работы — 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_settings unit/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-After 5, быстрее секунды, 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/baseline2/summary.md и командой make bench_queue; sync всех дельт в основные спеки (/opsx:sync): сверка читает только openspec/specs/.

    Проверка: make student_test — сверка: нет ни «no test», ни «marker points»; test_exclusion_evidence_exists называет только evidence/queue/baseline2/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.dirty false, host_state, план 57 ячеек; swapouts_delta 0 или пометка разобрана: настоящая помеха — переснять под новой меткой.

  • 9.2 Коммит метки. make student_test на рабочем стенде после make run_docker.

    Проверка: test_exclusion_evidence_exists зелёный. Оговорка: по метке зелёный, файл метки он больше не называет (ссылка переведена на evidence/queue/baseline2/summary.md, снова красная до задачи 10.20); остаётся красным по трём файлам вне change (evidence/auth/passwords-and-tokens.md, evidence/cache/hits.md, evidence/idempotency/replay-after-restart.md), их снимают на финальном шаге лабы на итоговом коде.

  • 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 Коммит отчёта основной сессией (a8ef6ad).

    Проверка: git status чист, шапка отчёта называет commit метки.

10. Замечания проверки

Находки verify. Метка переснимается целиком под именем baseline2 на коммите с правками: каталог baseline не трогается (bench.md, «Результаты»). Пороги H1–H9 не меняются. Задачи 10.1–10.19 — код, инструмент, спеки и правила на рабочем дереве; 10.20–10.21 — на закоммиченном коде.

  • 10.1 C1: lb_down считает только слоты-серверы (svname не BACKEND и не FRONTEND), подсчёт — в bench/overload.py, проверка в --selftest; другие подсчёты UP профиля очереди сверены.

    Проверка: --selftest красный до правки; одна реплика UP плюс BACKEND UP — да, обе UP — нет.

  • 10.2 C2: задача 9.5 отмечена.

  • 10.3 W1: queue lag в сводке; queue_wait по окнам — новые столбцы в конце cells.csv, столбцы в таблице сводки, определение в REPORT.md.

  • 10.4 W2: cpu_worker_per_job_s — ready до recovery_end.

    Проверка: --selftest красный до правки.

  • 10.5 W3: уточнение порога H3 в REPORT.md рядом с гипотезой, столбцы литеральной доли и доли окна after.

  • 10.6 W4: худший случай дорогих файлов назван неизмеренным расчётом: REPORT.md, комментарий src/config/settings.py, settings.md, решение 2.

  • 10.7 S1: арифметика REPORT.md, «Предел 250»; решение 2 о копиях при (2, 2) и (2, 256).

  • 10.8 S2: спек — восстановление от последней загрузки окна (дельта и основной).

  • 10.9 S3: CPU и троттлинг по окнам и ролям — новые столбцы.

  • 10.10 S4: столбцы перезапусков relay, сверка принятых в обратную сторону: лишние строки БД — пометка, как lost.

  • 10.11 S5: причина завершения worker из docker events: разные столбцы для ядра, команды и прочих; oom_kill не переименован; правило и H2 — по подтверждённому oom.

    Проверка: --selftest — ядро, docker kill, код выхода; проба событий Docker на живом контейнере.

  • 10.12 S6: recommend не считает настройку, не снятую на части классов, кандидатом; сводка называет «снята не на всех классах».

    Проверка: --selftest красный до правки.

  • 10.13 S7: условие H6 для lp (4, 4) в r3 названо в REPORT.md.

  • 10.14 S8: тест значения -1 настройки предела.

  • 10.15 S9: «17 с» до тела — с закрытием соединения 21 с в правилах; граница уборщика проверена, правка формулы вне change — KNOWN_ISSUES.md.

  • 10.16 S10: счёт готовых ячеек при прерывании.

  • 10.17 Ссылки на метку: spec_coverage.py, спеки, правила, AGENTS.md, задачи — evidence/queue/baseline2/summary.md; причина пересъёмки — REPORT.md.

    Проверка: test_exclusion_evidence_exists называет новый файл, пока метка не снята: так и должно быть.

  • 10.18 Прокрутка: make bench_queue_quick и блоки, которых в ней нет, на рабочем дереве.

  • 10.19 Регресс: make lint, make check, make validate PYTHON=.venv/bin/python, make service_test, make service_test_db, все --selftest, openspec validate track1-queue-overload --strict, make test, make student_test, make failure_checks FAULT_ARGS='-k backlog'.

  • 10.20 Метка: make bench_queue QUEUE_LABEL=baseline2 на коммите с правками, коммит метки.

    Проверка: код 0; git.dirty false; план 57 ячеек; test_exclusion_evidence_exists этот файл больше не называет.

  • 10.21 REPORT.md — числа, вердикты и рекомендация по baseline2, lb_down, lag, причины перезапуска, литеральная доля H3; S1 пересчитан на новой метке.

    Проверка: числа совпадают со сводкой baseline2, make check, openspec validate track1-queue-overload --strict.