314 lines
20 KiB
Markdown
314 lines
20 KiB
Markdown
# 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
|
||
существуют.
|