Files
mtusi2026lab2/openspec/specs/lab3-load-balancing/spec.md
T
ArtyomandClaude Opus 5.5 e4253eb076 Archive the image attachments change
Grade 3 of lab 4 is closed. RustFS with a private bucket runs in the
stand, metadata lives in PostgreSQL and the bytes only in the bucket,
uploads answer 201 ready after the object write and the commit, and
the original is served byte for byte to chat members only. The smoke
test passes from a fresh clone; limits of 10 MiB and 40 MP, content
type by content and dangerous names are covered by 325 own tests; an
upload survives the stop of the replica that took it, both replicas
fail over under writes in under 3.1 s, a full restart keeps metadata
and bytes, and with S3 stopped uploads and downloads answer 503 within
2.6 s while texts, metadata and readiness keep working. 22 checks show
the bucket is private outside the API and the API key is limited.

For the defence: upload the fixture, send it in a message, download it
as the second member and compare SHA-256, get 404 as a stranger and
403 for an anonymous GET in S3, then run persistence, failover and the
upload failover scenario.

The lab4-attachments and lab4-object-storage specs are added, and
message sending, history, idempotent replay, the restart hook and stand
persistence are updated in the main specs.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-28 22:20:38 +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, 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 после прогона позже, чем до него