- carry the lab 3 solution over from mtusi2026lab3-safronov (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests, bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts, Dockerfile, compose, pyproject and uv lock - merge Makefile, .gitignore and .dockerignore (the lab 3 versions only add lines to the skeleton, which is the same in lab 4) and .env.example (lab 4 skeleton names listed in the header) - rename the compose project to mtusi-lab4 and the image to :lab4 so the stand does not reuse the lab 3 containers and volumes - update AGENTS.md for lab 4: current lab, origin commit, contract and test files of the new skeleton Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
29 KiB
load-balancing Specification
Purpose
Работа API за балансировщиком: одна точка входа, несколько взаимозаменяемых реплик без привязки клиента, проверка их готовности, безопасные повторы и сохранение чтения и записи при отказе любой одной реплики.
Requirements
Requirement: Единая точка входа
Стенд SHALL принимать запросы клиентов в одной точке — балансировщике
(LB), опубликованном на 127.0.0.1:${APP_OUT_PORT}. Реплики API MUST
NOT публиковать порты на хосте и MUST NOT иметь фиксированного имени
контейнера. Ответы реплик SHALL проходить через LB без замены
заголовков X-Request-Id и X-Instance-Id и тела.
Scenario: Порт только у балансировщика
- WHEN стенд запущен
make run_docker, и выполненdocker compose ps - THEN у контейнеров
apiнет опубликованных портов, у них нет заданногоcontainer_name, а API на хосте доступно только через порт LB на127.0.0.1
Requirement: Взаимозаменяемые реплики
Сервис API SHALL запускаться в числе реплик API_REPLICAS, по
умолчанию 2. Это значение читают compose и Makefile, приложение MUST
NOT его читать. Реплики SHALL быть
одинаковыми: один образ, одна конфигурация, общие PostgreSQL и Valkey.
В памяти процесса MUST NOT быть состояния, от которого зависит
корректность ответа. Изменение числа реплик MUST NOT требовать правки
конфигурации LB. LB SHALL обслуживать до 8 реплик.
Scenario: Две реплики по умолчанию
- WHEN выполнен
make run_dockerбезAPI_REPLICASв.env - THEN работают два контейнера
apiс разнымиX-Instance-Id, и оба получают запросы через LB
Scenario: Масштабирование без правки балансировщика
- WHEN выполнен
make replicas API_REPLICAS=3, а конфигурация LB не менялась - THEN не позже чем через 10 с запросы через LB обслуживают три
разных
X-Instance-Id
Requirement: Распределение без привязки клиента
LB SHALL распределять запросы по готовым репликам по очереди, независимо от соединения, сессии и cookie клиента. Привязка клиента к реплике (sticky session) MUST NOT использоваться. Запросы одной сессии SHALL обслуживаться разными репликами без повторного входа. Подтверждённое сообщение SHALL быть видно следующему чтению через любую реплику.
Scenario: Одна сессия на разных репликах
- WHEN пользователь вошёл один раз и выполняет 20 запросов
GET /api/v1/users/meс одним токеном через LB - THEN все ответы 200 с этим пользователем, а
X-Instance-Idпринимает не меньше двух разных значений
Scenario: Запись видна через другую реплику
- WHEN сообщение отправлено через LB, затем история чата читается несколько раз подряд
- THEN каждое чтение содержит это сообщение, в том числе чтения
с другим
X-Instance-Id, чем у отправки
Scenario: Распределение видно оператору
- WHEN выполнен
make instances - THEN команда входит одним синтетическим пользователем, выполняет
серию запросов с одним токеном и печатает
X-Instance-Idкаждого ответа и число ответов каждой реплики
Requirement: Проверка готовности реплик
LB SHALL активно проверять каждую реплику запросом
GET /health/ready. SHALL быть заданы явно:
- период проверок;
- период повторной проверки после первой неудачи и до возврата;
- число неудач до исключения и успехов до возврата;
- таймаут проверки.
Реплика, которая не проходит проверки, SHALL исключаться из распределения: она остановлена, не отвечает или отвечает 503. Вернувшаяся реплика SHALL включаться без перезапуска LB.
Время обнаружения отказа по проверкам MUST NOT превышать 10 с. Худший
случай — у реплики, которая принимает соединение, но не отвечает:
период плюс таймаут проверки, затем ещё (число неудач − 1) раз период
повторной проверки плюс таймаут. Таймаут проверки внутри
/health/ready SHALL быть меньше таймаута проверки LB.
Scenario: Остановленная реплика исключена
- WHEN одна из двух реплик остановлена
- THEN не позже чем через 10 с статистика LB показывает её не в
состоянии
UP, и запросы через LB обслуживает только оставшаяся
Scenario: Вернувшаяся реплика включена
- WHEN остановленная реплика запущена снова
- THEN не позже чем через 10 с после её готовности статистика LB
показывает её
UP, и запросы снова распределяются по обеим
Requirement: Повтор только при отказе соединения
LB SHALL повторять запрос на другой реплике, только если соединение с
репликой не установлено, то есть запрос до неё не дошёл. Такой повтор
безопасен для любого метода. Запрос, который реплика уже получила, MUST
NOT повторяться LB: ни по таймауту ответа, ни по обрыву ответа, ни по
ответу 5xx. Причина — POST /users и POST /chats не идемпотентны.
Отправку сообщения повторяет клиент, с тем же Idempotency-Key.
Произведение таймаута соединения LB на число попыток SHALL быть меньше
2 с: перенаправление должно успеть раньше таймаута клиента публичной
проверки.
Scenario: Отказ соединения перенаправлен
- WHEN реплика закрыла приёмный сокет (
docker stop), а LB ещё не исключил её по проверкам - THEN запрос, направленный на неё, LB передаёт другой реплике, и клиент получает ответ API, а не ошибку LB
Scenario: Оборванный ответ не повторяется
- WHEN процесс реплики убит (
docker kill), пока она обрабатывает запрос - THEN клиент получает ошибку LB, а журнал LB показывает, что запрос на другую реплику не повторялся
Requirement: Ошибки балансировщика в формате контракта
Ответы, которые создаёт сам LB, SHALL иметь статус 502, 503 или 504 и
тело в формате ошибки контракта с code unavailable. Такие ответы
возникают, когда нет готовых реплик, ответ реплики оборвался или не
пришёл вовремя. request_id тела SHALL совпадать с заголовком
X-Request-Id, который ставит LB. X-Instance-Id у таких ответов
может отсутствовать.
Scenario: Нет готовых реплик
- WHEN все реплики API остановлены, и клиент запрашивает
/health/readyчерез LB - THEN ответ 503 с телом
{"error": {"code": "unavailable", ...}},request_idравенX-Request-Id, а других полей в теле нет
Requirement: Отказ одной реплики
При остановке любой одной реплики из двух и более новые чтения и
записи через LB SHALL проходить снова не позже чем через 10 с от
начала остановки. Подтверждённые сообщения SHALL оставаться
доступными. Повтор неподтверждённой отправки с тем же ключом MUST NOT
создавать дубль. Ошибки переходного периода допустимы и SHALL
учитываться. Публичная проверка make test-failover ACTION_SCRIPT=scripts/stop-one.sh SHALL проходить для каждой реплики,
если предыдущая перед этим восстановлена.
Scenario: Штатная остановка каждой реплики
- WHEN
make test-failover ACTION_SCRIPT=scripts/stop-one.shвыполнен, затем реплики восстановлены, и проверка повторена так, чтобы остановленной оказалась другая реплика - THEN оба прогона печатают
PASS, первая успешная запись после начала остановки — не позже 10 с, дублей нет
Scenario: Отказ процесса без graceful
- WHEN та же проверка выполнена с
STOP_MODE=kill - THEN она печатает
PASS: оборванные запросы учтены как неудачные попытки, повтор с тем же ключом не создаёт дубль
Requirement: Failover hook
scripts/stop-one.sh SHALL останавливать ровно одну работающую
реплику API этого проекта compose — ту, чей контейнер соответствует
TARGET_INSTANCE_ID (значению X-Instance-Id). Скрипт SHALL
возвращать 0 не позже чем через 10 с. Режим задаёт STOP_MODE:
stop (по умолчанию, SIGTERM и graceful) или kill (SIGKILL).
Остановленная реплика SHALL оставаться остановленной, несмотря на
политику перезапуска контейнера. Восстановление — отдельной командой
make replicas.
Если значение не соответствует ни одной работающей реплике API этого проекта, скрипт SHALL завершаться с ненулевым кодом и ничего не останавливать. PostgreSQL, Valkey, LB, контейнеры других проектов и volumes скрипт MUST NOT трогать. Секреты он MUST NOT печатать.
Scenario: Остановка по instance id
- WHEN
scripts/stop-one.shвыполнен сTARGET_INSTANCE_ID, равнымX-Instance-Idодной из реплик - THEN скрипт вернул 0 быстрее 10 с,
docker compose ps -aпоказывает остановленным контейнер, ID которого начинается сTARGET_INSTANCE_ID, а остальные контейнеры стенда работают с прежним временем старта
Scenario: Чужой или неизвестный id
- WHEN
TARGET_INSTANCE_IDпуст, имеет недопустимый формат, указывает на контейнер PostgreSQL, Valkey или LB этого стенда либо не соответствует ни одному контейнеру - THEN скрипт завершается с ненулевым кодом, и ни один контейнер не остановлен
Scenario: Реплика не поднимается сама
- WHEN реплика остановлена скриптом в режиме
stopилиkill, и прошло 15 с - THEN контейнер всё ещё остановлен, и его
X-Instance-Idне встречается в ответах через LB
Scenario: Восстановление реплик
- WHEN после остановки реплики выполнен
make replicas - THEN работают
API_REPLICASреплик, остановленный контейнер запущен снова с тем же ID, и не позже чем через 10 с LB снова распределяет запросы по всем репликам
Requirement: Статистика балансировщика внутри сети
LB SHALL отдавать статистику по каждой реплике: состояние проверки,
число запросов, повторы, очередь. Статистика SHALL быть доступна только
внутри сети compose; на хост она MUST NOT публиковаться. Оператор SHALL
получать её одной командой make lb_stats.
Scenario: Состояние реплик
- WHEN стенд запущен, и выполнен
make lb_stats - THEN команда печатает по строке на каждый занятый слот реплики с её адресом и состоянием проверки, а порт статистики не опубликован на хосте
Requirement: Время обнаружения отказа
Время от действия над репликой до её исключения LB SHALL измеряться под нагрузкой для трёх режимов:
stop— SIGTERM и graceful shutdown;kill— SIGKILL, отказ процесса;pause— процесс заморожен: соединение принимается, ответа нет.
Действие, смена состояния реплики в LB и ответы клиенту SHALL
сопоставляться на одних часах. Каждое измерение MUST NOT превышать
худший случай формулы проверок своего режима и 10 с. Формула и
измерения по режимам SHALL быть в REPORT.md.
Scenario: Остановка и убитый процесс
- WHEN реплика остановлена
docker stopили убитаdocker killпод нагрузкой - THEN журнал LB показывает её
DOWNили в обслуживании не позже худшего случая формулы для недоступного адреса, а время от действия записано в результаты профиляfailover
Scenario: Зависшая реплика
- WHEN процесс реплики заморожен
docker pauseпод нагрузкой - THEN LB исключает реплику не позже худшего случая формулы и 10 с, а запросы, уже отправленные на неё, получают 504 от LB в формате ошибки контракта
Requirement: Отказ реплики под нагрузкой
Каждая реплика по очереди SHALL останавливаться посреди нагрузки с постоянной интенсивностью (запись с ключом и чтение истории), затем восстанавливаться перед остановкой следующей. Для каждой остановки SHALL измеряться посекундно:
- успешные ответы в секунду;
- ошибки по кодам;
- доля успешных ответов;
- распределение ответов по
X-Instance-Id.
Время восстановления — от действия до момента, после которого доля успешных ответов в каждой секунде не ниже 99 %. Оно MUST NOT превышать 10 с. Возврат реплики MUST NOT давать ошибок клиенту.
Scenario: Каждая реплика в каждом режиме
- WHEN профиль
failoverостанавливает по очереди каждую из двух реплик в режимахstopиkill, восстанавливая предыдущую - THEN для каждой остановки есть посекундная шкала, время обнаружения и время восстановления не больше 10 с, а после возврата реплики ошибок нет
Scenario: Ответы распределяются снова
- WHEN остановленная реплика восстановлена посреди нагрузки
- THEN не позже чем через 10 с её
X-Instance-Idснова есть в ответах, и ошибок за это время нет
Requirement: Транзакции зависшей реплики
Открытую транзакцию реплики, процесс которой заморожен, PostgreSQL
SHALL прерывать после простоя [database] idle_in_transaction_timeout_ms. Блокировки этой транзакции, в том
числе строки ключа идемпотентности, SHALL сниматься. Срок SHALL быть
больше [database] request_timeout_seconds: транзакция живой реплики
дольше этого срока не живёт, и прерывание её не задевает. Повтор
неподтверждённой отправки с тем же ключом через другую реплику SHALL
получать 201 после прерывания. В чате при этом SHALL оставаться одно
сообщение.
Scenario: Простой в транзакции
- WHEN соединение приложения открыло транзакцию и простаивает
дольше
idle_in_transaction_timeout_ms - THEN PostgreSQL прерывает это соединение, а его журнал называет причину — простой в транзакции
Scenario: Повтор ключа после зависшей реплики
- WHEN реплика заморожена посреди отправки сообщения с ключом K, пока её транзакция держит K, а клиент повторяет ту же отправку с K через LB
- THEN после прерывания транзакции повтор получает 201, в чате ровно одно сообщение с этим текстом, а после разморозки реплика снова обслуживает запросы
Requirement: Поочерёдная замена реплик
Команда make rolling_update (scripts/rolling-update.sh) SHALL
заменять работающие реплики API на образ из текущего checkout по одной,
без остановки обслуживания. Порядок:
- сборка образа;
- миграции, один раз (
db-migrations); - для каждой старой реплики:
- рядом запускается одна новая;
- скрипт ждёт её готовности и состояния
UPв статистике LB; - старая выводится из LB, дорабатывает запросы, останавливается и удаляется.
Реплик одновременно SHALL быть не больше API_REPLICAS + 1. Число
должно помещаться в слоты LB. Правка конфигурации LB и его перезапуск
MUST NOT требоваться.
После успешной замены SHALL работать ровно API_REPLICAS реплик. Все
они SHALL быть на новом образе и в состоянии UP в LB. Контейнеров
прежнего образа SHALL не остаться ни работающих, ни остановленных.
Под постоянной нагрузкой через LB (запись с ключом и чтение истории) замена MUST NOT давать клиенту ошибок. Каждая подтверждённая запись SHALL оставаться доступной.
Перед заменой скрипт SHALL проверять стенд:
- работает ровно
API_REPLICASреплик; - остановленных реплик нет;
- все реплики
UPв LB; - для ещё одной реплики есть свободный слот LB;
- нет слотов LB в ручном дренаже или обслуживании, которое оставила прерванная замена.
Если условие не выполнено, скрипт SHALL завершаться с ненулевым кодом до сборки и ничего не менять.
Scenario: Замена двух реплик
- WHEN работают две реплики прежнего образа, и выполнен
make rolling_update - THEN команда завершается с кодом 0, работают две реплики с новыми
X-Instance-Idна новом образе, обеUPв LB, а контейнеров прежних реплик нет
Scenario: Замена под нагрузкой
- WHEN во время
make rolling_updateчерез LB с постоянной интенсивностью идут запись с ключом и чтение истории - THEN ни один ответ клиенту не ошибочен, в ответах сначала есть
только старые
X-Instance-Id, затем старые и новые, затем только новые, а число сообщений в чате равно числу отправленных ключей
Scenario: Стенд не готов к замене
- WHEN одна реплика остановлена
scripts/stop-one.sh, или работает неAPI_REPLICASреплик - THEN скрипт завершается с ненулевым кодом до сборки, называет
причину и предлагает
make replicas, а контейнеры не меняются
Scenario: Слот остался в ручном состоянии
- WHEN слот LB без адреса оставлен в ручном обслуживании или
дренаже, и выполнен
make rolling_update - THEN скрипт завершается с ненулевым кодом до сборки, называет слот
и печатает команду, которая возвращает его в
ready, а контейнеры не меняются
Requirement: Вывод реплики из балансировщика перед остановкой
Перед плановой остановкой реплики LB SHALL перестать направлять ей
новые запросы. Запросы, которые она уже обрабатывает, SHALL
дорабатываться. Остановка SHALL начинаться после того, как запросов в
полёте у неё не осталось, или по истечении срока ожидания, большего
timeout server LB. Управление LB SHALL быть доступно только изнутри
контейнера LB. Из сети compose и с хоста оно MUST NOT быть доступно.
Состояние слота, выставленное при замене, SHALL сниматься, когда адрес удалённой реплики ушёл из слота. Слот, который потом получит новая реплика, SHALL включаться по обычным проверкам готовности.
Scenario: Выведенная реплика не получает запросов
- WHEN слот реплики переведён в дренаж, и через LB идут запросы
- THEN все новые ответы приходят от других реплик, а запросы, начатые до дренажа, получают ответ
Scenario: Управление LB недоступно из сети
- WHEN контейнер в сети стенда или процесс на хосте обращается к портам LB
- THEN изменить состояние реплики он не может: канал управления LB слушает только loopback внутри контейнера LB
Scenario: Слот после замены
- WHEN замена завершена
- THEN в статистике LB нет слотов в дренаже или в обслуживании, выставленном вручную; свободные слоты — только в обслуживании по DNS
Requirement: Сбой поочерёдной замены
Если новая реплика не стала готовой в LB за срок ожидания или замена прервана раньше, скрипт SHALL удалить её и завершиться с ненулевым кодом, в том числе когда её ID скрипту ещё не известен. Старые реплики, которые ещё не заменены, SHALL остаться в работе.
Если замена прервана (Ctrl+C, ошибка) после того, как новая реплика
стала UP, скрипт SHALL довести вывод текущей старой реплики до
удаления. Только после этого он завершается.
В любом исходе SHALL работать API_REPLICAS готовых реплик. Слоты LB
SHALL быть без состояния, выставленного вручную. Реплики разных версий
допустимы: миграция совместима с обеими. Повторный запуск SHALL
доводить замену до конца.
Scenario: Новая реплика не готова
- WHEN новая реплика не стала
UPв LB за срок ожидания - THEN она удалена, скрипт завершился с ненулевым кодом и назвал
шаг, работают
API_REPLICASреплик, всеUP, и запросы через LB обслуживаются
Scenario: Прерывание при запуске новой реплики
- WHEN скрипт прерван Ctrl+C, пока compose создаёт новую реплику, и её ID скрипту ещё не известен
- THEN новая реплика удалена, работают
API_REPLICASпрежних реплик, всеUP, а слоты без ручного состояния
Scenario: Прерывание во время дренажа
- WHEN скрипт прерван Ctrl+C, пока старая реплика выводится из LB
- THEN старая реплика остановлена и удалена, новая работает,
реплик
API_REPLICAS, а слот старой реплики без ручного состояния