Grade 3 of lab 5 is closed. Upload answers 202 queued only after the original is staged in the private bucket and the attachment, its job and the outbox row are committed together; a separate relay publishes the outbox to a durable quorum queue with publisher confirms and returns expired leases; a separate FastStream worker claims a job under a lease, publishes the original and the 256 px JPEG thumbnail, commits fenced by the lease token and acks only after the commit. Transient errors retry up to JOB_MAX_ATTEMPTS and end in retry_exhausted, undecodable images fail at once with invalid_image, and a redelivered job changes nothing. The defence demonstration (worker down, upload, message, API, relay and broker restarts, worker up, ready) and the lab 4 minimum pass on a stand raised from empty volumes. The lab5-attachment-pipeline and lab5-job-delivery capabilities join the main specs, and the upload, content, message and restart requirements of lab 1, lab 3 and lab 4 are updated in place. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
9.2 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
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после прогона позже, чем до него