Files
mtusi2026lab2/openspec/specs/lab3-load-balancing/spec.md
T
ArtyomandClaude Opus 5.5 8cd30488d2 Archive the carry over of the lab 3 fixes change
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
2026-10-30 06:25:44 +03:00

9.5 KiB
Raw Blame History

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) сразу видит ≥2 X-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 после прогона позже, чем до него