diff --git a/openspec/changes/add-lab3-failover-operations/.openspec.yaml b/openspec/changes/archive/2026-10-28-add-lab3-failover-operations/.openspec.yaml similarity index 58% rename from openspec/changes/add-lab3-failover-operations/.openspec.yaml rename to openspec/changes/archive/2026-10-28-add-lab3-failover-operations/.openspec.yaml index 1bb6456d..01fc7ab7 100644 --- a/openspec/changes/add-lab3-failover-operations/.openspec.yaml +++ b/openspec/changes/archive/2026-10-28-add-lab3-failover-operations/.openspec.yaml @@ -1,2 +1,4 @@ schema: spec-driven created: 2026-10-28 +archived: 2026-10-28 +lab: 3 diff --git a/openspec/changes/add-lab3-failover-operations/design.md b/openspec/changes/archive/2026-10-28-add-lab3-failover-operations/design.md similarity index 100% rename from openspec/changes/add-lab3-failover-operations/design.md rename to openspec/changes/archive/2026-10-28-add-lab3-failover-operations/design.md diff --git a/openspec/changes/add-lab3-failover-operations/proposal.md b/openspec/changes/archive/2026-10-28-add-lab3-failover-operations/proposal.md similarity index 100% rename from openspec/changes/add-lab3-failover-operations/proposal.md rename to openspec/changes/archive/2026-10-28-add-lab3-failover-operations/proposal.md diff --git a/openspec/changes/add-lab3-failover-operations/specs/lab1-service-operability/spec.md b/openspec/changes/archive/2026-10-28-add-lab3-failover-operations/specs/lab1-service-operability/spec.md similarity index 100% rename from openspec/changes/add-lab3-failover-operations/specs/lab1-service-operability/spec.md rename to openspec/changes/archive/2026-10-28-add-lab3-failover-operations/specs/lab1-service-operability/spec.md diff --git a/openspec/changes/add-lab3-failover-operations/specs/lab2-dependency-failures/spec.md b/openspec/changes/archive/2026-10-28-add-lab3-failover-operations/specs/lab2-dependency-failures/spec.md similarity index 100% rename from openspec/changes/add-lab3-failover-operations/specs/lab2-dependency-failures/spec.md rename to openspec/changes/archive/2026-10-28-add-lab3-failover-operations/specs/lab2-dependency-failures/spec.md diff --git a/openspec/changes/add-lab3-failover-operations/specs/lab3-failover-operations/spec.md b/openspec/changes/archive/2026-10-28-add-lab3-failover-operations/specs/lab3-failover-operations/spec.md similarity index 100% rename from openspec/changes/add-lab3-failover-operations/specs/lab3-failover-operations/spec.md rename to openspec/changes/archive/2026-10-28-add-lab3-failover-operations/specs/lab3-failover-operations/spec.md diff --git a/openspec/changes/add-lab3-failover-operations/tasks.md b/openspec/changes/archive/2026-10-28-add-lab3-failover-operations/tasks.md similarity index 100% rename from openspec/changes/add-lab3-failover-operations/tasks.md rename to openspec/changes/archive/2026-10-28-add-lab3-failover-operations/tasks.md diff --git a/openspec/specs/lab1-service-operability/spec.md b/openspec/specs/lab1-service-operability/spec.md index 8bcaa26b..1aed9489 100644 --- a/openspec/specs/lab1-service-operability/spec.md +++ b/openspec/specs/lab1-service-operability/spec.md @@ -79,7 +79,7 @@ ### Requirement: Корректное завершение по сигналу -По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд; срок мягкой остановки сервера SHALL быть меньше `stop_grace_period` контейнера, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую. +По получении `SIGTERM` сервис SHALL сначала выйти из ротации: на время окна `DRAIN_SECONDS` (по умолчанию 2 с, больше максимального времени обнаружения балансировщиком) `/health/ready` SHALL отвечать `503 unavailable`, а принятые и новые запросы SHALL обслуживаться как обычно. После окна сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс; весь срок, включая окно, SHALL укладываться в `SHUTDOWN_TIMEOUT_SECONDS` (по умолчанию 5 с), который меньше таймаута хука остановки, `stop_grace_period` контейнера и 10 секунд, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую. #### Scenario: Остановка укладывается в срок @@ -87,6 +87,11 @@ - **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period` - **AND** код завершения соответствует штатной остановке, а не убийству по таймауту +#### Scenario: Сначала вывод из ротации + +- **WHEN** процессу сервера послан `SIGTERM` +- **THEN** в течение окна `DRAIN_SECONDS` `/health/ready` отвечает `503` в общем формате ошибки, `/health/live` — `200`, соединения ещё принимаются, а после окна порт закрыт и процесс завершается с кодом 0 не позднее `SHUTDOWN_TIMEOUT_SECONDS` + #### Scenario: Принятый запрос дорабатывается - **WHEN** `SIGTERM` приходит во время обработки принятого запроса diff --git a/openspec/specs/lab2-dependency-failures/spec.md b/openspec/specs/lab2-dependency-failures/spec.md index 536c8eb1..b53fde59 100644 --- a/openspec/specs/lab2-dependency-failures/spec.md +++ b/openspec/specs/lab2-dependency-failures/spec.md @@ -5,18 +5,24 @@ ## Requirements ### Requirement: Отказ PostgreSQL даёт ограниченную ошибку -При недоступном PostgreSQL защищённые endpoint и `/health/ready` SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` SHALL отвечать `200`. +При недоступном PostgreSQL защищённые endpoint и `/health/ready` каждой реплики SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` реплики SHALL отвечать `200`. Балансировщик SHALL исключить все реплики из ротации не позднее чем через 1,5 с после отказа и SHALL сам отвечать на любой запрос `503` в общем формате ошибки с `request_id`, равным `X-Request-Id`; после возвращения PostgreSQL реплики SHALL вернуться в ротацию без перезапуска. #### Scenario: PostgreSQL остановлен - **WHEN** сервис `postgres` остановлен -- **THEN** `GET /health/ready` и `GET /api/v1/users/me` отвечают `503 unavailable` быстрее 2 с, `GET /health/live` — `200`, ни один ответ не `500` +- **THEN** `GET /health/ready` и `GET /api/v1/users/me` через LB отвечают `503 unavailable` быстрее 2 с, `GET /health/live` внутри реплики — `200`, ни один ответ не `500` #### Scenario: Неизвестный токен при остановленной БД - **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном - **THEN** ответ `503`, а не `200` +#### Scenario: Балансировщик исключает все реплики + +- **WHEN** PostgreSQL остановлен дольше времени обнаружения +- **THEN** статистика LB показывает 0 готовых реплик, а запрос через LB, включая `GET /health/live`, получает `503 {"error":{"code":"unavailable",...}}` без `X-Instance-Id` +- **AND** после запуска PostgreSQL все реплики снова готовы в LB без перезапуска своих процессов + ### Requirement: Восстановление без рестарта API После возвращения PostgreSQL API SHALL восстанавливать обслуживание без перезапуска своего процесса за счёт переподключения пула. diff --git a/openspec/specs/lab3-failover-operations/spec.md b/openspec/specs/lab3-failover-operations/spec.md new file mode 100644 index 00000000..c1d5a4fa --- /dev/null +++ b/openspec/specs/lab3-failover-operations/spec.md @@ -0,0 +1,85 @@ +# lab3-failover-operations Specification + +## Purpose +Определяет эксплуатационные гарантии реплицированного стенда: за какое время балансировщик исключает отказавшую реплику, как переживается поочерёдный отказ и плановая замена реплик под нагрузкой, как проверяется общая идемпотентность параллельными запросами и как ограничены ресурсы, порты, секреты и хранилища. +## Requirements +### Requirement: Согласованные проверки, таймауты и остановка + +Балансировщик SHALL проверять каждую реплику `GET /health/ready` с периодом 1 с, после первого провала — каждые 0,5 с, исключать её после 2 провалов подряд и возвращать после 2 успехов. Реплика, которая появилась или вернулась через DNS (запуск, `restore.sh`, новая реплика rolling update), SHALL получать запросы только после 2 успешных проверок, а не сразу после появления адреса. Максимальное время обнаружения SHALL составлять 1,5 с для реплики, которая отвечает `503` или отказывает в соединении, и 3,5 с для зависшей реплики (с таймаутом проверки 1 с). Readiness реплики SHALL отвечать быстрее таймаута проверки. Цепочка таймаутов SHALL убывать от внешнего звена к внутреннему: ожидание ответа балансировщиком > таймаут запроса в приложении > таймаут оператора и ожидания соединения с БД. Срок остановки реплики SHALL укладываться в таймаут хука остановки, а тот — в `stop_grace_period` и в 10 с. + +#### Scenario: Конфигурация согласована + +- **WHEN** выполняется `make student-test` +- **THEN** тест цепочки таймаутов по `compose.yaml`, `infra/haproxy/haproxy.cfg` и `scripts/stop-one.sh` проходит: окно вывода из ротации больше максимума обнаружения, срок остановки меньше таймаута хука, таймаут хука меньше `stop_grace_period` и 10 с, `timeout server` балансировщика больше `REQUEST_TIMEOUT_SECONDS`, а тот больше суммы таймаутов БД + +#### Scenario: Обнаружение измерено по каждому виду отказа + +- **WHEN** выполняется `make detection` +- **THEN** для `SIGTERM` через `scripts/stop-one.sh`, `docker kill`, `docker pause` и остановки PostgreSQL в `evidence/detection/*.json` записаны время обнаружения, заявленный максимум и время возврата в ротацию, и каждое время обнаружения не больше заявленного максимума + +#### Scenario: Остановка по сигналу не теряет запросы + +- **WHEN** реплике посылается `SIGTERM` через `scripts/stop-one.sh` +- **THEN** балансировщик исключает её раньше, чем хук завершился, а реплика закрывает приём соединений только после этого + +#### Scenario: Возврат реплики без преждевременного трафика + +- **WHEN** остановленная реплика запускается снова под нагрузкой +- **THEN** балансировщик не направляет на неё запросы, пока она не прошла 2 проверки готовности: счётчики повторов и перенаправлений LB (`wretr`, `wredis`) за прогон равны 0 + +#### Scenario: Зависшая реплика + +- **WHEN** процесс реплики приостановлен (`docker pause`) и не отвечает на проверки +- **THEN** балансировщик исключает её не позднее чем через 3,5 с, а после `docker unpause` возвращает в ротацию + +### Requirement: Поочерёдный отказ под нагрузкой + +Оператор SHALL одной командой останавливать каждую реплику по очереди под открытой нагрузкой (постоянная интенсивность запросов, 80 % отправок сообщений и 20 % чтений истории) и возвращать её до остановки следующей. Для каждой реплики SHALL фиксироваться интенсивность и доля ошибок нагрузки, задержки p50/p95/p99, время обнаружения, время возврата в ротацию, ошибки и время восстановления записи зонда, повторяющего неудачную запись с тем же ключом, и счётчики повторов и перенаправлений балансировщика. + +#### Scenario: Каждая реплика по очереди + +- **WHEN** выполняется `make failover-each` +- **THEN** `evidence/failover-each/summary.json` содержит запись на каждую реплику; в каждой хук завершился кодом 0, доля ошибок нагрузки не больше 1 %, запись восстановилась не позже 10 с, пока реплика была исключена, её `X-Instance-Id` не встречался, а после возврата она снова обслуживает запросы + +### Requirement: Общая идемпотентность под параллельными запросами + +Параллельные `POST /api/v1/chats/{chat_id}/messages` с одним `Idempotency-Key` и одним телом, распределённые балансировщиком по разным репликам, SHALL создавать ровно одно сообщение и SHALL получать одинаковые ответы `201`; тот же ключ с другим телом SHALL получать `409`. + +#### Scenario: Серия гонок через LB + +- **WHEN** выполняется `make lb-check` (20 раундов по 8 параллельных запросов с одним ключом на раунд) +- **THEN** все 160 ответов `201`, их обслужили не менее двух реплик, в каждом раунде тела ответов совпадают, в истории ровно одна копия, а другой body получает `409` + +### Requirement: Лимиты и изоляция + +Каждый сервис стенда, включая генератор нагрузки, SHALL иметь лимиты CPU и памяти. Ни один сервис SHALL NOT задавать `container_name`. Опубликованные порты SHALL быть только у балансировщика и только на `127.0.0.1`. Секреты SHALL монтироваться только сервисам, которые ими пользуются; volumes данных SHALL принадлежать только своему хранилищу; реплики API SHALL работать с корневой файловой системой только для чтения; внутренняя сеть SHALL быть недоступна снаружи, а генератор нагрузки SHALL видеть только балансировщик. + +#### Scenario: Проверка лимитов и изоляции + +- **WHEN** выполняется `make limits` +- **THEN** проверка по `docker compose config` и `docker inspect` запущенных контейнеров печатает таблицу сервисов с лимитами, портами, секретами, volumes и сетями в `evidence/limits.txt` и завершается `PASS`; ни у одного контейнера `api` нет опубликованных портов + +#### Scenario: Нарушение политики + +- **WHEN** сервису без необходимости добавлен секрет, порт или `container_name`, либо снят лимит +- **THEN** `make limits` перечисляет нарушение и завершается ненулевым кодом + +### Requirement: Поочерёдная замена под нагрузкой и однократные миграции + +Оператор SHALL одной командой заменять реплики новой версией образа по одной: сначала миграции применяются один раз отдельным процессом, затем на каждую старую реплику запускается новая, и старая останавливается только после того, как балансировщик видит новую готовой. Число готовых реплик в балансировщике SHALL NOT опускаться ниже исходного. Миграции SHALL быть совместимы с работающей предыдущей версией (только добавление объектов схемы) либо ограничение SHALL быть описано в `REPORT.md`. + +#### Scenario: Замена под нагрузкой + +- **WHEN** выполняется `make rolling-update` +- **THEN** `evidence/rolling/result.json` показывает, что балансировщик ни разу не видел меньше исходного числа готовых реплик, доля ошибок нагрузки не больше 1 %, зонд не потерял записей, а после замены запросы обслуживают только новые контейнеры + +#### Scenario: Обновление с прежней версии + +- **WHEN** выполняется `make rolling-update FROM_REV=<коммит>` +- **THEN** стенд сначала поднимается на образе, собранном из этого коммита, а затем заменяется текущей версией с теми же гарантиями; журнал замены называет старый и новый образ каждой реплики + +#### Scenario: Миграции один раз + +- **WHEN** идёт поочерёдная замена +- **THEN** `migrate` запускается один раз до замены первой реплики, реплики схему не меняют, а повторный запуск сообщает `up to date` +