docs: propose upload-memory

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-21 23:21:42 +03:00
co-authored by Claude Opus 5.5
parent f894040b72
commit fc1524d0d6
12 changed files with 1985 additions and 0 deletions
+94
View File
@@ -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).
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-21
+689
View File
@@ -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; ответ меняет одну строку таблицы ошибок, сценарии
и тесты, но не подход и не задачи.
+124
View File
@@ -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`.
@@ -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` —
положительным целым числом
@@ -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` совпадают с файлом
@@ -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 не завершены из-за памяти
@@ -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** у каждой гипотезы есть вывод со ссылкой на ячейки сводки
метки, а числа совпадают со сводкой
@@ -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** сервис не стартует, в журнале — ошибка проверки настроек с
именем поля
@@ -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`)
@@ -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` удаляет их и начинает заново
+313
View File
@@ -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
существуют.