HAProxy 3.4 is the only published entry point; api runs as API_REPLICAS replicas without ports, found through Docker DNS and checked on /health/ready. Retries only on connection failure, LB errors in the contract error format, resource limits and per-service secrets. Adds scripts/stop-one.sh, LB-aware restart.sh, make replicas / instances / lb_stats and replica tests driven by EXPECT_REPLICAS. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
230 lines
15 KiB
Markdown
230 lines
15 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. Реплики 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** команда печатает по строке на каждый занятый слот реплики с
|
||
её адресом и состоянием проверки, а порт статистики не опубликован на
|
||
хосте
|