Files
mtusi2026lab4/openspec/changes/upload-memory/tasks.md
T
2026-10-21 23:21:42 +03:00

20 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 при прогоне.

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 — ошибка с именем поля.

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 и тесты вложений зелёные.

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.cfg f894040 (git show f894040:infra/haproxy/haproxy.cfg во временный файл, аргумент --config).

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/.

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

  • 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 log 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 существуют.