Files
mtusi2026lab3/openspec/specs/lab3-load-balancing/spec.md
T
ArtyomandClaude Opus 5.5 8d28d45d55 Archive the load-balanced replicas and idempotent messages change
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>
2026-10-28 11:53:26 +03:00

85 lines
9.0 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.
# 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` после прогона позже, чем до него