From 6cab9d3c413b31d76b0b4175f246bc152bfd1a5d Mon Sep 17 00:00:00 2001 From: roman Date: Thu, 22 Oct 2026 00:23:37 +0300 Subject: [PATCH] feat: bound upload memory with per-replica slots and a body deadline Co-Authored-By: Claude Opus 5.5 --- .claude/rules/api-contract.md | 27 +- .claude/rules/balancer.md | 44 +- .claude/rules/bench.md | 74 ++ .claude/rules/docker.md | 10 + .claude/rules/infra.md | 24 +- .claude/rules/logging.md | 16 +- .claude/rules/run-modes.md | 6 +- .claude/rules/service-layer.md | 36 +- .claude/rules/settings.md | 30 +- .claude/rules/student-tests.md | 51 +- .claude/skills/run-mtusi-messenger/SKILL.md | 2 + .claude/skills/run-mtusi-messenger/driver.py | 443 +++++++++ .gitignore | 2 + AGENTS.md | 72 +- KNOWN_ISSUES.md | 23 + Makefile | 18 + PLAN.md | 36 + bench/bench.compose.yml | 15 +- bench/bench.env | 4 +- bench/k6/uploads.js | 102 ++ bench/run.py | 597 +++++++++++- bench/sampler.sh | 94 ++ bench/uploads.py | 974 +++++++++++++++++++ config_example.toml | 14 + docker-compose.yml | 8 + evidence/tests/failure-checks.md | 48 + infra/haproxy/haproxy.cfg | 28 +- openspec/changes/upload-memory/design.md | 88 ++ openspec/changes/upload-memory/tasks.md | 179 +++- openspec/specs/api-conventions/spec.md | 15 +- openspec/specs/attachments/spec.md | 130 ++- openspec/specs/load-balancing/spec.md | 91 +- openspec/specs/load-benchmark/spec.md | 150 ++- openspec/specs/service-configuration/spec.md | 48 + openspec/specs/storage-consistency/spec.md | 13 +- openspec/specs/student-tests/spec.md | 15 +- scripts/rolling-update.sh | 9 +- src/api/dependencies.py | 5 +- src/api/errors.py | 19 +- src/config/settings.py | 21 + src/core/exceptions/__init__.py | 4 + src/core/exceptions/attachment.py | 13 + src/core/repos/attachment_object.py | 7 +- src/core/services/attachment.py | 126 ++- src/infra/s3/client.py | 17 +- src/infra/upload_slots.py | 78 ++ src/main.py | 4 + src/utils/constants.py | 5 + student-tests/conftest.py | 21 +- student-tests/contract.py | 11 + student-tests/images.py | 13 + student-tests/run_failures.py | 41 +- student-tests/spec_coverage.py | 16 + student-tests/test_attachments.py | 53 + student-tests/test_failures.py | 352 ++++++- 55 files changed, 4133 insertions(+), 209 deletions(-) create mode 100644 bench/k6/uploads.js create mode 100644 bench/uploads.py create mode 100644 src/infra/upload_slots.py diff --git a/.claude/rules/api-contract.md b/.claude/rules/api-contract.md index 705e7293..39dd1db5 100644 --- a/.claude/rules/api-contract.md +++ b/.claude/rules/api-contract.md @@ -80,11 +80,17 @@ FastAPI 0.141 из `uv.lock`: | 409 | `conflict` | `username` занят; с лабы 3 — тот же `Idempotency-Key` с другим телом сообщения | | 413 | `payload_too_large` | с лабы 4: тело загрузки больше 10 MiB (по `Content-Length` или счётчику) или изображение больше 40 млн пикселей (`PayloadTooLarge`) | | 415 | `unsupported_media_type` | с лабы 4: `Content-Type` не PNG/JPEG, содержимое не PNG/JPEG, подмена MIME, повреждённое изображение (`UnsupportedMediaType`) | +| 429 | `rate_limited` | с change `upload-memory`: места загрузки процесса заняты — очередь ожидания полна или место не освободилось за срок (`UploadsBusy`); всегда с `Retry-After: 1` (`UPLOAD_RETRY_AFTER_SECONDS`, таблица `RETRY_AFTER` в `errors.py`) | | 500 | `internal_error` | необработанное исключение, без деталей; с лабы 4 ещё у готового вложения нет объекта в S3 или он другого размера (`AttachmentContentMissing`, причина — `error` в журнале) | | 503 | `unavailable` | недоступен Postgres или хранилище сессий: ограниченная ошибка вместо 500 (`infra.md`); с лабы 4 — недоступен S3 на путях байтов вложений | -`429` в схеме есть, но обязательной причины для него нет. Для 429 нужен -`Retry-After`. `DELETE /auth/sessions/current` отвечает 204 без тела. +`429` контракт описывает как ограничение частоты запросов и требует +`Retry-After` — положительное целое. У нас 429 — только у загрузки, когда +заняты места процесса (design change `upload-memory`, решение 2). Места +ограничивают одновременность, а не частоту: трактовка — вопрос 1 +преподавателю (`PLAN.md`, `### upload-memory`). До ответа — 429, ответ +«503» меняет строку `DOMAIN_ERRORS`, сценарии и тесты, но не подход. +`DELETE /auth/sessions/current` отвечает 204 без тела. - Время — RFC 3339 UTC с `Z`, назначает сервер. Формат отдавать явно через `src/utils/utc.py`, а не полагаться на сериализацию по @@ -273,9 +279,20 @@ ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), hook — - Порядок проверок загрузки: 401 → 400 (`chat_id`, `filename`, их проверяет FastAPI после зависимостей) → 404 (членство) → 415 (`Content-Type`: тип до `;`, без регистра) → 413 (`Content-Length`) → - 413 (счётчик прочитанного) → 415/413 (содержимое: сигнатура и подмена - MIME, целостность, пиксели). Тело не читается до пройденных 1–5. - Пустое тело — 415. + 429 (место загрузки, с change `upload-memory`) → тело: 413 (счётчик + прочитанного), 400 (тело не пришло за `[uploads] + body_timeout_seconds` — `UploadTimedOut`, или обрыв — + `UploadInterrupted`) → 415/413 (содержимое: сигнатура и подмена MIME, + целостность, пиксели). Тело не читается до пройденных 1–6; отказ на + 1–5 места не ждёт и не занимает (посторонний и заведомо большое тело не + вытесняют живые загрузки). Пустое тело — 415. +- Места загрузки (спек `attachments`, «Одновременные загрузки реплики»; + `service-layer.md`): `[uploads] max_concurrent` (4) на процесс, очередь + до `max_waiting` (16) по порядку прихода, ожидание не дольше + `wait_timeout_seconds` (5 с); очередь полна — 429 сразу, срок вышел — + 429 по сроку. Место держится до ответа. LB 429 не повторяет, повтор — + клиент после `Retry-After`. Ни строки, ни объекта у 429 и у 400 по + сроку тела нет. - Лимиты — константы `ATTACHMENT_MAX_BYTES` (10 485 760) и `ATTACHMENT_MAX_PIXELS` (40 млн), не настройки (`settings.md`). Ровно лимит проходит. diff --git a/.claude/rules/balancer.md b/.claude/rules/balancer.md index 4d61da10..5c80187c 100644 --- a/.claude/rules/balancer.md +++ b/.claude/rules/balancer.md @@ -89,6 +89,19 @@ paths: `unavailable` (в перечислении кодов контракта нет отдельных для 502 и 504); `request_id` — `%[unique-id]`, он же в заголовке `X-Request-Id`. `X-Instance-Id` у них нет — контракт это допускает. + С change `upload-memory` так же `http-error status 400` с `code` + `invalid_request`: неверный запрос и клиент, замолчавший посреди тела + дольше `timeout client` (30 с; до change — HTML). 408 на медленные + заголовки (`timeout http-request`) HAProxy строит до потока запроса, + `http-error` его не меняет — остаётся HTML (`KNOWN_ISSUES.md`, + `REPORT.md`). +- `tune.sndbuf.server 262144` в `global` (change `upload-memory`, + решение 6): буфер отправки LB к реплике фиксирован, тело загрузки, + которое реплика не читает (ожидание места, отказ до тела), не копится + в памяти LB целиком — пик LB 51 MiB вместо 109 при 40 загрузках по + 10 MiB. Буфер приёма от клиента не ограничен (клиентам с большим RTT + нужен большой); `maxconn` на слот не ставится — менял бы поведение + всех путей лабы 3. - Статистика — страница `/stats` и `/stats;csv` (`stats show-legends`: адрес слота) во `frontend monitor` на `:8404`, там же `monitor-uri /lb/ready` (503, если готовых реплик нет). Только внутри сети @@ -121,6 +134,30 @@ paths: раньше. Поэтому `timeout connect` 500 мс, а не 1 с, и `redispatch 1`; - `timeout server` > `[database] request_timeout_seconds` + запас на KDF входа, иначе LB рвал бы ответ, который API ещё отдаст; +- путь загрузки вложения (change `upload-memory`, решение 7) — свой + `timeout server` 30 с: `http-request set-timeout server 30s if + METH_POST { path_reg ^/api/v1/chats/[^/]+/attachments$ }` в `backend + api`. Больше самого долгого молчания живой загрузки: до тела `2 × + request_timeout_seconds + [uploads] wait_timeout_seconds` = 17 с + (вход, членство, ожидание места), после тела — проверка (до ~4 с) + + tx1 6 + PUT 5 + tx2 6 + компенсация 5 ≈ 26 с. Тело ограничивают + `[uploads] body_timeout_seconds` (30 с) и `timeout client` (30 с). + Остальные пути — прежние 10 с: общий 30 с держал бы любой запрос к + зависшей реплике 30 с до 504, а замеры `failover` рассчитаны на 10. + Выражение повторяет путь ручки в `src/api/routers/v1/attachment.py`: + при смене префикса API менять вместе. Наибольшая длительность загрузки + U = 17 + 30 + 26 ≈ 73 с < `ROLLOUT_DRAIN_TIMEOUT` 90 с; + `graceful_shutdown_seconds` прежний (8 с): `stop-one.sh` и `docker + stop` — отказ, загрузка дольше 8 с обрывается, строку `pending` + убирает уборщик. Проверка поведения — `driver.py lb-upload-timeouts`: + временная сеть, HAProxy закреплённого образа с конфигурацией проекта + (`--config`) и заглушка реплики под именем `api` на образе API, пять + случаев параллельно (~35 с) — молчание 12 с до и после тела загрузки — + 201, 12 с на другом пути — 504 через ~10 с, 32 с на пути загрузки — + 504 через ~30 с, клиент молчит посреди тела — 400 в формате контракта, + `request_id` = `X-Request-Id`; код 1 при расхождении (на + конфигурации `f894040` — 502 и 504 через 10 с и 400 HTML). Evidence — + `evidence/uploads/lb-timeouts.md`; - таймаут проверки внутри `/health/ready` (2 с) < `timeout check` HAProxy (2,5 с, `infra.md`): медленный PostgreSQL даёт 503 от реплики, а не таймаут проверки. Уменьшать таймаут готовности ради быстрого @@ -243,8 +280,11 @@ Compose не умеет rolling update сам (это `update_config` Swarm). Ц down`) и включается через ≤ 1,5 с проверок. Срок `ROLLOUT_READY_TIMEOUT` (60 с). 5. Вывод старой из LB через runtime API (ниже): `drain` → запросов в - полёте (`scur`) 0, не дольше `ROLLOUT_DRAIN_TIMEOUT` 12 с (> `timeout - server`) → `maint` → `docker stop --timeout 10` (в строке скрипта — + полёте (`scur`) 0, не дольше `ROLLOUT_DRAIN_TIMEOUT` 90 с (с change + `upload-memory`; больше `timeout server` пути загрузки 30 с и + наибольшей длительности загрузки ≈ 73 с, иначе замена обрывала бы + живую загрузку; обычно дренаж — 0–2 с) → `maint` → `docker stop + --timeout 10` (в строке скрипта — время и код выхода: 0 — graceful, 137 — SIGKILL по сроку) → `docker rm` → адрес ушёл из слота (DNS, ≤ 10 с) → `ready`. 6. Шаги 3–5 для каждой старой. В конце — N реплик на новом образе, все diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index 7e4ac99e..a1044d75 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -98,6 +98,7 @@ change `s3-storage`, решение 9): старт стенда перечисл | `run.py` (профили `restore`, `restore_quick`), `k6/after_backup.js`, `k6/restore_check.js` | `make bench_restore`, `make bench_restore_quick` | тот же стенд без матрицы прогонов: backup под записью, восстановление в новое хранилище, сверка, RTO и потеря, кэш до и после `FLUSHALL` | | `run.py` (профили `failover`, `failover_quick`), `failover.py`, `resources.py`, `sampler.sh` (режим `scan`), `k6/failover.js`, `k6/retry.js` | `make bench_failover`, `make bench_failover_quick` | две реплики с лимитами рабочего стенда, постоянная интенсивность записи с ключом и чтения, каждая реплика в каждом режиме (`stop`, `kill`, `pause`) с возвратом: посекундная шкала, время обнаружения и восстановления, сверка записей, CPU и память каждого компонента по окнам фазы; результаты — `evidence/failover/<метка>/` | | `run.py` (профили `rollout`, `rollout_quick`), `rollout.py`, `resources.py`, `sampler.sh` (режим `scan`), `k6/failover.js`, `k6/retry.js`, `scripts/rolling-update.sh` | `make bench_rollout`, `make bench_rollout_quick` | две реплики с лимитами рабочего стенда на образе прежнего commit, та же постоянная нагрузка, посреди неё — поочерёдная замена на образ текущего checkout: посекундная шкала с ответами старых и новых реплик, шаги по каждой реплике, контейнеры, образы и ревизия схемы до и после, сверка записей, CPU и память каждого компонента по окнам замены; результаты — `evidence/rollout/<метка>/` | +| `run.py` (профили `uploads`, `uploads_quick`), `uploads.py`, `sampler.sh` (режим `peak`), `k6/uploads.js`, `k6/prepare.js` | `make bench_uploads [UPLOADS_LABEL=…]`, `make bench_uploads_quick` | память реплики при одновременных загрузках вложений (change `upload-memory`): одна реплика 1 CPU / 512 МБ без swap, S3 рабочего стенда, варианты «до» / «без лимита» / «с лимитом», тела PNG ~1 и ~10 MiB, 1 / 10 / 20 / 40 клиентов; пик `memory.peak` окна, OOM, ответы по кодам, загрузок/с и p50/p95/p99; результаты — `evidence/uploads/<метка>/` | | `run.py` (профили `scaling_*`), `scaling.py`, `sampler.sh`, `k6/mixed.js` | `make bench_scaling SERIES=a\|b\|pool\|ab\|db\|db4`, `make bench_scaling_quick`, `SERIES=db_quick` | серии трека 1: конфигурации реплик и лимитов, на каждую ячейку — свежий стенд, открытая модель, фиксированные уровни и поиск R* по SLO, посекундный сэмплер контейнеров, ВМ, LB и PostgreSQL; результаты — `evidence/bench/<метка>/` | | `plots.py` | `make bench_plots LABELS="…"` | графики SVG и сводка серий (R* от числа реплик, p95 от интенсивности, CPU по компонентам, точка насыщения) — `evidence/plots//` | | `compare.py` | `make bench_compare` | дельта двух меток стенда (ячейки матрицы или общие конфигурации серий), эффект или шум | @@ -148,6 +149,19 @@ change `s3-storage`, решение 9): старт стенда перечисл `failover` и `rollout` (с change `profile-resources`) — тот же сэмплер 0,25 CPU / 128 МиБ в режиме `scan` (`sample_resources`), k6 по-прежнему без лимита; +- **буфер приёма сокетов реплики** (с change `upload-memory`): `sysctls` + сервиса `api` из основного `docker-compose.yml` (`net.ipv4.tcp_rmem` + `4096 131072 524288`) действует и на `bench/`; значение — в паспорте + всех профилей (`stand.api_tcp_rmem`), ядро ВМ — `docker.kernel`. + Для прежних профилей это смена стенда, но запросы и ответы JSON меньше + начального буфера (128 KiB) — результаты не меняются; метки до change + поля в паспорте не имеют. Там же исправлено: контейнер сэмплера (образ + PostgreSQL) удаляется с `-v`, иначе каждый запуск оставлял анонимный + volume `/var/lib/postgresql`; +- **S3** — запускает только профиль `uploads`: образ, аргументы и + лимиты рабочего стенда (`BENCH_S3_*`, 1 CPU / 512 МБ, swap = память), + bucket `bench` (`bench.env`) и пользователи — тот же `s3-bootstrap`; + override `s3` нужен compose и в остальных профилях; - **PostgreSQL `max_connections`:** 100, как у образа (`-c max_connections` в override); у серий — из конфигурации ячейки, лимиты конфигурации в паспорте (`limits.<конфигурация>`); @@ -304,6 +318,59 @@ change `s3-storage`, решение 9): старт стенда перечисл `quick-rollout-*` — в `.gitignore`. Замер для отчёта — `make bench_rollout` после проверки хоста, рабочий стенд остановлен. +## Профиль загрузок (`uploads`) + +Спек `load-benchmark`, «Профиль загрузок»; design change `upload-memory`, +решение 10. Методика — поля `Profile` (`uploads_*`) в `run.py`, разбор без +docker — `bench/uploads.py` (`--selftest`). + +- **Стенд:** LB, одна реплика API 1 CPU / 512 МБ без swap (OOM-kill + виден, а не прячется в swap), PostgreSQL, Valkey, S3 и `s3-bootstrap` + (раздел выше); k6 без лимита. +- **Варианты:** «до» — образ `Profile.uploads_before` (`f894040`, + последний до change `upload-memory`; `git archive` → тег `bench-from`, + проверка commit до стенда — код 2, как у `rollout_from`, смена при + переходе в лабу 5 — так же); «без лимита» — образ checkout с + `UPLOADS__MAX_CONCURRENT=1000`, `UPLOADS__MAX_WAITING=0`; «с лимитом» — + образ checkout со значениями по умолчанию. Окружение варианта задаёт + override `.work/variant.compose.yml`, а не `BENCH_*`: иначе изменился + бы `stand.app_env` прежних профилей, и `bench_compare` отказал бы со + старыми метками. В паспорте — `app_env` по вариантам. +- **Тела:** PNG из шума RGB шириной 1024 (`random.Random(seed + высота)`, + stdlib): ~1 MiB (1 048 276 байт) и ~10 MiB (10 479 107 байт), не больше + 10 485 760; размеры и SHA-256 — в паспорте. Тело 10 MiB у `uploads` и + `uploads_quick` побайтно одно. +- **Прогон:** вариант × размер × C ∈ {1, 10, 20, 40} × повтор (3), круги + с перестановкой по зерну. Перед каждым — новый volume S3 с bootstrap, + новая реплика с окружением варианта, ожидание процесса и `UP` в LB, + одна разогревающая загрузка. PostgreSQL, пользователь и чат — один раз + на метку. Окно — `constant-vus` k6 (`k6/uploads.js`): C VU, 3 с + разгона и 20 с окна без пауз; на 429 — пауза `Retry-After`, на прочие + ошибки — 1 с; строка на запрос — в файл консоли. +- **Память:** сэмплер `peak` сбрасывает `memory.peak` реплики, S3 и LB + перед нагрузкой (после разогрева) и читает пик в конце; окно памяти — + весь прогон k6. Раз в 0,2 с — `memory.current`, `anon`, `sock`, + `oom_kill`. Ядро без сброса (< 6.12) — наибольшая выборка и + `peak_sampled`. Загрузок/с и перцентили — по загрузкам окна `[t0 + 3, + t0 + 23)`, ответы по кодам — за весь прогон, в том числе после OOM. +- **Пометки:** `oom` (реплика завершена ядром — результат варианта, не + сбой команды; следующий прогон на новой реплике), `host_swap`, + `peak_sampled`, `s3_down`. Блокировка `bench/.bench.lock`, отказ + занятой метки и остатков стенда — как у остальных профилей. +- **Результаты:** `evidence/uploads/<метка>/` — `meta.json` (раздел + `uploads`: commit «до», образы, тела, план, `app_env`), `runs.csv` + (строка на прогон: вариант, размер, C, повтор, память до окна, пик + окна, пик старта, наибольшие `anon` и `sock`, `oom_kill`, код выхода и + `OOMKilled`, ответы по кодам, загрузок 201/с, p50/p95/p99, пики S3 и + LB, пометки), `summary.md` (медиана и min–max по ячейкам, сценарии + спеков, H1–H4 с итогом), `raw/<прогон>-k6.json`, `raw/<прогон>-peak.log`. + `quick-uploads-*` — в `.gitignore`. +- **Время:** полный профиль — 72 прогона, ~50 мин; `uploads_quick` — + «без лимита» и «с лимитом», 10 MiB, C ∈ {1, 10, 40}, один повтор, + ~4,5 мин. Замер для отчёта — `make bench_uploads` после проверки хоста, + рабочий стенд остановлен (`make stop`), гипотезы H1–H4 закоммичены + раньше метки. + ## Серии трека 1 (`scaling_*`) Доказательство уровня «5», трек 1 «Цена масштабирования» (design change @@ -416,6 +483,13 @@ change `s3-storage`, решение 9): старт стенда перечисл `` (design change `attachments`, «Уточнения apply», п. 9). Второе хранилище и его volume `Stand.stop()` удаляет до `compose down`; - ревизия `alembic_version` до и после замены (профиль `rollout`). +- Исключение для S3 стенда (профиль `uploads`, change `upload-memory`): + перед каждым прогоном оркестратор удаляет S3 (`kill`: volume всё равно + уходит), его volume `mtusi-bench_s3_data`, поднимает S3 и `s3-bootstrap` + заново. К bucket и объектам он не обращается. Счётчики памяти cgroup + реплики, S3 и LB читает сэмплер `peak` (`--user 0`, cgroupfs на + запись, `--network none`): сброс `memory.peak` через свой дескриптор — + управление счётчиком, а не приложением. Схему меняет не оркестратор, а миграция приложения, которую запускает `scripts/rolling-update.sh`, — как на рабочем стенде. diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index e694c55a..309b4762 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -135,6 +135,16 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t «4»). Секреты S3 по сервисам — раздел S3 ниже, уборщик — раздел «Уборщик» ниже. Healthcheck образа проверяет `APP__PORT`; `stop_grace_period: 10s`; + с change `upload-memory` — `sysctls: net.ipv4.tcp_rmem: "4096 131072 + 524288"`: буфер приёма сокетов реплики до 512 KiB, а не до 32 MiB ВМ + Docker Desktop. Ядро копит недочитанное тело (ожидание места загрузки, + отказ до тела) в буфере сокета, и он считается памятью контейнера + (`sock` в `memory.stat`): при 40 загрузках по 10 MiB `sock` реплики + 17 MiB вместо 134. Параметр сетевого пространства контейнера — его + получают все контейнеры сервиса `api`, в том числе `docker compose + run` (`make test_isolated`, стенд отказов) и `bench/`; новые реплики — + после `make rolling_update`. Скорость не страдает: RTT в сети Docker — + доли миллисекунды. В консоли sysctl нет (`run-modes.md`); `restart: unless-stopped`; лимиты CPU/RAM (`deploy.resources.limits`) у всех сервисов — override стендов (`bench/`) задаёт лимиты в той же форме: `cpus` / `mem_limit` рядом с diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 04df4ad4..9cdf9165 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -52,6 +52,20 @@ paths: aiobotocore создаёт `start()` в lifespan (модели botocore — при старте, сети нет), закрывает `aclose()` рядом с `cache.aclose()`. Ниже — правила клиента. +- `upload_slots.py` (change `upload-memory`, design, решение 1) — класс + `UploadSlots` и глобал `upload_slots` из `settings.uploads` (при + импорте, как `_limiter` в `password.py`): места загрузок процесса на + `asyncio.Semaphore` (ожидающие — по порядку прихода), счётчик + ожидающих и срок ожидания. Контекст `slot()`: места нет и ожидающих + уже `max_waiting` — сразу `UploadsBusy`; иначе ожидание не дольше + `wait_timeout_seconds` (`asyncio.timeout`), не вышло — `UploadsBusy`; + отдаёт ожидание в мс, место освобождает в `finally`. Отмену во время + ожидания `Semaphore` обрабатывает сам: место, отданное отменённому + ожидающему, переходит следующему. Это допуск к обработке, а не данные: + места считает каждая реплика, корректность ответов от них не зависит + (`api-layer.md`). Глобал импортирует только `dependencies.py`, + уборщик его не создаёт. Отвергнуты — очередь в LB, `--limit-concurrency` + uvicorn, места по байтам, счётчик в Valkey или PostgreSQL (design). - `early_stop.py` — ранний обработчик SIGTERM и SIGINT процесса (`install(process_name)`, `disarm()`, `write_record`): только stdlib, ни настроек, ни логгера, ни других модулей `src`; клиентом хранилища @@ -166,7 +180,15 @@ paths: - **срок на вызов** — `asyncio.timeout([s3] timeout_seconds)` (5 с, меньше `timeout server` HAProxy), у `open` — ещё и на каждый блок чтения тела; `connect_timeout_seconds` и `read_timeout` botocore — - из `[s3]`; пул aiohttp — `[s3] max_connections`; + из `[s3]`; пул aiohttp — `[s3] max_connections`. Отдельного срока PUT + по размеру нет: места API ограничивают одновременные PUT (4 на + реплику, 12 при замене), p95 при 12 — 1,6–1,9 с (design change + `upload-memory`, решение 8), а больший срок удлинил бы границу B + уборщика; + - `put(key, body, *, size, content_type)` — тело потоком с `read`, + `seek`, `tell` (сервис передаёт свой `BytesIO`), `size` — в журнал + вызова. Не `bytes`: botocore обернул бы его в `BytesIO` с общим + буфером, и aiohttp скопировал бы тело при `getbuffer()`; - адресация `path`: `bucket.s3` Docker DNS не разрешает; простаивающее соединение aiohttp закрывает через `S3_KEEPALIVE_TIMEOUT_SECONDS` (15 с), раньше шлюза (120 с); diff --git a/.claude/rules/logging.md b/.claude/rules/logging.md index d0328fe9..03a23d48 100644 --- a/.claude/rules/logging.md +++ b/.claude/rules/logging.md @@ -133,14 +133,20 @@ paths: подпись), «Object storage denied access» (`AccessDenied`) и «Object storage bucket is missing» (`NoSuchBucket`), `debug` на успешный вызов; текста исключения botocore в записи нет. Запись «Started API» — - с `s3_host`, `s3_port`, `s3_bucket`; пустые ключи — `warning`. + с `s3_host`, `s3_port`, `s3_bucket`; пустые ключи — `warning`. С change + `upload-memory` в ней же `uploads_max_concurrent`, + `uploads_max_waiting`, `uploads_wait_timeout_seconds`, + `uploads_body_timeout_seconds` (спек `service-configuration`, + «Параметры загрузок»). - С лабы 4 — `filename` вложений (его выбирает пользователь) и байты изображений. Модуль `attachment_service` пишет `info` «Uploaded attachment» (`attachment_id`, `chat_id`, `size_bytes`, - `content_type`, `width`, `height`, `duration_ms`), `info` «Rejected - attachment» с `reason` (`type`, `declared_size`, `size`, `content`, - `content_mismatch`, `damaged`, `pixels`, `interrupted`), `chat_id` и - `filename_length`, `error` «Attachment content is missing» / «…size + `content_type`, `width`, `height`, `waited_ms`, `duration_ms`), `info` + «Rejected attachment» с `reason` (`type`, `declared_size`, `size`, + `content`, `content_mismatch`, `damaged`, `pixels`, `interrupted`; с + change `upload-memory` — `busy` с `waited_ms`: места заняты, 429, и + `body_timeout` с `size` прочитанного: тело не пришло за срок, 400), + `chat_id` и `filename_length`, `error` «Attachment content is missing» / «…size differs» с `attachment_id` и `object_key`. С change `upload-consistency`: `warning` «Attachment upload left pending» с `attachment_id` и `step` (`put`, `ready`, `commit`), `info` «Deleted diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index b5dfe716..5701771b 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -90,7 +90,11 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n `docker stop`, профиль `failover`) имитирует отказ, исключение для одиночного 502 к ней по-прежнему относится. - Console-режим — один процесс на `127.0.0.1` без LB, для разработки и - скилла `run-mtusi-messenger`. Проверки лабы 3 (≥2 реплики, failover, + скилла `run-mtusi-messenger`. Места загрузок (`[uploads]`) и срок тела + в консоли работают, а ограничения буфера приёма сокетов (`sysctls` у + `api` в compose, `docker.md`) нет: процесс на macOS, ожидающая + загрузка держит в буфере ядра больше 512 KiB — ограничение в + `REPORT.md` (design change `upload-memory`, решение 6). Проверки лабы 3 (≥2 реплики, failover, гонка через разные реплики) — только на стенде compose через LB. ## Уборщик (с лабы 4) diff --git a/.claude/rules/service-layer.md b/.claude/rules/service-layer.md index d4d3943b..852c7f19 100644 --- a/.claude/rules/service-layer.md +++ b/.claude/rules/service-layer.md @@ -68,19 +68,37 @@ paths: - лог: `Created message` или `Replayed message` с `message_id` и `replayed`, без ключа и текста (`logging.md`). - Вложения (лаба 4, design change `attachments`, решения 1, 5–9): - - `AttachmentService(db_scope, cache, storage)` — отличие от правила - выше: вместо `db_session` фабрика короткой сессии на шаг + - `AttachmentService(db_scope, cache, storage, slots)` — отличие от + правила выше: вместо `db_session` фабрика короткой сессии на шаг (`db_session_scope`), каждый шаг с БД — свой `async with self.db_scope()`, без вложенных: соединение пула не занято передачей тела, на запрос не больше одного соединения. `storage` — глобал - `object_storage` из зависимости; + `object_storage` из зависимости, `slots` — глобал `upload_slots` + (места загрузок процесса, `infra.md`; в сервисе только тип под + `TYPE_CHECKING`); - порядок записи загрузки: проверки (членство, `Content-Type`, - `Content-Length`) → чтение тела со счётчиком → структура - изображения и SHA-256 одним `anyio.to_thread.run_sync` → строка - `pending` с `object_key` (commit) → PUT (`attachment_object_repo`) → - `_mark_ready` (commit) → DTO. Отказ S3 или БД после `pending` — 503, - строка остаётся до уборщика. Отклонённая до `pending` загрузка - ничего не пишет; + `Content-Length`) — без места → `async with self.slots.slot()` (429 + `UploadsBusy`: `info` «Rejected attachment», `reason=busy`, + `waited_ms`) → внутри `_store` весь остальной путь до ответа: чтение + тела со счётчиком под `asyncio.timeout([uploads] + body_timeout_seconds)` (истёк — `UploadTimedOut`, 400) → структура + изображения и SHA-256 одним `anyio.to_thread.run_sync` над + `buffer.getvalue()` → `size = len(data)`, `del data` → строка + `pending` с `object_key` (commit) → `buffer.seek(0)`, PUT этим же + `BytesIO` (`attachment_object_repo.put_original(..., body=buffer, + size=size)`) → `_mark_ready` (commit) → DTO; место освобождается при + выходе из контекста, в том числе после компенсации и при отмене. + Отказ S3 или БД после `pending` — 503, строка остаётся до уборщика. + Отклонённая до `pending` загрузка ничего не пишет (design change + `upload-memory`, решения 1–5); + - одна копия тела: `del data` до PUT обязателен. Пока жива ссылка на + `bytes` из `getvalue()`, буфер `BytesIO` общий, и `getbuffer()` + aiohttp при PUT копирует тело целиком — два тела на загрузку вместо + одного (проба: 2,3 тела против 1,19). `bytes` в `put` не передавать: + botocore оборачивает его в `BytesIO` с общим буфером, и копия та же; + - ожидание места, тело и проверка — до `created_at` строки `pending`: + граница живой загрузки уборщика (B = 17 с) от очереди и медленного + клиента не растёт (`settings.md`, «Уборщик»); - компенсация (design change `upload-consistency`, решение 1) — только удаление объекта и только при известном исходе, в `_mark_ready`: флаг «COMMIT отправлен» ставится прямо перед `commit()` и только при diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index 32c5840a..46129797 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -15,7 +15,7 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда - `src/config/settings.py`: `Settings(BaseSettings)` из секций-`BaseModel` (`App`, `Database`, `Auth`, `Cache` — Valkey, `S3`, `Idempotency`, - `Cleaner`). + `Uploads`, `Cleaner`). Экземпляр один — `settings` на уровне модуля. Импорт везде `from src.config import settings`. Второй `Settings()` не создавать, поля в рантайме не менять. @@ -173,6 +173,34 @@ make env_setup»). Значение уже существующей переме `S3__SECRET_ACCESS_KEY`), моста в консоль нет — консольного уборщика нет, разовый проход идёт в контейнере. +### Загрузки (с change `upload-memory`) + +`[uploads]` (класс `Uploads`, design change `upload-memory`, решения 1–4 +и 9) читает процесс API: `max_concurrent` (int, `ge=1`, 4), +`max_waiting` (int, `ge=0`, 16; 0 — без очереди, сразу 429), +`wait_timeout_seconds` (float, `gt=0`, 5), `body_timeout_seconds` +(float, `gt=0`, 30). Значения — в `config.toml`, разовая подмена — +`UPLOADS__*` (стенд отказов — 1 / 1 / 1 / 2 у третьего API, профиль +`uploads` — 1000 / 0 у варианта «без лимита»). Настройки, а не +константы: у установок разный лимит памяти. Неверное значение — +ошибка проверки настроек с именем поля, сервис не стартует. «Started +API» называет все четыре. + +- `max_concurrent` 4 — бюджет реплики 512 МБ: база ~105 MiB + хэши + паролей 4 × 64 MiB + места до ~90 MiB при 40 клиентах ≈ 450 MiB; при + 8 местах — ~530 MiB; +- `wait_timeout_seconds` 5 — молчание реплики до тела `2 × [database] + request_timeout_seconds + wait_timeout_seconds` = 17 с меньше `timeout + server` LB пути загрузки (30 с, `balancer.md`); при смене любого из + них пересчитать цепочку; +- `body_timeout_seconds` 30 — один срок на всё тело с момента, как + загрузка заняла место (не срок простоя: клиент по байту раз в 29 с + держал бы место вечно). Наибольшая длительность загрузки 17 + 30 + 26 + ≈ 73 с < `ROLLOUT_DRAIN_TIMEOUT` (90 с); +- **граница B уборщика прежняя** (17 с): ожидание места, тело и + проверка идут до `created_at` строки `pending`, а сроки tx1, PUT и tx2 + не менялись. Поэтому `[uploads]` в проверку grace уборщика не входит. + ### Уборщик (с лабы 4) `[cleaner]` (класс `Cleaner`, design change `upload-consistency`, diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 13cd5f2d..69e3c242 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -169,6 +169,42 @@ paths: `test_upload_outlives_grace` на том коде зелёные (ветки были верны) и красные на временных регрессиях — компенсация на любой сбой (объекта нет сразу после 503) и возврат `RuntimeError` (500); +- с change `upload-memory` (design, решение 11) — места загрузки и срок + тела: + - `test_attachments.py::test_concurrent_uploads` («Загрузки в + пределах лимита», любой стенд): 10 участников одного чата за + `threading.Barrier`, у каждого свой `Api` (срок 30 с) и свой PNG из + шума ~1 MiB (`images.png_noise(seed=…)`); все 201, `id` разные, + загрузки пересекались по времени, каждое скачивается побайтно; + - `contract.py`: код 429 — `rate_limited`, `assert_error(resp, 429)` + требует `Retry-After` — положительное целое; + - третий API стенда отказов — «узкий по загрузкам» + (`<проект>-api-uploads`, `UPLOADS_ENV` в `run_failures.py`: 1 место, + 1 в очереди, ожидание 1 с, срок тела 2 с), тестам — + `FAULT_UPLOADS_BASE_URL` (фикстура `uploads_api`, срок клиента 30 с) + и `FAULT_UPLOADS_ENV`; тесты сверяют, что стенд запущен с этим + окружением (`assert_uploads_stand`). Место держит загрузка A + (`held_slot`): генератор тела отдаёт половину и ждёт + `threading.Event`; A отпускается до истечения её срока тела (2 с); + - тесты (`fault`): `test_upload_slots_busy` (B ждёт, C сразу 429 < 0,5 + с, B — 429 не раньше 1 с, `Retry-After` ≥ 1; из трёх загрузок новая + строка и объект — только у A), `test_rejections_before_queue` (при + полной очереди 404 постороннему, 413 по `Content-Length` 30 MiB и 415 + по `Content-Type` — быстрее срока ожидания и раньше 429 ожидавшей), + `test_upload_waits_for_slot` (B ждёт и получает 201, `B.created_at > + A.updated_at` — сценарий `storage-consistency`), + `test_slot_released_after_failures` (413 по счётчику, 415 по + содержимому, 400 по сроку тела, обрыв, 503 при остановленном S3 — + после каждого `sample.png` получает 201 быстрее срока ожидания), + `test_slow_body` (тело частями дольше срока — 400 «Upload body was + not received in time», ни строки, ни объекта; мелкими частями в + срок — 201 с тем же SHA-256); + - красный прогон на `f894040`: упали все пять — у прежнего кода нет ни + мест, ни срока тела (`evidence/tests/failure-checks.md`); + - сценарии памяти «Одна копия тела при записи в S3» и «Память не + растёт с числом загрузок» — исключения сверки: `make bench_uploads` → + `evidence/uploads/baseline/summary.md` (`bench.md`, профиль + `uploads`); - исключения сверки: «Принявшая реплика остановлена» — `driver.py attachment-failover` → `evidence/attachments/failover.md`; «Байты не в БД и не на диске API» — `driver.py attachment-storage` → @@ -236,12 +272,17 @@ paths: healthcheck PostgreSQL проверяет служебную базу `postgres` (иначе каждая проверка — сессия в базе приложения и шум счётчика `db-sessions`); - - два API на свободных портах `127.0.0.1`: обычный (`BASE_URL`; с + - три API на свободных портах `127.0.0.1`: обычный (`BASE_URL`; с лабы 4 в окружении `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1` — `LIMITS_ENV`, тест получает их в `FAULT_LIMITS_ENV` и грузит - `sample.png`: лимиты — константы, спек `service-configuration`) и + `sample.png`: лимиты — константы, спек `service-configuration`), «тесный» (`FAULT_TIGHT_BASE_URL`: сроки сессии и ключа - идемпотентности 2 с, пул 1, короткие таймауты); + идемпотентности 2 с, пул 1, короткие таймауты) и с change + `upload-memory` «узкий по загрузкам» (`FAULT_UPLOADS_BASE_URL`, + `UPLOADS_ENV` → `FAULT_UPLOADS_ENV`: 1 место, 1 в очереди, ожидание + 1 с, срок тела 2 с); без любого из трёх адресов `pytest -m fault` + останавливается до первого теста; при падении печатаются журналы + всех трёх; - уборщик (с лабы 4): после bootstrap — `up -d --no-deps cleaner` с grace 20 с и интервалом 1 с из `failures.compose.yml` (`CLEANER__*`, `restart: "no"`: падение не прячется за @@ -249,8 +290,8 @@ paths: compose и передаёт тестам (`FAULT_CLEANER_GRACE_S`, `FAULT_CLEANER_INTERVAL_S`) и строкой `start cleaner: grace … s, interval … s` в вывод. При падении печатается и журнал уборщика. - Прогон — ~4 мин (32 проверки, pytest ~220 с; до `upload-consistency` - ~70 с); + Прогон — ~5 мин (37 проверок, pytest ~255 с; до `upload-memory` — + 32 и ~220 с, до `upload-consistency` ~70 с); - `pytest -m fault`, затем журнал PostgreSQL стенда: сводка `postgres log: N lines, crash markers M; "too many clients" X, "administrator command" Y` после каждого прогона и ненулевой код при признаках diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 68369fd9..d54d1299 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -122,6 +122,7 @@ python3 $D stop | `attachment-failover [--mode stop\|kill]` | только стенд с LB: спек `attachments` «Принявшая реплика остановлена». Синтетические Алиса, Боб, Ева и чат; загрузка `tests/fixtures/sample.png` через LB (реплика A — `X-Instance-Id` ответа), сообщение со ссылкой, `scripts/stop-one.sh` с `TARGET_INSTANCE_ID=A` и `STOP_MODE`, Боб скачивает через LB (до 30 попыток), пока не ответит другая реплика: SHA-256 совпадает, метаданные равны ответу загрузки; Ева — 404 на метаданные и байты. В `finally` — `make replicas`, затем ожидание, пока LB снова видит все реплики `UP`. Печатает `docker compose ps` до и после и таблицу «шаг → ожидаемо → получено → реплика» без токенов. Код 1 при расхождении, без LB (порт консольного процесса драйвера) — код 2. Вывод — `evidence/attachments/failover.md` | | `attachment-storage` | только стенд с LB: спек `attachments` «Байты не в БД и не на диске API». Две загрузки fixture через LB; psql — колонки `attachments` и `message_attachments` (из `bytea` только 32-байтный `sha256`), `object_key` = `<база>/attachments//original` без `filename`; `weed shell fs.ls -l` — объект в bucket и его размер; анонимный GET ключа с `127.0.0.1:S3_OUT_PORT` — 403; скачивание участником — тот же SHA-256; `docker diff` каждой реплики — ни одного файла оригинала. Код 1 с названной проверкой, без LB — код 2. Вывод — `evidence/attachments/storage.md` | | `upload-consistency` | только стенд с LB: спеки `attachments` «Порядок записи» и `storage-consistency` (design change `upload-consistency`, решение 11). Синтетические Алиса, Боб и чат; готовое вложение R. Шаги: (1) `docker compose pause s3` → загрузка через LB — 503 за ~5 с → `unpause` в `finally`; новая строка `pending` по psql (`id`, статус, возраст, ключ); (2) триггер «фиксация `ready` падает» (SQLSTATE 08006) на рабочей базе только для уникального `filename` прогона → загрузка 503 → строка `pending`, объекта уже нет (компенсация), триггер снят (`finally`, и остаток прошлого прогона — в начале); (3) метаданные, байты и сообщение со ссылкой на обе строки — 404; (4) после grace прогона 30 с — `docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once`, его JSON-вывод; (5) psql и `weed shell fs.tree` (файлы `original`, а не каталоги) — ни строк, ни объектов обеих загрузок, объектов без строки под префиксом рабочей базы нет; R скачивается с тем же SHA-256. Таблица «проверка → ожидаемо → получено» без токенов и секретов; код 1 при расхождении, без LB — код 2. ~45 с. Вывод — `evidence/attachments/consistency.md` | +| `lb-upload-timeouts [--config F] [--image ТЕГ]` | без стенда (рабочий стенд и проекты compose не трогает): спек `load-balancing` «Загрузки через балансировщик» и «Ошибки балансировщика в формате контракта» (design change `upload-memory`, решение 7). `haproxy -c` конфигурации F (по умолчанию `infra/haproxy/haproxy.cfg`) в закреплённом образе LB из `docker-compose.yml`, затем временная сеть `mtusi-lbto-<метка>`: заглушка реплики на образе API (по умолчанию `mtusi-messenger:lab4`, asyncio stdlib) под сетевым именем `api` и HAProxy с F и `API_PORT=8080` на свободном `127.0.0.1`; ожидание `UP` заглушки по `/health/ready` через LB. Пять случаев параллельно, у каждого своё соединение и свой `case` в строке запроса: заглушка молчит 12 с до чтения тела загрузки 10 MiB и после него — 201 от заглушки; 12 с на `GET /api/v1/users/me` — 504 LB через ~10 с; 32 с на пути загрузки — 504 LB через ~30 с; клиент отправил половину тела и молчит — 400 LB через ~30 с (`timeout client`). Ошибки LB — `application/json`, ровно `{"error": {"code", "message", "request_id"}}`, `code` по статусу, `request_id` = `X-Request-Id`. Таблица «случай → ожидаемо → получено → время», код 1 при расхождении. Сеть и контейнеры (метка `mtusi.lb-upload-timeouts`) удаляются при любом исходе, в том числе по Ctrl+C, SIGTERM, SIGHUP. ~35 с. На `haproxy.cfg` до change (`git archive f894040 infra/haproxy/haproxy.cfg \| tar -x -C <каталог>`, `--config <каталог>/infra/haproxy/haproxy.cfg`) — код 1: 502 и 504 через 10 с на пути загрузки, 400 в HTML. Вывод — `evidence/uploads/lb-timeouts.md` | | `stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3]` | спек `graceful-shutdown` «Остановка во время старта»: контейнеры образа (по умолчанию `mtusi-messenger:lab4`) с лимитами реплики (1 CPU / 512 МиБ без swap), без сети и `config.toml`; `docker stop --timeout 10` через паузу после `docker run` и сразу по строке «Started server process». По потоку `docker events` и журналу: «сигнал через», время `docker stop`, «выход после сигнала», код выхода, этап (`import` / `server-start` / `running`), кто остановил (`early` / `uvicorn`). Код 0 — каждая попытка с кодом 0 и `docker stop` ≤ 1 с, есть `import`, остановленный ранним обработчиком, и `running`. Проекты compose не трогает, свои контейнеры удаляет по метке `mtusi.stop-at-start`. Вывод — `evidence/failover/stop-at-start.md` | | `stop` | SIGTERM всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает | | `all` | всё подряд (`student` — если есть `student-tests/`), `stop` в `finally` | @@ -172,6 +173,7 @@ python3 $D --port 8080 auth-storage # Argon2id в users, SHA-256 ток python3 $D --port 8080 attachment-failover --mode kill # реплика, принявшая файл, убита: скачивание через другую, тот же SHA-256 python3 $D --port 8080 attachment-storage # байты только в приватном bucket: схема, ключ, объект, аноним 403, docker diff python3 $D --port 8080 upload-consistency # S3 заморожен и сбой ready: 503, pending не видны, компенсация, cleaner --once всё убрал +python3 $D lb-upload-timeouts # сроки LB пути загрузки на заглушке: 201 после 12 с молчания, 504 через 10/30 с, 400 в формате контракта; ~35 с docker compose logs --no-log-prefix cleaner | tail -3 # уборщик: Started cleaner (60/900/100), проходы, отказы docker compose run --rm --no-deps cleaner --once # разовый проход уборщика (grace 900 с): код 0 — проход дошёл до конца python3 $D stop-at-start # docker stop стартующей реплики: ~0,06 с и код 0 (раньше 10 с и 137) diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index d91b1975..3c9da70f 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -96,6 +96,15 @@ нет, готовое вложение скачивается с тем же SHA-256; триггер снимается в finally и в начале следующего прогона; код 1 при расхождении, без LB — код 2 + lb-upload-timeouts [--config F] [--image ТЕГ] без стенда: спек + load-balancing «Загрузки через балансировщик» — временная + сеть, HAProxy закреплённого образа с конфигурацией F (по + умолчанию infra/haproxy/haproxy.cfg) и заглушка реплики под + именем api; молчание заглушки 12 с до и после тела загрузки — + 201, 12 с на другом пути — 504 через ~10 с, 32 с на пути + загрузки — 504 через ~30 с, клиент молчит посреди тела — 400 + в формате контракта; сеть и контейнеры удаляются при любом + исходе; код 1 при расхождении stop остановить свой экземпляр на порту all start → flow → smoke → student (если есть student-tests/) → stop @@ -127,6 +136,7 @@ import os import re import secrets import signal +import socket import subprocess import sys import threading @@ -2761,6 +2771,426 @@ def report_rows(rows: list[tuple[str, str, str]]) -> int: return 0 +# lb-upload-timeouts: сроки LB пути загрузки на заглушке (design change +# upload-memory, решение 7). Молчание заглушки: дольше timeout server +# прочих путей (10 с), но меньше срока пути загрузки (30 с) — и дольше его +LBTO_LABEL = "mtusi.lb-upload-timeouts" +LBTO_SILENT_S = 12 +LBTO_LONG_S = 32 +# сколько клиент молчит посреди тела, если LB не ответил раньше: дольше +# timeout client (30 с) +LBTO_CLIENT_SILENT_S = 35 +LBTO_BODY_BYTES = 10 * 1024 * 1024 +LBTO_UPLOAD_PATH = f"{CHATS}/{uuid.UUID(int=1)}/attachments" +LBTO_READY_TIMEOUT_S = 30 +# заглушка реплики на asyncio (stdlib образа API): /health/ready — 200, +# остальное — по параметру case; тело читает только там, где сказано +LBTO_STUB = r""" +import asyncio, json, os + +SILENT = float(os.environ["STUB_SILENT_S"]) +LONG = float(os.environ["STUB_LONG_S"]) + + +async def handle(reader, writer): + try: + head = await reader.readuntil(b"\r\n\r\n") + lines = head.decode("latin-1").split("\r\n") + target = lines[0].split(" ")[1] + headers = {} + for line in lines[1:]: + name, sep, value = line.partition(":") + if sep: + headers[name.strip().lower()] = value.strip() + path, _, query = target.partition("?") + params = dict(p.split("=", 1) for p in query.split("&") if "=" in p) + case = params.get("case", "") + length = int(headers.get("content-length") or 0) + status = 200 + if path != "/health/ready": + if case == "before-body": + await asyncio.sleep(SILENT) + await reader.readexactly(length) + status = 201 + elif case in ("after-body", "too-long"): + await reader.readexactly(length) + await asyncio.sleep(SILENT if case == "after-body" else LONG) + status = 201 + elif case == "other-path": + await asyncio.sleep(SILENT) + else: + await reader.readexactly(length) + status = 201 + body = json.dumps({"status": "ok", "case": case}).encode() + writer.write( + f"HTTP/1.1 {status} Stub\r\nContent-Type: application/json\r\n" + f"Content-Length: {len(body)}\r\nX-Request-Id: stub-{case}\r\n" + "X-Instance-Id: stub\r\nConnection: close\r\n\r\n".encode() + body + ) + await writer.drain() + except Exception: + pass + finally: + writer.close() + + +async def main(): + server = await asyncio.start_server(handle, "0.0.0.0", 8080) + async with server: + await server.serve_forever() + + +asyncio.run(main()) +""" + + +def lbto_docker(*args: str, check: bool = True) -> str: + """docker CLI без shell; вывод — строкой.""" + result = subprocess.run( + ["docker", *args], + capture_output=True, + text=True, + check=False, + ) + if check and result.returncode != 0: + raise RuntimeError( + f"docker {args[0]} {args[1] if len(args) > 1 else ''}: " + f"{result.stderr.strip()[-300:]}", + ) + return result.stdout.strip() + + +def lbto_haproxy_image() -> str: + """Образ LB рабочего стенда — тег и digest из docker-compose.yml.""" + text = (ROOT / "docker-compose.yml").read_text(encoding="utf-8") + match = re.search(r"^\s*image:\s*(haproxy:\S+)\s*$", text, re.MULTILINE) + if match is None: + raise RuntimeError("no haproxy image in docker-compose.yml") + return match.group(1) + + +def lbto_error_ok( + headers: dict[str, str], + body: bytes, + code: str, +) -> str: + """Пусто — ответ LB в формате ошибки контракта; иначе — что не так.""" + media = headers.get("content-type", "").split(";")[0].strip() + if media != "application/json": + return f"Content-Type {media or '-'}" + try: + data = json.loads(body.decode("utf-8")) + except (UnicodeDecodeError, ValueError): + return "body is not JSON" + error = data.get("error") if isinstance(data, dict) else None + if not isinstance(error, dict) or set(data) != {"error"}: + return "not {error: …}" + if set(error) != {"code", "message", "request_id"}: + return f"error fields {sorted(error)}" + if error["code"] != code: + return f"code {error['code']}" + request_id = headers.get("x-request-id", "") + if not request_id or error["request_id"] != request_id: + return "request_id differs from X-Request-Id" + return "" + + +def lbto_request( + port: int, + method: str, + path: str, + body: bytes | None, +) -> tuple[int, dict[str, str], bytes, float]: + """Запрос через LB: статус, заголовки, тело, секунды до ответа.""" + conn = http.client.HTTPConnection("127.0.0.1", port, timeout=60) + started = time.monotonic() + try: + headers = {"Content-Type": "image/png"} if body is not None else {} + conn.request(method, path, body=body, headers=headers) + resp = conn.getresponse() + data = resp.read() + elapsed = time.monotonic() - started + return ( + resp.status, + {k.lower(): v for k, v in resp.getheaders()}, + data, + elapsed, + ) + finally: + conn.close() + + +def lbto_silent_client( + port: int, +) -> tuple[int, dict[str, str], bytes, float]: + """Клиент отправил половину тела и молчит: ответ LB и секунды от + последнего отправленного байта.""" + sock = socket.create_connection(("127.0.0.1", port), timeout=10) + try: + head = ( + f"POST {LBTO_UPLOAD_PATH}?case=client-silent HTTP/1.1\r\n" + f"Host: 127.0.0.1:{port}\r\nContent-Type: image/png\r\n" + f"Content-Length: {LBTO_BODY_BYTES}\r\n\r\n" + ).encode("ascii") + sock.sendall(head + bytes(LBTO_BODY_BYTES // 2)) + started = time.monotonic() + sock.settimeout(LBTO_CLIENT_SILENT_S + 10) + resp = http.client.HTTPResponse(sock, method="POST") + resp.begin() + data = resp.read() + return ( + resp.status, + {k.lower(): v for k, v in resp.getheaders()}, + data, + time.monotonic() - started, + ) + finally: + sock.close() + + +def cmd_lb_upload_timeouts(config: str, image: str) -> int: + """Сроки LB пути загрузки (спек `load-balancing`, «Загрузки через + балансировщик», «Ошибки балансировщика в формате контракта»; design + change `upload-memory`, решение 7). + + Временная сеть, заглушка реплики под именем `api` (образ API, stdlib) + и HAProxy закреплённого образа с `config`, порт LB — на свободном + `127.0.0.1`. Случаи идут параллельно, каждый — своё соединение и свой + `case` в строке запроса. Хранилищ и стендов compose не трогает; сеть и + контейнеры по метке удаляются при любом исходе.""" + + def interrupted(signum: int, _frame: object) -> None: + raise KeyboardInterrupt(signal.Signals(signum).name) + + config_path = Path(config).resolve() + if not config_path.is_file(): + print(f"config {config_path} not found") + return 2 + tag = uuid.uuid4().hex[:8] + label = f"{LBTO_LABEL}={tag}" + network = f"mtusi-lbto-{tag}" + haproxy = lbto_haproxy_image() + port = lbto_free_port() + print(f"config {config_path}") + print(f"haproxy {haproxy}, stub image {image}, LB 127.0.0.1:{port}") + previous = { + signum: signal.signal(signum, interrupted) + for signum in (signal.SIGTERM, signal.SIGHUP) + } + mount = ( + f"type=bind,src={config_path}," + "dst=/usr/local/etc/haproxy/haproxy.cfg,readonly" + ) + try: + checked = subprocess.run( + [ + "docker", + "run", + "--rm", + "--label", + label, + "-e", + "API_PORT=8080", + "--mount", + mount, + haproxy, + "haproxy", + "-c", + "-f", + "/usr/local/etc/haproxy/haproxy.cfg", + ], + capture_output=True, + text=True, + check=False, + ) + print(f"haproxy -c: exit {checked.returncode}") + if checked.returncode != 0: + print((checked.stdout + checked.stderr).strip()[-600:]) + return 1 + lbto_docker("network", "create", "--label", label, network) + lbto_docker( + "run", + "-d", + "--name", + f"{network}-api", + "--label", + label, + "--network", + network, + "--network-alias", + "api", + "--no-healthcheck", + "-e", + f"STUB_SILENT_S={LBTO_SILENT_S}", + "-e", + f"STUB_LONG_S={LBTO_LONG_S}", + "--entrypoint", + "python", + image, + "-c", + LBTO_STUB, + ) + lbto_docker( + "run", + "-d", + "--name", + f"{network}-lb", + "--label", + label, + "--network", + network, + "-e", + "API_PORT=8080", + "-p", + f"127.0.0.1:{port}:8080", + "--mount", + mount, + haproxy, + ) + deadline = time.monotonic() + LBTO_READY_TIMEOUT_S + while True: + try: + status = lbto_request(port, "GET", "/health/ready", None)[0] + except OSError: + status = 0 + if status == 200: + break + if time.monotonic() > deadline: + print(f"stub is not UP in LB after {LBTO_READY_TIMEOUT_S}s") + return 1 + time.sleep(0.5) + return lbto_cases(port) + finally: + left = lbto_docker( + "ps", + "-aq", + "--filter", + f"label={label}", + check=False, + ).split() + if left: + lbto_docker("rm", "-f", *left, check=False) + lbto_docker("network", "rm", network, check=False) + for signum, handler in previous.items(): + signal.signal(signum, handler) + + +def lbto_free_port() -> int: + """Свободный порт 127.0.0.1; сокет закрывается до публикации LB.""" + with socket.socket() as sock: + sock.bind(("127.0.0.1", 0)) + return sock.getsockname()[1] + + +def lbto_cases(port: int) -> int: + """Случаи параллельно; таблица и код 1 при расхождении.""" + body = b"\x89PNG\r\n\x1a\n" + bytes(LBTO_BODY_BYTES - 8) + upload = f"{LBTO_UPLOAD_PATH}?case=" + # случай, вызов, статус, code ошибки LB (пусто — ответ заглушки) и + # границы времени ответа, с + cases = [ + ( + "upload: replica silent 12 s before body", + lambda: lbto_request(port, "POST", f"{upload}before-body", body), + 201, + "", + (LBTO_SILENT_S - 0.5, LBTO_SILENT_S + 5), + ), + ( + "upload: replica silent 12 s after body", + lambda: lbto_request(port, "POST", f"{upload}after-body", body), + 201, + "", + (LBTO_SILENT_S - 0.5, LBTO_SILENT_S + 5), + ), + ( + "other path: replica silent 12 s", + lambda: lbto_request( + port, + "GET", + "/api/v1/users/me?case=other-path", + None, + ), + 504, + "unavailable", + (9.5, 12), + ), + ( + "upload: replica silent 32 s", + lambda: lbto_request(port, "POST", f"{upload}too-long", body), + 504, + "unavailable", + (29.5, 32), + ), + ( + "upload: client silent mid-body", + lambda: lbto_silent_client(port), + 400, + "invalid_request", + (29, 33), + ), + ] + results: dict[int, object] = {} + + def run_case(number: int, call: object) -> None: + try: + results[number] = call() # type: ignore[operator] + except Exception as e: # noqa: BLE001 — исход случая в таблицу + results[number] = e + + threads = [ + threading.Thread(target=run_case, args=(number, case[1])) + for number, case in enumerate(cases) + ] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + width = max(len(case[0]) for case in cases) + print( + f"{'case':<{width}} {'expected':<29} {'got':<24} {'time':>7}", + ) + failed = 0 + for number, (name, _, status, code, (low, high)) in enumerate(cases): + expected = f"{status} {code or 'replica'} {low:g}–{high:g} s" + outcome = results.get(number) + if isinstance(outcome, Exception): + got, elapsed, problem = type(outcome).__name__, None, "error" + else: + got_status, headers, data, elapsed = outcome # type: ignore[misc] + problem = "" + if got_status != status: + problem = f"status {got_status}" + elif code: + problem = lbto_error_ok(headers, data, code) + elif headers.get("x-instance-id") != "stub": + problem = "not the replica answer" + if not problem and not low <= elapsed <= high: + problem = f"time {elapsed:.2f} s" + source = ( + "replica" if headers.get("x-instance-id") == "stub" else "LB" + ) + got = f"{got_status} {source}" + if got_status >= 400 and source == "LB": + media = headers.get("content-type", "").split(";")[0] + got += f" {media or '-'}" + time_cell = "-" if elapsed is None else f"{elapsed:.2f} s" + verdict = "" if not problem else f" FAIL: {problem}" + failed += bool(problem) + print( + f"{name:<{width}} {expected:<29} {got:<24} {time_cell:>7}" + f"{verdict}", + ) + if failed: + print(f"FAIL: {failed} case(s) differ") + return 1 + print( + "PASS: the upload path waits 30 s for the replica, other paths 10 s, " + "LB errors are in the contract format", + ) + return 0 + + # stop-at-start: записи журнала, по которым видны этапы старта и остановки STARTED_SERVER = "Started server process" SERVER_RUNNING = "Uvicorn running on" @@ -3144,6 +3574,17 @@ def main() -> int: failover.add_argument("--mode", choices=("stop", "kill"), default="stop") sub.add_parser("attachment-storage") sub.add_parser("upload-consistency") + lbto = sub.add_parser("lb-upload-timeouts") + lbto.add_argument( + "--config", + default=str(ROOT / "infra" / "haproxy" / "haproxy.cfg"), + help="конфигурация HAProxy (по умолчанию — проекта)", + ) + lbto.add_argument( + "--image", + default="mtusi-messenger:lab4", + help="образ заглушки реплики (нужен только python)", + ) stop = sub.add_parser("stop-at-start") stop.add_argument("--image", default="mtusi-messenger:lab4") stop.add_argument( @@ -3226,6 +3667,8 @@ def main() -> int: return cmd_attachment_storage(port) if args.cmd == "upload-consistency": return cmd_upload_consistency(port) + if args.cmd == "lb-upload-timeouts": + return cmd_lb_upload_timeouts(args.config, args.image) if args.cmd == "stop-at-start": return cmd_stop_at_start( args.image, diff --git a/.gitignore b/.gitignore index 472eb50d..9d63dad4 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,8 @@ evidence/bench/quick-*/ evidence/failover/quick-*/ # make bench_rollout_quick: то же для профиля поочерёдной замены evidence/rollout/quick-*/ +# make bench_uploads_quick: то же для профиля загрузок +evidence/uploads/quick-*/ # сравнения пробных меток evidence/compare/*quick-* # make bench_plots на пробных метках diff --git a/AGENTS.md b/AGENTS.md index c7c6665f..66b1c38f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,13 @@ SeaweedFS с приватным bucket, bootstrap и клиент `src/infra/s3/ уборщик незавершённых загрузок — сервис `cleaner` (`python -m src.cleaner`, grace 900 с, свой пользователь S3 «чтение и удаление»), частичный индекс строк `pending`, новая capability -`storage-consistency`. План работ, решения и +`storage-consistency`. Память и сроки загрузки — активный change +`upload-memory` (`openspec/changes/upload-memory/`): места загрузки на +процесс API (`[uploads]`: 4 места, очередь 16, ожидание 5 с, затем 429 +`rate_limited` с `Retry-After`), срок тела 30 с (400), одна копия тела +при PUT, буферы сокетов реплики 512 KiB и LB 256 KiB, `timeout server` +LB пути загрузки 30 с, дренаж замены 90 с, профиль `uploads` стенда +`bench/`. План работ, решения и трек «5» — `PLAN.md`. Из лабы 2: PostgreSQL как источник истины, вход по Basic → Bearer-сессия, Valkey — кэш карточек чатов. Из лабы 3: HAProxy перед ≥2 репликами API @@ -38,8 +44,8 @@ src.cleaner`, grace 900 с, свой пользователь S3 «чтение `upload-consistency` лабы 4 — в `openspec/changes/archive/`, активных нет, спеки синхронизированы (новые capability: с `s3-storage` — `object-storage`, с `attachments` — `attachments`, с -`upload-consistency` — `storage-consistency`); в `KNOWN_ISSUES.md` одна открытая запись (bootstrap после удаления -bucket). Отчёт, evidence и рабочий план лабы 3 остались в её +`upload-consistency` — `storage-consistency`); в `KNOWN_ISSUES.md` две открытые записи (bootstrap после удаления +bucket; 408 LB на медленные заголовки текстом HAProxy). Отчёт, evidence и рабочий план лабы 3 остались в её репозитории (`REPORT.md`, `evidence/`, `git show 063eedb:PLAN.md`). Стек: Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore @@ -139,6 +145,18 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore `ready` уборщик не трогает. У уборщика свой пользователь S3 — только чтение и удаление объектов своего bucket, ключи `S3_CLEANER_*` только у него и bootstrap (`docker.md`, `settings.md`). +- Лаба 4, память загрузок (change `upload-memory`): память загрузок + реплики ограничена числом мест, а не числом клиентов. Место берётся + после проверок 401/400/404/415/413 и до чтения тела, держится до + ответа и освобождается при любом исходе; без места — очередь процесса + до `[uploads] max_waiting` не дольше `wait_timeout_seconds`, затем 429 + с `Retry-After` без строки и объекта. Тело — не дольше + `body_timeout_seconds` с момента места (иначе 400), в PUT уходит тот же + `BytesIO` без второй копии (`service-layer.md`). Ожидание, тело и + проверка — до строки `pending`: граница B уборщика прежняя (17 с). + Буфер приёма сокетов `api` — 512 KiB (`sysctls`), буфер отправки LB к + реплике — 256 KiB; `timeout server` пути загрузки 30 с, остальных — 10 + с; `ROLLOUT_DRAIN_TIMEOUT` 90 с (`balancer.md`, `docker.md`). - `.env`, `config.toml`, секреты, токены и реальные данные не попадают ни в git, ни в образ. В `evidence/` и `REPORT.md` — только обезличенные выводы команд. @@ -318,6 +336,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `driver.py --port attachment-failover [--mode stop\|kill]` | вложение через LB, `stop-one.sh` принявшей реплики, скачивание через другую (тот же SHA-256), 404 постороннему, затем `make replicas`; доказательство исключения `attachments` «Принявшая реплика остановлена» | | `driver.py --port attachment-storage` | схема таблиц вложений, вид `object_key`, объект в bucket, анонимный GET — 403, `docker diff` реплик; доказательство исключения «Байты не в БД и не на диске API» | | `driver.py --port upload-consistency` | согласованность БД и S3 на рабочем стенде (~45 с): загрузка при `pause` S3 и со сбоем фиксации `ready` (триггер на `filename` прогона) — 503, строки `pending` не видны, компенсация удалила объект; `cleaner --once` с grace 30 с убирает обе, объектов без строки нет, готовое вложение цело; `evidence/attachments/consistency.md` | +| `driver.py lb-upload-timeouts [--config F]` | сроки LB пути загрузки без стенда (~35 с): `haproxy -c`, временная сеть, HAProxy закреплённого образа с F (по умолчанию `infra/haproxy/haproxy.cfg`) и заглушка реплики `api` на образе API; молчание 12 с до и после тела загрузки — 201, 12 с на другом пути — 504 через ~10 с, 32 с на пути загрузки — 504 через ~30 с, клиент молчит посреди тела — 400 в формате контракта; уборка при любом исходе, код 1 при расхождении; `evidence/uploads/lb-timeouts.md` | | `docker compose run --rm --no-deps cleaner --once` | разовый проход уборщика незавершённых загрузок (grace — `[cleaner]` или `-e CLEANER__PENDING_GRACE_SECONDS=…`, не меньше 18 с): 0 — проход дошёл до конца, 1 — прерван отказом, 2 — неверная конфигурация; журнал сервиса — `docker compose logs --no-log-prefix cleaner` | | `make lb_stats` | слоты HAProxy: адрес, состояние проверки (`DRAIN`, `MAINT` при замене), запросы, повторы, перенаправления (CSV статистики изнутри контейнера LB) | | `make rolling_update [COMMIT=...] [MIGRATE=0]` | поочерёдная замена реплик без простоя (`scripts/rolling-update.sh`, `balancer.md`): сборка из рабочего дерева (или файлов `COMMIT` через `git archive`), миграции один раз, затем по одной — новая `healthy` и `UP` в LB, старая `drain` → запросов в полёте 0 → `maint` → stop → rm → слот `ready`. Нужен штатный стенд (`make replicas`) без слотов LB в ручном `drain` / `maint` (иначе код 2 и команда `set server … state ready`); сбой и Ctrl+C — `API_REPLICAS` готовых реплик, повтор доводит; `MIGRATE=0` — откат на прежний образ (после него `docker compose up` без сборки не запускать: `migrate` прежнего образа упадёт на новой ревизии) | @@ -341,6 +360,8 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `make bench_rollout_quick` | то же с короткими окнами (~2 мин), с ресурсами, метка `quick-rollout-<время>`, в git не идёт | | `make bench_scaling SERIES=a\|b\|pool\|ab\|db\|db4 [SCALING_LABEL=...] [RESUME=1]` | уровень 5, трек 1: серия на стенде `mtusi-bench` (метка `scaling-<серия>` по умолчанию). `a` — бюджет 4 CPU: 1 × 4, 2 × 2, 4 × 1 (~50 мин); `b` — 1…6 реплик по 1 CPU (~100 мин); `pool` — 4 реплики при `max_connections` 100 и 50 (~35 мин); `ab` — 1 × 1 и 6 × 1 для «до/после» и A/A (~35 мин); `db` — 1, 2, 4 реплики при PostgreSQL 0,5 CPU и контроль 4 × 1 при 2 CPU (~50 мин); `db4` — только 4 × 1 при 0,5 и 2 CPU (~25 мин, «до/после» `scaling-improvement`); `db_quick` — самопроверка серии `db` (~4 мин, метка `quick-*`). Ячейка — конфигурация × повтор (3), свежий стенд; открытая модель 70/20/10, фиксированные 250 и 500/с и поиск R* по SLO; сэмплер контейнеров, ВМ, LB и PostgreSQL. `RESUME=1` — продолжить прерванную метку на том же commit. Перед запуском — проверка хоста, рабочий стенд — `make stop`; метку коммитить до следующей серии (`bench.md`) | | `make bench_scaling_quick` | самопроверка серий: 1 × 1 и 2 × 1 при `max_connections` 50, короткие окна (~4 мин), метка `quick-scaling-<время>`, в git не идёт | +| `make bench_uploads [UPLOADS_LABEL=...]` | уровень 4, память при одновременных загрузках (~50 мин, метка `baseline` по умолчанию; change `upload-memory`): стенд `mtusi-bench` с LB, одной репликой 1 CPU / 512 МБ без swap, PostgreSQL, Valkey и S3 рабочего стенда; варианты «до» (`Profile.uploads_before` — `f894040`, `git archive`; commit вне истории — код 2), «без лимита» (1000 мест, без очереди) и «с лимитом» (по умолчанию) × тела PNG ~1 и ~10 MiB × 1 / 10 / 20 / 40 клиентов × 3 повтора, на прогон — новые реплика и volume S3; пик `memory.peak` окна со сбросом (сэмплер `peak`), `anon`, `sock`, OOM, ответы по кодам, загрузок/с, p50/p95/p99, пики S3 и LB, H1–H4 в сводке — `evidence/uploads/<метка>/`. Перед запуском — проверка хоста (`bench.md`), рабочий стенд — `make stop`, гипотезы закоммичены раньше | +| `make bench_uploads_quick` | то же короче (~4,5 мин): «без лимита» и «с лимитом», 10 MiB, 1 / 10 / 40 клиентов, один повтор, метка `quick-uploads-<время>`, в git не идёт | | `make bench_plots LABELS="..." [PLOTS=scaling]` | графики SVG и сводка серий трека 1 из меток: R* от числа реплик, p95 от интенсивности, CPU по компонентам, эффективность и точка насыщения — `evidence/plots//` | | `make bench_ab BEFORE=... AFTER=... REAPPLY= [SERIES=...]` | «до» и «после» одного изменения подряд (два прогона `bench`): `bench` для `BEFORE`, commit доказательств, `git revert` commit отката `REAPPLY`, `bench` для `AFTER`; с `SERIES` — серия трека 1 вместо матрицы (`make bench_scaling`). Нужно чистое рабочее дерево; сама делает два коммита | | `make bench_compare BEFORE=... AFTER=... [AA=...] [CHANGE=...]` | дельта двух меток `make bench` по ячейкам матрицы, у серий трека 1 — по общим конфигурациям (R*, задержки на фиксированных уровнях, CPU на запрос) и таблица PostgreSQL на R* и первой нарушившей ступени (CPU на запрос, новые сессии, соединения); `CHANGE` — change в шапке сравнения серий (по умолчанию `scaling-bench`); метки с разной методикой не сравнивает (в том числе метку без LB с меткой стенда на LB и серию с матрицей); с `AA` (метка того же кода, что `BEFORE`) отделяет эффект от шума. Результат в `evidence/compare/<до>__<после>.md` | @@ -362,29 +383,30 @@ src/ main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run cleaner/__main__.py # python -m src.cleaner [--once]: early_stop.install("cleaner") до импорта → main(); неверные настройки — запись без значений и код 2 cleaner/main.py # уборщик незавершённых загрузок: проверка grace > 2 × request_timeout + s3 timeout (иначе код 2), свой engine и клиент S3, цикл с интервалом, SIGTERM — довести текущий шаг строки и выйти 0, --once — коды 0/1/2 - config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds, [cleaner] interval_seconds 60, pending_grace_seconds 900, batch_size 100 + config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds, [uploads] max_concurrent 4, max_waiting 16, wait_timeout_seconds 5, body_timeout_seconds 30 (места загрузок процесса API), [cleaner] interval_seconds 60, pending_grace_seconds 900, batch_size 100 api/ routers/health.py # /health/live, /health/ready: вне версии, без идентификации routers/v1/.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py); attachment.py — один роутер с двумя префиксами: загрузка (тело через request.stream(), схема — openapi_extra, строгий UTF-8 filename по scope["query_string"]), метаданные, байты StreamingResponse schemas/.py # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12; attachment.py — DisplayFilename (отказ на / \ Cc и пробелы) и Attachment; message.py — CreateMessage с attachment_ids и валидатором пустого текста dependencies.py # db_session_scope (сессия на шаг — session_scope с фабрикой API) и get_db_session поверх него, фабрики сервисов (с кэшем; вложения — без сессии запроса), разбор Basic, текущая сессия по Bearer, CurrentUserBrief (вход с короткой сессией), пагинация - errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; у 500 — X-Request-Id и X-Instance-Id + errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; RETRY_AFTER — Retry-After у 429 занятых мест загрузки; у 500 — X-Request-Id и X-Instance-Id middlewares/ # X-Request-Id, X-Instance-Id и access-лог core/ repos/.py # атомарный доступ к хранилищу, модульные функции repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO repos/attachment.py # строки вложений: вставка pending (created_at = updated_at), mark_ready (pending и непомеченная → ready RETURNING), чтение одной и до 10; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), mark_removing (пометка updated_at), delete_attachment - repos/attachment_object.py # оригинал в S3: ключ <база>/attachments//original, put, open, delete_original + repos/attachment_object.py # оригинал в S3: ключ <база>/attachments//original, put_original (поток BytesIO и size, без копии тела), open, delete_original repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой services/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией - services/attachment.py # AttachmentService(db_scope, cache, storage): загрузка (проверки → тело со счётчиком в BytesIO, bytes без копии → структура и SHA-256 в потоке → pending → PUT → ready; сбой ready до COMMIT или пропавшая строка — удаление объекта и 503), метаданные, отдача потоком + services/attachment.py # AttachmentService(db_scope, cache, storage, slots): загрузка (проверки → место загрузки, 429 → тело со счётчиком и сроком в BytesIO, 400 по сроку → структура и SHA-256 в потоке над getvalue() → del → pending → PUT тем же BytesIO → ready; сбой ready до COMMIT или пропавшая строка — удаление объекта и 503; место — до ответа), метаданные, отдача потоком services/attachment_cleanup.py # AttachmentCleanupService(db_scope, storage): проход уборщика — кандидаты keyset, каждая строка в два шага: блокировка и пометка (commit) → блокировка, DELETE объекта и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO - exceptions/.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва, 500 пропавшего объекта + exceptions/.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва и срока тела (UploadTimedOut), 429 занятых мест (UploadsBusy), 500 пропавшего объекта infra/ early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog logger.py # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи password.py # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username + upload_slots.py # UploadSlots (asyncio.Semaphore по порядку прихода, счётчик ожидающих, срок ожидания; slot() — UploadsBusy или ожидание в мс, место в finally) и глобал upload_slots из [uploads]; импортирует только dependencies.py db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping db/session.py # глобалы engine и session_factory процесса API db/scope.py # session_scope(factory, timeout_seconds): сессия на шаг, срок, отказ БД → invalidate, warning, ServiceUnavailable; общая для API и уборщика @@ -392,7 +414,7 @@ src/ db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit; attachment.py — Attachment (частичный индекс pending по (created_at, id)) и MessageAttachment (порядок position, FK без каскада) cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск cache/instance.py # глобал cache процесса API - s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put / head / open (чтение блоками) / delete, срок на вызов и блок, ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo, StoredObject + s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put (поток read/seek/tell и size) / head / open (чтение блоками) / delete, срок на вызов и блок, ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo, StoredObject s3/instance.py # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan schemas/ dataclasses/.py # DTO между repo → service → api @@ -403,11 +425,11 @@ src/ utc.py # utcnow() (aware UTC), формат RFC 3339 с Z cursor.py # непрозрачный keyset-курсор: кодирование и разбор; поля проверяются по отдельности, незнакомые игнорируются, смена формата — новая CURSOR_VERSION student-tests/ # black-box тесты по HTTP (уровень 4): make student_test - conftest.py # BASE_URL, EXPECT_REPLICAS и фикстура replicas (пропуск против одного процесса), проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook + conftest.py # BASE_URL, EXPECT_REPLICAS и фикстура replicas (пропуск против одного процесса), проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api/uploads_api, сбор маркеров spec, стоп без hook api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message (с attachment_ids) — с Idempotency-Key; post_attachment/upload, attachment_meta, attachment_content - contract.py # тела по схемам contracts/openapi.json, форматы id, attachment_ids и времени, X-Instance-Id, assert_error (с 413 и 415), assert_errors (статусы всех вариантов запроса разом), assert_content (байты, тип, nosniff, без Location и x-amz-*), assert_replicas - images.py # изображения для тестов: PNG на stdlib (любые IHDR, Adam7, точный размер, бомба, огромные размеры, порча байта), JPEG через Pillow (dev), обрезка и хвост - test_attachments.py # спек attachments: загрузка, лимиты, тип и целостность, filename, доступ, метаданные, оригинал, variant, повтор, другая реплика + contract.py # тела по схемам contracts/openapi.json, форматы id, attachment_ids и времени, X-Instance-Id, assert_error (с 413, 415 и 429 — Retry-After положительное целое), assert_errors (статусы всех вариантов запроса разом), assert_content (байты, тип, nosniff, без Location и x-amz-*), assert_replicas + images.py # изображения для тестов: PNG на stdlib (любые IHDR, Adam7, точный размер, бомба, огромные размеры, порча байта, шум RGB ~1 MiB от зерна — png_noise), JPEG через Pillow (dev), обрезка и хвост + test_attachments.py # спек attachments: загрузка, лимиты, тип и целостность, filename, доступ, метаданные, оригинал, variant, повтор, 10 одновременных загрузок, другая реплика test_idempotency.py # спек idempotency: ключ, повтор, 409, область, порядок кодов, повтор через другую реплику (гонка — test_race.py, отказы — test_failures.py) test_load_balancing.py # спек load-balancing (вне сверки покрытия): одна сессия на разных репликах, запись видна через другую реплику spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия; missing_evidence — файл evidence по ссылке исключения должен быть в репозитории @@ -415,32 +437,33 @@ student-tests/ # black-box тесты по HTTP (уровень 4) test_.py # сценарии основных спеков, маркер @pytest.mark.spec test_failures.py # проверки отказов (маркер fault): только make failure_checks run_isolated.py # make test_isolated: образ на временной базе test_, уборка базы и префикса test_/ в S3 (weed shell fs.rm, затем проверка fs.ls: код 0 weed shell успеха не значит; префикс только из проверенного имени) (stdlib) - run_failures.py # make failure_checks: стенд <рабочий>-failures (Postgres, Valkey, S3 + bootstrap, уборщик с grace 20 с и интервалом 1 с → FAULT_CLEANER_*), два API, pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), журналы API и уборщика при падении, уборка (stdlib) + run_failures.py # make failure_checks: стенд <рабочий>-failures (Postgres, Valkey, S3 + bootstrap, уборщик с grace 20 с и интервалом 1 с → FAULT_CLEANER_*), три API (обычный, «тесный», «узкий по загрузкам» с UPLOADS_ENV → FAULT_UPLOADS_BASE_URL / FAULT_UPLOADS_ENV), pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), журналы API и уборщика при падении, уборка (stdlib) fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников, сообщений и вложений (fail-attachments insert|ready|stall|commit|outlive|undeletable: сбой вставки, перевода в ready до и на COMMIT, задержка, строка «старше grace» с ожиданием уборщика, неудаляемая строка), заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions, attachment-ids, last-pending, object-ids (файлы original по fs.tree), kill-api / start-api (stdlib) failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, S3, LB), уборщик с CLEANER__* 20 / 1 и restart "no", stop_grace_period 2 с у S3, healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster) -bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling - run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json +bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling / bench_uploads (с S3) + run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json; профиль uploads (S3 и bootstrap на стенде, на прогон — новый volume S3 и реплика с окружением варианта через .work/variant.compose.yml, образ «до» — тег bench-from, сэмплер peak), в паспорте всех профилей stand.api_tcp_rmem и docker.kernel scaling.py # серии трека 1 без docker: лестница и автомат поиска R*, разбор итога k6 и строк сэмплера, агрегаты окна, вердикт SLO и брака генератора, признаки узкого места (THRESHOLDS), предельный CPU на запрос, сводка серии; --selftest plots.py # make bench_plots: SVG на stdlib (R* от числа реплик, p95 от интенсивности, CPU по компонентам) и сводка с точкой насыщения; render_series — графики в каталоге метки - sampler.sh # сэмплер (только в контейнере mtusi-bench-sampler на образе PostgreSQL, --cgroupns host): режим list (серии) — cpu.stat, память и PSI заданных контейнеров, /proc/stat и PSI ВМ, статистика HAProxy, psql \watch по pg_stat_activity / database / wal / io; режим scan (failover, rollout) — обход cgroup всех контейнеров и /proc/stat, без сети, psql и LB + sampler.sh # сэмплер (только в контейнере mtusi-bench-sampler на образе PostgreSQL, --cgroupns host): режим list (серии) — cpu.stat, память и PSI заданных контейнеров, /proc/stat и PSI ВМ, статистика HAProxy, psql \watch по pg_stat_activity / database / wal / io; режим scan (failover, rollout) — обход cgroup всех контейнеров и /proc/stat, без сети, psql и LB; режим peak (uploads) — сброс memory.peak реплики, S3 и LB через свой дескриптор (perl), чтение пика в конце окна, выборка current / anon / sock / oom_kill раз в 0,2 с (--user 0, cgroupfs rw, без сети) + uploads.py # профиль uploads без docker: тела PNG из шума от зерна, план кругами, разбор строк k6 и сэмплера peak, строка runs.csv, пометки oom / host_swap / peak_sampled / s3_down, summary.md (медиана и min–max по ячейкам, сценарии спеков, H1–H4); --selftest resources.py # ресурсы профилей failover и rollout без docker: интервалы контейнеров (сброс при новой cgroup, заморозка, новые контейнеры с момента запуска), окна, CPU / троттлинг / память по компонентам и ВМ, CPU на запрос в установившихся окнах, resources.csv / samples.csv, разделы summary.md; --selftest failover.py # профиль failover без docker: строки k6 о запросах, статистика и журнал HAProxy, события Docker, посекундная шкала, величины фазы, summary.md rollout.py # профиль rollout без docker: строки скрипта замены, события контейнеров проекта, состояния слотов LB (UP, drain, maint, ready), шаги по репликам, шкала со старыми и новыми ответами, окна до / во время / после, summary.md - bench.compose.yml # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain; s3 и cleaner описаны (mtusi-bench-s3, mtusi-bench-cleaner, без порта), но профили их не запускают + bench.compose.yml # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain; s3 (лимиты BENCH_S3_*, swap = память) запускает только профиль uploads, cleaner описан (mtusi-bench-cleaner, без порта), но профили его не запускают; буфер приёма реплики — sysctls основного compose bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей и секретов S3: их генерирует run.py) - k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом), mixed (ступень серии трека 1: ramping-arrival-rate 70/20/10, тег окна, распределение по X-Instance-Id, досрочный выход); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы + k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом), mixed (ступень серии трека 1: ramping-arrival-rate 70/20/10, тег окна, распределение по X-Instance-Id, досрочный выход), uploads (constant-vus загрузок тела из /work, пауза Retry-After на 429 и 1 с на прочие ошибки, строка на запрос, WARMUP — одна загрузка); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы compare.py # make bench_compare: дельта двух меток (ячейки матрицы или общие конфигурации серий), уровень шума, эффект или шум; отказ при разной методике, в том числе метке без LB и серии против матрицы ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд, с --series — серии трека 1 migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose; 739b8f04d5fb — частичный индекс pending CONCURRENTLY в autocommit_block infra/ # конфигурации сервисов стенда; README.md — skeleton valkey/valkey.conf # лимит памяти и LRU, persistence выключен s3/bootstrap.sh # bootstrap S3 (сервис s3-bootstrap, network_mode: service:s3): apply — bucket, анонимный доступ none, политики api-objects и cleaner-objects, пользователи api и cleaner с ключами из .env, проверки приватности обоих ключей; check (и строки ключа уборщика) и cleanup — для make s3_check; секреты — stdin weed shell и файл curl на tmpfs - haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта, мониторинг :8404, runtime API на 127.0.0.1:9999 внутри контейнера (drain / maint / ready при замене) + haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта (400, 502, 503, 504), timeout server 30 с пути загрузки (set-timeout, остальные 10 с), tune.sndbuf.server 256 KiB, мониторинг :8404, runtime API на 127.0.0.1:9999 внутри контейнера (drain / maint / ready при замене) scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey, s3 (~25 с); start api повторяет migrate и s3-bootstrap (no-op); уборщика не трогает — рестарт хранилищ он переживает сам scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG -scripts/rolling-update.sh # make rolling_update: предусловия (в том числе слоты LB без ручного состояния), сборка (или COMMIT через git archive), миграции один раз в контейнере сервиса migrate, по одной: новая UP в LB → старая drain → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/ +scripts/rolling-update.sh # make rolling_update: предусловия (в том числе слоты LB без ручного состояния), сборка (или COMMIT через git archive), миграции один раз в контейнере сервиса migrate, по одной: новая UP в LB → старая drain (до 90 с: дольше загрузки) → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/ Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck, MALLOC_MMAP_THRESHOLD_ (буфер загрузки растёт без копии) -docker-compose.yml # проект mtusi-lab4: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), migrate, s3-bootstrap, api × API_REPLICAS без портов, cleaner (уборщик: точка входа python -m src.cleaner, пул 1, ключи S3_CLEANER_*, без healthcheck), haproxy — единственный порт API; адреса и порты из .env, volumes postgres_data и s3_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env, x-s3-api-keys-env) +docker-compose.yml # проект mtusi-lab4: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), migrate, s3-bootstrap, api × API_REPLICAS без портов (sysctls: буфер приёма сокетов до 512 KiB), cleaner (уборщик: точка входа python -m src.cleaner, пул 1, ключи S3_CLEANER_*, без healthcheck), haproxy — единственный порт API; адреса и порты из .env, volumes postgres_data и s3_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env, x-s3-api-keys-env) .dockerignore config_example.toml, .env.example evidence/attachments/ # change attachments: smoke.md, failover.md (driver.py attachment-failover stop и kill), storage.md (driver.py attachment-storage), slow-transfer.md (10 MiB через LB дольше 6 с); change upload-consistency: consistency.md (driver.py upload-consistency и журналы API и уборщика), cleaner-process.md (старт, отказ конфигурации, остановка, окно 0, рестарт хранилищ, отказ S3 во время прохода) @@ -460,6 +483,7 @@ evidence/bench/<метка>/ # результаты make bench / bench_rest evidence/bench/scaling-*/ # серии трека 1 (a, b, pool, A/A scaling-aa, db — насыщение PostgreSQL; db4 — «до/после» пула без переполнения: scaling-db-aa*, -before*, -nooverflow*, окончательные — с суффиксом 2): паспорт с планом, бюджетом и лимитами по конфигурациям, runs.csv (строка на ступень), searches.csv (строка на ячейку), samples.csv (посекундно в окнах), summary.md, p95-by-rate.svg, cpu-by-component.svg, итоги k6 ступеней и журналы 5xx evidence/plots/scaling/ # make bench_plots по сериям a и b: графики SVG и summary.md (R*, эффективность, точка насыщения, цена запроса, память) evidence/plots/scaling-db/ # make bench_plots по серии db: R* по лимитам PostgreSQL и раздел «Насыщение PostgreSQL» +evidence/uploads/ # change upload-memory: <метка>/ — make bench_uploads (meta.json, runs.csv, summary.md, raw/), lb-timeouts.md — driver.py lb-upload-timeouts, rollout-upload.md — медленная загрузка во время make rolling_update evidence/compare/ # таблицы make bench_compare: <до>__<после>.md KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы ``` @@ -569,7 +593,9 @@ KNOWN_ISSUES.md # найденные попутно дефекты, - `Profile.rollout_from` в `bench/run.py` (профили `rollout`, `rollout_quick`) поменять на commit новой лабы до изменения, которое должна показать замена: commit этой лабы в истории новой нет, и - команда откажет до стенда (`bench.md`, профиль `rollout`). + команда откажет до стенда (`bench.md`, профиль `rollout`). Так же + `Profile.uploads_before` (профиль `uploads`, вариант «до»): commit новой + лабы до изменения, которое показывает профиль. - Сначала прочитать переходы API в `COURSE.md` и `contracts/README.md` нового skeleton, потом править код. Обновить этот файл: номер лабы, таблицу важных файлов, новые правила. diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index fff28711..ad3fbe34 100644 --- a/KNOWN_ISSUES.md +++ b/KNOWN_ISSUES.md @@ -21,3 +21,26 @@ (повтор с ограниченным сроком), и описать это в `docker.md`. Удобно разобрать в change `track2-reconciler`: там ошибки на стороне S3 вносятся намеренно. + +## LB отвечает 408 на медленные заголовки текстом HAProxy + +- **Где:** `infra/haproxy/haproxy.cfg`, `defaults`: `timeout + http-request 10s`, HAProxy 3.4.6. +- **Что:** клиент, который присылает заголовки запроса дольше 10 с, + получает от LB 408 со страницей HAProxy в HTML, а не ошибку в формате + контракта (`{"error": {...}}` с `request_id` = `X-Request-Id`). + `http-error status 408 … lf-string` его не меняет: такой ответ HAProxy + строит до потока запроса, где `http-error` уже не действует. Проба + change `upload-memory` (design, Context, п. 4; таблица «HAProxy, + сроки»): заголовки за 12 с — 408 HTML и с `http-error status 408`, и + без него. 400 посреди тела после change идёт в формате контракта. +- **Чем грозит:** клиент с медленной сетью на заголовках получает ответ + вне формата контракта. Путь загрузки и остальные пути API не + затронуты: заголовки приходят за миллисекунды. +- **Предложение:** `errorfile 408` со статичным JSON не годится: + `request_id` в нём один на все ответы, а контракт требует тот же id, + что в `X-Request-Id`, и уникальный. Варианты для разбора: проверить + `http-errors` / `errorloc` и Lua-ответ в новых версиях HAProxy 3.x; + либо поднять `timeout http-request` и назвать ограничение в + `REPORT.md` (уже названо в спеке `load-balancing`, «Ошибки + балансировщика в формате контракта»). diff --git a/Makefile b/Makefile index bdb54c2a..78f0d355 100644 --- a/Makefile +++ b/Makefile @@ -336,6 +336,24 @@ bench_rollout: bench_rollout_quick: $(KEEP_AWAKE) uv run python bench/run.py --profile rollout_quick --label quick-rollout-$(shell date -u +%Y%m%dT%H%M%SZ) +UPLOADS_LABEL ?= baseline + +# уровень 4 лабы 4: память реплики при одновременных загрузках на стенде +# mtusi-bench (HAProxy, одна реплика 1 CPU / 512 МБ без swap, S3 рабочего +# стенда): варианты «до» (Profile.uploads_before), «без лимита» и «с +# лимитом» × тела 1 и 10 MiB × 1/10/20/40 клиентов × 3 повтора, на каждый +# прогон — новые S3 и реплика; пик памяти окна, OOM, ответы по кодам, +# загрузок/с; ~50 мин; результат — evidence/uploads/$(UPLOADS_LABEL)/ +.PHONY: bench_uploads +bench_uploads: + $(KEEP_AWAKE) uv run python bench/run.py --profile uploads --label $(UPLOADS_LABEL) + +# то же коротко (самопроверка): «без лимита» и «с лимитом», 10 MiB, 1/10/40 +# клиентов, один повтор, ~5 мин; в git не идёт +.PHONY: bench_uploads_quick +bench_uploads_quick: + $(KEEP_AWAKE) uv run python bench/run.py --profile uploads_quick --label quick-uploads-$(shell date -u +%Y%m%dT%H%M%SZ) + SCALING_LABEL ?= scaling-$(SERIES) # уровень 5, трек 1 «Цена масштабирования»: серия на стенде mtusi-bench — diff --git a/PLAN.md b/PLAN.md index a35386ec..bbbd6aa0 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1015,6 +1015,34 @@ design, «Уточнения apply», п. 16–20; tasks, группа 11): 12. **Драйвер `lb-upload-timeouts`** (решение 7): сроки LB на заглушке за `haproxy.cfg` проекта. Evidence — `evidence/uploads/lb-timeouts.md`. +Приняты 2026-10-21 в `/opsx:apply` (подробности — design, «Уточнения +apply»; вопрос 1 открыт — сделано 429, как по умолчанию): + +13. **Красный прогон — 5 из 5** новых тестов отказов на `f894040` + (п. 2): `test_rejections_before_queue` проверяет и полноту очереди + (429 ожидавшей), `test_slot_released_after_failures` включает шаг + «400 по сроку тела» — оба поэтому красные на прежнем коде, а не + зелёные, как ждали tasks. На дереве — все пять зелёные. +14. **Тесты мест под срок тела стенда 2 с** (п. 1, 3): держатель места + отпускается сразу после 429 ожидавшей, сверка — «новые `id` — только + держателя»; ранние отказы быстрее срока ожидания (1 с), а не 0,5 с. +15. **Одна копия тела подтверждена до профиля**: PUT 10 MiB в образе API + против S3 стенда — 1,19 тела над базой против 2,31 у прежнего пути, + SHA-256 совпал. +16. **Тип мест в сервисе — под `TYPE_CHECKING`, `Retry-After` — таблица + `RETRY_AFTER` в `errors.py`, `UploadsBusy` журналирует сервис** (п. + 4–6). +17. **Драйвер `lb-upload-timeouts`** (п. 8): пять случаев параллельно, + ~33 с; код 0 на текущем `haproxy.cfg`, код 1 на `f894040` (502 и 504 + через 10 с, 400 HTML). +18. **Профиль `uploads`** (п. 10): разбор — `bench/uploads.py`; окно + памяти — весь прогон k6 со сбросом пика после разогрева; окружение + варианта — свой override, чтобы `stand.app_env` прежних профилей не + менялся; S3 перед прогоном — `kill` и новый volume. `uploads_quick` + на дереве: «с лимитом» при 40 × 10 MiB — пик 180 MiB, 429 вместо + 5xx; «без лимита» — OOM. Попутно исправлен сэмплер: каждый запуск + оставлял анонимный volume (удаление без `-v`). + #### Вопросы 1. Какой код отдавать, когда все места загрузки реплики заняты и @@ -1037,3 +1065,11 @@ design, «Уточнения apply», п. 16–20; tasks, группа 11): `Retry-After` остаётся), сценарии `attachments` и `api-conventions`, ожидания тестов и `REPORT.md`. Остальной design и задачи не меняются (design, решение 2). + + **Состояние на apply 2026-10-21:** ответа нет, сделано 429 + `rate_limited` с `Retry-After: 1` (поручение основной сессии). Строки, + которые поменяет ответ «503»: `DOMAIN_ERRORS` и `RETRY_AFTER` в + `src/api/errors.py`, `ERROR_CODES` и проверка `Retry-After` в + `student-tests/contract.py`, ожидания `test_upload_slots_busy` и + `test_rejections_before_queue`, сценарии спеков `attachments` и + `api-conventions`, правило `api-contract.md`. diff --git a/bench/bench.compose.yml b/bench/bench.compose.yml index 279a4b9a..26e5110e 100644 --- a/bench/bench.compose.yml +++ b/bench/bench.compose.yml @@ -43,14 +43,23 @@ services: memory: ${BENCH_CACHE_MEMORY:?run make bench} memswap_limit: ${BENCH_CACHE_MEMORY:?run make bench} - # S3 (лаба 4) описан, но профили лаб 2–3 его не запускают: старт стенда + # S3 (лаба 4) запускает только профиль uploads (design change + # upload-memory, решение 10): образ, аргументы сервера и лимиты рабочего + # стенда, swap = память; bucket и пользователей создаёт тот же + # s3-bootstrap. Профили лаб 2–3 его не запускают: старт стенда # перечисляет сервисы, а реплики API поднимает с --no-deps (design change - # s3-storage, решение 9). Если сервис всё же запустят — без порта хоста, - # без перезапуска и под своим именем + # s3-storage, решение 9). Без порта хоста, без перезапуска, под своим + # именем s3: container_name: mtusi-bench-s3 restart: "no" ports: !reset [] + deploy: + resources: + limits: + cpus: ${BENCH_S3_CPUS:?run make bench} + memory: ${BENCH_S3_MEMORY:?run make bench} + memswap_limit: ${BENCH_S3_MEMORY:?run make bench} # уборщик незавершённых загрузок (design change upload-consistency, # решение 9) описан, как s3, и тоже не запускается: старт стенда diff --git a/bench/bench.env b/bench/bench.env index e8d9d90d..e6ddaa0c 100644 --- a/bench/bench.env +++ b/bench/bench.env @@ -8,8 +8,8 @@ POSTGRES_HOST=postgres POSTGRES_PORT=5432 VALKEY_HOST=valkey VALKEY_PORT=6379 -# S3 описан в compose, но профили лаб 2–3 его не запускают; секреты S3 -# генерирует run.py +# S3 запускает только профиль uploads (лаба 4), профили лаб 2–3 — нет; +# секреты S3 генерирует run.py S3_HOST=s3 S3_PORT=8333 S3__BUCKET=bench diff --git a/bench/k6/uploads.js b/bench/k6/uploads.js new file mode 100644 index 00000000..8aedb4ad --- /dev/null +++ b/bench/k6/uploads.js @@ -0,0 +1,102 @@ +// Профиль загрузок (design change upload-memory, решение 10): CLIENTS VU +// загружают одно и то же тело PNG без пауз (constant-vus) через LB, пока +// оркестратор меряет память реплики. На 429 VU ждёт Retry-After, на прочие +// ошибки — секунду. Каждая загрузка — строка «up,,<итерация>, +// <отправка мс>,<длительность мс>,<статус>,» в файл консоли +// k6 (--console-output); setup() пишет «up-t0,<мс>» — начало нагрузки на +// часах ВМ: окно замера — [t0 + RAMP_S, t0 + RAMP_S + WINDOW_S). WARMUP=1 — +// одна разогревающая загрузка, она должна получить 201. +import exec from "k6/execution"; +import http from "k6/http"; +import { fail, sleep } from "k6"; + +import { + API, + SUMMARY_THRESHOLDS, + SUMMARY_TREND_STATS, + WORK_DIR, + summaryFiles, +} from "./lib.js"; + +const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`)); +// тело — файл рабочего каталога, его строит оркестратор (bench/uploads.py) +const BODY = open(`${WORK_DIR}/${__ENV.BODY}`, "b"); +const CLIENTS = Number(__ENV.CLIENTS || 1); +const RAMP_S = Number(__ENV.RAMP_S || 3); +const WINDOW_S = Number(__ENV.WINDOW_S || 20); +const WARMUP = __ENV.WARMUP === "1"; +// больше timeout server LB пути загрузки (30 с): клиент видит ответ LB +const TIMEOUT = "60s"; +const URL = `${API}/chats/${fixture.readChatId}/attachments?filename=bench.png`; +// идентификация — Bearer, как authHeaders() в lib.js, но тело — PNG, а не +// JSON +const HEADERS = { + Authorization: `Bearer ${fixture.tokens[fixture.readerId]}`, + "Content-Type": "image/png", +}; + +export const options = { + scenarios: { + upload: WARMUP + ? { executor: "per-vu-iterations", vus: 1, iterations: 1 } + : { + executor: "constant-vus", + vus: CLIENTS, + duration: `${RAMP_S + WINDOW_S}s`, + // начатая загрузка доходит до ответа: больше срока LB (30 с) и + // паузы после ответа — строк столько же, сколько итераций + gracefulStop: "45s", + }, + }, + summaryTrendStats: SUMMARY_TREND_STATS, + thresholds: { + ...SUMMARY_THRESHOLDS, + "iterations{scenario:upload}": ["count>=0"], + }, +}; + +export function setup() { + const t0 = Date.now(); + console.log(`up-t0,${t0}`); + return t0; +} + +// длительность — по монотонным таймингам k6; без ответа (status 0) — +// разность часов +function report(start, res) { + const instance = res.headers["X-Instance-Id"] || "-"; + const t = res.timings; + const measured = t.blocked + t.connecting + t.tls_handshaking + t.duration; + const duration = Math.max( + 0, + Math.round(res.status === 0 ? Date.now() - start : measured), + ); + console.log( + `up,${exec.vu.idInTest},${exec.vu.iterationInScenario},${start},` + + `${duration},${res.status},${instance}`, + ); +} + +export default function () { + const start = Date.now(); + const res = http.post(URL, BODY, { + headers: HEADERS, + responseType: "none", + timeout: TIMEOUT, + responseCallback: http.expectedStatuses(201), + }); + report(start, res); + if (WARMUP && res.status !== 201) { + fail(`warmup upload: ${res.status}`); + } + if (res.status === 429) { + const retry = Number(res.headers["Retry-After"]); + sleep(retry > 0 ? retry : 1); + } else if (res.status !== 201) { + sleep(1); + } +} + +export function handleSummary(data) { + return summaryFiles(data); +} diff --git a/bench/run.py b/bench/run.py index 6e9667d1..61835911 100644 --- a/bench/run.py +++ b/bench/run.py @@ -41,6 +41,7 @@ import plots import resources import rollout import scaling +import uploads ROOT = Path(__file__).resolve().parents[1] K6_IMAGE = ( @@ -66,6 +67,13 @@ APP_READY_PROBE = ( LB = "mtusi-bench-haproxy" DB = "mtusi-bench-postgres" CACHE = "mtusi-bench-valkey" +# S3 стенда (container_name в bench.compose.yml) и его volume: запускает +# только профиль uploads, volume пересоздаётся перед каждым прогоном +S3 = "mtusi-bench-s3" +S3_VOLUME = f"{PROJECT}_s3_data" +# окружение реплики по варианту профиля uploads: override поверх +# bench.compose.yml в рабочем каталоге метки +VARIANT_COMPOSE = "variant.compose.yml" K6 = "mtusi-bench-k6" # сэмплер серий трека 1: образ PostgreSQL стенда, --cgroupns host # (решение 7 design change scaling-bench) @@ -325,6 +333,25 @@ class Profile: # наблюдения, нагрузку и окна не меняет; лимиты и интервал сэмплера — # поля sampler_* ниже (design change profile-resources, решение 2) sample_resources: bool = False + # профиль загрузок (design change upload-memory, решение 10): варианты + # кода (bench/uploads.py, VARIANTS), commit образа «до», тела — имя и + # высота PNG из шума шириной 1024, число одновременных клиентов, разгон + # и окно прогона, окружение варианта «без лимита», интервал сэмплера + # peak. Лимиты S3 — у всех профилей (compose требует их при разборе), + # но S3 запускает только этот профиль + uploads_variants: tuple[str, ...] = () + uploads_before: str = "" + uploads_sizes: tuple[tuple[str, int], ...] = () + uploads_clients: tuple[int, ...] = () + uploads_ramp_s: int = 3 + uploads_window_s: int = 20 + uploads_unlimited_env: tuple[tuple[str, str], ...] = ( + ("UPLOADS__MAX_CONCURRENT", "1000"), + ("UPLOADS__MAX_WAITING", "0"), + ) + uploads_sample_interval_s: float = 0.2 + s3_cpus: str = "1" + s3_memory: str = "512m" # серии трека 1 (решения 1–6, 14 design change scaling-bench): имя # серии, конфигурации (реплик, CPU и память реплики, max_connections # PostgreSQL), чаты записи, смесь, фиксированные уровни, лестница и @@ -378,6 +405,10 @@ class Profile: def is_rollout(self) -> bool: return bool(self.rollout_from) + @property + def is_uploads(self) -> bool: + return bool(self.uploads_variants) + PROFILES = { "full": Profile( @@ -543,6 +574,53 @@ PROFILES = { rollout_after_s=8, sample_resources=True, ), + # память реплики при одновременных загрузках (уровень 4 лабы 4): одна + # реплика с лимитами рабочего стенда без swap, S3 рабочего стенда; три + # варианта кода × тела 1 и 10 MiB × 1/10/20/40 клиентов × 3 повтора, + # на каждый прогон — новые volume S3 и реплика. «До» — f894040, + # последний commit до change upload-memory. Design change + # upload-memory, решение 10 + "uploads": Profile( + name="uploads", + sizes=(), + concurrency=(), + repeats=3, + read_warmup_s=0, + read_measure_s=0, + write_warmup=0, + write_measure=0, + members=1, + cpus="1", + memory="512m", + db_cpus="2", + db_memory="1g", + cache_cpus="0.5", + cache_memory="128m", + uploads_variants=("before", "unlimited", "limited"), + uploads_before="f894040", + uploads_sizes=(("1MiB", 341), ("10MiB", 3409)), + uploads_clients=(1, 10, 20, 40), + ), + "uploads_quick": Profile( + name="uploads_quick", + sizes=(), + concurrency=(), + repeats=1, + read_warmup_s=0, + read_measure_s=0, + write_warmup=0, + write_measure=0, + members=1, + cpus="1", + memory="512m", + db_cpus="2", + db_memory="1g", + cache_cpus="0.5", + cache_memory="128m", + uploads_variants=("unlimited", "limited"), + uploads_sizes=(("10MiB", 3409),), + uploads_clients=(1, 10, 40), + ), } @@ -993,6 +1071,9 @@ def vm_warnings(profile: Profile) -> list[str]: extra = (profile.generator_memory, profile.sampler_memory) elif profile.sample_resources: extra = (profile.sampler_memory,) + elif profile.is_uploads: + # профиль загрузок: S3 и сэмплер peak + extra = (profile.s3_memory, profile.sampler_memory) limits = max(k * size_bytes(memory) for k, memory in replicas) + sum( size_bytes(value) for value in ( @@ -1072,6 +1153,9 @@ def static_passport(profile: Profile) -> dict[str, Any]: "docker": { "server": docker.get("ServerVersion"), "vm_os": docker.get("OperatingSystem"), + # ядро ВМ: сброс memory.peak через свой дескриптор — с 6.12 + # (профиль uploads) + "kernel": docker.get("KernelVersion"), "vm_cpus": docker.get("NCPU"), "vm_memory_gib": round(docker.get("MemTotal", 0) / 2**30, 1), "cgroup": docker.get("CgroupVersion"), @@ -1239,6 +1323,8 @@ def compose_env(profile: Profile) -> dict[str, str]: "BENCH_LB_CPUS": profile.lb_cpus, "BENCH_LB_MEMORY": profile.lb_memory, "BENCH_DB_MAX_CONNECTIONS": str(profile.db_max_connections), + "BENCH_S3_CPUS": profile.s3_cpus, + "BENCH_S3_MEMORY": profile.s3_memory, } @@ -1282,10 +1368,16 @@ class Stand: self.label_dir = label_dir self.work_dir = label_dir / ".work" self.env = compose_env(profile) + # профиль uploads: override окружения реплики по варианту + self.extra_files: list[Path] = [] def compose(self, *args: str, check: bool = True) -> str: """docker compose стенда; без `-p mtusi-bench` не вызывается.""" - files = [arg for path in COMPOSE_FILES for arg in ("-f", str(path))] + files = [ + arg + for path in (*COMPOSE_FILES, *self.extra_files) + for arg in ("-f", str(path)) + ] proc = subprocess.run( [ "docker", @@ -1484,6 +1576,11 @@ class Stand: say("postgres and valkey healthy") self.compose("run", "--rm", "migrate") say("migrations applied") + if self.profile.is_uploads: + # S3 — только профиль загрузок (design change upload-memory, + # решение 10); прочие профили его не запускают + self.start_s3() + say("s3 healthy, bootstrap done") self.compose( "up", "-d", @@ -1529,6 +1626,189 @@ class Stand: self.wait_ready() say(f"{self.profile.replicas} api replicas UP behind haproxy") + def start_s3(self) -> None: + """S3 стенда и его bootstrap: `up --wait s3`, затем код выхода + bootstrap отдельным `up --exit-code-from` (`--wait` одноразовый + сервис считает готовым уже запущенным, как `make start_s3`).""" + self.compose("up", "-d", "--wait", "s3") + self.compose( + "up", + "--no-deps", + "--exit-code-from", + "s3-bootstrap", + "s3-bootstrap", + ) + + def recycle_uploads(self, image: str, env: dict[str, str]) -> None: + """Перед прогоном профиля загрузок (решение 10): новый volume S3 с + bootstrap и новый контейнер реплики на образе варианта `image` с + окружением `env` (override `VARIANT_COMPOSE`), затем готовность + процесса и `UP` в LB. + + S3 останавливается `kill`, а не плавно (~15 с): его volume всё + равно удаляется. Реплика — сначала удаляется: новый контейнер + может получить тот же адрес, и LB держал бы слот `UP` от прежнего + (поэтому, как в `switch_api`, сначала готовность процесса).""" + self.compose("rm", "-s", "-f", APP_SERVICE, check=False) + self.compose("kill", "s3", "s3-bootstrap", check=False) + self.compose("rm", "-f", "s3", "s3-bootstrap") + subprocess.run( + ["docker", "volume", "rm", S3_VOLUME], + capture_output=True, + check=False, + ) + if S3_VOLUME in sh("docker", "volume", "ls", "-q").split(): + raise BenchError(f"volume {S3_VOLUME} was not removed") + self.start_s3() + sh("docker", "tag", image, APP_IMAGE) + path = self.work_dir / VARIANT_COMPOSE + self.extra_files = [] + if env: + lines = ["services:", " api:", " environment:"] + lines += [f' {key}: "{value}"' for key, value in env.items()] + path.write_text("\n".join(lines) + "\n", encoding="utf-8") + self.extra_files = [path] + self.compose( + "up", + "-d", + "--no-deps", + "--no-build", + "--force-recreate", + APP_SERVICE, + ) + self.wait_processes_ready() + self.wait_ready() + + def app_env(self, name: str) -> dict[str, str]: + """Окружение приложения контейнера без секретов: параметры в + формате настроек (`SECTION__FIELD`), без паролей, секрета и ключа + доступа S3.""" + env = json.loads( + sh("docker", "inspect", "-f", "{{json .Config.Env}}", name), + ) + return dict( + sorted( + item.split("=", 1) + for item in env + if re.match(r"[A-Z0-9_]+__[A-Z0-9_]+=", item) + and not any( + mark in item.split("=", 1)[0] for mark in SECRET_ENV_MARKS + ) + ), + ) + + def tcp_rmem(self, name: str) -> str | None: + """Буфер приёма сокетов контейнера (`net.ipv4.tcp_rmem`: мин., + начальный, наибольший): у реплик — из `sysctls` сервиса `api` + (design change `upload-memory`, решение 6).""" + value = sh( + "docker", + "exec", + name, + "cat", + "/proc/sys/net/ipv4/tcp_rmem", + check=False, + ) + return " ".join(value.split()) or None + + def start_peak_sampler(self, name: str, targets: dict[str, str]) -> None: + """Сэмплер прогона профиля загрузок в режиме `peak`: `--user 0`, + cgroupfs на запись (сброс `memory.peak` через свой дескриптор), + `--network none`, без метки проекта и паролей. Готов — когда для + каждой роли записан итог сброса и есть первая выборка.""" + p = self.profile + image = sh("docker", "inspect", "-f", "{{.Config.Image}}", DB) + for suffix in (".log", ".stop"): + (self.work_dir / f"{name}{suffix}").unlink(missing_ok=True) + proc = subprocess.run( + [ + "docker", + "run", + "-d", + "--name", + SAMPLER, + "--user", + "0", + "--cgroupns", + "host", + "--network", + "none", + "--cpus", + p.sampler_cpus, + "--memory", + p.sampler_memory, + "--memory-swap", + p.sampler_memory, + "-v", + "/sys/fs/cgroup:/sys/fs/cgroup:rw", + "-v", + f"{SAMPLER_SCRIPT}:/sampler.sh:ro", + "-v", + f"{self.work_dir}:/work", + "--entrypoint", + "bash", + image, + "/sampler.sh", + f"{p.uploads_sample_interval_s:g}", + "peak", + name, + *(f"{role}={ident}" for role, ident in targets.items()), + ], + capture_output=True, + text=True, + check=False, + ) + if proc.returncode != 0: + raise BenchError(f"peak sampler did not start: {proc.stderr}") + path = self.work_dir / f"{name}.log" + deadline = time.monotonic() + 5 + while time.monotonic() < deadline: + time.sleep(0.2) + text = path.read_text(encoding="utf-8") if path.exists() else "" + parsed = uploads.parse_peak(text) + if all( + role in parsed.roles and parsed.roles[role].samples + for role in targets + ) and text.count("reset ") >= len(targets): + return + tail = sh("docker", "logs", "--tail", "5", SAMPLER, check=False) + raise BenchError(f"peak sampler: no samples in 5s\n{tail}") + + def stop_peak_sampler(self, name: str) -> str: + """Конец окна: файл остановки, сэмплер читает пики и выходит; + возвращает его строки и удаляет контейнер.""" + (self.work_dir / f"{name}.stop").touch() + deadline = time.monotonic() + 15 + while time.monotonic() < deadline: + running = sh( + "docker", + "inspect", + "-f", + "{{.State.Running}}", + SAMPLER, + check=False, + ) + if running != "true": + break + time.sleep(0.2) + self.stop_sampler() + path = self.work_dir / f"{name}.log" + return path.read_text(encoding="utf-8") if path.exists() else "" + + def exit_state(self, name: str) -> dict[str, Any]: + """Состояние контейнера после прогона: работает ли, убит ли из-за + памяти и код выхода.""" + state = json.loads( + sh("docker", "inspect", "-f", "{{json .State}}", name), + ) + return { + "running": bool(state.get("Running")), + "oom_killed": bool(state.get("OOMKilled")), + "exit_code": None + if state.get("Running") + else state.get("ExitCode"), + } + def replicas(self, *, stopped: bool = False) -> list[str]: """Имена контейнеров реплик api по порядку; `stopped` — и остановленные.""" @@ -1591,8 +1871,10 @@ class Stand: контейнер не из compose не дал бы compose удалить сеть. Volume восстановления compose не знает, он удаляется отдельно. """ + # -v — анонимные volume образа (у сэмплера — /var/lib/postgresql); + # именованный volume восстановления удаляется ниже отдельно subprocess.run( - ["docker", "rm", "-f", K6, SAMPLER, RESTORE_DB], + ["docker", "rm", "-f", "-v", K6, SAMPLER, RESTORE_DB], capture_output=True, check=False, ) @@ -1694,6 +1976,8 @@ class Stand: """ replicas = self.replicas() roles = {APP_SERVICE: replicas[0], **CONTAINERS, "k6": K6} + if self.profile.is_uploads: + roles["s3"] = S3 limits: dict[str, Any] = {} for role, name in roles.items(): limits[role] = self.container_limits(name) @@ -1950,8 +2234,11 @@ class Stand: return texts[0], texts[1] def stop_sampler(self) -> None: + # -v: сэмплер — на образе PostgreSQL, у него volume образа + # /var/lib/postgresql; без -v каждый запуск оставлял бы анонимный + # volume (найдено в apply change upload-memory) subprocess.run( - ["docker", "rm", "-f", SAMPLER], + ["docker", "rm", "-f", "-v", SAMPLER], capture_output=True, check=False, ) @@ -2186,26 +2473,9 @@ class Stand: "-c", 'exec valkey-cli -p "$VALKEY_PORT" CONFIG GET "maxmemory*"', ).splitlines() - env = json.loads( - sh( - "docker", - "inspect", - "-f", - "{{json .Config.Env}}", - self.replicas()[0], - ), - ) + replica = self.replicas()[0] # без секретов: пароли хранилищ, секрет и ключ доступа S3 - app_env = dict( - sorted( - item.split("=", 1) - for item in env - if re.match(r"[A-Z0-9_]+__[A-Z0-9_]+=", item) - and not any( - mark in item.split("=", 1)[0] for mark in SECRET_ENV_MARKS - ) - ), - ) + app_env = self.app_env(replica) def image(name: str) -> dict[str, str]: return { @@ -2219,7 +2489,16 @@ class Stand: "id": sh("docker", "inspect", "-f", "{{.Image}}", name), } + extra: dict[str, Any] = {} + if self.profile.is_uploads: + # S3 — только у профиля загрузок; образ и аргументы — рабочего + # стенда + extra["s3"] = image(S3) return { + **extra, + # буфер приёма сокетов реплики: sysctls сервиса api (design + # change upload-memory, решение 6), одинаков у всех профилей + "api_tcp_rmem": self.tcp_rmem(replica), "postgres": { **image(DB), "version": self.psql("SHOW server_version;\n"), @@ -2914,6 +3193,12 @@ class Results: self.runs.append(row) self.append("runs.csv", RUN_FIELDS, row) + def add_upload(self, row: dict[str, Any]) -> None: + """Прогон профиля загрузок — строка `runs.csv` (столбцы + `uploads.RUN_FIELDS`).""" + self.runs.append(row) + self.append("runs.csv", uploads.RUN_FIELDS, row) + def add_prefill(self, row: dict[str, Any]) -> None: self.prefill.append(row) self.append("prefill.csv", PREFILL_FIELDS, row) @@ -2969,7 +3254,9 @@ class Results: (self.dir / "summary.md").write_text(text, encoding="utf-8") plots.render_series(self.dir) return - if self.meta["profile"].get("rollout_from"): + if self.meta["profile"].get("uploads_variants"): + text = uploads.render_summary(self.meta, self.runs) + elif self.meta["profile"].get("rollout_from"): text = rollout.render_summary( self.meta, self.rollout, @@ -3250,6 +3537,14 @@ class Bench: if profile.is_series: # серия трека 1 — ячейки: конфигурация × повтор self.runs_total = len(profile.configs) * profile.repeats + if profile.is_uploads: + # профиль загрузок — вариант × тело × клиенты × повтор + self.runs_total = ( + len(profile.uploads_variants) + * len(profile.uploads_sizes) + * len(profile.uploads_clients) + * profile.repeats + ) self.runs_done = 0 # серии: ячейка и попытка текущей ступени, длительности ячеек, # номер ступени в метке (столбец run) @@ -3289,6 +3584,11 @@ class Bench: def eta(self) -> float: p = self.profile + if p.is_uploads: + # прогон: смена S3 и реплики (~15 с), разгон, окно, остаток + per_run = 20 + p.uploads_ramp_s + p.uploads_window_s + left = (self.runs_total - self.runs_done) * per_run + return left + (0 if self.prepared else 90) if p.is_series: # ячейка ≈ 5–6 мин (решение 5), затем среднее снятых per_cell = ( @@ -3370,6 +3670,9 @@ class Bench: # --------------------------------------------------------- этапы def run(self) -> None: + if self.profile.is_uploads: + self.run_uploads() + return if self.profile.is_series: self.run_series() return @@ -5099,6 +5402,210 @@ class Bench: # ---------------------------------------------- серии трека 1 + # --------------------------------------------- профиль загрузок + + def run_uploads(self) -> None: + """Профиль загрузок (design change `upload-memory`, решение 10): + образы вариантов, тела, план кругами, стенд с S3, пользователь и + чат, затем прогоны — на каждый новые volume S3 и реплика.""" + p = self.profile + stand = self.stand + meta = self.results.meta + info: dict[str, Any] = meta.setdefault("uploads", {}) + checkout = meta["app_image"]["id"] + images = {"unlimited": checkout, "limited": checkout} + if "before" in p.uploads_variants: + self.stage = "before image" + commit = sh( + "git", + "-C", + str(ROOT), + "rev-parse", + "--short", + f"{p.uploads_before}^{{commit}}", + ) + info["before_commit"] = commit + images["before"] = stand.build_from(commit) + self.say( + f"uploads: image of {commit} built ({images['before'][:19]}…)", + ) + info["images"] = {v: images[v] for v in p.uploads_variants} + bodies = uploads.build_bodies(p.uploads_sizes, p.seed) + heights = dict(p.uploads_sizes) + info["bodies"] = { + name: uploads.body_passport(name, heights[name], data) + for name, data in bodies.items() + } + stand.work_dir.mkdir(parents=True, exist_ok=True) + for name, data in bodies.items(): + (stand.work_dir / f"body-{name}.png").write_bytes(data) + plan = uploads.plan_runs( + p.uploads_variants, + [name for name, _ in p.uploads_sizes], + p.uploads_clients, + p.repeats, + p.order_seed, + ) + info["plan"] = plan + info["app_env"] = {} + self.runs_total = len(plan) + self.results.write_meta() + # стенд на образе checkout: миграции, пользователь и вход по Basic + # (Argon2id) — до первого окна; PostgreSQL и пользователь — на всю + # метку, а реплика окна — всегда новая + self.stage = "start" + stand.start(lambda text: self.say(f"uploads: {text}")) + meta["limits"] = stand.limits() + meta["stand"] = stand.passport() + self.results.write_meta() + stand.k6( + "prepare.js", + {"MEMBERS": p.members, "BACKGROUND": "", "WRITE_CHATS": 1}, + ) + self.prepared = True + self.say( + f"uploads: {len(plan)} runs planned " + f"({len(p.uploads_variants)} variants × " + f"{len(p.uploads_sizes)} bodies × {len(p.uploads_clients)} " + f"levels × {p.repeats})", + ) + try: + for run in plan: + self.run_upload(run, images[run["variant"]], bodies) + self.runs_done += 1 + finally: + # тег стенда — снова образ checkout + sh("docker", "tag", checkout, APP_IMAGE, check=False) + stand.extra_files = [] + + def run_upload( + self, + run: dict[str, Any], + image: str, + bodies: dict[str, bytes], + ) -> None: + """Один прогон: новые S3 и реплика варианта, разогревающая + загрузка, сэмплер `peak` (сброс пика перед нагрузкой), k6 + `constant-vus`, затем пики, состояние реплики и строка + `runs.csv`. Реплика, убитая из-за памяти, — пометка `oom`, а не + сбой команды.""" + p = self.profile + stand = self.stand + name = run["run"] + info = self.results.meta["uploads"] + self.stage = name + self.progress() + env = ( + dict(p.uploads_unlimited_env) + if run["variant"] == "unlimited" + else {} + ) + stand.recycle_uploads(image, env) + replica = stand.replicas()[0] + if run["variant"] not in info["app_env"]: + info["app_env"][run["variant"]] = stand.app_env(replica) + self.results.write_meta() + body = f"body-{run['size']}.png" + # разогрев: одна загрузка 201 до окна (соединения, модели botocore) + stand.k6("uploads.js", {"BODY": body, "WARMUP": 1}) + targets = { + "api": stand.full_id(replica), + "s3": stand.full_id(S3), + "haproxy": stand.full_id(LB), + } + swap_before = swapouts() + stand.start_peak_sampler(name, targets) + log_name = f"{name}.log.k6" + load: subprocess.Popen[bytes] | None = None + peak_text = "" + try: + load = stand.k6_console( + "uploads.js", + { + "BODY": body, + "CLIENTS": run["clients"], + "RAMP_S": p.uploads_ramp_s, + "WINDOW_S": p.uploads_window_s, + "NAME": f"{name}-k6", + }, + log_name, + ) + load.wait(timeout=p.uploads_ramp_s + p.uploads_window_s + 180) + finally: + if load is not None and load.poll() is None: + load.kill() + peak_text = stand.stop_peak_sampler(name) + (self.results.dir / "raw" / f"{name}-peak.log").write_text( + peak_text, + encoding="utf-8", + ) + if load.returncode != 0: + tail = (stand.work_dir / f"{log_name}.out").read_text( + encoding="utf-8", + errors="replace", + )[-3000:] + raise BenchError( + f"{name}: k6 uploads.js failed ({load.returncode}):\n{tail}", + ) + swap_after = swapouts() + down = stand.down_storages() + if down: + raise BenchError(f"{name}: storage died: {', '.join(down)}") + state = stand.exit_state(replica) + s3_state = stand.exit_state(S3) + state["s3_down"] = not s3_state["running"] or s3_state["oom_killed"] + text = (stand.work_dir / log_name).read_text( + encoding="utf-8", + errors="replace", + ) + t0, ups = uploads.parse_k6(text) + k6_data = json.loads( + (self.results.dir / "raw" / f"{name}-k6.json").read_text( + encoding="utf-8", + ), + ) + iterations = ( + k6_data["metrics"] + .get("iterations{scenario:upload}", {}) + .get("values", {}) + .get("count") + ) + if t0 is None or iterations != len(ups): + raise BenchError( + f"{name}: {len(ups)} k6 upload lines, {iterations} " + f"iterations, t0 {t0}", + ) + stats = uploads.k6_stats( + ups, + t0, + p.uploads_ramp_s, + p.uploads_window_s, + ) + swapped = ( + None + if swap_before is None or swap_after is None + else swap_after - swap_before + ) + row = uploads.run_row( + run, + len(bodies[run["size"]]), + uploads.parse_peak(peak_text), + stats, + state, + swapped, + ) + self.results.add_upload(row) + fives = sum(stats[f"s{code}"] for code in (502, 503, 504)) + self.say( + f"{name} ({run['order']}/{self.runs_total}): before " + f"{row['mem_before_mib']} MiB, peak {row['peak_mib']} MiB " + f"({row['peak_source']}), sock {row['sock_max_mib']} MiB, 201 " + f"{stats['s201']}, 429 {stats['s429']}, 5xx {fives}, conn " + f"{stats['s_conn_error']}, {stats['uploads_per_s']}/s, p95 " + f"{stats['p95_ms']} ms{' OOM' if 'oom' in row['flags'] else ''}", + ) + self.progress(last={"run": name, "flags": row["flags"]}) + def run_series(self) -> None: """Серия трека 1 (решения 4–5 design change `scaling-bench`): план ячеек кругами — в паспорт до первой ячейки; при продолжении @@ -5698,10 +6205,14 @@ def resume_problems( return found -def rollout_commit_problem(commit: str) -> str | None: - """Commit прежнего образа профиля замены есть в истории; иначе — - сообщение с commit и подменой `--from` (design change `attachments`, - решение 14).""" +def rollout_commit_problem( + commit: str, + field: str = "rollout_from", + kind: str = "rollout", +) -> str | None: + """Commit прежнего образа профиля замены (или варианта «до» профиля + загрузок) есть в истории; иначе — сообщение с commit и подменой + `--from` (design change `attachments`, решение 14).""" found = subprocess.run( [ "git", @@ -5719,8 +6230,8 @@ def rollout_commit_problem(commit: str) -> str | None: if found.returncode == 0: return None return ( - f"rollout commit {commit!r} is not in this repository history: " - "update Profile.rollout_from (.claude/rules/bench.md) or pass " + f"{kind} commit {commit!r} is not in this repository history: " + f"update Profile.{field} (.claude/rules/bench.md) or pass " "--from for debugging" ) @@ -5746,11 +6257,18 @@ def apply_overrides( raise SystemExit(f"--modes {args.modes}: failover profiles only") overrides["failover_modes"] = modes if args.rollout_from: - if not profile.is_rollout: + if profile.is_uploads: + overrides["uploads_before"] = args.rollout_from + elif not profile.is_rollout: raise SystemExit( - f"--from {args.rollout_from}: rollout profiles only", + f"--from {args.rollout_from}: rollout and uploads profiles " + "only", ) - overrides["rollout_from"] = args.rollout_from + else: + overrides["rollout_from"] = args.rollout_from + if args.concurrency and profile.is_uploads: + # профиль загрузок: число клиентов, а не уровни матрицы + overrides["uploads_clients"] = overrides.pop("concurrency") if args.fixed: if not profile.is_series: raise SystemExit(f"--fixed {args.fixed}: track 1 series only") @@ -5783,6 +6301,17 @@ def main(argv: list[str]) -> int: if problem: print(problem, flush=True) return 2 + if profile.is_uploads and "before" in profile.uploads_variants: + # commit варианта «до» — тоже до стенда (спек load-benchmark, + # «Профиль загрузок») + problem = rollout_commit_problem( + profile.uploads_before, + "uploads_before", + "uploads «before»", + ) + if problem: + print(problem, flush=True) + return 2 # профиль отказа реплик — доказательство уровня 4, рядом с прогонами # make test-failover (решение 7 design change graceful-failover) kind = "failover" if profile.is_failover else "bench" @@ -5790,6 +6319,10 @@ def main(argv: list[str]) -> int: # поочерёдная замена — доказательство уровня 4 (решение 8 design # change rolling-update) kind = "rollout" + if profile.is_uploads: + # память загрузок — доказательство уровня 4 лабы 4 (design change + # upload-memory, решение 10) + kind = "uploads" label_dir = ROOT / "evidence" / kind / args.label relative = label_dir.relative_to(ROOT) if label_dir.exists() and not args.resume: diff --git a/bench/sampler.sh b/bench/sampler.sh index f14627a3..1a15983b 100644 --- a/bench/sampler.sh +++ b/bench/sampler.sh @@ -23,6 +23,17 @@ # `cg <нс> - …` на каждый; роли назначает оркестратор. Строки # vm — как в list. Ни psql, ни опроса LB: наблюдатель не обращается к # стенду. +# peak (профиль uploads, design change upload-memory, решение 10): +# <интервал, с> peak <имя> <роль>=<полный id контейнера>… +# Контейнер без сети, --user 0, cgroupfs на запись. perl открывает +# memory.peak каждого контейнера на чтение и запись, пишет его прежнее +# значение (`start <роль> <байт>`) и сбрасывает пик записью в свой +# дескриптор (ядро ≥ 6.12): `reset <роль> ok|failed`. Раз в интервал — +# `pk <нс> <роль> ` +# (`anon`, `sock` — memory.stat, `oom_kill` — memory.events) или +# `pk <нс> <роль> missing`. Появился /work/<имя>.stop — perl +# читает пик через тот же дескриптор (`peak <роль> <байт>|missing`), +# строка `end <нс>`, выход 0. Всё — в /work/<имя>.log. set -u interval=$1 @@ -31,6 +42,10 @@ mode=list if [[ ${1:-} == scan ]]; then mode=scan shift +elif [[ ${1:-} == peak ]]; then + mode=peak + name=$2 + shift 2 fi roles=() ids=() @@ -68,6 +83,85 @@ FROM pg_stat_io WHERE object = 'wal' SQL fi +if [[ $mode == peak ]]; then + log=/work/$name.log + stop=/work/$name.stop + : >"$log" + exec 4>>"$log" + # пик через свой дескриптор: сброс и чтение — в одном процессе perl, bash + # позиционировать дескриптор не умеет + perl -e ' + use strict; + my ($stop, @targets) = @ARGV; + $| = 1; + my %fh; + for my $t (@targets) { + my ($role, $id) = split /=/, $t, 2; + my $path = "/sys/fs/cgroup/docker/$id/memory.peak"; + my $h; + if (!open($h, "+<", $path)) { + print "start $role missing\nreset $role failed open\n"; + next; + } + my $old = ""; + sysread($h, $old, 64); + chomp $old; + print "start $role ", ($old =~ /^\d+$/ ? $old : "missing"), "\n"; + sysseek($h, 0, 0); + if (defined syswrite($h, "reset")) { + print "reset $role ok\n"; + $fh{$role} = $h; + } else { + print "reset $role failed $!\n"; + } + } + select(undef, undef, undef, 0.05) until -e $stop; + for my $role (sort keys %fh) { + my $h = $fh{$role}; + my $value = ""; + if (sysseek($h, 0, 0) && sysread($h, $value, 64)) { + chomp $value; + } + print "peak $role ", ($value =~ /^\d+$/ ? $value : "missing"), "\n"; + } + ' "$stop" "$@" >&4 & + perl_pid=$! + + pk_line() { + local role=$1 id=$2 dir=/sys/fs/cgroup/docker/$2 + local key val mem= anon= sock= oom= + { + read -r mem <"$dir/memory.current" + while read -r key val; do + case $key in + anon) anon=$val ;; + sock) sock=$val ;; + esac + done <"$dir/memory.stat" + while read -r key val; do + [[ $key == oom_kill ]] && oom=$val + done <"$dir/memory.events" + } 2>/dev/null + if [[ -z $mem || -z $anon || -z $sock || -z $oom ]]; then + printf 'pk %s %s %s missing\n' "$ns" "$role" "${id:0:12}" >&4 + return + fi + printf 'pk %s %s %s %s %s %s %s\n' "$ns" "$role" "${id:0:12}" \ + "$mem" "$anon" "$sock" "$oom" >&4 + } + + while [[ ! -e $stop ]]; do + ns=${EPOCHREALTIME/./}000 + for i in "${!ids[@]}"; do + pk_line "${roles[$i]}" "${ids[$i]}" + done + sleep "$interval" + done + wait "$perl_pid" + printf 'end %s\n' "${EPOCHREALTIME/./}000" >&4 + exit 0 +fi + exec 4>>/work/samples.log cg_line() { diff --git a/bench/uploads.py b/bench/uploads.py new file mode 100644 index 00000000..5647d2ec --- /dev/null +++ b/bench/uploads.py @@ -0,0 +1,974 @@ +"""Профиль загрузок: тела, план, разбор и сводка без docker. + +Оркестрирует прогоны `run.py` (профили `uploads`, `uploads_quick`), здесь +— чистые функции на stdlib: PNG из шума на `random.Random(seed)`, план +прогонов кругами, строки k6 о каждой загрузке, строки сэмплера в режиме +`peak`, строка `runs.csv`, сводка по ячейкам и проверка гипотез H1–H4. +Методика — design change `upload-memory`, решение 10; правило — +`.claude/rules/bench.md`, «Профиль загрузок». Проверка — +`uv run python bench/uploads.py --selftest`. +""" + +import hashlib +import random +import re +import statistics +import struct +import sys +import zlib +from collections.abc import Iterable +from dataclasses import dataclass, field +from typing import Any + +# лимит тела контракта (contracts/README.md, «Вложения (с lab4)») +MAX_BODY_BYTES = 10 * 1024 * 1024 +MIB = 2**20 +# ширина PNG из шума: строка 1024 × 3 байта RGB и байт фильтра +PNG_WIDTH = 1024 +PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n" +# варианты кода (решение 10): образ commit до change, checkout без лимита, +# checkout с параметрами по умолчанию +VARIANTS = ("before", "unlimited", "limited") +VARIANT_NAMES = { + "before": "до", + "unlimited": "без лимита", + "limited": "с лимитом", +} +# коды ответов в runs.csv; 0 — ошибка соединения (ответа нет) +CODES = (201, 429, 400, 413, 415, 502, 503, 504, 0) +CODE_FIELDS = [f"s{code}" if code else "s_conn_error" for code in CODES] + +RUN_FIELDS = [ + "run", + "variant", + "size", + "body_bytes", + "clients", + "repeat", + "order", + "mem_before_mib", + "start_peak_mib", + "peak_mib", + "peak_source", + "anon_max_mib", + "sock_max_mib", + "oom_kill", + "exit_code", + "oom_killed", + *CODE_FIELDS, + "s_other", + "requests", + "window_s", + "uploads_per_s", + "p50_ms", + "p95_ms", + "p99_ms", + "s3_peak_mib", + "s3_anon_max_mib", + "lb_peak_mib", + "lb_sock_max_mib", + "host_swapouts", + "flags", +] + + +# ---------------------------------------------------------------- тела + + +def chunk(kind: bytes, body: bytes) -> bytes: + """Чанк PNG с верной CRC.""" + crc = zlib.crc32(kind + body) + return struct.pack(">I", len(body)) + kind + body + struct.pack(">I", crc) + + +def png_noise(height: int, seed: int, width: int = PNG_WIDTH) -> bytes: + """Настоящий RGB PNG из шума `random.Random(seed)`: строки с фильтром + 0, IDAT — zlib уровня 1 (шум не сжимается, размер ≈ width × height × + 3). Один `seed` — одни и те же байты.""" + noise = random.Random(seed) + rows = b"".join( + b"\x00" + noise.randbytes(width * 3) for _ in range(height) + ) + ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0) + return ( + PNG_SIGNATURE + + chunk(b"IHDR", ihdr) + + chunk(b"IDAT", zlib.compress(rows, 1)) + + chunk(b"IEND", b"") + ) + + +def build_bodies( + sizes: Iterable[tuple[str, int]], + seed: int, +) -> dict[str, bytes]: + """Тела профиля: имя размера → PNG высоты из профиля; зерно тела — + `seed` + высота: у полного и быстрого профиля тело одного размера — + одни и те же байты. Больше лимита контракта — отказ: такое тело + получало бы 413, а не нагружало память.""" + bodies = {} + for name, height in sizes: + data = png_noise(height, seed + height) + if len(data) > MAX_BODY_BYTES: + raise ValueError( + f"body {name}: {len(data)} bytes > {MAX_BODY_BYTES}", + ) + bodies[name] = data + return bodies + + +def body_passport(name: str, height: int, data: bytes) -> dict[str, Any]: + return { + "size": name, + "width": PNG_WIDTH, + "height": height, + "bytes": len(data), + "mib": round(len(data) / MIB, 3), + "sha256": hashlib.sha256(data).hexdigest(), + } + + +# ---------------------------------------------------------------- план + + +def plan_runs( + variants: Iterable[str], + sizes: Iterable[str], + clients: Iterable[int], + repeats: int, + seed: int, +) -> list[dict[str, Any]]: + """Прогоны кругами: в круге r — перестановка ячеек (вариант × размер + × клиенты) генератором `Random(seed + r)`; круг не начинается с ячейки, + на которой кончился прежний (как `scaling.plan_cells`).""" + cells = [ + (variant, size, count) + for variant in variants + for size in sizes + for count in clients + ] + plan: list[dict[str, Any]] = [] + previous = None + for round_no in range(1, repeats + 1): + order = list(range(len(cells))) + random.Random(seed + round_no).shuffle(order) + if len(order) > 1 and order[0] == previous: + order[0], order[1] = order[1], order[0] + for index in order: + variant, size, count = cells[index] + plan.append( + { + "run": f"{variant}-{size}-c{count}-r{round_no}", + "variant": variant, + "size": size, + "clients": count, + "repeat": round_no, + "order": len(plan) + 1, + }, + ) + previous = order[-1] + return plan + + +# ------------------------------------------------------------ строки k6 + + +T0_RE = re.compile(r"\bup-t0,(?P\d+)") +UPLOAD_RE = re.compile( + r"\bup,(?P\d+),(?P\d+),(?P\d+)," + r"(?P\d+),(?P\d+),(?P[A-Za-z0-9._-]+)", +) + + +@dataclass(frozen=True) +class Upload: + """Одна загрузка: отправка (мс часов ВМ), длительность, статус.""" + + vu: int + start_ms: int + duration_ms: int + status: int + instance: str + + +def parse_k6(text: str) -> tuple[int | None, list[Upload]]: + """Строки `uploads.js`: `up-t0,<мс>` из setup и `up,,<итерация>, + <отправка>,<длительность>,<статус>,` на каждую + загрузку. Строки консоли k6 обёрнуты в его формат — ищется начало + `up`.""" + t0 = None + uploads = [] + for line in text.splitlines(): + if match := T0_RE.search(line): + t0 = int(match["t0"]) + elif match := UPLOAD_RE.search(line): + uploads.append( + Upload( + vu=int(match["vu"]), + start_ms=int(match["start"]), + duration_ms=int(match["duration"]), + status=int(match["status"]), + instance=match["instance"], + ), + ) + return t0, uploads + + +def percentile(values: list[float], q: float) -> float | None: + """Перцентиль с линейной интерполяцией (как p(N) k6).""" + if not values: + return None + ordered = sorted(values) + pos = (len(ordered) - 1) * q + low = int(pos) + high = min(low + 1, len(ordered) - 1) + return ordered[low] + (ordered[high] - ordered[low]) * (pos - low) + + +def k6_stats( + uploads: list[Upload], + t0: int, + ramp_s: float, + window_s: float, +) -> dict[str, Any]: + """Ответы по кодам — за весь прогон (разгон и окно, в том числе после + гибели реплики); загрузок 201 в секунду и перцентили успешных — по + загрузкам, отправленным в окне `[t0 + ramp, t0 + ramp + window)`.""" + counts = dict.fromkeys(CODE_FIELDS, 0) + other = 0 + for item in uploads: + if item.status in CODES: + key = f"s{item.status}" if item.status else "s_conn_error" + counts[key] += 1 + else: + other += 1 + w0 = t0 + ramp_s * 1000 + w1 = w0 + window_s * 1000 + ok = [ + item.duration_ms + for item in uploads + if item.status == 201 and w0 <= item.start_ms < w1 + ] + + def ms(value: float | None) -> float | None: + return None if value is None else round(value, 1) + + return { + **counts, + "s_other": other, + "requests": len(uploads), + "window_s": window_s, + "uploads_per_s": round(len(ok) / window_s, 2), + "p50_ms": ms(percentile(ok, 0.5)), + "p95_ms": ms(percentile(ok, 0.95)), + "p99_ms": ms(percentile(ok, 0.99)), + } + + +# -------------------------------------------------------- строки сэмплера + + +@dataclass +class Peak: + """Память одного контейнера за окно по строкам сэмплера `peak`.""" + + start_peak: int | None = None + reset: bool = False + peak: int | None = None + first_current: int | None = None + max_current: int = 0 + max_anon: int = 0 + max_sock: int = 0 + oom_kill_start: int | None = None + oom_kill_end: int | None = None + samples: int = 0 + missing: int = 0 + + @property + def oom_kills(self) -> int: + if self.oom_kill_start is None or self.oom_kill_end is None: + return 0 + return self.oom_kill_end - self.oom_kill_start + + @property + def window_peak(self) -> int | None: + """Пик окна: значение `memory.peak` через свой дескриптор после + сброса; без сброса или без чтения (контейнер погиб) — наибольшая + выборка `memory.current`.""" + if self.reset and self.peak is not None: + return max(self.peak, self.max_current) + return self.max_current or None + + @property + def source(self) -> str: + return "reset" if self.reset and self.peak is not None else "sampled" + + +@dataclass +class PeakSamples: + roles: dict[str, Peak] = field(default_factory=dict) + ended: bool = False + + +def parse_peak(text: str) -> PeakSamples: + """Строки сэмплера в режиме `peak` (`bench/sampler.sh`): + `start <роль> <байт>|missing`, `reset <роль> ok|failed`, + `pk <нс> <роль> ` или + `pk <нс> <роль> missing`, `peak <роль> <байт>|missing`, + `end <нс>`.""" + result = PeakSamples() + + def role(name: str) -> Peak: + return result.roles.setdefault(name, Peak()) + + for line in text.splitlines(): + parts = line.split() + if not parts: + continue + kind = parts[0] + if kind == "start" and len(parts) == 3 and parts[2].isdigit(): + role(parts[1]).start_peak = int(parts[2]) + elif kind == "reset" and len(parts) >= 3: + role(parts[1]).reset = parts[2] == "ok" + elif kind == "pk" and len(parts) == 8: + item = role(parts[2]) + current, anon, sock, oom = (int(v) for v in parts[4:8]) + item.samples += 1 + if item.first_current is None: + item.first_current = current + item.max_current = max(item.max_current, current) + item.max_anon = max(item.max_anon, anon) + item.max_sock = max(item.max_sock, sock) + if item.oom_kill_start is None: + item.oom_kill_start = oom + item.oom_kill_end = oom + elif kind == "pk" and len(parts) == 5 and parts[4] == "missing": + role(parts[2]).missing += 1 + elif kind == "peak" and len(parts) == 3 and parts[2].isdigit(): + role(parts[1]).peak = int(parts[2]) + elif kind == "end": + result.ended = True + return result + + +def mib(value: int | None) -> float | None: + return None if value is None else round(value / MIB, 1) + + +def run_row( + run: dict[str, Any], + body_bytes: int, + peaks: PeakSamples, + stats: dict[str, Any], + state: dict[str, Any], + swapouts: int | None, +) -> dict[str, Any]: + """Строка `runs.csv` прогона. Пометки: `oom` — реплику завершило ядро + из-за памяти (`OOMKilled` контейнера или `oom_kill` cgroup), + `host_swap` — хост выгружал страницы в swap во время прогона, + `peak_sampled` — пик окна по выборкам, а не по сброшенному + `memory.peak`.""" + app = peaks.roles.get("api", Peak()) + s3 = peaks.roles.get("s3", Peak()) + lb = peaks.roles.get("haproxy", Peak()) + oom = bool(state.get("oom_killed")) or app.oom_kills > 0 + flags = [] + if oom: + flags.append("oom") + if swapouts: + flags.append("host_swap") + if app.source == "sampled": + flags.append("peak_sampled") + if state.get("s3_down"): + flags.append("s3_down") + return { + **{key: run[key] for key in ("run", "variant", "size", "clients")}, + "repeat": run["repeat"], + "order": run["order"], + "body_bytes": body_bytes, + "mem_before_mib": mib(app.first_current), + "start_peak_mib": mib(app.start_peak), + "peak_mib": mib(app.window_peak), + "peak_source": app.source, + "anon_max_mib": mib(app.max_anon), + "sock_max_mib": mib(app.max_sock), + "oom_kill": app.oom_kills, + "exit_code": state.get("exit_code"), + "oom_killed": bool(state.get("oom_killed")), + **stats, + "s3_peak_mib": mib(s3.window_peak), + "s3_anon_max_mib": mib(s3.max_anon), + "lb_peak_mib": mib(lb.window_peak), + "lb_sock_max_mib": mib(lb.max_sock), + "host_swapouts": swapouts, + "flags": " ".join(flags), + } + + +# ---------------------------------------------------------------- сводка + + +def num(value: Any) -> float | None: + if value is None or value == "": + return None + return float(value) + + +def spread(values: Iterable[float | None], digits: int = 1) -> str: + """Медиана и min–max повторов; один повтор — значение.""" + present = [v for v in values if v is not None] + if not present: + return "—" + mid = statistics.median(present) + if len(present) == 1: + return f"{mid:.{digits}f}" + return ( + f"{mid:.{digits}f} ({min(present):.{digits}f}–" + f"{max(present):.{digits}f})" + ) + + +def median(values: Iterable[float | None]) -> float | None: + present = [v for v in values if v is not None] + return statistics.median(present) if present else None + + +def is_oom(row: dict[str, Any]) -> bool: + return "oom" in str(row.get("flags", "")).split() + + +def errors_5xx(row: dict[str, Any]) -> int: + return sum(int(num(row.get(f"s{code}")) or 0) for code in (502, 503, 504)) + + +def cells( + rows: list[dict[str, Any]], +) -> dict[tuple[str, str, int], list[dict[str, Any]]]: + grouped: dict[tuple[str, str, int], list[dict[str, Any]]] = {} + for row in rows: + key = (row["variant"], row["size"], int(row["clients"])) + grouped.setdefault(key, []).append(row) + return grouped + + +def per_client_bodies(row: dict[str, Any]) -> float | None: + """Рост пика окна над памятью до окна на клиента, в телах.""" + peak, before = num(row.get("peak_mib")), num(row.get("mem_before_mib")) + body = num(row.get("body_bytes")) + clients = int(row["clients"]) + if peak is None or before is None or not body or not clients: + return None + return (peak - before) * MIB / body / clients + + +def hypotheses( + rows: list[dict[str, Any]], + *, + memory_limit_mib: float, + big: str, +) -> list[dict[str, str]]: + """Проверка гипотез H1–H4 числами ячеек (design change + `upload-memory`, решение 10). Итог — «да», «нет» или «нет данных»; + вывод по гипотезе пишет `REPORT.md`.""" + grouped = cells(rows) + + def group(variant: str, size: str, clients: int) -> list[dict[str, Any]]: + return grouped.get((variant, size, clients), []) + + def peak(variant: str, clients: int) -> float | None: + return median(num(r["peak_mib"]) for r in group(variant, big, clients)) + + out = [] + # H1: с лимитом пик ≤ половины лимита, рост сверх C=10 ≤ 1 MiB на + # клиента, OOM и 5xx нет, лишние — 429 + limited = [r for r in rows if r["variant"] == "limited"] + levels = [c for c in (10, 20, 40) if group("limited", big, c)] + if levels: + peaks = {c: peak("limited", c) for c in levels} + base = peaks.get(10) + growth_ok = all( + base is not None + and peaks[c] is not None + and peaks[c] - base <= (c - 10) + for c in levels + if c > 10 + ) + half_ok = all( + v is not None and v <= memory_limit_mib / 2 for v in peaks.values() + ) + oom = sum(is_oom(r) for r in limited) + fives = sum(errors_5xx(r) for r in limited) + busy = sum(int(num(r.get("s429")) or 0) for r in limited) + verdict = half_ok and growth_ok and not oom and not fives + out.append( + { + "id": "H1", + "text": "«с лимитом»: пик при 10 MiB и C = 10, 20, 40 ≤ " + "половины лимита; сверх C = 10 — ≤ 1 MiB на клиента; OOM " + "и 5xx нет, лишние — 429", + "numbers": "пик, MiB: " + + ", ".join(f"C={c} {fmt(peaks[c])}" for c in levels) + + f" (половина лимита {memory_limit_mib / 2:g}); OOM " + f"{oom}, 5xx {fives}, 429 {busy}", + "result": "да" if verdict else "нет", + }, + ) + else: + out.append(no_data("H1")) + # H2: без лимита рост ~1,2–1,3 тела на клиента, 40 × 10 MiB — OOM; «до» + # — ~2,1 тела на клиента и OOM уже при 20 × 10 MiB + parts = [] + for variant in ("unlimited", "before"): + for clients in (10, 20, 40): + items = group(variant, big, clients) + if not items: + continue + ooms = sum(is_oom(r) for r in items) + slope = median( + per_client_bodies(r) for r in items if not is_oom(r) + ) + parts.append( + f"{VARIANT_NAMES[variant]} C={clients}: " + f"{fmt(slope, 2)} тела/клиента, OOM {ooms}/{len(items)}", + ) + if parts: + unl40 = group("unlimited", big, 40) + bef20 = group("before", big, 20) + slope10 = median( + per_client_bodies(r) + for r in group("unlimited", big, 10) + if not is_oom(r) + ) + checks = [ + slope10 is not None and slope10 <= 1.5, + bool(unl40) and all(is_oom(r) for r in unl40), + ] + if bef20: + checks.append(all(is_oom(r) for r in bef20)) + out.append( + { + "id": "H2", + "text": "«без лимита»: пик растёт на ~1,2–1,3 тела на " + "клиента, 40 × 10 MiB — OOM; «до» — ~2,1 тела и OOM при " + "20 × 10 MiB", + "numbers": "; ".join(parts), + "result": "да" if all(checks) else "нет", + }, + ) + else: + out.append(no_data("H2")) + # H3: загрузок/с при C ≥ 10 у «с лимитом» ≥ 90 % «без лимита», пока тот + # жив + ratios = [] + for size in sorted({r["size"] for r in rows}): + for clients in (10, 20, 40): + lim = group("limited", size, clients) + unl = group("unlimited", size, clients) + if not lim or not unl or any(is_oom(r) for r in unl): + continue + a = median(num(r["uploads_per_s"]) for r in lim) + b = median(num(r["uploads_per_s"]) for r in unl) + if a is not None and b: + ratios.append((size, clients, a, b, a / b)) + if ratios: + out.append( + { + "id": "H3", + "text": "загрузок 201 в секунду при C ≥ 10: «с лимитом» ≥ 90 % " + "«без лимита» на тех же C, пока тот жив", + "numbers": "; ".join( + f"{s} C={c}: {a:.2f} / {b:.2f} = {ratio:.0%}" + for s, c, a, b, ratio in ratios + ), + "result": "да" if all(r[4] >= 0.9 for r in ratios) else "нет", + }, + ) + else: + out.append(no_data("H3")) + # H4: 503 нет ни в одном варианте, пока реплика жива + alive = [r for r in rows if not is_oom(r)] + if alive: + count = sum(int(num(r.get("s503")) or 0) for r in alive) + out.append( + { + "id": "H4", + "text": "503 из-за срока записи в S3 нет ни в одном варианте, " + "пока реплика жива", + "numbers": f"503 в {len(alive)} прогонах без OOM: {count}", + "result": "да" if count == 0 else "нет", + }, + ) + else: + out.append(no_data("H4")) + return out + + +def no_data(name: str) -> dict[str, str]: + return {"id": name, "text": "", "numbers": "", "result": "нет данных"} + + +def fmt(value: float | None, digits: int = 1) -> str: + return "—" if value is None else f"{value:.{digits}f}" + + +def render_summary(meta: dict[str, Any], rows: list[dict[str, Any]]) -> str: + """`summary.md` метки: паспорт кратко, таблица ячеек (медиана и + min–max повторов), сценарии спеков и гипотезы.""" + profile = meta["profile"] + info = meta.get("uploads", {}) + bodies = info.get("bodies", {}) + big = max(bodies, key=lambda k: bodies[k]["bytes"]) if bodies else "" + limit_mib = ( + round( + (meta.get("limits", {}).get("api", {}).get("memory") or 0) / MIB, + ) + or 512 + ) + lines = [ + f"# Профиль загрузок: метка `{meta['label']}`", + "", + f"- Статус: **{meta['status']}**" + + (f" ({meta['reason']})" if meta.get("reason") else ""), + f"- Commit: `{meta['git']['commit']}`" + + (" + незакоммиченные изменения" if meta["git"]["dirty"] else ""), + f"- Профиль `{profile['name']}`: варианты " + + ", ".join( + f"«{VARIANT_NAMES[v]}»" for v in profile["uploads_variants"] + ) + + ( + f" (образ «до» — commit `{info.get('before_commit')}`)" + if info.get("before_commit") + else "" + ) + + f"; клиенты {', '.join(map(str, profile['uploads_clients']))}; " + f"повторов {profile['repeats']}; окно {profile['uploads_window_s']} " + f"с после {profile['uploads_ramp_s']} с разгона", + "- Тела: " + + ", ".join( + f"{name} — {item['bytes']} байт ({item['width']} × " + f"{item['height']}), SHA-256 `{item['sha256'][:16]}…`" + for name, item in bodies.items() + ), + f"- Реплика {profile['cpus']} CPU / {profile['memory']} без swap, " + f"буфер приёма `{meta.get('stand', {}).get('api_tcp_rmem', '—')}`; " + f"S3 {profile['s3_cpus']} CPU / {profile['s3_memory']}; LB " + f"{profile['lb_cpus']} CPU / {profile['lb_memory']}", + "- Пик — `memory.peak` cgroup, сброшенный через свой дескриптор " + "перед нагрузкой (`peak_source` = reset); без сброса — наибольшая " + "выборка раз в " + f"{profile['uploads_sample_interval_s']:g} с (пометка " + "`peak_sampled`). Память до окна — первая выборка. Ответы по кодам " + "— за весь прогон, загрузок/с и перцентили — по загрузкам окна. " + "Значения — медиана (min–max) повторов", + "- Посторонние контейнеры в VM во время замера: " + + (", ".join(meta.get("other_containers") or []) or "нет"), + "", + "## Ячейки", + "", + "«Пик старта» — `memory.peak` реплики до сброса (с её запуска: " + "фиктивный хэш пароля, разогревающая загрузка); пик окна его не " + "включает.", + "", + "| Вариант | Тело | C | Пик старта, MiB | До окна, MiB | Пик, MiB | " + "anon, MiB | sock, MiB | OOM | 201 | 429 | 5xx | ошибка соединения | " + "Загрузок/с | p50, мс | p95, мс | S3 пик, MiB | S3 anon, MiB | " + "LB пик, MiB | Пометки |", + "|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|" + "---|---|---|---|", + ] + grouped = cells(rows) + order = {v: i for i, v in enumerate(VARIANTS)} + for (variant, size, clients), items in sorted( + grouped.items(), + key=lambda kv: (order.get(kv[0][0], 9), kv[0][1], kv[0][2]), + ): + flags = sorted({f for r in items for f in str(r["flags"]).split()}) + + def col(key: str, digits: int = 1, rows: list = items) -> str: + return spread((num(r.get(key)) for r in rows), digits) + + fives = [float(errors_5xx(r)) for r in items] + lines.append( + f"| {VARIANT_NAMES.get(variant, variant)} | {size} | {clients} | " + f"{col('start_peak_mib')} | " + f"{col('mem_before_mib')} | {col('peak_mib')} | " + f"{col('anon_max_mib')} | {col('sock_max_mib')} | " + f"{sum(is_oom(r) for r in items)}/{len(items)} | " + f"{col('s201', 0)} | {col('s429', 0)} | {spread(fives, 0)} | " + f"{col('s_conn_error', 0)} | {col('uploads_per_s', 2)} | " + f"{col('p50_ms', 0)} | {col('p95_ms', 0)} | " + f"{col('s3_peak_mib')} | {col('s3_anon_max_mib')} | " + f"{col('lb_peak_mib')} | {' '.join(flags) or '—'} |", + ) + lines.append("") + lines += scenario_lines(rows, big) + lines += [ + "## Гипотезы", + "", + "Гипотезы — `REPORT.md`, раздел загрузок (commit до прогонов); " + f"здесь — их проверка числами ячеек тела {big or '—'}, лимит " + f"реплики {limit_mib} MiB.", + "", + "| Гипотеза | Утверждение | Числа | Выполнена |", + "|---|---|---|---|", + ] + for item in hypotheses(rows, memory_limit_mib=limit_mib, big=big): + lines.append( + f"| {item['id']} | {item['text'] or '—'} | " + f"{item['numbers'] or '—'} | {item['result']} |", + ) + lines.append("") + if meta.get("host_warnings"): + lines += ["## Предупреждения о хосте", ""] + lines += [f"- {w}" for w in meta["host_warnings"]] + lines.append("") + return "\n".join(lines) + + +def scenario_lines(rows: list[dict[str, Any]], big: str) -> list[str]: + """Сценарии спеков, которые доказывает метка (исключения сверки + покрытия `student-tests/spec_coverage.py`).""" + grouped = cells(rows) + lines = ["## Сценарии спеков", ""] + parts = [] + for variant in ("unlimited", "before"): + items = grouped.get((variant, big, 10), []) + slope = median(per_client_bodies(r) for r in items if not is_oom(r)) + if items: + parts.append( + f"«{VARIANT_NAMES[variant]}» — {fmt(slope, 2)} тела на " + "загрузку", + ) + if parts: + lines.append( + "- `attachments`, «Одна копия тела при записи в S3» (C = 10, " + f"{big}): рост пика над памятью до окна — " + + "; ".join(parts) + + " (порог «без лимита» — 1,5 тела, «до» — больше).", + ) + lim = [grouped.get(("limited", big, c), []) for c in (10, 20, 40)] + if any(lim): + flat = [r for items in lim for r in items] + lines.append( + "- `attachments`, «Память не растёт с числом загрузок» и " + "`load-balancing`, «Буферы соединений ограничены» («с лимитом», " + f"{big}): пик реплики " + + ", ".join( + f"C={c} {fmt(median(num(r['peak_mib']) for r in items))}" + for c, items in zip((10, 20, 40), lim, strict=True) + if items + ) + + " MiB, sock " + + ", ".join( + f"C={c} {fmt(median(num(r['sock_max_mib']) for r in items))}" + for c, items in zip((10, 20, 40), lim, strict=True) + if items + ) + + " MiB, LB " + + ", ".join( + f"C={c} {fmt(median(num(r['lb_peak_mib']) for r in items))}" + for c, items in zip((10, 20, 40), lim, strict=True) + if items + ) + + f" MiB; OOM {sum(is_oom(r) for r in flat)}, 5xx " + f"{sum(errors_5xx(r) for r in flat)}, 429 " + f"{sum(int(num(r.get('s429')) or 0) for r in flat)}.", + ) + lines.append("") + return lines + + +# --------------------------------------------------------------- selftest + + +def selftest() -> int: + failures: list[str] = [] + + def expect(name: str, got: Any, want: Any) -> None: + if got != want: + failures.append(f"{name}: got {got!r}, want {want!r}") + + sizes = (("1MiB", 341), ("10MiB", 3409)) + first = build_bodies(sizes, 7) + again = build_bodies(sizes, 7) + expect("bodies deterministic", first == again, True) + expect("bodies differ by seed", build_bodies(sizes, 8) == first, False) + for name, data in first.items(): + expect(f"{name} <= limit", len(data) <= MAX_BODY_BYTES, True) + expect(f"{name} is PNG", data[:8], PNG_SIGNATURE) + expect("1MiB size", 1_000_000 < len(first["1MiB"]) < 1_100_000, True) + expect( + "10MiB size", + 10_400_000 < len(first["10MiB"]) <= MAX_BODY_BYTES, + True, + ) + try: + build_bodies((("big", 3500),), 1) + failures.append("body over the limit accepted") + except ValueError: + pass + + plan = plan_runs(("unlimited", "limited"), ("10MiB",), (1, 10, 40), 3, 5) + expect("plan length", len(plan), 18) + expect("plan unique", len({p["run"] for p in plan}), 18) + for r in (1, 2): + last = [p for p in plan if p["repeat"] == r][-1] + head = [p for p in plan if p["repeat"] == r + 1][0] + expect( + f"round {r + 1} head", + (head["variant"], head["clients"]) + != (last["variant"], last["clients"]), + True, + ) + expect( + "plan stable", + plan + == plan_runs( + ("unlimited", "limited"), + ("10MiB",), + (1, 10, 40), + 3, + 5, + ), + True, + ) + + console = "\n".join( + [ + 'time="…" level=info msg="up-t0,1000" source=console', + "up,1,0,1100,90,201,abc", + "up,2,0,4100,80,201,abc", + "up,2,1,4300,5,429,abc", + "up,3,0,24100,10,201,abc", + "up,3,1,5000,0,0,-", + "up,3,2,5100,12,503,abc", + "garbage", + ], + ) + t0, ups = parse_k6(console) + expect("t0", t0, 1000) + expect("uploads", len(ups), 6) + stats = k6_stats(ups, t0 or 0, 3, 20) + expect("201", stats["s201"], 3) + expect("429", stats["s429"], 1) + expect("conn", stats["s_conn_error"], 1) + expect("503", stats["s503"], 1) + # окно [4000, 24000): одна 201 + expect("uploads/s", stats["uploads_per_s"], 0.05) + expect("p95", stats["p95_ms"], 80.0) + expect("percentile", percentile([1, 2, 3, 4], 0.5), 2.5) + + sampler = "\n".join( + [ + "start api 160000000", + "start s3 50000000", + "reset api ok", + "reset s3 failed", + "pk 1 api abc 100000000 90000000 1000000 0", + "pk 2 api abc 150000000 140000000 4000000 0", + "pk 3 api abc missing", + "pk 1 s3 def 40000000 30000000 0 0", + "pk 2 s3 def 60000000 35000000 0 0", + "peak api 152000000", + "peak s3 70000000", + "end 4", + ], + ) + parsed = parse_peak(sampler) + api = parsed.roles["api"] + expect("ended", parsed.ended, True) + expect("api window peak", api.window_peak, 152000000) + expect("api source", api.source, "reset") + expect("api first", api.first_current, 100000000) + expect("api missing", api.missing, 1) + expect("s3 sampled", parsed.roles["s3"].window_peak, 60000000) + expect("s3 source", parsed.roles["s3"].source, "sampled") + oom = parse_peak("pk 1 api a 1 1 1 0\npk 2 api a 2 2 2 1\n") + expect("oom kills", oom.roles["api"].oom_kills, 1) + + run = plan[0] + row = run_row(run, 10_000_000, parsed, stats, {"oom_killed": True}, 3) + expect("row flags", row["flags"], "oom host_swap") + expect("row fields", set(RUN_FIELDS) >= set(row), True) + expect("row peak", row["peak_mib"], 145.0) + + def synth(variant: str, clients: int, peak: float, **extra: Any) -> dict: + base = { + "run": f"{variant}-{clients}", + "variant": variant, + "size": "10MiB", + "clients": clients, + "body_bytes": 10 * MIB, + "mem_before_mib": 100.0, + "peak_mib": peak, + "uploads_per_s": 8.0, + "s201": 100, + "s429": 0, + "s503": 0, + "flags": "", + "sock_max_mib": 5, + "lb_peak_mib": 50, + } + return {**base, **extra} + + rows = [ + synth("limited", 10, 170), + synth("limited", 20, 178, s429=5), + synth("limited", 40, 180, s429=60), + synth("unlimited", 10, 230), + synth("unlimited", 20, 350), + synth("unlimited", 40, 512, flags="oom"), + synth("before", 10, 316), + synth("before", 20, 512, flags="oom"), + ] + result = { + h["id"]: h["result"] + for h in hypotheses(rows, memory_limit_mib=512, big="10MiB") + } + expect("H1", result["H1"], "да") + expect("H2", result["H2"], "да") + expect("H3", result["H3"], "да") + expect("H4", result["H4"], "да") + worse = rows + [synth("limited", 40, 300, flags="", s503=1)] + result = { + h["id"]: h["result"] + for h in hypotheses(worse, memory_limit_mib=512, big="10MiB") + } + expect("H1 worse", result["H1"], "нет") + expect("H4 worse", result["H4"], "нет") + meta = { + "label": "selftest", + "status": "complete", + "git": {"commit": "x", "dirty": False}, + "profile": { + "name": "uploads_quick", + "uploads_variants": ["unlimited", "limited"], + "uploads_clients": [1, 10, 40], + "repeats": 1, + "uploads_window_s": 20, + "uploads_ramp_s": 3, + "uploads_sample_interval_s": 0.2, + "cpus": "1", + "memory": "512m", + "s3_cpus": "1", + "s3_memory": "512m", + "lb_cpus": "1", + "lb_memory": "256m", + }, + "uploads": {"bodies": {"10MiB": body_passport("10MiB", 3409, b"x")}}, + } + text = render_summary(meta, rows) + expect("summary has H1", "| H1 |" in text, True) + expect("summary has cells", "| с лимитом | 10MiB | 40 |" in text, True) + if failures: + print("selftest failed:\n " + "\n ".join(failures), flush=True) + return 1 + print("selftest ok", flush=True) + return 0 + + +if __name__ == "__main__": + if sys.argv[1:] == ["--selftest"]: + sys.exit(selftest()) + print("usage: uv run python bench/uploads.py --selftest", flush=True) + sys.exit(2) diff --git a/config_example.toml b/config_example.toml index 41998a9a..b71ea902 100644 --- a/config_example.toml +++ b/config_example.toml @@ -79,6 +79,20 @@ max_connections = 10 # Короткий срок для проверки — окружением IDEMPOTENCY__TTL_SECONDS=2 ttl_seconds = 86400 +[uploads] +# Места загрузок вложений процесса API; разовая подмена — окружением +# UPLOADS__*. Память загрузок ограничена числом мест, а не клиентов. +# загрузок, которые процесс обрабатывает одновременно +max_concurrent = 4 +# загрузок, которые ждут места; 0 — без ожидания, сразу 429 +max_waiting = 16 +# секунды ожидания места, затем 429 rate_limited с Retry-After; вход, +# членство и ожидание (2 × 6 + 5 = 17 с) меньше timeout server LB пути +# загрузки (30 с) +wait_timeout_seconds = 5 +# секунды на всё тело с момента, как загрузка заняла место; иначе 400 +body_timeout_seconds = 30 + [cleaner] # Уборщик незавершённых загрузок (сервис compose cleaner); реплики API # секцию не читают. Разовая подмена — окружением CLEANER__*. diff --git a/docker-compose.yml b/docker-compose.yml index 4ca1b21e..9358d046 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -312,6 +312,14 @@ services: condition: service_completed_successfully # healthcheck — из образа; SIGKILL не раньше, чем через 10 с stop_grace_period: 10s + # буфер приёма сокетов реплики — до 512 KiB, а не до 32 MiB ВМ Docker: + # ядро копит недочитанное тело (ожидание места загрузки, отказ до тела) + # в буфере сокета, и он считается памятью контейнера. Параметр сетевого + # пространства контейнера — его получают все контейнеры сервиса, в том + # числе bench/, make test_isolated и стенд отказов (design change + # upload-memory, решение 6). В консоли (make run_dev) его нет + sysctls: + net.ipv4.tcp_rmem: "4096 131072 524288" deploy: replicas: ${API_REPLICAS:-2} resources: diff --git a/evidence/tests/failure-checks.md b/evidence/tests/failure-checks.md index 922032df..4802b558 100644 --- a/evidence/tests/failure-checks.md +++ b/evidence/tests/failure-checks.md @@ -238,3 +238,51 @@ E AssertionError: assert '2b1ccadf-…' in set() # объект удал E AssertionError: POST /api/v1/chats/e6a74a0b-…/attachments: expected 503; got 500 {"error":{"code":"internal_error","message":"Internal server error","request_id":"…"}} ====================== 2 failed, 227 deselected in 3.49s ======================= ``` + +## Красный прогон до кода `upload-memory` (apply, 2026-10-21) + +Новые тесты мест загрузки и срока тела (tasks change `upload-memory`, +1.2–1.4) и третий API стенда отказов (`UPLOADS_ENV`) против кода +`f894040` (HEAD `fc1524d`, в `src/` правок ещё нет): `make +failure_checks FAULT_ARGS='-k "slot or queue or slow_body"'`. Прежний API +секцию `[uploads]` не знает и окружение `UPLOADS__*` игнорирует: +5 failed. + +``` +[failure_checks] ready: api=http://127.0.0.1:50458 tight=http://127.0.0.1:50462 uploads=http://127.0.0.1:50467 +collecting ... collected 235 items / 230 deselected / 5 selected +student-tests/test_failures.py::test_upload_slots_busy FAILED [ 20%] +student-tests/test_failures.py::test_rejections_before_queue FAILED [ 40%] +student-tests/test_failures.py::test_upload_waits_for_slot FAILED [ 60%] +student-tests/test_failures.py::test_slot_released_after_failures FAILED [ 80%] +student-tests/test_failures.py::test_slow_body FAILED [100%] +E AssertionError: POST /api/v1/chats/c6d00a36-…/attachments: expected 429; got 201 {"id":"9f6d3dcd-…", …} +E AssertionError: POST /api/v1/chats/f25be5c6-…/attachments: expected 429; got 201 {"id":"0d558e8b-…", …} +E assert '2026-10-21T20:29:49.137493Z' > '2026-10-21T20:29:49.331772Z' +E AssertionError: POST /api/v1/chats/b9f1daa1-…/attachments: expected 400; got 201 {"id":"24f4bc9f-…", …} +E AssertionError: POST /api/v1/chats/acec553a-…/attachments: expected 400; got 201 {"id":"820f7582-…", …} +====================== 5 failed, 230 deselected in 12.08s ====================== +[failure_checks] postgres log: 56 lines, crash markers 0; "too many clients" 0, "administrator command" 0 +[failure_checks] results: {'fault': 1, 'postgres': 0} +``` + +Причины — дефект прежнего кода, а не тестов и не стенда (мест и срока тела +у него нет): +- `test_upload_slots_busy` — загрузка при занятом месте и полной очереди + принята (201), а не 429; +- `test_rejections_before_queue` — ожидавшая в очереди загрузка B + принята сразу (201): «очередь полна», условие сценария, на прежнем коде + недостижимо. Тест проверяет его до ранних отказов (404, 413, 415), иначе + быстрые отказы ничего бы не доказывали; +- `test_upload_waits_for_slot` — B не ждала места: её `created_at` + раньше `updated_at` загрузки, которая держала место; +- `test_slot_released_after_failures` — 413 по счётчику и 415 по + содержимому с последующей загрузкой прошли, а тело дольше срока + (шаг 3) принято (201): срока тела нет; +- `test_slow_body` — тело дольше срока принято (201), а не 400. + +Tasks (1.5) ждали зелёными `test_slot_released_after_failures` и +`test_rejections_before_queue`. Первый включает шаг «400 по сроку тела» +(design, решение 11), которого прежний код не выполняет; второй проверяет +полную очередь (ответ 429 ожидавшей) — design change `upload-memory`, +«Уточнения apply», п. 2. diff --git a/infra/haproxy/haproxy.cfg b/infra/haproxy/haproxy.cfg index 780b1140..0b96300c 100644 --- a/infra/haproxy/haproxy.cfg +++ b/infra/haproxy/haproxy.cfg @@ -17,6 +17,12 @@ global # достать, доступ — docker compose exec haproxy (bash /dev/tcp). # Решение 2 design change rolling-update stats socket ipv4@127.0.0.1:9999 level admin + # буфер отправки к реплике фиксирован (256 KiB): тело загрузки, которое + # реплика не читает (ожидание места, отказ до тела), не копится в + # памяти LB целиком — 51 MiB вместо 109 при 40 загрузках по 10 MiB. + # Буфер приёма от клиента не ограничен: клиентам с большим RTT нужен + # большой (design change upload-memory, решение 6) + tune.sndbuf.server 262144 # DNS Docker: имя сервиса api отвечает адресами всех работающих реплик. # Пропавший адрес уходит из слота, новый появляется за 1–2 с без @@ -52,7 +58,8 @@ defaults # уже начала, не повторяется: POST /users и POST /chats не # идемпотентны, отправку сообщения повторяет клиент с тем же ключом retry-on conn-failure - # больше [database] request_timeout_seconds (6 с) и KDF входа + # больше [database] request_timeout_seconds (6 с) и KDF входа; у пути + # загрузки вложения — 30 с (backend api, http-request set-timeout) timeout server 10s timeout client 30s timeout http-request 10s @@ -67,7 +74,11 @@ defaults unique-id-format lb-%{+X}o%ci%cp%Ts%rt%pid # ответы самого LB — в формате ошибки контракта; в перечислении кодов # контракта нет отдельных кодов для 502 и 504, ближайший — unavailable. - # X-Instance-Id у них нет: контракт это допускает + # X-Instance-Id у них нет: контракт это допускает. 400 — неверный запрос + # или клиент замолчал посреди тела дольше timeout client (change + # upload-memory). 408 на медленные заголовки HAProxy строит до потока + # запроса, http-error его не меняет (KNOWN_ISSUES.md) + http-error status 400 content-type application/json lf-string '{"error":{"code":"invalid_request","message":"Invalid request","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]" http-error status 502 content-type application/json lf-string '{"error":{"code":"unavailable","message":"API replica closed the connection","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]" http-error status 503 content-type application/json lf-string '{"error":{"code":"unavailable","message":"No API replica is available","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]" http-error status 504 content-type application/json lf-string '{"error":{"code":"unavailable","message":"API replica did not respond in time","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]" @@ -80,6 +91,19 @@ frontend entry backend api # по очереди, без cookie и stick-table: sticky session запрещён balance roundrobin + # путь загрузки вложения (design change upload-memory, решение 7): срок + # ответа реплики 30 с вместо 10, больше самого долгого молчания живой + # загрузки: + # до тела — 2 × [database] request_timeout_seconds (вход, членство) + + # [uploads] wait_timeout_seconds = 2 × 6 + 5 = 17 с; + # после тела — проверка (до ~4 с) + pending 6 + PUT 5 + ready 6 + + # компенсация 5 ≈ 26 с. + # Тело ограничивают [uploads] body_timeout_seconds (30 с) и timeout + # client; наибольшая длительность загрузки 17 + 30 + 26 ≈ 73 с < + # ROLLOUT_DRAIN_TIMEOUT (90 с, scripts/rolling-update.sh). Остальные + # пути — прежние 10 с. Выражение — путь ручки в API + # (src/api/routers/v1/attachment.py): при смене префикса менять вместе + http-request set-timeout server 30s if METH_POST { path_reg ^/api/v1/chats/[^/]+/attachments$ } # соединение с репликой не переходит в общий пул и не отдаётся другому # клиенту: оно живёт, пока жив сеанс клиента, а простаивающий сеанс LB # закрывает по timeout http-keep-alive (10 с). uvicorn держит diff --git a/openspec/changes/upload-memory/design.md b/openspec/changes/upload-memory/design.md index b217681c..2977d7da 100644 --- a/openspec/changes/upload-memory/design.md +++ b/openspec/changes/upload-memory/design.md @@ -687,3 +687,91 @@ git до sync дельт (`student-tests.md`). `unavailable` (решение 2, `PLAN.md`, «Вопросы», п. 1). До ответа преподавателя — 429; ответ меняет одну строку таблицы ошибок, сценарии и тесты, но не подход и не задачи. + +## Уточнения apply + +Решения `/opsx:apply` (2026-10-21), пользователь недоступен; вопрос 1 +`PLAN.md` открыт — сделано 429, как в решении 2. + +1. **`test_upload_slots_busy`: A отпускается раньше сверки списков.** + Таблица решения 11 сверяет «новых `id` нет» до отпускания A, но срок + тела стенда 2 с с момента, как A заняла место, а B получает 429 только + через ~1,2 с; два вызова hook (`attachment-ids`, `object-ids`) не + успели бы. Поэтому после 429 у B A отпускается сразу (201), а сверка + — `новые id = {A}` и в строках, и в объектах: у B и C ничего нет. +2. **`test_rejections_before_queue` проверяет, что очередь была полна**: + ожидавшая B получает 429, а три ранних отказа приходят до её ответа. + Без этого быстрые 404 / 413 / 415 ничего не доказывали бы: сценарий + требует полной очереди. Поэтому на коде без мест тест красный (B — 201), + а не зелёный, как ждали tasks (1.5). `test_slot_released_after_failures` + на прежнем коде тоже красный — на шаге «тело дольше срока — 400»: срока + тела там нет. Красный прогон — 5 из 5 (`evidence/tests/ + failure-checks.md`). +3. **Срок ранних отказов — меньше срока ожидания места (1 с), а не 0,5 с.** + Тело 30 MiB с `Content-Length` httpx отправляет целиком, прежде чем + читать ответ, и через проброс порта Docker Desktop это заметная доля + 0,5 с. Ошибка, которую ловит проверка (ранний отказ ждёт место), дала + бы ≥ 1 с или 429. Порог 0,5 с остался у C («Очередь ожидания полна»). +4. **Тип `UploadSlots` в сервисе — под `TYPE_CHECKING`.** Импорт + `src/infra/upload_slots.py` создаёт глобал, а `src.core.services` + импортирует и процесс уборщика; глобал берёт только + `src/api/dependencies.py` (`infra.md`). +5. **`Retry-After` — таблица `RETRY_AFTER` в `errors.py`** рядом с + `CHALLENGES` (тип исключения → секунды), а не условие в обработчике: + новое исключение с повтором — одна строка. +6. **`UploadsBusy` журналирует сервис, а не `UploadSlots`**: путь на + месте вынесен в `_store`, `upload` ловит только `UploadsBusy` входа в + место и пишет «Rejected attachment» (`reason=busy`, `waited_ms` от + начала ожидания). `body_timeout` пишет и `size` прочитанного. +7. **`config.toml` рабочего дерева получил секцию `[uploads]`** с теми же + значениями, что `config_example.toml` (правило `settings.md`, «Новое + поле или секция», п. 3); поведение не меняется — значения по + умолчанию. +8. **Драйвер `lb-upload-timeouts`** (задача 7.1): + - перед стендом — `haproxy -c` той же конфигурации в том же образе + (ошибка — код 1), нет файла — код 2; образ LB — по строке `image: + haproxy:…` из `docker-compose.yml`; + - заглушка — `mtusi-messenger:lab4` с `--entrypoint python -c`, + `--no-healthcheck`, сетевое имя `api`, порт 8080; задержки — + окружением; ответ заглушки узнаётся по `X-Instance-Id: stub`; + - пять случаев параллельно (~33 с), каждый со своим `?case=…` на пути + загрузки; клиент — с хоста через свободный порт `127.0.0.1`, тело + 10 MiB; «клиент молчит посреди тела» — сырой сокет: заголовки с + `Content-Length` 10 MiB и половина тела, время — от последнего + байта (LB отвечает по `timeout client` через ~30 с, отдельные 35 с + не ждутся); + - границы: 201 — 11,5–17 с; 504 другого пути — 9,5–12 с; 504 пути + загрузки — 29,5–32 с; 400 — 29–33 с; ошибки LB — ровно `{"error": + {code, message, request_id}}`, `request_id` = `X-Request-Id`; + - уборка по метке контейнеров и сети `mtusi-lbto-` в `finally`, в + том числе по SIGTERM и SIGHUP. +9. **Sync дельт — по блокам требований**, как в `attachments` и + `upload-consistency`: блоки MODIFIED заменены целиком, ADDED + дописаны в конец спека; все блоки основных спеков построчно совпали с + дельтами. +10. **Профиль `uploads`** (задачи 8.1–8.6): + - разбор без docker вынесен в `bench/uploads.py` (тела, план, разбор + k6 и сэмплера, строка `runs.csv`, сводка, `--selftest`), как + `failover.py` и `rollout.py`; + - окно памяти — весь прогон k6 (разгон и окно): пик сбрасывается + перед нагрузкой, после разогревающей загрузки. Загрузок в секунду + и перцентили — по загрузкам, отправленным в окне `[t0 + 3, t0 + + 23)`; ответы по кодам — за весь прогон, в том числе после OOM; + - S3 перед прогоном гасится `kill`, а не плавной остановкой (~15 с): + его volume всё равно удаляется; + - окружение варианта — override `.work/variant.compose.yml`, а не + переменные `BENCH_*` в `bench.compose.yml`: иначе `stand.app_env` + прежних профилей изменился бы, и `bench_compare` отказал бы со + старыми метками; у «с лимитом» и «до» окружение пустое; + - зерно тела — `seed + высота`: тело 10 MiB у `uploads` и + `uploads_quick` побайтно одно; + - пользователь, вход и чат — один раз на метку (`members=1`), + реплика окна каждый раз новая; + - к столбцам решения 10 добавлены `start_peak_mib` (пик старта до + сброса — проверка «Пик окна без памяти старта»), `lb_sock_max_mib`, + `host_swapouts`; пометка `s3_down`; + - в паспорт всех профилей — `stand.api_tcp_rmem` и `docker.kernel`; + - найден и исправлен дефект стенда, касается и прежних профилей: + контейнер сэмплера (образ PostgreSQL) удалялся без `-v` и оставлял + анонимный volume `/var/lib/postgresql` на каждый запуск; теперь + `stop_sampler` и `Stand.stop()` удаляют его с `-v`. diff --git a/openspec/changes/upload-memory/tasks.md b/openspec/changes/upload-memory/tasks.md index 8a994df8..142671d9 100644 --- a/openspec/changes/upload-memory/tasks.md +++ b/openspec/changes/upload-memory/tasks.md @@ -9,15 +9,15 @@ ## 1. Тесты и красный прогон -- [ ] 1.1 `student-tests/contract.py`: `assert_error(resp, 429)` — `code` +- [x] 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` (спек +- [x] 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` с +- [x] 1.3 `run_failures.py`: третий API `<проект>-api-uploads` с `UPLOADS_ENV`: - `UPLOADS__MAX_CONCURRENT=1`, `UPLOADS__MAX_WAITING=1`; - `UPLOADS__WAIT_TIMEOUT_SECONDS=1`, @@ -27,14 +27,14 @@ API при падении; уборка. Фикстура `uploads_api` в `conftest.py`. Проверка: `make failure_checks FAULT_ARGS='-k uploads'` поднимает три API и убирает стенд. -- [ ] 1.4 `test_failures.py` (маркер `fault`, `spec` по таблице решения +- [x] 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 +- [x] 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`. @@ -43,21 +43,28 @@ отказов в очереди. Вывод и число упавших — в `evidence/tests/` (раздел красного прогона `failure-checks.md`) и в tasks при прогоне. + Прогон 2026-10-21 на `f894040` (HEAD `fc1524d`): **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` +- [x] 2.1 `src/utils/constants.py`: `UPLOAD_RETRY_AFTER_SECONDS = 1` с комментарием (design, решение 2). Проверка: `make lint`. -- [ ] 2.2 `src/core/exceptions/attachment.py`: +- [x] 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 +- [x] 2.3 `src/api/errors.py`: `UploadsBusy` → 429 `ErrorCode.RATE_LIMITED` с заголовком `Retry-After` из константы (рядом с `CHALLENGES`), `UploadTimedOut` → 400 `invalid_request`. Проверка — тесты 1.4. -- [ ] 2.4 Секция `[uploads]` — класс `Uploads` в +- [x] 2.4 Секция `[uploads]` — класс `Uploads` в `src/config/settings.py`: - `max_concurrent` (int, `ge=1`, 4); - `max_waiting` (int, `ge=0`, 16); @@ -72,9 +79,14 @@ - с `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` и глобал +- [x] 3.1 `src/infra/upload_slots.py`: класс `UploadSlots` и глобал `upload_slots` из `settings.uploads` (design, решение 1). Контекст `slot()`: - места нет и ожидающих уже `max_waiting` — сразу `UploadsBusy`; @@ -88,11 +100,19 @@ ожидающий. Третий — сразу `UploadsBusy`, второй — через срок. После отмены ожидающей задачи и после исключения внутри контекста место снова свободно. -- [ ] 3.2 `src/api/dependencies.py`: `AttachmentService(db_scope=…, + + Прогон (`scratchpad/slots_check.py`): третий — `UploadsBusy` за + 0,000 с, второй — за 0,502 с (срок 0,5); после отмены ожидающей, после + исключения и после отмены уже разбуженной ожидающей место сразу + свободно, `_value` 1, ожидающих 0. +- [x] 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`; + + Тип в сервисе — под `TYPE_CHECKING`: импорт модуля создаёт глобал, а + сервис импортирует и уборщик (design, «Уточнения apply», п. 4). +- [x] 3.3 `AttachmentService.upload` (`src/core/services/attachment.py`; design, решения 3 и 4): - после проверок членства, `Content-Type` и `Content-Length` — `async with self.slots.slot()`, внутри — остальной путь до ответа; @@ -105,22 +125,31 @@ - докстринги — новый порядок. Проверка — тесты 1.4 зелёные (группа 10). -- [ ] 3.4 `src/main.py`: запись «Started API» с + + На дереве: `make failure_checks FAULT_ARGS='-k "slot or queue or + slow_body"'` — 5 passed (evidence — после commit, 10.5). +- [x] 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_concurrent` 4, + `uploads_max_waiting` 16, `uploads_wait_timeout_seconds` 5.0, + `uploads_body_timeout_seconds` 30.0. + ## 4. Одна копия тела при PUT -- [ ] 4.1 `_read_body` возвращает `BytesIO`. Сервис: +- [x] 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)` +- [x] 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` — в журнал вызова. Проверка: @@ -129,14 +158,26 @@ - SHA-256 сохранённого объекта совпал; - `make test` и тесты вложений зелёные. + Прогон (`scratchpad/put_memory_check.py`, `docker compose run --rm + --no-deps` сервиса `api` с `src` дерева поверх образа, тело + 10 479 105 байт, объекты под `umcheck/` удалены): прежний путь (PUT + `bytes`) — пик над базой 2,31 тела; новый (тот же `BytesIO` после + `del`) — 1,19 тела в трёх загрузках подряд; SHA-256 всех объектов + совпал. `make test` и тесты вложений — в `make test_isolated` (9.4). + ## 5. Стенд и LB -- [ ] 5.1 `docker-compose.yml`, сервис `api`: `sysctls: +- [x] 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`: + + На дереве: `docker compose run --rm --no-deps --entrypoint cat api + /proc/sys/net/ipv4/tcp_rmem` — `4096 131072 524288` (так же запускают + API `make test_isolated` и стенд отказов); реплики рабочего стенда — + после `make rolling_update` (10.1). +- [x] 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`; @@ -146,11 +187,17 @@ Проверка: `haproxy -c` в закреплённом образе с `API_PORT`; `make run_docker`, `make instances`, `make test`. -- [ ] 5.3 `scripts/rolling-update.sh`: `ROLLOUT_DRAIN_TIMEOUT` по + + `haproxy -c` (`haproxy:3.4.6-trixie@sha256:e2739156…`, `API_PORT=8080`) + — код 0. Рабочий стенд в этом запуске не перестраивается: LB — `up -d + --force-recreate haproxy` в 10.1; поведение — драйвер 7.1. +- [x] 5.3 `scripts/rolling-update.sh`: `ROLLOUT_DRAIN_TIMEOUT` по умолчанию 90 с, комментарий: «больше `timeout server` пути загрузки и наибольшей длительности загрузки». Проверка: `make rolling_update` на рабочем стенде — код 0, дренаж каждой реплики — секунды. -- [ ] 5.4 `KNOWN_ISSUES.md`: запись «LB отвечает 408 на медленные + + Прогон `make rolling_update` — в 10.1 (после commit). +- [x] 5.4 `KNOWN_ISSUES.md`: запись «LB отвечает 408 на медленные заголовки текстом HAProxy»: - где и что, проба — design, Context п. 4; - предложение и почему `errorfile` со статичным `request_id` не @@ -160,21 +207,31 @@ ## 6. Спеки и сверка покрытия -- [ ] 6.1 Sync дельт в основные спеки (`/opsx:sync` или вручную, как в +- [x] 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` «Одна копия тела + + Sync — `/opsx:sync` вручную по блокам: 7 спеков, все блоки дельты + совпали с основными построчно; `openspec validate --specs` — 24 passed; + `openspec validate upload-memory --strict` — valid. +- [x] 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, +- [x] 7.1 `driver.py lb-upload-timeouts` (stdlib, Python 3.9; design, решение 7): - временная сеть, HAProxy закреплённого образа с `infra/haproxy/haproxy.cfg` и `API_PORT`; @@ -191,9 +248,17 @@ f894040:infra/haproxy/haproxy.cfg` во временный файл, аргумент `--config`). + Прогон на дереве (~33 с, пять случаев параллельно): текущий + `haproxy.cfg` — код 0 (201 за 12,06 и 12,13 с; 504 другого пути за + 10,01 с; 504 пути загрузки за 30,12 с; 400 `application/json` за + 30,02 с). Конфигурация `f894040` (`git archive … | tar -x` в + scratchpad) — код 1: 502 за 10,23 с, 504 за 10,13 и 10,13 с, 400 + `text/html`. Временные сети и контейнеры убраны, volumes те же. + Решения сверх design — design, «Уточнения apply», п. 8. + ## 8. Профиль `uploads` стенда `bench/` -- [ ] 8.1 `bench/run.py`: профили `uploads` и `uploads_quick` (поля +- [x] 8.1 `bench/run.py`: профили `uploads` и `uploads_quick` (поля `Profile`, design, решение 10): - стенд с S3 и bootstrap, лимиты рабочего стенда, реплика без swap; - варианты «до» (`uploads_before = "f894040"`, сборка как у @@ -206,17 +271,28 @@ - отказ занятой метки и остатков стенда. Проверка: отказ на занятой метке и на commit вне истории (код 2). -- [ ] 8.2 Тела PNG ~1 MiB и ~10 MiB из шума (`random.Random(seed)`, + + Прогон: занятая метка и `--from deadbeef0` — код 2 до стенда. + Разбор без docker — новый `bench/uploads.py` (`--selftest`); решения + сверх design — design, «Уточнения apply», п. 10. +- [x] 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`, разгон и окно, тело из + + `--selftest` — ok; в образе API `inspect_image` принял оба тела + (1 048 276 байт 1024 × 341 и 10 479 107 байт 1024 × 3409). +- [x] 8.3 `bench/k6/uploads.js`: `constant-vus`, разгон и окно, тело из смонтированного файла, Bearer из `lib.js`; на 429 — пауза `Retry-After`, на прочие ошибки — 1 с; строка на запрос в файл консоли. Проверка: число строк = итерации из итога k6, как в `failover`. -- [ ] 8.4 `bench/sampler.sh`, режим `peak`: + + Сверку строк и `iterations{scenario:upload}` делает сам `run.py` + (несовпадение — `BenchError`); в `uploads_quick` прошла во всех шести + прогонах (216–840 итераций). +- [x] 8.4 `bench/sampler.sh`, режим `peak`: - сброс `memory.peak` реплики, S3 и LB через свой дескриптор (perl) в начале окна и чтение в конце; - выборка `memory.current`, `anon`, `sock`, `oom_kill` раз в 0,2 с; @@ -225,19 +301,42 @@ Проверка: на `uploads_quick` пик окна при C = 1 ниже пика старта реплики. -- [ ] 8.5 Результаты `evidence/uploads/<метка>/`: `meta.json`, `runs.csv` + + `uploads_quick`: пик окна при C = 1 — 120,6 / 120,8 MiB, пик старта — + 152,5–152,7 MiB (сброс работает, ядро 7.0.14-linuxkit). +- [x] 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`, + + Прогон на дереве (метка `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. +- [x] 8.6 Регресс `bench/`: `make bench_quick`, `bench_restore_quick`, `bench_failover_quick`, `bench_rollout_quick` — код 0; в паспортах — буфер приёма реплики. Проверка — коды и паспорта. + Все четыре — код 0 (`bench_quick` 18/18, `bench_failover_quick` 4/4, + `bench_rollout_quick` — замена 12,6 с без ошибок; «stale POST 500» в + `bench_restore_quick` — как в закоммиченных метках `restore`). В + паспортах — `stand.api_tcp_rmem` `4096 131072 524288` и + `docker.kernel` `7.0.14-linuxkit`. Попутно исправлено: сэмплер + оставлял анонимный volume на каждый запуск (design, «Уточнения apply», + п. 10). + ## 9. Правила и документы -- [ ] 9.1 Правила по design, решение 12: +- [x] 9.1 Правила по design, решение 12: - `api-contract.md` — 429 и порядок проверок; - `service-layer.md` — места, буфер в PUT, порядок записи; - `infra.md` — `upload_slots.py`; @@ -253,7 +352,9 @@ Проверка: правила не противоречат коду; `grep -rn "DRAIN_TIMEOUT (12)\|12 с (> timeout server)" .claude/rules scripts` пуст. -- [ ] 9.2 AGENTS.md: + + Grep пуст (код 1). `bench.md` — ещё исправление сэмплера (`-v`). +- [x] 9.2 AGENTS.md: - вводный абзац — change `upload-memory`; - инвариант лабы 4 о памяти загрузок; - команды `make bench_uploads`, `bench_uploads_quick`, `driver.py @@ -262,12 +363,22 @@ `bench/`, `evidence/uploads/`. Проверка — чтение по таблице команд. -- [ ] 9.3 `PLAN.md`, раздел `### upload-memory`: решения apply по +- [x] 9.3 `PLAN.md`, раздел `### upload-memory`: решения apply по образцу прежних changes, ответ на вопрос 1, когда придёт. Строку этапа 4 сводной таблицы отмечает основная сессия при archive. -- [ ] 9.4 `make lint`, `make check`, `make validate + + Решения 13–18; вопрос 1 — без ответа, записано состояние и что + поменяет ответ «503». +- [x] 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_test` 192 passed, 5 skipped (реплики), 1 failed — + ожидаемо `test_exclusion_evidence_exists` (6.2), сверка покрытия: 227 + сценариев, 210 с тестами (45 — проверки отказов), 17 исключений. + ## 10. Прогоны и evidence - [ ] 10.1 Commit кода (основная сессия, после подтверждения). Затем на @@ -283,6 +394,10 @@ - [ ] 10.2 Гипотезы H1–H4 (design, решение 10) — в `REPORT.md`, раздел загрузок, отдельным commit до первого прогона метки (`bench.md`, `COURSE.md`). Проверка: в `git log` commit гипотез раньше метки. + + Текст гипотез и методики — в `REPORT.md`, «Одновременные загрузки: + гипотезы (change `upload-memory`)» (apply, 2026-10-21); commit — + основная сессия, задача не закрыта до него. - [ ] 10.3 `make bench_uploads` после проверки хоста (`bench.md`, «Результаты»; рабочий стенд — `make stop`), затем commit метки. Проверка: diff --git a/openspec/specs/api-conventions/spec.md b/openspec/specs/api-conventions/spec.md index 1f121426..7f635193 100644 --- a/openspec/specs/api-conventions/spec.md +++ b/openspec/specs/api-conventions/spec.md @@ -114,8 +114,10 @@ Unicode code points. Сервис SHALL использовать пары статус — `code`: 400 — `invalid_request`, 401 — `unauthorized`, 404 — `not_found`, 409 — `conflict`, 413 — `payload_too_large`, 415 — `unsupported_media_type`, -500 — `internal_error`, 503 — `unavailable`. Метод, не поддерживаемый -путём, SHALL давать 405 с `code` `invalid_request`. +429 — `rate_limited`, 500 — `internal_error`, 503 — `unavailable`. +Метод, не поддерживаемый путём, SHALL давать 405 с `code` +`invalid_request`. Ответ 429 SHALL содержать заголовок `Retry-After` — +положительное целое число секунд. #### Scenario: Неизвестный путь @@ -134,6 +136,15 @@ Unicode code points. - **THEN** ответы 413 с `code` `payload_too_large` и 415 с `code` `unsupported_media_type` в формате ошибки +#### Scenario: Лимит одновременных загрузок + +- **WHEN** все места загрузки процесса заняты и очередь ожидания полна + (`attachments`, «Одновременные загрузки реплики»), и участник + загружает вложение +- **THEN** ответ 429 с `code` `rate_limited` в формате ошибки, с + непустыми `X-Request-Id` и `X-Instance-Id` и с `Retry-After` — + положительным целым числом + ### Requirement: Невалидный запрос даёт 400 Сервис SHALL отвечать 400 `invalid_request`, а не 422, когда тело не diff --git a/openspec/specs/attachments/spec.md b/openspec/specs/attachments/spec.md index 786e00d6..da935e69 100644 --- a/openspec/specs/attachments/spec.md +++ b/openspec/specs/attachments/spec.md @@ -63,7 +63,9 @@ SHALL отдаваться без чтения тела. Без `Content-Length` частями) тело SHALL читаться потоком со счётчиком. Ответ 413 SHALL отдаваться, как только прочитано больше лимита, остаток тела MUST NOT читаться. На одну загрузку процесс API MUST NOT держать в памяти больше -лимита и одного блока чтения тела. +лимита и одного блока чтения тела. Это касается всех шагов загрузки, в +том числе записи объекта в S3: для отправки тело MUST NOT копироваться +целиком. #### Scenario: Граница размера @@ -82,6 +84,15 @@ SHALL отдаваться без чтения тела. Без `Content-Length` - **WHEN** участник передаёт 30 MiB частями, без `Content-Length` - **THEN** ответ 413 `payload_too_large` в формате ошибки +#### Scenario: Одна копия тела при записи в S3 + +- **WHEN** 10 клиентов одновременно загружают по 10 MiB в одну реплику, + у которой лимит одновременных загрузок выше 10 (профиль загрузок + стенда `bench/`, вариант «без лимита») +- **THEN** пик памяти реплики выше её памяти до загрузок не больше чем + на 1,5 размера тела на каждую загрузку, а у кода до этого изменения + (вариант «до») — больше + ### Requirement: Лимит пикселей до распаковки Ширину и высоту изображения сервис SHALL брать из заголовка до @@ -250,11 +261,15 @@ U+FFFD MUST NOT превращать отказ в принятое имя. 3. 404 — чата нет или пользователь в нём не состоит; 4. 415 — `Content-Type` запроса; 5. 413 — `Content-Length` запроса; -6. 413 — число прочитанных байтов; -7. 415 или 413 — содержимое: формат и целостность или число пикселей. +6. 429 — нет места для загрузки (требование «Одновременные загрузки + реплики»); +7. тело: 413 — прочитано больше лимита; 400 — тело не пришло за срок + (требование «Срок передачи тела») или клиент оборвал передачу; +8. 415 или 413 — содержимое: формат и целостность или число пикселей. -Тело MUST NOT читаться, пока не пройдены проверки 1–5. Ошибка клиента -MUST NOT давать 500. +Тело MUST NOT читаться, пока не пройдены проверки 1–6. Загрузка, +отклонённая на проверках 1–5, MUST NOT ждать места и занимать его. +Ошибка клиента MUST NOT давать 500. #### Scenario: Посторонний с большим файлом @@ -272,6 +287,14 @@ MUST NOT давать 500. - **WHEN** участник загружает 30 MiB с `Content-Type: text/plain` - **THEN** ответ 415 `unsupported_media_type` +#### Scenario: Отказ раньше очереди + +- **WHEN** все места загрузки процесса заняты и очередь ожидания полна, + и посторонний загружает файл в чат, участник загружает 30 MiB с + `Content-Length` 31 457 280, а затем PNG с `Content-Type: text/plain` +- **THEN** ответы 404, 413 и 415 приходят сразу, без ожидания места, а + не 429 + ### Requirement: Доступ к вложению Метаданные и байты вложения SHALL быть доступны любому участнику чата @@ -523,3 +546,100 @@ API. - **WHEN** вложение загружено, затем выполнен `scripts/restart.sh` - **THEN** прежним токеном метаданные — 200, а байты совпадают с загруженными по SHA-256 + +### Requirement: Одновременные загрузки реплики + +Каждый процесс API SHALL обрабатывать одновременно не больше `[uploads] +max_concurrent` загрузок (`service-configuration`, «Параметры +загрузок»): у процесса столько мест загрузки. Загрузка занимает место +после проверок 1–5 требования «Порядок проверок загрузки» и до чтения +тела. Место SHALL освобождаться при любом исходе загрузки: 201, ошибка, +обрыв клиента, истёкший срок, отмена запроса. + +Загрузка, которой места нет, SHALL ждать его в очереди процесса по +порядку прихода, но не дольше `[uploads] wait_timeout_seconds`. В +очереди SHALL быть не больше `[uploads] max_waiting` загрузок. Если +очередь полна, ответ SHALL отдаваться сразу. Если за срок ожидания +место не освободилось, ответ SHALL отдаваться по его истечении. Ответ в +обоих случаях — 429 `rate_limited` в формате ошибки с заголовком +`Retry-After` — положительным целым числом секунд. Такая загрузка MUST +NOT оставлять ни метаданных, ни объекта. Ожидающая загрузка MUST NOT +держать соединение с PostgreSQL. + +Места считает каждый процесс отдельно. Балансировщик ответ 429 на другой +реплике не повторяет (`load-balancing`), загрузку повторяет клиент после +`Retry-After`. + +Память загрузок процесса SHALL ограничиваться числом мест, а не числом +клиентов. Ожидающее или отклонённое соединение SHALL держать в памяти +процесса и в буферах его сокетов не больше 1 MiB, каким бы ни было +тело. + +#### Scenario: Загрузки в пределах лимита + +- **WHEN** 10 участников одного чата одновременно загружают по + настоящему PNG около 1 MiB, а параметры загрузок — по умолчанию +- **THEN** все ответы 201 с разными `id`, и каждое вложение скачивается + с тем же SHA-256 + +#### Scenario: Все места заняты + +- **WHEN** все места загрузки процесса заняты загрузками, тела которых + ещё идут, приходит ещё одна загрузка, и место за срок ожидания не + освобождается +- **THEN** ответ 429 `rate_limited` с `Retry-After` не меньше 1 приходит + не раньше срока ожидания, а нового вложения нет ни в PostgreSQL, ни в + bucket + +#### Scenario: Очередь ожидания полна + +- **WHEN** все места загрузки процесса заняты, и очередь ожидания полна +- **THEN** следующая загрузка сразу получает 429 `rate_limited` с + `Retry-After`, без ожидания + +#### Scenario: Ожидание места + +- **WHEN** место занято загрузкой, которая заканчивается раньше срока + ожидания, а следующая загрузка ждёт его в очереди +- **THEN** ожидавшая загрузка получает 201, и её вложение скачивается с + тем же SHA-256 + +#### Scenario: Место освобождается + +- **WHEN** загрузка на единственном месте процесса заканчивается 413 по + счётчику, 415 по содержимому, 400 по сроку тела, обрывом клиента или + 503 при остановленном S3 +- **THEN** после каждой такой загрузки следующая получает место сразу: + ответ 201 без ожидания (после 503 — когда S3 вернулся) + +#### Scenario: Память не растёт с числом загрузок + +- **WHEN** 10, 20 и 40 клиентов одновременно и без пауз загружают по + 10 MiB в одну реплику с параметрами по умолчанию (профиль загрузок + стенда `bench/`, вариант «с лимитом») +- **THEN** пик памяти реплики в каждом случае не больше половины лимита + контейнера, при 20 и 40 клиентах он выше, чем при 10, не больше чем на + 1 MiB на каждого клиента сверх 10, реплика не завершена из-за памяти, + лишние загрузки получают 429, а ответов 5xx нет + +### Requirement: Срок передачи тела + +Тело загрузки SHALL приходить целиком не позже `[uploads] +body_timeout_seconds` после того, как загрузка заняла место. Иначе +ответ SHALL быть 400 `invalid_request` в формате ошибки. Загрузка при +этом MUST NOT оставлять ни метаданных, ни объекта, и её место +освобождается. Тело, которое пришло в срок, SHALL приниматься, как бы +мелко его ни делил клиент и какие бы паузы ни делал. + +#### Scenario: Медленный клиент + +- **WHEN** участник шлёт настоящий PNG частями так, что тело идёт + дольше срока передачи +- **THEN** ответ 400 `invalid_request`, нового вложения нет ни в + PostgreSQL, ни в bucket, а следующая загрузка — 201 без ожидания места + +#### Scenario: Медленная передача в срок + +- **WHEN** участник шлёт настоящий PNG мелкими частями с паузами и + укладывается в срок передачи +- **THEN** ответ 201, а `size_bytes` и `sha256` совпадают с файлом diff --git a/openspec/specs/load-balancing/spec.md b/openspec/specs/load-balancing/spec.md index 0dc3cb60..0bf6357c 100644 --- a/openspec/specs/load-balancing/spec.md +++ b/openspec/specs/load-balancing/spec.md @@ -136,12 +136,17 @@ NOT повторяться LB: ни по таймауту ответа, ни п ### Requirement: Ошибки балансировщика в формате контракта -Ответы, которые создаёт сам LB, SHALL иметь статус 502, 503 или 504 и -тело в формате ошибки контракта с `code` `unavailable`. Такие ответы -возникают, когда нет готовых реплик, ответ реплики оборвался или не -пришёл вовремя. `request_id` тела SHALL совпадать с заголовком -`X-Request-Id`, который ставит LB. `X-Instance-Id` у таких ответов -может отсутствовать. +Ответы, которые создаёт сам LB, SHALL иметь статус 400, 502, 503 или +504 и тело в формате ошибки контракта. У 502, 503 и 504 `code` — +`unavailable`: нет готовых реплик, ответ реплики оборвался или не пришёл +вовремя. У 400 `code` — `invalid_request`: запрос клиента неверен или +клиент замолчал посреди тела дольше `timeout client` LB. `request_id` +тела SHALL совпадать с заголовком `X-Request-Id`, который ставит LB. +`X-Instance-Id` у таких ответов может отсутствовать. + +Ограничение называется в `REPORT.md`: ответ 408 на заголовки, которые +не пришли за `timeout http-request`, LB отдаёт своим текстом, а не в +формате ошибки контракта. #### Scenario: Нет готовых реплик @@ -150,6 +155,13 @@ NOT повторяться LB: ни по таймауту ответа, ни п - **THEN** ответ 503 с телом `{"error": {"code": "unavailable", ...}}`, `request_id` равен `X-Request-Id`, а других полей в теле нет +#### Scenario: Клиент замолчал посреди тела + +- **WHEN** клиент через LB отправил часть тела загрузки и молчит дольше + `timeout client` LB +- **THEN** ответ LB 400 с телом `{"error": {"code": "invalid_request", + ...}}`, `request_id` равен `X-Request-Id`, а других полей в теле нет + ### Requirement: Отказ одной реплики При остановке любой одной реплики из двух и более новые чтения и @@ -394,9 +406,11 @@ SHALL оставаться доступной. Перед плановой остановкой реплики LB SHALL перестать направлять ей новые запросы. Запросы, которые она уже обрабатывает, SHALL дорабатываться. Остановка SHALL начинаться после того, как запросов в -полёте у неё не осталось, или по истечении срока ожидания, большего -`timeout server` LB. Управление LB SHALL быть доступно только изнутри -контейнера LB. Из сети compose и с хоста оно MUST NOT быть доступно. +полёте у неё не осталось, или по истечении срока ожидания. Срок SHALL +быть больше `timeout server` LB и больше наибольшей длительности живой +загрузки (требование «Загрузки через балансировщик»). Управление LB +SHALL быть доступно только изнутри контейнера LB. Из сети compose и с +хоста оно MUST NOT быть доступно. Состояние слота, выставленное при замене, SHALL сниматься, когда адрес удалённой реплики ушёл из слота. Слот, который потом получит новая @@ -421,6 +435,14 @@ SHALL оставаться доступной. - **THEN** в статистике LB нет слотов в дренаже или в обслуживании, выставленном вручную; свободные слоты — только в обслуживании по DNS +#### Scenario: Загрузка во время дренажа + +- **WHEN** через LB идёт загрузка вложения, тело которой передаётся + дольше 12 с, и во время неё `make rolling_update` выводит реплику, + которая её принимает +- **THEN** загрузка получает 201 от этой реплики, и только после ответа + реплика останавливается + ### Requirement: Сбой поочерёдной замены Если новая реплика не стала готовой в LB за срок ожидания или замена @@ -456,3 +478,54 @@ SHALL быть без состояния, выставленного вручн - **WHEN** скрипт прерван Ctrl+C, пока старая реплика выводится из LB - **THEN** старая реплика остановлена и удалена, новая работает, реплик `API_REPLICAS`, а слот старой реплики без ручного состояния + +### Requirement: Загрузки через балансировщик + +Для `POST /api/v1/chats/{chat_id}/attachments` срок, в который LB ждёт +реплику (`timeout server`), SHALL быть 30 с. Это больше самого длинного +молчания живой загрузки: +- до чтения тела — вход, членство в чате и ожидание места загрузки, не + дольше `2 × [database] request_timeout_seconds + [uploads] + wait_timeout_seconds` (17 с); +- после тела — проверка изображения, запись метаданных, запись объекта, + перевод в `ready` и удаление объекта при компенсации, не дольше `2 × + request_timeout_seconds + 2 × [s3] timeout_seconds` плюс проверка + изображения (около 26 с). + +У остальных путей срок SHALL оставаться прежним, 10 с: цепочка +таймаутов лабы 3 для них не меняется. + +Наибольшая длительность живой загрузки — молчание до тела, срок +передачи тела (`[uploads] body_timeout_seconds`) и молчание после тела, +около 73 с при значениях по умолчанию. Она и формула SHALL быть в +`REPORT.md`. + +Соединение с недочитанным телом SHALL держать в буферах ядра ограниченный +объём: буфер приёма сокетов реплики API — не больше 512 KiB, буфер +отправки LB к реплике — 256 KiB. Так ожидающие и отклонённые загрузки не +переносят тела целиком ни в память реплики, ни в память LB. + +#### Scenario: Долгая обработка загрузки + +- **WHEN** реплика на пути загрузки молчит дольше 10 с, но меньше 30 с: + до чтения тела или после него +- **THEN** клиент получает ответ реплики, а не 502 или 504 от LB + +#### Scenario: Прежний срок остальных путей + +- **WHEN** реплика молчит дольше 10 с на любом другом пути +- **THEN** через ~10 с клиент получает 504 от LB в формате ошибки + контракта + +#### Scenario: Загрузка дольше срока LB + +- **WHEN** реплика на пути загрузки молчит дольше 30 с +- **THEN** через ~30 с клиент получает 504 от LB в формате ошибки + контракта + +#### Scenario: Буферы соединений ограничены + +- **WHEN** 40 клиентов одновременно загружают по 10 MiB через LB в одну + реплику с параметрами загрузок по умолчанию +- **THEN** пик памяти LB и буферов сокетов реплики растёт не больше чем + на 1 MiB на клиента, а реплика и LB не завершены из-за памяти diff --git a/openspec/specs/load-benchmark/spec.md b/openspec/specs/load-benchmark/spec.md index da19c0b2..3d6ce9c4 100644 --- a/openspec/specs/load-benchmark/spec.md +++ b/openspec/specs/load-benchmark/spec.md @@ -68,18 +68,21 @@ run_dev` / `make run_docker`). После завершения, в том чис ### Requirement: Фиксированный стенд Стенд SHALL состоять из балансировщика (LB), реплик приложения, -PostgreSQL и Valkey. Число реплик SHALL задаваться методикой, по -умолчанию одна. Приложение SHALL запускаться в контейнерах из образа, -собранного из текущего checkout тем же `Dockerfile`. Исключение — -профиль поочерёдной замены. Он стартует на образе commit, заданного -методикой: образ собирается тем же `Dockerfile` из файлов этого commit -без изменения рабочего дерева. Заканчивается профиль на образе текущего -checkout. LB SHALL +PostgreSQL и Valkey. В профиле загрузок к ним SHALL добавляться S3 с +его bootstrap. Число реплик SHALL задаваться методикой, по умолчанию +одна. Приложение SHALL запускаться в контейнерах из образа, собранного +из текущего checkout тем же `Dockerfile`. Исключения — профиль +поочерёдной замены и вариант «до» профиля загрузок. Они берут образ +commit, заданного методикой: образ собирается тем же `Dockerfile` из +файлов этого commit без изменения рабочего дерева. Профиль замены +заканчивается на образе текущего checkout. LB SHALL запускаться из того же образа и с той же конфигурацией, что у рабочего стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL получает те же настройки образа плюс модуль записи планов, выключенный -вне снятия плана. В сериях трека 1 предел соединений PostgreSQL +вне снятия плана. S3 SHALL запускаться из того же образа и с теми же +аргументами сервера, что у рабочего стенда, а bucket и пользователей +создаёт тот же bootstrap. В сериях трека 1 предел соединений PostgreSQL (`max_connections`) — параметр конфигурации серии, по умолчанию 100, как у образа. Схема БД SHALL применяться миграциями до наполнения. @@ -88,20 +91,24 @@ checkout. LB SHALL - у каждой реплики приложения — лимит CPU и памяти без swap, заданный методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по конфигурации); -- у LB, PostgreSQL и Valkey — свои лимиты CPU и памяти без swap, +- у LB, PostgreSQL, Valkey и S3 — свои лимиты CPU и памяти без swap, заданные методикой; в серии трека 1 они одинаковы во всех конфигурациях; - у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без swap, заданный методикой; в остальных профилях генератор без лимита. +Буфер приёма сокетов реплик приложения SHALL быть ограничен так же, как +у рабочего стенда (`load-balancing`, «Загрузки через балансировщик»). +Значение SHALL записываться в паспорт. + Healthcheck образа приложения SHALL быть отключён: готовность реплик проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки приложения и хранилищ SHALL браться из методики стенда, а не из `.env` -и `config.toml` рабочего стенда. Пароли хранилищ SHALL генерироваться -на прогон. Генератор нагрузки SHALL работать в той же docker-сети и -обращаться к приложению через LB по имени сервиса, минуя проброс -портов хоста. Стенд SHALL считаться готовым, когда LB видит готовыми -все реплики. +и `config.toml` рабочего стенда. Пароли хранилищ и секреты S3 SHALL +генерироваться на прогон. Генератор нагрузки SHALL работать в той же +docker-сети и обращаться к приложению через LB по имени сервиса, минуя +проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит +готовыми все реплики. #### Scenario: Лимиты в паспорте @@ -152,6 +159,13 @@ Healthcheck образа приложения SHALL быть отключён: его последней ревизии, рабочее дерево не меняется, а commit и образы до и после записаны в паспорт +#### Scenario: S3 в профиле загрузок + +- **WHEN** запускается профиль загрузок +- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами + и лимитами, bootstrap завершился успешно, а образ и лимиты S3 и + ограничение буфера приёма реплики записаны в паспорт + ### Requirement: Сценарии нагрузки Стенд SHALL поддерживать два сценария с синтетическими данными @@ -1824,3 +1838,111 @@ change `attachments`. Commit SHALL меняться при переходе в - **WHEN** commit методики не найден в репозитории - **THEN** команда завершается с ненулевым кодом до запуска стенда, а сообщение называет commit и `--from` + +### Requirement: Профиль загрузок + +Команда `make bench_uploads` (метка `UPLOADS_LABEL`, по умолчанию +`baseline`) SHALL на свежем стенде мерить память реплики при +одновременных загрузках вложений. Команда `make bench_uploads_quick` — +то же короче, метка `quick-uploads-…`, в git не идёт. Результаты SHALL +сохраняться в `evidence/uploads/<метка>/`. Занятая метка SHALL давать +отказ до запуска стенда. + +Стенд — LB и одна реплика с лимитами рабочего стенда (1 CPU, 512 МБ без +swap), PostgreSQL, Valkey и S3 с лимитами рабочего стенда. + +Варианты кода: +- «до» — образ commit из методики, последнего до change `upload-memory`; +- «без лимита» — образ текущего checkout, мест загрузки больше, чем + клиентов, очереди нет; +- «с лимитом» — образ текущего checkout с параметрами загрузок по + умолчанию. + +Тела — настоящие PNG около 1 MiB и около 10 MiB, не больше лимита +контракта. Их строит оркестратор, детерминированно от зерна методики. + +Прогон — вариант × размер × число одновременных клиентов (1, 10, 20 и +40) × повтор. Повторов в полном профиле три. Каждый прогон SHALL идти на +новом контейнере реплики и новом volume S3. Клиенты загружают без пауз +окно, заданное методикой. На 429 клиент ждёт `Retry-After`, на прочие +ошибки — секунду. + +Для каждого прогона SHALL сохраняться: +- пик памяти реплики за окно — пик cgroup, сброшенный в начале окна, — + и память перед окном; +- наибольшие анонимная память и память буферов сокетов реплики; +- было ли завершение реплики из-за памяти; +- ответы по кодам, ошибка соединения — отдельным кодом; +- успешных загрузок в секунду, p50, p95 и p99 успешных; +- пик памяти S3 (в том числе анонимной) и LB. + +Прогон с завершением реплики из-за памяти SHALL помечаться `oom` и +записываться как результат варианта, а не как сбой команды. Следующий +прогон идёт на новой реплике. + +Граница чёрного ящика: генератор обращается к приложению только по HTTP +через LB, оркестратор управляет стендом через docker CLI. Сверх этого он +читает счётчики памяти cgroup контейнеров и пересоздаёт volume S3 с +bootstrap между прогонами. К bucket и объектам он не обращается. + +В паспорте метки SHALL быть: +- лимиты и образы, в том числе commit варианта «до»; +- окружение приложения каждого варианта без секретов; +- размеры и SHA-256 тел; +- версия ядра ВМ; +- ограничение буфера приёма сокетов реплики; +- состояние хоста. + +#### Scenario: Полный профиль + +- **WHEN** выполнен `make bench_uploads` +- **THEN** в `evidence/uploads/<метка>/` есть паспорт, таблица прогонов + (три варианта × два размера × четыре уровня × три повтора), сводка по + ячейкам с медианой и разбросом повторов и сырые итоги генератора, код + выхода 0 + +#### Scenario: Быстрый профиль + +- **WHEN** выполнен `make bench_uploads_quick` +- **THEN** за несколько минут проходят варианты «без лимита» и «с + лимитом» на 10 MiB при 1, 10 и 40 клиентах, по одному повтору, код + выхода 0, каталог метки в git не попадает + +#### Scenario: Реплика убита из-за памяти + +- **WHEN** в прогоне реплику завершило ядро из-за памяти +- **THEN** прогон помечен `oom`, в таблице есть ответы по кодам до и + после завершения, следующий прогон идёт на новой реплике, а команда + не прерывается + +#### Scenario: Пик окна без памяти старта + +- **WHEN** реплика при старте заняла больше памяти, чем в окне прогона +- **THEN** пик прогона отражает только окно, а не старт процесса + +### Requirement: Загрузки в отчёте + +`REPORT.md` SHALL содержать по профилю загрузок: +- гипотезы о пике памяти с лимитом и без него, о пропускной способности + и о сроке записи в S3. Они записаны и зафиксированы commit до первого + прогона метки; +- методику: стенд, лимиты, варианты, тела, уровни, окно, повторы; +- таблицу результатов по меткам: пик памяти, завершения из-за памяти, + ответы по кодам, загрузок в секунду и p95 — по вариантам, размерам и + уровням; +- выводы по каждой гипотезе и ограничения: один хост, ВМ Docker Desktop, + генератор на том же хосте, одна нода S3. + +Числа в отчёт SHALL переноситься из сводки метки, а не пересчитываться +вручную. + +#### Scenario: Гипотезы до прогонов + +- **WHEN** проверяющий смотрит историю `REPORT.md` и каталога метки +- **THEN** commit с гипотезами раньше commit с результатами метки + +#### Scenario: Выводы по метке + +- **WHEN** проверяющий открывает раздел загрузок в `REPORT.md` +- **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки + метки, а числа совпадают со сводкой diff --git a/openspec/specs/service-configuration/spec.md b/openspec/specs/service-configuration/spec.md index 5aae9fd1..185d9e6e 100644 --- a/openspec/specs/service-configuration/spec.md +++ b/openspec/specs/service-configuration/spec.md @@ -415,3 +415,51 @@ grace SHALL быть описаны в `REPORT.md`. - **WHEN** уборщик запускается с `CLEANER__INTERVAL_SECONDS=0` или `CLEANER__INTERVAL_SECONDS=abc` - **THEN** уборщик не стартует, в журнале — ошибка проверки настроек + +### Requirement: Параметры загрузок + +Ограничения загрузок вложений процесса API (capability `attachments`, +«Одновременные загрузки реплики», «Срок передачи тела») SHALL +задаваться в секции `[uploads]`: +- `max_concurrent` — сколько загрузок процесс обрабатывает одновременно, + по умолчанию 4; +- `max_waiting` — сколько загрузок может ждать места, по умолчанию 16; + 0 — без ожидания, загрузка без места сразу получает 429; +- `wait_timeout_seconds` — сколько секунд загрузка ждёт места, по + умолчанию 5; +- `body_timeout_seconds` — за сколько секунд после того, как загрузка + заняла место, должно прийти её тело, по умолчанию 30. + +`max_concurrent` SHALL быть целым не меньше 1, `max_waiting` — целым не +меньше 0, сроки — положительными числами. Иначе сервис MUST NOT +стартовать (требование «Некорректное значение останавливает запуск»). +Значения SHALL одинаково действовать в консоли и в docker. Разовая +подмена SHALL работать через окружение `UPLOADS__*` без правки файлов. +Запись журнала о старте API SHALL называть все четыре значения. + +Значения по умолчанию и их обоснование SHALL быть описаны в `REPORT.md`: +- бюджет памяти реплики: интерпретатор, хэши паролей и места загрузок в + лимите контейнера; +- сроки пути загрузки в балансировщике (`load-balancing`, «Загрузки + через балансировщик»). + +#### Scenario: Параметры загрузок по умолчанию + +- **WHEN** сервис запущен без секции `[uploads]` и без переменных + `UPLOADS__*` +- **THEN** запись журнала о старте называет 4 места, 16 ожидающих, + ожидание 5 с и срок тела 30 с + +#### Scenario: Подмена параметров загрузок окружением + +- **WHEN** сервис запущен с `UPLOADS__MAX_CONCURRENT=1` и + `UPLOADS__MAX_WAITING=0`, а файлы не менялись +- **THEN** вторая одновременная загрузка, пока первая не закончилась, + сразу получает 429 + +#### Scenario: Неверный параметр загрузок + +- **WHEN** сервис запускается с `UPLOADS__MAX_CONCURRENT=0`, + `UPLOADS__MAX_WAITING=-1` или `UPLOADS__BODY_TIMEOUT_SECONDS=abc` +- **THEN** сервис не стартует, в журнале — ошибка проверки настроек с + именем поля diff --git a/openspec/specs/storage-consistency/spec.md b/openspec/specs/storage-consistency/spec.md index 9e3185bf..40039be1 100644 --- a/openspec/specs/storage-consistency/spec.md +++ b/openspec/specs/storage-consistency/spec.md @@ -67,7 +67,11 @@ Grace SHALL быть больше наибольшего времени, за к проходит путь от записи метаданных до фиксации `ready`. Это два шага с PostgreSQL и запись объекта, у каждого свой срок (capability `service-configuration`, «Параметры уборщика»). Возраст загрузки -отсчитывается от записи её метаданных по часам приложения. +отсчитывается от записи её метаданных по часам приложения. Ожидание +места загрузки, чтение тела и проверка изображения (capability +`attachments`, «Одновременные загрузки реплики», «Срок передачи тела») +SHALL идти до записи метаданных и в эту границу не входят: очередь +загрузок и медленный клиент её не удлиняют. Загрузка, которая длится дольше grace (процесс API заморожен), и уборщик SHALL исключать друг друга на одном вложении. Исходов два: @@ -120,6 +124,13 @@ S3 выполнил удаление уже после срока вызова. - **THEN** метаданные вложения — 200 в статусе `ready`, а байты скачиваются с тем же SHA-256 +#### Scenario: Ожидание места не входит в возраст загрузки + +- **WHEN** загрузка ждала места, пока его держала другая загрузка того + же процесса, и обе завершились 201 +- **THEN** время записи метаданных ожидавшей (`created_at`) позже + перевода в `ready` той, что держала место (`updated_at`) + ### Requirement: Уборка при отказах хранилищ Уборщик MUST NOT удалять метаданные незавершённой загрузки, пока diff --git a/openspec/specs/student-tests/spec.md b/openspec/specs/student-tests/spec.md index ab555645..bf18bed0 100644 --- a/openspec/specs/student-tests/spec.md +++ b/openspec/specs/student-tests/spec.md @@ -367,19 +367,26 @@ PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по «Очистка кэша»; - `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке», «Ключ после срока»; +- `api-conventions`: «Лимит одновременных загрузок»; - `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв - передачи тела»; + передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь + ожидания полна», «Ожидание места», «Место освобождается», «Медленный + клиент», «Медленная передача в срок»; - `storage-consistency`: все сценарии. Команда SHALL: - собрать образ из рабочего дерева; - поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить миграции и bootstrap S3; -- запустить два API: с настройками по умолчанию и «тесный» — с - коротким сроком сессии и ключа идемпотентности и пулом из одного - соединения; +- запустить три API: + - с настройками по умолчанию; + - «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом + из одного соединения; + - «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в + очереди, коротким сроком ожидания места и коротким сроком тела. Их + значения SHALL передаваться проверкам; - запустить уборщика с коротким grace и интервалом, сравнимыми со временем теста, и передать их значения проверкам. Grace при этом SHALL проходить проверку границы живой загрузки (`service- diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh index 3ed885a2..d3f4d058 100755 --- a/scripts/rolling-update.sh +++ b/scripts/rolling-update.sh @@ -24,8 +24,11 @@ set -eu # ROLLOUT_MIGRATE=0 — без миграций: откат на прежний образ, его миграции # не знают новой ревизии, а схема только расширялась; # ROLLOUT_READY_TIMEOUT (60) — срок готовности новой реплики, с; -# ROLLOUT_DRAIN_TIMEOUT (12) — срок дренажа старой, с: больше timeout -# server LB (10 с), дольше запрос через LB не живёт. +# ROLLOUT_DRAIN_TIMEOUT (90) — срок дренажа старой, с: больше timeout +# server пути загрузки и наибольшей длительности загрузки (LB 30 с, +# загрузка ≈ 73 с — haproxy.cfg, design change upload-memory, решение +# 7), иначе плановая замена оборвала бы живую загрузку. Обычно дренаж +# кончается за 0–2 с, срок нужен только медленной загрузке. # Проект compose — как у самого docker compose: COMPOSE_PROJECT_NAME, # COMPOSE_FILE, COMPOSE_ENV_FILES или docker-compose.yml и .env # репозитория; стенд bench/ (профиль rollout) вызывает этот же скрипт со @@ -39,7 +42,7 @@ LB_API_PORT=9999 replicas="${API_REPLICAS:-2}" ready_timeout="${ROLLOUT_READY_TIMEOUT:-60}" -drain_timeout="${ROLLOUT_DRAIN_TIMEOUT:-12}" +drain_timeout="${ROLLOUT_DRAIN_TIMEOUT:-90}" commit="${ROLLOUT_COMMIT:-}" migrate="${ROLLOUT_MIGRATE:-1}" diff --git a/src/api/dependencies.py b/src/api/dependencies.py index 6a48b7c0..e66459b3 100644 --- a/src/api/dependencies.py +++ b/src/api/dependencies.py @@ -2,7 +2,8 @@ Сервисы получают сессию БД, а чаты и сообщения — ещё и кэш процесса (`src/infra/cache/instance.py`). Вложения — фабрику короткой сессии на -шаг, кэш и хранилище объектов (`src/infra/s3/instance.py`). +шаг, кэш, хранилище объектов (`src/infra/s3/instance.py`) и места +загрузок процесса (`src/infra/upload_slots.py`). """ import base64 @@ -33,6 +34,7 @@ from src.infra.db.scope import session_scope from src.infra.db.session import engine, session_factory from src.infra.logger import current_user_id from src.infra.s3.instance import object_storage +from src.infra.upload_slots import upload_slots from src.schemas import dataclasses from src.utils.constants import ( PAGE_LIMIT_DEFAULT, @@ -108,6 +110,7 @@ async def get_attachment_service() -> AttachmentService: db_scope=db_session_scope, cache=cache, storage=object_storage, + slots=upload_slots, ) diff --git a/src/api/errors.py b/src/api/errors.py index e29087e1..2a01422f 100644 --- a/src/api/errors.py +++ b/src/api/errors.py @@ -20,6 +20,7 @@ from src.utils.constants import ( AUTH_REALM, INSTANCE_ID_HEADER, REQUEST_ID_HEADER, + UPLOAD_RETRY_AFTER_SECONDS, ) DOMAIN_ERRORS: dict[type[exceptions.DomainError], tuple[int, ErrorCode]] = { @@ -33,7 +34,12 @@ DOMAIN_ERRORS: dict[type[exceptions.DomainError], tuple[int, ErrorCode]] = { exceptions.InvalidCursor: (400, ErrorCode.INVALID_REQUEST), exceptions.InvalidFilename: (400, ErrorCode.INVALID_REQUEST), exceptions.UploadInterrupted: (400, ErrorCode.INVALID_REQUEST), + # тело не пришло за срок: как обрыв, клиент не доставил тело + exceptions.UploadTimedOut: (400, ErrorCode.INVALID_REQUEST), exceptions.PayloadTooLarge: (413, ErrorCode.PAYLOAD_TOO_LARGE), + # места загрузки процесса заняты (design change upload-memory, + # решение 2); заголовок Retry-After — RETRY_AFTER ниже + exceptions.UploadsBusy: (429, ErrorCode.RATE_LIMITED), exceptions.UnsupportedMediaType: ( 415, ErrorCode.UNSUPPORTED_MEDIA_TYPE, @@ -53,6 +59,11 @@ CHALLENGES: dict[type[exceptions.DomainError], str] = { exceptions.Unauthenticated: f'Bearer realm="{AUTH_REALM}"', } +# Retry-After у 429: через сколько секунд повторить запрос +RETRY_AFTER: dict[type[exceptions.DomainError], int] = { + exceptions.UploadsBusy: UPLOAD_RETRY_AFTER_SECONDS, +} + HTTP_ERRORS: dict[int, tuple[ErrorCode, str]] = { 404: (ErrorCode.NOT_FOUND, "Not found"), 405: (ErrorCode.INVALID_REQUEST, "Method not allowed"), @@ -89,13 +100,17 @@ async def handle_domain_error( status_code, code = next( DOMAIN_ERRORS[cls] for cls in type(exc).__mro__ if cls in DOMAIN_ERRORS ) - challenge = CHALLENGES.get(type(exc)) + headers: dict[str, str] = {} + if challenge := CHALLENGES.get(type(exc)): + headers["WWW-Authenticate"] = challenge + if (retry_after := RETRY_AFTER.get(type(exc))) is not None: + headers["Retry-After"] = str(retry_after) return error_response( request_id=_request_id(request), status_code=status_code, code=code, message=str(exc), - headers={"WWW-Authenticate": challenge} if challenge else None, + headers=headers or None, ) diff --git a/src/config/settings.py b/src/config/settings.py index 7b2a53f5..d48c090f 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -226,6 +226,26 @@ class Idempotency(BaseModel): ttl_seconds: int = Field(default=86400, gt=0) +class Uploads(BaseModel): + """Места загрузок вложений процесса API (design change + `upload-memory`, решения 1–4 и 9). + + Значения — из `config.toml`, разовая подмена — окружением + `UPLOADS__*`. Память загрузок ограничена числом мест, а не числом + клиентов; сроки — часть цепочки таймаутов пути загрузки в LB + (`infra/haproxy/haproxy.cfg`, `REPORT.md`). + """ + + # загрузок, которые процесс обрабатывает одновременно (места) + max_concurrent: int = Field(default=4, ge=1) + # загрузок, которые ждут места; 0 — без ожидания, сразу 429 + max_waiting: int = Field(default=16, ge=0) + # секунды ожидания места; не вышло — 429 + wait_timeout_seconds: float = Field(default=5, gt=0) + # секунды на всё тело с момента, как загрузка заняла место; иначе 400 + body_timeout_seconds: float = Field(default=30, gt=0) + + class Cleaner(BaseModel): """Уборщик незавершённых загрузок (`python -m src.cleaner`). @@ -258,6 +278,7 @@ class Settings(BaseSettings): cache: Cache = Cache() s3: S3 = S3() idempotency: Idempotency = Idempotency() + uploads: Uploads = Uploads() cleaner: Cleaner = Cleaner() @classmethod diff --git a/src/core/exceptions/__init__.py b/src/core/exceptions/__init__.py index d3eb6e98..90de92d6 100644 --- a/src/core/exceptions/__init__.py +++ b/src/core/exceptions/__init__.py @@ -5,6 +5,8 @@ from .attachment import ( PayloadTooLarge, UnsupportedMediaType, UploadInterrupted, + UploadsBusy, + UploadTimedOut, ) from .base import DomainError from .chat import ChatNotFound, InvalidChatMembers @@ -32,5 +34,7 @@ __all__ = [ "Unauthenticated", "UnsupportedMediaType", "UploadInterrupted", + "UploadTimedOut", + "UploadsBusy", "UsernameTaken", ] diff --git a/src/core/exceptions/attachment.py b/src/core/exceptions/attachment.py index b617e1be..aa51488b 100644 --- a/src/core/exceptions/attachment.py +++ b/src/core/exceptions/attachment.py @@ -36,6 +36,19 @@ class UploadInterrupted(DomainError): default_message = "Upload interrupted" +class UploadsBusy(DomainError): + """Места загрузки процесса заняты: очередь ожидания полна или место не + освободилось за срок ожидания (429 с `Retry-After`).""" + + default_message = "Too many uploads in progress, retry later" + + +class UploadTimedOut(DomainError): + """Тело загрузки не пришло целиком за срок после занятия места.""" + + default_message = "Upload body was not received in time" + + class AttachmentContentMissing(DomainError): """У готового вложения нет объекта в S3 или его размер другой. diff --git a/src/core/repos/attachment_object.py b/src/core/repos/attachment_object.py index 3f3158f3..bfe4f733 100644 --- a/src/core/repos/attachment_object.py +++ b/src/core/repos/attachment_object.py @@ -9,6 +9,7 @@ Repo над хранилищем объектов, как `chat_cache.py` над """ from contextlib import AbstractAsyncContextManager +from typing import BinaryIO from uuid import UUID from src.infra.s3 import ObjectStorage, StoredObject @@ -34,10 +35,12 @@ async def put_original( storage: ObjectStorage, *, key: str, - data: bytes, + body: BinaryIO, + size: int, content_type: str, ) -> None: - await storage.put(key, data, content_type=content_type) + """Записать оригинал из потока с начала: тело не копируется.""" + await storage.put(key, body, size=size, content_type=content_type) async def delete_original(storage: ObjectStorage, *, key: str) -> None: diff --git a/src/core/services/attachment.py b/src/core/services/attachment.py index 745f422a..0f3a6fe6 100644 --- a/src/core/services/attachment.py +++ b/src/core/services/attachment.py @@ -1,13 +1,16 @@ +import asyncio import hashlib import io import time from collections.abc import AsyncIterator, Callable from contextlib import AbstractAsyncContextManager, AsyncExitStack +from typing import TYPE_CHECKING from uuid import UUID, uuid4 import anyio.to_thread from sqlalchemy.ext.asyncio import AsyncSession +from src.config import settings from src.core import exceptions from src.core.repos import attachment as attachment_repo from src.core.repos import attachment_object as attachment_object_repo @@ -27,6 +30,11 @@ from src.utils.image import ( ) from src.utils.utc import utcnow +if TYPE_CHECKING: + # только тип: глобал мест создаёт импорт модуля, а его берёт лишь + # src/api/dependencies.py (infra.md) + from src.infra.upload_slots import UploadSlots + logger: AbstractLogger = get_logger().bind(module="attachment_service") # Content-Type загрузки: тип без параметров, в нижнем регистре @@ -48,7 +56,9 @@ class AttachmentService: Сессии на весь запрос нет: каждый шаг с БД — свой короткий `async with self.db_scope()`, без вложенных, поэтому ни одно соединение пула не занято передачей тела (design change - `attachments`, решение 5). `filename` в журнал не пишется. + `attachments`, решение 5). Загрузка идёт на месте из `slots` — мест + процесса (design change `upload-memory`, решение 1); ожидающая + загрузка соединения с БД не держит. `filename` в журнал не пишется. """ def __init__( @@ -56,10 +66,12 @@ class AttachmentService: db_scope: DbScope, cache: Cache, storage: ObjectStorage, + slots: "UploadSlots", ) -> None: self.db_scope = db_scope self.cache = cache self.storage = storage + self.slots = slots async def _require_member( self, @@ -86,13 +98,17 @@ class AttachmentService: """Загрузка оригинала; 201 только после `ready` в БД. Порядок проверок — спек «Порядок проверок загрузки»: членство - (404), `Content-Type` (415), `Content-Length` (413), затем тело со - счётчиком (413) и содержимое (415 или 413). Порядок записи - (design change `attachments`, решение 1): строка `pending` с - ключом объекта — commit, PUT, `ready` — commit. Отказ S3 или БД - после строки `pending` — 503, строка остаётся до уборщика; - компенсация после записанного объекта — `_mark_ready` (design - change `upload-consistency`, решение 1). + (404), `Content-Type` (415), `Content-Length` (413) — без места; + затем место загрузки (429, design change `upload-memory`, решения + 1–3), тело со счётчиком и сроком (413, 400) и содержимое (415 или + 413). Место держится до ответа, включая запись и компенсацию. + Ожидание места, тело и проверка идут до строки `pending`, поэтому + граница живой загрузки уборщика прежняя. Порядок записи (design + change `attachments`, решение 1): строка `pending` с ключом + объекта — commit, PUT, `ready` — commit. Отказ S3 или БД после + строки `pending` — 503, строка остаётся до уборщика; компенсация + после записанного объекта — `_mark_ready` (design change + `upload-consistency`, решение 1). """ started = time.monotonic() log = logger.bind( @@ -119,7 +135,44 @@ class AttachmentService: declared_size=content_length, ) raise exceptions.PayloadTooLarge - data = await self._read_body(body=body, log=log) + waiting_since = time.monotonic() + try: + async with self.slots.slot() as waited_ms: + return await self._store( + chat_id=chat_id, + owner_id=owner_id, + filename=filename, + media_type=media_type, + body=body, + started=started, + waited_ms=waited_ms, + log=log, + ) + except exceptions.UploadsBusy: + # бросает только вход в место: тело не читалось, строки нет + log.info( + "Rejected attachment", + reason="busy", + waited_ms=round((time.monotonic() - waiting_since) * 1000), + ) + raise + + async def _store( + self, + *, + chat_id: UUID, + owner_id: UUID, + filename: str, + media_type: str, + body: AsyncIterator[bytes], + started: float, + waited_ms: int, + log: AbstractLogger, + ) -> dataclasses.AttachmentFullDTO: + """Путь загрузки на занятом месте: тело, проверка, запись.""" + buffer = await self._read_body(body=body, log=log) + # bytes над буфером BytesIO, без копии + data = buffer.getvalue() try: info, sha256 = await anyio.to_thread.run_sync(_inspect, data) except TooManyPixels as e: @@ -134,6 +187,12 @@ class AttachmentService: if info.content_type != media_type: log.info("Rejected attachment", reason="content_mismatch") raise exceptions.UnsupportedMediaType + size = len(data) + # пока жива ссылка на bytes, буфер BytesIO общий, и getbuffer() + # aiohttp при PUT скопировал бы тело целиком — два тела на загрузку + # вместо одного (design change upload-memory, решение 5, Context + # п. 1). После del буфер снова только у BytesIO + del data attachment_id = uuid4() now = utcnow() @@ -143,7 +202,7 @@ class AttachmentService: owner_id=owner_id, filename=filename, content_type=info.content_type, - size_bytes=len(data), + size_bytes=size, sha256=sha256, object_key=attachment_object_repo.original_key( self.storage, @@ -160,11 +219,13 @@ class AttachmentService: ) await db_session.commit() log = log.bind(attachment_id=attachment_id) + buffer.seek(0) try: await attachment_object_repo.put_original( self.storage, key=pending.object_key, - data=data, + body=buffer, + size=size, content_type=pending.content_type.value, ) except Exception: @@ -183,6 +244,7 @@ class AttachmentService: content_type=ready.content_type, width=info.width, height=info.height, + waited_ms=waited_ms, duration_ms=round((time.monotonic() - started) * 1000), ) return ready @@ -257,30 +319,40 @@ class AttachmentService: *, body: AsyncIterator[bytes], log: AbstractLogger, - ) -> bytes: - """Тело целиком; больше лимита — 413 сразу, без дочитывания. + ) -> io.BytesIO: + """Тело целиком в `BytesIO`; больше лимита — 413 сразу, без + дочитывания; не пришло за `[uploads] body_timeout_seconds` — 400. - Блоки копятся в `BytesIO`, а `getvalue()` отдаёт `bytes` над его - же буфером, без копии: в памяти одно тело и блок чтения (спек - «Лимит размера до чтения тела»). Именно `bytes`, а не - `bytearray`: botocore оборачивает тело `PutObject` в `BytesIO`, и - `bytes` он не копирует, а `bytearray` копирует. Рост буфера без - копии в образе даёт `MALLOC_MMAP_THRESHOLD_` (`Dockerfile`; - design, решение 6). + Блоки копятся в `BytesIO`: проверка берёт `getvalue()` (`bytes` + над его же буфером, без копии), а PUT — сам буфер (design change + `upload-memory`, решение 5). В памяти одно тело и блок чтения + (спек «Лимит размера до чтения тела»). Рост буфера без копии в + образе даёт `MALLOC_MMAP_THRESHOLD_` (`Dockerfile`; design change + `attachments`, решение 6). Срок — один на всё тело с момента, как + загрузка заняла место: клиент, который шлёт по байту, место + вечно не держит (design change `upload-memory`, решение 4). """ buffer = io.BytesIO() size = 0 try: - async for chunk in body: - size += len(chunk) - if size > ATTACHMENT_MAX_BYTES: - log.info("Rejected attachment", reason="size", size=size) - raise exceptions.PayloadTooLarge - buffer.write(chunk) + async with asyncio.timeout(settings.uploads.body_timeout_seconds): + async for chunk in body: + size += len(chunk) + if size > ATTACHMENT_MAX_BYTES: + log.info( + "Rejected attachment", + reason="size", + size=size, + ) + raise exceptions.PayloadTooLarge + buffer.write(chunk) except exceptions.UploadInterrupted: log.info("Rejected attachment", reason="interrupted") raise - return buffer.getvalue() + except TimeoutError as e: + log.info("Rejected attachment", reason="body_timeout", size=size) + raise exceptions.UploadTimedOut from e + return buffer async def get_attachment( self, diff --git a/src/infra/s3/client.py b/src/infra/s3/client.py index 36e81758..7b876c2b 100644 --- a/src/infra/s3/client.py +++ b/src/infra/s3/client.py @@ -28,7 +28,7 @@ import time from collections.abc import AsyncIterator from contextlib import AsyncExitStack, asynccontextmanager from dataclasses import dataclass -from typing import Any +from typing import Any, BinaryIO import aiohttp from aiobotocore.config import AioConfig @@ -170,16 +170,23 @@ class ObjectStorage: async def put( self, key: str, - data: bytes, + body: BinaryIO, *, + size: int, content_type: str, ) -> None: - """Записать объект целиком.""" + """Записать объект целиком из потока с `read`, `seek` и `tell`. + + Поток, а не `bytes`: botocore обернул бы `bytes` в `BytesIO` с + общим буфером, и aiohttp при `getbuffer()` скопировал бы тело + целиком (design change `upload-memory`, решение 5). `size` — в + журнал вызова. + """ await self._call( "put_object", key, - size=len(data), - Body=data, + size=size, + Body=body, ContentType=content_type, ) diff --git a/src/infra/upload_slots.py b/src/infra/upload_slots.py new file mode 100644 index 00000000..686b6fb2 --- /dev/null +++ b/src/infra/upload_slots.py @@ -0,0 +1,78 @@ +"""Места загрузок вложений процесса API: допуск к обработке, а не данные. + +Design change `upload-memory`, решения 1–3. Процесс обрабатывает не +больше `[uploads] max_concurrent` загрузок одновременно, ещё не больше +`max_waiting` ждут места по порядку прихода (`asyncio.Semaphore` отдаёт +место первому ожидающему), но не дольше `wait_timeout_seconds`. Очередь +полна или срок вышел — `UploadsBusy` (429). Так память загрузок +ограничена числом мест, а не числом клиентов. + +Состояние в памяти процесса корректности ответов не задевает: как лимит +хэшей паролей (`src/infra/password.py`), это допуск к обработке, и места +считает каждая реплика сама. Глобал `upload_slots` создаётся при импорте +из `settings.uploads`; импортирует его только `src/api/dependencies.py`, +сервис получает его конструктором (`infra.md`). +""" + +import asyncio +import time +from collections.abc import AsyncIterator +from contextlib import asynccontextmanager + +from src.config import settings +from src.core.exceptions import UploadsBusy + + +class UploadSlots: + """Места загрузок процесса и короткая очередь ожидания.""" + + def __init__( + self, + *, + max_concurrent: int, + max_waiting: int, + wait_timeout_seconds: float, + ) -> None: + self.max_concurrent = max_concurrent + self.max_waiting = max_waiting + self.wait_timeout_seconds = wait_timeout_seconds + self._semaphore = asyncio.Semaphore(max_concurrent) + self._waiting = 0 + + @asynccontextmanager + async def slot(self) -> AsyncIterator[int]: + """Занять место на время контекста; отдаёт ожидание места в мс. + + Места нет и ожидающих уже `max_waiting` — сразу `UploadsBusy`. + Иначе ожидание по порядку прихода не дольше срока, не вышло — + `UploadsBusy`. Занятое место освобождается в `finally` при любом + исходе, в том числе при отмене запроса. Отмену во время ожидания + `asyncio.Semaphore` обрабатывает сам: место, отданное отменённому + ожидающему, переходит следующему, и число мест не меняется. + """ + started = time.monotonic() + if self._semaphore.locked(): + if self._waiting >= self.max_waiting: + raise UploadsBusy + self._waiting += 1 + try: + async with asyncio.timeout(self.wait_timeout_seconds): + await self._semaphore.acquire() + except TimeoutError as e: + raise UploadsBusy from e + finally: + self._waiting -= 1 + else: + # место свободно: acquire не уступает цикл событий + await self._semaphore.acquire() + try: + yield round((time.monotonic() - started) * 1000) + finally: + self._semaphore.release() + + +upload_slots = UploadSlots( + max_concurrent=settings.uploads.max_concurrent, + max_waiting=settings.uploads.max_waiting, + wait_timeout_seconds=settings.uploads.wait_timeout_seconds, +) diff --git a/src/main.py b/src/main.py index b5d53d97..6695cbca 100644 --- a/src/main.py +++ b/src/main.py @@ -57,6 +57,10 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]: s3_host=s3.host, s3_port=s3.port, s3_bucket=s3.bucket, + uploads_max_concurrent=settings.uploads.max_concurrent, + uploads_max_waiting=settings.uploads.max_waiting, + uploads_wait_timeout_seconds=settings.uploads.wait_timeout_seconds, + uploads_body_timeout_seconds=settings.uploads.body_timeout_seconds, ) try: yield diff --git a/src/utils/constants.py b/src/utils/constants.py index bd67ce14..c19ae071 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -79,6 +79,11 @@ OBJECT_KEY_MAX_BYTES = 1024 # ключ объекта: `<имя базы>/attachments//original` ATTACHMENT_KEY_PREFIX = "attachments" ATTACHMENT_ORIGINAL_SUFFIX = "original" +# секунды в Retry-After ответа 429, когда места загрузки процесса заняты: +# за секунду реплика доводит несколько загрузок (7–8,5 по 10 MiB), а повтор +# через LB уходит на следующую реплику (design change `upload-memory`, +# решение 2) +UPLOAD_RETRY_AFTER_SECONDS = 1 # пагинация PAGE_LIMIT_MIN = 1 diff --git a/student-tests/conftest.py b/student-tests/conftest.py index 883ffe8a..11001c2b 100644 --- a/student-tests/conftest.py +++ b/student-tests/conftest.py @@ -20,7 +20,13 @@ EXPECT_REPLICAS = int(os.environ.get("EXPECT_REPLICAS", "2")) # hook стенда отказов и «тесный» API задаёт make failure_checks FAULT_HOOK = os.environ.get("FAULT_HOOK", "") FAULT_TIGHT_BASE_URL = os.environ.get("FAULT_TIGHT_BASE_URL", "").rstrip("/") +# «узкий по загрузкам» API стенда отказов (change upload-memory) +FAULT_UPLOADS_BASE_URL = os.environ.get("FAULT_UPLOADS_BASE_URL", "").rstrip( + "/", +) FAULT_HOOK_TIMEOUT_S = 120 +# срок клиента «узкого» API: больше ожидания места, срока тела и шагов +UPLOADS_CLIENT_TIMEOUT_S = 30 @pytest.hookimpl(tryfirst=True) @@ -53,7 +59,9 @@ def pytest_collection_finish(session: pytest.Session) -> None: selected = [ item for item in session.items if item.get_closest_marker("fault") ] - if selected and not (FAULT_HOOK and FAULT_TIGHT_BASE_URL): + if selected and not ( + FAULT_HOOK and FAULT_TIGHT_BASE_URL and FAULT_UPLOADS_BASE_URL + ): pytest.exit( "fault checks need the failure stand and its hook: " "run make failure_checks", @@ -164,3 +172,14 @@ def tight_api() -> Iterator[Api]: пулом из одного соединения.""" with Api(FAULT_TIGHT_BASE_URL) as client: yield client + + +@pytest.fixture(scope="session") +def uploads_api() -> Iterator[Api]: + """API стенда отказов с одним местом загрузки, одной загрузкой в + очереди, ожиданием места 1 с и сроком тела 2 с (`FAULT_UPLOADS_ENV`).""" + with Api( + FAULT_UPLOADS_BASE_URL, + timeout=UPLOADS_CLIENT_TIMEOUT_S, + ) as client: + yield client diff --git a/student-tests/contract.py b/student-tests/contract.py index b8dc6cf2..c7df759d 100644 --- a/student-tests/contract.py +++ b/student-tests/contract.py @@ -44,9 +44,14 @@ ERROR_CODES = { 409: "conflict", 413: "payload_too_large", 415: "unsupported_media_type", + # с change upload-memory: все места загрузки процесса заняты + 429: "rate_limited", 500: "internal_error", 503: "unavailable", } +# Retry-After у 429 — положительное целое число секунд (спек +# api-conventions, «Соответствие статусов и кодов ошибок») +RETRY_AFTER_RE = re.compile(r"^[1-9][0-9]*$") @cache @@ -144,6 +149,12 @@ def assert_error(resp: httpx.Response, status: int) -> dict[str, Any]: resp, "request_id differs from X-Request-Id", ) + if status == 429: + retry_after = resp.headers.get("Retry-After", "") + assert RETRY_AFTER_RE.fullmatch(retry_after), describe( + resp, + f"Retry-After {retry_after!r} is not a positive integer", + ) return error diff --git a/student-tests/images.py b/student-tests/images.py index 51a233c9..96c48599 100644 --- a/student-tests/images.py +++ b/student-tests/images.py @@ -9,6 +9,7 @@ SOF. Большие файлы и «бомбы» живут только в па import functools import io +import random import struct import zlib from pathlib import Path @@ -122,6 +123,18 @@ def png_of_size(size: int) -> bytes: return data +def png_noise(width: int = 1024, height: int = 341, *, seed: int = 0) -> bytes: + """Настоящий RGB PNG из шума: сжимается плохо, поэтому размер файла — + около `width × height × 3` байт (по умолчанию ~1 MiB). Разные `seed` — + разные байты; один `seed` — одни и те же.""" + noise = random.Random(seed) + row_bytes = width * 3 + rows = b"".join( + b"\x00" + noise.randbytes(row_bytes) for _ in range(height) + ) + return png(width, height, color=2, idat=zlib.compress(rows, 1)) + + def png_huge(width: int, height: int) -> bytes: """Несколько килобайт с огромными размерами в IHDR.""" return png( diff --git a/student-tests/run_failures.py b/student-tests/run_failures.py index a2640d2e..5111e9b8 100644 --- a/student-tests/run_failures.py +++ b/student-tests/run_failures.py @@ -7,10 +7,11 @@ S3 со своими volumes, порты хранилищ не публикую - запускает уборщика незавершённых загрузок с grace 20 с и интервалом 1 с (`failures.compose.yml`; design change `upload-consistency`, решение 10) и передаёт оба значения тестам; -- запускает два контейнера API: обычный (с `MAX_UPLOAD_BYTES=1` и - `MAX_IMAGE_PIXELS=1` в окружении — лимиты вложений от них не зависят) и +- запускает три контейнера API: обычный (с `MAX_UPLOAD_BYTES=1` и + `MAX_IMAGE_PIXELS=1` в окружении — лимиты вложений от них не зависят), «тесный» (сроки сессии и ключа идемпотентности 2 с, пул из одного - соединения); + соединения) и «узкий по загрузкам» (одно место загрузки, одна в + очереди, ожидание места 1 с, срок тела 2 с; change `upload-memory`); - прогоняет тесты с маркером `fault` (`pytest -m fault`), передав им hook `student-tests/fault_hook.py`; при падении печатает журналы API и уборщика; @@ -76,6 +77,16 @@ LIMITS_ENV = { "MAX_UPLOAD_BYTES": "1", "MAX_IMAGE_PIXELS": "1", } +# «узкий по загрузкам» API (change upload-memory, design, решение 11): одно +# место загрузки, одна загрузка в очереди, ожидание места 1 с, срок тела +# 2 с. Те же пары тест получает в `FAULT_UPLOADS_ENV` и сверяет, что стенд +# запущен с ними +UPLOADS_ENV = { + "UPLOADS__MAX_CONCURRENT": "1", + "UPLOADS__MAX_WAITING": "1", + "UPLOADS__WAIT_TIMEOUT_SECONDS": "1", + "UPLOADS__BODY_TIMEOUT_SECONDS": "2", +} def say(message: str) -> None: @@ -157,6 +168,11 @@ def cleaner_timings(project: str) -> dict[str, str]: } +def env_pairs(env: dict[str, str]) -> str: + """`KEY=value` через пробел: так окружение API получают тесты.""" + return " ".join(f"{key}={value}" for key, value in env.items()) + + def free_port() -> int: with socket.socket() as sock: sock.bind(("127.0.0.1", 0)) @@ -284,7 +300,8 @@ def main() -> int: return 2 default_name = f"{project}-api" tight_name = f"{project}-api-tight" - containers = [default_name, tight_name] + uploads_name = f"{project}-api-uploads" + containers = [default_name, tight_name, uploads_name] say(f"project={project} (working stand: {working})") if not cleanup(project, containers): @@ -320,17 +337,25 @@ def main() -> int: say("start api containers") base_url = start_api(project, default_name, free_port(), LIMITS_ENV) tight_url = start_api(project, tight_name, free_port(), TIGHT_ENV) - say(f"ready: api={base_url} tight={tight_url}") + uploads_url = start_api( + project, + uploads_name, + free_port(), + UPLOADS_ENV, + ) + say( + f"ready: api={base_url} tight={tight_url} uploads={uploads_url}", + ) env = ( os.environ | { "BASE_URL": base_url, "FAULT_TIGHT_BASE_URL": tight_url, + "FAULT_UPLOADS_BASE_URL": uploads_url, "FAULT_HOOK": str(FAULT_HOOK), "FAULT_PROJECT": project, - "FAULT_LIMITS_ENV": " ".join( - f"{key}={value}" for key, value in LIMITS_ENV.items() - ), + "FAULT_LIMITS_ENV": env_pairs(LIMITS_ENV), + "FAULT_UPLOADS_ENV": env_pairs(UPLOADS_ENV), } | storage_names(project) | timings diff --git a/student-tests/spec_coverage.py b/student-tests/spec_coverage.py index d7ad93d2..96126b2d 100644 --- a/student-tests/spec_coverage.py +++ b/student-tests/spec_coverage.py @@ -129,6 +129,22 @@ EXCLUDED: dict[Scenario, Exclusion] = { "LAB=4 проверка скачивает тот же оригинал прежним токеном — " "evidence/replicas/test-persistence.md", ), + ("attachments", "Одна копия тела при записи в S3"): Exclusion( + reason="нужен пик памяти cgroup реплики под одновременными " + "загрузками и образ кода до change upload-memory, а тесты ходят " + "по HTTP", + check="make bench_uploads (профиль uploads стенда bench/): " + "варианты «до» и «без лимита» при 10 клиентах по 10 MiB, пик окна " + "над памятью до загрузок в телах на загрузку — " + "evidence/uploads/baseline/summary.md", + ), + ("attachments", "Память не растёт с числом загрузок"): Exclusion( + reason="нужен пик памяти cgroup реплики, реплика без swap и " + "завершение ядром из-за памяти, а тесты ходят по HTTP", + check="make bench_uploads: вариант «с лимитом» при 10, 20 и 40 " + "клиентах по 10 MiB — пик окна, oom, ответы по кодам — " + "evidence/uploads/baseline/summary.md", + ), ("users", "Хэш в БД"): Exclusion( reason="нужен доступ к таблице users, а тесты ходят по HTTP", check="driver.py --port auth-storage: префикс $argon2id$ и " diff --git a/student-tests/test_attachments.py b/student-tests/test_attachments.py index 0b0c6c43..2943c3ef 100644 --- a/student-tests/test_attachments.py +++ b/student-tests/test_attachments.py @@ -7,9 +7,12 @@ """ import hashlib +import threading +import time import urllib.parse import uuid from collections.abc import Iterator +from concurrent.futures import ThreadPoolExecutor from typing import Any import pytest @@ -32,6 +35,10 @@ from contract import ( BIG_BYTES = 30 * 1024 * 1024 # сколько скачиваний ждать ответа другой реплики (round-robin LB) REPLICA_ATTEMPTS = 20 +# одновременные загрузки сценария «Загрузки в пределах лимита» +CONCURRENT_UPLOADS = 10 +# срок клиента загрузки: больше ожидания места (5 с) и сроков шагов +CONCURRENT_CLIENT_TIMEOUT_S = 30 def chunks(data: bytes, size: int = 1024 * 1024) -> Iterator[bytes]: @@ -645,6 +652,52 @@ def test_repeated_upload( ) +@pytest.mark.spec("attachments", "Загрузки в пределах лимита") +def test_concurrent_uploads(api: Api, base_url: str) -> None: + """10 участников одного чата загружают по PNG ~1 MiB одновременно: при + параметрах загрузок по умолчанию (4 места и 16 в очереди на процесс) + все помещаются даже в один процесс (design change `upload-memory`, + решение 11).""" + actors = [ + api.register(display_name=f"Uploader {number}") + for number in range(CONCURRENT_UPLOADS) + ] + chat = api.create_chat(actors[0], *actors[1:], title="Uploads") + bodies = [ + images.png_noise(seed=number) for number in range(CONCURRENT_UPLOADS) + ] + barrier = threading.Barrier(CONCURRENT_UPLOADS) + + def upload(number: int) -> tuple[dict[str, Any], float, float]: + with Api(base_url, timeout=CONCURRENT_CLIENT_TIMEOUT_S) as own: + # соединение открыто до барьера: после него сразу загрузка + own.request("GET", "/health/live") + barrier.wait() + started = time.monotonic() + attachment = own.upload( + actors[number], + chat["id"], + bodies[number], + filename=f"noise-{number}.png", + ) + return attachment, started, time.monotonic() + + with ThreadPoolExecutor(max_workers=CONCURRENT_UPLOADS) as pool: + results = list(pool.map(upload, range(CONCURRENT_UPLOADS))) + attachments = [attachment for attachment, _, _ in results] + assert len({item["id"] for item in attachments}) == CONCURRENT_UPLOADS + # загрузки правда шли одновременно, а не по очереди клиента + spans = sorted((started, ended) for _, started, ended in results) + overlapping = sum(started < spans[0][1] for started, _ in spans) + assert overlapping >= 2, f"uploads did not overlap: {spans}" + for number, attachment in enumerate(attachments): + assert_content( + api.attachment_content(actors[0], attachment["id"]), + bodies[number], + "image/png", + ) + + @pytest.mark.spec("attachments", "Скачивание через другую реплику") def test_download_through_other_replica( api: Api, diff --git a/student-tests/test_failures.py b/student-tests/test_failures.py index 9d89fa9f..943c793e 100644 --- a/student-tests/test_failures.py +++ b/student-tests/test_failures.py @@ -3,14 +3,17 @@ Стенд и hook готовит `student-tests/run_failures.py`: свои Postgres, Valkey и S3, уборщик незавершённых загрузок (grace и интервал — `FAULT_CLEANER_GRACE_S`, `FAULT_CLEANER_INTERVAL_S`), обычный API -(`BASE_URL`, с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1` в окружении) и +(`BASE_URL`, с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1` в окружении), «тесный» (сроки сессии и ключа идемпотентности 2 с, пул из одного -соединения). На хранилища и API тесты действуют только через фикстуру +соединения) и «узкий по загрузкам» (`FAULT_UPLOADS_BASE_URL`: одно место +загрузки, одна в очереди, ожидание 1 с, срок тела 2 с — change +`upload-memory`). На хранилища и API тесты действуют только через фикстуру `stand` (hook `student-tests/fault_hook.py`) и всегда возвращают их в рабочее состояние. Решение 4 design change `failure-checks`, решение 10 design change `upload-consistency`. """ +import hashlib import os import statistics import threading @@ -1130,3 +1133,348 @@ def test_object_storage_paused( (pending,) = new_ids(before, attachment_rows(stand)) wait_cleaned(stand, pending, since=started) assert not orphan_objects(stand) + + +# --------------------------------------------------------------------------- +# Места загрузки и срок тела (change upload-memory, design, решение 11): +# «узкий по загрузкам» API — одно место, одна загрузка в очереди, ожидание +# места и срок тела из FAULT_UPLOADS_ENV (run_failures.py, UPLOADS_ENV). +# Место держит загрузка, тело которой стоит на threading.Event теста +# --------------------------------------------------------------------------- + +UPLOADS_ENV = dict( + item.split("=", 1) + for item in os.environ.get("FAULT_UPLOADS_ENV", "").split() +) +# окружение, с которым тесты ниже ждут «узкий» API +EXPECTED_UPLOADS_ENV = { + "UPLOADS__MAX_CONCURRENT": "1", + "UPLOADS__MAX_WAITING": "1", + "UPLOADS__WAIT_TIMEOUT_SECONDS": "1", + "UPLOADS__BODY_TIMEOUT_SECONDS": "2", +} +WAIT_TIMEOUT_S = float(UPLOADS_ENV.get("UPLOADS__WAIT_TIMEOUT_SECONDS", "1")) +BODY_TIMEOUT_S = float(UPLOADS_ENV.get("UPLOADS__BODY_TIMEOUT_SECONDS", "2")) +# отказ без ожидания места: вход, членство и ответ +IMMEDIATE_S = 0.5 +# пауза, за которую запрос в соседнем потоке доходит до места или очереди +SETTLE_S = 0.2 +# сколько держатель места ждёт отпускания, если тест упал раньше +HOLD_MAX_S = 10 + + +def assert_uploads_stand() -> None: + """Без этого окружения «узкого» API тесты мест ничего не доказывают.""" + assert UPLOADS_ENV == EXPECTED_UPLOADS_ENV, ( + f"uploads stand started with {UPLOADS_ENV}, " + f"expected {EXPECTED_UPLOADS_ENV}" + ) + + +class Upload: + """Загрузка в своём потоке и своём соединении; ответ — `result()`.""" + + def __init__(self, api: Api, actor: Actor, chat: dict[str, Any]) -> None: + self._base_url = str(api.client.base_url) + self._actor = actor + self._chat = chat + self._outcome: dict[str, Any] = {} + self._thread: threading.Thread | None = None + + def start(self, data: Any, **kwargs: Any) -> "Upload": + def run() -> None: + with Api(self._base_url, timeout=THREAD_CLIENT_TIMEOUT_S) as own: + started = time.monotonic() + try: + self._outcome["resp"] = upload_raw( + own, + self._actor, + self._chat, + data, + **kwargs, + ) + except (BodyAborted, httpx.TransportError) as e: + self._outcome["error"] = e + self._outcome["elapsed"] = time.monotonic() - started + self._outcome["ended"] = time.monotonic() + + self._thread = threading.Thread(target=run) + self._thread.start() + return self + + def result(self) -> tuple[httpx.Response, float, float]: + """Ответ, длительность и момент ответа (`time.monotonic`).""" + assert self._thread is not None + self._thread.join(THREAD_CLIENT_TIMEOUT_S) + assert not self._thread.is_alive(), "upload thread hangs" + assert "resp" in self._outcome, self._outcome + return ( + self._outcome["resp"], + self._outcome["elapsed"], + self._outcome["ended"], + ) + + +@contextmanager +def held_slot( + api: Api, + actor: Actor, + chat: dict[str, Any], + data: bytes, +) -> Iterator[Callable[[], httpx.Response]]: + """Загрузка A держит место: отдаёт половину тела и ждёт отпускания. + + Внутри — после того, как A заняла место; вызов отдаваемой функции + отпускает A и возвращает её ответ. В `finally` A отпускается всегда. + """ + sent = threading.Event() + release = threading.Event() + + def body() -> Iterator[bytes]: + yield data[: len(data) // 2] + sent.set() + if not release.wait(HOLD_MAX_S): + raise BodyAborted + yield data[len(data) // 2 :] + + holder = Upload(api, actor, chat).start(body()) + try: + assert sent.wait(HOLD_MAX_S), "holder did not start its body" + # вход и членство — короткие шаги БД, затем место + time.sleep(SETTLE_S) + + def finish() -> httpx.Response: + release.set() + return holder.result()[0] + + yield finish + finally: + release.set() + + +def slow_chunks(data: bytes, *, parts: int, seconds: float) -> Iterator[bytes]: + """Тело `parts` частями, растянутое на `seconds`.""" + size = -(-len(data) // parts) + for offset in range(0, len(data), size): + if offset: + time.sleep(seconds / (parts - 1)) + yield data[offset : offset + size] + + +def objects_and_rows(stand: Stand) -> tuple[dict[str, str], set[str]]: + return attachment_rows(stand), stored_ids(stand) + + +@pytest.mark.spec("attachments", "Все места заняты") +@pytest.mark.spec("attachments", "Очередь ожидания полна") +@pytest.mark.spec("api-conventions", "Лимит одновременных загрузок") +def test_upload_slots_busy( + uploads_api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + assert_uploads_stand() + data = images.sample_png() + before = objects_and_rows(stand) + with held_slot(uploads_api, alice, chat, data) as finish_holder: + # B ждёт место в очереди, C застаёт полную очередь + waiting = Upload(uploads_api, alice, chat).start(data) + time.sleep(SETTLE_S) + busy, busy_s = timed( + lambda: upload_raw(uploads_api, alice, chat, data), + ) + waited, waited_s, _ = waiting.result() + # A отпускается сразу: её тело ограничено сроком тела стенда + holder = finish_holder() + assert_error(busy, 429) + assert busy_s < IMMEDIATE_S, f"429 of a full queue after {busy_s:.2f}s" + assert_error(waited, 429) + assert waited_s >= WAIT_TIMEOUT_S, f"429 after {waited_s:.2f}s" + for resp in (busy, waited): + assert int(resp.headers["Retry-After"]) >= 1 + attachment = assert_ok(holder, 201, "Attachment") + # из трёх загрузок осталась только принятая: у 429 ни строки, ни объекта + rows, stored = objects_and_rows(stand) + assert new_ids(before[0], rows) == {attachment["id"]} + assert stored - before[1] == {attachment["id"]} + + +@pytest.mark.spec("attachments", "Отказ раньше очереди") +def test_rejections_before_queue( + uploads_api: Api, + alice: Actor, + eve: Actor, + chat: dict[str, Any], +) -> None: + assert_uploads_stand() + data = images.sample_png() + # 30 MiB, которые начинаются как PNG: Content-Length 31 457 280 + big = images.PNG_SIGNATURE + bytes( + 3 * images.MAX_BYTES - len(images.PNG_SIGNATURE), + ) + with held_slot(uploads_api, alice, chat, data) as finish_holder: + waiting = Upload(uploads_api, alice, chat).start(data) + time.sleep(SETTLE_S) + early = [ + (status, *timed(call)) + for status, call in ( + (404, lambda: upload_raw(uploads_api, eve, chat, data)), + (413, lambda: upload_raw(uploads_api, alice, chat, big)), + ( + 415, + lambda: upload_raw( + uploads_api, + alice, + chat, + data, + content_type="text/plain", + ), + ), + ) + ] + early_done = time.monotonic() + waited, _, waited_at = waiting.result() + holder = finish_holder() + # очередь была полна всё время ранних отказов + assert_error(waited, 429) + assert early_done < waited_at + for status, resp, elapsed in early: + assert_error(resp, status) + # без ожидания места: ожидающий получил бы его не раньше срока + assert elapsed < WAIT_TIMEOUT_S, f"{status} after {elapsed:.2f}s" + assert early[1][1].request.headers["Content-Length"] == "31457280" + assert_ok(holder, 201, "Attachment") + + +@pytest.mark.spec("attachments", "Ожидание места") +@pytest.mark.spec( + "storage-consistency", + "Ожидание места не входит в возраст загрузки", +) +def test_upload_waits_for_slot( + uploads_api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + assert_uploads_stand() + first = images.sample_png() + second = images.png(80, 60) + with held_slot(uploads_api, alice, chat, first) as finish_holder: + waiting = Upload(uploads_api, bob, chat).start(second) + time.sleep(SETTLE_S) + # A заканчивается раньше срока ожидания B + holder = finish_holder() + held = assert_ok(holder, 201, "Attachment") + waited_resp, waited_s, _ = waiting.result() + waited = assert_ok(waited_resp, 201, "Attachment") + assert waited_s < WAIT_TIMEOUT_S + BODY_TIMEOUT_S, waited_s + # метаданные ожидавшей записаны после перевода в ready державшей место: + # ожидание прошло до строки pending (граница B уборщика прежняя) + assert waited["created_at"] > held["updated_at"], (held, waited) + for attachment, data in ((held, first), (waited, second)): + assert_content( + uploads_api.attachment_content(alice, attachment["id"]), + data, + "image/png", + ) + + +@pytest.mark.spec("attachments", "Место освобождается") +def test_slot_released_after_failures( + uploads_api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + assert_uploads_stand() + over = images.png_of_size(images.MAX_BYTES + 1) + + def aborted_body() -> Iterator[bytes]: + yield images.PNG_SIGNATURE + bytes(1024 * 1024) + raise BodyAborted + + def next_upload_gets_slot(after: str) -> None: + resp, elapsed = timed( + lambda: upload_raw(uploads_api, alice, chat, images.sample_png()), + ) + assert_ok(resp, 201, "Attachment") + assert elapsed < WAIT_TIMEOUT_S, ( + f"upload after {after} waited {elapsed:.2f}s for a slot" + ) + + assert_error( + upload_raw( + uploads_api, + alice, + chat, + slow_chunks(over, parts=10, seconds=0), + ), + 413, + ) + next_upload_gets_slot("413 by counter") + assert_error(upload_raw(uploads_api, alice, chat, b"not an image"), 415) + next_upload_gets_slot("415 by content") + slow = slow_chunks( + images.sample_png(), + parts=4, + seconds=BODY_TIMEOUT_S + 1, + ) + assert_error(upload_raw(uploads_api, alice, chat, slow), 400) + next_upload_gets_slot("400 by body timeout") + with ( + Api( + str(uploads_api.client.base_url), + timeout=THREAD_CLIENT_TIMEOUT_S, + ) as own, + pytest.raises((BodyAborted, httpx.TransportError)), + ): + upload_raw(own, alice, chat, aborted_body()) + # API замечает обрыв не мгновенно + time.sleep(SETTLE_S) + next_upload_gets_slot("interrupted body") + with outage(stand, "stop", "s3"): + assert_error( + upload_raw(uploads_api, alice, chat, images.sample_png()), + 503, + ) + next_upload_gets_slot("503 with S3 stopped") + + +@pytest.mark.spec("attachments", "Медленный клиент") +@pytest.mark.spec("attachments", "Медленная передача в срок") +def test_slow_body( + uploads_api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + assert_uploads_stand() + data = images.sample_png() + before = objects_and_rows(stand) + late = upload_raw( + uploads_api, + alice, + chat, + slow_chunks(data, parts=6, seconds=BODY_TIMEOUT_S + 1), + ) + error = assert_error(late, 400) + assert error["message"] == "Upload body was not received in time" + rows, stored = objects_and_rows(stand) + assert not new_ids(before[0], rows) + assert not stored - before[1] + # мелкие части с паузами, но в срок: тело принято как есть + in_time = slow_chunks(data, parts=20, seconds=BODY_TIMEOUT_S / 2) + resp, elapsed = timed( + lambda: upload_raw(uploads_api, alice, chat, in_time), + ) + attachment = assert_ok(resp, 201, "Attachment") + assert elapsed < WAIT_TIMEOUT_S + BODY_TIMEOUT_S, elapsed + assert attachment["size_bytes"] == len(data) + assert attachment["sha256"] == hashlib.sha256(data).hexdigest() + assert_content( + uploads_api.attachment_content(alice, attachment["id"]), + data, + "image/png", + )