20 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 при прогоне.
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— ошибка с именем поля.
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, второй — через срок. После отмены ожидающей задачи и после исключения внутри контекста место снова свободно. - места нет и ожидающих уже
-
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и тип в сервисе. -
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).
- после проверок членства,
-
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, «Параметры загрузок по умолчанию»).
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 в образе 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и стенда отказов. -
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. -
5.3
scripts/rolling-update.sh:ROLLOUT_DRAIN_TIMEOUTпо умолчанию 90 с, комментарий: «большеtimeout serverпути загрузки и наибольшей длительности загрузки». Проверка:make rolling_updateна рабочем стенде — код 0, дренаж каждой реплики — секунды. -
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есть «Одновременные загрузки реплики». - 6.2
spec_coverage.py,EXCLUDED:attachments«Одна копия тела при записи в S3» и «Память не растёт с числом загрузок». Способ —make bench_uploads→evidence/uploads/<метка>/summary.md. Проверка:test_coverage.pyзелёный. До commit меткиtest_exclusion_evidence_existsожидаемо красный и называет оба сценария — записать это в tasks при прогоне.
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). - временная сеть, 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).
-
8.2 Тела PNG ~1 MiB и ~10 MiB из шума (
random.Random(seed), stdlib), размеры и SHA-256 в паспорте. Проверка:--selftest: размер ≤ 10 485 760, два запуска дают одни байты;- разовая проверка в образе API: тела принимает
inspect_image(самbench/srcне импортирует).
-
8.3
bench/k6/uploads.js:constant-vus, разгон и окно, тело из смонтированного файла, Bearer изlib.js; на 429 — паузаRetry-After, на прочие ошибки — 1 с; строка на запрос в файл консоли. Проверка: число строк = итерации из итога k6, как вfailover. -
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 ниже пика старта реплики. - сброс
-
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 видны в сводке. -
8.6 Регресс
bench/:make bench_quick,bench_restore_quick,bench_failover_quick,bench_rollout_quick— код 0; в паспортах — буфер приёма реплики. Проверка — коды и паспорта.
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пуст. -
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. -
9.4
make lint,make check,make validate PYTHON=.venv/bin/python— код 0.
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 гипотез раньше метки. -
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 существуют.