Files
mtusi2026lab4/openspec/changes/upload-memory/proposal.md
T
2026-10-21 23:21:42 +03:00

125 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.