Files
mtusi2026lab4/openspec/changes/upload-memory/tasks.md
T

27 KiB
Raw Blame History

Tasks

Порядок — design, Migration Plan; тесты пишутся раньше кода, чтобы снять красный прогон без checkout и stash. Значения и формулы — design, решения 7 и 9; методика профиля — решение 10; тесты — решение 11. Commit делает основная сессия после подтверждения пользователя (bench.md, «Измеренное состояние — commit»). Замеры и evidence — только с закоммиченного кода.

1. Тесты и красный прогон

  • 1.1 student-tests/contract.py: assert_error(resp, 429) — code rate_limited и Retry-After — положительное целое. Проверка — тесты 1.4.

  • 1.2 test_attachments.py::test_concurrent_uploads (спек attachments, «Загрузки в пределах лимита»). 10 потоков за threading.Barrier, у каждого свой Api, PNG ~1 MiB из images.py: все 201, id разные, каждое скачивается с тем же SHA-256. Проверка — make test_isolated и make student_test через LB (группа 10).

  • 1.3 run_failures.py: третий API <проект>-api-uploads с UPLOADS_ENV:

    • UPLOADS__MAX_CONCURRENT=1, UPLOADS__MAX_WAITING=1;
    • UPLOADS__WAIT_TIMEOUT_SECONDS=1, UPLOADS__BODY_TIMEOUT_SECONDS=2.

    Тестам — FAULT_UPLOADS_BASE_URL и FAULT_UPLOADS_ENV; журнал этого API при падении; уборка. Фикстура uploads_api в conftest.py. Проверка: make failure_checks FAULT_ARGS='-k uploads' поднимает три API и убирает стенд.

  • 1.4 test_failures.py (маркер fault, spec по таблице решения 11): test_upload_slots_busy, test_rejections_before_queue, test_upload_waits_for_slot, test_slot_released_after_failures, test_slow_body. Место держит загрузка с генератором тела на threading.Event. Клиент с ожиданием — со сроком 30 с, сроки стенда — из FAULT_UPLOADS_ENV (тест сверяет, что стенд запущен с ними). Новые id проверяются списками hook (attachment-ids, object-ids).

  • 1.5 Красный прогон на коде до групп 2–4: make failure_checks FAULT_ARGS='-k "slot or queue or slow_body"'. Старый API не знает [uploads], поэтому ожидаемо падают test_upload_slots_busy, test_upload_waits_for_slot и test_slow_body. test_slot_released_after_failures и test_rejections_before_queue на коде без мест зелёные: они ловят утечку места и ожидание ранних отказов в очереди. Вывод и число упавших — в evidence/tests/ (раздел красного прогона failure-checks.md) и в tasks при прогоне.

    Прогон 2026-10-21 на f894040 (HEAD fc1524d): 5 failed — все пять. test_slot_released_after_failures красный на шаге «тело дольше срока — 400» (срока тела нет, 201; шаги 413 и 415 прошли), test_rejections_before_queue — на проверке, что очередь полна (ожидавшая получила 201, а не 429). Отклонение от ожидания tasks — design, «Уточнения apply», п. 2.

2. Константы, исключения, настройки

  • 2.1 src/utils/constants.py: UPLOAD_RETRY_AFTER_SECONDS = 1 с комментарием (design, решение 2). Проверка: make lint.

  • 2.2 src/core/exceptions/attachment.py:

    • UploadsBusy — «Too many uploads in progress, retry later»;
    • UploadTimedOut — «Upload body was not received in time».

    Реэкспорт в __init__.py. Проверка: uv run python -c "from src.core.exceptions import UploadsBusy, UploadTimedOut".

  • 2.3 src/api/errors.py: UploadsBusy → 429 ErrorCode.RATE_LIMITED с заголовком Retry-After из константы (рядом с CHALLENGES), UploadTimedOut → 400 invalid_request. Проверка — тесты 1.4.

  • 2.4 Секция [uploads] — класс Uploads в src/config/settings.py:

    • max_concurrent (int, ge=1, 4);
    • max_waiting (int, ge=0, 16);
    • wait_timeout_seconds (float, gt=0, 5);
    • body_timeout_seconds (float, gt=0, 30).

    Поле uploads в Settings, строки с комментариями в config_example.toml (settings.md, «Новое поле или секция»). Проверка:

    • uv run python -c "from src.config import settings; print(settings.uploads.max_concurrent)" — 4;
    • с UPLOADS__MAX_CONCURRENT=0, UPLOADS__MAX_WAITING=-1 и UPLOADS__BODY_TIMEOUT_SECONDS=abc — ошибка с именем поля.

    Прогон: 4 / 16 / 5.0 / 30.0; ошибки — uploads.max_concurrent, uploads.max_waiting, uploads.body_timeout_seconds (и uploads.wait_timeout_seconds при 0). Секция добавлена и в рабочий config.toml (те же значения).

3. Места загрузки и срок тела

  • 3.1 src/infra/upload_slots.py: класс UploadSlots и глобал upload_slots из settings.uploads (design, решение 1). Контекст slot():

    • места нет и ожидающих уже max_waiting — сразу UploadsBusy;
    • иначе ожидание по порядку прихода не дольше wait_timeout_seconds, истекло — UploadsBusy;
    • контекст отдаёт ожидание в мс;
    • место освобождается в finally, в том числе при CancelledError; отмена во время ожидания не уменьшает число мест.

    Проверка — разовый скрипт в scratchpad на asyncio: 1 место, 1 ожидающий. Третий — сразу UploadsBusy, второй — через срок. После отмены ожидающей задачи и после исключения внутри контекста место снова свободно.

    Прогон (scratchpad/slots_check.py): третий — UploadsBusy за 0,000 с, второй — за 0,502 с (срок 0,5); после отмены ожидающей, после исключения и после отмены уже разбуженной ожидающей место сразу свободно, _value 1, ожидающих 0.

  • 3.2 src/api/dependencies.py: AttachmentService(db_scope=…, cache=…, storage=…, slots=upload_slots). Глобал импортирует только dependencies.py (infra.md). Проверка: grep -rn upload_slots src — только infra/upload_slots.py, dependencies.py и тип в сервисе.

    Тип в сервисе — под TYPE_CHECKING: импорт модуля создаёт глобал, а сервис импортирует и уборщик (design, «Уточнения apply», п. 4).

  • 3.3 AttachmentService.upload (src/core/services/attachment.py; design, решения 3 и 4):

    • после проверок членства, Content-Type и Content-Length — async with self.slots.slot(), внутри — остальной путь до ответа;
    • _read_body под asyncio.timeout(body_timeout_seconds), истёк — UploadTimedOut и info «Rejected attachment» (reason=body_timeout);
    • UploadsBusy — info «Rejected attachment» (reason=busy, waited_ms);
    • «Uploaded attachment» — с waited_ms;
    • докстринги — новый порядок.

    Проверка — тесты 1.4 зелёные (группа 10).

    На дереве: make failure_checks FAULT_ARGS='-k "slot or queue or slow_body"' — 5 passed (evidence — после commit, 10.5).

  • 3.4 src/main.py: запись «Started API» с uploads_max_concurrent, uploads_max_waiting, uploads_wait_timeout_seconds, uploads_body_timeout_seconds. Проверка: make run_dev — запись с 4, 16, 5, 30 (спек service-configuration, «Параметры загрузок по умолчанию»).

    Проверено консольным запуском APP__RUN_MODE=console APP__PORT=8095 uv run python -m src (порт 8080 занят LB рабочего стенда, а make run_dev слушает его): uploads_max_concurrent 4, uploads_max_waiting 16, uploads_wait_timeout_seconds 5.0, uploads_body_timeout_seconds 30.0.

4. Одна копия тела при PUT

  • 4.1 _read_body возвращает BytesIO. Сервис:

    • data = buffer.getvalue();
    • проверка изображения и SHA-256 над data;
    • size = len(data), del data;
    • buffer.seek(0), PUT этим буфером.

    Комментарий — почему del (design, решение 5, Context п. 1).

  • 4.2 ObjectStorage.put(key, body, *, size, content_type) (src/infra/s3/client.py) и put_original(storage, *, key, body, size, content_type) (src/core/repos/attachment_object.py): тело — поток с read, seek, tell; size — в журнал вызова. Проверка:

    • скрипт в scratchpad в образе API против S3 стенда: VmHWM шага PUT ≤ 1,3 тела (было 2,0);
    • SHA-256 сохранённого объекта совпал;
    • make test и тесты вложений зелёные.

    Прогон (scratchpad/put_memory_check.py, docker compose run --rm --no-deps сервиса api с src дерева поверх образа, тело 10 479 105 байт, объекты под umcheck/ удалены): прежний путь (PUT bytes) — пик над базой 2,31 тела; новый (тот же BytesIO после del) — 1,19 тела в трёх загрузках подряд; SHA-256 всех объектов совпал. make test и тесты вложений — в make test_isolated (9.4).

5. Стенд и LB

  • 5.1 docker-compose.yml, сервис api: sysctls: net.ipv4.tcp_rmem: "4096 131072 524288" с комментарием (design, решение 6). Проверка: docker compose exec api cat /proc/sys/net/ipv4/tcp_rmem на каждой реплике; то же в контейнере make test_isolated и стенда отказов.

    На дереве: docker compose run --rm --no-deps --entrypoint cat api /proc/sys/net/ipv4/tcp_rmem — 4096 131072 524288 (так же запускают API make test_isolated и стенд отказов); реплики рабочего стенда — после make rolling_update (10.1).

  • 5.2 infra/haproxy/haproxy.cfg:

    • global — tune.sndbuf.server 262144;
    • defaults — http-error status 400 с "code":"invalid_request", request_id %[unique-id] и заголовком X-Request-Id;
    • backend api — http-request set-timeout server 30s if METH_POST { path_reg ^/api/v1/chats/[^/]+/attachments$ } с формулой решения 7 в комментарии.

    Проверка: haproxy -c в закреплённом образе с API_PORT; make run_docker, make instances, make test.

    haproxy -c (haproxy:3.4.6-trixie@sha256:e2739156…, API_PORT=8080) — код 0. Рабочий стенд в этом запуске не перестраивается: LB — up -d --force-recreate haproxy в 10.1; поведение — драйвер 7.1.

  • 5.3 scripts/rolling-update.sh: ROLLOUT_DRAIN_TIMEOUT по умолчанию 90 с, комментарий: «больше timeout server пути загрузки и наибольшей длительности загрузки». Проверка: make rolling_update на рабочем стенде — код 0, дренаж каждой реплики — секунды.

    Прогон make rolling_update — в 10.1 (после commit).

  • 5.4 KNOWN_ISSUES.md: запись «LB отвечает 408 на медленные заголовки текстом HAProxy»:

    • где и что, проба — design, Context п. 4;
    • предложение и почему errorfile со статичным request_id не годится: контракт требует id из X-Request-Id.

    Проверка: запись есть.

6. Спеки и сверка покрытия

  • 6.1 Sync дельт в основные спеки (/opsx:sync или вручную, как в attachments и upload-consistency): сверка покрытия видит новые сценарии. Проверка: openspec validate upload-memory --strict, в openspec/specs/attachments/spec.md есть «Одновременные загрузки реплики».

    Sync — /opsx:sync вручную по блокам: 7 спеков, все блоки дельты совпали с основными построчно; openspec validate --specs — 24 passed; openspec validate upload-memory --strict — valid.

  • 6.2 spec_coverage.py, EXCLUDED: attachments «Одна копия тела при записи в S3» и «Память не растёт с числом загрузок». Способ — make bench_uploads → evidence/uploads/<метка>/summary.md. Проверка: test_coverage.py зелёный. До commit метки test_exclusion_evidence_exists ожидаемо красный и называет оба сценария — записать это в tasks при прогоне.

    Ссылка — evidence/uploads/baseline/summary.md (метка по умолчанию 10.3). Прогон до метки: test_exclusion_evidence_exists — 1 failed, «exclusion refers to missing evidence/uploads/baseline/summary.md» по обоим сценариям; остальное в test_coverage.py зелёное (полная сверка — в make test_isolated, 9.4).

7. Драйвер скилла

  • 7.1 driver.py lb-upload-timeouts (stdlib, Python 3.9; design, решение 7):

    • временная сеть, HAProxy закреплённого образа с infra/haproxy/haproxy.cfg и API_PORT;
    • заглушка на образе API под именем api: /health/ready — 200, остальное — задержки по пути;
    • случаи: молчание 12 с на пути загрузки до тела и после тела — 201; 12 с на GET /api/v1/users/me — 504 через ~10 с; 32 с на пути загрузки — 504 через ~30 с; клиент молчит посреди тела 35 с — 400 в формате контракта, request_id = X-Request-Id;
    • уборка сети и контейнеров при любом исходе, код 1 при расхождении.

    SKILL.md — строка команды. Проверка: команда — код 0 на текущем haproxy.cfg и код 1 на haproxy.cfg f894040 (git show f894040:infra/haproxy/haproxy.cfg во временный файл, аргумент --config).

    Прогон на дереве (~33 с, пять случаев параллельно): текущий haproxy.cfg — код 0 (201 за 12,06 и 12,13 с; 504 другого пути за 10,01 с; 504 пути загрузки за 30,12 с; 400 application/json за 30,02 с). Конфигурация f894040 (git archive … | tar -x в scratchpad) — код 1: 502 за 10,23 с, 504 за 10,13 и 10,13 с, 400 text/html. Временные сети и контейнеры убраны, volumes те же. Решения сверх design — design, «Уточнения apply», п. 8.

8. Профиль uploads стенда bench/

  • 8.1 bench/run.py: профили uploads и uploads_quick (поля Profile, design, решение 10):

    • стенд с S3 и bootstrap, лимиты рабочего стенда, реплика без swap;
    • варианты «до» (uploads_before = "f894040", сборка как у rollout_from, проверка commit до стенда), «без лимита» и «с лимитом» с окружением в паспорте;
    • круги прогонов с перестановкой по зерну;
    • перед прогоном — новый volume S3 с bootstrap и новая реплика, ожидание UP, разогрев;
    • пометки oom, host_swap; блокировка bench/.bench.lock;
    • отказ занятой метки и остатков стенда.

    Проверка: отказ на занятой метке и на commit вне истории (код 2).

    Прогон: занятая метка и --from deadbeef0 — код 2 до стенда. Разбор без docker — новый bench/uploads.py (--selftest); решения сверх design — design, «Уточнения apply», п. 10.

  • 8.2 Тела PNG ~1 MiB и ~10 MiB из шума (random.Random(seed), stdlib), размеры и SHA-256 в паспорте. Проверка:

    • --selftest: размер ≤ 10 485 760, два запуска дают одни байты;
    • разовая проверка в образе API: тела принимает inspect_image (сам bench/ src не импортирует).

    --selftest — ok; в образе API inspect_image принял оба тела (1 048 276 байт 1024 × 341 и 10 479 107 байт 1024 × 3409).

  • 8.3 bench/k6/uploads.js: constant-vus, разгон и окно, тело из смонтированного файла, Bearer из lib.js; на 429 — пауза Retry-After, на прочие ошибки — 1 с; строка на запрос в файл консоли. Проверка: число строк = итерации из итога k6, как в failover.

    Сверку строк и iterations{scenario:upload} делает сам run.py (несовпадение — BenchError); в uploads_quick прошла во всех шести прогонах (216–840 итераций).

  • 8.4 bench/sampler.sh, режим peak:

    • сброс memory.peak реплики, S3 и LB через свой дескриптор (perl) в начале окна и чтение в конце;
    • выборка memory.current, anon, sock, oom_kill раз в 0,2 с;
    • контейнер — --user 0, cgroupfs на запись, без сети;
    • ядро без сброса — наибольшая выборка и peak_sampled в паспорте.

    Проверка: на uploads_quick пик окна при C = 1 ниже пика старта реплики.

    uploads_quick: пик окна при C = 1 — 120,6 / 120,8 MiB, пик старта — 152,5–152,7 MiB (сброс работает, ядро 7.0.14-linuxkit).

  • 8.5 Результаты evidence/uploads/<метка>/: meta.json, runs.csv (столбцы решения 10), summary.md (медиана и разброс по ячейкам, строки гипотез H1–H4), raw/. quick-uploads-* — в .gitignore. Makefile: bench_uploads (UPLOADS_LABEL ?= baseline) и bench_uploads_quick под $(KEEP_AWAKE). Проверка: make bench_uploads_quick — код 0, H1 и H2 видны в сводке.

    Прогон на дереве (метка quick-uploads-20261021T210436Z, в git не идёт): код 0, 6/6, без host_warnings. 10 MiB, пик реплики / 201 / 429 / 5xx / загрузок в с / p95: «без лимита» C = 1 — 120,6 MiB, 263, 0, 0, 11,45, 106 мс; C = 10 — 227,5, 216, 0, 0, 9,2, 1 499 мс; C = 40 — OOM (500,1 MiB по выборкам), 0 × 201, 800 × 5xx, 40 ошибок соединения; «с лимитом» C = 1 — 120,8, 253, 0, 0, 11,0, 116 мс; C = 10 — 169,8, 253, 0, 0, 10,75, 1 248 мс; C = 40 — 180,2, 272, 460, 0, 11,3, 2 095 мс. В сводке H1–H4 — «да» (без лимита 1,23 тела на клиента при C = 10). Отладочный прогон с вариантом «до» (--concurrency 10 --repeats 1): образ f894040 собран, при 10 × 10 MiB «до» — 324,5 MiB, 2,20 тела на загрузку, «без лимита» — 1,22. Это не evidence: метка — в 10.3.

  • 8.6 Регресс bench/: make bench_quick, bench_restore_quick, bench_failover_quick, bench_rollout_quick — код 0; в паспортах — буфер приёма реплики. Проверка — коды и паспорта.

    Все четыре — код 0 (bench_quick 18/18, bench_failover_quick 4/4, bench_rollout_quick — замена 12,6 с без ошибок; «stale POST 500» в bench_restore_quick — как в закоммиченных метках restore). В паспортах — stand.api_tcp_rmem 4096 131072 524288 и docker.kernel 7.0.14-linuxkit. Попутно исправлено: сэмплер оставлял анонимный volume на каждый запуск (design, «Уточнения apply», п. 10).

9. Правила и документы

  • 9.1 Правила по design, решение 12:

    • api-contract.md — 429 и порядок проверок;
    • service-layer.md — места, буфер в PUT, порядок записи;
    • infra.md — upload_slots.py;
    • settings.md — [uploads]; B прежняя и почему;
    • docker.md — sysctls у api;
    • balancer.md — срок пути загрузки, http-error 400, tune.sndbuf.server, дренаж 90 с, цепочка;
    • bench.md — профиль uploads, исключение S3 у оркестратора, смена стенда для прежних профилей;
    • student-tests.md — третий API и тесты;
    • logging.md — новые поля и причины;
    • run-modes.md — консоль без sysctl.

    Проверка: правила не противоречат коду; grep -rn "DRAIN_TIMEOUT (12)\|12 с (> timeout server)" .claude/rules scripts пуст.

    Grep пуст (код 1). bench.md — ещё исправление сэмплера (-v).

  • 9.2 AGENTS.md:

    • вводный абзац — change upload-memory;
    • инвариант лабы 4 о памяти загрузок;
    • команды make bench_uploads, bench_uploads_quick, driver.py lb-upload-timeouts;
    • карта кода: upload_slots.py, [uploads], профиль и файлы bench/, evidence/uploads/.

    Проверка — чтение по таблице команд.

  • 9.3 PLAN.md, раздел ### upload-memory: решения apply по образцу прежних changes, ответ на вопрос 1, когда придёт. Строку этапа 4 сводной таблицы отмечает основная сессия при archive.

    Решения 13–18; вопрос 1 — без ответа, записано состояние и что поменяет ответ «503».

  • 9.4 make lint, make check, make validate PYTHON=.venv/bin/python — код 0.

    Все три — код 0; openspec validate upload-memory --strict — valid. На дереве (не evidence): make failure_checks — 37 passed за 254 с, журнал PostgreSQL без признаков аварии; make test_isolated — smoke PASS, student_test 192 passed, 5 skipped (реплики), 1 failed — ожидаемо test_exclusion_evidence_exists (6.2), сверка покрытия: 227 сценариев, 210 с тестами (45 — проверки отказов), 17 исключений.

10. Прогоны и evidence

  • 10.1 Commit кода (основная сессия, после подтверждения). Затем на рабочем стенде make rolling_update и docker compose up -d --force-recreate haproxy (design, Migration Plan). Проверка:

    • make test;
    • make student_test через LB: ожидаемо красный только test_exclusion_evidence_exists (6.2);
    • make test-persistence ACTION_SCRIPT=scripts/restart.sh;
    • make test-failover ACTION_SCRIPT=scripts/stop-one.sh для обеих реплик;
    • make s3_check.
  • 10.2 Гипотезы H1–H4 (design, решение 10) — в REPORT.md, раздел загрузок, отдельным commit до первого прогона метки (bench.md, COURSE.md). Проверка: в git log commit гипотез раньше метки.

    Текст гипотез и методики — в REPORT.md, «Одновременные загрузки: гипотезы (change upload-memory)» (apply, 2026-10-21); commit — основная сессия, задача не закрыта до него.

  • 10.3 make bench_uploads после проверки хоста (bench.md, «Результаты»; рабочий стенд — make stop), затем commit метки. Проверка:

    • паспорт без host_warnings;
    • ячейки «с лимитом» без oom и 5xx;
    • «до» и «без лимита» на 40 × 10 MiB — oom.

    Расхождение с гипотезой — не повод править гипотезу: вывод в REPORT.md.

  • 10.4 driver.py lb-upload-timeouts → evidence/uploads/lb-timeouts.md. Две медленные загрузки (~20 с, по одной на реплику) во время make rolling_update → evidence/uploads/rollout-upload.md: обе 201, строки дренажа (спек load-balancing, «Загрузка во время дренажа»).

  • 10.5 После commit метки — make failure_checks, make test_isolated, make student_test через LB, все зелёные. Выводы — в evidence/tests/ (failure-checks.md, student-test-lb.md, файл test_isolated). Проверка: test_exclusion_evidence_exists зелёный.

  • 10.6 REPORT.md (design, решение 12):

    • раздел «Память и сроки загрузки» с формулами и B;
    • результаты и выводы по H1–H4 из summary.md метки;
    • строки таблицы доказательств уровня «4» вместо TODO (upload-memory …);
    • обновлённые «Ограничения»;
    • вопрос 1 в «Согласованиях», если ответ пришёл.

    Проверка: числа совпадают со сводкой метки, ссылки на evidence существуют.