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

314 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
существуют.