Files
mtusi2026lab4/openspec/changes/upload-memory/design.md
T

62 KiB
Raw Blame History

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; ответ меняет одну строку таблицы ошибок, сценарии и тесты, но не подход и не задачи.

Уточнения apply

Решения /opsx:apply (2026-10-21), пользователь недоступен; вопрос 1 PLAN.md открыт — сделано 429, как в решении 2.

  1. test_upload_slots_busy: A отпускается раньше сверки списков. Таблица решения 11 сверяет «новых id нет» до отпускания A, но срок тела стенда 2 с с момента, как A заняла место, а B получает 429 только через ~1,2 с; два вызова hook (attachment-ids, object-ids) не успели бы. Поэтому после 429 у B A отпускается сразу (201), а сверка — новые id = {A} и в строках, и в объектах: у B и C ничего нет.

  2. test_rejections_before_queue проверяет, что очередь была полна: ожидавшая B получает 429, а три ранних отказа приходят до её ответа. Без этого быстрые 404 / 413 / 415 ничего не доказывали бы: сценарий требует полной очереди. Поэтому на коде без мест тест красный (B — 201), а не зелёный, как ждали tasks (1.5). test_slot_released_after_failures на прежнем коде тоже красный — на шаге «тело дольше срока — 400»: срока тела там нет. Красный прогон — 5 из 5 (evidence/tests/ failure-checks.md).

  3. Срок ранних отказов — меньше срока ожидания места (1 с), а не 0,5 с. Тело 30 MiB с Content-Length httpx отправляет целиком, прежде чем читать ответ, и через проброс порта Docker Desktop это заметная доля 0,5 с. Ошибка, которую ловит проверка (ранний отказ ждёт место), дала бы ≥ 1 с или 429. Порог 0,5 с остался у C («Очередь ожидания полна»).

  4. Тип UploadSlots в сервисе — под TYPE_CHECKING. Импорт src/infra/upload_slots.py создаёт глобал, а src.core.services импортирует и процесс уборщика; глобал берёт только src/api/dependencies.py (infra.md).

  5. Retry-After — таблица RETRY_AFTER в errors.py рядом с CHALLENGES (тип исключения → секунды), а не условие в обработчике: новое исключение с повтором — одна строка.

  6. UploadsBusy журналирует сервис, а не UploadSlots: путь на месте вынесен в _store, upload ловит только UploadsBusy входа в место и пишет «Rejected attachment» (reason=busy, waited_ms от начала ожидания). body_timeout пишет и size прочитанного.

  7. config.toml рабочего дерева получил секцию [uploads] с теми же значениями, что config_example.toml (правило settings.md, «Новое поле или секция», п. 3); поведение не меняется — значения по умолчанию.

  8. Драйвер lb-upload-timeouts (задача 7.1):

    • перед стендом — haproxy -c той же конфигурации в том же образе (ошибка — код 1), нет файла — код 2; образ LB — по строке image: haproxy:… из docker-compose.yml;
    • заглушка — mtusi-messenger:lab4 с --entrypoint python -c, --no-healthcheck, сетевое имя api, порт 8080; задержки — окружением; ответ заглушки узнаётся по X-Instance-Id: stub;
    • пять случаев параллельно (~33 с), каждый со своим ?case=… на пути загрузки; клиент — с хоста через свободный порт 127.0.0.1, тело 10 MiB; «клиент молчит посреди тела» — сырой сокет: заголовки с Content-Length 10 MiB и половина тела, время — от последнего байта (LB отвечает по timeout client через ~30 с, отдельные 35 с не ждутся);
    • границы: 201 — 11,5–17 с; 504 другого пути — 9,5–12 с; 504 пути загрузки — 29,5–32 с; 400 — 29–33 с; ошибки LB — ровно {"error": {code, message, request_id}}, request_id = X-Request-Id;
    • уборка по метке контейнеров и сети mtusi-lbto-<tag> в finally, в том числе по SIGTERM и SIGHUP.
  9. Sync дельт — по блокам требований, как в attachments и upload-consistency: блоки MODIFIED заменены целиком, ADDED дописаны в конец спека; все блоки основных спеков построчно совпали с дельтами.

  10. Профиль uploads (задачи 8.1–8.6):

    • разбор без docker вынесен в bench/uploads.py (тела, план, разбор k6 и сэмплера, строка runs.csv, сводка, --selftest), как failover.py и rollout.py;
    • окно памяти — весь прогон k6 (разгон и окно): пик сбрасывается перед нагрузкой, после разогревающей загрузки. Загрузок в секунду и перцентили — по загрузкам, отправленным в окне [t0 + 3, t0 + 23); ответы по кодам — за весь прогон, в том числе после OOM;
    • S3 перед прогоном гасится kill, а не плавной остановкой (~15 с): его volume всё равно удаляется;
    • окружение варианта — override .work/variant.compose.yml, а не переменные BENCH_* в bench.compose.yml: иначе stand.app_env прежних профилей изменился бы, и bench_compare отказал бы со старыми метками; у «с лимитом» и «до» окружение пустое;
    • зерно тела — seed + высота: тело 10 MiB у uploads и uploads_quick побайтно одно;
    • пользователь, вход и чат — один раз на метку (members=1), реплика окна каждый раз новая;
    • к столбцам решения 10 добавлены start_peak_mib (пик старта до сброса — проверка «Пик окна без памяти старта»), lb_sock_max_mib, host_swapouts; пометка s3_down;
    • в паспорт всех профилей — stand.api_tcp_rmem и docker.kernel;
    • найден и исправлен дефект стенда, касается и прежних профилей: контейнер сэмплера (образ PostgreSQL) удалялся без -v и оставлял анонимный volume /var/lib/postgresql на каждый запуск; теперь stop_sampler и Stand.stop() удаляют его с -v.
  11. Буфер приёма LB от клиента — tune.rcvbuf.client 131072 (уточняет решение 6; решение основной сессии после метки baseline, отброшенной из-за host_warnings и dirty). В той метке пик LB «с лимитом» на 10 MiB — 38,8 / 83,5 / 107,3 / 139,9 MiB при C = 1 / 10 / 20 / 40 (~2,6 MiB на клиента), sock LB до 112 MiB: сценарий load-balancing «Буферы соединений ограничены» не выполнялся. Причина — буфер приёма от клиента, который решение 6 оставило без ограничения: проба /proc/net/tcp контейнера LB во время bench_uploads_quick показала у сокетов клиентов очередь приёма до 9 MiB на сокет и 39 MiB суммарно при C = 40, у сокетов к реплике — до ~8 MiB (tune.sndbuf.server). В пробе design клиент httpx слал медленнее k6, и рост автонастройки окна был меньше.

    tune.rcvbuf.client пик LB C = 1 / 10 / 40, MiB рост на клиента очередь клиента, max C = 1: загрузок/с, p50
    нет (как было) 52,5 / 79,1 / 100,9 1,24 MiB 9,0 MiB 11,4, 82 мс
    262144 33,8 / 38,3 / 67,7 0,87 MiB 0,48 MiB 11,05, 85 мс
    131072 35,6 / 41,4 / 57,3 0,56 MiB 0,24 MiB 11,25, 84 мс

    Выбрано 128 KiB — запас до 1 MiB на клиента при 256 KiB тонкий (одна проба, uploads_quick). Скорость одного клиента в сети Docker прежняя. Цена — окно TCP клиента: ~20 Мбит/с при RTT 50 мс (10 MiB за ~4 с при сроке тела 30 с); клиенту с RTT больше ~370 мс 10 MiB в 30 с не уложить — ограничение в REPORT.md. Альтернатива — sysctls net.ipv4.tcp_rmem у haproxy (автонастройка до 512 KiB) — отвергнута: задела бы и буфер приёма LB от реплики (ответы, скачивание), а tune.rcvbuf.client живёт в том же haproxy.cfg, что tune.sndbuf.server, и действует на стенде bench/ и в драйвере без правки compose. Спек от правки не меняется: сценарий требует ≤ 1 MiB на клиента, и теперь он выполняется.