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

230 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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** команда печатает по строке на каждый занятый слот реплики с
её адресом и состоянием проверки, а порт статистики не опубликован на
хосте