Grade 3 of lab 3 is closed: the stand runs two API replicas of one compose service behind HAProxy as the only published entry point, one token reaches both replicas by X-Instance-Id, stopping either replica with scripts/stop-one.sh keeps writes going within 1.2-1.7 s without errors or duplicates, eight concurrent posts with one key give one message, and make test, the persistence scenario with scripts/restart.sh, the failover scenario, lint, own tests, check, validate and the lab 2 stack fault tests pass. The new lab3-load-balancing and lab3-idempotent-messages specs are synced, and the lab 1 history and operability specs and the lab 2 storage spec carry their deltas. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
85 lines
9.0 KiB
Markdown
85 lines
9.0 KiB
Markdown
# 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` после прогона позже, чем до него
|
||
|