27 KiB
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)—coderate_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(HEADfc1524d): 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→ 429ErrorCode.RATE_LIMITEDс заголовкомRetry-Afterиз константы (рядом сCHALLENGES),UploadTimedOut→ 400invalid_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); после отмены ожидающей, после исключения и после отмены уже разбуженной ожидающей место сразу свободно,_value1, ожидающих 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_concurrent4,uploads_max_waiting16,uploads_wait_timeout_seconds5.0,uploads_body_timeout_seconds30.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/удалены): прежний путь (PUTbytes) — пик над базой 2,31 тела; новый (тот жеBytesIOпослеdel) — 1,19 тела в трёх загрузках подряд; SHA-256 всех объектов совпал.make testи тесты вложений — вmake test_isolated(9.4). - скрипт в scratchpad в образе API против S3 стенда:
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(так же запускают APImake 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.cfgf894040(git show f894040:infra/haproxy/haproxy.cfgво временный файл, аргумент--config).Прогон на дереве (~33 с, пять случаев параллельно): текущий
haproxy.cfg— код 0 (201 за 12,06 и 12,13 с; 504 другого пути за 10,01 с; 504 пути загрузки за 30,12 с; 400application/jsonза 30,02 с). Конфигурацияf894040(git archive … | tar -xв scratchpad) — код 1: 502 за 10,23 с, 504 за 10,13 и 10,13 с, 400text/html. Временные сети и контейнеры убраны, volumes те же. Решения сверх design — design, «Уточнения apply», п. 8. - временная сеть, HAProxy закреплённого образа с
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; в образе APIinspect_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_quick18/18,bench_failover_quick4/4,bench_rollout_quick— замена 12,6 с без ошибок; «stale POST 500» вbench_restore_quick— как в закоммиченных меткахrestore). В паспортах —stand.api_tcp_rmem4096 131072 524288иdocker.kernel7.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/.
Проверка — чтение по таблице команд.
- вводный абзац — change
-
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_test192 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 logcommit гипотез раньше метки.Текст гипотез и методики — в
REPORT.md, «Одновременные загрузки: гипотезы (changeupload-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 существуют.