Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e. Contracts, public tests and evidence of lab 5 are not carried over. The compose project, image and CI prefix are renamed to lab6; the first broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the OpenSpec changes of lab 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
162 lines
16 KiB
Markdown
162 lines
16 KiB
Markdown
# 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 не изменились
|