Files
mtusi2026lab3/openspec/changes/replicas-lb/tasks.md
T
ricoromaandClaude Opus 5.5 a4ca9ef3a7 fix: correct replicas-lb details found in verify
- 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>
2026-10-10 18:44:57 +03:00

13 KiB
Raw Blame History

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-error 502/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 без портов, haproxy healthy на 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;
    • StartedAt LB, обеих реплик, 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 с причиной.
  • 3.3 test_idempotency.py «Повтор через другую реплику» и test_race.py «Гонка одного ключа через реплики», маркеры spec idempotency (решение 10). Докстринг прежней «Гонки одного ключа» — без ссылки на будущий change.

    Проверка:

    • против LB оба проходят, тест гонки — в пяти запусках pytest подряд;
    • ожидание «через разные реплики» проверено на ошибочном варианте: временно balance first в конфиге LB (весь трафик на первую реплику) — тест гонки и тест повтора падают с числом увиденных реплик. Конфиг вернуть, LB перезапустить.
  • 3.4 «Одно значение на процесс» в test_api_conventions.py по решению 10. Проверка: проходит против LB и против одного процесса (make test_isolated).

  • 3.5 /opsx:sync, как в change instance-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, рабочий стенд не тронут (StartedAt LB и реплик прежние).
  • 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 check 3 с, timeout connect 500 мс, 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.

    Проверка: у каждой новой строки таблицы есть команда, наблюдение и файл.

  • 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 и отчёта.