docs: propose upload-memory
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -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
|
||||
@@ -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; ответ меняет одну строку таблицы ошибок, сценарии
|
||||
и тесты, но не подход и не задачи.
|
||||
@@ -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` удаляет их и начинает заново
|
||||
@@ -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
|
||||
существуют.
|
||||
Reference in New Issue
Block a user