Files
mtusi2026lab6/openspec/specs/load-balancing/spec.md
T
2026-11-14 05:07:04 +03:00

35 KiB
Raw Blame History

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 иметь статус 400, 502, 503 или 504 и тело в формате ошибки контракта. У 502, 503 и 504 code — unavailable: нет готовых реплик, ответ реплики оборвался или не пришёл вовремя. У 400 code — invalid_request: запрос клиента неверен или клиент замолчал посреди тела дольше timeout client LB. request_id тела SHALL совпадать с заголовком X-Request-Id, который ставит LB. X-Instance-Id у таких ответов может отсутствовать.

Ограничение называется в REPORT.md: ответ 408 на заголовки, которые не пришли за timeout http-request, LB отдаёт своим текстом, а не в формате ошибки контракта.

Scenario: Нет готовых реплик

  • WHEN все реплики API остановлены, и клиент запрашивает /health/ready через LB
  • THEN ответ 503 с телом {"error": {"code": "unavailable", ...}}, request_id равен X-Request-Id, а других полей в теле нет

Scenario: Клиент замолчал посреди тела

  • WHEN клиент через LB отправил часть тела загрузки и молчит дольше timeout client LB
  • THEN ответ LB 400 с телом {"error": {"code": "invalid_request", ...}}, 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 отдавать статистику по каждой реплике: состояние проверки, число запросов, повторы, очередь. На том же внутреннем порту LB SHALL отдавать метрики в формате Prometheus уровней frontend и backend: ответы по классам статуса, запросы, число готовых реплик; их забирает Collector (observability, «Ответы балансировщика в метриках»). Статистика и метрики SHALL быть доступны только внутри сети compose; на хост они MUST NOT публиковаться. Оператор SHALL получать статистику одной командой make lb_stats.

Scenario: Состояние реплик

  • WHEN стенд запущен, и выполнен make lb_stats
  • THEN команда печатает по строке на каждый занятый слот реплики с её адресом и состоянием проверки, а порт статистики не опубликован на хосте

Scenario: Метрики балансировщика

  • WHEN стенд запущен, и клиент выполнил N запросов через LB
  • THEN в Prometheus есть ряды ответов публичного frontend по классам статуса с job="haproxy", их сумма выросла не меньше чем на N, а порт метрик на хосте не опубликован

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 по одной, без остановки обслуживания. Порядок:

  1. сборка образа;
  2. миграции, один раз (db-migrations);
  3. для каждой старой реплики:
    • рядом запускается одна новая;
    • скрипт ждёт её готовности и состояния 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 начинаться после того, как запросов в полёте у неё не осталось, или по истечении срока ожидания. Срок 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

Scenario: Загрузка во время дренажа

  • WHEN через LB идёт загрузка вложения, тело которой передаётся дольше 12 с, и во время неё make rolling_update выводит реплику, которая её принимает
  • THEN загрузка получает 202 от этой реплики, и только после ответа реплика останавливается

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, а слот старой реплики без ручного состояния

Requirement: Загрузки через балансировщик

Для POST /api/v1/chats/{chat_id}/attachments срок, в который LB ждёт реплику (timeout server), SHALL быть 30 с. Это больше самого длинного молчания живой загрузки:

  • до чтения тела — вход, членство в чате и ожидание места загрузки, не дольше 2 × [database] request_timeout_seconds + [uploads] wait_timeout_seconds (17 с);
  • после тела — проверка изображения, запись метаданных, запись объекта в staging, перевод в queued с заданием и удаление объекта при компенсации, не дольше 2 × request_timeout_seconds + 2 × [s3] timeout_seconds плюс проверка изображения (около 26 с). Брокера на этом пути нет.

У остальных путей срок SHALL оставаться прежним, 10 с: цепочка таймаутов лабы 3 для них не меняется.

Наибольшая длительность живой загрузки — молчание до тела, срок передачи тела ([uploads] body_timeout_seconds) и молчание после тела, около 73 с при значениях по умолчанию. Она и формула SHALL быть в REPORT.md.

Соединение с недочитанным телом SHALL держать в буферах ядра ограниченный объём: буфер приёма сокетов реплики API — не больше 512 KiB, буфер отправки LB к реплике — 256 KiB, буфер приёма LB от клиента — 128 KiB. Так ожидающие и отклонённые загрузки не переносят тела целиком ни в память реплики, ни в память LB.

Scenario: Долгая обработка загрузки

  • WHEN реплика на пути загрузки молчит дольше 10 с, но меньше 30 с: до чтения тела или после него
  • THEN клиент получает ответ реплики, а не 502 или 504 от LB

Scenario: Прежний срок остальных путей

  • WHEN реплика молчит дольше 10 с на любом другом пути
  • THEN через ~10 с клиент получает 504 от LB в формате ошибки контракта

Scenario: Загрузка дольше срока LB

  • WHEN реплика на пути загрузки молчит дольше 30 с
  • THEN через ~30 с клиент получает 504 от LB в формате ошибки контракта

Scenario: Буферы соединений ограничены

  • WHEN 40 клиентов одновременно загружают по 10 MiB через LB в одну реплику с параметрами загрузок по умолчанию
  • THEN пик памяти LB и буферов сокетов реплики растёт не больше чем на 1 MiB на клиента, а реплика и LB не завершены из-за памяти