feat: put API replicas behind HAProxy

HAProxy 3.4 is the only published entry point; api runs as
API_REPLICAS replicas without ports, found through Docker DNS and
checked on /health/ready. Retries only on connection failure, LB errors
in the contract error format, resource limits and per-service secrets.
Adds scripts/stop-one.sh, LB-aware restart.sh, make replicas /
instances / lb_stats and replica tests driven by EXPECT_REPLICAS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-10 18:05:05 +03:00
co-authored by Claude Opus 5.5
parent 8e15e02898
commit ab71c3b51e
31 changed files with 1295 additions and 240 deletions
+11 -8
View File
@@ -2,16 +2,19 @@
set -eu
# Restart hook для make test-persistence (tests/README.md) по образцу
# scripts/restart.example.sh; правила — .claude/rules/docker.md.
# Перезапускает API и все хранилища стенда (на лабе 2 — Postgres и
# Valkey) с сохранением volume, схемы и данных: без down -v, FLUSHALL и
# повторного наполнения. Кэш Valkey после рестарта пуст: persistence у
# него выключен, данные — в Postgres. start api запускает и его
# зависимость migrate: повторный прогон миграций ничего не меняет.
# Готовность API ждёт сам тест. Секреты не печатает.
# Перезапускает балансировщик, все реплики API и все хранилища стенда
# (Postgres и Valkey) с сохранением volume, схемы и данных: без down -v,
# FLUSHALL и повторного наполнения. Кэш Valkey после рестарта пуст:
# persistence у него выключен, данные — в Postgres.
# LB гасится первым и поднимается последним. start поднимает те же
# контейнеры всех реплик: число реплик не меняется (реплика, остановленная
# stop-one.sh, тоже запускается). start api запускает и его зависимость
# migrate: повторный прогон миграций ничего не меняет.
# Готовность через LB ждёт сам тест. Секреты не печатает.
cd "$(dirname "$0")/.."
docker compose stop api
docker compose stop haproxy api
docker compose restart postgres valkey
# те же контейнеры: --wait только дожидается их healthcheck
docker compose up -d --wait postgres valkey
docker compose start api
docker compose start api haproxy
+73
View File
@@ -0,0 +1,73 @@
#!/bin/sh
set -eu
# Failover hook для make test-failover (tests/README.md) по образцу
# scripts/stop-one.example.sh; правила — .claude/rules/balancer.md,
# решения — design change replicas-lb, решение 7.
# TARGET_INSTANCE_ID — X-Instance-Id реплики, то есть начало ID её
# контейнера (hostname в compose). Скрипт останавливает ровно одну
# работающую реплику сервиса api этого проекта и оставляет её
# остановленной: restart: unless-stopped не поднимает контейнер ни после
# docker stop, ни после docker kill. Postgres, Valkey, LB, чужие контейнеры
# и volumes не трогает. Восстановление — make replicas.
# STOP_MODE=stop (по умолчанию) — docker stop: SIGTERM и graceful;
# STOP_MODE=kill — docker kill: SIGKILL, отказ процесса без graceful;
# STOP_ONE_LOG=<файл> — дописать строку «время, TARGET_INSTANCE_ID,
# полный ID контейнера, режим» (доказательство: тест скрывает вывод hook).
# Секретов и окружения не печатает.
: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
mode="${STOP_MODE:-stop}"
case "$mode" in
stop | kill) ;;
*)
echo "stop-one: STOP_MODE must be stop or kill" >&2
exit 2
;;
esac
# hostname контейнера — его ID в hex, от 12 символов
case "$TARGET_INSTANCE_ID" in
*[!0-9a-f]*)
echo "stop-one: TARGET_INSTANCE_ID is not a container id" >&2
exit 2
;;
esac
if [ "${#TARGET_INSTANCE_ID}" -lt 12 ] || [ "${#TARGET_INSTANCE_ID}" -gt 64 ]; then
echo "stop-one: TARGET_INSTANCE_ID is not a container id" >&2
exit 2
fi
cd "$(dirname "$0")/.."
# только работающие реплики сервиса api этого проекта, полные ID
match=""
for id in $(docker compose ps -q --no-trunc api); do
case "$id" in
"$TARGET_INSTANCE_ID"*)
if [ -n "$match" ]; then
echo "stop-one: TARGET_INSTANCE_ID matches several replicas" >&2
exit 3
fi
match="$id"
;;
esac
done
if [ -z "$match" ]; then
echo "stop-one: no running api replica of this project matches TARGET_INSTANCE_ID" >&2
exit 3
fi
if [ "$mode" = stop ]; then
# uvicorn завершается сам не позже 8 с (graceful_shutdown_seconds);
# 9 с гарантируют возврат hook раньше 10 с и для зависшего процесса
docker stop --timeout 9 "$match" >/dev/null
else
docker kill "$match" >/dev/null
fi
if [ -n "${STOP_ONE_LOG:-}" ]; then
printf '%s TARGET_INSTANCE_ID=%s container=%s mode=%s\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$TARGET_INSTANCE_ID" "$match" "$mode" \
>>"$STOP_ONE_LOG"
fi
echo "stop-one: stopped api container $(printf '%.12s' "$match") (mode $mode)" >&2