Files
mtusi2026lab2/openspec/specs/lab3-load-balancing/spec.md
T
ArtyomandClaude Opus 5.5 adb29a2afc Archive the asynchronous attachments change
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>
2026-10-29 01:31:34 +03:00

85 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` после прогона позже, чем до него