125 lines
8.7 KiB
Markdown
125 lines
8.7 KiB
Markdown
# 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`.
|