62 KiB
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_seconds5 с на вызов, пул 10 соединений; - реплика — 1 CPU / 512 МБ,
memswap_limitне задан (Docker даёт swap 2 × лимит); хэши паролей — доkdf_concurrency4 × 64 MiB; - HAProxy:
timeout server10 с,timeout client30 с,timeout http-request10 с,http-reuse never;ROLLOUT_DRAIN_TIMEOUT12 с («большеtimeout server»); - SeaweedFS: 1 CPU / 512 МБ,
GOMEMLIMIT=400MiB,-s3.concurrentUploadLimitMB=64; - граница живой загрузки уборщика B = 2 × 6 + 5 = 17 с, проверка — в
src/cleaner/main.py(live_upload_bound_seconds).
Что найдено до решений
- При PUT тело копируется ещё раз. botocore превращает
bytesвBytesIO(bytes)с общим буфером (convert_body_to_file_like_object).BytesIOPayloadaiohttp берёт его размер черезgetbuffer()(aiohttp/payload.py, строка 850), и CPython копирует общий буфер целиком. Снимокtracemallocво время записи тела: 9,99 MiB одним блоком с этим стеком. Проверкаattachments(«Уточнения apply», п. 10) моделировала только botocore и копии не видела. Поэтому «~1,2 тела» вREPORT.mdневерно: на шаге PUT — два тела, а спекattachments(«Лимит размера до чтения тела») сейчас нарушен. - Ожидание до чтения тела память само не бережёт. uvicorn
(httptools) перестаёт читать сокет после 64 KiB, но ядро принимает
дальше — до буфера приёма сокета. У ВМ Docker Desktop
net.ipv4.tcp_rmem=4096 131072 33554432, то есть до 32 MiB на соединение, и эта память (sockвmemory.stat) считается памятью контейнера. С той же стороны LB копит недоставленное в буфере отправки к реплике:tcp_wmemдо 4 MiB. - Срок LB на пути загрузки — 10 с на молчание с обеих сторон тела. Реплика, которая не читает тело дольше 10 с (ожидание места, медленная БД), даёт клиенту 502 от LB. Реплика, которая молчит после тела дольше 10 с, даёт 504 (пробы ниже).
- Клиент, замолчавший посреди тела, получает от LB 400 в HTML, а не
в формате контракта. Ответ 408 на медленные заголовки — тоже HTML, и
http-error status 408его не меняет: такой ответ HAProxy строит до потока запроса. - Пик 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, «Порядок проверок загрузки»):
- вход, параметры, членство (404),
Content-Type(415),Content-Length(413) — без места; - место (429);
- тело со счётчиком и сроком (413, 400);
- проверка изображения и SHA-256 (415, 413);
- строка
pending(tx1), PUT,ready(tx2), компенсация; - ответ, место освобождается.
Ранние отказы не занимают места и не стоят в очереди: посторонний или
заведомо большое тело не вытесняют живые загрузки. Ожидающая загрузка
сессии БД не держит: вход и членство — короткие шаги до места (решение
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, в котором копилось тело. Сервис:
data = buffer.getvalue()—bytesнад буфером, без копии;- проверка изображения и SHA-256 в потоке над
data; size = len(data), затемdel data— буфер снова не общий;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 с,anonS3 — 341 MiB (проба).[s3] timeout_seconds5 с — один для всех вызовов. Отдельного срока PUT по размеру нет. Это закрывает открытый вопрос designattachments(«Срок 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» с
reasonbusy(с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: overrides3уже описан,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) — до первого окна.
- новый volume S3 (
-
Окно —
constant-vusk6: 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(sysctlapi),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 на соединение,
maxconn4096 больше его лимита 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_TIMEOUT90 с: застрявшая загрузка задерживает замену] → срок тела ограничивает её ~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
- Код: места, срок тела, буфер в PUT, ошибки, настройки, журнал. Миграции схемы нет.
- Стенд:
sysctlsуapi,haproxy.cfg,rolling-update.sh,config_example.toml. - Тесты, стенд отказов, сверка покрытия;
make lint, прогоны. - Профиль
uploads, драйвер, регрессbench/. - Правила, AGENTS.md,
KNOWN_ISSUES.md,PLAN.md. - Commit после подтверждения пользователя. Затем гипотезы — отдельным
commit, затем замеры и evidence с закоммиченного кода, затем
REPORT.md.
На рабочем стенде:
make rolling_update— реплики на новый образ, новые контейнеры получаютsysctlsиз compose; старые без ограничения дорабатывают до дренажа.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или 503unavailable(решение 2,PLAN.md, «Вопросы», п. 1). До ответа преподавателя — 429; ответ меняет одну строку таблицы ошибок, сценарии и тесты, но не подход и не задачи.
Уточнения apply
Решения /opsx:apply (2026-10-21), пользователь недоступен; вопрос 1
PLAN.md открыт — сделано 429, как в решении 2.
-
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 ничего нет. -
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). -
Срок ранних отказов — меньше срока ожидания места (1 с), а не 0,5 с. Тело 30 MiB с
Content-Lengthhttpx отправляет целиком, прежде чем читать ответ, и через проброс порта Docker Desktop это заметная доля 0,5 с. Ошибка, которую ловит проверка (ранний отказ ждёт место), дала бы ≥ 1 с или 429. Порог 0,5 с остался у C («Очередь ожидания полна»). -
Тип
UploadSlotsв сервисе — подTYPE_CHECKING. Импортsrc/infra/upload_slots.pyсоздаёт глобал, аsrc.core.servicesимпортирует и процесс уборщика; глобал берёт толькоsrc/api/dependencies.py(infra.md). -
Retry-After— таблицаRETRY_AFTERвerrors.pyрядом сCHALLENGES(тип исключения → секунды), а не условие в обработчике: новое исключение с повтором — одна строка. -
UploadsBusyжурналирует сервис, а неUploadSlots: путь на месте вынесен в_store,uploadловит толькоUploadsBusyвхода в место и пишет «Rejected attachment» (reason=busy,waited_msот начала ожидания).body_timeoutпишет иsizeпрочитанного. -
config.tomlрабочего дерева получил секцию[uploads]с теми же значениями, чтоconfig_example.toml(правилоsettings.md, «Новое поле или секция», п. 3); поведение не меняется — значения по умолчанию. -
Драйвер
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-Length10 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.
- перед стендом —
-
Sync дельт — по блокам требований, как в
attachmentsиupload-consistency: блоки MODIFIED заменены целиком, ADDED дописаны в конец спека; все блоки основных спеков построчно совпали с дельтами. -
Профиль
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.
- разбор без docker вынесен в
-
Буфер приёма 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 на клиента),sockLB до 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. Альтернатива —sysctlsnet.ipv4.tcp_rmemуhaproxy(автонастройка до 512 KiB) — отвергнута: задела бы и буфер приёма LB от реплики (ответы, скачивание), аtune.rcvbuf.clientживёт в том жеhaproxy.cfg, чтоtune.sndbuf.server, и действует на стендеbench/и в драйвере без правки compose. Спек от правки не меняется: сценарий требует ≤ 1 MiB на клиента, и теперь он выполняется.