Files
mtusi2026lab3/openspec/specs/load-balancing/spec.md
T
ricoromaandClaude Opus 5.5 c50b7211b8 chore: archive graceful-failover change
Delta specs synced into graceful-shutdown, load-balancing, load-benchmark
and service-configuration; the change moves to
openspec/changes/archive/2026-10-11-graceful-failover/. PLAN.md marks the
change archived and AGENTS.md notes what was handed to rolling-update.

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

20 KiB
Raw Blame History

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, в чате ровно одно сообщение с этим текстом, а после разморозки реплика снова обслуживает запросы