- stop-one.sh: an empty TARGET_INSTANCE_ID now exits 2 in any shell,
as the design states (${VAR:?} gave 1 under bash).
- driver.py kill-inflight: reproducible "aborted response is not
retried" scenario (logins in flight, replica killed via stop-one.sh).
- Detection time of a hung replica is fall x (inter + timeout check) =
8 s, not inter x fall + timeout check = 5 s (docker pause: 7.3 s);
fixed in haproxy.cfg, balancer.md and the design.
- The 1 CPU replica limit is kept on purpose; the compose comment and
the design now say that Argon2id uses more and logins are slower.
- load-balancing spec: API_REPLICAS is read by compose and Makefile.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
13 KiB
Tasks
Как строить — design.md (дальше «решение N»). Что должно получиться
— дельты в specs/. Перед первым файлом слоя прочитать его правило:
balancer.md, docker.md, run-modes.md, settings.md,
student-tests.md, bench.md.
Evidence снимается с закоммиченного кода: сначала коммит кода, потом evidence, потом коммит evidence и отчёта (бриф основной сессии: коммиты без отдельного подтверждения).
1. Балансировщик и compose
-
1.1
infra/haproxy/haproxy.cfgпо решениям 1–5:resolvers docker;frontend entryна"*:${API_PORT}";backend apiсserver-template api- 8, проверками/health/readyи цепочкой таймаутов из таблицы решения 3;retry-on conn-failure,option redispatch 1;http-error502/503/504 в формате контракта;frontend monitorна:8404;- журнал в stdout,
nbthread 1; - комментарии к числам — какое соотношение
balancer.mdони держат.
Проверка:
haproxy -cв образеhaproxy:3.4.6-trixie@sha256:…сAPI_PORT=8080—Configuration file is valid. -
1.2
docker-compose.ymlпо решению 6:- сервис
haproxy: пин тега и digest, конфиг только на чтение, порт127.0.0.1:${APP_OUT_PORT}:${APP__PORT}, healthcheck через/lb/ready,depends_on: api; api:deploy.replicas: ${API_REPLICAS:-2}, безports;- лимиты у всех пяти сервисов;
- якоря
x-db-env/x-cache-envвместоx-app-env.
Строка
API_REPLICAS=2в.env.example. Шапка файла — о стенде с LB.Проверка:
docker compose --env-file .env config --quiet— код 0;- в
docker compose configуhaproxyнетPASSWORD, уmigrateнетCACHE__; grep -n container_name docker-compose.ymlпуст.
- сервис
-
1.3 Поднять стенд на новом compose:
make run_docker. Volume тот же,make wipe_dataне нужен.Проверка:
docker compose ps— две репликиapiбез портов,haproxyhealthyна127.0.0.1:8080;make test—PASS: lab3 public API scenario;curl -i localhost:8080/health/liveнесколько раз — разныеX-Instance-Id;- журнал
migrate— один прогон.
2. Hook-скрипты и цели Makefile
-
2.1
scripts/restart.shпо решению 8: LB и все реплики, порядокdocker.md. Проверка:make test-persistence ACTION_SCRIPT=scripts/restart.sh—PASS;StartedAtLB, обеих реплик, Postgres и Valkey новые, ID те же.
-
2.2 Новый
scripts/stop-one.shпо решению 7 и образцуscripts/stop-one.example.sh:- формат
TARGET_INSTANCE_ID, поиск средиdocker compose ps -q api; STOP_MODE=stop|kill,STOP_ONE_LOG;#!/bin/sh,set -eu, исполняемый бит (git update-index --chmod=+x).
Проверка вручную:
- остановка реплики по её
X-Instance-Id— код 0 быстрее 10 с, остановлен именно этот контейнер; - пустой, не-hex, ID Postgres / Valkey / LB, неизвестный ID — ненулевой код, ни один контейнер не остановлен;
- после
killреплика через 15 с всё ещёexited.
- формат
-
2.3 Свои цели
Makefileпо решению 9:API_REPLICAS ?= 2,EXPECT_REPLICAS,replicas,instances,lb_stats,EXPECT_REPLICASуstudent_test. Цели skeleton не трогать.Проверка:
make replicasпослеstop-one.sh— тот же контейнер снова работает,make lb_stats— оба слотаUP;make replicas API_REPLICAS=3—make instancesвидит три значения не позже чем через 10 с,make replicasвозвращает два;make lb_statsпечатает только занятые слоты.
3. Тесты реплик
-
3.1
conftest.pyиcontract.pyпо решению 10:EXPECT_REPLICAS, фикстураreplicasс пропуском и причиной, помощникassert_replicas. Проверка:make lint. -
3.2 Новый
test_load_balancing.py: «Одна сессия на разных репликах», «Запись видна через другую реплику». Сценарии — в докстрингах, не маркерами. Проверка:- против LB (
make student_test) оба проходят, печатают увиденныеX-Instance-Id; - с
EXPECT_REPLICAS=1—SKIPPEDс причиной.
- против LB (
-
3.3
test_idempotency.py«Повтор через другую реплику» иtest_race.py«Гонка одного ключа через реплики», маркерыspecidempotency(решение 10). Докстринг прежней «Гонки одного ключа» — без ссылки на будущий change.Проверка:
- против LB оба проходят, тест гонки — в пяти запусках pytest подряд;
- ожидание «через разные реплики» проверено на ошибочном варианте:
временно
balance firstв конфиге LB (весь трафик на первую реплику) — тест гонки и тест повтора падают с числом увиденных реплик. Конфиг вернуть, LB перезапустить.
-
3.4 «Одно значение на процесс» в
test_api_conventions.pyпо решению 10. Проверка: проходит против LB и против одного процесса (make test_isolated). -
3.5
/opsx:sync, как в changeinstance-id-idempotency: сверка покрытия читает основные спеки, и без sync маркеры новых сценариевidempotencyуказывали бы на неизвестные сценарии. Archive потом выполняется с «Sync anyway». Проверка:- в
openspec/specs/естьload-balancing/spec.md, новые сценарииidempotency, изменённые требованияcontainer-run,api-conventions,student-tests; openspec validate --specsбез ошибок;make student_test—test_coverage.pyпроходит.
- в
4. Свои стенды и скилл
- 4.1
student-tests/run_isolated.py:EXPECT_REPLICAS=1уmake student_test.student-tests/failures.compose.yml: сброс портовhaproxy, безapi(решение 12). Проверка:make test_isolated— код 0, тесты репликSKIPPEDс причиной;make failure_checks— код 0, рабочий стенд не тронут (StartedAtLB и реплик прежние).
- 4.2
bench/bench.compose.ymlпо решению 12: одна реплика, лимиты в формеdeploy.resources.limits. Проверка:make bench_quickиmake bench_restore_quick— код 0;- в паспорте те же лимиты API, Postgres и Valkey, что в прежней
метке
quick-*.
- 4.3 Скилл
run-mtusi-messengerпо решению 11:instancesиEXPECT_REPLICAS=1вdriver.py,SKILL.md. Проверка:python3 .claude/skills/run-mtusi-messenger/driver.py all— код 0, тесты реплик пропущены с причиной;driver.py --port 8080 instances— ≥2 значения;driver.py --port 8080 flow—FAILED: none.
5. Документы и общая проверка
-
5.1 Правила и инструкции под решения:
balancer.md: цепочка таймаутов (timeout check3 с,timeout connect500 мс,redispatch 1),STOP_ONE_LOG,make replicas/lb_stats/instances, ответы LB в формате контракта;docker.md: якоря окружения, healthcheck LB;run-modes.md: свои цели реплик,EXPECT_REPLICAS;student-tests.md: режимEXPECT_REPLICAS, тесты реплик и где они пропускаются;bench.md: одна реплика и форма лимитов в override доgraceful-failover;AGENTS.md: «Переходное состояние» (закрытые пункты убрать), карта кода (haproxy.cfg,stop-one.sh,test_load_balancing.pyбез «(лаба 3)»), таблица команд (replicas,instances,lb_stats,test-failoverтеперь запускается).
Проверка:
grep -n "(лаба 3)" AGENTS.md— толькоrolling-update.sh. -
5.2 Общая проверка кода:
make lint,make check;openspec validate replicas-lb --strict;make test,make student_testчерез LB;make test_isolated,make failure_checks.
Затем коммит кода.
6. Evidence и отчёт
-
6.1 Evidence по таблице решения 13 с закоммиченного кода:
make test-failoverдля каждой реплики, восстанавливая предыдущую;STOP_MODE=kill;- отказы
stop-one.sh; make test-persistence;- распределение, лимиты, ответы LB;
- выводы тестов.
Проверка: в каждом файле спеки, change, дата, commit, стенд и хост. Нет паролей, токенов и абсолютных путей домашнего каталога.
TARGET_INSTANCE_IDв строкеSTOP_ONE_LOGсовпадает с ID остановленного контейнера. -
6.2
REPORT.md:- «Архитектура и решения»: схема процессов; HAProxy вместо
Nginx / Traefik / Swarm (таблица из
PLAN.md); цепочка таймаутов; лимиты и расчёт соединений; окружение по сервисам; - соответствие
API_REPLICAS; - «Запуск из чистого clone»: команды стенда с LB;
- строки доказательств уровня «3» и «4» этого change;
- ответы на вопросы защиты:
depends_on/healthcheck — не балансировщик; какие POST безопасно повторять; локальные сессии при росте числа реплик; - ограничения: SPOF LB, 8 слотов, граница пула;
- восстановление реплики после
stop-one.sh.
Проверка: у каждой новой строки таблицы есть команда, наблюдение и файл.
- «Архитектура и решения»: схема процессов; HAProxy вместо
Nginx / Traefik / Swarm (таблица из
-
6.3 Финал:
make lint,make check,openspec validate replicas-lb --strict;- отметить задачи, коммит evidence и отчёта;
graphify update .;- стенд
mtusi-lab3оставлен запущенным через LB, обе репликиUP.
7. Правки по verify (решение 14)
-
7.1 Код и документы:
scripts/stop-one.sh: пустойTARGET_INSTANCE_ID— код 2 явно;driver.py kill-inflightиSKILL.md;- формула обнаружения в
haproxy.cfg,balancer.md,design.md; - обоснование лимита 1 CPU в
docker-compose.ymlиdesign.md; - формулировка
API_REPLICASв спекеload-balancing.
Проверка:
make lint,make check,openspec validate replicas-lb --strict,driver.py kill-inflight --help; коммит. -
7.2 Стенд с итогового commit:
make down,make run_docker. Evidence решения 13 снято заново на нём, включая новые файлы и разделы:clean-clone-ports.md;- зависшая реплика и PostgreSQL в
lb-errors.md; - цена лимита в
stand.md; make testи «Реплик меньше ожидаемого» вstudent-test-lb.md;kill-inflightвtest-failover-kill.md.
Проверка: в шапке каждого файла — итоговый commit.
make test-failoverостановил каждую из двух реплик, ID остановленной =TARGET_INSTANCE_ID. -
7.3
REPORT.md: формула и замер обнаружения, цена лимита 1 CPU, отказ PostgreSQL через LB, строки доказательств с новыми файлами. Коммит evidence и отчёта.