# Балансировщик стенда (с лабы 3): единственная точка входа перед репликами # сервиса api. Правила — .claude/rules/balancer.md, решения — design # change replicas-lb (решения 1–5) и graceful-failover (цепочка таймаутов, # решения 1–3). Порт приходит переменной окружения API_PORT (= APP__PORT # из .env); секретов LB не получает. Тот же файл использует стенд bench/. global # журнал — в stdout контейнера (docker compose logs haproxy) log stdout format raw local0 info maxconn 4096 # один поток на лимит 1 CPU: иначе HAProxy создал бы поток на каждый # CPU ВМ и делил между ними одну квоту nbthread 1 # runtime API для поочерёдной замены (scripts/rolling-update.sh): # слот уходящей реплики — drain, maint, затем снова ready. Только # loopback внутри контейнера LB: из сети compose и с хоста не # достать, доступ — docker compose exec haproxy (bash /dev/tcp). # Решение 2 design change rolling-update stats socket ipv4@127.0.0.1:9999 level admin # буфер отправки к реплике фиксирован (256 KiB): тело загрузки, которое # реплика не читает (ожидание места, отказ до тела), не копится в # памяти LB целиком (design change upload-memory, решение 6) tune.sndbuf.server 262144 # буфер приёма от клиента тоже фиксирован (128 KiB, в ядре — до # 256 KiB на сокет): без него ядро растило его до tcp_rmem ВМ (32 MiB), # и тело, которое LB не может отдать реплике, копилось там — до 9 MiB # на сокет клиента, sock LB до 112 MiB при 40 загрузках по 10 MiB. # Окно 128 KiB даёт ~20 Мбит/с при RTT 50 мс: 10 MiB — за ~4 с, срок # тела 30 с (design change upload-memory, «Уточнения apply», п. 11) tune.rcvbuf.client 131072 # DNS Docker: имя сервиса api отвечает адресами всех работающих реплик. # Пропавший адрес уходит из слота, новый появляется за 1–2 с без # перезагрузки LB resolvers docker nameserver dns 127.0.0.11:53 accepted_payload_size 8192 resolve_retries 3 timeout resolve 1s timeout retry 1s hold valid 1s hold obsolete 1s hold nx 1s hold other 1s hold refused 1s hold timeout 1s defaults mode http log global option httplog # обычные успешные запросы не пишутся; ошибки, таймауты, повторы, # перенаправления и смена состояния реплик — пишутся option dontlog-normal # timeout connect × (retries + 1) = 0,5 × 3 = 1,5 с < 2 с таймаута # клиента tests/resilience.py: перенаправление успевает раньше timeout connect 500ms retries 2 # каждый повтор — на другую реплику, а не на ту же option redispatch 1 # повтор только если соединение не установлено: запрос до реплики не # дошёл, повтор безопасен для любого метода. Ответ, который реплика # уже начала, не повторяется: POST /users и POST /chats не # идемпотентны, отправку сообщения повторяет клиент с тем же ключом retry-on conn-failure # больше [database] request_timeout_seconds (6 с) и KDF входа; у пути # загрузки вложения — 30 с (backend api, http-request set-timeout) timeout server 10s timeout client 30s timeout http-request 10s # простаивающий сеанс клиента, а с ним и соединение с репликой # (http-reuse never): меньше [app] keep_alive_seconds реплики (60 с) timeout http-keep-alive 10s # больше таймаута проверки внутри /health/ready (2 с) на 0,5 с: # медленный PostgreSQL даёт 503 от реплики (L7STS), а не таймаут # проверки. Худшее обнаружение — в комментарии backend api timeout check 2500ms # request_id ответов, которые создаёт сам LB unique-id-format lb-%{+X}o%ci%cp%Ts%rt%pid # ответы самого LB — в формате ошибки контракта; в перечислении кодов # контракта нет отдельных кодов для 502 и 504, ближайший — unavailable. # X-Instance-Id у них нет: контракт это допускает. 400 — неверный запрос # или клиент замолчал посреди тела дольше timeout client (change # upload-memory). 408 на медленные заголовки HAProxy строит до потока # запроса, http-error его не меняет (KNOWN_ISSUES.md) http-error status 400 content-type application/json lf-string '{"error":{"code":"invalid_request","message":"Invalid request","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]" http-error status 502 content-type application/json lf-string '{"error":{"code":"unavailable","message":"API replica closed the connection","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]" http-error status 503 content-type application/json lf-string '{"error":{"code":"unavailable","message":"No API replica is available","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]" http-error status 504 content-type application/json lf-string '{"error":{"code":"unavailable","message":"API replica did not respond in time","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]" # точка входа клиентов: на хосте — 127.0.0.1:APP_OUT_PORT (compose) frontend entry bind "*:${API_PORT}" default_backend api backend api # по очереди, без cookie и stick-table: sticky session запрещён balance roundrobin # путь загрузки вложения (design change upload-memory, решение 7): срок # ответа реплики 30 с вместо 10, больше самого долгого молчания живой # загрузки: # до тела — 2 × [database] request_timeout_seconds (вход, членство) + # [uploads] wait_timeout_seconds = 2 × 6 + 5 = 17 с; # после тела — проверка (до ~4 с) + pending 6 + PUT 5 + ready 6 + # компенсация 5 ≈ 26 с. # Тело ограничивают [uploads] body_timeout_seconds (30 с) и timeout # client; наибольшая длительность загрузки 17 + 30 + 26 ≈ 73 с < # ROLLOUT_DRAIN_TIMEOUT (90 с, scripts/rolling-update.sh). Остальные # пути — прежние 10 с. Выражение — путь ручки в API # (src/api/routers/v1/attachment.py): при смене префикса менять вместе http-request set-timeout server 30s if METH_POST { path_reg ^/api/v1/chats/[^/]+/attachments$ } # соединение с репликой не переходит в общий пул и не отдаётся другому # клиенту: оно живёт, пока жив сеанс клиента, а простаивающий сеанс LB # закрывает по timeout http-keep-alive (10 с). uvicorn держит # простаивающее соединение [app] keep_alive_seconds = 60 с, дольше — # значит, закрывает LB, и запрос не уходит в соединение, которое # реплика в этот момент закрывает (ответа не было бы, а empty-response # LB не повторяет). С пулом (http-reuse safe) последнее простаивающее # соединение LB держал, пока его не закрывала реплика. Гонку при # SIGTERM (uvicorn сразу закрывает простаивающие соединения) не убирает # ни один режим: одиночный 502 в части фаз stop под нагрузкой (design # change graceful-failover, решение 3; evidence/failover/keep-alive.md). # Плановую остановку scripts/rolling-update.sh делает после вывода # реплики из LB (drain через runtime API в global) — без этой гонки http-reuse never # активная проверка готовности: /health/live для LB не годится, # живой процесс без PostgreSQL запросы не обслуживает option httpchk http-check send meth GET uri /health/ready http-check expect status 200 # реплика исключается после 2 неудачных проверок подряд и # возвращается после 2 успешных; проверка раз в секунду (inter, у # исключённой — downinter = inter), а после первой неудачи и до # возврата — через fastinter. Следующая проверка начинается через # интервал после конца предыдущей, поэтому худшее обнаружение: # зависшая (соединение есть, ответа нет): inter + timeout check + # (fall − 1) × (fastinter + timeout check) = 1 + 2,5 + 0,5 + 2,5 # = 6,5 с ≤ 10 с; # адрес пропал (stop после выхода, kill): таймаут соединения # проверки min(timeout connect, inter) = 0,5 с: 1 + 0,5 + 0,5 + # 0,5 = 2,5 с; DNS уводит слот в обслуживание за 1–2 с; # сокет закрыт, адрес жив (окно graceful): 1 + 0,5 = 1,5 с. # Возврат: ≤ downinter + fastinter = 1,5 с после готовности. # init-state down: слот, получивший адрес из DNS (старт LB, новая или # вернувшаяся реплика), начинает DOWN и получает запросы только после # rise проверок, а не сразу — иначе запросы шли бы на процесс, который # ещё не слушает порт default-server check inter 1s fastinter 500ms fall 2 rise 2 resolvers docker init-addr none init-state down resolve-prefer ipv4 # 8 слотов — максимум реплик в сериях трека 1; лишние слоты в MAINT, # девятую реплику LB не увидит server-template api- 8 "api:${API_PORT}" # мониторинг внутри сети compose, наружу не публикуется: # /lb/ready — healthcheck контейнера LB (200, пока есть готовая реплика), # /stats и /stats;csv — состояние и счётчики каждой реплики (make lb_stats) frontend monitor bind :8404 monitor-uri /lb/ready monitor fail if { nbsrv(api) lt 1 } stats enable stats uri /stats # адрес реплики в статистике (поле addr): только внутри сети stats show-legends