fix: correct replicas-lb details found in verify

- stop-one.sh: an empty TARGET_INSTANCE_ID now exits 2 in any shell,
  as the design states (${VAR:?} gave 1 under bash).
- driver.py kill-inflight: reproducible "aborted response is not
  retried" scenario (logins in flight, replica killed via stop-one.sh).
- Detection time of a hung replica is fall x (inter + timeout check) =
  8 s, not inter x fall + timeout check = 5 s (docker pause: 7.3 s);
  fixed in haproxy.cfg, balancer.md and the design.
- The 1 CPU replica limit is kept on purpose; the compose comment and
  the design now say that Argon2id uses more and logins are slower.
- load-balancing spec: API_REPLICAS is read by compose and Makefile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-10 18:44:57 +03:00
co-authored by Claude Opus 5.5
parent de93056eab
commit a4ca9ef3a7
10 changed files with 287 additions and 29 deletions
+17 -4
View File
@@ -96,9 +96,15 @@ paths:
Числа живут в конфигах и в таблице `REPORT.md`. Правило — соотношения Числа живут в конфигах и в таблице `REPORT.md`. Правило — соотношения
между ними: между ними:
- время обнаружения отказа ≈ `inter × fall + timeout check` ≤ 10 с - худшее время обнаружения отказа ≤ 10 с (рубрика «3»: «не позднее
(рубрика «3»: «не позднее 10 секунд»). В `REPORT.md` — и формула, и 10 секунд»). HAProxy начинает следующую проверку через `inter` после
замер (замер — change `graceful-failover`); конца предыдущей, поэтому для зависшей реплики (соединение есть,
ответа нет) худшее ≈ `fall × (inter + timeout check)`, а не `inter ×
fall + timeout check`: при 1 с / 2 / 3 с — 8 с, замер `docker pause` —
7,3 с (change `replicas-lb`). Остановленную реплику проверка не ждёт:
отказ соединения сразу или `timeout connect`, пропавший адрес DNS
убирает за 1–2 с. В `REPORT.md` — и формула, и замер по режимам
(change `graceful-failover`);
- `timeout connect` × (`retries` + 1) < 2 с: таймаут клиента в - `timeout connect` × (`retries` + 1) < 2 с: таймаут клиента в
`tests/resilience.py` — 2 с, и повтор на живую реплику должен успеть `tests/resilience.py` — 2 с, и повтор на живую реплику должен успеть
раньше. Поэтому `timeout connect` 500 мс, а не 1 с, и `redispatch 1`; раньше. Поэтому `timeout connect` 500 мс, а не 1 с, и `redispatch 1`;
@@ -140,7 +146,14 @@ Hook для `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
остановлен: `docker compose ps` до и после, ID совпадает с остановлен: `docker compose ps` до и после, ID совпадает с
`TARGET_INSTANCE_ID` (строка `STOP_ONE_LOG`). Одного заголовка мало `TARGET_INSTANCE_ID` (строка `STOP_ONE_LOG`). Одного заголовка мало
(README, «Сценарий защиты», п. 3). Повторить для каждой реплики, (README, «Сценарий защиты», п. 3). Повторить для каждой реплики,
восстанавливая предыдущую (`make replicas`). восстанавливая предыдущую (`make replicas`). Тест останавливает
реплику, ответившую на его первую отправку; при round-robin по двум
репликам после `make replicas` это снова та же, поэтому перед прогоном
для другой очередь сдвигают одним запросом через LB.
- Оборванный ответ при `kill` (запрос уже на реплике, LB его не
повторяет) — `driver.py --port 8080 kill-inflight` скилла
`run-mtusi-messenger`: входы по Basic в полёте и kill реплики через
этот hook.
## Свои цели Makefile ## Свои цели Makefile
+18 -4
View File
@@ -13,7 +13,8 @@ FastAPI/uvicorn, данные в PostgreSQL из compose, карточки ча
останавливает сервер. Против стенда compose (`make run_docker`: останавливает сервер. Против стенда compose (`make run_docker`:
HAProxy на `APP_OUT_PORT` перед репликами API) работают те же команды HAProxy на `APP_OUT_PORT` перед репликами API) работают те же команды
драйвера, кроме `start`/`stop`, плюс `instances` — распределение одной драйвера, кроме `start`/`stop`, плюс `instances` — распределение одной
сессии по репликам. Только стандартная библиотека Python. сессии по репликам и `kill-inflight` — kill реплики с запросами в
полёте. Только стандартная библиотека Python.
Все пути — от корня репозитория. Проверено на macOS (arm64), uv 0.12, Все пути — от корня репозитория. Проверено на macOS (arm64), uv 0.12,
Python 3.12 из `.python-version`, Docker Desktop 29.8. Python 3.12 из `.python-version`, Docker Desktop 29.8.
@@ -30,8 +31,9 @@ Python 3.12 из `.python-version`, Docker Desktop 29.8.
Аутентификация лабы 2: регистрация с `password`, вход Аутентификация лабы 2: регистрация с `password`, вход
`POST /api/v1/auth/sessions` по `Authorization: Basic`, дальше — `POST /api/v1/auth/sessions` по `Authorization: Basic`, дальше —
`Authorization: Bearer <token>`. `X-User-Id` доступа не даёт. Пароль — `Authorization: Bearer <token>`. `X-User-Id` доступа не даёт. Пароль —
Argon2id, около 30 мс на регистрацию и вход, поэтому `flow` и Argon2id, около 30 мс на регистрацию и вход в консоли и около 120 мс в
`student-tests` идут дольше, чем на лабе 1. контейнере с лимитом 1 CPU, поэтому `flow` и `student-tests` идут
дольше, чем на лабе 1, а `make test_isolated` — около минуты.
## Setup ## Setup
@@ -85,6 +87,7 @@ python3 $D stop
| `smoke` | `tests/smoke.py --base-url http://localhost:<port>` | | `smoke` | `tests/smoke.py --base-url http://localhost:<port>` |
| `student` | `make student_test BASE_URL=http://localhost:<port>` (pytest по `student-tests/`); против своего процесса (есть pid-файл) — с `EXPECT_REPLICAS=1`, тесты реплик пропускаются с причиной; код 1, если каталога нет | | `student` | `make student_test BASE_URL=http://localhost:<port>` (pytest по `student-tests/`); против своего процесса (есть pid-файл) — с `EXPECT_REPLICAS=1`, тесты реплик пропускаются с причиной; код 1, если каталога нет |
| `instances [--count N]` | вход одним синтетическим пользователем, N (12) × `GET /api/v1/users/me` с одним токеном: `X-Instance-Id` каждого ответа и число ответов каждой реплики; токен не печатается. Его зовёт `make instances` | | `instances [--count N]` | вход одним синтетическим пользователем, N (12) × `GET /api/v1/users/me` с одним токеном: `X-Instance-Id` каждого ответа и число ответов каждой реплики; токен не печатается. Его зовёт `make instances` |
| `kill-inflight [--threads 8] [--seconds 4] [--after 1.5]` | только стенд с LB (`--port 8080`): потоки входят по Basic, через `--after` с `scripts/stop-one.sh` в режиме kill убивает реплику пробного запроса. Печатает статусы по репликам и ответы LB: оборванные входы — 502 в формате контракта без повтора, начатые после kill — 201 от другой реплики. Код 1, если оборванных нет. Реплика остаётся остановленной — `make replicas` |
| `stop` | SIGTERM всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает | | `stop` | SIGTERM всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает |
| `all` | всё подряд (`student` — если есть `student-tests/`), `stop` в `finally` | | `all` | всё подряд (`student` — если есть `student-tests/`), `stop` в `finally` |
@@ -120,6 +123,7 @@ make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка р
STOP_MODE=kill STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh STOP_MODE=kill STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# kill вместо graceful; журнал: какой TARGET_INSTANCE_ID и контейнер # kill вместо graceful; журнал: какой TARGET_INSTANCE_ID и контейнер
TARGET_INSTANCE_ID=<x-instance-id> scripts/stop-one.sh # остановить одну реплику руками TARGET_INSTANCE_ID=<x-instance-id> scripts/stop-one.sh # остановить одну реплику руками
python3 $D --port 8080 kill-inflight # kill реплики во время входов: 502 от LB без повтора
make replicas # вернуть остановленные реплики (те же ID), ждать healthy make replicas # вернуть остановленные реплики (те же ID), ждать healthy
make replicas API_REPLICAS=3 # разово 3 реплики; LB видит новую за 1–3 с без правки конфига make replicas API_REPLICAS=3 # разово 3 реплики; LB видит новую за 1–3 с без правки конфига
make down # удалить контейнеры, volume с данными остаётся make down # удалить контейнеры, volume с данными остаётся
@@ -133,6 +137,12 @@ make wipe_data # удалить и данные: т
`make test-failover` — `make replicas`: иначе следующий прогон увидит `make test-failover` — `make replicas`: иначе следующий прогон увидит
одну реплику и упадёт на `less than two API instances observed`. одну реплику и упадёт на `less than two API instances observed`.
Тест останавливает реплику, ответившую на его первую отправку, а число
запросов до неё постоянно. При round-robin по двум репликам после `make
replicas` он снова выберет ту же. Чтобы остановить другую, очередь LB
сдвигают одним запросом перед тестом: `curl -s -o /dev/null
http://127.0.0.1:8080/health/live`.
## Direct invocation (без HTTP) ## Direct invocation (без HTTP)
Для правок в `src/core/` сервисы вызываются поверх сессии БД, сервер не Для правок в `src/core/` сервисы вызываются поверх сессии БД, сервер не
@@ -289,7 +299,11 @@ make lint # ruff; затрагивает и dr
- **`/health/ready` отвечает 503, `/health/live` — 200** — Postgres - **`/health/ready` отвечает 503, `/health/live` — 200** — Postgres
недоступен: `docker compose ps postgres`, `make start_db`. Запросы к недоступен: `docker compose ps postgres`, `make start_db`. Запросы к
API в это время получают 503 `unavailable`, после возврата Postgres API в это время получают 503 `unavailable`, после возврата Postgres
проходят без рестарта сервера. проходят без рестарта сервера. Так отвечает один процесс (консоль).
Через LB реплики без Postgres не проходят проверку `/health/ready`, и
через 2–3 с на всё, включая `/health/live`, отвечает сам HAProxy: 503
`No API replica is available`. После возврата Postgres реплики
возвращаются через 2 проверки.
- **В логе `warning` «Cache is unavailable»** — Valkey остановлен или - **В логе `warning` «Cache is unavailable»** — Valkey остановлен или
завис (рестарт Valkey отказом не считается: клиент один раз завис (рестарт Valkey отказом не считается: клиент один раз
переоткрывает соединение): `docker compose ps valkey`, `make переоткрывает соединение): `docker compose ps valkey`, `make
@@ -21,6 +21,12 @@
instances [--count N] распределение одной сессии по репликам: вход instances [--count N] распределение одной сессии по репликам: вход
одним синтетическим пользователем, N × GET /users/me с одним одним синтетическим пользователем, N × GET /users/me с одним
токеном, X-Instance-Id каждого ответа и итог по репликам токеном, X-Instance-Id каждого ответа и итог по репликам
kill-inflight [--threads N] [--seconds S] [--after A] только стенд
с LB: N потоков S секунд входят по Basic (Argon2id — запросы
в полёте есть всегда), через A секунд scripts/stop-one.sh в
режиме kill убивает реплику пробного запроса; статусы по
репликам и ответы LB. Реплика остаётся остановленной
(make replicas)
stop остановить свой экземпляр на порту stop остановить свой экземпляр на порту
all start → flow → smoke → student (если есть student-tests/) → stop all start → flow → smoke → student (если есть student-tests/) → stop
@@ -40,6 +46,7 @@ import os
import signal import signal
import subprocess import subprocess
import sys import sys
import threading
import time import time
import urllib.error import urllib.error
import urllib.request import urllib.request
@@ -595,6 +602,108 @@ def cmd_instances(port: int, count: int) -> int:
return 1 if failures else 0 return 1 if failures else 0
def cmd_kill_inflight(
port: int,
*,
threads: int,
seconds: float,
after: float,
) -> int:
"""Сценарий «Оборванный ответ не повторяется» (спек `load-balancing`).
`threads` потоков `seconds` секунд подряд входят по Basic одним
синтетическим пользователем: Argon2id на реплике с лимитом 1 CPU
занимает сотни миллисекунд, поэтому в момент kill запросы в полёте
есть. Через `after` секунд `scripts/stop-one.sh` в режиме kill
убивает реплику, ответившую на пробный запрос. Пароль и токены не
печатаются, тела успешных ответов не сохраняются.
"""
_, pid_path = paths(port)
if pid_path.exists():
print(f"port {port}: console process of the driver, no LB to test")
return 1
tag = uuid.uuid4().hex[:8]
username, password = f"kill_{tag}", f"Pw-kill-{uuid.uuid4().hex}"
body = {
"username": username,
"display_name": "Kill demo",
"password": password,
}
status, _, _ = call(port, "POST", USERS, body=body)
if status != 201:
print(f"register: {status}")
return 1
authorization = basic(username, password)
_, probe, _ = call(port, "GET", "/health/live")
target = probe.get("x-instance-id", "")
print(f"target replica (X-Instance-Id of a probe): {target}")
# (статус, реплика, тело ошибки LB, совпал ли request_id с заголовком)
results: list[tuple[int, str, object, bool]] = []
lock = threading.Lock()
deadline = time.monotonic() + seconds
def login() -> None:
while time.monotonic() < deadline:
try:
status, hdrs, payload = call(
port,
"POST",
SESSIONS,
authorization=authorization,
)
except OSError as error:
status, hdrs, payload = 0, {}, type(error).__name__
error = None
same_id = False
if status >= 500 or status == 0:
error = payload
if isinstance(payload, dict) and "error" in payload:
error = payload["error"]
same_id = error.get("request_id") == hdrs.get(
"x-request-id",
)
with lock:
results.append(
(status, hdrs.get("x-instance-id", "LB"), error, same_id),
)
workers = [threading.Thread(target=login) for _ in range(threads)]
for worker in workers:
worker.start()
time.sleep(after)
hook = subprocess.run(
[str(ROOT / "scripts" / "stop-one.sh")],
cwd=ROOT,
env=os.environ | {"TARGET_INSTANCE_ID": target, "STOP_MODE": "kill"},
capture_output=True,
text=True,
check=False,
)
print(f"stop-one.sh (kill): exit {hook.returncode}; {hook.stderr.strip()}")
for worker in workers:
worker.join()
print(f"{len(results)} logins in {seconds:g} s by {threads} threads")
counts = Counter((status, instance) for status, instance, _, _ in results)
for (status, instance), served in sorted(counts.items()):
print(f" {status} via {instance}: {served}")
cut = [(s, e, same) for s, _, e, same in results if e is not None]
for status, error, same_id in cut:
print(
f" LB error {status}: {json.dumps(error, ensure_ascii=False)}"
f" request_id == X-Request-Id: {same_id}",
)
print(f"replica {target} is left stopped; restore: make replicas")
if hook.returncode != 0:
return 1
if not cut:
print("no request was in flight on the killed replica: repeat")
return 1
unexpected = {status for status, _, _, _ in results} - {201, 502}
return 1 if unexpected else 0
def main() -> int: def main() -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--port", type=int, default=DEFAULT_PORT) parser.add_argument("--port", type=int, default=DEFAULT_PORT)
@@ -603,6 +712,10 @@ def main() -> int:
sub.add_parser(name) sub.add_parser(name)
instances = sub.add_parser("instances") instances = sub.add_parser("instances")
instances.add_argument("--count", type=int, default=12) instances.add_argument("--count", type=int, default=12)
inflight = sub.add_parser("kill-inflight")
inflight.add_argument("--threads", type=int, default=8)
inflight.add_argument("--seconds", type=float, default=4)
inflight.add_argument("--after", type=float, default=1.5)
req = sub.add_parser("req") req = sub.add_parser("req")
req.add_argument("method") req.add_argument("method")
req.add_argument("path") req.add_argument("path")
@@ -636,6 +749,13 @@ def main() -> int:
return cmd_req(port, args) return cmd_req(port, args)
if args.cmd == "instances": if args.cmd == "instances":
return cmd_instances(port, args.count) return cmd_instances(port, args.count)
if args.cmd == "kill-inflight":
return cmd_kill_inflight(
port,
threads=args.threads,
seconds=args.seconds,
after=args.after,
)
handlers = { handlers = {
"start": cmd_start, "start": cmd_start,
"stop": cmd_stop, "stop": cmd_stop,
+4 -2
View File
@@ -165,8 +165,10 @@ services:
replicas: ${API_REPLICAS:-2} replicas: ${API_REPLICAS:-2}
resources: resources:
limits: limits:
# один процесс — один event loop: больше 1 CPU не использует; # один event loop занимает не больше 1 CPU. Argon2id (p=4, до
# Argon2id 4 × 64 MiB + интерпретатор ≈ 350 МБ # kdf_concurrency хэшей сразу) взял бы больше: под лимитом вход
# медленнее в 4–5 раз, осознанно (REPORT.md, «Ограничения»).
# Память: Argon2id 4 × 64 MiB + интерпретатор ≈ 350 МБ
cpus: "1.0" cpus: "1.0"
memory: 512M memory: 512M
+4 -2
View File
@@ -50,8 +50,10 @@ defaults
timeout client 30s timeout client 30s
timeout http-request 10s timeout http-request 10s
timeout http-keep-alive 10s timeout http-keep-alive 10s
# больше таймаута проверки внутри /health/ready (2 с); обнаружение # больше таймаута проверки внутри /health/ready (2 с). Следующая
# отказа ≈ inter × fall + timeout check = 1 × 2 + 3 = 5 с ≤ 10 с # проверка — через inter после конца предыдущей, поэтому худшее
# обнаружение зависшей реплики ≈ fall × (inter + timeout check) =
# 2 × (1 + 3) = 8 с ≤ 10 с; остановленную проверка не ждёт
timeout check 3s timeout check 3s
# request_id ответов, которые создаёт сам LB # request_id ответов, которые создаёт сам LB
unique-id-format lb-%{+X}o%ci%cp%Ts%rt%pid unique-id-format lb-%{+X}o%ci%cp%Ts%rt%pid
+85 -13
View File
@@ -142,7 +142,7 @@ server-template api- 8 "api:${API_PORT}"
| Параметр | Значение | Соотношение (`balancer.md`) | | Параметр | Значение | Соотношение (`balancer.md`) |
|---|---|---| |---|---|---|
| `inter` / `fall` / `rise` | 1 с / 2 / 2 | обнаружение ≈ `inter × fall + timeout check` = 1 × 2 + 3 = 5 с ≤ 10 с | | `inter` / `fall` / `rise` | 1 с / 2 / 2 | худшее обнаружение зависшей реплики ≈ `fall × (inter + timeout check)` = 2 × (1 + 3) = 8 с ≤ 10 с (решение 14) |
| `timeout check` | 3 с | > `READINESS_DB_TIMEOUT_SECONDS` = 2 с внутри `/health/ready` | | `timeout check` | 3 с | > `READINESS_DB_TIMEOUT_SECONDS` = 2 с внутри `/health/ready` |
| `timeout connect` | 500 мс | `timeout connect × (retries + 1)` = 0,5 × 3 = 1,5 с < 2 с (таймаут клиента `tests/resilience.py`) | | `timeout connect` | 500 мс | `timeout connect × (retries + 1)` = 0,5 × 3 = 1,5 с < 2 с (таймаут клиента `tests/resilience.py`) |
| `retries` | 2 | с `option redispatch 1` каждый повтор идёт на другую реплику | | `retries` | 2 | с `option redispatch 1` каждый повтор идёт на другую реплику |
@@ -156,10 +156,11 @@ server-template api- 8 "api:${API_PORT}"
раньше собственного таймаута `/health/ready` (2 с). Медленный, но раньше собственного таймаута `/health/ready` (2 с). Медленный, но
живой PostgreSQL выглядел бы как мёртвая реплика, а это нарушает живой PostgreSQL выглядел бы как мёртвая реплика, а это нарушает
`infra.md`. Уменьшать таймаут готовности в коде этот change не будет `infra.md`. Уменьшать таймаут готовности в коде этот change не будет
(Non-Goals). Цена — худшее обнаружение «зависшей» реплики 5 с вместо (Non-Goals). Цена — худшее обнаружение «зависшей» реплики 8 с вместо
3 с. Остановленную или убитую реплику проверка не ждёт: соединение 4 с (формула исправлена в verify, решение 14). Остановленную или
отвергается сразу (`stop`) или ограничено `timeout connect` убитую реплику проверка не ждёт: соединение отвергается сразу
(адрес пропал). Пересмотр — `graceful-failover`. (`stop`) или ограничено `timeout connect` (адрес пропал). Пересмотр —
`graceful-failover`.
- **`timeout connect` 500 мс вместо 1 с и `option redispatch 1`.** При - **`timeout connect` 500 мс вместо 1 с и `option redispatch 1`.** При
1 с и `retries 2` худший путь — 3 с, больше 2-секундного таймаута 1 с и `retries 2` худший путь — 3 с, больше 2-секундного таймаута
клиента. `redispatch 1` уводит уже первый повтор на другую реплику, а клиента. `redispatch 1` уводит уже первый повтор на другую реплику, а
@@ -223,7 +224,7 @@ server-template api- 8 "api:${API_PORT}"
| Сервис | CPU | Память | Почему так | | Сервис | CPU | Память | Почему так |
|---|---|---|---| |---|---|---|---|
| `api` (на реплику) | 1.0 | 512M | один процесс — один event loop, больше 1 CPU не использует; Argon2id 4 × 64 MiB + интерпретатор ≈ 350 МБ | | `api` (на реплику) | 1.0 | 512M | один event loop занимает не больше 1 CPU; Argon2id взял бы больше, вход под лимитом медленнее (решение 14); Argon2id 4 × 64 MiB + интерпретатор ≈ 350 МБ |
| `postgres` | 2.0 | 1G | `shared_buffers` по умолчанию 128 МБ, запас на соединения реплик | | `postgres` | 2.0 | 1G | `shared_buffers` по умолчанию 128 МБ, запас на соединения реплик |
| `valkey` | 0.5 | 128M | `maxmemory 64mb` + накладные | | `valkey` | 0.5 | 128M | `maxmemory 64mb` + накладные |
| `haproxy` | 1.0 | 256M | `nbthread 1` (решение 1) | | `haproxy` | 1.0 | 256M | `nbthread 1` (решение 1) |
@@ -262,7 +263,9 @@ STOP_ONE_LOG=файл → строка «время, TARGET_INSTANCE_ID, пол
`docker-compose.yml`, без `-p`: hook работает с рабочим стендом `docker-compose.yml`, без `-p`: hook работает с рабочим стендом
`mtusi-lab3`. `mtusi-lab3`.
- Формат — только hex: hostname в compose — начало ID контейнера. - Формат — только hex: hostname в compose — начало ID контейнера.
Пустое и иное значение — выход 2 до вызова docker. ID PostgreSQL, Пустое и иное значение — выход 2 до вызова docker. Пустое значение
проверяется явно, а не через `${VAR:?}` образца: тот даёт 1 в bash и
2 в dash (исправлено в verify). ID PostgreSQL,
Valkey и LB не попадут в `ps -q api`, контейнеры других проектов — тем Valkey и LB не попадут в `ps -q api`, контейнеры других проектов — тем
более. более.
- `--timeout 9`: uvicorn сам завершается не позже 8 с - `--timeout 9`: uvicorn сам завершается не позже 8 с
@@ -388,6 +391,13 @@ STOP_ONE_LOG=файл → строка «время, TARGET_INSTANCE_ID, пол
`Counter`. Токен не печатается. `Counter`. Токен не печатается.
- `student` передаёт `EXPECT_REPLICAS=1`, если на порту процесс самого - `student` передаёт `EXPECT_REPLICAS=1`, если на порту процесс самого
драйвера (есть pid-файл). драйвера (есть pid-файл).
- Команда `kill-inflight` (добавлена в verify): воспроизводимый
сценарий «Оборванный ответ не повторяется». Потоки входят по Basic
(Argon2id на реплике с лимитом 1 CPU — сотни миллисекунд, запросы в
полёте есть всегда), через заданное время `scripts/stop-one.sh` в
режиме kill убивает реплику пробного запроса. Печатает статусы по
репликам и ответы LB. Против процесса самого драйвера отказывается:
LB там нет. Реплика остаётся остановленной, возврат — `make replicas`.
- `SKILL.md`: - `SKILL.md`:
- описание — уже не «один API без балансировщика»; - описание — уже не «один API без балансировщика»;
- раздел «Run: контейнер» — LB, реплики, `make replicas`, - раздел «Run: контейнер» — LB, реплики, `make replicas`,
@@ -423,20 +433,70 @@ STOP_ONE_LOG=файл → строка «время, TARGET_INSTANCE_ID, пол
| Файл | Что показывает | | Файл | Что показывает |
|---|---| |---|---|
| `evidence/replicas/stand.md` | `docker compose ps` — порт хоста только у `haproxy`, `postgres`, `valkey`, все на `127.0.0.1`. У `api` нет портов и `container_name`. Лимиты всех контейнеров из `docker inspect`. Имена переменных окружения по сервисам — без значений. Один прогон `migrate` | | `evidence/replicas/stand.md` | `docker compose ps` — порт хоста только у `haproxy`, `postgres`, `valkey`, все на `127.0.0.1`. У `api` нет портов и `container_name`. Лимиты всех контейнеров из `docker inspect`. Имена переменных окружения по сервисам — без значений. Один прогон `migrate`. Цена лимита 1 CPU для входа (решение 14) |
| `evidence/replicas/clean-clone-ports.md` | настоящий `git clone`, `make run_docker` во временном проекте с нестандартными `APP_OUT_PORT`, `APP__PORT`, портами Postgres и Valkey: LB проверяет реплики на `APP__PORT`, `make test` и `make student_test` через LB (решение 14) |
| `evidence/replicas/distribution.md` | `make instances` (≥2 значения, одна сессия), `make lb_stats`. `make replicas API_REPLICAS=3` → три значения, обратно → два | | `evidence/replicas/distribution.md` | `make instances` (≥2 значения, одна сессия), `make lb_stats`. `make replicas API_REPLICAS=3` → три значения, обратно → два |
| `evidence/replicas/lb-errors.md` | все реплики остановлены — 503 JSON от LB, `request_id` = `X-Request-Id`; healthcheck LB `unhealthy`; восстановление | | `evidence/replicas/lb-errors.md` | все реплики остановлены — 503 JSON от LB, `request_id` = `X-Request-Id`; healthcheck LB `unhealthy`; восстановление. Зависшая реплика (`docker pause`) — исключена по `timeout check`, запрос в полёте — 504; PostgreSQL остановлен — реплики отвечают 503 на проверку, LB исключает обе (решение 14) |
| `evidence/replicas/test-persistence.md` | `make test-persistence` через LB, `StartedAt` всех контейнеров до и после, те же ID | | `evidence/replicas/test-persistence.md` | `make test-persistence` через LB, `StartedAt` всех контейнеров до и после, те же ID |
| `evidence/failover/test-failover.md` | `make test-failover` (`STOP_MODE=stop`) для каждой реплики по очереди. `docker compose ps -a` и `StartedAt` до и после. `STOP_ONE_LOG`: `TARGET_INSTANCE_ID` = ID остановленного. `lb_stats` и журнал LB (перенаправления). `make replicas` между прогонами | | `evidence/failover/test-failover.md` | `make test-failover` (`STOP_MODE=stop`) для каждой реплики по очереди. `docker compose ps -a` и `StartedAt` до и после. `STOP_ONE_LOG`: `TARGET_INSTANCE_ID` = ID остановленного. `lb_stats` и журнал LB (перенаправления). `make replicas` между прогонами |
| `evidence/failover/test-failover-kill.md` | то же с `STOP_MODE=kill`. Контейнер `exited` 137 и через 15 с не поднят; журнал LB: оборванный ответ без повтора | | `evidence/failover/test-failover-kill.md` | то же с `STOP_MODE=kill`. Контейнер `exited` 137 и через 15 с не поднят; `driver.py kill-inflight`: оборванный ответ — 502 без повтора |
| `evidence/failover/stop-one-refusals.md` | пустой, не-hex, ID PostgreSQL / Valkey / LB, неизвестный ID — ненулевой код, `StartedAt` всех контейнеров прежний | | `evidence/failover/stop-one-refusals.md` | пустой, не-hex, ID PostgreSQL / Valkey / LB, неизвестный ID — ненулевой код, `StartedAt` всех контейнеров прежний |
| `evidence/tests/student-test-lb.md` | `make student_test` через LB: тесты реплик выполнены и прошли | | `evidence/tests/student-test-lb.md` | `make test` и `make student_test` через LB: тесты реплик выполнены и прошли; тот же набор против одного процесса без `EXPECT_REPLICAS=1` — тесты реплик падают с числом увиденных значений |
| `evidence/tests/test-isolated.md`, `failure-checks.md` | новые прогоны: тесты реплик пропущены с причиной; проверки отказов прошли | | `evidence/tests/test-isolated.md`, `failure-checks.md` | новые прогоны: тесты реплик пропущены с причиной; проверки отказов прошли |
| `evidence/tests/bench-self-checks.md` | `make bench_quick` и `make bench_restore_quick` на новом compose — код 0 (самопроверки, не замеры) | | `evidence/tests/bench-self-checks.md` | `make bench_quick` и `make bench_restore_quick` на новом compose — код 0 (самопроверки, не замеры) |
Все снимаются с закоммиченного кода, в шапке — спеки, change, дата, Все снимаются с закоммиченного кода, в шапке — спеки, change, дата,
commit, стенд, хост. commit, стенд, хост.
### 14. Правки по verify (2026-10-10)
Verify сверил код, тесты и evidence с артефактами и нашёл:
- **Evidence стенда снято не с того кода.** Стенд был поднят на
`ab71c3b`, а LB перечитал `haproxy.cfg` с `init-state down` за минуту
до коммита `4e0cc4e`. После правок verify стенд пересоздан (`make
down`, `make run_docker`) с итогового commit, и всё evidence этого
change снято заново на нём.
- **Формула обнаружения занижала время для зависшей реплики.** HAProxy
начинает следующую проверку через `inter` после конца предыдущей.
Если реплика не отвечает, каждая проверка ждёт `timeout check`, и
худшее время — `fall × (inter + timeout check)` = 2 × (1 + 3) = 8 с,
а не `inter × fall + timeout check` = 5 с. Замер: `docker pause`
реплики — `DOWN` через 7,3 с (`lb-errors.md`). Остановленную реплику
проверка не ждёт: соединение отвергается сразу или ограничено
`timeout connect` 500 мс, а пропавший адрес DNS уводит слот в
обслуживание за 1–2 с. Числа не меняются: 8 с ≤ 10 с. Подбор и замер
по режимам — `graceful-failover`. Формула исправлена в
`haproxy.cfg`, `balancer.md`, `REPORT.md`.
- **Лимит 1 CPU и Argon2id.** Утверждение «процесс больше 1 CPU не
использует» верно для event loop, но не для KDF. Один хэш Argon2id
(`p=4`) — четыре потока, около 0,1 с CPU. Под лимитом 1 CPU проверка
пароля идёт около 0,12 с вместо 0,025 с, четыре одновременных — около
0,8 с. Пока идёт вход, запросы той же реплики делят с ним квоту. Лимит
остаётся 1 CPU осознанно:
- вход редок по сравнению с остальными запросами;
- вход в замеры трека 1 не входит;
- серия B трека 1 считает реплику в 1 CPU;
- `make test_isolated` (сотни регистраций и входов, каждый — хэш
Argon2id) идёт около минуты вместо 21 с, это не регрессия кода.
Замер — `stand.md`, ограничение — `REPORT.md`.
- **`stop-one.sh` с пустым `TARGET_INSTANCE_ID`** давал код 1 вместо
заявленного 2 (решение 7): проверка теперь явная.
- **Сценарий «Оборванный ответ не повторяется»** был показан разовым
скриптом вне репозитория. Теперь это команда `kill-inflight` драйвера
(решение 11).
- **Сценариям без evidence добавлено evidence:**
- `make test` через LB;
- «Реплик меньше ожидаемого» — набор против одного процесса без
`EXPECT_REPLICAS=1`;
- «Штатный запуск», «Другой внешний порт», «Другой внутренний порт» —
настоящий `git clone` во временном проекте;
- «Реплика … не отвечает или отвечает 503» требования «Проверка
готовности реплик» и 504 от LB — `lb-errors.md`.
- **Спек `load-balancing`:** `API_REPLICAS` читают compose и Makefile,
а не «только compose».
## Risks / Trade-offs ## Risks / Trade-offs
- **[HAProxy держит keep-alive к реплике, и uvicorn закрывает его при - **[HAProxy держит keep-alive к реплике, и uvicorn закрывает его при
@@ -445,8 +505,20 @@ commit, стенд, хост.
`make test-failover` повторяет с тем же ключом. Частоту видно в `make test-failover` повторяет с тем же ключом. Частоту видно в
журнале LB, замер — `graceful-failover`. журнале LB, замер — `graceful-failover`.
- **[`timeout check` 3 с медленнее плана]** → худшее обнаружение - **[`timeout check` 3 с медленнее плана]** → худшее обнаружение
зависшей реплики 5 с. Укладывается в 10 с. Пересмотр вместе с зависшей реплики 8 с (замер — 7,3 с, решение 14). Укладывается в
таймаутом готовности — `graceful-failover`. 10 с, но запас небольшой. Пересмотр вместе с таймаутом готовности —
`graceful-failover`.
- **[Готовность зависит от общего PostgreSQL]** → при его отказе все
реплики не проходят проверку, и через 2–3 с на всё, включая
`/health/live`, отвечает сам LB: 503 `unavailable` в формате
контракта. Это тот же код, что отдал бы API. После возврата
PostgreSQL реплики включаются через `rise` проверок (`lb-errors.md`).
- **[uvicorn закрывает простаивающее соединение через 5 с
(`timeout_keep_alive` по умолчанию)]** → если LB отправит запрос в
такое соединение в момент закрытия, ответа не будет, и LB вернёт 502
без повтора (повтор только `conn-failure`). На прогонах этого change
не наблюдалось. Проверить в профиле `failover` под нагрузкой —
`graceful-failover`.
- **[`server-template` на 8 слотов]** → девятая реплика не получит - **[`server-template` на 8 слотов]** → девятая реплика не получит
трафик. Это максимум серий трека 1. Ограничение — в `REPORT.md` и в трафик. Это максимум серий трека 1. Ограничение — в `REPORT.md` и в
комментарии конфига. комментарии конфига.
@@ -28,7 +28,8 @@ NOT публиковать порты на хосте и MUST NOT иметь ф
### Requirement: Взаимозаменяемые реплики ### Requirement: Взаимозаменяемые реплики
Сервис API SHALL запускаться в числе реплик `API_REPLICAS`, по Сервис API SHALL запускаться в числе реплик `API_REPLICAS`, по
умолчанию 2. Это значение читает только compose. Реплики SHALL быть умолчанию 2. Это значение читают compose и Makefile, приложение MUST
NOT его читать. Реплики SHALL быть
одинаковыми: один образ, одна конфигурация, общие PostgreSQL и Valkey. одинаковыми: один образ, одна конфигурация, общие PostgreSQL и Valkey.
В памяти процесса MUST NOT быть состояния, от которого зависит В памяти процесса MUST NOT быть состояния, от которого зависит
корректность ответа. Изменение числа реплик MUST NOT требовать правки корректность ответа. Изменение числа реплик MUST NOT требовать правки
+27
View File
@@ -203,3 +203,30 @@ evidence, потом коммит evidence и отчёта (бриф основ
- отметить задачи, коммит evidence и отчёта; - отметить задачи, коммит evidence и отчёта;
- `graphify update .`; - `graphify update .`;
- стенд `mtusi-lab3` оставлен запущенным через LB, обе реплики `UP`. - стенд `mtusi-lab3` оставлен запущенным через LB, обе реплики `UP`.
## 7. Правки по verify (решение 14)
- [x] 7.1 Код и документы:
- `scripts/stop-one.sh`: пустой `TARGET_INSTANCE_ID` — код 2 явно;
- `driver.py kill-inflight` и `SKILL.md`;
- формула обнаружения в `haproxy.cfg`, `balancer.md`, `design.md`;
- обоснование лимита 1 CPU в `docker-compose.yml` и `design.md`;
- формулировка `API_REPLICAS` в спеке `load-balancing`.
Проверка: `make lint`, `make check`, `openspec validate replicas-lb
--strict`, `driver.py kill-inflight --help`; коммит.
- [ ] 7.2 Стенд с итогового commit: `make down`, `make run_docker`.
Evidence решения 13 снято заново на нём, включая новые файлы и
разделы:
- `clean-clone-ports.md`;
- зависшая реплика и PostgreSQL в `lb-errors.md`;
- цена лимита в `stand.md`;
- `make test` и «Реплик меньше ожидаемого» в `student-test-lb.md`;
- `kill-inflight` в `test-failover-kill.md`.
Проверка: в шапке каждого файла — итоговый commit. `make
test-failover` остановил каждую из двух реплик, ID остановленной =
`TARGET_INSTANCE_ID`.
- [ ] 7.3 `REPORT.md`: формула и замер обнаружения, цена лимита 1 CPU,
отказ PostgreSQL через LB, строки доказательств с новыми файлами.
Коммит evidence и отчёта.
+2 -1
View File
@@ -28,7 +28,8 @@ NOT публиковать порты на хосте и MUST NOT иметь ф
### Requirement: Взаимозаменяемые реплики ### Requirement: Взаимозаменяемые реплики
Сервис API SHALL запускаться в числе реплик `API_REPLICAS`, по Сервис API SHALL запускаться в числе реплик `API_REPLICAS`, по
умолчанию 2. Это значение читает только compose. Реплики SHALL быть умолчанию 2. Это значение читают compose и Makefile, приложение MUST
NOT его читать. Реплики SHALL быть
одинаковыми: один образ, одна конфигурация, общие PostgreSQL и Valkey. одинаковыми: один образ, одна конфигурация, общие PostgreSQL и Valkey.
В памяти процесса MUST NOT быть состояния, от которого зависит В памяти процесса MUST NOT быть состояния, от которого зависит
корректность ответа. Изменение числа реплик MUST NOT требовать правки корректность ответа. Изменение числа реплик MUST NOT требовать правки
+8 -2
View File
@@ -13,8 +13,14 @@ set -eu
# STOP_MODE=kill — docker kill: SIGKILL, отказ процесса без graceful; # STOP_MODE=kill — docker kill: SIGKILL, отказ процесса без graceful;
# STOP_ONE_LOG=<файл> — дописать строку «время, TARGET_INSTANCE_ID, # STOP_ONE_LOG=<файл> — дописать строку «время, TARGET_INSTANCE_ID,
# полный ID контейнера, режим» (доказательство: тест скрывает вывод hook). # полный ID контейнера, режим» (доказательство: тест скрывает вывод hook).
# Секретов и окружения не печатает. # Секретов и окружения не печатает. Неверный ввод — код 2 до вызова
: "${TARGET_INSTANCE_ID:?test provides target API instance alias}" # docker, нет такой реплики — код 3.
# пустое значение — тот же код 2 в любой оболочке (${VAR:?} даёт 1 в bash
# и 2 в dash)
if [ -z "${TARGET_INSTANCE_ID:-}" ]; then
echo "stop-one: TARGET_INSTANCE_ID is empty; test provides target API instance alias" >&2
exit 2
fi
mode="${STOP_MODE:-stop}" mode="${STOP_MODE:-stop}"
case "$mode" in case "$mode" in