Files
mtusi2026lab5/openspec/specs/load-balancing/spec.md
T
ricoromaandClaude Opus 5.5 e2a6427c24 feat: add job outbox, relay, leases and image variants to the pipeline
Move publishing out of the upload path: a relay process publishes queued
jobs with confirms. Add lease and attempt fencing, backoff with jitter, a
per-job render process with CPU and memory limits, crop and optimized
variants, the failed registry with audited replay, and staging cleanup.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 15:36:15 +03:00

534 lines
34 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.
# load-balancing Specification
## Purpose
Работа API за балансировщиком: одна точка входа, несколько
взаимозаменяемых реплик без привязки клиента, проверка их готовности,
безопасные повторы и сохранение чтения и записи при отказе любой одной
реплики.
## Requirements
### Requirement: Единая точка входа
Стенд SHALL принимать запросы клиентов в одной точке — балансировщике
(LB), опубликованном на `127.0.0.1:${APP_OUT_PORT}`. Реплики API MUST
NOT публиковать порты на хосте и MUST NOT иметь фиксированного имени
контейнера. Ответы реплик SHALL проходить через LB без замены
заголовков `X-Request-Id` и `X-Instance-Id` и тела.
#### Scenario: Порт только у балансировщика
- **WHEN** стенд запущен `make run_docker`, и выполнен
`docker compose ps`
- **THEN** у контейнеров `api` нет опубликованных портов, у них нет
заданного `container_name`, а API на хосте доступно только через
порт LB на `127.0.0.1`
### Requirement: Взаимозаменяемые реплики
Сервис API SHALL запускаться в числе реплик `API_REPLICAS`, по
умолчанию 2. Это значение читают compose и Makefile, приложение MUST
NOT его читать. Реплики SHALL быть
одинаковыми: один образ, одна конфигурация, общие PostgreSQL и Valkey.
В памяти процесса MUST NOT быть состояния, от которого зависит
корректность ответа. Изменение числа реплик MUST NOT требовать правки
конфигурации LB. LB SHALL обслуживать до 8 реплик.
#### Scenario: Две реплики по умолчанию
- **WHEN** выполнен `make run_docker` без `API_REPLICAS` в `.env`
- **THEN** работают два контейнера `api` с разными `X-Instance-Id`, и
оба получают запросы через LB
#### Scenario: Масштабирование без правки балансировщика
- **WHEN** выполнен `make replicas API_REPLICAS=3`, а конфигурация LB
не менялась
- **THEN** не позже чем через 10 с запросы через LB обслуживают три
разных `X-Instance-Id`
### Requirement: Распределение без привязки клиента
LB SHALL распределять запросы по готовым репликам по очереди, независимо
от соединения, сессии и cookie клиента. Привязка клиента к реплике
(sticky session) MUST NOT использоваться. Запросы одной сессии SHALL
обслуживаться разными репликами без повторного входа. Подтверждённое
сообщение SHALL быть видно следующему чтению через любую реплику.
#### Scenario: Одна сессия на разных репликах
- **WHEN** пользователь вошёл один раз и выполняет 20 запросов
`GET /api/v1/users/me` с одним токеном через LB
- **THEN** все ответы 200 с этим пользователем, а `X-Instance-Id`
принимает не меньше двух разных значений
#### Scenario: Запись видна через другую реплику
- **WHEN** сообщение отправлено через LB, затем история чата
читается несколько раз подряд
- **THEN** каждое чтение содержит это сообщение, в том числе чтения
с другим `X-Instance-Id`, чем у отправки
#### Scenario: Распределение видно оператору
- **WHEN** выполнен `make instances`
- **THEN** команда входит одним синтетическим пользователем, выполняет
серию запросов с одним токеном и печатает `X-Instance-Id` каждого
ответа и число ответов каждой реплики
### Requirement: Проверка готовности реплик
LB SHALL активно проверять каждую реплику запросом
`GET /health/ready`. SHALL быть заданы явно:
- период проверок;
- период повторной проверки после первой неудачи и до возврата;
- число неудач до исключения и успехов до возврата;
- таймаут проверки.
Реплика, которая не проходит проверки, SHALL исключаться из
распределения: она остановлена, не отвечает или отвечает 503.
Вернувшаяся реплика SHALL включаться без перезапуска LB.
Время обнаружения отказа по проверкам MUST NOT превышать 10 с. Худший
случай — у реплики, которая принимает соединение, но не отвечает:
период плюс таймаут проверки, затем ещё (число неудач − 1) раз период
повторной проверки плюс таймаут. Таймаут проверки внутри
`/health/ready` SHALL быть меньше таймаута проверки LB.
#### Scenario: Остановленная реплика исключена
- **WHEN** одна из двух реплик остановлена
- **THEN** не позже чем через 10 с статистика LB показывает её не в
состоянии `UP`, и запросы через LB обслуживает только оставшаяся
#### Scenario: Вернувшаяся реплика включена
- **WHEN** остановленная реплика запущена снова
- **THEN** не позже чем через 10 с после её готовности статистика LB
показывает её `UP`, и запросы снова распределяются по обеим
### Requirement: Повтор только при отказе соединения
LB SHALL повторять запрос на другой реплике, только если соединение с
репликой не установлено, то есть запрос до неё не дошёл. Такой повтор
безопасен для любого метода. Запрос, который реплика уже получила, MUST
NOT повторяться LB: ни по таймауту ответа, ни по обрыву ответа, ни по
ответу 5xx. Причина — `POST /users` и `POST /chats` не идемпотентны.
Отправку сообщения повторяет клиент, с тем же `Idempotency-Key`.
Произведение таймаута соединения LB на число попыток SHALL быть меньше
2 с: перенаправление должно успеть раньше таймаута клиента публичной
проверки.
#### Scenario: Отказ соединения перенаправлен
- **WHEN** реплика закрыла приёмный сокет (`docker stop`), а LB ещё
не исключил её по проверкам
- **THEN** запрос, направленный на неё, LB передаёт другой реплике, и
клиент получает ответ API, а не ошибку LB
#### Scenario: Оборванный ответ не повторяется
- **WHEN** процесс реплики убит (`docker kill`), пока она обрабатывает
запрос
- **THEN** клиент получает ошибку LB, а журнал LB показывает, что
запрос на другую реплику не повторялся
### Requirement: Ошибки балансировщика в формате контракта
Ответы, которые создаёт сам LB, SHALL иметь статус 400, 502, 503 или
504 и тело в формате ошибки контракта. У 502, 503 и 504 `code` —
`unavailable`: нет готовых реплик, ответ реплики оборвался или не пришёл
вовремя. У 400 `code` — `invalid_request`: запрос клиента неверен или
клиент замолчал посреди тела дольше `timeout client` LB. `request_id`
тела SHALL совпадать с заголовком `X-Request-Id`, который ставит LB.
`X-Instance-Id` у таких ответов может отсутствовать.
Ограничение называется в `REPORT.md`: ответ 408 на заголовки, которые
не пришли за `timeout http-request`, LB отдаёт своим текстом, а не в
формате ошибки контракта.
#### Scenario: Нет готовых реплик
- **WHEN** все реплики API остановлены, и клиент запрашивает
`/health/ready` через LB
- **THEN** ответ 503 с телом `{"error": {"code": "unavailable", ...}}`,
`request_id` равен `X-Request-Id`, а других полей в теле нет
#### Scenario: Клиент замолчал посреди тела
- **WHEN** клиент через LB отправил часть тела загрузки и молчит дольше
`timeout client` LB
- **THEN** ответ LB 400 с телом `{"error": {"code": "invalid_request",
...}}`, `request_id` равен `X-Request-Id`, а других полей в теле нет
### Requirement: Отказ одной реплики
При остановке любой одной реплики из двух и более новые чтения и
записи через LB SHALL проходить снова не позже чем через 10 с от
начала остановки. Подтверждённые сообщения SHALL оставаться
доступными. Повтор неподтверждённой отправки с тем же ключом MUST NOT
создавать дубль. Ошибки переходного периода допустимы и SHALL
учитываться. Публичная проверка `make test-failover
ACTION_SCRIPT=scripts/stop-one.sh` SHALL проходить для каждой реплики,
если предыдущая перед этим восстановлена.
#### Scenario: Штатная остановка каждой реплики
- **WHEN** `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
выполнен, затем реплики восстановлены, и проверка повторена так,
чтобы остановленной оказалась другая реплика
- **THEN** оба прогона печатают `PASS`, первая успешная запись после
начала остановки — не позже 10 с, дублей нет
#### Scenario: Отказ процесса без graceful
- **WHEN** та же проверка выполнена с `STOP_MODE=kill`
- **THEN** она печатает `PASS`: оборванные запросы учтены как
неудачные попытки, повтор с тем же ключом не создаёт дубль
### Requirement: Failover hook
`scripts/stop-one.sh` SHALL останавливать ровно одну работающую
реплику API этого проекта compose — ту, чей контейнер соответствует
`TARGET_INSTANCE_ID` (значению `X-Instance-Id`). Скрипт SHALL
возвращать 0 не позже чем через 10 с. Режим задаёт `STOP_MODE`:
`stop` (по умолчанию, SIGTERM и graceful) или `kill` (SIGKILL).
Остановленная реплика SHALL оставаться остановленной, несмотря на
политику перезапуска контейнера. Восстановление — отдельной командой
`make replicas`.
Если значение не соответствует ни одной работающей реплике API этого
проекта, скрипт SHALL завершаться с ненулевым кодом и ничего не
останавливать. PostgreSQL, Valkey, LB, контейнеры других проектов и
volumes скрипт MUST NOT трогать. Секреты он MUST NOT печатать.
#### Scenario: Остановка по instance id
- **WHEN** `scripts/stop-one.sh` выполнен с `TARGET_INSTANCE_ID`,
равным `X-Instance-Id` одной из реплик
- **THEN** скрипт вернул 0 быстрее 10 с, `docker compose ps -a`
показывает остановленным контейнер, ID которого начинается с
`TARGET_INSTANCE_ID`, а остальные контейнеры стенда работают с
прежним временем старта
#### Scenario: Чужой или неизвестный id
- **WHEN** `TARGET_INSTANCE_ID` пуст, имеет недопустимый формат,
указывает на контейнер PostgreSQL, Valkey или LB этого стенда либо не
соответствует ни одному контейнеру
- **THEN** скрипт завершается с ненулевым кодом, и ни один контейнер
не остановлен
#### Scenario: Реплика не поднимается сама
- **WHEN** реплика остановлена скриптом в режиме `stop` или `kill`,
и прошло 15 с
- **THEN** контейнер всё ещё остановлен, и его `X-Instance-Id` не
встречается в ответах через LB
#### Scenario: Восстановление реплик
- **WHEN** после остановки реплики выполнен `make replicas`
- **THEN** работают `API_REPLICAS` реплик, остановленный контейнер
запущен снова с тем же ID, и не позже чем через 10 с LB снова
распределяет запросы по всем репликам
### Requirement: Статистика балансировщика внутри сети
LB SHALL отдавать статистику по каждой реплике: состояние проверки,
число запросов, повторы, очередь. Статистика SHALL быть доступна только
внутри сети compose; на хост она MUST NOT публиковаться. Оператор SHALL
получать её одной командой `make lb_stats`.
#### Scenario: Состояние реплик
- **WHEN** стенд запущен, и выполнен `make lb_stats`
- **THEN** команда печатает по строке на каждый занятый слот реплики с
её адресом и состоянием проверки, а порт статистики не опубликован на
хосте
### Requirement: Время обнаружения отказа
Время от действия над репликой до её исключения LB SHALL измеряться
под нагрузкой для трёх режимов:
- `stop` — SIGTERM и graceful shutdown;
- `kill` — SIGKILL, отказ процесса;
- `pause` — процесс заморожен: соединение принимается, ответа нет.
Действие, смена состояния реплики в LB и ответы клиенту SHALL
сопоставляться на одних часах. Каждое измерение MUST NOT превышать
худший случай формулы проверок своего режима и 10 с. Формула и
измерения по режимам SHALL быть в `REPORT.md`.
#### Scenario: Остановка и убитый процесс
- **WHEN** реплика остановлена `docker stop` или убита `docker kill`
под нагрузкой
- **THEN** журнал LB показывает её `DOWN` или в обслуживании не позже
худшего случая формулы для недоступного адреса, а время от действия
записано в результаты профиля `failover`
#### Scenario: Зависшая реплика
- **WHEN** процесс реплики заморожен `docker pause` под нагрузкой
- **THEN** LB исключает реплику не позже худшего случая формулы и 10 с,
а запросы, уже отправленные на неё, получают 504 от LB в формате
ошибки контракта
### Requirement: Отказ реплики под нагрузкой
Каждая реплика по очереди SHALL останавливаться посреди нагрузки с
постоянной интенсивностью (запись с ключом и чтение истории), затем
восстанавливаться перед остановкой следующей. Для каждой остановки
SHALL измеряться посекундно:
- успешные ответы в секунду;
- ошибки по кодам;
- доля успешных ответов;
- распределение ответов по `X-Instance-Id`.
Время восстановления — от действия до момента, после которого доля
успешных ответов в каждой секунде не ниже 99 %. Оно MUST NOT
превышать 10 с. Возврат реплики MUST NOT давать ошибок клиенту.
#### Scenario: Каждая реплика в каждом режиме
- **WHEN** профиль `failover` останавливает по очереди каждую из двух
реплик в режимах `stop` и `kill`, восстанавливая предыдущую
- **THEN** для каждой остановки есть посекундная шкала, время
обнаружения и время восстановления не больше 10 с, а после возврата
реплики ошибок нет
#### Scenario: Ответы распределяются снова
- **WHEN** остановленная реплика восстановлена посреди нагрузки
- **THEN** не позже чем через 10 с её `X-Instance-Id` снова есть в
ответах, и ошибок за это время нет
### Requirement: Транзакции зависшей реплики
Открытую транзакцию реплики, процесс которой заморожен, PostgreSQL
SHALL прерывать после простоя `[database]
idle_in_transaction_timeout_ms`. Блокировки этой транзакции, в том
числе строки ключа идемпотентности, SHALL сниматься. Срок SHALL быть
больше `[database] request_timeout_seconds`: транзакция живой реплики
дольше этого срока не живёт, и прерывание её не задевает. Повтор
неподтверждённой отправки с тем же ключом через другую реплику SHALL
получать 201 после прерывания. В чате при этом SHALL оставаться одно
сообщение.
#### Scenario: Простой в транзакции
- **WHEN** соединение приложения открыло транзакцию и простаивает
дольше `idle_in_transaction_timeout_ms`
- **THEN** PostgreSQL прерывает это соединение, а его журнал называет
причину — простой в транзакции
#### Scenario: Повтор ключа после зависшей реплики
- **WHEN** реплика заморожена посреди отправки сообщения с ключом K,
пока её транзакция держит K, а клиент повторяет ту же отправку с K
через LB
- **THEN** после прерывания транзакции повтор получает 201, в чате
ровно одно сообщение с этим текстом, а после разморозки реплика
снова обслуживает запросы
### Requirement: Поочерёдная замена реплик
Команда `make rolling_update` (`scripts/rolling-update.sh`) SHALL
заменять работающие реплики API на образ из текущего checkout по одной,
без остановки обслуживания. Порядок:
1. сборка образа;
2. миграции, один раз (`db-migrations`);
3. для каждой старой реплики:
- рядом запускается одна новая;
- скрипт ждёт её готовности и состояния `UP` в статистике LB;
- старая выводится из LB, дорабатывает запросы, останавливается и
удаляется.
Реплик одновременно SHALL быть не больше `API_REPLICAS` + 1. Число
должно помещаться в слоты LB. Правка конфигурации LB и его перезапуск
MUST NOT требоваться.
После успешной замены SHALL работать ровно `API_REPLICAS` реплик. Все
они SHALL быть на новом образе и в состоянии `UP` в LB. Контейнеров
прежнего образа SHALL не остаться ни работающих, ни остановленных.
Под постоянной нагрузкой через LB (запись с ключом и чтение истории)
замена MUST NOT давать клиенту ошибок. Каждая подтверждённая запись
SHALL оставаться доступной.
Перед заменой скрипт SHALL проверять стенд:
- работает ровно `API_REPLICAS` реплик;
- остановленных реплик нет;
- все реплики `UP` в LB;
- для ещё одной реплики есть свободный слот LB;
- нет слотов LB в ручном дренаже или обслуживании, которое оставила
прерванная замена.
Если условие не выполнено, скрипт SHALL завершаться с ненулевым кодом
до сборки и ничего не менять.
#### Scenario: Замена двух реплик
- **WHEN** работают две реплики прежнего образа, и выполнен `make
rolling_update`
- **THEN** команда завершается с кодом 0, работают две реплики с новыми
`X-Instance-Id` на новом образе, обе `UP` в LB, а контейнеров прежних
реплик нет
#### Scenario: Замена под нагрузкой
- **WHEN** во время `make rolling_update` через LB с постоянной
интенсивностью идут запись с ключом и чтение истории
- **THEN** ни один ответ клиенту не ошибочен, в ответах сначала есть
только старые `X-Instance-Id`, затем старые и новые, затем только
новые, а число сообщений в чате равно числу отправленных ключей
#### Scenario: Стенд не готов к замене
- **WHEN** одна реплика остановлена `scripts/stop-one.sh`, или работает
не `API_REPLICAS` реплик
- **THEN** скрипт завершается с ненулевым кодом до сборки, называет
причину и предлагает `make replicas`, а контейнеры не меняются
#### Scenario: Слот остался в ручном состоянии
- **WHEN** слот LB без адреса оставлен в ручном обслуживании или
дренаже, и выполнен `make rolling_update`
- **THEN** скрипт завершается с ненулевым кодом до сборки, называет слот
и печатает команду, которая возвращает его в `ready`, а контейнеры не
меняются
### Requirement: Вывод реплики из балансировщика перед остановкой
Перед плановой остановкой реплики LB SHALL перестать направлять ей
новые запросы. Запросы, которые она уже обрабатывает, SHALL
дорабатываться. Остановка SHALL начинаться после того, как запросов в
полёте у неё не осталось, или по истечении срока ожидания. Срок SHALL
быть больше `timeout server` LB и больше наибольшей длительности живой
загрузки (требование «Загрузки через балансировщик»). Управление LB
SHALL быть доступно только изнутри контейнера LB. Из сети compose и с
хоста оно MUST NOT быть доступно.
Состояние слота, выставленное при замене, SHALL сниматься, когда адрес
удалённой реплики ушёл из слота. Слот, который потом получит новая
реплика, SHALL включаться по обычным проверкам готовности.
#### Scenario: Выведенная реплика не получает запросов
- **WHEN** слот реплики переведён в дренаж, и через LB идут запросы
- **THEN** все новые ответы приходят от других реплик, а запросы,
начатые до дренажа, получают ответ
#### Scenario: Управление LB недоступно из сети
- **WHEN** контейнер в сети стенда или процесс на хосте обращается к
портам LB
- **THEN** изменить состояние реплики он не может: канал управления LB
слушает только loopback внутри контейнера LB
#### Scenario: Слот после замены
- **WHEN** замена завершена
- **THEN** в статистике LB нет слотов в дренаже или в обслуживании,
выставленном вручную; свободные слоты — только в обслуживании по DNS
#### Scenario: Загрузка во время дренажа
- **WHEN** через LB идёт загрузка вложения, тело которой передаётся
дольше 12 с, и во время неё `make rolling_update` выводит реплику,
которая её принимает
- **THEN** загрузка получает 202 от этой реплики, и только после ответа
реплика останавливается
### Requirement: Сбой поочерёдной замены
Если новая реплика не стала готовой в LB за срок ожидания или замена
прервана раньше, скрипт SHALL удалить её и завершиться с ненулевым
кодом, в том числе когда её ID скрипту ещё не известен. Старые реплики,
которые ещё не заменены, SHALL остаться в работе.
Если замена прервана (Ctrl+C, ошибка) после того, как новая реплика
стала `UP`, скрипт SHALL довести вывод текущей старой реплики до
удаления. Только после этого он завершается.
В любом исходе SHALL работать `API_REPLICAS` готовых реплик. Слоты LB
SHALL быть без состояния, выставленного вручную. Реплики разных версий
допустимы: миграция совместима с обеими. Повторный запуск SHALL
доводить замену до конца.
#### Scenario: Новая реплика не готова
- **WHEN** новая реплика не стала `UP` в LB за срок ожидания
- **THEN** она удалена, скрипт завершился с ненулевым кодом и назвал
шаг, работают `API_REPLICAS` реплик, все `UP`, и запросы через LB
обслуживаются
#### Scenario: Прерывание при запуске новой реплики
- **WHEN** скрипт прерван Ctrl+C, пока compose создаёт новую реплику, и
её ID скрипту ещё не известен
- **THEN** новая реплика удалена, работают `API_REPLICAS` прежних
реплик, все `UP`, а слоты без ручного состояния
#### Scenario: Прерывание во время дренажа
- **WHEN** скрипт прерван Ctrl+C, пока старая реплика выводится из LB
- **THEN** старая реплика остановлена и удалена, новая работает,
реплик `API_REPLICAS`, а слот старой реплики без ручного состояния
### Requirement: Загрузки через балансировщик
Для `POST /api/v1/chats/{chat_id}/attachments` срок, в который LB ждёт
реплику (`timeout server`), SHALL быть 30 с. Это больше самого длинного
молчания живой загрузки:
- до чтения тела — вход, членство в чате и ожидание места загрузки, не
дольше `2 × [database] request_timeout_seconds + [uploads]
wait_timeout_seconds` (17 с);
- после тела — проверка изображения, запись метаданных, запись объекта в
staging, перевод в `queued` с заданием и удаление объекта при
компенсации, не дольше `2 × request_timeout_seconds + 2 × [s3]
timeout_seconds` плюс проверка изображения (около 26 с). Брокера на этом
пути нет.
У остальных путей срок SHALL оставаться прежним, 10 с: цепочка
таймаутов лабы 3 для них не меняется.
Наибольшая длительность живой загрузки — молчание до тела, срок
передачи тела (`[uploads] body_timeout_seconds`) и молчание после тела,
около 73 с при значениях по умолчанию. Она и формула SHALL быть в
`REPORT.md`.
Соединение с недочитанным телом SHALL держать в буферах ядра ограниченный
объём: буфер приёма сокетов реплики API — не больше 512 KiB, буфер
отправки LB к реплике — 256 KiB, буфер приёма LB от клиента — 128 KiB.
Так ожидающие и отклонённые загрузки не
переносят тела целиком ни в память реплики, ни в память LB.
#### Scenario: Долгая обработка загрузки
- **WHEN** реплика на пути загрузки молчит дольше 10 с, но меньше 30 с:
до чтения тела или после него
- **THEN** клиент получает ответ реплики, а не 502 или 504 от LB
#### Scenario: Прежний срок остальных путей
- **WHEN** реплика молчит дольше 10 с на любом другом пути
- **THEN** через ~10 с клиент получает 504 от LB в формате ошибки
контракта
#### Scenario: Загрузка дольше срока LB
- **WHEN** реплика на пути загрузки молчит дольше 30 с
- **THEN** через ~30 с клиент получает 504 от LB в формате ошибки
контракта
#### Scenario: Буферы соединений ограничены
- **WHEN** 40 клиентов одновременно загружают по 10 MiB через LB в одну
реплику с параметрами загрузок по умолчанию
- **THEN** пик памяти LB и буферов сокетов реплики растёт не больше чем
на 1 MiB на клиента, а реплика и LB не завершены из-за памяти