# 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`, а слот старой реплики без ручного состояния