Files
mtusi2026lab5/openspec/specs/queue-overload/spec.md
T
ricoromaandClaude Opus 5.5 d667fa3c57 feat: limit accepted attachment work and add queue overload bench
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>
2026-11-01 07:30:08 +03:00

15 KiB
Raw Blame History

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, неподтверждённых сообщений не больше 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 не изменились