Files
mtusi2026lab3/openspec/changes/replicas-lb/specs/load-balancing/spec.md
T
ricoromaandClaude Opus 5.5 8e15e02898 docs: propose replicas-lb change
HAProxy as the single entry point, API replicas without published
ports, resource limits and per-service secrets, restart and stop-one
hooks, replica tests in student-tests.

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

14 KiB
Raw Blame History

Spec Delta

Purpose

Работа API за балансировщиком: одна точка входа, несколько взаимозаменяемых реплик без привязки клиента, проверка их готовности, безопасные повторы и сохранение чтения и записи при отказе любой одной реплики.

ADDED 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. Реплики 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 с. Таймаут проверки внутри /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 команда печатает по строке на каждый занятый слот реплики с её адресом и состоянием проверки, а порт статистики не опубликован на хосте