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