Reject uploads with 429 at [uploads] max_unfinished_jobs, counted by the existing partial indexes in the membership block. Add the bench_queue profile, hypotheses H1-H9 and the fifth failure-stand API. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
15 KiB
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-Length31 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, неподтверждённых сообщений не большеprefetch, заданий в очереди брокера не больше предела опубликованных, а незавершённых заданий столько же, сколько принято и не завершено
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 незавершённых заданий становится ноль без действий оператора, очередь брокера пуста, время восстановления записано, а скорость обработки в окне восстановления не ниже скорости в окне перегрузки с запасом разброса
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 не изменились