feat: bound upload memory with per-replica slots and a body deadline

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-22 00:23:37 +03:00
co-authored by Claude Opus 5.5
parent fc1524d0d6
commit 6cab9d3c41
55 changed files with 4133 additions and 209 deletions
+22 -5
View File
@@ -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`). Ровно
лимит проходит.
+42 -2
View File
@@ -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 реплик на новом образе, все
+74
View File
@@ -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/<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): старт стенда перечисл
`<NOSRV>` (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`, — как на рабочем стенде.
+10
View File
@@ -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` рядом с
+23 -1
View File
@@ -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 с);
+11 -5
View File
@@ -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
+5 -1
View File
@@ -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)
+27 -9
View File
@@ -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()` и только при
+29 -1
View File
@@ -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`,
+46 -5
View File
@@ -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` после каждого прогона и ненулевой код при признаках
@@ -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/<id>/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)
@@ -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,
+2
View File
@@ -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 на пробных метках
+49 -23
View File
@@ -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 <LB> attachment-failover [--mode stop\|kill]` | вложение через LB, `stop-one.sh` принявшей реплики, скачивание через другую (тот же SHA-256), 404 постороннему, затем `make replicas`; доказательство исключения `attachments` «Принявшая реплика остановлена» |
| `driver.py --port <LB> attachment-storage` | схема таблиц вложений, вид `object_key`, объект в bucket, анонимный GET — 403, `docker diff` реплик; доказательство исключения «Байты не в БД и не на диске API» |
| `driver.py --port <LB> 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/<PLOTS>/` |
| `make bench_ab BEFORE=... AFTER=... REAPPLY=<commit> [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/<domain>.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/<domain>.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/<domain>.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/<id>/original, put, open, delete_original
repos/attachment_object.py # оригинал в S3: ключ <база>/attachments/<id>/original, put_original (поток BytesIO и size, без копии тела), open, delete_original
repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой
services/<domain>.py # <Domain>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/<domain>.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва, 500 пропавшего объекта
exceptions/<domain>.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/<domain>.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_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
test_failures.py # проверки отказов (маркер fault): только make failure_checks
run_isolated.py # make test_isolated: образ на временной базе test_<db>, уборка базы и префикса test_<db>/ в 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, потом править код. Обновить этот файл: номер лабы,
таблицу важных файлов, новые правила.
+23
View File
@@ -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`, «Ошибки
балансировщика в формате контракта»).
+18
View File
@@ -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 —
+36
View File
@@ -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`.
+12 -3
View File
@@ -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, и тоже не запускается: старт стенда
+2 -2
View File
@@ -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
+102
View File
@@ -0,0 +1,102 @@
// Профиль загрузок (design change upload-memory, решение 10): CLIENTS VU
// загружают одно и то же тело PNG без пауз (constant-vus) через LB, пока
// оркестратор меряет память реплики. На 429 VU ждёт Retry-After, на прочие
// ошибки — секунду. Каждая загрузка — строка «up,<vu>,<итерация>,
// <отправка мс>,<длительность мс>,<статус>,<X-Instance-Id>» в файл консоли
// 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);
}
+565 -32
View File
@@ -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 <commit> 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:
+94
View File
@@ -23,6 +23,17 @@
# `cg <нс> - <id12> …` на каждый; роли назначает оркестратор. Строки
# 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 <нс> <роль> <id12> <memory.current> <anon> <sock> <oom_kill>`
# (`anon`, `sock` — memory.stat, `oom_kill` — memory.events) или
# `pk <нс> <роль> <id12> 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() {
+974
View File
@@ -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<t0>\d+)")
UPLOAD_RE = re.compile(
r"\bup,(?P<vu>\d+),(?P<iteration>\d+),(?P<start>\d+),"
r"(?P<duration>\d+),(?P<status>\d+),(?P<instance>[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,<vu>,<итерация>,
<отправка>,<длительность>,<статус>,<X-Instance-Id>` на каждую
загрузку. Строки консоли 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 <нс> <роль> <id12> <current> <anon> <sock> <oom_kill>` или
`pk <нс> <роль> <id12> 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)
+14
View File
@@ -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__*.
+8
View File
@@ -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:
+48
View File
@@ -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.
+26 -2
View File
@@ -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 держит
+88
View File
@@ -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-<tag>` в `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`.
+147 -32
View File
@@ -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 метки.
Проверка:
+13 -2
View File
@@ -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, когда тело не
+125 -5
View File
@@ -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` совпадают с файлом
+82 -9
View File
@@ -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 не завершены из-за памяти
+136 -14
View File
@@ -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** у каждой гипотезы есть вывод со ссылкой на ячейки сводки
метки, а числа совпадают со сводкой
@@ -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** сервис не стартует, в журнале — ошибка проверки настроек с
именем поля
+12 -1
View File
@@ -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 удалять метаданные незавершённой загрузки, пока
+11 -4
View File
@@ -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-
+6 -3
View File
@@ -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}"
+4 -1
View File
@@ -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,
)
+17 -2
View File
@@ -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,
)
+21
View File
@@ -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
+4
View File
@@ -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",
]
+13
View File
@@ -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 или его размер другой.
+5 -2
View File
@@ -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:
+99 -27
View File
@@ -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,
+12 -5
View File
@@ -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,
)
+78
View File
@@ -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,
)
+4
View File
@@ -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
+5
View File
@@ -79,6 +79,11 @@ OBJECT_KEY_MAX_BYTES = 1024
# ключ объекта: `<имя базы>/attachments/<id>/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
+20 -1
View File
@@ -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
+11
View File
@@ -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
+13
View File
@@ -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(
+33 -8
View File
@@ -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
+16
View File
@@ -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 <LB> auth-storage: префикс $argon2id$ и "
+53
View File
@@ -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,
+350 -2
View File
@@ -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",
)