diff --git a/openspec/changes/add-lab3-load-balanced-replicas/.openspec.yaml b/openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/.openspec.yaml similarity index 58% rename from openspec/changes/add-lab3-load-balanced-replicas/.openspec.yaml rename to openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/.openspec.yaml index 1bb6456d..01fc7ab7 100644 --- a/openspec/changes/add-lab3-load-balanced-replicas/.openspec.yaml +++ b/openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/.openspec.yaml @@ -1,2 +1,4 @@ schema: spec-driven created: 2026-10-28 +archived: 2026-10-28 +lab: 3 diff --git a/openspec/changes/add-lab3-load-balanced-replicas/design.md b/openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/design.md similarity index 100% rename from openspec/changes/add-lab3-load-balanced-replicas/design.md rename to openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/design.md diff --git a/openspec/changes/add-lab3-load-balanced-replicas/proposal.md b/openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/proposal.md similarity index 100% rename from openspec/changes/add-lab3-load-balanced-replicas/proposal.md rename to openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/proposal.md diff --git a/openspec/changes/add-lab3-load-balanced-replicas/specs/lab1-messenger-history/spec.md b/openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/specs/lab1-messenger-history/spec.md similarity index 100% rename from openspec/changes/add-lab3-load-balanced-replicas/specs/lab1-messenger-history/spec.md rename to openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/specs/lab1-messenger-history/spec.md diff --git a/openspec/changes/add-lab3-load-balanced-replicas/specs/lab1-service-operability/spec.md b/openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/specs/lab1-service-operability/spec.md similarity index 100% rename from openspec/changes/add-lab3-load-balanced-replicas/specs/lab1-service-operability/spec.md rename to openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/specs/lab1-service-operability/spec.md diff --git a/openspec/changes/add-lab3-load-balanced-replicas/specs/lab2-persistent-storage/spec.md b/openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/specs/lab2-persistent-storage/spec.md similarity index 100% rename from openspec/changes/add-lab3-load-balanced-replicas/specs/lab2-persistent-storage/spec.md rename to openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/specs/lab2-persistent-storage/spec.md diff --git a/openspec/changes/add-lab3-load-balanced-replicas/specs/lab3-idempotent-messages/spec.md b/openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/specs/lab3-idempotent-messages/spec.md similarity index 100% rename from openspec/changes/add-lab3-load-balanced-replicas/specs/lab3-idempotent-messages/spec.md rename to openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/specs/lab3-idempotent-messages/spec.md diff --git a/openspec/changes/add-lab3-load-balanced-replicas/specs/lab3-load-balancing/spec.md b/openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/specs/lab3-load-balancing/spec.md similarity index 100% rename from openspec/changes/add-lab3-load-balanced-replicas/specs/lab3-load-balancing/spec.md rename to openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/specs/lab3-load-balancing/spec.md diff --git a/openspec/changes/add-lab3-load-balanced-replicas/tasks.md b/openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/tasks.md similarity index 100% rename from openspec/changes/add-lab3-load-balanced-replicas/tasks.md rename to openspec/changes/archive/2026-10-28-add-lab3-load-balanced-replicas/tasks.md diff --git a/openspec/specs/lab1-messenger-history/spec.md b/openspec/specs/lab1-messenger-history/spec.md index 309ff91f..a8c20c81 100644 --- a/openspec/specs/lab1-messenger-history/spec.md +++ b/openspec/specs/lab1-messenger-history/spec.md @@ -5,14 +5,19 @@ ## Requirements ### Requirement: Отправка сообщения -Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером. +Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`. #### Scenario: Сообщение отправлено -- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат +- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат с новым `Idempotency-Key` - **THEN** ответ `201`, тело соответствует схеме `Message` - **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным +#### Scenario: Ключ не передан + +- **WHEN** участник отправляет корректное тело без заголовка `Idempotency-Key` +- **THEN** ответ `400` с кодом `invalid_request` + #### Scenario: Отправитель не берётся из тела запроса - **WHEN** тело запроса содержит поле `sender_id` @@ -31,13 +36,13 @@ #### Scenario: Посторонний пишет в чужой чат -- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение +- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение с ключом - **THEN** ответ `404` с кодом `not_found` - **AND** сообщение не сохраняется #### Scenario: Доступ проверяется раньше содержимого -- **WHEN** посторонний отправляет в чужой чат тело, нарушающее схему +- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text` - **THEN** ответ `404`, а не `400` ### Requirement: Порядок истории diff --git a/openspec/specs/lab1-service-operability/spec.md b/openspec/specs/lab1-service-operability/spec.md index 41d83992..8bcaa26b 100644 --- a/openspec/specs/lab1-service-operability/spec.md +++ b/openspec/specs/lab1-service-operability/spec.md @@ -34,18 +34,28 @@ ### Requirement: Сквозной идентификатор запроса -Каждый ответ сервиса, включая ответы проб и ответы об ошибках, SHALL содержать непустой заголовок `X-Request-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое. +Каждый ответ сервиса, включая ответы проб, `204` выхода и ответы об ошибках (`404`/`405` неизвестного маршрута, `413`, `500` необработанного исключения), SHALL содержать непустые заголовки `X-Request-Id` и `X-Instance-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое. `X-Instance-Id` SHALL идентифицировать реплику (контейнер), а не отдельный процесс-воркер: значение SHALL быть одинаковым у всех процессов реплики, стабильным на всё время её жизни и SHALL совпадать с hostname контейнера, чтобы оператор мог сопоставить ответ с `docker ps`. #### Scenario: Идентификатор присутствует в любом ответе - **WHEN** выполняется любой запрос к сервису, успешный или ошибочный -- **THEN** ответ содержит непустой `X-Request-Id` +- **THEN** ответ содержит непустые `X-Request-Id` и `X-Instance-Id` #### Scenario: Клиентский идентификатор сохраняется - **WHEN** запрос содержит `X-Request-Id` с непустым значением - **THEN** ответ содержит то же значение +#### Scenario: Один идентификатор на реплику + +- **WHEN** реплика с несколькими процессами-воркерами обслуживает серию запросов +- **THEN** все её ответы несут одно и то же значение `X-Instance-Id`, равное hostname контейнера + +#### Scenario: Необработанное исключение несёт идентификаторы + +- **WHEN** обработка запроса завершается непредвиденным исключением +- **THEN** ответ `500` содержит `X-Request-Id` и `X-Instance-Id` + ### Requirement: Единый формат ошибки Ответ с кодом `4xx` или `5xx` SHALL иметь `Content-Type: application/json` и тело `{"error":{"code":...,"message":...,"request_id":...}}` без каких-либо дополнительных полей. `code` SHALL принимать значение из перечисления контракта, `request_id` SHALL совпадать со значением заголовка `X-Request-Id`. `message` SHALL быть непустым и SHALL NOT содержать stack trace, SQL, учётных данных, внутренних путей и сведений о существовании чужих объектов. @@ -69,12 +79,12 @@ ### Requirement: Корректное завершение по сигналу -По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую. +По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд; срок мягкой остановки сервера SHALL быть меньше `stop_grace_period` контейнера, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую. #### Scenario: Остановка укладывается в срок - **WHEN** запущенному контейнеру послан `SIGTERM` -- **THEN** процесс завершается не позднее чем через 10 секунд +- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period` - **AND** код завершения соответствует штатной остановке, а не убийству по таймауту #### Scenario: Принятый запрос дорабатывается @@ -112,8 +122,8 @@ #### Scenario: API доступен на опубликованном порту -- **WHEN** контейнер запущен с публикацией порта 8080 -- **THEN** `GET /health/ready` с хоста отвечает `200` +- **WHEN** стенд поднят командой `make up` +- **THEN** `GET /health/ready` с хоста через опубликованный порт балансировщика отвечает `200` #### Scenario: Процесс работает не от root diff --git a/openspec/specs/lab2-persistent-storage/spec.md b/openspec/specs/lab2-persistent-storage/spec.md index 2422a3e5..6b771aca 100644 --- a/openspec/specs/lab2-persistent-storage/spec.md +++ b/openspec/specs/lab2-persistent-storage/spec.md @@ -19,12 +19,12 @@ PostgreSQL SHALL хранить пользователей, сессии, чат ### Requirement: Версионируемые миграции -Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одноразовым процессом до старта API, одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой. +Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одним одноразовым процессом до старта реплик API, а не каждой репликой; одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой. Новая миграция SHALL быть аддитивной: работающая предыдущая версия API SHALL продолжать работать на схеме после неё. #### Scenario: Миграции с пустого volume - **WHEN** стенд поднимается на пустом volume PostgreSQL -- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартует API +- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартуют реплики API #### Scenario: Повторный запуск @@ -36,6 +36,11 @@ PostgreSQL SHALL хранить пользователей, сессии, чат - **WHEN** текст применённой миграции изменён и процесс миграций запущен - **THEN** процесс завершается ненулевым кодом и схему не трогает +#### Scenario: Реплики не мигрируют схему + +- **WHEN** стартует или перезапускается реплика API +- **THEN** она не применяет миграции; журнал версий меняет только процесс `migrate` + ### Requirement: Атомарное создание чата Создание чата SHALL записывать чат и всех его участников в одной транзакции. Если хотя бы одна запись нарушает ограничение, транзакция SHALL откатываться целиком: ни строки чата, ни строк участников не остаётся. @@ -48,12 +53,12 @@ PostgreSQL SHALL хранить пользователей, сессии, чат ### Requirement: Данные и сессии переживают рестарт -Пользователи, чаты, участники, сообщения и ещё действующие сессии SHALL сохраняться при перезапуске API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же. +Пользователи, чаты, участники, сообщения, ключи идемпотентности и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же. #### Scenario: Полный рестарт стенда - **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh` -- **THEN** hook перезапускает API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session` +- **THEN** hook перезапускает балансировщик, API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session` #### Scenario: Логаут после рестарта @@ -62,12 +67,17 @@ PostgreSQL SHALL хранить пользователей, сессии, чат ### Requirement: Воспроизводимый стенд из репозитория -Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck. Наружу SHALL публиковаться только API на `127.0.0.1:8080`. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, и SHALL NOT появляться в Git, образе и журнале. +Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на `127.0.0.1` (порт HTTP и порт статистики); PostgreSQL, Valkey и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны, и SHALL NOT появляться в Git, образе и журнале. #### Scenario: Подъём из чистого clone - **WHEN** в чистом clone выполняются `make secrets` и `make up` -- **THEN** все сервисы становятся `healthy` или завершаются кодом 0, а `GET /health/ready` отвечает `200` +- **THEN** все сервисы становятся `healthy` или завершаются кодом 0, а `GET /health/ready` через балансировщик отвечает `200` + +#### Scenario: Опубликован только балансировщик + +- **WHEN** выполняется `docker compose ps --format '{{.Service}} {{.Ports}}'` +- **THEN** опубликованные порты есть только у сервиса `lb` и все они привязаны к `127.0.0.1` #### Scenario: Секреты и volumes вне Git diff --git a/openspec/specs/lab3-idempotent-messages/spec.md b/openspec/specs/lab3-idempotent-messages/spec.md new file mode 100644 index 00000000..d4728d35 --- /dev/null +++ b/openspec/specs/lab3-idempotent-messages/spec.md @@ -0,0 +1,81 @@ +# lab3-idempotent-messages Specification + +## Purpose +Определяет идемпотентную отправку сообщения через `Idempotency-Key`: формат и область ключа, повтор и конфликт, срок хранения результата, атомарность записи и поведение при конкурентном повторе через разные реплики и при неопределённом исходе. +## Requirements +### Requirement: Обязательный ключ идемпотентности + +`POST /api/v1/chats/{chat_id}/messages` SHALL требовать заголовок `Idempotency-Key` длиной 1–128 символов из `[A-Za-z0-9._:-]`. Отсутствующий или не соответствующий формату ключ SHALL давать `400` с кодом `invalid_request` в общем формате ошибки; сообщение при этом SHALL NOT сохраняться. Остальные endpoint SHALL NOT требовать ключ. + +#### Scenario: Ключ отсутствует + +- **WHEN** участник отправляет корректное сообщение без `Idempotency-Key` +- **THEN** ответ `400` с кодом `invalid_request`, история чата не меняется + +#### Scenario: Ключ неверного формата + +- **WHEN** `Idempotency-Key` пустой, длиннее 128 символов или содержит пробел, `/` или не-ASCII символ +- **THEN** ответ `400` с кодом `invalid_request` + +### Requirement: Повтор возвращает исходный результат + +Область ключа SHALL составлять пользователь сессии, метод и путь чата и сам ключ. Повтор с тем же ключом и семантически тем же JSON (порядок полей не важен) в течение `IDEMPOTENCY_TTL_SECONDS` (не меньше 86 400 с) SHALL возвращать `201` и тот же объект `Message` — те же `id`, `text` и строку `created_at` — без создания нового сообщения. Тот же ключ с другим JSON SHALL давать `409` с кодом `conflict`. Одинаковый ключ у разных пользователей или в разных чатах SHALL действовать независимо. После истечения срока ключ SHALL приниматься как новый. + +#### Scenario: Повтор того же тела + +- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":...}` +- **THEN** ответ `201`, тело равно телу первого ответа целиком, в истории одно такое сообщение + +#### Scenario: Тот же ключ, другое тело + +- **WHEN** участник повторяет `POST` с тем же ключом, но другим `text` +- **THEN** ответ `409` с кодом `conflict`, новое сообщение не создаётся + +#### Scenario: Тот же ключ у другого пользователя + +- **WHEN** другой участник того же чата отправляет сообщение с тем же значением ключа +- **THEN** ответ `201` с новым сообщением этого участника + +#### Scenario: Тот же ключ в другом чате + +- **WHEN** участник отправляет в другой свой чат сообщение с уже использованным ключом +- **THEN** ответ `201` с новым сообщением в этом чате + +#### Scenario: Срок ключа истёк + +- **WHEN** с момента первой отправки прошло больше `IDEMPOTENCY_TTL_SECONDS` и участник отправляет с тем же ключом другой текст +- **THEN** ответ `201` с новым сообщением, а не `409` + +### Requirement: Повтор заново проверяет доступ + +Повтор с известным ключом SHALL снова проверять сессию и членство в чате до выдачи сохранённого результата: отозванный или истёкший токен SHALL получать `401`, посторонний — `404`. Ответы `4xx` и `5xx` SHALL NOT сохраняться как результат ключа: после такого ответа повтор с тем же ключом обрабатывается как первая попытка. + +#### Scenario: Повтор после выхода + +- **WHEN** пользователь отправил сообщение, вышел и повторил запрос с тем же ключом и прежним токеном +- **THEN** ответ `401` + +#### Scenario: Ошибка не занимает ключ + +- **WHEN** участник отправил с ключом `K` пустой текст и получил `400`, затем отправил с ключом `K` корректный текст +- **THEN** второй ответ `201` с новым сообщением + +#### Scenario: Посторонний с чужим ключом + +- **WHEN** посторонний отправляет в чат запрос с ключом, уже использованным участником +- **THEN** ответ `404`, сохранённое сообщение не раскрывается + +### Requirement: Атомарная и общая для реплик идемпотентность + +Сообщение и запись ключа SHALL фиксироваться одной транзакцией PostgreSQL: либо сохраняются оба, либо ни одно. Одновременные запросы с одним ключом и одним телом, пришедшие на разные реплики, SHALL создавать ровно одно сообщение, и каждый из них SHALL получать `201` с одинаковым `Message`. Если исход первой попытки неизвестен клиенту (обрыв, таймаут, остановка реплики), повтор с тем же ключом SHALL возвращать уже сохранённое сообщение либо, если транзакция не была зафиксирована, создавать его ровно один раз. + +#### Scenario: Конкурентный повтор через разные реплики + +- **WHEN** 8 параллельных `POST` с одним ключом и одним телом отправлены через LB +- **THEN** все ответы `201` с одинаковым телом, ответы пришли от ≥2 реплик, в истории чата ровно одно такое сообщение + +#### Scenario: Повтор после отказа реплики + +- **WHEN** во время `make test-failover` запрос не получил ответа и повторён с тем же ключом и текстом +- **THEN** в истории нет дублей по `id` и `text`, а каждый подтверждённый ответ совпадает с записью истории байт-в-байт + diff --git a/openspec/specs/lab3-load-balancing/spec.md b/openspec/specs/lab3-load-balancing/spec.md new file mode 100644 index 00000000..0cc58663 --- /dev/null +++ b/openspec/specs/lab3-load-balancing/spec.md @@ -0,0 +1,84 @@ +# lab3-load-balancing Specification + +## Purpose +Определяет развёртывание API несколькими взаимозаменяемыми репликами за единственной публичной точкой входа: что видно клиенту, как балансировщик выбирает и исключает реплики, какие запросы он вправе повторить и как оператор останавливает одну реплику и перезапускает стенд. +## Requirements +### Requirement: Единственная точка входа и не менее двух реплик + +Стенд SHALL описываться одним `compose.yaml` и запускаться документированной командой. API SHALL работать не менее чем двумя репликами одного compose-service без `container_name`; их число SHALL задаваться `API_REPLICAS` (по умолчанию 2). Наружу SHALL публиковаться только балансировщик на `127.0.0.1`; порты реплик API SHALL NOT публиковаться. Все реплики SHALL использовать одну общую PostgreSQL и одно общее хранилище сессий. + +#### Scenario: Стенд поднят + +- **WHEN** выполняется `make up`, затем `docker compose ps` +- **THEN** работают ≥2 контейнера сервиса `api` в состоянии `healthy`, у них нет опубликованных портов, а единственные опубликованные порты принадлежат сервису `lb` + +#### Scenario: Реплика недоступна в обход балансировщика + +- **WHEN** с хоста выполняется запрос на порт 8080 контейнера реплики +- **THEN** соединение не устанавливается: реплика слушает только внутреннюю сеть + +### Requirement: Разные реплики на одной сессии + +Балансировщик SHALL распределять новые соединения по готовым репликам без привязки клиента (sticky session). Реплика SHALL NOT хранить в памяти процесса сессии, ключи идемпотентности и другое состояние, от которого зависит ответ другой реплики: токен, выданный через одну реплику, SHALL приниматься любой другой, а отзыв сессии SHALL действовать на всех репликах сразу. + +#### Scenario: Один токен, несколько реплик + +- **WHEN** клиент с одним Bearer-токеном выполняет 40 запросов `GET /api/v1/users/me`, каждый новым соединением через LB +- **THEN** все ответы `200`, а заголовок `X-Instance-Id` принимает не менее двух разных значений + +#### Scenario: Выход действует на всех репликах + +- **WHEN** пользователь выполнил `DELETE /api/v1/auth/sessions/current` через одну реплику +- **THEN** следующий запрос с этим токеном получает `401` независимо от того, какая реплика его обслужила + +### Requirement: Готовность backend и обновление адресов + +Балансировщик SHALL активно проверять каждую реплику запросом `GET /health/ready` и SHALL исключать из ротации реплику, которая не отвечает `200`. Адреса реплик SHALL обновляться через DNS без перезапуска балансировщика: остановленная реплика исчезает из ротации, запущенная или пересозданная появляется сама. Ответы, сформированные самим балансировщиком (`502`, `503`, `504`), SHALL иметь тело в общем формате ошибки с `request_id`, равным заголовку `X-Request-Id`. + +#### Scenario: Реплика возвращается в ротацию + +- **WHEN** остановленная реплика снова запущена +- **THEN** после успешных проверок готовности балансировщик снова направляет на неё запросы без перезапуска `lb` + +#### Scenario: Нет ни одной готовой реплики + +- **WHEN** все реплики API остановлены +- **THEN** запрос через LB получает `503` с телом `{"error":{"code":"unavailable",...}}` + +### Requirement: Повтор запросов балансировщиком + +Балансировщик SHALL повторять на другой реплике запрос, который не удалось отправить из-за отказа соединения. Повтор после того, как запрос мог быть обработан, SHALL допускаться только для `GET` и для `POST /api/v1/chats/{chat_id}/messages` с `Idempotency-Key`. Балансировщик SHALL NOT прозрачно повторять `POST /api/v1/users`, `POST /api/v1/chats` и `POST /api/v1/auth/sessions`. + +#### Scenario: Создание чата не повторяется + +- **WHEN** реплика оборвала соединение во время `POST /api/v1/chats` +- **THEN** клиент получает ошибку балансировщика, а не результат повторной отправки на другую реплику + +### Requirement: Остановка одной реплики + +Оператор SHALL иметь исполняемый хук `scripts/stop-one.sh`, который по переменной `TARGET_INSTANCE_ID` находит контейнер реплики с этим `X-Instance-Id`, останавливает только его с сохранением остальных сервисов и volumes, оставляет остановленным и завершается кодом 0 быстрее 10 секунд. Неизвестный идентификатор SHALL давать ненулевой код без остановки чего-либо. Не позднее 10 секунд от запуска хука SHALL продолжаться новые чтения и записи через LB, а подтверждённые сообщения SHALL оставаться доступными. Хук `scripts/restore.sh` SHALL возвращать остановленные реплики и ждать, пока балансировщик снова видит их готовыми. + +#### Scenario: Отказ реплики под запросами + +- **WHEN** выполняется `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` +- **THEN** тест печатает `PASS: failover preserved confirmed data and existing session`, хук завершился быстрее 10 с, первая успешная запись после хука пришла не позже 10 с от его старта, остановленная реплика больше не отвечает, а `docker ps -a` показывает именно её контейнер в состоянии `exited` + +#### Scenario: Вторая реплика + +- **WHEN** после `scripts/restore.sh` тест повторяется и целью становится другая реплика +- **THEN** тест снова проходит + +#### Scenario: Неизвестная реплика + +- **WHEN** хук запущен с `TARGET_INSTANCE_ID`, которому не соответствует ни один контейнер `api` +- **THEN** хук завершается ненулевым кодом, и все контейнеры продолжают работать + +### Requirement: Рестарт стенда + +Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, PostgreSQL и Valkey с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд снова готов. + +#### Scenario: Полный рестарт сохраняет сессию + +- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh` +- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `postgres` и `valkey` после прогона позже, чем до него +