# queue-overload Specification ## Purpose Поведение конвейера вложений под перегрузкой с лабы 5, трек 1: предел незавершённых заданий на входе API и что видит клиент у предела, где и как сдерживается работа, что происходит с остальным API, восстановление после перегрузки и рестарты worker и брокера под ней. Как это меряется — `load-benchmark`, «Профиль очереди». ## Requirements ### Requirement: Предел незавершённых заданий Незавершённое задание — задание в состоянии `queued` или `processing`, в том числе ожидающее следующей попытки или неопубликованное. Загрузка, прошедшая проверки 1–5 (`attachments`, «Порядок проверок загрузки»), SHALL получать ответ 429 `rate_limited` в формате ошибки с заголовком `Retry-After` — положительным целым числом секунд, если незавершённых заданий стенда не меньше `[uploads] max_unfinished_jobs` (`service-configuration`, «Параметры загрузок»). Значение 0 — предела нет. Такая загрузка MUST NOT читать тело, занимать место загрузки и ждать его, MUST NOT оставлять ни метаданных, ни объекта. Ответ SHALL приходить сразу: без ожидания освобождения работы. Клиент повторяет загрузку сам, после `Retry-After`: это новая загрузка, она ничего не дублирует, потому что отклонённая ничего не сохранила. Балансировщик такой ответ не повторяет (`load-balancing`). Предел SHALL быть один на стенд: его считают по PostgreSQL все реплики, память процесса в подсчёте не участвует. Предел мягкий: загрузки, которые уже прошли проверку и ещё не зафиксировали задание, могут превысить его, но не больше чем на число загрузок в полёте: реплик × (`[uploads] max_concurrent` + `[uploads] max_waiting`). Проверка MUST NOT добавлять загрузке шаг с PostgreSQL сверх прежних: цепочка сроков пути загрузки в балансировщике не меняется. Её цена MUST NOT расти с числом завершённых заданий и с превышением предела. Журнал реплики SHALL называть отказ: причина «предел заданий», предел и найденное число, без `filename`. #### Scenario: Предел достигнут - **WHEN** worker остановлен, предел равен K, и участник последовательно загружает настоящие PNG - **THEN** первые загрузки до K незавершённых заданий получают 202, следующая — 429 `rate_limited` с `Retry-After` не меньше 1, с непустыми `X-Request-Id` и `X-Instance-Id`, быстрее секунды, и нового вложения нет ни в PostgreSQL, ни в bucket #### Scenario: Загрузки снова принимаются - **WHEN** предел достигнут, worker запущен, и незавершённых заданий стало меньше предела - **THEN** следующая загрузка получает 202, а все принятые раньше вложения становятся `ready` #### Scenario: Завершённые задания не считаются - **WHEN** незавершённых заданий нет, а вложений `ready` и `failed` больше предела - **THEN** загрузка получает 202 #### Scenario: Ожидание следующей попытки считается - **WHEN** задание ждёт следующую попытку, её срок ещё не наступил, а незавершённых заданий вместе с ним столько же, сколько предел - **THEN** загрузка получает 429 #### Scenario: Порядок проверок у предела - **WHEN** предел достигнут, и посторонний загружает файл в чат, участник загружает 30 MiB с `Content-Length` 31 457 280, а затем PNG с `Content-Type: text/plain` - **THEN** ответы 404, 413 и 415, а не 429 #### Scenario: Остальной API у предела - **WHEN** предел достигнут - **THEN** отправка текста — 201, история — 200, метаданные и скачивание готового вложения — 200, сообщение со ссылкой на принятое вложение — 201, а `/health/ready` — 200 #### Scenario: Предел при остановленных брокере и relay - **WHEN** брокер и relay остановлены, и участник загружает файлы до предела - **THEN** загрузки до предела получают 202 быстрее секунды, следующая — 429, а после запуска брокера, relay и worker все принятые вложения становятся `ready` #### Scenario: Превышение ограничено - **WHEN** незавершённых заданий нет, предел равен K, и участники одновременно загружают заметно больше K файлов - **THEN** каждый ответ — 202 или 429, принятых не меньше K и не больше K плюс числа загрузок в полёте, и каждое принятое вложение становится `ready` #### Scenario: Предел выключен - **WHEN** сервис запущен с `UPLOADS__MAX_UNFINISHED_JOBS=0`, worker остановлен, и участник загружает файлы - **THEN** каждый ответ 202, сколько бы заданий ни ждало ### Requirement: Сдерживание работы по уровням Работа под перегрузкой SHALL сдерживаться последовательно, и на каждом уровне SHALL быть видно, сколько её там: - приём: места загрузки реплики и предел незавершённых заданий — клиент видит 429; - outbox: задания, которые relay ещё не опубликовал, — в PostgreSQL; - очередь брокера: не больше `[relay] max_published_backlog` опубликованных и не взятых заданий, остальные ждут в outbox; - worker: брокер выдаёт не больше `[worker] prefetch` неподтверждённых сообщений, а взято в работу не больше `[worker] concurrency` заданий; - процесс обработки: лимиты памяти и CPU на задание, лимит памяти контейнера worker. Сдерживание за входом клиент MUST NOT видеть иначе, чем дольше не меняющееся `queued`: ни одного кода ошибки оно не даёт. #### Scenario: Работа копится там, где положено - **WHEN** загрузки идут быстрее потолка worker, и предел незавершённых заданий не достигнут - **THEN** в каждый момент заданий `processing` не больше `concurrency` на один worker, кроме строк завершённого процесса, ждущих аренду, неподтверждённых сообщений не больше `prefetch` на один worker, заданий в очереди брокера не больше предела опубликованных, а незавершённых заданий столько же, сколько принято и не завершено #### Scenario: Приём упирается в места загрузки - **WHEN** загрузки на границе байтов контракта идут быстрее, чем реплики и S3 успевают их принимать, а предел незавершённых заданий не достигнут - **THEN** лишние загрузки получают 429 от мест загрузки, принятые — 202, ответов 5xx нет, а принято не меньше, чем при интенсивности ниже этой границы #### Scenario: Сначала места, затем предел - **WHEN** загрузки на границе байтов контракта идут быстрее, чем реплики и S3 успевают их принимать, столько времени, что незавершённых заданий набирается до предела - **THEN** сначала лишние загрузки получают 429 от мест загрузки, затем — 429 от предела незавершённых заданий, журнал реплик называет обе причины, ответов 5xx нет, а незавершённых заданий не больше предела плюс загрузок в полёте ### Requirement: API под перегрузкой Пока работа копится, остальной API SHALL обслуживаться: отправка сообщений, чтение истории, метаданные и скачивание готовых вложений MUST NOT получать ответы 5xx из-за перегрузки очереди, а реплики API MUST NOT выводиться из балансировщика. Загрузка SHALL отвечать 202 или 429, а 5xx на ней — только при отказе S3 или PostgreSQL. #### Scenario: Контрольный поток под перегрузкой - **WHEN** загрузки идут быстрее потолка worker, но не быстрее, чем принимают реплики и S3, а рядом идёт постоянный поток отправки текста, чтения истории и скачивания готовых вложений (`load-benchmark`, «Профиль очереди») - **THEN** ответов 5xx контрольного потока нет, его p95 при отправке и чтении истории не больше 200 мс, при скачивании — не больше 500 мс, а все реплики остаются в балансировщике ### Requirement: Восстановление после перегрузки Восстановление — состояние после спада нагрузки, в котором незавершённых заданий нет, очередь брокера пуста, а время до `ready` новой работы вернулось к значению до перегрузки. После снятия нагрузки конвейер SHALL приходить в него сам, без действий оператора. Каждое принятое вложение (ответ 202) SHALL дойти до `ready` или названного `failed`: потерянных и зависших MUST NOT быть. Эффект MUST NOT дублироваться: на вложение одно задание и по одному варианту каждого имени. Время восстановления SHALL быть измерено и не больше времени обработки накопленного при потолке worker с запасом, заданным гипотезой (`load-benchmark`, «Очередь под перегрузкой в отчёте»). #### Scenario: Бэклог уходит за измеренное время - **WHEN** загрузки шли быстрее потолка worker, и нагрузка снята - **THEN** на любой настройке незавершённых заданий становится ноль без действий оператора, очередь брокера пуста и время восстановления записано; на настройке, которая помещается в лимит памяти worker, без завершений и перезапусков worker и с конкуренцией не больше двух мест на CPU worker, скорость обработки в окне восстановления не ниже скорости в окне перегрузки с запасом разброса; на прочих настройках падение скорости записывается и называется в отчёте #### Scenario: Никого не теряем - **WHEN** нагрузка снята, и проверяющий по HTTP запрашивает метаданные каждого вложения, на которое ответили 202 - **THEN** каждое `ready` с тремя вариантами или `failed` с `error_code`, зависших нет, а выборочные оригинал и варианты скачиваются с SHA-256 из метаданных #### Scenario: Время до готовности вернулось - **WHEN** очередь разобрана, и загрузки снова идут ниже потолка worker - **THEN** p95 времени до `ready` новых вложений не больше чем в полтора раза выше p95 до перегрузки ### Requirement: Рестарты под перегрузкой Остановка процессов конвейера под перегрузкой MUST NOT терять принятую работу и MUST NOT создавать второй набор вариантов. #### Scenario: Worker убит под перегрузкой - **WHEN** загрузки идут быстрее потолка worker, worker завершён сигналом KILL и снова запущен - **THEN** каждое принятое вложение становится `ready`, новых попыток сверх взятых к моменту KILL не появилось, одна попытка на задание у остальных, а взятые заканчиваются не позже срока аренды с запасом #### Scenario: Брокер перезапущен под перегрузкой - **WHEN** загрузки идут быстрее потолка worker, и брокер перезапущен с сохранённым volume - **THEN** загрузки отвечают 202 и во время рестарта, каждое принятое вложение становится `ready`, сообщения в очереди после разбора нет, а счётчики перезапусков relay и worker не изменились