Files
mtusi2026lab6/openspec/specs/queue-overload/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
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>
2026-11-11 04:46:56 +03:00

162 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 не изменились