Sync the rolling-update delta specs into db-migrations, graceful-shutdown, load-balancing and load-benchmark, move the change to the archive, mark it in PLAN.md and update the transitional state and code map in AGENTS.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
459 lines
29 KiB
Markdown
459 lines
29 KiB
Markdown
# 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 иметь статус 502, 503 или 504 и
|
||
тело в формате ошибки контракта с `code` `unavailable`. Такие ответы
|
||
возникают, когда нет готовых реплик, ответ реплики оборвался или не
|
||
пришёл вовремя. `request_id` тела SHALL совпадать с заголовком
|
||
`X-Request-Id`, который ставит LB. `X-Instance-Id` у таких ответов
|
||
может отсутствовать.
|
||
|
||
#### Scenario: Нет готовых реплик
|
||
|
||
- **WHEN** все реплики API остановлены, и клиент запрашивает
|
||
`/health/ready` через LB
|
||
- **THEN** ответ 503 с телом `{"error": {"code": "unavailable", ...}}`,
|
||
`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 начинаться после того, как запросов в
|
||
полёте у неё не осталось, или по истечении срока ожидания, большего
|
||
`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
|
||
|
||
### 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`, а слот старой реплики без ручного состояния
|