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