From b76a666621cdfa592563ea519eb99aa68c32e9eb Mon Sep 17 00:00:00 2001 From: roman Date: Sat, 10 Oct 2026 22:32:12 +0300 Subject: [PATCH] docs: propose graceful-failover change Co-Authored-By: Claude Opus 5.5 --- .../changes/graceful-failover/.openspec.yaml | 2 + openspec/changes/graceful-failover/design.md | 513 ++++++++++++++++++ .../changes/graceful-failover/proposal.md | 136 +++++ .../specs/graceful-shutdown/spec.md | 36 ++ .../specs/load-balancing/spec.md | 121 +++++ .../specs/load-benchmark/spec.md | 202 +++++++ .../specs/service-configuration/spec.md | 43 ++ openspec/changes/graceful-failover/tasks.md | 144 +++++ 8 files changed, 1197 insertions(+) create mode 100644 openspec/changes/graceful-failover/.openspec.yaml create mode 100644 openspec/changes/graceful-failover/design.md create mode 100644 openspec/changes/graceful-failover/proposal.md create mode 100644 openspec/changes/graceful-failover/specs/graceful-shutdown/spec.md create mode 100644 openspec/changes/graceful-failover/specs/load-balancing/spec.md create mode 100644 openspec/changes/graceful-failover/specs/load-benchmark/spec.md create mode 100644 openspec/changes/graceful-failover/specs/service-configuration/spec.md create mode 100644 openspec/changes/graceful-failover/tasks.md diff --git a/openspec/changes/graceful-failover/.openspec.yaml b/openspec/changes/graceful-failover/.openspec.yaml new file mode 100644 index 00000000..53f62d70 --- /dev/null +++ b/openspec/changes/graceful-failover/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-10 diff --git a/openspec/changes/graceful-failover/design.md b/openspec/changes/graceful-failover/design.md new file mode 100644 index 00000000..cb4b06f2 --- /dev/null +++ b/openspec/changes/graceful-failover/design.md @@ -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=`, `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:`: имя сервиса — алиас в + сети `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)`. Ключ — `<прогон>.<фаза>.`: + повтор строит тот же ключ без журнала ключей. + - Чтение — страница истории читаемого чата с курсором из пула, зерно + профиля, проверка полной страницы. + - Каждый запрос — строка `fo,,,<отправка мс>,<длительность + мс>,<статус>,` в вывод 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`. + Схема БД не менялась. diff --git a/openspec/changes/graceful-failover/proposal.md b/openspec/changes/graceful-failover/proposal.md new file mode 100644 index 00000000..35efdc05 --- /dev/null +++ b/openspec/changes/graceful-failover/proposal.md @@ -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 — те же образы. diff --git a/openspec/changes/graceful-failover/specs/graceful-shutdown/spec.md b/openspec/changes/graceful-failover/specs/graceful-shutdown/spec.md new file mode 100644 index 00000000..7ec4bb05 --- /dev/null +++ b/openspec/changes/graceful-failover/specs/graceful-shutdown/spec.md @@ -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` с + момента последнего запроса diff --git a/openspec/changes/graceful-failover/specs/load-balancing/spec.md b/openspec/changes/graceful-failover/specs/load-balancing/spec.md new file mode 100644 index 00000000..0fc0cebf --- /dev/null +++ b/openspec/changes/graceful-failover/specs/load-balancing/spec.md @@ -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, в чате + ровно одно сообщение с этим текстом, а после разморозки реплика + снова обслуживает запросы diff --git a/openspec/changes/graceful-failover/specs/load-benchmark/spec.md b/openspec/changes/graceful-failover/specs/load-benchmark/spec.md new file mode 100644 index 00000000..b1145aed --- /dev/null +++ b/openspec/changes/graceful-failover/specs/load-benchmark/spec.md @@ -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** команда завершается с ненулевым кодом, называет контейнер, а + стенд удаляется diff --git a/openspec/changes/graceful-failover/specs/service-configuration/spec.md b/openspec/changes/graceful-failover/specs/service-configuration/spec.md new file mode 100644 index 00000000..d931152f --- /dev/null +++ b/openspec/changes/graceful-failover/specs/service-configuration/spec.md @@ -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** сервис не стартует, ошибка называет оба параметра diff --git a/openspec/changes/graceful-failover/tasks.md b/openspec/changes/graceful-failover/tasks.md new file mode 100644 index 00000000..1b945fc6 --- /dev/null +++ b/openspec/changes/graceful-failover/tasks.md @@ -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`; + - рабочее дерево чистое.