From fc1524d0d6c274075fe9c268ad2976e54cd723cd Mon Sep 17 00:00:00 2001 From: roman Date: Wed, 21 Oct 2026 23:21:42 +0300 Subject: [PATCH] docs: propose upload-memory Co-Authored-By: Claude Opus 5.5 --- PLAN.md | 94 +++ openspec/changes/upload-memory/.openspec.yaml | 2 + openspec/changes/upload-memory/design.md | 689 ++++++++++++++++++ openspec/changes/upload-memory/proposal.md | 124 ++++ .../specs/api-conventions/spec.md | 37 + .../upload-memory/specs/attachments/spec.md | 182 +++++ .../specs/load-balancing/spec.md | 124 ++++ .../specs/load-benchmark/spec.md | 212 ++++++ .../specs/service-configuration/spec.md | 49 ++ .../specs/storage-consistency/spec.md | 74 ++ .../upload-memory/specs/student-tests/spec.md | 85 +++ openspec/changes/upload-memory/tasks.md | 313 ++++++++ 12 files changed, 1985 insertions(+) create mode 100644 openspec/changes/upload-memory/.openspec.yaml create mode 100644 openspec/changes/upload-memory/design.md create mode 100644 openspec/changes/upload-memory/proposal.md create mode 100644 openspec/changes/upload-memory/specs/api-conventions/spec.md create mode 100644 openspec/changes/upload-memory/specs/attachments/spec.md create mode 100644 openspec/changes/upload-memory/specs/load-balancing/spec.md create mode 100644 openspec/changes/upload-memory/specs/load-benchmark/spec.md create mode 100644 openspec/changes/upload-memory/specs/service-configuration/spec.md create mode 100644 openspec/changes/upload-memory/specs/storage-consistency/spec.md create mode 100644 openspec/changes/upload-memory/specs/student-tests/spec.md create mode 100644 openspec/changes/upload-memory/tasks.md diff --git a/PLAN.md b/PLAN.md index eb1cab4e..a35386ec 100644 --- a/PLAN.md +++ b/PLAN.md @@ -943,3 +943,97 @@ design, «Уточнения apply», п. 16–20; tasks, группа 11): Правило `settings.md` и сценарии `make env_setup` обновляет apply. **Сделано в apply** (решение 12 выше): рабочий `.env` получил две строки `S3_CLEANER_*` этой командой. + +### upload-memory + +#### Решения + +Приняты 2026-10-21 в `/opsx:propose`, подробности — design change +`upload-memory`. Пробы — design, Context: проект compose `umprobe`, +реплика 1 CPU / 512 МБ, прототип в копии дерева в scratchpad. + +1. **Проба опровергла «~1,2 тела» из `REPORT.md`** (Context, п. 1–5): + - при PUT aiohttp копирует тело (`getbuffer()` у `BytesIO`, общего с + `bytes`). Пик загрузки — около двух тел, и спек `attachments` + («Лимит размера до чтения тела») сейчас нарушен; + - код `f894040` без swap при 20 одновременных загрузках по 10 MiB — + OOM-kill. Со swap рабочего стенда при 30 — 512 MiB и ещё 267 MiB в + swap; + - ожидание до чтения тела само память не бережёт: ядро копит + недочитанное тело в буфере сокета, до 32 MiB на соединение; + - LB даёт 502/504, если реплика молчит дольше 10 с до тела или после + него, а клиенту, замолчавшему посреди тела, отвечает 400 в HTML. +2. **Места загрузки — на процесс API** (решение 1): 4 места, очередь до + 16, ожидание до 5 с по порядку прихода. Отвергнуты очередь в LB + (второй набор слотов ломал бы замену реплик и профили лабы 3), + `--limit-concurrency` uvicorn, места по байтам и общий счётчик в + Valkey или PostgreSQL. +3. **Ответ при занятых местах — 429 `rate_limited`, `Retry-After: 1`** + (решение 2) — до ответа на вопрос 1 ниже. Очередь, а не сразу 429: + сообщение несёт до 10 вложений, и 10–20 одновременных загрузок по + 10 MiB на пробе проходят все. +4. **Место — после проверок 401/400/404/415/413 и до тела, держится до + ответа** (решение 3). Граница уборщика B = 17 с не меняется: + ожидание, тело и проверка — до `created_at`, сроки tx1, PUT и tx2 + прежние. Проверка grace и стенд отказов (20 с) остаются. Свойство + закреплено сценарием `storage-consistency` и тестом: `created_at` + ожидавшей позже `updated_at` той, что держала место. +5. **Срок тела — 30 с с момента, как загрузка заняла место, иначе 400 + `invalid_request`** (решение 4), по образцу обрыва тела. 408 в + контракте ручки нет. Срок простоя между блоками отвергнут: клиент по + байту раз в 29 с держал бы место вечно. +6. **В PUT уходит тот же `BytesIO`** (решение 5): после проверки ссылка + на `bytes` удаляется, буфер снова не общий. Проба — 1,19 тела вместо + 2,0–2,3, SHA-256 объекта совпал. +7. **Буферы ядра** (решение 6): у `api` — `net.ipv4.tcp_rmem` до 512 KiB + (`sysctls` в compose), у LB — `tune.sndbuf.server 262144`. При 40 + загрузках `sock` реплики — 17 MiB вместо 134, пик LB — 51 MiB вместо + 109. Скорость загрузки одного клиента та же. +8. **Цепочка таймаутов пути загрузки** (решение 7): + - `timeout server` LB для `POST …/attachments` — 30 с: молчание до + тела ≤ 17 с, после ≈ 26 с; остальные пути — прежние 10 с; + - ответ LB 400 — в формате контракта; + - `ROLLOUT_DRAIN_TIMEOUT` — 90 с, больше наибольшей длительности + загрузки ~73 с; + - 408 на медленные заголовки остаётся HTML: `http-error` его не + меняет, запись в `KNOWN_ISSUES.md`. +9. **S3 без изменений** (решение 8): лимит загрузок шлюза 64 МБ, + `GOMEMLIMIT`, 512 МБ и общий срок вызова 5 с. При 12 одновременных + PUT (три реплики × 4 места) p95 — 1,6–1,9 с. Отдельный срок PUT не + нужен — это закрывает открытый вопрос design `attachments`. +10. **Профиль `uploads`** (решение 10): одна реплика без swap, S3 рабочего + стенда. Варианты: «до» (образ `f894040`), «без лимита» и «с + лимитом». Тела 1 и 10 MiB, 1 / 10 / 20 / 40 клиентов, 3 повтора, + новые S3 и реплика на прогон. Пик окна — `memory.peak` со сбросом + через свой дескриптор: пик старта (фиктивный хэш, 152 MiB) его иначе + перекрывает. Гипотезы H1–H4 — в design, в `REPORT.md` — отдельным + commit до прогонов. +11. **Тесты** (решение 11): в `make student_test` — 10 одновременных + загрузок. В `make failure_checks` — третий API с 1 местом, 1 в + очереди, ожиданием 1 с и сроком тела 2 с, пять тестов. Сценарии + памяти — исключения сверки со ссылкой на метку профиля. +12. **Драйвер `lb-upload-timeouts`** (решение 7): сроки LB на заглушке за + `haproxy.cfg` проекта. Evidence — `evidence/uploads/lb-timeouts.md`. + +#### Вопросы + +1. Какой код отдавать, когда все места загрузки реплики заняты и + очередь полна или ожидание истекло: 429 `rate_limited` или 503 + `unavailable`? Контракт (`contracts/openapi.json`, ручка + `uploadAttachment`) допускает оба: + - 429 описан как «Ограничение частоты запросов», у него одного есть + заголовок `Retry-After`; + - 503 описан как «Зависимость недоступна». + + `contracts/README.md` разрешает факультативное ограничение запросов + кодом `429 rate_limited`. Места загрузки ограничивают одновременность, + а не частоту, и это расхождение формулировки. Поэтому трактовку + выбирает преподаватель. + - По умолчанию до ответа — 429 с `Retry-After: 1`. Причины: из двух + описаний контракта к ограничению подходит только 429, а «зависимость + недоступна» неверно. Кроме того, клиент и профиль `uploads` отличат + занятые места от отказа S3, который тоже 503. + - Ответ «503» меняет строку таблицы `src/api/errors.py` (заголовок + `Retry-After` остаётся), сценарии `attachments` и + `api-conventions`, ожидания тестов и `REPORT.md`. Остальной design + и задачи не меняются (design, решение 2). diff --git a/openspec/changes/upload-memory/.openspec.yaml b/openspec/changes/upload-memory/.openspec.yaml new file mode 100644 index 00000000..dc36fb1b --- /dev/null +++ b/openspec/changes/upload-memory/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-21 diff --git a/openspec/changes/upload-memory/design.md b/openspec/changes/upload-memory/design.md new file mode 100644 index 00000000..b217681c --- /dev/null +++ b/openspec/changes/upload-memory/design.md @@ -0,0 +1,689 @@ +# Design + +## Context + +Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. + +Код — состояние после `upload-consistency` (`f894040`): +- `AttachmentService.upload` (`src/core/services/attachment.py`): вход + коротким шагом БД → членство (404) → `Content-Type` (415) → + `Content-Length` (413) → тело в `io.BytesIO` со счётчиком → + `getvalue()` (`bytes` без копии) → структура и SHA-256 в потоке → + строка `pending` (tx1) → PUT (`bytes`) → `ready` (tx2) → 201. + Лимита одновременных загрузок нет, срока чтения тела нет; +- клиент S3 — aiobotocore 3.9.2 / botocore 1.43.106 / aiohttp 3.14.5, + `[s3] timeout_seconds` 5 с на вызов, пул 10 соединений; +- реплика — 1 CPU / 512 МБ, `memswap_limit` не задан (Docker даёт swap + 2 × лимит); хэши паролей — до `kdf_concurrency` 4 × 64 MiB; +- HAProxy: `timeout server` 10 с, `timeout client` 30 с, `timeout + http-request` 10 с, `http-reuse never`; `ROLLOUT_DRAIN_TIMEOUT` 12 с + («больше `timeout server`»); +- SeaweedFS: 1 CPU / 512 МБ, `GOMEMLIMIT=400MiB`, + `-s3.concurrentUploadLimitMB=64`; +- граница живой загрузки уборщика B = 2 × 6 + 5 = 17 с, проверка — в + `src/cleaner/main.py` (`live_upload_bound_seconds`). + +### Что найдено до решений + +1. **При PUT тело копируется ещё раз.** botocore превращает `bytes` в + `BytesIO(bytes)` с общим буфером (`convert_body_to_file_like_object`). + `BytesIOPayload` aiohttp берёт его размер через `getbuffer()` + (`aiohttp/payload.py`, строка 850), и CPython копирует общий буфер + целиком. Снимок `tracemalloc` во время записи тела: 9,99 MiB одним + блоком с этим стеком. Проверка `attachments` («Уточнения apply», + п. 10) моделировала только botocore и копии не видела. Поэтому + «~1,2 тела» в `REPORT.md` неверно: на шаге PUT — два тела, а спек + `attachments` («Лимит размера до чтения тела») сейчас нарушен. +2. **Ожидание до чтения тела память само не бережёт.** uvicorn + (httptools) перестаёт читать сокет после 64 KiB, но ядро принимает + дальше — до буфера приёма сокета. У ВМ Docker Desktop + `net.ipv4.tcp_rmem` = `4096 131072 33554432`, то есть до 32 MiB на + соединение, и эта память (`sock` в `memory.stat`) считается памятью + контейнера. С той же стороны LB копит недоставленное в буфере + отправки к реплике: `tcp_wmem` до 4 MiB. +3. **Срок LB на пути загрузки — 10 с на молчание с обеих сторон тела.** + Реплика, которая не читает тело дольше 10 с (ожидание места, медленная + БД), даёт клиенту 502 от LB. Реплика, которая молчит после тела + дольше 10 с, даёт 504 (пробы ниже). +4. **Клиент, замолчавший посреди тела, получает от LB 400 в HTML**, а не + в формате контракта. Ответ 408 на медленные заголовки — тоже HTML, и + `http-error status 408` его не меняет: такой ответ HAProxy строит до + потока запроса. +5. **Пик cgroup с момента старта бесполезен для окна.** При старте + реплика считает фиктивный хэш пароля (lifespan): пик 152 MiB при + рабочих 102 MiB. Это выше пика окна с лимитом при телах по 1 MiB + (140 MiB). Сброс + `memory.peak` записью в свой дескриптор (ядро ≥ 6.12) работает в ВМ: + ядро 7.0.14, контейнер `--user 0 --cgroupns host` с cgroupfs на + запись, без `--privileged`. + +### Пробы (2026-10-21, scratchpad, проект compose `umprobe`) + +Стенд пробы — тот же `docker-compose.yml` под проектом `umprobe` со своим +env-файлом, без портов хоста: +- одна реплика 1 CPU / 512 МБ на образе `git archive f894040`, прототип — + копия этого дерева с местами загрузок, буфером в PUT и сроком тела; +- PostgreSQL, Valkey, S3 с bootstrap, HAProxy с конфигурацией проекта. + +Нагрузка — httpx из образа API в сети стенда через LB: C клиентов +одновременно, у каждого 2–5 загрузок подряд. Тело — настоящий PNG из +шума: 10 482 183 байта (1024 × 3409 RGB) или около 1 MiB. Память — +сэмплер в контейнере с `--cgroupns host`: +- пик cgroup реплики, сброшенный в начале серии через свой дескриптор; +- `memory.current` раз в 20 мс; +- `anon` и `sock` из `memory.stat`; +- `oom_kill` из `memory.events`. + +ВМ Docker — 12 CPU / 7,75 ГиБ, swap 1 ГиБ, Docker 29.9.1. Созданные +volumes `umprobe_postgres_data`, `umprobe_s3_data`, сеть `umprobe-hap` и +образы `mtusi-messenger:umprobe`, `mtusi-messenger:umprobe-lim` удалены +после проб. + +**Память реплики, 10 MiB.** Колонка «реплика» — пик cgroup, через «/» — +наибольшие `anon` и `sock`. База — 98–110 MiB. + +| Код | swap | C | реплика, MiB | ответы | +|---|---|---|---|---| +| `f894040` | есть | 1 | 126 / 119 / 4 | 3 × 201 | +| `f894040` | есть | 10 | 316 / 302 / 9 | 20 × 201, p95 2,0 с | +| `f894040` | есть | 20 | 512 (лимит) / 504 / 46 | 40 × 201, p95 3,2 с | +| `f894040` | есть | 30 | 512 + swap 267 / 507 / 85 | 60 × 201, p95 5,5 с | +| `f894040` | нет | 20 | OOM-kill (exit 137) | 20 × 502, 13 × 503, 7 обрывов | +| буфер в PUT, мест 1000 | есть | 10 | 229 / 203 / 12 | 20 × 201 | +| буфер в PUT, мест 1000 | есть | 20 | 335 / 306 / 53 | 40 × 201 | +| буфер в PUT, мест 1000 | нет | 40 | OOM-kill, `anon` 500 | 40 × 502, 40 обрывов | +| 4 места, 8 в очереди | есть | 10 / 20 / 40 | 172 / 199 / 289, `sock` 13 / 43 / 134 | 40: 24 × 201, 56 × 429 | +| то же, `tcp_rmem` до 512 KiB | есть | 1 / 10 / 40 | 120 / 163 / 176, `sock` 3 / 7 / 17 | 40: 24 × 201, 56 × 429 | +| 4 места, 16 в очереди, 512 KiB | есть | 10 / 20 / 40 | 169 / 178 / 179 | 30 / 60 × 201; 40: 60 × 201, 60 × 429 | +| то же | нет | 40 | 192, OOM нет | 60 × 201, 60 × 429, p95 2,8 с | +| то же, LB с буфером 256 KiB, реплика без 512 KiB | нет | 40 | 241, `sock` 90 | 60 × 201, 60 × 429 | + +Тело 1 MiB, 4 места и 16 в очереди: 40 клиентов × 5 загрузок — 81 × +201 и 119 × 429 (клиент без паузы), 92 загрузки/с, пик 140 MiB. +Пропускная способность одной реплики на 10 MiB — 7–8,5 загрузки/с с +лимитом и без, её задаёт S3. + +**Шаги одной загрузки** (скрипт в образе API, клиент приложения, 4 +загрузки подряд, `VmHWM` со сбросом). Чтение тела — 1,00 тела, +проверка — 1,00. PUT с `bytes` — 2,02–2,34 тела, `tracemalloc` во время +PUT — +1,05 тела (копия из п. 1). PUT тем же `BytesIO` после `del` ссылки +на `bytes` — 1,19 тела в пяти загрузках, SHA-256 сохранённого объекта +совпал. + +**S3 под одновременной записью** (клиент приложения напрямую, 10 MiB, +три объекта на клиента): + +| C | p50, с | p95, с | max, с | MiB/с | `anon` S3, MiB | +|---|---|---|---|---|---| +| 1 | 0,09 | 0,10 | 0,10 | 107 | — | +| 4 | 0,40 | 0,50 | 0,51 | 99 | — | +| 8 | 0,84 | 1,61 | 1,70 | 85 | — | +| 12 | 1,07–1,18 | 1,71–1,91 | 1,94–2,31 | 85–90 | 341 | +| 16 | 1,67 | 2,39 | 2,49 | 89 | — | +| 24 | 2,60–2,63 | 3,05–3,40 | 3,65–4,42 | 86 | 368 | + +`memory.current` S3 при 12 и 24 — у лимита 512 МБ за счёт страничного +кэша томов (~200 MiB `file`), OOM нет. Срок вызова 5 с близок только при +24 и больше одновременных PUT. + +**HAProxy, сроки** (тот же образ и `defaults` проекта, заглушка на +asyncio вместо реплики, клиент httpx, тело 10 MiB): + +| Случай | Ответ клиенту | +|---|---| +| реплика не читает тело 12 с | 502 через 10,18 с | +| то же, `http-request set-timeout server 30s` на пути | 201 через 12,05 с | +| реплика молчит 12 с после тела | 504 через 10,05 с | +| то же, `set-timeout server 30s` | 201 через 12,05 с | +| ранний 429 до чтения тела 10 MiB | 429 через 0,04 с | +| клиент молчит 35 с посреди тела | 400 HTML через 35,06 с (`cH--`); с `http-error status 400` — 400 в формате контракта | +| клиент шлёт 10 MiB 20 частями раз в 2 с (40 с) | 201 через 40,11 с | +| заголовки приходят за 12 с | 408 HTML; `http-error status 408` не меняет | + +**Память LB** при 40 загрузках по 10 MiB через одну реплику (4 места, 16 +в очереди): + +| LB | пик, MiB | `sock`, MiB | +|---|---|---| +| как сейчас | 109 | 85 | +| `tcp_rmem` LB до 512 KiB | 109 | 82 | +| `tune.sndbuf.server 262144` | 51–52 | 30–32 | + +Копит буфер отправки LB к реплике, а не буфер приёма от клиента. Загрузка +одного клиента со всеми ограничениями — 0,09–0,12 с, как без них. + +**Прототип мест через LB** (1 место, 1 в очереди, ожидание 1 с, тело +2 с): +- тело частями 4 с — 400 «Upload body was not received in time». + Реплика ответила на 2-й секунде, клиент httpx получил ответ, дослав + тело; +- следующая загрузка — 201 через 0,07 с; +- место занято, в очереди одна — третья загрузка получает 429 через + 0,01 с, ожидавшая — 429 через 1,01 с, `Retry-After: 1`; +- ожидавшая 332 мс загрузка — 201, её `created_at` (…49.789113Z) позже + `updated_at` той, что держала место (…49.781759Z). + +## Goals / Non-Goals + +**Goals:** + +- Память загрузок реплики ограничена числом мест, а не числом клиентов, + на всём пути: тело, буферы сокетов реплики и LB. +- Ни одна живая загрузка не обрывается сроком LB, плановой заменой + реплики или уборщиком. Цепочка таймаутов лабы 3 для остальных путей + та же. +- Эксперимент рубрики с ≥ 10 одновременными загрузками — профиль + `bench/` с вариантами «до», «без лимита» и «с лимитом». +- Граница живой загрузки уборщика (B = 17 с) не меняется. Это свойство + закреплено тестом, а не только расчётом. + +**Non-Goals:** + +- Общий лимит загрузок на стенд (очередь в LB) — решение 1. +- Лимит одновременных скачиваний и буферы ядра при медленном + скачивании — ограничение в `REPORT.md`. +- Ограничение частоты запросов пользователя (rate limiting контракта по + пользователю) — факультативно, не делается. +- 408 LB на медленные заголовки в формате контракта — `KNOWN_ISSUES.md`. + +## Decisions + +### 1. Места загрузки — на процесс API + +Процесс API держит `[uploads] max_concurrent` мест (решение 9). Счётчик — +`asyncio.Semaphore`: ожидающие идут по порядку прихода. Рядом счётчик +ожидающих и срок ожидания. Класс `UploadSlots` и глобал `upload_slots` +лежат в `src/infra/upload_slots.py`, глобал создаётся из +`settings.uploads` при импорте, как `_limiter` в `src/infra/password.py`. +Импортирует его только `src/api/dependencies.py`, сервис получает его +конструктором: `AttachmentService(db_scope, cache, storage, slots)`. + +Контекст `slots.slot()`: +- места нет и ожидающих уже `max_waiting` — сразу `UploadsBusy`; +- иначе ожидание места не дольше `wait_timeout_seconds`, не вышло — + `UploadsBusy`; +- место занято — контекст отдаёт время ожидания и освобождает место в + `finally`, в том числе при `CancelledError`. + +Состояние в памяти процесса корректности не задевает: это допуск к +обработке, как лимит хэшей паролей, а не данные (`api-layer.md`). + +*Альтернатива:* очередь в LB — отдельный backend загрузок с `maxconn` на +слот и `timeout queue`. Лучше распределяет нагрузку: загрузка ждёт любую +свободную реплику. Отвергнута: +- слоты второго backend получают адреса из DNS в своём порядке, и + `scripts/rolling-update.sh`, профили `failover` и `rollout` пришлось бы + учить второму набору слотов (дренаж, `maint`, разбор статистики); +- реплика без LB — `make test_isolated`, стенд отказов, консоль — + осталась бы без защиты. + +*Альтернатива:* `--limit-concurrency` uvicorn. Отвергнута: считает все +запросы, а не загрузки, и отвечает 503 текстом, не в формате контракта. +*Альтернатива:* места по байтам (`Content-Length`), как +`concurrentUploadLimitMB` SeaweedFS. Отвергнута: сложнее (свой +семафор с весами без голодания больших), а выигрыш мал: проверка +изображения упирается в 1 CPU реплики. *Альтернатива:* общий счётчик в +Valkey или PostgreSQL. Отвергнута: допуск к обработке — свойство +процесса и его памяти, а отказ Valkey не должен ломать загрузку. + +### 2. Что видит клиент: короткая очередь, затем 429 с `Retry-After` + +Без места загрузка ждёт в очереди процесса до 5 с. Очередь полна или +срок вышел — `429 rate_limited`, `Retry-After: 1`, сообщение «Too many +uploads in progress, retry later». Исключение `UploadsBusy` +(`src/core/exceptions/attachment.py`) — строка в `DOMAIN_ERRORS`, +заголовок — рядом с вызовом `WWW-Authenticate` в `errors.py`. +`Retry-After` — константа `UPLOAD_RETRY_AFTER_SECONDS = 1` +(`src/utils/constants.py`): за секунду освобождаются несколько мест +(7–8,5 загрузки по 10 MiB в секунду на реплику), а повтор через LB уходит +на следующую реплику. + +Контракт для ручки загрузки допускает 201, 400, 401, 404, 413, 415, 429, +503 и 500 (`contracts/openapi.json`): +- 429 — «Ограничение частоты запросов», единственный с заголовком + `Retry-After` (положительное целое); +- 503 — «Зависимость недоступна». + +`contracts/README.md` называет пару `429 rate_limited` и разрешает +факультативное ограничение запросов. Места загрузки — ограничение +одновременности, а не частоты. Это расхождение формулировки, поэтому +трактовка — вопрос преподавателю (`PLAN.md`, `### upload-memory`, +«Вопросы», п. 1). До ответа — 429. Если ответ «503», меняются: +- строка таблицы `errors.py` (заголовок `Retry-After` остаётся); +- сценарии спеков `attachments` и `api-conventions`; +- ожидания тестов и `REPORT.md`. + +Остальной design от ответа не зависит. + +*Альтернатива:* сразу 429, без очереди. Отвергнута: сообщение может +нести до 10 вложений, и клиент шлёт их разом. На пробе 10 и 20 +одновременных загрузок по 10 MiB с очередью — все 201 (p95 1,5 и 2,8 с), +без очереди лишние сверх 4 получали бы 429. *Альтернатива:* ждать без +срока. Отвергнута: молчание реплики до тела ограничено сроком LB +(решение 7), а ожидающих без предела — память (Context, п. 2). +*Альтернатива:* 503 `unavailable` с `Retry-After`. Её семантика HTTP +(перегрузка) подходит, но описание контракта — «зависимость недоступна». +Тогда отказ S3 и занятые места не различить ни клиенту, ни профилю +`uploads` (ответы по кодам). Поэтому 503 — только по ответу +преподавателя. + +### 3. Где место в пути загрузки + +Порядок (спек `attachments`, «Порядок проверок загрузки»): +1. вход, параметры, членство (404), `Content-Type` (415), + `Content-Length` (413) — без места; +2. место (429); +3. тело со счётчиком и сроком (413, 400); +4. проверка изображения и SHA-256 (415, 413); +5. строка `pending` (tx1), PUT, `ready` (tx2), компенсация; +6. ответ, место освобождается. + +Ранние отказы не занимают места и не стоят в очереди: посторонний или +заведомо большое тело не вытесняют живые загрузки. Ожидающая загрузка +сессии БД не держит: вход и членство — короткие шаги до места (решение +5 design `attachments`). + +Место держится до ответа, включая tx2 и компенсацию: при медленном S3 +или БД меньше загрузок держат тела одновременно. + +**Граница B уборщика не меняется.** Ожидание места, тело и проверка идут +до `created_at` строки `pending`, а сроки tx1, PUT и tx2 прежние +(решение 8). Проверка `src/cleaner/main.py`, grace 900 с и стенд отказов +(20 с) остаются. Свойство закреплено сценарием `storage-consistency` +«Ожидание места не входит в возраст загрузки»: `created_at` ожидавшей +позже `updated_at` той, что держала место (проба прототипа). Дельта +`storage-consistency` уточняет только текст, правило `settings.md` и +`REPORT.md` называют, почему B прежняя. + +*Альтернатива:* место после строки `pending`. Отвергнута: очередь +удлинила бы B, а с ней — проверку уборщика и grace стенда отказов. +*Альтернатива:* место после чтения тела. Отвергнута: тела ожидающих уже +в памяти. *Альтернатива:* отпускать место сразу после PUT. Отвергнута: +выигрыш — только время tx2, а правило «место = загрузка до ответа» +проще проверять. + +### 4. Срок передачи тела + +`[uploads] body_timeout_seconds` (30 с) — один срок на всё тело с +момента, как загрузка заняла место: `asyncio.timeout` вокруг +`_read_body`. Истёк — `UploadTimedOut` (новое исключение, 400 +`invalid_request`, «Upload body was not received in time»), `info` +«Rejected attachment» с `reason=body_timeout`. Отклонение — до строки +`pending`: ни метаданных, ни объекта. Через LB простой клиента +ограничивает ещё и `timeout client` (30 с). Его 400 переводится в +формат контракта (решение 7). + +Код 400 — по образцу обрыва тела (`UploadInterrupted`, 400, design +`attachments`, решение 6): клиент не доставил тело. 408 в контракте +ручки нет. + +*Альтернатива:* срок простоя между блоками. Отвергнута: клиент, который +шлёт по байту раз в 29 с, держит место бесконечно — проба через LB: +10 MiB за 40 с прошли. *Альтернатива:* 60 с. Отвергнута: место +держится дольше, а наибольшая длительность загрузки и срок дренажа +растут до ~105 с. 30 с хватает для 10 MiB от 2,8 Мбит/с, медленная +передача из `evidence/attachments/slow-transfer.md` (12,4 с) проходит. +*Альтернатива:* `option http-buffer-request` и `timeout http-request` в +LB. Отвергнута: LB буферизует тело, а для 10 MiB его буферов нет. + +### 5. Одна копия тела: в PUT уходит тот же `BytesIO` + +`_read_body` возвращает `BytesIO`, в котором копилось тело. Сервис: +1. `data = buffer.getvalue()` — `bytes` над буфером, без копии; +2. проверка изображения и SHA-256 в потоке над `data`; +3. `size = len(data)`, затем `del data` — буфер снова не общий; +4. `buffer.seek(0)` и PUT этим `BytesIO`. + +aiohttp тогда берёт `getbuffer()` без копии. Проба: 1,19 тела на PUT +вместо 2,02–2,34 (Context). `ObjectStorage.put(key, body, *, size, +content_type)` принимает поток с `read`, `seek` и `tell`. `size` идёт в +журнал вызова. `put_original` в repo — так же. Других вызовов `put` нет. + +`MALLOC_MMAP_THRESHOLD_` в образе остаётся: рост буфера через `mremap` +без копии (решение 6 design `attachments`). + +*Альтернатива:* свой `io.RawIOBase` над `memoryview`. Отвергнута: aiohttp +читает такие потоки через пул потоков, блок за блоком. *Альтернатива:* +`bytearray`. Отвергнута: его копирует botocore. *Альтернатива:* своя +регистрация payload aiohttp. Отвергнута: зависит от внутренностей +aiohttp. + +### 6. Буферы ядра: 512 KiB у реплики, 256 KiB у LB к реплике + +- Сервис `api` в `docker-compose.yml`: `sysctls: net.ipv4.tcp_rmem: + "4096 131072 524288"`. Буфер приёма сокета реплики — не больше + 512 KiB. Ожидающая или отклонённая загрузка держит в ядре до 0,5 MiB, + а не до 32 MiB. Параметр сетевого пространства контейнера: его + наследуют все контейнеры сервиса — рабочий стенд, `bench/`, `make + test_isolated`, стенд отказов. +- `infra/haproxy/haproxy.cfg`, `global`: `tune.sndbuf.server 262144`. + Буфер отправки LB к реплике фиксирован, недочитанное тело не копится в + памяти LB: 51 MiB вместо 109 при 40 загрузках. + +Скорость не страдает: RTT в сети Docker — доли миллисекунды, загрузка +10 MiB — 0,09–0,12 с, как без ограничений (Context). Буфер приёма LB от +клиента не ограничен: с фиксированным буфером к реплике LB держит +~0,75 MiB на соединение (проба), а клиентам с большим RTT нужен большой +буфер. + +В консоли (`make run_dev`, процесс на macOS) sysctl нет — ограничение в +`REPORT.md` и `run-modes.md`. Места загрузки там работают. + +*Альтернатива:* `SO_RCVBUF` на сокете uvicorn из приложения. Отвергнута: +`uvicorn.run` своих опций сокета не принимает, пришлось бы связывать +сокет самим, а в режиме reload сокет связывает супервизор. +*Альтернатива:* без ограничения. Отвергнута: `sock` реплики — 90–134 MiB +при 40 клиентах, и память растёт с числом клиентов, а не мест. +*Альтернатива:* `maxconn` на слот в backend `api`. Отвергнута: меняет +поведение всех путей лабы 3 под нагрузкой и при зависшей реплике +(очередь LB и `timeout queue` вместо 504), то есть профиль `failover`. + +### 7. Цепочка таймаутов пути загрузки + +| Звено | Значение | Обоснование | +|---|---|---| +| молчание реплики до тела | ≤ 2 × `request_timeout_seconds` (6) + `wait_timeout_seconds` (5) = 17 с | вход и членство — по шагу БД, затем место | +| тело | ≤ `body_timeout_seconds` (30 с) | решение 4; простой клиента ≤ `timeout client` 30 с | +| молчание реплики после тела | ≤ проверка (до ~4 с при 4 загрузках на 1 CPU) + tx1 6 + PUT 5 + tx2 6 + компенсация 5 ≈ 26 с | шаги с прежними сроками | +| `timeout server` LB на пути загрузки | 30 с | больше 17 и 26 с; `http-request set-timeout server 30s if METH_POST { path_reg ^/api/v1/chats/[^/]+/attachments$ }` в `backend api` | +| `timeout server` остальных путей | 10 с, как было | цепочка лабы 3 (`balancer.md`) | +| наибольшая длительность загрузки U | 17 + 30 + 26 ≈ 73 с | | +| `ROLLOUT_DRAIN_TIMEOUT` | 90 с | > U и > 30 с; обычно дренаж кончается за 0–2 с, срок нужен только медленной загрузке | +| `graceful_shutdown_seconds` | 8 с, как было | `stop-one.sh` и `docker stop` — отказ, загрузка дольше 8 с обрывается, строка `pending` — уборщику | + +Ещё в `defaults` LB — `http-error status 400 … invalid_request`, в том же +формате, что 502/503/504: клиенту, замолчавшему посреди тела дольше 30 с, +и любому неверному запросу LB отвечает в формате контракта. + +Проверка конфигурации — `haproxy -c` в закреплённом образе. Проверка +поведения — драйвер скилла `lb-upload-timeouts`: +- временная сеть, HAProxy с `infra/haproxy/haproxy.cfg` проекта; +- заглушка под именем `api` на образе API, `/health/ready` — 200, + остальные пути — задержки по пути; +- случаи: молчание 12 с на пути загрузки до тела и после тела — 201; + 12 с на другом пути — 504 через ~10 с; 32 с на пути загрузки — 504 + через ~30 с; клиент молчит посреди тела 35 с — 400 в формате контракта. + +Evidence — `evidence/uploads/lb-timeouts.md`. Так проверяется сама +конфигурация LB, без отказов хранилищ. + +*Альтернатива:* общий `timeout server` 30 с. Отвергнута: зависшая +реплика держала бы любой запрос 30 с до 504, а срок обнаружения отказа +(6,5 с) и замеры `failover` лабы 3 рассчитаны на 10 с. *Альтернатива:* +общий срок всей загрузки в API не больше 9 с. Отвергнута: отмена посреди +tx1, PUT или tx2 ломает правила компенсации `upload-consistency`. +*Альтернатива:* оставить 10 с. Отвергнута: в худшем пути клиент получает +502/504, а загрузка может стать `ready` (`REPORT.md`, «Ограничения»). + +408 на медленные заголовки остаётся HTML (Context, п. 4). `errorfile 408` +дал бы только статичный `request_id`, а контракт требует тот же id, что +в `X-Request-Id`, и он должен быть уникален. Это не путь загрузки: +запись `KNOWN_ISSUES.md` с предложением. + +### 8. S3: прежние лимиты и прежний срок вызова + +- `-s3.concurrentUploadLimitMB=64`, `GOMEMLIMIT=400MiB` и 512 МБ + остаются. Места API ограничивают число одновременных PUT в S3: N × 4 — + 8 на рабочем стенде, 12 во время `make rolling_update`. Там p95 PUT — + 1,6–1,9 с, max — 2,3 с, `anon` S3 — 341 MiB (проба). +- `[s3] timeout_seconds` 5 с — один для всех вызовов. Отдельного срока + PUT по размеру нет. Это закрывает открытый вопрос design `attachments` + («Срок PUT большого объекта под одновременной записью»): при 12 PUT + запас больше двух раз. + +*Альтернатива:* срок PUT по размеру (5 с + размер / скорость). +Отвергнута: B выросла бы, а с ней grace стенда отказов (сейчас 20 с при +B = 17) и проверка уборщика. Удаление объекта уборщиком внутри +транзакции должно оставаться короче `idle_in_transaction` (10 с), а +значит, общий срок вызова поднимать нельзя. *Альтернатива:* поднять +`concurrentUploadLimitMB`. Отвергнута: при 24 одновременных PUT `anon` S3 +уже 368 MiB при `GOMEMLIMIT` 400 MiB. + +### 9. Значения по умолчанию + +| Параметр | Значение | Почему | +|---|---|---| +| `max_concurrent` | 4 | бюджет реплики 512 МБ: база ~105 MiB + хэши паролей 4 × 64 MiB + места до ~90 MiB при 40 клиентах (замер) ≈ 450 MiB. При 8 местах — ~530 MiB > 512 | +| `max_waiting` | 16 | на пробе 20 одновременных по 10 MiB — все 201, ожидание ≤ 2,8 с < 5 с; ожидающий держит ≤ ~0,8 MiB | +| `wait_timeout_seconds` | 5 | молчание до тела ≤ 17 с < 30 с LB; дольше ждать бессмысленно — реплика насыщена | +| `body_timeout_seconds` | 30 | решение 4 | +| `Retry-After` | 1 с (константа) | решение 2 | + +Секция `[uploads]` — класс `Uploads` в `src/config/settings.py`, строки в +`config_example.toml`, подмена — `UPLOADS__*`. Значения отличаются +между установками: у них разный лимит памяти, а профилю `uploads` нужен +вариант «без лимита». Поэтому это настройки, а не константы. + +Запись «Started API» дополняется полями `uploads_max_concurrent`, +`uploads_max_waiting`, `uploads_wait_timeout_seconds`, +`uploads_body_timeout_seconds`. В журнале загрузок: +- «Rejected attachment» с `reason` `busy` (с `waited_ms`) и + `body_timeout`; +- «Uploaded attachment» с `waited_ms`. + +`filename` в журнал по-прежнему не попадает (`logging.md`). + +### 10. Профиль `uploads` стенда `bench/` + +Методика — поля `Profile` (`run.py`), правило `bench.md` — новым +разделом: +- **Стенд** `mtusi-bench`: LB (1 CPU / 256 МБ), одна реплика (1 CPU / + 512 МБ, `memswap_limit` = память — OOM-kill виден, а не прячется в + swap), PostgreSQL 2 CPU / 1 ГБ, Valkey 0,5 / 128 МБ, S3 и + `s3-bootstrap` — образ, аргументы и лимиты рабочего стенда. Первый + профиль, который запускает S3: override `s3` уже описан, `bench.env` + даёт `S3__BUCKET=bench`. Буфер приёма реплики — из основного compose + (решение 6) и в паспорте. Генератор k6 — без лимита, как в `failover`. +- **Варианты:** + - «до» — образ `git archive f894040` под тегом `bench-from` (механизм + `rollout_from`, проверка commit до стенда); + - «без лимита» — образ checkout с `UPLOADS__MAX_CONCURRENT=1000`, + `UPLOADS__MAX_WAITING=0`; + - «с лимитом» — образ checkout с параметрами по умолчанию. + + Окружение варианта — в паспорт (`stand.app_env` по варианту). +- **Тела** — PNG из шума RGB шириной 1024 на `random.Random(seed)`: + около 1 MiB и около 10 MiB, ≤ 10 485 760 байт. Строит оркестратор + (stdlib), монтирует в k6, размеры и SHA-256 — в паспорт. +- **Прогон** — вариант × размер × C ∈ {1, 10, 20, 40} × повтор (3). + Порядок — круги с перестановкой по зерну, как в сериях. Перед каждым + прогоном: + - новый volume S3 (`rm -sf s3`, удаление volume, `up --wait s3`, + bootstrap); + - новый контейнер реплики с окружением варианта; + - ожидание `UP` в LB; + - одна разогревающая загрузка. + + PostgreSQL и пользователь — на всю метку. Вход по Basic (Argon2id) — + до первого окна. +- **Окно** — `constant-vus` k6: C VU, 3 с разгона и 20 с окна, каждая VU + грузит без пауз. На 429 — пауза `Retry-After`, на прочие ошибки — 1 с. + Строка на запрос — в файл консоли k6, как в `failover`. +- **Память** — сэмплер на образе PostgreSQL стенда, новый режим `peak`. + В начале окна он сбрасывает `memory.peak` реплики, S3 и LB через свой + дескриптор (perl: открытие на запись, `sysseek`, `sysread`). В конце + читает пик через тот же дескриптор. Раз в 0,2 с пишет + `memory.current`, `anon`, `sock`, `memory.events` (`oom_kill`). Нужен + cgroupfs на запись (`-v /sys/fs/cgroup:/sys/fs/cgroup:rw`, `--user 0`), + без сети. Ядро без сброса (< 6.12) — наибольшая выборка и пометка + `peak_sampled` в паспорте. +- **Строка прогона** (`runs.csv`): вариант, размер, C, повтор, память + перед окном, пик окна, наибольшие `anon` и `sock` реплики, `oom_kill`, + код выхода и `OOMKilled` контейнера, ответы по кодам (201, 429, 400, + 413, 415, 502, 503, 504, ошибка соединения), загрузок 201 в секунду, + p50 / p95 / p99 успешных, пики S3 (и `anon`) и LB, пометки (`oom`, + `host_swap`). +- **Сводка** (`summary.md`): по ячейке — медиана и разброс повторов, + проверка гипотез числами из таблицы. Каталог — + `evidence/uploads/<метка>/` (`meta.json`, `runs.csv`, `summary.md`, + `raw/<прогон>-k6.json`); `quick-uploads-*` — в `.gitignore`. +- **Время**: прогон ~40 с со сменой S3 и реплики. Полный профиль — 72 + прогона, ~50 мин; быстрый — «без лимита» и «с лимитом», 10 MiB, C ∈ + {1, 10, 40}, один повтор, ~5 мин. Диск: до ~1,8 ГиБ записей за прогон, + volume удаляется перед следующим. +- **Чёрный ящик**: k6 — только HTTP через LB. Оркестратор — docker CLI, + счётчики cgroup (сэмплер) и смена volume S3 с bootstrap. К bucket и + объектам он не обращается. Исключение для S3 — новой строкой `bench.md` + рядом с исключением PostgreSQL. + +**Гипотезы** (числа — из проб, фиксируются commit до первого прогона; +`REPORT.md`, раздел загрузок): +- H1 — «с лимитом»: пик реплики при 10 MiB и C = 10, 20, 40 не больше + половины лимита (256 MiB). Сверх пика при C = 10 — не больше 1 MiB на + клиента. OOM нет, 5xx нет, лишние — 429. +- H2 — «без лимита»: пик растёт примерно на 1,2–1,3 тела на клиента. При + 40 × 10 MiB реплика убита из-за памяти. «До» растёт на ~2,1 тела на + клиента и убита уже при 20 × 10 MiB. +- H3 — загрузок 201 в секунду при C ≥ 10 у «с лимитом» не меньше 90 % от + «без лимита» на тех же C, пока тот жив. Предел задаёт S3, а не места. + p95 растёт на время ожидания в очереди. +- H4 — 503 из-за срока PUT нет ни в одном варианте, пока реплика жива: в + S3 не больше 4 PUT от одной реплики. + +*Альтернатива:* время окна вместо числа загрузок — оставлено окно, как в +остальных профилях. *Альтернатива:* две реплики. Отвергнута: число +клиентов на реплику было бы неточным из-за round-robin, а память +считается на реплику. *Альтернатива:* без варианта «до». Отвергнута: +без него правка решения 5 доказана только пробой, а не меткой. +*Альтернатива:* общий S3 на все прогоны. Отвергнута: десятки гигабайт +объектов, страничный кэш S3 менял бы его память от прогона к прогону. + +### 11. Тесты + +`make student_test` и `make test_isolated` (`test_attachments.py`): +- `test_concurrent_uploads` — 10 потоков за `threading.Barrier`, у + каждого свой `Api`. Все 201, `id` разные, каждое скачивается с тем же + SHA-256. Тело — PNG ~1 MiB из `images.py`. Сценарий «Загрузки в + пределах лимита»; при параметрах по умолчанию 10 загрузок помещаются + в места и очередь даже одного процесса. + +`make failure_checks` — третий API стенда отказов +`<проект>-api-uploads` (`run_failures.py`, `UPLOADS_ENV`): +`UPLOADS__MAX_CONCURRENT=1`, `UPLOADS__MAX_WAITING=1`, +`UPLOADS__WAIT_TIMEOUT_SECONDS=1`, `UPLOADS__BODY_TIMEOUT_SECONDS=2`. +Тесты получают `FAULT_UPLOADS_BASE_URL` и `FAULT_UPLOADS_ENV`. Место +держит загрузка A: тело — генератор, который отдаёт половину и ждёт +`threading.Event` теста. Пока она идёт, тест выполняет нужный запрос, +затем отпускает A. Тесты и сценарии: + +| Тест | Сценарии | Ход | +|---|---|---| +| `test_upload_slots_busy` | `attachments` «Все места заняты», «Очередь ожидания полна»; `api-conventions` «Лимит одновременных загрузок» | A держит место → B ждёт → C сразу 429 (< 0,5 с) → B — 429 не раньше 1 с; у обоих `Retry-After` ≥ 1, формат ошибки, `X-Instance-Id` → новых `id` нет ни в строках, ни в объектах → A отпущена — 201 | +| `test_rejections_before_queue` | `attachments` «Отказ раньше очереди» | A держит место, B ждёт → посторонний, 30 MiB с `Content-Length`, `text/plain` — 404, 413, 415 быстрее 0,5 с | +| `test_upload_waits_for_slot` | `attachments` «Ожидание места»; `storage-consistency` «Ожидание места не входит в возраст загрузки» | A держит место ~0,5 с → B ждёт и получает 201 → `B.created_at > A.updated_at` → оба скачиваются с тем же SHA-256 | +| `test_slot_released_after_failures` | `attachments` «Место освобождается» | по очереди: 10 MiB + 1 частями (413), текст (415), тело дольше 2 с (400), обрыв тела (исключение итератора), S3 `stop` (503, затем `start`) → после каждого загрузка `sample.png` — 201 быстрее срока ожидания | +| `test_slow_body` | `attachments` «Медленный клиент», «Медленная передача в срок» | тело частями за 3 с — 400 `invalid_request`, новых `id` нет; тело частями за ~1 с — 201 с тем же SHA-256 | + +Клиент тестов с ожиданием — со сроком 30 с. Тесты читают свои сроки из +`FAULT_UPLOADS_ENV` и проверяют, что стенд запущен с ними. Новые тесты +добавляют к `make failure_checks` ~25 с, третий API — ~3 с старта. +`contract.py`: `assert_error(resp, 429)` требует `Retry-After` — +положительное целое. + +Сверка покрытия (`spec_coverage.py`, `EXCLUDED`), способ — метка +профиля `uploads`: +- `attachments` «Одна копия тела при записи в S3» — варианты «до» и + «без лимита» при C = 10; +- `attachments` «Память не растёт с числом загрузок» — вариант «с + лимитом». + +Ссылка — на `evidence/uploads/<метка>/summary.md`. Файл должен быть в +git до sync дельт (`student-tests.md`). + +### 12. Документы и evidence + +- Правила: `api-contract.md` (429, порядок проверок), `service-layer.md` + (места, буфер в PUT), `infra.md` (`upload_slots.py`), `settings.md` + (`[uploads]`, B прежняя), `docker.md` (sysctl `api`), `balancer.md` + (срок пути загрузки, `http-error 400`, `tune.sndbuf.server`, дренаж + 90 с), `bench.md` (профиль `uploads`, исключение S3), `student-tests.md` + (третий API, тесты), `logging.md` (поля), `run-modes.md` (консоль без + sysctl); AGENTS.md — команды и карта кода. +- Evidence (с закоммиченного кода): + - `evidence/uploads/<метка>/` — `make bench_uploads`; + - `evidence/uploads/lb-timeouts.md` — `driver.py lb-upload-timeouts`; + - `evidence/uploads/rollout-upload.md` — медленная загрузка (~20 с) + во время `make rolling_update`, 201 и строки дренажа; + - `evidence/tests/` — `make failure_checks`, `make student_test` через + LB, `make test_isolated`. +- `REPORT.md`: + - раздел «Память и сроки загрузки»: места, очередь и 429, срок тела, + одна копия, буферы, цепочка таймаутов с формулами, B прежняя; + - эксперимент: гипотезы, методика, таблица, выводы, ограничения; + - пункты «Ограничений» о памяти ~1,2 тела, очереди SeaweedFS, + компенсации +5 с и сроке LB переписываются по факту; + - строка таблицы доказательств вместо `TODO (upload-memory …)`. + +## Risks / Trade-offs + +- [Места считает каждая реплика: одна отвечает 429, пока у другой есть + свободные; LB 429 не повторяет] → очередь сглаживает всплески, + `Retry-After: 1` и round-robin уводят повтор на другую реплику; + ограничение в `REPORT.md`. +- [Тело отклонённой загрузки реплика дочитывает и выбрасывает (uvicorn + держит соединение)] → память это не занимает (буферы по решению 6), + но CPU и сеть тратит. Закрывать соединение после раннего ответа + нельзя: ядро сбросит его вместе с непрочитанным ответом. Ограничение в + `REPORT.md`. +- [Тысячи одновременных загрузок: LB держит до ~0,8 MiB на соединение, + `maxconn` 4096 больше его лимита 256 МБ] → предел — `maxconn`; + ограничение в `REPORT.md`, на стенде нагрузки такого уровня нет. +- [Ограничение буфера приёма снижает скорость клиента с большим RTT] → + ограничен только буфер реплики в сети Docker, клиентский буфер LB не + тронут. +- [Скачивание медленному клиенту держит буферы ядра у реплики и LB, а + лимита одновременных скачиваний нет] → вне change, ограничение в + `REPORT.md`. +- [Ответ на вопрос 1 — «503»] → смена одной строки таблицы ошибок, + сценариев и ожиданий тестов (решение 2). +- [Сброс `memory.peak` требует ядра ≥ 6.12 и cgroupfs на запись у + сэмплера] → иначе наибольшая выборка раз в 0,2 с и пометка в паспорте. + На пробе выборка раз в 20 мс отставала от пика на 1–5 MiB. +- [Зависшая реплика держит загрузку 30 с до 504 вместо 10] → только путь + загрузки; обнаружение отказа проверками LB не меняется (6,5 с). +- [`ROLLOUT_DRAIN_TIMEOUT` 90 с: застрявшая загрузка задерживает замену] → + срок тела ограничивает её ~73 с; обычный дренаж — 0–2 с. +- [Регулярное выражение пути в LB разойдётся с API при смене префикса] → + комментарий в `haproxy.cfg` и в `balancer.md`, сценарий драйвера на + настоящем пути. +- [Вариант «до» требует commit в истории] → проверка до стенда, как у + `rollout_from`; при переходе в лабу 5 — правило AGENTS.md. +- [Стенд `bench/` для прежних профилей меняется: буфер приёма реплики + 512 KiB] → запросы и ответы JSON меньше начального буфера (128 KiB), + на результаты не влияет; значение в паспорте, правило `bench.md` + называет смену. +- [В консоли sysctl нет] → ограничение `run-modes.md` и `REPORT.md`; + места работают. + +## Migration Plan + +1. Код: места, срок тела, буфер в PUT, ошибки, настройки, журнал. + Миграции схемы нет. +2. Стенд: `sysctls` у `api`, `haproxy.cfg`, `rolling-update.sh`, + `config_example.toml`. +3. Тесты, стенд отказов, сверка покрытия; `make lint`, прогоны. +4. Профиль `uploads`, драйвер, регресс `bench/`. +5. Правила, AGENTS.md, `KNOWN_ISSUES.md`, `PLAN.md`. +6. Commit после подтверждения пользователя. Затем гипотезы — отдельным + commit, затем замеры и evidence с закоммиченного кода, затем + `REPORT.md`. + +На рабочем стенде: +1. `make rolling_update` — реплики на новый образ, новые контейнеры + получают `sysctls` из compose; старые без ограничения дорабатывают + до дренажа. +2. `docker compose up -d --force-recreate haproxy` — новая конфигурация + LB. Перерыв точки входа — ~1–2 с, LB один (`balancer.md`). + +Уборщик не меняется. Откат: +- `make rolling_update COMMIT=f894040 MIGRATE=0`; +- `haproxy.cfg` прежнего commit и пересоздание LB. + +Схема и данные не меняются. + +## Open Questions + +- Код ответа при занятых местах — 429 `rate_limited` или 503 + `unavailable` (решение 2, `PLAN.md`, «Вопросы», п. 1). До ответа + преподавателя — 429; ответ меняет одну строку таблицы ошибок, сценарии + и тесты, но не подход и не задачи. diff --git a/openspec/changes/upload-memory/proposal.md b/openspec/changes/upload-memory/proposal.md new file mode 100644 index 00000000..f599a82a --- /dev/null +++ b/openspec/changes/upload-memory/proposal.md @@ -0,0 +1,124 @@ +# Proposal + +## Why + +Рубрика «4» лабы 4 (`README.md`): лимиты, таймауты и потоковая обработка +не должны позволять загрузкам занять неограниченную RAM, нужен +эксперимент с ≥ 10 одновременными загрузками и замером пика памяти. +Сейчас лимита одновременных загрузок нет, и проба этого change показала +больше, чем записано в `REPORT.md` (design, Context): +- при записи объекта в S3 тело копируется ещё раз: пик одной загрузки — + около двух тел, а не 1,2; +- 20 одновременных загрузок по 10 MiB убивают реплику 512 МБ по памяти + (OOM-kill), если swap выключен. На рабочем стенде со swap реплика + уходит в swap на ~270 MiB уже при 30 загрузках; +- ожидание до чтения тела память не бережёт: недочитанное тело копится в + буфере сокета ядра, до 32 MiB на соединение, и этот буфер считается + памятью контейнера; +- у чтения тела нет общего срока: медленный клиент держит загрузку + сколько угодно. При этом обработка после тела и ожидание до него могут + длиться дольше `timeout server` LB (10 с). Тогда LB отвечает 502/504, + хотя API ещё доведёт загрузку. + +## What Changes + +- Лимит одновременных загрузок на реплику, `[uploads] max_concurrent` + (по умолчанию 4). Место берётся после проверок 401/400/404/415/413 по + `Content-Length` и до чтения тела. Сверх лимита — очередь до + `max_waiting` (16) с ожиданием не дольше `wait_timeout_seconds` (5 с). + Очередь полна или срок вышел — `429 rate_limited` с `Retry-After`. + Такой ответ ничего не оставляет ни в PostgreSQL, ни в S3. Место + освобождается при любом исходе: 201, ошибка, обрыв, срок. +- Срок чтения тела `[uploads] body_timeout_seconds` (30 с) с момента, + как загрузка заняла место. Не успел — 400 `invalid_request`, ни + метаданных, ни объекта. +- Тело уходит в PUT тем же буфером, в котором копилось, — без второй + копии. Требование «на загрузку — не больше лимита и блока чтения» + спека `attachments` снова выполняется и на шаге записи в S3. +- Буфер приёма сокетов реплики API ограничен 512 KiB + (`net.ipv4.tcp_rmem` в compose). Буфер отправки LB к репликам — + 256 KiB (`tune.sndbuf.server`). Так ожидающая или отклонённая загрузка + держит в ядре сотни килобайт, а не всё тело. +- Цепочка таймаутов пути загрузки: + - у `POST …/attachments` свой `timeout server` LB — 30 с, больше + самого длинного молчания живой загрузки (до тела ≤ 17 с, после тела + ≤ ~26 с). У остальных путей прежние 10 с; + - ответ LB 400 (клиент замолчал посреди тела) — в формате ошибки + контракта; + - срок дренажа `scripts/rolling-update.sh` — 90 с, больше наибольшей + длительности загрузки (~73 с). Плановая замена не обрывает живую + загрузку. +- Граница живой загрузки уборщика не меняется: место, тело и проверка + изображения идут до записи метаданных, а сроки шагов после неё прежние + (B = 17 с). Это свойство закреплено сценарием и тестом. +- Профиль `uploads` стенда `bench/` (`make bench_uploads`, + `make bench_uploads_quick`). Одна реплика с лимитами рабочего стенда, + без swap, 1 / 10 / 20 / 40 одновременных загрузок по 1 и 10 MiB. Три + варианта: + - «до» — код до этого change; + - «без лимита» — этот код с огромным лимитом; + - «с лимитом» — значения по умолчанию. + + По каждому прогону — пик памяти реплики (`memory.peak` cgroup со + сбросом на окно), OOM-kill, ответы по кодам, p50 / p95, загрузок в + секунду, память S3 и LB; 3 повтора. Гипотезы коммитятся до прогонов. +- Тесты: + - `make student_test` — 10 одновременных загрузок проходят; + - `make failure_checks` — третий API стенда отказов с одним местом + загрузки. На нём: 429 после ожидания и сразу при полной очереди, + отказы раньше очереди, освобождение места после ошибок и обрыва, + медленный клиент, ожидание места не входит в возраст загрузки. +- Драйвер скилла: `lb-upload-timeouts` — сроки LB на заглушке за + конфигурацией проекта. Evidence `evidence/uploads/`, раздел + `REPORT.md` о памяти и сроках загрузки, выводы эксперимента. + +Не входит: reconciler и стоимость сверки (`track2-reconciler`, +`track2-reconcile-cost`), presigned upload, превью и `202` (лаба 5), +лимит одновременных скачиваний, отчёт и PR (этап 7). + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +- `attachments`: лимит одновременных загрузок реплики, очередь, 429 с + `Retry-After`; срок передачи тела; место в «Порядке проверок + загрузки»; одна копия тела и при записи в S3. +- `api-conventions`: пара 429 — `rate_limited` с `Retry-After`. +- `storage-consistency`: ожидание места и чтение тела не входят в + границу живой загрузки. +- `service-configuration`: секция `[uploads]`. +- `load-balancing`: сроки и буферы пути загрузки в LB, ответ LB 400 в + формате контракта, срок дренажа больше длительности загрузки. +- `load-benchmark`: профиль загрузок, S3 и образ «до» на стенде, + результаты в отчёте. +- `student-tests`: третий API стенда отказов, новые сценарии отказов. + +## Impact + +- Код: + - `src/core/services/attachment.py` — место загрузки, срок тела, + буфер в PUT; + - новый `src/infra/upload_slots.py` — места загрузок процесса; + - `src/infra/s3/client.py`, `src/core/repos/attachment_object.py` — + тело-поток в `put`; + - `src/core/exceptions/attachment.py` и `src/api/errors.py` — 429 с + `Retry-After`, 400 по сроку тела; + - `src/api/dependencies.py`, `src/config/settings.py` (`[uploads]`), + `src/utils/constants.py`, `src/main.py` (запись о старте). +- Стенд: `docker-compose.yml` (`sysctls` у `api`), + `infra/haproxy/haproxy.cfg`, `scripts/rolling-update.sh`, + `config_example.toml`, `Makefile`; `bench/` (профиль, k6, сэмплер, + override). +- Тесты: `student-tests/test_attachments.py`, `test_failures.py`, + `contract.py`, `run_failures.py`, `spec_coverage.py`. +- Документы: скилл `run-mtusi-messenger`; правила `api-contract.md`, + `service-layer.md`, `infra.md`, `settings.md`, `docker.md`, + `balancer.md`, `bench.md`, `student-tests.md`, `logging.md`, + `run-modes.md`; AGENTS.md, `REPORT.md`, `PLAN.md`, `KNOWN_ISSUES.md`. +- Регресс: быстрые профили `bench/` лаб 2–3, `make failure_checks` + (дольше на ~30 с), `make test-persistence`, `make test-failover`, + `make rolling_update`. diff --git a/openspec/changes/upload-memory/specs/api-conventions/spec.md b/openspec/changes/upload-memory/specs/api-conventions/spec.md new file mode 100644 index 00000000..403b2a43 --- /dev/null +++ b/openspec/changes/upload-memory/specs/api-conventions/spec.md @@ -0,0 +1,37 @@ +## MODIFIED Requirements + +### Requirement: Соответствие статусов и кодов ошибок + +Сервис SHALL использовать пары статус — `code`: 400 — +`invalid_request`, 401 — `unauthorized`, 404 — `not_found`, 409 — +`conflict`, 413 — `payload_too_large`, 415 — `unsupported_media_type`, +429 — `rate_limited`, 500 — `internal_error`, 503 — `unavailable`. +Метод, не поддерживаемый путём, SHALL давать 405 с `code` +`invalid_request`. Ответ 429 SHALL содержать заголовок `Retry-After` — +положительное целое число секунд. + +#### Scenario: Неизвестный путь + +- **WHEN** клиент запрашивает `GET /api/v1/unknown` +- **THEN** ответ 404 с `code` `not_found` в формате ошибки + +#### Scenario: Неподдерживаемый метод + +- **WHEN** клиент выполняет `DELETE /api/v1/users` +- **THEN** ответ 405 с `code` `invalid_request` в формате ошибки + +#### Scenario: Лимит и тип вложения + +- **WHEN** участник загружает вложение больше 10 MiB, а затем текст с + `Content-Type: image/png` +- **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` — + положительным целым числом diff --git a/openspec/changes/upload-memory/specs/attachments/spec.md b/openspec/changes/upload-memory/specs/attachments/spec.md new file mode 100644 index 00000000..26a4e22a --- /dev/null +++ b/openspec/changes/upload-memory/specs/attachments/spec.md @@ -0,0 +1,182 @@ +## MODIFIED Requirements + +### Requirement: Лимит размера до чтения тела + +Тело больше 10 485 760 байт (10 MiB) SHALL отклоняться ответом 413 +`payload_too_large`, а тело ровно 10 485 760 байт проверку размера +SHALL проходить. Если `Content-Length` запроса больше лимита, ответ +SHALL отдаваться без чтения тела. Без `Content-Length` (передача +частями) тело SHALL читаться потоком со счётчиком. Ответ 413 SHALL +отдаваться, как только прочитано больше лимита, остаток тела MUST NOT +читаться. На одну загрузку процесс API MUST NOT держать в памяти больше +лимита и одного блока чтения тела. Это касается всех шагов загрузки, в +том числе записи объекта в S3: для отправки тело MUST NOT копироваться +целиком. + +#### Scenario: Граница размера + +- **WHEN** участник загружает настоящий PNG размером ровно 10 485 760 + байт, а затем такой же PNG на один байт длиннее +- **THEN** первый ответ 201, второй — 413 `payload_too_large` + +#### Scenario: Заявленный размер больше лимита + +- **WHEN** участник загружает 30 MiB с `Content-Length` 31 457 280 +- **THEN** ответ 413 `payload_too_large` в формате ошибки, а клиент + получает его, не дожидаясь отправки всего тела + +#### Scenario: Большое тело без 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 определяться первой из +них по порядку: +1. 401 — нет действительной сессии; +2. 400 — неверный `chat_id` или `filename`; +3. 404 — чата нет или пользователь в нём не состоит; +4. 415 — `Content-Type` запроса; +5. 413 — `Content-Length` запроса; +6. 429 — нет места для загрузки (требование «Одновременные загрузки + реплики»); +7. тело: 413 — прочитано больше лимита; 400 — тело не пришло за срок + (требование «Срок передачи тела») или клиент оборвал передачу; +8. 415 или 413 — содержимое: формат и целостность или число пикселей. + +Тело MUST NOT читаться, пока не пройдены проверки 1–6. Загрузка, +отклонённая на проверках 1–5, MUST NOT ждать места и занимать его. +Ошибка клиента MUST NOT давать 500. + +#### Scenario: Посторонний с большим файлом + +- **WHEN** Ева загружает 30 MiB в чат Алисы и Боба +- **THEN** ответ 404 `not_found`, а не 413 + +#### Scenario: Без сессии с опасным именем + +- **WHEN** загрузка без `Authorization` идёт с `filename` `a/b.png`, а + затем с допустимым именем +- **THEN** оба ответа 401 `unauthorized` с `WWW-Authenticate: Bearer` + +#### Scenario: Неверный тип и большой размер + +- **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 + +## ADDED Requirements + +### Requirement: Одновременные загрузки реплики + +Каждый процесс API SHALL обрабатывать одновременно не больше `[uploads] +max_concurrent` загрузок (`service-configuration`, «Параметры +загрузок»): у процесса столько мест загрузки. Загрузка занимает место +после проверок 1–5 требования «Порядок проверок загрузки» и до чтения +тела. Место SHALL освобождаться при любом исходе загрузки: 201, ошибка, +обрыв клиента, истёкший срок, отмена запроса. + +Загрузка, которой места нет, SHALL ждать его в очереди процесса по +порядку прихода, но не дольше `[uploads] wait_timeout_seconds`. В +очереди SHALL быть не больше `[uploads] max_waiting` загрузок. Если +очередь полна, ответ SHALL отдаваться сразу. Если за срок ожидания +место не освободилось, ответ SHALL отдаваться по его истечении. Ответ в +обоих случаях — 429 `rate_limited` в формате ошибки с заголовком +`Retry-After` — положительным целым числом секунд. Такая загрузка MUST +NOT оставлять ни метаданных, ни объекта. Ожидающая загрузка MUST NOT +держать соединение с PostgreSQL. + +Места считает каждый процесс отдельно. Балансировщик ответ 429 на другой +реплике не повторяет (`load-balancing`), загрузку повторяет клиент после +`Retry-After`. + +Память загрузок процесса SHALL ограничиваться числом мест, а не числом +клиентов. Ожидающее или отклонённое соединение SHALL держать в памяти +процесса и в буферах его сокетов не больше 1 MiB, каким бы ни было +тело. + +#### Scenario: Загрузки в пределах лимита + +- **WHEN** 10 участников одного чата одновременно загружают по + настоящему PNG около 1 MiB, а параметры загрузок — по умолчанию +- **THEN** все ответы 201 с разными `id`, и каждое вложение скачивается + с тем же SHA-256 + +#### Scenario: Все места заняты + +- **WHEN** все места загрузки процесса заняты загрузками, тела которых + ещё идут, приходит ещё одна загрузка, и место за срок ожидания не + освобождается +- **THEN** ответ 429 `rate_limited` с `Retry-After` не меньше 1 приходит + не раньше срока ожидания, а нового вложения нет ни в PostgreSQL, ни в + bucket + +#### Scenario: Очередь ожидания полна + +- **WHEN** все места загрузки процесса заняты, и очередь ожидания полна +- **THEN** следующая загрузка сразу получает 429 `rate_limited` с + `Retry-After`, без ожидания + +#### Scenario: Ожидание места + +- **WHEN** место занято загрузкой, которая заканчивается раньше срока + ожидания, а следующая загрузка ждёт его в очереди +- **THEN** ожидавшая загрузка получает 201, и её вложение скачивается с + тем же SHA-256 + +#### Scenario: Место освобождается + +- **WHEN** загрузка на единственном месте процесса заканчивается 413 по + счётчику, 415 по содержимому, 400 по сроку тела, обрывом клиента или + 503 при остановленном S3 +- **THEN** после каждой такой загрузки следующая получает место сразу: + ответ 201 без ожидания (после 503 — когда S3 вернулся) + +#### Scenario: Память не растёт с числом загрузок + +- **WHEN** 10, 20 и 40 клиентов одновременно и без пауз загружают по + 10 MiB в одну реплику с параметрами по умолчанию (профиль загрузок + стенда `bench/`, вариант «с лимитом») +- **THEN** пик памяти реплики в каждом случае не больше половины лимита + контейнера, при 20 и 40 клиентах он выше, чем при 10, не больше чем на + 1 MiB на каждого клиента сверх 10, реплика не завершена из-за памяти, + лишние загрузки получают 429, а ответов 5xx нет + +### Requirement: Срок передачи тела + +Тело загрузки SHALL приходить целиком не позже `[uploads] +body_timeout_seconds` после того, как загрузка заняла место. Иначе +ответ SHALL быть 400 `invalid_request` в формате ошибки. Загрузка при +этом MUST NOT оставлять ни метаданных, ни объекта, и её место +освобождается. Тело, которое пришло в срок, SHALL приниматься, как бы +мелко его ни делил клиент и какие бы паузы ни делал. + +#### Scenario: Медленный клиент + +- **WHEN** участник шлёт настоящий PNG частями так, что тело идёт + дольше срока передачи +- **THEN** ответ 400 `invalid_request`, нового вложения нет ни в + PostgreSQL, ни в bucket, а следующая загрузка — 201 без ожидания места + +#### Scenario: Медленная передача в срок + +- **WHEN** участник шлёт настоящий PNG мелкими частями с паузами и + укладывается в срок передачи +- **THEN** ответ 201, а `size_bytes` и `sha256` совпадают с файлом diff --git a/openspec/changes/upload-memory/specs/load-balancing/spec.md b/openspec/changes/upload-memory/specs/load-balancing/spec.md new file mode 100644 index 00000000..15cd080d --- /dev/null +++ b/openspec/changes/upload-memory/specs/load-balancing/spec.md @@ -0,0 +1,124 @@ +## MODIFIED Requirements + +### Requirement: Ошибки балансировщика в формате контракта + +Ответы, которые создаёт сам 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: Нет готовых реплик + +- **WHEN** все реплики API остановлены, и клиент запрашивает + `/health/ready` через 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: Вывод реплики из балансировщика перед остановкой + +Перед плановой остановкой реплики LB SHALL перестать направлять ей +новые запросы. Запросы, которые она уже обрабатывает, SHALL +дорабатываться. Остановка SHALL начинаться после того, как запросов в +полёте у неё не осталось, или по истечении срока ожидания. Срок SHALL +быть больше `timeout server` LB и больше наибольшей длительности живой +загрузки (требование «Загрузки через балансировщик»). Управление LB +SHALL быть доступно только изнутри контейнера LB. Из сети compose и с +хоста оно MUST NOT быть доступно. + +Состояние слота, выставленное при замене, SHALL сниматься, когда адрес +удалённой реплики ушёл из слота. Слот, который потом получит новая +реплика, SHALL включаться по обычным проверкам готовности. + +#### Scenario: Выведенная реплика не получает запросов + +- **WHEN** слот реплики переведён в дренаж, и через LB идут запросы +- **THEN** все новые ответы приходят от других реплик, а запросы, + начатые до дренажа, получают ответ + +#### Scenario: Управление LB недоступно из сети + +- **WHEN** контейнер в сети стенда или процесс на хосте обращается к + портам LB +- **THEN** изменить состояние реплики он не может: канал управления LB + слушает только loopback внутри контейнера LB + +#### Scenario: Слот после замены + +- **WHEN** замена завершена +- **THEN** в статистике LB нет слотов в дренаже или в обслуживании, + выставленном вручную; свободные слоты — только в обслуживании по DNS + +#### Scenario: Загрузка во время дренажа + +- **WHEN** через LB идёт загрузка вложения, тело которой передаётся + дольше 12 с, и во время неё `make rolling_update` выводит реплику, + которая её принимает +- **THEN** загрузка получает 201 от этой реплики, и только после ответа + реплика останавливается + +## ADDED Requirements + +### Requirement: Загрузки через балансировщик + +Для `POST /api/v1/chats/{chat_id}/attachments` срок, в который LB ждёт +реплику (`timeout server`), SHALL быть 30 с. Это больше самого длинного +молчания живой загрузки: +- до чтения тела — вход, членство в чате и ожидание места загрузки, не + дольше `2 × [database] request_timeout_seconds + [uploads] + wait_timeout_seconds` (17 с); +- после тела — проверка изображения, запись метаданных, запись объекта, + перевод в `ready` и удаление объекта при компенсации, не дольше `2 × + request_timeout_seconds + 2 × [s3] timeout_seconds` плюс проверка + изображения (около 26 с). + +У остальных путей срок SHALL оставаться прежним, 10 с: цепочка +таймаутов лабы 3 для них не меняется. + +Наибольшая длительность живой загрузки — молчание до тела, срок +передачи тела (`[uploads] body_timeout_seconds`) и молчание после тела, +около 73 с при значениях по умолчанию. Она и формула SHALL быть в +`REPORT.md`. + +Соединение с недочитанным телом SHALL держать в буферах ядра ограниченный +объём: буфер приёма сокетов реплики API — не больше 512 KiB, буфер +отправки LB к реплике — 256 KiB. Так ожидающие и отклонённые загрузки не +переносят тела целиком ни в память реплики, ни в память LB. + +#### Scenario: Долгая обработка загрузки + +- **WHEN** реплика на пути загрузки молчит дольше 10 с, но меньше 30 с: + до чтения тела или после него +- **THEN** клиент получает ответ реплики, а не 502 или 504 от LB + +#### Scenario: Прежний срок остальных путей + +- **WHEN** реплика молчит дольше 10 с на любом другом пути +- **THEN** через ~10 с клиент получает 504 от LB в формате ошибки + контракта + +#### Scenario: Загрузка дольше срока LB + +- **WHEN** реплика на пути загрузки молчит дольше 30 с +- **THEN** через ~30 с клиент получает 504 от LB в формате ошибки + контракта + +#### Scenario: Буферы соединений ограничены + +- **WHEN** 40 клиентов одновременно загружают по 10 MiB через LB в одну + реплику с параметрами загрузок по умолчанию +- **THEN** пик памяти LB и буферов сокетов реплики растёт не больше чем + на 1 MiB на клиента, а реплика и LB не завершены из-за памяти diff --git a/openspec/changes/upload-memory/specs/load-benchmark/spec.md b/openspec/changes/upload-memory/specs/load-benchmark/spec.md new file mode 100644 index 00000000..32e023be --- /dev/null +++ b/openspec/changes/upload-memory/specs/load-benchmark/spec.md @@ -0,0 +1,212 @@ +## MODIFIED Requirements + +### Requirement: Фиксированный стенд + +Стенд SHALL состоять из балансировщика (LB), реплик приложения, +PostgreSQL и Valkey. В профиле загрузок к ним SHALL добавляться S3 с +его bootstrap. Число реплик SHALL задаваться методикой, по умолчанию +одна. Приложение SHALL запускаться в контейнерах из образа, собранного +из текущего checkout тем же `Dockerfile`. Исключения — профиль +поочерёдной замены и вариант «до» профиля загрузок. Они берут образ +commit, заданного методикой: образ собирается тем же `Dockerfile` из +файлов этого commit без изменения рабочего дерева. Профиль замены +заканчивается на образе текущего checkout. LB SHALL +запускаться из того же образа и с той же конфигурацией, что у рабочего +стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у +рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL +получает те же настройки образа плюс модуль записи планов, выключенный +вне снятия плана. S3 SHALL запускаться из того же образа и с теми же +аргументами сервера, что у рабочего стенда, а bucket и пользователей +создаёт тот же bootstrap. В сериях трека 1 предел соединений PostgreSQL +(`max_connections`) — параметр конфигурации серии, по умолчанию 100, как +у образа. Схема БД SHALL применяться миграциями до наполнения. + +Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека +1 — во всех прогонах одной конфигурации: +- у каждой реплики приложения — лимит CPU и памяти без swap, заданный + методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по + конфигурации); +- у LB, PostgreSQL, Valkey и S3 — свои лимиты CPU и памяти без swap, + заданные методикой; в серии трека 1 они одинаковы во всех + конфигурациях; +- у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без + swap, заданный методикой; в остальных профилях генератор без лимита. + +Буфер приёма сокетов реплик приложения SHALL быть ограничен так же, как +у рабочего стенда (`load-balancing`, «Загрузки через балансировщик»). +Значение SHALL записываться в паспорт. + +Healthcheck образа приложения SHALL быть отключён: готовность реплик +проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки +приложения и хранилищ SHALL браться из методики стенда, а не из `.env` +и `config.toml` рабочего стенда. Пароли хранилищ и секреты S3 SHALL +генерироваться на прогон. Генератор нагрузки SHALL работать в той же +docker-сети и обращаться к приложению через LB по имени сервиса, минуя +проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит +готовыми все реплики. + +#### Scenario: Лимиты в паспорте + +- **WHEN** прогон завершён +- **THEN** паспорт стенда содержит число реплик и лимиты CPU и памяти + реплики приложения, LB, PostgreSQL и Valkey, прочитанные у запущенных + контейнеров, и они одинаковы для всех размеров + +#### Scenario: Лимиты конфигурации серии + +- **WHEN** серия трека 1 завершена +- **THEN** паспорт по каждой конфигурации содержит число реплик, лимиты + CPU и памяти каждого контейнера стенда и генератора и предел + соединений PostgreSQL, прочитанные у запущенных контейнеров, и они + одинаковы во всех повторах конфигурации + +#### Scenario: Нехватка памяти + +- **WHEN** процесс приложения превысил лимит памяти и был убит +- **THEN** прогон помечен как проваленный из-за OOM, а не записан как + обычный результат + +#### Scenario: Настройки рабочего стенда не влияют + +- **WHEN** `.env` и `config.toml` рабочего стенда изменены или + отсутствуют +- **THEN** стенд запускается с теми же настройками приложения и + хранилищ, а окружение приложения в паспорте то же + +#### Scenario: Схема до наполнения + +- **WHEN** начинается наполнение размера +- **THEN** миграции применены до последней ревизии, и приложение + отвечает готовностью + +#### Scenario: Одна реплика за балансировщиком + +- **WHEN** профиль лабы 2 (`full`, `quick`, `restore`, + `restore_quick`) запущен с одной репликой +- **THEN** все запросы генератора проходят через LB, прогон завершается + с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и + разделы, что раньше + +#### Scenario: Образ прежнего commit + +- **WHEN** запускается профиль поочерёдной замены +- **THEN** реплики стартуют на образе commit из методики, схема — на + его последней ревизии, рабочее дерево не меняется, а commit и образы + до и после записаны в паспорт + +#### Scenario: S3 в профиле загрузок + +- **WHEN** запускается профиль загрузок +- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами + и лимитами, bootstrap завершился успешно, а образ и лимиты S3 и + ограничение буфера приёма реплики записаны в паспорт + +## ADDED Requirements + +### Requirement: Профиль загрузок + +Команда `make bench_uploads` (метка `UPLOADS_LABEL`, по умолчанию +`baseline`) SHALL на свежем стенде мерить память реплики при +одновременных загрузках вложений. Команда `make bench_uploads_quick` — +то же короче, метка `quick-uploads-…`, в git не идёт. Результаты SHALL +сохраняться в `evidence/uploads/<метка>/`. Занятая метка SHALL давать +отказ до запуска стенда. + +Стенд — LB и одна реплика с лимитами рабочего стенда (1 CPU, 512 МБ без +swap), PostgreSQL, Valkey и S3 с лимитами рабочего стенда. + +Варианты кода: +- «до» — образ commit из методики, последнего до change `upload-memory`; +- «без лимита» — образ текущего checkout, мест загрузки больше, чем + клиентов, очереди нет; +- «с лимитом» — образ текущего checkout с параметрами загрузок по + умолчанию. + +Тела — настоящие PNG около 1 MiB и около 10 MiB, не больше лимита +контракта. Их строит оркестратор, детерминированно от зерна методики. + +Прогон — вариант × размер × число одновременных клиентов (1, 10, 20 и +40) × повтор. Повторов в полном профиле три. Каждый прогон SHALL идти на +новом контейнере реплики и новом volume S3. Клиенты загружают без пауз +окно, заданное методикой. На 429 клиент ждёт `Retry-After`, на прочие +ошибки — секунду. + +Для каждого прогона SHALL сохраняться: +- пик памяти реплики за окно — пик cgroup, сброшенный в начале окна, — + и память перед окном; +- наибольшие анонимная память и память буферов сокетов реплики; +- было ли завершение реплики из-за памяти; +- ответы по кодам, ошибка соединения — отдельным кодом; +- успешных загрузок в секунду, p50, p95 и p99 успешных; +- пик памяти S3 (в том числе анонимной) и LB. + +Прогон с завершением реплики из-за памяти SHALL помечаться `oom` и +записываться как результат варианта, а не как сбой команды. Следующий +прогон идёт на новой реплике. + +Граница чёрного ящика: генератор обращается к приложению только по HTTP +через LB, оркестратор управляет стендом через docker CLI. Сверх этого он +читает счётчики памяти cgroup контейнеров и пересоздаёт volume S3 с +bootstrap между прогонами. К bucket и объектам он не обращается. + +В паспорте метки SHALL быть: +- лимиты и образы, в том числе commit варианта «до»; +- окружение приложения каждого варианта без секретов; +- размеры и SHA-256 тел; +- версия ядра ВМ; +- ограничение буфера приёма сокетов реплики; +- состояние хоста. + +#### Scenario: Полный профиль + +- **WHEN** выполнен `make bench_uploads` +- **THEN** в `evidence/uploads/<метка>/` есть паспорт, таблица прогонов + (три варианта × два размера × четыре уровня × три повтора), сводка по + ячейкам с медианой и разбросом повторов и сырые итоги генератора, код + выхода 0 + +#### Scenario: Быстрый профиль + +- **WHEN** выполнен `make bench_uploads_quick` +- **THEN** за несколько минут проходят варианты «без лимита» и «с + лимитом» на 10 MiB при 1, 10 и 40 клиентах, по одному повтору, код + выхода 0, каталог метки в git не попадает + +#### Scenario: Реплика убита из-за памяти + +- **WHEN** в прогоне реплику завершило ядро из-за памяти +- **THEN** прогон помечен `oom`, в таблице есть ответы по кодам до и + после завершения, следующий прогон идёт на новой реплике, а команда + не прерывается + +#### Scenario: Пик окна без памяти старта + +- **WHEN** реплика при старте заняла больше памяти, чем в окне прогона +- **THEN** пик прогона отражает только окно, а не старт процесса + +### Requirement: Загрузки в отчёте + +`REPORT.md` SHALL содержать по профилю загрузок: +- гипотезы о пике памяти с лимитом и без него, о пропускной способности + и о сроке записи в S3. Они записаны и зафиксированы commit до первого + прогона метки; +- методику: стенд, лимиты, варианты, тела, уровни, окно, повторы; +- таблицу результатов по меткам: пик памяти, завершения из-за памяти, + ответы по кодам, загрузок в секунду и p95 — по вариантам, размерам и + уровням; +- выводы по каждой гипотезе и ограничения: один хост, ВМ Docker Desktop, + генератор на том же хосте, одна нода S3. + +Числа в отчёт SHALL переноситься из сводки метки, а не пересчитываться +вручную. + +#### Scenario: Гипотезы до прогонов + +- **WHEN** проверяющий смотрит историю `REPORT.md` и каталога метки +- **THEN** commit с гипотезами раньше commit с результатами метки + +#### Scenario: Выводы по метке + +- **WHEN** проверяющий открывает раздел загрузок в `REPORT.md` +- **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки + метки, а числа совпадают со сводкой diff --git a/openspec/changes/upload-memory/specs/service-configuration/spec.md b/openspec/changes/upload-memory/specs/service-configuration/spec.md new file mode 100644 index 00000000..95965a44 --- /dev/null +++ b/openspec/changes/upload-memory/specs/service-configuration/spec.md @@ -0,0 +1,49 @@ +## ADDED Requirements + +### Requirement: Параметры загрузок + +Ограничения загрузок вложений процесса API (capability `attachments`, +«Одновременные загрузки реплики», «Срок передачи тела») SHALL +задаваться в секции `[uploads]`: +- `max_concurrent` — сколько загрузок процесс обрабатывает одновременно, + по умолчанию 4; +- `max_waiting` — сколько загрузок может ждать места, по умолчанию 16; + 0 — без ожидания, загрузка без места сразу получает 429; +- `wait_timeout_seconds` — сколько секунд загрузка ждёт места, по + умолчанию 5; +- `body_timeout_seconds` — за сколько секунд после того, как загрузка + заняла место, должно прийти её тело, по умолчанию 30. + +`max_concurrent` SHALL быть целым не меньше 1, `max_waiting` — целым не +меньше 0, сроки — положительными числами. Иначе сервис MUST NOT +стартовать (требование «Некорректное значение останавливает запуск»). +Значения SHALL одинаково действовать в консоли и в docker. Разовая +подмена SHALL работать через окружение `UPLOADS__*` без правки файлов. +Запись журнала о старте API SHALL называть все четыре значения. + +Значения по умолчанию и их обоснование SHALL быть описаны в `REPORT.md`: +- бюджет памяти реплики: интерпретатор, хэши паролей и места загрузок в + лимите контейнера; +- сроки пути загрузки в балансировщике (`load-balancing`, «Загрузки + через балансировщик»). + +#### Scenario: Параметры загрузок по умолчанию + +- **WHEN** сервис запущен без секции `[uploads]` и без переменных + `UPLOADS__*` +- **THEN** запись журнала о старте называет 4 места, 16 ожидающих, + ожидание 5 с и срок тела 30 с + +#### Scenario: Подмена параметров загрузок окружением + +- **WHEN** сервис запущен с `UPLOADS__MAX_CONCURRENT=1` и + `UPLOADS__MAX_WAITING=0`, а файлы не менялись +- **THEN** вторая одновременная загрузка, пока первая не закончилась, + сразу получает 429 + +#### Scenario: Неверный параметр загрузок + +- **WHEN** сервис запускается с `UPLOADS__MAX_CONCURRENT=0`, + `UPLOADS__MAX_WAITING=-1` или `UPLOADS__BODY_TIMEOUT_SECONDS=abc` +- **THEN** сервис не стартует, в журнале — ошибка проверки настроек с + именем поля diff --git a/openspec/changes/upload-memory/specs/storage-consistency/spec.md b/openspec/changes/upload-memory/specs/storage-consistency/spec.md new file mode 100644 index 00000000..829e55da --- /dev/null +++ b/openspec/changes/upload-memory/specs/storage-consistency/spec.md @@ -0,0 +1,74 @@ +## MODIFIED Requirements + +### Requirement: Безопасность уборки + +Уборщик MUST NOT трогать готовые вложения (`ready`) ни в каком возрасте. +Незавершённую загрузку моложе grace он тоже MUST NOT трогать. + +Grace SHALL быть больше наибольшего времени, за которое живая загрузка +проходит путь от записи метаданных до фиксации `ready`. Это два шага с +PostgreSQL и запись объекта, у каждого свой срок (capability +`service-configuration`, «Параметры уборщика»). Возраст загрузки +отсчитывается от записи её метаданных по часам приложения. Ожидание +места загрузки, чтение тела и проверка изображения (capability +`attachments`, «Одновременные загрузки реплики», «Срок передачи тела») +SHALL идти до записи метаданных и в эту границу не входят: очередь +загрузок и медленный клиент её не удлиняют. + +Загрузка, которая длится дольше grace (процесс API заморожен), и +уборщик SHALL исключать друг друга на одном вложении. Исходов два: +- вложение стало `ready` вместе с объектом, и уборщик его не трогает; +- уборщик начал его уборку, а загрузка отвечает 503 `unavailable` и + удаляет записанный ею объект. + +До удаления объекта уборщик SHALL помечать метаданные вложения как +убираемые и фиксировать пометку отдельно. Помеченное вложение MUST NOT +становиться `ready`. Поэтому сбой уборки после удаления объекта не даёт +вложения `ready` без объекта: загрузка отвечает 503, а уборку доводит +следующий проход. Сбой — например, не удалось удалить метаданные, или +S3 выполнил удаление уже после срока вызова. Вложение `ready` без +объекта MUST NOT появляться ни при каком порядке этих действий. + +Ограничение называется в `REPORT.md`. Пока идёт поочерёдная замена +реплик API, реплики прежней версии пометку не проверяют. Для их +загрузок, переживших grace, это свойство не гарантировано. + +#### Scenario: Загрузка дольше grace + +- **WHEN** загрузка записала объект, а к переводу в `ready` её + метаданным уже больше grace, и уборщик убирает их, пока загрузка ждёт + перевода +- **THEN** ответ 503 `unavailable`, а не 201 и не 500, нет ни + метаданных, ни объекта этого вложения, а в bucket нет объектов + вложений без метаданных + +#### Scenario: Сбой уборки после удаления объекта + +- **WHEN** загрузка ждёт перевода в `ready`, её метаданным больше grace, + а уборщик удалил её объект, но удалить метаданные не смог: PostgreSQL + отказал +- **THEN** ответ загрузки 503 `unavailable`, а не 201, метаданные в + статусе «загружается», и вложения `ready` без объекта нет +- **AND** когда удаление метаданных снова проходит, уборщик доводит + уборку, и в bucket нет объектов вложений без метаданных + +#### Scenario: Свежая загрузка не тронута + +- **WHEN** незавершённой загрузке меньше grace, а уборщик за это время + сделал несколько проходов +- **THEN** её метаданные в статусе «загружается» на месте, и убираются + они только после истечения grace + +#### Scenario: Готовые вложения не тронуты + +- **WHEN** готовому вложению больше grace, и уборщик всё это время + работал, в том числе убирал незавершённые загрузки +- **THEN** метаданные вложения — 200 в статусе `ready`, а байты + скачиваются с тем же SHA-256 + +#### Scenario: Ожидание места не входит в возраст загрузки + +- **WHEN** загрузка ждала места, пока его держала другая загрузка того + же процесса, и обе завершились 201 +- **THEN** время записи метаданных ожидавшей (`created_at`) позже + перевода в `ready` той, что держала место (`updated_at`) diff --git a/openspec/changes/upload-memory/specs/student-tests/spec.md b/openspec/changes/upload-memory/specs/student-tests/spec.md new file mode 100644 index 00000000..82102fef --- /dev/null +++ b/openspec/changes/upload-memory/specs/student-tests/spec.md @@ -0,0 +1,85 @@ +## MODIFIED Requirements + +### Requirement: Проверки отказов на отдельном стенде + +Сценарии отказов SHALL проверяться автоматически одной командой +`make failure_checks`: +- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при + запросе с токеном»; +- `data-storage`: «Сбой при добавлении участников», «БД остановлена», + «БД вернулась», «Соединения исчерпаны»; +- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище + объектов недоступно»; +- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся», + «Очистка кэша»; +- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке», + «Ключ после срока»; +- `api-conventions`: «Лимит одновременных загрузок»; +- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего + не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не + видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв + передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь + ожидания полна», «Ожидание места», «Место освобождается», «Медленный + клиент», «Медленная передача в срок»; +- `storage-consistency`: все сценарии. + +Команда SHALL: +- собрать образ из рабочего дерева; +- поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить + миграции и bootstrap S3; +- запустить три API: + - с настройками по умолчанию; + - «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом + из одного соединения; + - «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в + очереди, коротким сроком ожидания места и коротким сроком тела. Их + значения SHALL передаваться проверкам; +- запустить уборщика с коротким grace и интервалом, сравнимыми со + временем теста, и передать их значения проверкам. Grace при этом + SHALL проходить проверку границы живой загрузки (`service- + configuration`, «Параметры уборщика»); +- выполнить проверки отказов; +- удалить стенд вместе с его данными при любом исходе. + +Hook стенда отказов SHALL уметь: +- сообщить вложения стенда в PostgreSQL с их статусами и `id` + последнего вложения в статусе «загружается»; +- сообщить, у каких вложений есть объект в bucket стенда, — по самим + объектам, а не по каталогам хранилища; +- внедрить отказ PostgreSQL при записи метаданных и при фиксации + `ready` загрузки с заданным `filename` и задержать такую фиксацию; +- убить и снова запустить обычный API стенда. + +Других сведений о хранилищах проверки вложений не получают. Объекты без +метаданных проверка находит сравнением этих двух списков. + +Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на +хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш, +хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода +SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка. +Параллельный запуск двух прогонов не поддерживается: уборка хвоста в +начале второго удаляет стенд первого. + +#### Scenario: Успешный прогон + +- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks` +- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и + volumes стенда отказов после команды нет, а у контейнеров рабочего + стенда прежнее время старта, и рабочий API отвечает + +#### Scenario: Упавшая проверка + +- **WHEN** во время `make failure_checks` падает хотя бы одна проверка +- **THEN** код выхода ненулевой, журналы API и уборщика стенда отказов + выведены, стенд отказов удалён + +#### Scenario: Прерывание + +- **WHEN** `make failure_checks` прерван Ctrl+C +- **THEN** стенд отказов остановлен и удалён вместе с volumes + +#### Scenario: Хвост прошлого прогона + +- **WHEN** контейнеры или volumes стенда отказов остались от прогона, + убитого без уборки +- **THEN** следующий `make failure_checks` удаляет их и начинает заново diff --git a/openspec/changes/upload-memory/tasks.md b/openspec/changes/upload-memory/tasks.md new file mode 100644 index 00000000..8a994df8 --- /dev/null +++ b/openspec/changes/upload-memory/tasks.md @@ -0,0 +1,313 @@ +# Tasks + +Порядок — design, Migration Plan; тесты пишутся раньше кода, чтобы снять +красный прогон без checkout и stash. Значения и формулы — design, +решения 7 и 9; методика профиля — решение 10; тесты — решение 11. Commit +делает основная сессия после подтверждения пользователя (`bench.md`, +«Измеренное состояние — commit»). Замеры и evidence — только с +закоммиченного кода. + +## 1. Тесты и красный прогон + +- [ ] 1.1 `student-tests/contract.py`: `assert_error(resp, 429)` — `code` + `rate_limited` и `Retry-After` — положительное целое. Проверка — + тесты 1.4. +- [ ] 1.2 `test_attachments.py::test_concurrent_uploads` (спек + `attachments`, «Загрузки в пределах лимита»). 10 потоков за + `threading.Barrier`, у каждого свой `Api`, PNG ~1 MiB из `images.py`: + все 201, `id` разные, каждое скачивается с тем же SHA-256. Проверка — + `make test_isolated` и `make student_test` через LB (группа 10). +- [ ] 1.3 `run_failures.py`: третий API `<проект>-api-uploads` с + `UPLOADS_ENV`: + - `UPLOADS__MAX_CONCURRENT=1`, `UPLOADS__MAX_WAITING=1`; + - `UPLOADS__WAIT_TIMEOUT_SECONDS=1`, + `UPLOADS__BODY_TIMEOUT_SECONDS=2`. + + Тестам — `FAULT_UPLOADS_BASE_URL` и `FAULT_UPLOADS_ENV`; журнал этого + API при падении; уборка. Фикстура `uploads_api` в `conftest.py`. + Проверка: `make failure_checks FAULT_ARGS='-k uploads'` поднимает три + API и убирает стенд. +- [ ] 1.4 `test_failures.py` (маркер `fault`, `spec` по таблице решения + 11): `test_upload_slots_busy`, `test_rejections_before_queue`, + `test_upload_waits_for_slot`, `test_slot_released_after_failures`, + `test_slow_body`. Место держит загрузка с генератором тела на + `threading.Event`. Клиент с ожиданием — со сроком 30 с, сроки стенда — + из `FAULT_UPLOADS_ENV` (тест сверяет, что стенд запущен с ними). Новые + `id` проверяются списками hook (`attachment-ids`, `object-ids`). +- [ ] 1.5 Красный прогон на коде до групп 2–4: `make failure_checks + FAULT_ARGS='-k "slot or queue or slow_body"'`. Старый API не знает + `[uploads]`, поэтому ожидаемо падают `test_upload_slots_busy`, + `test_upload_waits_for_slot` и `test_slow_body`. + `test_slot_released_after_failures` и `test_rejections_before_queue` + на коде без мест зелёные: они ловят утечку места и ожидание ранних + отказов в очереди. Вывод и число упавших — в `evidence/tests/` (раздел + красного прогона `failure-checks.md`) и в tasks при прогоне. + +## 2. Константы, исключения, настройки + +- [ ] 2.1 `src/utils/constants.py`: `UPLOAD_RETRY_AFTER_SECONDS = 1` + с комментарием (design, решение 2). Проверка: `make lint`. +- [ ] 2.2 `src/core/exceptions/attachment.py`: + - `UploadsBusy` — «Too many uploads in progress, retry later»; + - `UploadTimedOut` — «Upload body was not received in time». + + Реэкспорт в `__init__.py`. Проверка: `uv run python -c "from + src.core.exceptions import UploadsBusy, UploadTimedOut"`. +- [ ] 2.3 `src/api/errors.py`: `UploadsBusy` → 429 + `ErrorCode.RATE_LIMITED` с заголовком `Retry-After` из константы (рядом + с `CHALLENGES`), `UploadTimedOut` → 400 `invalid_request`. Проверка — + тесты 1.4. +- [ ] 2.4 Секция `[uploads]` — класс `Uploads` в + `src/config/settings.py`: + - `max_concurrent` (int, `ge=1`, 4); + - `max_waiting` (int, `ge=0`, 16); + - `wait_timeout_seconds` (float, `gt=0`, 5); + - `body_timeout_seconds` (float, `gt=0`, 30). + + Поле `uploads` в `Settings`, строки с комментариями в + `config_example.toml` (`settings.md`, «Новое поле или секция»). + Проверка: + - `uv run python -c "from src.config import settings; + print(settings.uploads.max_concurrent)"` — 4; + - с `UPLOADS__MAX_CONCURRENT=0`, `UPLOADS__MAX_WAITING=-1` и + `UPLOADS__BODY_TIMEOUT_SECONDS=abc` — ошибка с именем поля. + +## 3. Места загрузки и срок тела + +- [ ] 3.1 `src/infra/upload_slots.py`: класс `UploadSlots` и глобал + `upload_slots` из `settings.uploads` (design, решение 1). Контекст + `slot()`: + - места нет и ожидающих уже `max_waiting` — сразу `UploadsBusy`; + - иначе ожидание по порядку прихода не дольше + `wait_timeout_seconds`, истекло — `UploadsBusy`; + - контекст отдаёт ожидание в мс; + - место освобождается в `finally`, в том числе при `CancelledError`; + отмена во время ожидания не уменьшает число мест. + + Проверка — разовый скрипт в scratchpad на asyncio: 1 место, 1 + ожидающий. Третий — сразу `UploadsBusy`, второй — через срок. После + отмены ожидающей задачи и после исключения внутри контекста место + снова свободно. +- [ ] 3.2 `src/api/dependencies.py`: `AttachmentService(db_scope=…, + cache=…, storage=…, slots=upload_slots)`. Глобал импортирует только + `dependencies.py` (`infra.md`). Проверка: `grep -rn upload_slots src` — + только `infra/upload_slots.py`, `dependencies.py` и тип в сервисе. +- [ ] 3.3 `AttachmentService.upload` (`src/core/services/attachment.py`; + design, решения 3 и 4): + - после проверок членства, `Content-Type` и `Content-Length` — `async + with self.slots.slot()`, внутри — остальной путь до ответа; + - `_read_body` под `asyncio.timeout(body_timeout_seconds)`, истёк — + `UploadTimedOut` и `info` «Rejected attachment» + (`reason=body_timeout`); + - `UploadsBusy` — `info` «Rejected attachment» (`reason=busy`, + `waited_ms`); + - «Uploaded attachment» — с `waited_ms`; + - докстринги — новый порядок. + + Проверка — тесты 1.4 зелёные (группа 10). +- [ ] 3.4 `src/main.py`: запись «Started API» с + `uploads_max_concurrent`, `uploads_max_waiting`, + `uploads_wait_timeout_seconds`, `uploads_body_timeout_seconds`. + Проверка: `make run_dev` — запись с 4, 16, 5, 30 (спек + `service-configuration`, «Параметры загрузок по умолчанию»). + +## 4. Одна копия тела при PUT + +- [ ] 4.1 `_read_body` возвращает `BytesIO`. Сервис: + - `data = buffer.getvalue()`; + - проверка изображения и SHA-256 над `data`; + - `size = len(data)`, `del data`; + - `buffer.seek(0)`, PUT этим буфером. + + Комментарий — почему `del` (design, решение 5, Context п. 1). +- [ ] 4.2 `ObjectStorage.put(key, body, *, size, content_type)` + (`src/infra/s3/client.py`) и `put_original(storage, *, key, body, size, + content_type)` (`src/core/repos/attachment_object.py`): тело — поток с + `read`, `seek`, `tell`; `size` — в журнал вызова. Проверка: + - скрипт в scratchpad в образе API против S3 стенда: `VmHWM` шага PUT + ≤ 1,3 тела (было 2,0); + - SHA-256 сохранённого объекта совпал; + - `make test` и тесты вложений зелёные. + +## 5. Стенд и LB + +- [ ] 5.1 `docker-compose.yml`, сервис `api`: `sysctls: + net.ipv4.tcp_rmem: "4096 131072 524288"` с комментарием (design, + решение 6). Проверка: `docker compose exec api cat + /proc/sys/net/ipv4/tcp_rmem` на каждой реплике; то же в контейнере + `make test_isolated` и стенда отказов. +- [ ] 5.2 `infra/haproxy/haproxy.cfg`: + - `global` — `tune.sndbuf.server 262144`; + - `defaults` — `http-error status 400` с `"code":"invalid_request"`, + `request_id` `%[unique-id]` и заголовком `X-Request-Id`; + - `backend api` — `http-request set-timeout server 30s if METH_POST { + path_reg ^/api/v1/chats/[^/]+/attachments$ }` с формулой решения 7 в + комментарии. + + Проверка: `haproxy -c` в закреплённом образе с `API_PORT`; `make + run_docker`, `make instances`, `make test`. +- [ ] 5.3 `scripts/rolling-update.sh`: `ROLLOUT_DRAIN_TIMEOUT` по + умолчанию 90 с, комментарий: «больше `timeout server` пути загрузки и + наибольшей длительности загрузки». Проверка: `make rolling_update` на + рабочем стенде — код 0, дренаж каждой реплики — секунды. +- [ ] 5.4 `KNOWN_ISSUES.md`: запись «LB отвечает 408 на медленные + заголовки текстом HAProxy»: + - где и что, проба — design, Context п. 4; + - предложение и почему `errorfile` со статичным `request_id` не + годится: контракт требует id из `X-Request-Id`. + + Проверка: запись есть. + +## 6. Спеки и сверка покрытия + +- [ ] 6.1 Sync дельт в основные спеки (`/opsx:sync` или вручную, как в + `attachments` и `upload-consistency`): сверка покрытия видит новые + сценарии. Проверка: `openspec validate upload-memory --strict`, в + `openspec/specs/attachments/spec.md` есть «Одновременные загрузки + реплики». +- [ ] 6.2 `spec_coverage.py`, `EXCLUDED`: `attachments` «Одна копия тела + при записи в S3» и «Память не растёт с числом загрузок». Способ — + `make bench_uploads` → `evidence/uploads/<метка>/summary.md`. Проверка: + `test_coverage.py` зелёный. До commit метки + `test_exclusion_evidence_exists` ожидаемо красный и называет оба + сценария — записать это в tasks при прогоне. + +## 7. Драйвер скилла + +- [ ] 7.1 `driver.py lb-upload-timeouts` (stdlib, Python 3.9; design, + решение 7): + - временная сеть, HAProxy закреплённого образа с + `infra/haproxy/haproxy.cfg` и `API_PORT`; + - заглушка на образе API под именем `api`: `/health/ready` — 200, + остальное — задержки по пути; + - случаи: молчание 12 с на пути загрузки до тела и после тела — 201; + 12 с на `GET /api/v1/users/me` — 504 через ~10 с; 32 с на пути + загрузки — 504 через ~30 с; клиент молчит посреди тела 35 с — 400 в + формате контракта, `request_id` = `X-Request-Id`; + - уборка сети и контейнеров при любом исходе, код 1 при расхождении. + + `SKILL.md` — строка команды. Проверка: команда — код 0 на текущем + `haproxy.cfg` и код 1 на `haproxy.cfg` `f894040` (`git show + f894040:infra/haproxy/haproxy.cfg` во временный файл, аргумент + `--config`). + +## 8. Профиль `uploads` стенда `bench/` + +- [ ] 8.1 `bench/run.py`: профили `uploads` и `uploads_quick` (поля + `Profile`, design, решение 10): + - стенд с S3 и bootstrap, лимиты рабочего стенда, реплика без swap; + - варианты «до» (`uploads_before = "f894040"`, сборка как у + `rollout_from`, проверка commit до стенда), «без лимита» и «с + лимитом» с окружением в паспорте; + - круги прогонов с перестановкой по зерну; + - перед прогоном — новый volume S3 с bootstrap и новая реплика, + ожидание `UP`, разогрев; + - пометки `oom`, `host_swap`; блокировка `bench/.bench.lock`; + - отказ занятой метки и остатков стенда. + + Проверка: отказ на занятой метке и на commit вне истории (код 2). +- [ ] 8.2 Тела PNG ~1 MiB и ~10 MiB из шума (`random.Random(seed)`, + stdlib), размеры и SHA-256 в паспорте. Проверка: + - `--selftest`: размер ≤ 10 485 760, два запуска дают одни байты; + - разовая проверка в образе API: тела принимает `inspect_image` (сам + `bench/` `src` не импортирует). +- [ ] 8.3 `bench/k6/uploads.js`: `constant-vus`, разгон и окно, тело из + смонтированного файла, Bearer из `lib.js`; на 429 — пауза + `Retry-After`, на прочие ошибки — 1 с; строка на запрос в файл + консоли. Проверка: число строк = итерации из итога k6, как в + `failover`. +- [ ] 8.4 `bench/sampler.sh`, режим `peak`: + - сброс `memory.peak` реплики, S3 и LB через свой дескриптор (perl) в + начале окна и чтение в конце; + - выборка `memory.current`, `anon`, `sock`, `oom_kill` раз в 0,2 с; + - контейнер — `--user 0`, cgroupfs на запись, без сети; + - ядро без сброса — наибольшая выборка и `peak_sampled` в паспорте. + + Проверка: на `uploads_quick` пик окна при C = 1 ниже пика старта + реплики. +- [ ] 8.5 Результаты `evidence/uploads/<метка>/`: `meta.json`, `runs.csv` + (столбцы решения 10), `summary.md` (медиана и разброс по ячейкам, + строки гипотез H1–H4), `raw/`. `quick-uploads-*` — в `.gitignore`. + `Makefile`: `bench_uploads` (`UPLOADS_LABEL ?= baseline`) и + `bench_uploads_quick` под `$(KEEP_AWAKE)`. Проверка: `make + bench_uploads_quick` — код 0, H1 и H2 видны в сводке. +- [ ] 8.6 Регресс `bench/`: `make bench_quick`, `bench_restore_quick`, + `bench_failover_quick`, `bench_rollout_quick` — код 0; в паспортах — + буфер приёма реплики. Проверка — коды и паспорта. + +## 9. Правила и документы + +- [ ] 9.1 Правила по design, решение 12: + - `api-contract.md` — 429 и порядок проверок; + - `service-layer.md` — места, буфер в PUT, порядок записи; + - `infra.md` — `upload_slots.py`; + - `settings.md` — `[uploads]`; B прежняя и почему; + - `docker.md` — `sysctls` у `api`; + - `balancer.md` — срок пути загрузки, `http-error 400`, + `tune.sndbuf.server`, дренаж 90 с, цепочка; + - `bench.md` — профиль `uploads`, исключение S3 у оркестратора, смена + стенда для прежних профилей; + - `student-tests.md` — третий API и тесты; + - `logging.md` — новые поля и причины; + - `run-modes.md` — консоль без sysctl. + + Проверка: правила не противоречат коду; `grep -rn "DRAIN_TIMEOUT + (12)\|12 с (> timeout server)" .claude/rules scripts` пуст. +- [ ] 9.2 AGENTS.md: + - вводный абзац — change `upload-memory`; + - инвариант лабы 4 о памяти загрузок; + - команды `make bench_uploads`, `bench_uploads_quick`, `driver.py + lb-upload-timeouts`; + - карта кода: `upload_slots.py`, `[uploads]`, профиль и файлы + `bench/`, `evidence/uploads/`. + + Проверка — чтение по таблице команд. +- [ ] 9.3 `PLAN.md`, раздел `### upload-memory`: решения apply по + образцу прежних changes, ответ на вопрос 1, когда придёт. Строку + этапа 4 сводной таблицы отмечает основная сессия при archive. +- [ ] 9.4 `make lint`, `make check`, `make validate + PYTHON=.venv/bin/python` — код 0. + +## 10. Прогоны и evidence + +- [ ] 10.1 Commit кода (основная сессия, после подтверждения). Затем на + рабочем стенде `make rolling_update` и `docker compose up -d + --force-recreate haproxy` (design, Migration Plan). Проверка: + - `make test`; + - `make student_test` через LB: ожидаемо красный только + `test_exclusion_evidence_exists` (6.2); + - `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; + - `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` для обеих + реплик; + - `make s3_check`. +- [ ] 10.2 Гипотезы H1–H4 (design, решение 10) — в `REPORT.md`, раздел + загрузок, отдельным commit до первого прогона метки (`bench.md`, + `COURSE.md`). Проверка: в `git log` commit гипотез раньше метки. +- [ ] 10.3 `make bench_uploads` после проверки хоста (`bench.md`, + «Результаты»; рабочий стенд — `make stop`), затем commit метки. + Проверка: + - паспорт без `host_warnings`; + - ячейки «с лимитом» без `oom` и 5xx; + - «до» и «без лимита» на 40 × 10 MiB — `oom`. + + Расхождение с гипотезой — не повод править гипотезу: вывод в + `REPORT.md`. +- [ ] 10.4 `driver.py lb-upload-timeouts` → + `evidence/uploads/lb-timeouts.md`. Две медленные загрузки (~20 с, по + одной на реплику) во время `make rolling_update` → + `evidence/uploads/rollout-upload.md`: обе 201, строки дренажа (спек + `load-balancing`, «Загрузка во время дренажа»). +- [ ] 10.5 После commit метки — `make failure_checks`, `make + test_isolated`, `make student_test` через LB, все зелёные. Выводы — в + `evidence/tests/` (`failure-checks.md`, `student-test-lb.md`, файл + `test_isolated`). Проверка: `test_exclusion_evidence_exists` зелёный. +- [ ] 10.6 `REPORT.md` (design, решение 12): + - раздел «Память и сроки загрузки» с формулами и B; + - результаты и выводы по H1–H4 из `summary.md` метки; + - строки таблицы доказательств уровня «4» вместо `TODO + (upload-memory …)`; + - обновлённые «Ограничения»; + - вопрос 1 в «Согласованиях», если ответ пришёл. + + Проверка: числа совпадают со сводкой метки, ссылки на evidence + существуют.