Sync the delta specs into the main specs: zones are linked by the schema and the ports main.py assembles, the event bus and the network dependencies name S3 and Valkey, an outsider does not wait for chat locks, an empty cursor is rejected, a request cancelled at shutdown gets 503 in the contract format, the body limit counts received bytes per route, logout withdraws the revocation mark on a database failure, detection runs three times, failover-each records the stopped replica, lost answers are retried on the stand, posting checks its input in a fixed order and make up waits for every replica in the balancer. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
9.5 KiB
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 - AND к завершению
make upстатистика балансировщика показываетUPу всех запущенных реплик, поэтому следующая команда (например,make test-failover) сразу видит ≥2X-Instance-Id
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 и S3-сервер с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд, включая S3, снова готов: первое же чтение метаданных и байтов вложения после хука SHALL проходить без повторов.
Scenario: Полный рестарт сохраняет сессию
- WHEN выполняется
make test-persistence ACTION_SCRIPT=scripts/restart.sh - THEN тест печатает
PASS: persistence preserved confirmed data and existing session, аStartedAtконтейнеровlb,api,postgres,valkeyиs3после прогона позже, чем до него