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

8.7 KiB
Raw Blame History

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.