Files
mtusi2026lab2/openspec/specs/lab3-load-balancing/spec.md
T
ArtyomandClaude Opus 5.5 a0d3947710 Carry over the agent context and openspec history from lab 5
Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 to lab 5 specs and the
archived lab 1 to lab 5 changes into the lab 6 skeleton, so lab 6
continues the same spec history instead of starting from scratch. The
files come from the lab 5 solution commit 64d5c67.

Rewrite AGENTS.md and the openspec context and rules for lab 6: the
business API stays at contract 1.6.0, API, relay and worker start the
OpenTelemetry SDK in every process after fork and export OTLP over HTTP
to a separate Collector, Prometheus, Loki and Tempo store metrics, logs
and traces on volumes, Grafana only reads them through provisioning
kept in Git, telemetry never blocks a request and never feeds
/health/ready, metric labels stay low-cardinality and message bodies
and secrets never leave the process. Out of scope moves to lab 7,
track 2 and clustered telemetry backends.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-29 03:46:20 +03:00

9.2 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

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, relay, worker, 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, relay, worker, postgres, valkey, s3 и broker после прогона позже, чем до него