docs: propose graceful-failover change

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-10 22:32:12 +03:00
co-authored by Claude Opus 5.5
parent aec6f23cb0
commit b76a666621
8 changed files with 1197 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-10
@@ -0,0 +1,513 @@
# Design
## Context
Мотивация — `proposal.md`, «Why». Требования — дельты в `specs/`.
Соотношения таймаутов — `balancer.md`, «Цепочка таймаутов», стенд
`bench/` — `bench.md`. Design выбирает числа и способ их замера.
Текущее состояние (commit `aec6f23`, change `replicas-lb` в архиве):
- `infra/haproxy/haproxy.cfg`:
- проверки `/health/ready`: `inter 1s fall 2 rise 2`, `timeout check
3s`, `init-state down`;
- соединения и повторы: `timeout connect 500ms`, `retries 2`,
`option redispatch 1`, `retry-on conn-failure`;
- сроки: `timeout server 10s`, `timeout client 30s`,
`http-keep-alive 10s`;
- DNS Docker с `hold` 1 с.
Повторное использование соединений к репликам — по умолчанию
(`http-reuse safe`).
- Приложение:
- `/health/ready` — `SELECT 1` через пул с таймаутом
`READINESS_DB_TIMEOUT_SECONDS` = 2 с;
- пул 10 + 5, `pool_timeout` 5 с, `connect_timeout` 3 с,
`statement_timeout` 5 с, срок работы запроса с БД
(`request_timeout_seconds`) 6 с;
- uvicorn: `timeout_graceful_shutdown` 8 с, `timeout_keep_alive` не
задан, то есть 5 с;
- KDF пароля — вне транзакций (`auth.md`): транзакция запроса
простаивает только между командами одного обработчика.
- Compose: `stop_grace_period` 10 с, `scripts/stop-one.sh` — `docker
stop --timeout 9`. Healthcheck образа — 10 с / 3 с, для LB не нужен.
- `bench/` — один API без LB: `container_name: mtusi-bench-api`, k6
ходит к нему по имени. Метрики приложения сняты с этого контейнера
(cgroup `cpu.stat`, `VmRSS` PID 1). В git нет ни одной метки лабы 3,
только пробные `quick-*`.
Разведка на рабочем стенде 2026-10-10 (две реплики, k6 в сети стенда,
300 запросов/с `GET /health/live` через LB):
- `docker stop` реплики — 0 ошибок из 11 966. `DOWN` через ~1,6 с
(«Layer4 timeout»): контейнер завершился за 0,4 с, его адрес пропал.
Через 0,15 с после этого слот уходит в обслуживание по DNS. Около
1,6 с запросы, назначенные на пропавший адрес, ждали `timeout
connect` (до 505 мс) и уходили на другую реплику.
- `docker kill` — так же 0 ошибок: запросы по ~1 мс, в полёте их не
было.
- Пул простаивающих соединений LB → реплика (`safe_conn_cur` 22 и
13 после всплеска) опустел целиком через ~5 с после последнего
запроса. Это `timeout_keep_alive` uvicorn (5 с): реплика закрывает
простаивающие соединения раньше, чем LB успевает их убрать.
## Goals / Non-Goals
**Goals:**
- Каждое звено цепочки — с числом, источником и соотношением, которое
оно держит (решение 1). Формула худшего обнаружения по режимам
сверяется с замером под нагрузкой.
- Отказ процесса API (`stop`, `kill`) не даёт ошибок или даёт только
ошибки запросов в полёте, которые клиент повторяет с ключом. Зависшая
реплика исключается заметно раньше 10 с.
- Стенд `bench/` готов к сериям трека 1: LB, N реплик и лимиты LB —
параметры профиля. Профили лабы 2 работают при N = 1.
- Профиль `failover` воспроизводим одной командой. Его шкалы сопоставимы
между фазами: одна интенсивность, одни окна, одни часы.
**Non-Goals:**
- Открытая модель ступенями, серии A/B, метрики LB и PostgreSQL по
репликам, графики — change `scaling-bench`. Здесь k6 с постоянной
интенсивностью только в профиле `failover`.
- Поочерёдная замена на новый образ — change `rolling-update`. Профиль
`failover` даст для неё основу (фаза, шкала), но не замену.
- Readiness вне общего пула соединений и отказ PostgreSQL через LB:
поведение остаётся прежним, ограничения — в Risks.
- Изменение API и контракта: HTTP-поведение не меняется.
## Decisions
### 1. Цепочка таймаутов
Время — от клиента к PostgreSQL. «Было» — commit `aec6f23`.
| Звено | Было | Стало | Соотношение и почему |
|---|---|---|---|
| Клиент `tests/resilience.py` | 2 с | — | задан skeleton; всё, что LB делает до ответа при отказе соединения, должно уложиться |
| Клиент k6 профиля `failover` | — | 15 с | > `timeout server`: клиент видит ответ LB (504), а не свой таймаут |
| HAProxy `timeout client` / `http-request` / `http-keep-alive` | 30 / 10 / 10 с | — | соединения клиентов; на отказ реплики не влияют |
| HAProxy `timeout connect` | 500 мс | — | × (`retries` 2 + 1) = 1,5 с < 2 с клиента. Живая реплика в сети Docker принимает соединение за доли миллисекунды; 500 мс ограничивают ожидание пропавшего адреса (разведка: всплеск задержки до 0,5 с на ~1,6 с) |
| HAProxy `retries`, `redispatch 1`, `retry-on conn-failure` | 2, да | — | повтор только недошедшего запроса, каждый — на другую реплику (`replicas-lb`, решение 4) |
| HAProxy `timeout server` | 10 с | — | > `request_timeout_seconds` 6 с + KDF входа под лимитом 1 CPU (до 1,6 с при 4 входах сразу) |
| HAProxy `inter` / `downinter` | 1 с / = `inter` | — | период проверок, в том числе исключённой реплики |
| HAProxy `fastinter` | = `inter` | 500 мс | повторная проверка после первой неудачи и до возврата (решение 2) |
| HAProxy `fall` / `rise` | 2 / 2 | — | одна неудача — ещё не отказ; возврат — после двух успехов подряд |
| HAProxy `timeout check` | 3 с | 2,5 с | > `READINESS_DB_TIMEOUT_SECONDS` 2 с на 0,5 с: медленный PostgreSQL даёт 503 от реплики, а не таймаут проверки (решение 2) |
| Таймаут соединения проверки | min(`timeout connect`, `inter`) = 0,5 с | — | правило HAProxy; ограничивает проверку пропавшего адреса |
| `resolvers docker` `hold` | 1 с | — | пропавший адрес уходит из слота за 1–2 с, новый появляется так же |
| HAProxy `pool-purge-delay` | 5 с (по умолчанию) | 5 с явно | период уборки простаивающих соединений к репликам (решение 3) |
| uvicorn `timeout_keep_alive` | 5 с (по умолчанию) | 60 с, `[app] keep_alive_seconds` | > времени, за которое LB сам убирает простаивающее соединение: закрывает LB, а не реплика (решение 3) |
| `/health/ready`: `SELECT 1` | 2 с | — | < `timeout check` |
| Пул: `pool_timeout` / `connect_timeout` | 5 / 3 с | — | ожидание соединения пула и подключение; оба < `request_timeout_seconds` |
| PostgreSQL `statement_timeout` | 5 с | — | < `request_timeout_seconds`: сервер сам прерывает долгую команду раньше, чем приложение рвёт соединение |
| Срок работы запроса с БД (`request_timeout_seconds`) | 6 с | — | < `timeout server` 10 с |
| PostgreSQL `idle_in_transaction_session_timeout` | нет | 10 с, `[database] idle_in_transaction_timeout_ms` | > `request_timeout_seconds`: транзакция живого запроса дольше не живёт. Снимает блокировки замороженной реплики (решение 4) |
| uvicorn `timeout_graceful_shutdown` | 8 с | — | < `stop_grace_period` 10 с; запросы в полёте дорабатывают |
| `scripts/stop-one.sh` | `docker stop --timeout 9` | — | возврат hook < 10 с |
| compose `stop_grace_period` | 10 с | — | SIGKILL после graceful |
Худшее время обнаружения по проверкам. Следующая проверка начинается
через интервал после конца предыдущей (`replicas-lb`, решение 14):
| Режим | Как выглядит для проверки | Формула | Было | Стало |
|---|---|---|---|---|
| зависшая реплика (`pause`) | соединение принято, ответа нет | `inter` + `timeout check` + (`fall` − 1) × (`fastinter` + `timeout check`) | 1 + 3 + 1 + 3 = 8 с | 1 + 2,5 + 0,5 + 2,5 = 6,5 с |
| адрес пропал (`stop` после выхода, `kill`) | таймаут соединения | `inter` + 0,5 + (`fall` − 1) × (`fastinter` + 0,5) | 1 + 0,5 + 1 + 0,5 = 3 с | 1 + 0,5 + 0,5 + 0,5 = 2,5 с |
| сокет закрыт, адрес жив (окно graceful) | отказ соединения сразу | `inter` + (`fall` − 1) × `fastinter` | 2 с | 1,5 с |
Ещё один путь исключения — DNS: остановленный контейнер пропадает из
ответа DNS Docker, и слот уходит в обслуживание через `hold` 1–2 с.
Действует то, что сработает раньше. Возврат: первая успешная проверка
через ≤ `downinter` 1 с после готовности, вторая — через `fastinter`,
итого ≤ 1,5 с плюс время самих проверок.
### 2. Зависшая реплика: `fastinter` и `timeout check` 2,5 с
Худшее обнаружение зависшей реплики — 6,5 с вместо 8 с. Запас до 10 с
вырастает с 2 с до 3,5 с. Вклад каждой правки:
- `fastinter 500ms` — вторая проверка после первой неудачи идёт
через 0,5 с, а не через `inter`. Та же правка ускоряет возврат
реплики. Число проверок в установившемся режиме не меняется: частота
растёт только в переходном состоянии.
- `timeout check` 2,5 с. Внутренний таймаут готовности (2 с) остаётся
меньше на 0,5 с. Медленный PostgreSQL по-прежнему даёт 503 от реплики
(`L7STS`), а не таймаут проверки (`L7TOUT`). Исход для LB в обоих
случаях один — неудача. Запас нужен для того, чтобы журнал называл
причину правильно.
Альтернативы:
- **Таймаут готовности 1 с, `timeout check` 1,5 с** (обнаружение
4,5 с). Отвергнуто:
- `/health/ready` берёт соединение из общего пула, и под нагрузкой
ожидание пула длиннее 1 с — уже повод вывести реплику;
- заминка PostgreSQL на 1–2 с (контрольная точка) вывела бы из LB все
реплики разом, и на всё отвечал бы 503 сам LB. Сейчас такие
запросы просто медленнее.
- **`fall 1`.** Одна неудачная проверка исключает реплику: лишние
выходы из LB от единичной задержки. Отвергнуто.
- **Пассивная проверка** (`observe layer4`, `error-limit`, `on-error
mark-down`). Ускоряет исключение остановленной реплики под нагрузкой:
ошибки соединения живого трафика копятся за миллисекунды. Зависшую
реплику не ловит: соединение принимается, а ответ 504 приходит только
через `timeout server`. Ошибок при `stop` и `kill` и так нет
(разведка), выигрыш — только всплеск задержки ~1,6 с. Не добавляется:
второй механизм исключения, который пришлось бы объяснять и
замерять. Пересмотр — если профиль `failover` покажет ошибки.
### 3. Простаивающие соединения LB → реплика: закрывает LB
HAProxy держит пул простаивающих соединений к каждой реплике (`http-reuse
safe`). Каждые `pool-purge-delay` (5 с) он закрывает половину
соединений сверх оценки нужного числа. Без запросов оценка падает
вдвое за период, и пул пустеет за несколько периодов. uvicorn закрывает
простаивающее соединение через `timeout_keep_alive`. Разведка: это
5 с, и закрывает реплика. Если LB отправит запрос в соединение в
момент его закрытия, ответа не будет. `empty-response` LB не
повторяет намеренно, поэтому клиент получит 502.
Решение:
- `[app] keep_alive_seconds` = 60 → `uvicorn.run(...,
timeout_keep_alive=...)`. Это заметно дольше, чем LB убирает пул
(≈ 6 периодов по 5 с для 20 соединений). Простаивающее соединение
закрывает LB, и запрос в закрывающееся соединение не уходит.
- `pool-purge-delay 5s` в `haproxy.cfg` явно: это вторая половина
соотношения.
- Проверка в apply — команда драйвера `idle-conns` (решение 8):
всплеск через LB, затем статистика LB раз в секунду. Число
простаивающих соединений убывает ступенями и обнуляется раньше 60 с.
Иначе — увеличить срок или уменьшить `pool-purge-delay`.
Цена: реплика держит лишние дескрипторы до 60 с. Простаивающее
соединение uvicorn ничего не стоит, кроме дескриптора.
Альтернативы:
- **`option http-server-close`.** LB закрывает соединение с репликой
после каждого ответа, и гонки нет совсем. Но каждый запрос — новое
TCP-соединение и новый объект протокола uvicorn: десятки
микросекунд CPU реплики на запрос. В треке 1 это заметно на потолке
RPS. Отвергнуто.
- **`retry-on empty-response`.** LB повторил бы и запрос, который
реплика выполнила, а ответ потеряла. Для `POST /users` и `POST /chats`
это второй объект (`replicas-lb`, решение 4). Отвергнуто.
- **`http-reuse never`.** Соединение не делится между клиентами, но
остаётся за keep-alive соединением своего клиента. Гонку по сроку
простоя не убирает. Отвергнуто.
Остаётся гонка при SIGTERM: uvicorn сразу закрывает простаивающие
соединения. Окно — между закрытием и тем, как LB обработает FIN, то
есть доли миллисекунды. В режиме `safe` первый запрос клиентского
соединения никогда не идёт в чужое простаивающее соединение. Поэтому
клиенты с новым соединением на запрос, как `tests/resilience.py`, этой
гонки не встречают. Профиль `failover` (k6 держит keep-alive) её
измеряет: 502 в фазах `stop`. Если они появятся — Risks.
### 4. `idle_in_transaction_session_timeout` 10 с
Замороженный процесс (`docker pause`, зависание) держит открытую
транзакцию сколь угодно долго. Его TCP-соединение живо: ядро ВМ
отвечает за него, и keepalive PostgreSQL ничего не замечает. Если
транзакция уже вставила строку ключа идемпотентности, повтор того же
ключа через другую реплику ждёт её блокировку до `statement_timeout`
(5 с) и получает 503. Так до разморозки. Контракт требует, чтобы
неподтверждённую запись можно было повторить.
Решение:
- `server_settings` asyncpg получает
`idle_in_transaction_session_timeout` рядом с `statement_timeout`.
Значение — из `[database] idle_in_transaction_timeout_ms`, 10 000;
0 — не задавать.
- Валидатор `Database`: значение — 0 или больше
`request_timeout_seconds` × 1000. Транзакция живого запроса дольше
этого срока не живёт: `get_db_session` прерывает работу с БД через
`request_timeout_seconds` и закрывает соединение без возврата в пул.
Значит, PostgreSQL прерывает только транзакцию процесса, который
перестал работать.
- 10 с: на 4 с больше срока запроса. Почти совпадает с `timeout server`:
когда клиент получает 504 от LB и повторяет запрос, транзакция
замороженной реплики уже прервана или вот-вот будет. Повтор ждёт
блокировку не дольше `statement_timeout` и получает 201 с первой-второй
попытки.
Альтернативы:
- **TCP keepalive сервера.** Замороженный контейнер не мёртв для сети,
ядро отвечает на keepalive. Не работает.
- **Меньший `statement_timeout`.** Он ограничивает выполняющуюся
команду, а не простой между командами. Блокировку не снимает.
- **`lock_timeout` у повтора.** Быстрее отдаёт 503, но блокировку не
снимает. Ключ остаётся занятым до разморозки.
Проверка — команда драйвера `hang-key` (решение 8). Вставка сообщения с
пробным текстом задерживается триггером. Реплика, выполняющая её,
замораживается посреди транзакции. Повторы ключа через LB получают
201 после прерывания транзакции, в чате одно сообщение, журнал
PostgreSQL называет причину. Плюс счётчик таких прерываний в фазах
`pause` профиля `failover`.
### 5. Как меряется время обнаружения
Все отметки — на часах ВМ Docker. Часы хоста и ВМ не сравниваются:
- **момент действия** — событие Docker (`docker events --since --until
--filter container=<id>`, `TimeNano`): `kill` с сигналом 15 (`docker
stop`), `kill` с сигналом 9 (`docker kill`), `pause`. Возврат —
событие `start` или `unpause`;
- **смена состояния в LB** — строки журнала HAProxy с отметкой Docker
(`docker logs -t`). Состояние то же, что в статистике (`status`), но
журнал даёт точное время перехода. Опрос статистики дал бы
±0,2–0,5 с;
- исключение — первая из строк «`Server api/<слот> is DOWN`» и
«`… enters maintenance`» (DNS) после действия;
- возврат — «`… is UP`» после события возврата;
- **ответы клиенту** — `Date.now()` в k6 при отправке каждого запроса,
плюс длительность, статус и `X-Instance-Id`.
Слот реплики (`api-1` … `api-8`) — по адресу контейнера в статистике
LB перед действием: слот получает адрес из DNS, и имя слота с именем
контейнера не связано (`balancer.md`).
Величины фазы, секунды от действия:
| Величина | Определение |
|---|---|
| обнаружение | первая строка исключения слота в журнале LB |
| первая запись / первое чтение | первый 201 / 200 среди запросов, отправленных после действия. При round-robin — почти сразу: вторая реплика обслуживает всё время. Это доказательство «новые чтения и записи продолжаются» |
| последняя ошибка | отправка последнего неуспешного запроса окна отказа |
| восстановление | конец последней секунды с долей успеха < 99 %, 0 — если таких секунд нет. Секунда запроса — по моменту отправки: запрос, отправленный на зависшую реплику и получивший 504 через 10 с, относится к секунде отправки |
| возврат в LB | строка `is UP` от события возврата |
| реплика снова отвечает | первый ответ с её `X-Instance-Id` после возврата |
Формула решения 1 — верхняя граница обнаружения. Превышение
помечается в таблице фаз (`over_bound`), но команда не падает: это
результат, а не сбой стенда.
### 6. Стенд `bench/` на HAProxy + N реплик
- **`bench/bench.compose.yml`:**
- `api`: без `container_name`, `deploy.replicas:
${BENCH_API_REPLICAS}`, лимиты на реплику — те же `BENCH_APP_*`,
healthcheck образа выключен;
- `haproxy`: `container_name: mtusi-bench-haproxy` (он один, имя
нужно оркестратору), `restart: "no"`, лимиты `BENCH_LB_CPUS` /
`BENCH_LB_MEMORY` без swap, порт сброшен. Конфиг — тот же
`infra/haproxy/haproxy.cfg` из основного файла;
- запуск: `up -d --no-deps api haproxy` после миграций.
- **k6** ходит на `http://haproxy:<APP__PORT>`: имя сервиса — алиас в
сети `mtusi-bench`. Адрес по умолчанию в `lib.js` меняется.
- **`run.py`:**
- реплики — `compose ps -q api`, без постоянного имени;
- готовность стенда — LB видит `UP` все N слотов (статистика LB
изнутри контейнера LB, как `make lb_stats`), а не `python` внутри
API;
- снимок CPU, памяти и RSS — сумма по репликам, `VmHWM` — максимум.
При N = 1 — те же числа, что раньше;
- сторож и состояние приложения: упала любая реплика — `app_down`;
- `switch_api` (этап восстановления) пересоздаёт все реплики и ждёт
их в LB;
- паспорт: `limits` — первая реплика как `api`, плюс `haproxy` и
`api_replicas`; окружение приложения — из первой реплики.
- **`Profile`** — новые поля `replicas` (1), `lb_cpus` ("1"),
`lb_memory` ("256m"): в `meta.json` и в паспорт.
Предупреждение о памяти ВМ считает N × память реплики и память LB.
- **Совместимость.** Профили `full`, `quick`, `restore`,
`restore_quick` — N = 1, прежние лимиты, прежние столбцы и разделы
сводки. Это смена методики, как и предусмотрено `bench.md`:
- в пути запроса теперь LB — лишний переход и CPU LB;
- реплику раз в секунду проверяет LB — `SELECT 1` в квоте API;
- в git нет меток лабы 3, которые стали бы несравнимыми, а метки лабы
2 с лабой 3 не сравниваются и так.
Проверка — `make bench_quick` и `make bench_restore_quick` с кодом 0.
- **Почему не «при N = 1 мимо LB».** Серии трека 1 сравнивают 1, 2 и 4
реплики. Если при N = 1 запросы шли бы мимо LB, разница включала бы
стоимость LB. Один путь для всех N — сравнение честное.
### 7. Профиль `failover`
Профили в `run.py`:
| Поле | `failover` | `failover_quick` |
|---|---|---|
| реплик | 2 | 2 |
| лимиты API (на реплику) / PostgreSQL / Valkey / LB | 1 CPU 512m / 2 CPU 1g / 0,5 CPU 128m / 1 CPU 256m — как рабочий стенд | те же |
| режимы | `stop`, `kill`, `pause` | `stop`, `kill` |
| интенсивность | 100 записей + 100 чтений в секунду | та же |
| окна: до действия / отказ / после возврата | 15 / 20 / 15 с | 5 / 10 / 8 с |
| читаемый чат | 1 000 сообщений, без фоновых чатов | тот же |
| порог восстановления | 99 % | 99 % |
- **Лимиты рабочего стенда, а не матрицы лабы 2.** Профиль отвечает на
вопрос «что видит клиент стенда `make run_docker` при отказе
реплики». Поэтому реплика — 1 CPU и 512 МБ, как в
`docker-compose.yml`.
- **Интенсивность.** 200 запросов в секунду — около половины потолка
одной реплики (запись с ключом и страница истории на 1 CPU). После
отказа одна реплика держит всю нагрузку без перегрузки. Значит,
ошибки шкалы — от отказа, а не от нехватки CPU. При 200 запросах в
секунду порог 99 % значим: одна ошибка в секунду — уже 0,5 %.
- **Порядок.** Для каждого режима — реплика 1, реплика 2. Перед фазой
LB видит обе `UP`. Фаза:
1. k6 (`k6/failover.js`) стартует на `до + отказ + после` секунд;
2. через «до» — действие: `docker stop --timeout 9` (как
`stop-one.sh`), `docker kill` или `docker pause`;
3. через «отказ» от действия — возврат: `docker start` того же
контейнера (как `make replicas`: те же ID) или `docker unpause`;
4. k6 доживает до конца;
5. события Docker, журнал LB и журнал PostgreSQL окна фазы, ожидание
обеих реплик в LB (до 30 с);
6. сверка записей.
- **`k6/failover.js`.** Два сценария `constant-arrival-rate` —
запись и чтение, `maxVUs` с запасом под зависшую реплику: 100
запросов в секунду × 10 с ожидания 504.
- Запись — в чат записи, отправитель по кругу, текст
`syntheticText("f<фаза>", n)`. Ключ — `<прогон>.<фаза>.<n>`:
повтор строит тот же ключ без журнала ключей.
- Чтение — страница истории читаемого чата с курсором из пула, зерно
профиля, проверка полной страницы.
- Каждый запрос — строка `fo,<w|r>,<n>,<отправка мс>,<длительность
мс>,<статус>,<X-Instance-Id>` в вывод k6. Вывод пишется в файл
`.work/`, а не в трубу: 11 тысяч строк за фазу переполнили бы
буфер трубы, пока оркестратор ждёт момента действия.
- **`lib.js`.** `messageHeaders(token, key)` и `sendMessage(..., key)`:
ключ можно задать. Без него — новый UUID, как раньше.
- **Сверка (`k6/retry.js`).** Каждая неуспешная запись фазы
повторяется с тем же ключом и телом до 201, не больше 5 попыток. Затем
`psql` стенда:
- число сообщений чата записи = число строк `fo,w` за все фазы;
- разных текстов столько же.
Расхождение — `BenchError` с фазой. Так повтор после неопределённого
исхода (`kill`, 504 от зависшей реплики) доказан без потерь и дублей.
- **`bench/failover.py`** — чистые функции на stdlib, без docker:
- разбор строк k6, журнала LB и событий Docker;
- посекундная шкала и величины решения 5;
- сводка `summary.md`.
`run.py` их импортирует и только оркестрирует. Метрики матрицы лабы 2
в профиле не снимаются: нет `runs.csv` и `prefill.csv`, кроме порции
наполнения читаемого чата.
- **Результаты** — `evidence/failover/<метка>/`:
- `meta.json` — паспорт, как у `bench`, с профилем;
- `phases.csv` — строка на фазу;
- `timeline.csv` — строка на секунду фазы;
- `summary.md` — таблица фаз и фрагменты шкал вокруг действия и
возврата;
- `raw/<фаза>-k6.json` — итог k6;
- `raw/<фаза>-lb.log` — строки смены состояния из журнала LB;
- `progress.json`.
Пробные метки `quick-failover-*` — в `.gitignore`.
- **Отказ команды:**
- k6 завершился ошибкой;
- PostgreSQL или Valkey упал или перезапускался;
- реплика не вернулась в LB за 30 с;
- сверка не сошлась.
Превышение формулы — пометка, а не отказ (решение 5).
- **Make:** `bench_failover` (`FAILOVER_LABEL ?= baseline`) и
`bench_failover_quick` (`quick-failover-<время>`), обе под
`caffeinate -isu`, как `bench`.
### 8. Команды драйвера для проверки решений 3 и 4
Однократный скрипт вне репозитория не воспроизвести (`replicas-lb`,
решение 14). Поэтому проверки — команды драйвера скилла
`run-mtusi-messenger`. Только против стенда с LB:
- **`idle-conns [--keep-alive 60]`:**
1. всплеск запросов через LB с keep-alive соединениями;
2. статистика LB раз в секунду: `idle_conn_cur` и `safe_conn_cur` по
слотам;
3. итог — через сколько секунд пул пуст. Код 1, если пул не опустел
за срок keep-alive.
- **`hang-key`** — сценарий «Повтор ключа после зависшей реплики»:
1. синтетический пользователь и чат;
2. временный триггер задерживает вставку сообщения с одним пробным
текстом на 2 с (`pg_sleep`). Другие вставки он не трогает;
3. отправка с ключом K в фоне. Реплика, которая её выполняет (адрес
клиента в `pg_stat_activity`), замораживается `docker pause`;
4. повторы K через LB до 201 со временем и `X-Instance-Id`;
5. разморозка, число сообщений с пробным текстом и строка журнала
PostgreSQL о прерывании;
6. в `finally` — удаление триггера и разморозка.
Работает с рабочим стендом: триггер срабатывает только на пробный
текст и удаляется при любом исходе.
### 9. Evidence и отчёт
| Файл | Что показывает |
|---|---|
| `evidence/failover/<метка>/` | полный профиль `failover`: 6 фаз, шкалы, таблица фаз; паспорт и состояние хоста (питание, память, `Swapouts` до и после) |
| `evidence/failover/detection.md` | замер обнаружения по фазам метки в сравнении с формулой решения 1; журнал LB вокруг действия |
| `evidence/failover/keep-alive.md` | `driver.py idle-conns`: пул LB пустеет раньше 60 с; до change — за ~5 с, закрывала реплика (разведка) |
| `evidence/failover/hung-key.md` | `driver.py hang-key`: повтор ключа после зависшей реплики; проверка настроек (`SHOW` на соединении приложения, отказ запуска при неверном сроке) |
| `evidence/tests/graceful-failover-checks.md` | регрессия на итоговом commit: `make test`, `student_test` через LB, `test_isolated`, `failure_checks`, `test-persistence`, `test-failover` (`stop` и `kill`), `bench_quick`, `bench_restore_quick`, `bench_failover_quick` |
`REPORT.md`:
- таблица решения 1 вместо прежней цепочки;
- формула и замер обнаружения по режимам;
- строки доказательств уровня «4»:
- согласованные таймауты и SIGTERM;
- поочерёдная остановка с RPS, ошибками и восстановлением;
- «Эксперименты и отказы» — таблица фаз;
- ответ «отказ процесса и отказ узла» — с замером;
- ограничения обновлены: keep-alive, зависшая реплика.
Всё снимается с закоммиченного кода. Рабочий стенд пересоздаётся
`make down` и `make run_docker`: после пересборки на Docker 29.8
`make run_docker` не пересоздаёт работающие `api` (verify
`replicas-lb`).
## Risks / Trade-offs
- **[Гонка keep-alive при SIGTERM остаётся]** → окно — доли
миллисекунды. Клиенты с новым соединением на запрос её не встречают
(режим `safe`). Профиль `failover` её измеряет. Go-клиент (k6) сам
повторяет запрос на закрытом повторно используемом соединении, если
запрос повторяемый: `GET` или с заголовком `Idempotency-Key`. Тогда
она видна только как задержка. Если 502 появятся под нагрузкой, это
результат в отчёте и повод для дренажа перед SIGTERM (readiness 503,
затем остановка) — следующим change, со сменой спека
`graceful-shutdown`.
- **[`/health/ready` через общий пул]** → под перегрузкой проверка ждёт
пул, и реплика может выйти из LB. Таймаут 2 с — длиннее любого
ожидания в пределах SLO трека 1 (p95 200 мс), поэтому на сериях не
скажется. Пересмотр — если трек 1 покажет выходы из LB у порога.
- **[Отказ PostgreSQL выводит из LB все реплики]** → поведение
прежнее: через 1–2 с на всё отвечает 503 сам LB, в формате контракта.
Без PostgreSQL API и так отвечает 503 на всё, кроме `/health/live`.
Ограничение — в `REPORT.md` (`replicas-lb`).
- **[`timeout check` ближе к таймауту готовности]** → 0,5 с запаса на
ответ 503 под нагрузкой. Если не хватит, исход тот же (неудача), но
с другой причиной в журнале.
- **[Профиль `failover` и рабочий стенд в одной ВМ]** → профиль не
публикует портов и не трогает `mtusi-lab3`. На время замера для
отчёта рабочий стенд останавливается (`make stop`, бриф), иначе его
проверки LB шумят в той же ВМ.
- **[Строки k6 на каждый запрос]** → ~11 тысяч строк за фазу, CPU k6
растёт. Генератор работает без лимита CPU, его загрузка — в паспорте,
как у прочих профилей.
- **[Метки `bench` лабы 3 до и после change несравнимы]** → в git их
нет. Новая методика записана в `bench.md`, базовый замер трека 1
снимается после change.
- **[Триггер `hang-key` на рабочем стенде]** → срабатывает только на
пробный текст, удаляется в `finally`. Прерванный запуск оставил бы
функцию и триггер: команда печатает SQL удаления.
## Migration Plan
1. Код и конфиги коммитятся. Рабочий стенд — `make down`, `make
run_docker`: новый образ, новый `haproxy.cfg`. Volume данных тот же.
2. `config.toml` трогать не нужно: новые поля по умолчанию. Строки с
комментариями — в `config_example.toml`.
3. Откат — revert commit и снова `make down`, `make run_docker`.
Схема БД не менялась.
@@ -0,0 +1,136 @@
# Proposal
## Why
Рубрика «4» лабы 3 (`README.md`) требует трёх вещей, которых после
change `replicas-lb` ещё нет:
- согласованные health/readiness, таймауты и прекращение приёма при
SIGTERM, LB исключает недоступный backend, а период проверок и
максимальное время обнаружения отказа названы;
- поочерёдная остановка каждой API-реплики с восстановлением
предыдущей: RPS, ошибки и время восстановления;
- те же числа под нагрузкой, а не на тестовом клиенте раз в 0,1 с.
Сейчас цепочка таймаутов задана, но не замерена (AGENTS.md,
«Переходное состояние»). Verify `replicas-lb` оставил открытыми:
- **Мало запаса у зависшей реплики.** LB исключает её за `fall × (inter
+ timeout check)` = 8 с, замер — 7,3–7,7 с при пределе 10 с.
- **Гонка keep-alive не проверена.** uvicorn закрывает простаивающее
соединение через 5 с, а HAProxy держит такие соединения в пуле и
может отправить запрос в закрывающееся. Разведка на рабочем стенде
(2026-10-10, design, «Context») показала: пул LB опустел ровно через
~5 с после всплеска, то есть первым закрывает uvicorn.
- **Блокировка ключа у зависшей реплики.** Замороженный процесс держит
открытую транзакцию с ключом идемпотентности бесконечно. Повтор того
же ключа через другую реплику ждёт до `statement_timeout` и получает
503 снова и снова (`REPORT.md`, «Ограничения»).
- **Стенд `bench/` — один API без LB.** На нём нельзя ни измерить
отказ реплики под нагрузкой, ни начать серии трека 1 (`PLAN.md`,
«Трек 5 → Методика»).
## What Changes
- **Цепочка таймаутов.** Каждое звено обосновано и записано в design,
`REPORT.md` и комментариях конфигов:
- HAProxy: `fastinter 500ms`, `timeout check` 2,5 с вместо 3 с.
Худшее обнаружение зависшей реплики — 6,5 с вместо 8 с, вернувшаяся
реплика включается быстрее;
- uvicorn: `timeout_keep_alive` из новой настройки
`[app] keep_alive_seconds` (60 с) вместо неявных 5 с. Простаивающее
соединение LB → реплика закрывает LB, а не реплика;
- PostgreSQL: `idle_in_transaction_session_timeout` на соединениях
приложения из новой настройки `[database]
idle_in_transaction_timeout_ms` (10 с). Транзакция замороженной
реплики снимается, ключ освобождается.
- **Замер обнаружения отказа** для `stop`, `kill` и зависшей реплики
(`pause`): действие → `DOWN` в LB → первые успешные ответы →
восстановление доли успеха ≥ 99 %. Формула сверяется с замером.
- **Стенд `bench/` на HAProxy + N реплик.** Тот же `haproxy.cfg`, число
реплик и лимиты LB — поля `Profile`. k6 ходит через LB. При N = 1
профили лабы 2 (`full`, `quick`, `restore`, `restore_quick`)
работают как раньше. CPU и память приложения в метриках — сумма по
репликам.
- **Профиль `failover`** — `make bench_failover` и быстрый `make
bench_failover_quick`:
- две реплики с лимитами рабочего стенда;
- k6 с постоянной интенсивностью: запись с `Idempotency-Key` и
чтение истории;
- по очереди каждая реплика в каждом режиме: остановка посреди
нагрузки, восстановление, следующая;
- режимы `stop` и `kill`, в полном профиле ещё `pause`;
- посекундные успешные RPS и ошибки по кодам, распределение по
`X-Instance-Id`, время обнаружения и восстановления;
- после каждой фазы неподтверждённые записи повторяются с тем же
ключом, и число сообщений сверяется: без потерь и дублей.
Результаты — в `evidence/failover/<метка>/`.
- **Документы.** Правила `balancer.md`, `bench.md`, `run-modes.md`,
`infra.md` — под решения design. `AGENTS.md` — «Переходное
состояние», карта кода, команды. `REPORT.md`:
- таблица цепочки таймаутов;
- замер обнаружения;
- строки доказательств уровня «4»;
- «Эксперименты и отказы»;
- ответ на вопрос защиты «отказ процесса и отказ узла».
Вне этого change:
- поочерёдная замена реплик на новый образ под нагрузкой — change
`rolling-update`;
- открытая модель ступенями до SLO, серии A и B, метрики LB и
PostgreSQL по репликам — change `scaling-bench`. Здесь стенд только
получает LB и N реплик.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `graceful-shutdown`: остановка реплики за балансировщиком. Закрытый
сокет даёт отказ соединения, LB перенаправляет запрос, и при `stop`
под нагрузкой ошибок клиента нет. Простаивающие соединения LB →
реплика первым закрывает LB.
- `load-balancing`:
- быстрые повторные проверки (`fastinter`), формула и замер времени
обнаружения по режимам `stop`, `kill`, `pause`;
- транзакции зависшей реплики снимает PostgreSQL, повтор того же
ключа через другую реплику завершается;
- поочерёдная остановка каждой реплики под постоянной нагрузкой.
- `load-benchmark`:
- стенд — HAProxy и N реплик, генератор ходит через LB;
- метрики приложения — по всем репликам;
- новый профиль `failover` с посекундной шкалой, временем
обнаружения и восстановления, сверкой записей.
- `service-configuration`: новые параметры `[app] keep_alive_seconds`
и `[database] idle_in_transaction_timeout_ms`.
## Impact
- **Конфигурация стенда:** `infra/haproxy/haproxy.cfg` (проверки,
комментарии цепочки), `config_example.toml`.
- **Код приложения:**
- `src/config/settings.py` — два поля;
- `src/main.py` — `timeout_keep_alive` у uvicorn;
- `src/infra/db/engine.py` — серверная настройка
`idle_in_transaction_session_timeout`.
Поведение HTTP API не меняется.
- **Стенд `bench/`:**
- `bench.compose.yml`, `bench.env`;
- `run.py` — реплики, LB, профиль `failover`;
- новые `failover.py` (разбор шкалы, событий LB и docker) и
`k6/failover.js`, `k6/retry.js`;
- `k6/lib.js` — адрес LB, ключ отправки задаётся.
- **Makefile:** цели `bench_failover`, `bench_failover_quick`.
`.gitignore` — пробные метки `evidence/failover/quick-*`.
- **Документы:**
- `.claude/rules/` (`balancer.md`, `bench.md`, `run-modes.md`,
`infra.md`);
- `AGENTS.md`, `REPORT.md`;
- `evidence/failover/`, `evidence/tests/`.
- **Зависимости** не прибавляются: k6 и HAProxy — те же образы.
@@ -0,0 +1,36 @@
# Spec Delta
## ADDED Requirements
### Requirement: Остановка реплики за балансировщиком
Реплика API за балансировщиком (LB) после SIGTERM SHALL сразу
перестать принимать соединения и дорабатывать начатые запросы
(требования выше). Новое соединение с ней LB SHALL получать как отказ
соединения и передавать такой запрос другой реплике. Поэтому штатная
остановка одной реплики из двух (`docker stop`) под постоянной
нагрузкой через LB MUST NOT давать клиенту ошибок: ни ответов 5xx, ни
обрывов. На время обнаружения отказа допустим только рост задержки.
#### Scenario: docker stop под нагрузкой
- **WHEN** через LB с постоянной интенсивностью идут запись с ключом и
чтение истории, и одна из двух реплик остановлена `docker stop`
- **THEN** все ответы фазы — 201 и 200, и это так для остановки каждой
из реплик по очереди
### Requirement: Простаивающие соединения закрывает балансировщик
Реплика SHALL держать простаивающее keep-alive соединение дольше, чем
LB держит такое соединение в своём пуле. Тогда простаивающее
соединение LB → реплика закрывает LB, и он не отправляет запрос в
соединение, которое реплика в этот момент закрывает. Срок простоя на
стороне реплики SHALL задаваться настройкой `[app]
keep_alive_seconds`.
#### Scenario: Пул балансировщика после всплеска
- **WHEN** через LB прошёл всплеск запросов, а затем запросов нет
- **THEN** число простаивающих соединений LB к каждой реплике в
статистике LB становится нулевым раньше `keep_alive_seconds` с
момента последнего запроса
@@ -0,0 +1,121 @@
# Spec Delta
## MODIFIED Requirements
### 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`, и запросы снова распределяются по обеим
## ADDED Requirements
### 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, в чате
ровно одно сообщение с этим текстом, а после разморозки реплика
снова обслуживает запросы
@@ -0,0 +1,202 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Фиксированный стенд
Стенд SHALL состоять из балансировщика (LB), реплик приложения,
PostgreSQL и Valkey. Число реплик SHALL задаваться методикой, по
умолчанию одна. Приложение SHALL запускаться в контейнерах из образа,
собранного из текущего checkout тем же `Dockerfile`. LB SHALL
запускаться из того же образа и с той же конфигурацией, что у рабочего
стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у
рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL
получает те же настройки образа плюс модуль записи планов, выключенный
вне снятия плана. Схема БД SHALL применяться миграциями до наполнения.
Лимиты SHALL быть одинаковыми во всех прогонах профиля:
- у каждой реплики приложения — лимит CPU и памяти без swap, заданный
методикой (в профилях лабы 2 — 1 CPU и 2 ГБ);
- у LB, PostgreSQL и Valkey — свои лимиты CPU и памяти без swap,
заданные методикой.
Healthcheck образа приложения SHALL быть отключён: готовность реплик
проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки
приложения и хранилищ SHALL браться из методики стенда, а не из `.env`
и `config.toml` рабочего стенда. Пароли хранилищ SHALL генерироваться
на прогон. Генератор нагрузки SHALL работать в той же docker-сети и
обращаться к приложению через LB по имени сервиса, минуя проброс
портов хоста. Стенд SHALL считаться готовым, когда LB видит готовыми
все реплики.
#### Scenario: Лимиты в паспорте
- **WHEN** прогон завершён
- **THEN** паспорт стенда содержит число реплик и лимиты CPU и памяти
реплики приложения, LB, PostgreSQL и Valkey, прочитанные у запущенных
контейнеров, и они одинаковы для всех размеров
#### Scenario: Нехватка памяти
- **WHEN** процесс приложения превысил лимит памяти и был убит
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
обычный результат
#### Scenario: Настройки рабочего стенда не влияют
- **WHEN** `.env` и `config.toml` рабочего стенда изменены или
отсутствуют
- **THEN** стенд запускается с теми же настройками приложения и
хранилищ, а окружение приложения в паспорте то же
#### Scenario: Схема до наполнения
- **WHEN** начинается наполнение размера
- **THEN** миграции применены до последней ревизии, и приложение
отвечает готовностью
#### Scenario: Одна реплика за балансировщиком
- **WHEN** профиль лабы 2 (`full`, `quick`, `restore`,
`restore_quick`) запущен с одной репликой
- **THEN** все запросы генератора проходят через LB, прогон завершается
с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и
разделы, что раньше
### Requirement: Метрики прогона
Для каждого измеряемого прогона SHALL сохраняться:
- сценарий, размер истории, конкуренция, номер повтора, длительность;
- число успешных и неуспешных запросов, успешные RPS, доля ошибок;
- задержки p50, p95, p99 и max успешных запросов;
- потреблённое приложением CPU;
- RSS процесса приложения в начале, в конце и максимальный за прогон;
- число сообщений в хранилище в начале и в конце;
- загрузка CPU генератора и CPU контейнера PostgreSQL.
При нескольких репликах CPU, RSS и память приложения SHALL быть суммой
по всем репликам. При одной реплике они совпадают со значениями её
процесса.
Для каждого размера SHALL сохраняться:
- RSS приложения до и после наполнения;
- объём таблицы сообщений и её индексов после обслуживания БД;
- байты на сообщение в БД.
Наполнение SHALL идти порциями. Для каждой порции SHALL сохраняться:
- размер и число сообщений в хранилище до и после;
- успешные RPS и доля ошибок;
- задержки p50, p95, p99 и max;
- CPU приложения и CPU PostgreSQL;
- RSS в конце порции.
Так наполнение до 500 000 даёт кривую «запись при росте хранилища»
без дополнительного времени прогона. Новые метрики SHALL добавляться
новыми столбцами в конце таблиц. Прежние столбцы MUST NOT
переименовываться и удаляться.
#### Scenario: Строка прогона
- **WHEN** проверяющий открывает таблицу прогонов
- **THEN** у каждой строки заполнены все перечисленные поля
#### Scenario: Память на сообщение
- **WHEN** наполнение размера N завершено
- **THEN** в результатах есть прирост RSS приложения за наполнение,
объём таблицы и индексов сообщений и байты на сообщение в БД
#### Scenario: Кривая наполнения
- **WHEN** наполнение размера 500 000 завершено
- **THEN** в таблице наполнения есть строка на каждую порцию, от
пустого хранилища до 500 000 сообщений, с RPS, p95, p99, max, CPU
приложения и PostgreSQL и RSS
#### Scenario: Сумма по репликам
- **WHEN** прогон идёт с двумя репликами
- **THEN** CPU и RSS приложения в строке прогона — сумма значений обеих
реплик
## ADDED Requirements
### Requirement: Профиль отказа реплик
Команда `make bench_failover` (метка `FAILOVER_LABEL`) SHALL на свежем
стенде с двумя репликами и лимитами рабочего стенда по очереди
останавливать каждую реплику под нагрузкой и восстанавливать её. Команда
`make bench_failover_quick` — то же короче, метка `quick-failover-…`, в
git не идёт. Результаты SHALL сохраняться в `evidence/failover/<метка>/`.
Занятая метка SHALL давать отказ до запуска стенда.
Нагрузка — постоянная интенсивность, заданная методикой: запись
сообщения с `Idempotency-Key` и чтение страницы истории. Фаза — одна
реплика в одном режиме:
1. установившаяся нагрузка;
2. действие над репликой: `stop`, `kill` или `pause`;
3. окно отказа;
4. восстановление: запуск того же контейнера или разморозка;
5. нагрузка после возврата.
Режимы полного профиля — `stop`, `kill` и `pause`, быстрого — `stop` и
`kill`. Перед каждой фазой LB SHALL видеть готовыми обе реплики.
Для каждой фазы SHALL сохраняться посекундная шкала от момента
действия:
- успешные записи и чтения;
- ошибки по кодам, ошибка соединения — отдельным кодом;
- доля успешных;
- p50 и p95 задержки успешных;
- распределение ответов по `X-Instance-Id`.
Секунда запроса определяется по моменту его отправки.
Для каждой фазы SHALL сохраняться:
- момент действия по событию Docker;
- время до исключения реплики LB по его журналу;
- время до первой успешной записи и первого успешного чтения после
действия;
- число ошибок по кодам в окне отказа и после возврата;
- время восстановления до доли успешных ≥ 99 % (`load-balancing`);
- время до возврата реплики в LB.
После каждой фазы каждая неподтверждённая запись SHALL повторяться с
тем же ключом и тем же телом до ответа 201. Число сообщений чата записи
SHALL совпадать с числом разных ключей, отправленных за прогон, а
одинаковых текстов в нём MUST NOT быть. Иначе команда завершается с
ненулевым кодом и называет фазу.
#### Scenario: Полный профиль
- **WHEN** выполнен `make bench_failover`
- **THEN** в `evidence/failover/<метка>/` есть шесть фаз (две реплики ×
три режима) с посекундными шкалами, таблица фаз и сводка, код выхода
0
#### Scenario: Быстрый профиль
- **WHEN** выполнен `make bench_failover_quick`
- **THEN** за несколько минут проходят четыре фазы (две реплики ×
`stop` и `kill`), код выхода 0, каталог метки в git не попадает
#### Scenario: Время обнаружения в результатах
- **WHEN** фаза завершена
- **THEN** в таблице фаз есть момент действия, время до исключения
реплики, время до первых успешных ответов, время восстановления и
время до возврата реплики, все на часах ВМ Docker
#### Scenario: Без потерь и дублей
- **WHEN** в окне отказа часть записей получила ошибку
- **THEN** их повтор с тем же ключом получает 201, а в чате записи
столько сообщений, сколько разных ключей отправлено, без одинаковых
текстов
#### Scenario: Хранилище упало во время фазы
- **WHEN** контейнер PostgreSQL или Valkey был убит или перезапущен во
время фазы
- **THEN** команда завершается с ненулевым кодом, называет контейнер, а
стенд удаляется
@@ -0,0 +1,43 @@
# Spec Delta
## ADDED Requirements
### Requirement: Таймауты соединений за балансировщиком
Параметры приложения SHALL задавать два срока простоя соединений:
- `[app] keep_alive_seconds` — сколько секунд реплика держит
простаивающее keep-alive соединение HTTP; по умолчанию 60;
- `[database] idle_in_transaction_timeout_ms` — сколько миллисекунд
PostgreSQL ждёт следующую команду в открытой транзакции соединения
приложения, прежде чем прервать его; по умолчанию 10000, 0 —
без ограничения.
Оба SHALL одинаково действовать в консоли и в docker. Разовая подмена
SHALL работать через окружение (`APP__KEEP_ALIVE_SECONDS`,
`DATABASE__IDLE_IN_TRANSACTION_TIMEOUT_MS`) без правки файлов.
`keep_alive_seconds` SHALL быть целым положительным числом.
`idle_in_transaction_timeout_ms` SHALL быть нулём или целым числом
больше `[database] request_timeout_seconds` в миллисекундах: иначе
PostgreSQL прерывал бы транзакции живых запросов. При нарушении сервис
MUST NOT стартовать. Как эти сроки согласованы с балансировщиком и
сроком запроса, SHALL быть описано в `REPORT.md`.
#### Scenario: Сроки по умолчанию
- **WHEN** параметры в `config.toml` не заданы
- **THEN** реплика держит простаивающее соединение 60 с, а соединения
приложения с PostgreSQL получают
`idle_in_transaction_session_timeout` 10 с
#### Scenario: Срок не число
- **WHEN** сервис запускается с `APP__KEEP_ALIVE_SECONDS=0` или
`DATABASE__IDLE_IN_TRANSACTION_TIMEOUT_MS=abc`
- **THEN** сервис не стартует, в журнале — ошибка проверки настроек
#### Scenario: Срок простоя транзакции не больше срока запроса
- **WHEN** сервис запускается с
`DATABASE__IDLE_IN_TRANSACTION_TIMEOUT_MS=5000` при
`request_timeout_seconds` 6
- **THEN** сервис не стартует, ошибка называет оба параметра
+144
View File
@@ -0,0 +1,144 @@
# Tasks
Как строить — `design.md` (дальше «решение N»). Что должно получиться
— дельты в `specs/`. Перед первым файлом слоя прочитать его правило:
`balancer.md`, `bench.md`, `run-modes.md`, `infra.md`, `settings.md`,
`docker.md`.
Evidence снимается с закоммиченного кода: сначала коммит кода, потом
evidence, потом коммит evidence и отчёта. Замеры для отчёта (полный
профиль `failover`, замер обнаружения) — только после проверки хоста по
брифу основной сессии; рабочий стенд на время замера остановлен.
## 1. Приложение: сроки простоя соединений
- [ ] 1.1 `src/config/settings.py` и `config_example.toml` по решениям
3 и 4:
- `[app] keep_alive_seconds` (int, ≥ 1, по умолчанию 60);
- `[database] idle_in_transaction_timeout_ms` (int, ≥ 0, по умолчанию
10000);
- валидатор `Database`: 0 или больше `request_timeout_seconds` ×
1000, иначе ошибка с обоими именами.
Проверка: `uv run python -c` печатает поля по умолчанию; запуск с
`APP__KEEP_ALIVE_SECONDS=0`, `DATABASE__IDLE_IN_TRANSACTION_TIMEOUT_MS=abc`
и `=5000` — код 1, ошибка называет поле.
- [ ] 1.2 `src/main.py`: `timeout_keep_alive` у `uvicorn.run`.
`src/infra/db/engine.py`: `idle_in_transaction_session_timeout` в
`server_settings`, если значение не 0. Проверка: `SHOW
idle_in_transaction_session_timeout` на соединении engine приложения
внутри реплики — `10s`.
## 2. Балансировщик
- [ ] 2.1 `infra/haproxy/haproxy.cfg` по решениям 1–3:
- `fastinter 500ms` в `default-server`;
- `timeout check 2500ms`;
- `pool-purge-delay 5s` в `backend api`;
- комментарии к числам — формулы обнаружения по режимам из таблицы
решения 1 и соотношение с `keep_alive_seconds`.
Проверка: `haproxy -c` в закреплённом образе с `API_PORT=8080` —
`Configuration file is valid`.
## 3. Стенд `bench/` на HAProxy + N реплик
- [ ] 3.1 `bench/bench.compose.yml` и `bench/run.py` по решению 6:
- реплики без `container_name`, `BENCH_API_REPLICAS`;
- `haproxy` с лимитами `BENCH_LB_*`;
- поля `Profile` `replicas`, `lb_cpus`, `lb_memory`;
- готовность по статистике LB;
- снимки — сумма по репликам;
- паспорт с LB и числом реплик;
- `switch_api` с ожиданием реплик в LB.
`bench/k6/lib.js`: адрес LB по умолчанию, ключ отправки задаётся.
Проверка: `make lint`; `make bench_quick` и `make bench_restore_quick`
— код 0, в паспорте `api_replicas` 1 и лимиты LB.
- [ ] 3.2 Профиль `failover` по решениям 5 и 7:
- новые `bench/failover.py`, `bench/k6/failover.js`,
`bench/k6/retry.js`;
- профили `failover` и `failover_quick` в `run.py`, оркестрация фаз,
результаты в `evidence/failover/<метка>/`;
- цели `bench_failover`, `bench_failover_quick` в `Makefile`;
- `evidence/failover/quick-*/` в `.gitignore`.
Проверка: `make bench_failover_quick` — код 0, четыре фазы. В
`phases.csv` у каждой фазы есть обнаружение, восстановление, возврат
в LB и сошедшаяся сверка; `timeline.csv` посекундный; занятая метка
— отказ до запуска стенда.
## 4. Команды драйвера
- [ ] 4.1 `.claude/skills/run-mtusi-messenger/driver.py` и `SKILL.md`
по решению 8: `idle-conns`, `hang-key`. Проверка на рабочем стенде
после пересоздания с новым кодом:
- `driver.py --port 8080 idle-conns` — пул LB пуст раньше 60 с, код
0;
- `driver.py --port 8080 hang-key` — повтор ключа получает 201 после
прерывания транзакции, одно сообщение, в журнале PostgreSQL —
«idle-in-transaction timeout»; триггера после команды нет.
## 5. Документы и общая проверка кода
- [ ] 5.1 Правила и инструкции под решения:
- `balancer.md` — цепочка (`fastinter`, `timeout check`,
`pool-purge-delay` и keep-alive, обнаружение по режимам);
- `bench.md` — стенд с LB и N репликами, профиль `failover`, его
результаты, методика лабы 3;
- `run-modes.md` — `timeout_keep_alive`;
- `infra.md` — `idle_in_transaction_session_timeout`;
- скилл — новые команды.
`AGENTS.md`:
- «Переходное состояние» — убрать закрытый пункт `bench/`;
- карта кода — `failover.py`, `k6/failover.js`, `k6/retry.js`,
`evidence/failover/<метка>/`;
- команды — `bench_failover`, `bench_failover_quick`.
Проверка: `grep -n "graceful-failover" AGENTS.md .claude/rules/*.md` —
нет обещаний «будет в этом change».
- [ ] 5.2 Общая проверка кода:
- `make lint`, `make check`;
- `openspec validate graceful-failover --strict`;
- `make down`, `make run_docker`;
- `make test`, `make student_test` через LB;
- `make test_isolated`, `make failure_checks`;
- `make test-persistence ACTION_SCRIPT=scripts/restart.sh`;
- `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` в режимах
`stop` и `kill`, `make replicas` между прогонами;
- `make bench_quick`, `make bench_restore_quick`,
`make bench_failover_quick`.
Затем коммит кода.
## 6. Замеры, evidence и отчёт
- [ ] 6.1 Хост по брифу: питание, давление на память, посторонние
контейнеры, `vm_stat` (`Swapouts`) до. Рабочий стенд — `make stop`.
`make bench_failover` отвязанно через `nohup`, затем `Swapouts` после.
Проверка: метка `evidence/failover/baseline/` со статусом `complete`,
шесть фаз, сверка сошлась.
- [ ] 6.2 Evidence по таблице решения 9 с закоммиченного кода:
- `detection.md`, `keep-alive.md`, `hung-key.md`;
- `evidence/tests/graceful-failover-checks.md`.
Проверка: в шапке каждого — спеки, change, дата, commit, стенд, хост.
Нет паролей, токенов и абсолютных путей домашнего каталога.
- [ ] 6.3 `REPORT.md` по решению 9:
- цепочка таймаутов;
- формула и замер обнаружения;
- строки доказательств уровня «4»;
- «Эксперименты и отказы»;
- ответ «отказ процесса и отказ узла»;
- ограничения.
Проверка: у каждой новой строки таблицы доказательств есть команда,
наблюдение и файл.
- [ ] 6.4 Финал:
- `make lint`, `make check`, `openspec validate graceful-failover
--strict`;
- отметить задачи, коммит evidence и отчёта;
- `graphify update .`;
- рабочий стенд `mtusi-lab3` запущен через LB, обе реплики `UP`;
- рабочее дерево чистое.