fix: answer 503 when PostgreSQL refuses connections with too many clients
SQLSTATE 53300 (too_many_connections) joins UNAVAILABLE_SQLSTATES, so a refused pool connection gives 503 unavailable instead of 500. New fault check fills max_connections through the failure stand hook and expects 503 in the contract format. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Недоступность PostgreSQL
|
||||
|
||||
Если PostgreSQL недоступен, отказывает в новом подключении из-за
|
||||
предела соединений (`max_connections`) или не ответил за отведённое
|
||||
время, запрос SHALL завершаться ответом 503 с `code` `unavailable` в
|
||||
формате ошибки, а не 500 и не зависанием. Частично выполненная операция
|
||||
MUST NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL
|
||||
обслуживать запросы без перезапуска.
|
||||
|
||||
#### Scenario: БД остановлена
|
||||
|
||||
- **WHEN** PostgreSQL остановлен, и клиент отправляет сообщение
|
||||
- **THEN** ответ 503 `unavailable` без деталей в `message`
|
||||
|
||||
#### Scenario: БД вернулась
|
||||
|
||||
- **WHEN** PostgreSQL остановлен, затем снова запущен, а сервис не
|
||||
перезапускался
|
||||
- **THEN** следующие запросы после готовности БД обслуживаются штатно
|
||||
|
||||
#### Scenario: Предел соединений PostgreSQL исчерпан
|
||||
|
||||
- **WHEN** все слоты `max_connections` PostgreSQL заняты, и пулу
|
||||
сервиса для запроса нужно новое соединение
|
||||
- **THEN** PostgreSQL отказывает в подключении («too many clients»,
|
||||
SQLSTATE `53300`), а клиент получает 503 `unavailable` без деталей в
|
||||
`message`, а не 500
|
||||
- **AND** после освобождения слотов запросы обслуживаются без
|
||||
перезапуска сервиса
|
||||
@@ -86,10 +86,11 @@ PostgreSQL как источник истины, сохранность посл
|
||||
|
||||
### Requirement: Недоступность PostgreSQL
|
||||
|
||||
Если PostgreSQL недоступен или не ответил за отведённое время,
|
||||
запрос SHALL завершаться ответом 503 с `code` `unavailable` в формате
|
||||
ошибки, а не 500 и не зависанием. Частично выполненная операция MUST
|
||||
NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL
|
||||
Если PostgreSQL недоступен, отказывает в новом подключении из-за
|
||||
предела соединений (`max_connections`) или не ответил за отведённое
|
||||
время, запрос SHALL завершаться ответом 503 с `code` `unavailable` в
|
||||
формате ошибки, а не 500 и не зависанием. Частично выполненная операция
|
||||
MUST NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL
|
||||
обслуживать запросы без перезапуска.
|
||||
|
||||
#### Scenario: БД остановлена
|
||||
@@ -103,6 +104,16 @@ NOT фиксироваться. Когда PostgreSQL снова доступе
|
||||
перезапускался
|
||||
- **THEN** следующие запросы после готовности БД обслуживаются штатно
|
||||
|
||||
#### Scenario: Предел соединений PostgreSQL исчерпан
|
||||
|
||||
- **WHEN** все слоты `max_connections` PostgreSQL заняты, и пулу
|
||||
сервиса для запроса нужно новое соединение
|
||||
- **THEN** PostgreSQL отказывает в подключении («too many clients»,
|
||||
SQLSTATE `53300`), а клиент получает 503 `unavailable` без деталей в
|
||||
`message`, а не 500
|
||||
- **AND** после освобождения слотов запросы обслуживаются без
|
||||
перезапуска сервиса
|
||||
|
||||
### Requirement: Ограниченный пул соединений и таймауты
|
||||
|
||||
Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой.
|
||||
|
||||
+11
-4
@@ -9,7 +9,12 @@
|
||||
- пул исчерпан — `sqlalchemy.exc.TimeoutError`;
|
||||
- сработал `statement_timeout` — `DBAPIError` с SQLSTATE `57014`;
|
||||
- соединение оборвано (рестарт, `pg_terminate_backend`) — `DBAPIError`
|
||||
с `connection_invalidated`.
|
||||
с `connection_invalidated`;
|
||||
- отказ в подключении сверх `max_connections` — `TooManyConnectionsError`
|
||||
asyncpg, `DBAPIError` с SQLSTATE `53300` (класс 53: нехватка ресурсов),
|
||||
без `connection_invalidated`. Найден серией `pool` change
|
||||
`scaling-bench`; остальные коды класса 53 (диск, память) сюда не
|
||||
входят: их не воспроизводили.
|
||||
|
||||
Остальные `DBAPIError` (нарушение ограничения, синтаксис) — дефект
|
||||
сервиса, им положен 500, а не 503.
|
||||
@@ -17,9 +22,11 @@
|
||||
|
||||
from sqlalchemy import exc as sa_exc
|
||||
|
||||
# класс 08 — ошибки соединения; 57014 — query_canceled (statement_timeout);
|
||||
# 57P01–57P03 — сервер останавливается или ещё не принимает подключения
|
||||
UNAVAILABLE_SQLSTATES = ("08", "57014", "57P01", "57P02", "57P03")
|
||||
# класс 08 — ошибки соединения; 53300 — too_many_connections (отказ в
|
||||
# подключении сверх max_connections); 57014 — query_canceled
|
||||
# (statement_timeout); 57P01–57P03 — сервер останавливается или ещё не
|
||||
# принимает подключения
|
||||
UNAVAILABLE_SQLSTATES = ("08", "53300", "57014", "57P01", "57P02", "57P03")
|
||||
|
||||
|
||||
def is_db_unavailable(error: BaseException) -> bool:
|
||||
|
||||
@@ -20,6 +20,11 @@
|
||||
моменту уже вставлен в той же транзакции)
|
||||
clear-fail-messages убрать триггер
|
||||
count-chats <title> число чатов с этим названием
|
||||
fill-connections <секунд> занять все слоты max_connections сессиями
|
||||
psql (`SELECT pg_sleep`) и оборвать
|
||||
соединения API: их пулы переподключаются
|
||||
и получают «too many clients» (53300)
|
||||
clear-connections освободить слоты и дождаться подключения
|
||||
|
||||
Пароли не печатает: valkey-cli берёт пароль из VALKEYCLI_AUTH
|
||||
контейнера, psql работает от POSTGRES_USER контейнера. Только stdlib.
|
||||
@@ -92,6 +97,57 @@ DROP FUNCTION IF EXISTS fault_fail_messages();
|
||||
"""
|
||||
COUNT_CHATS_SQL = "SELECT count(*) FROM chats WHERE title = :'title';\n"
|
||||
|
||||
# Заполнение слотов: отвязанный sh в контейнере Postgres. Сначала столько
|
||||
# попыток, сколько слотов, затем новая попытка раз в 0,05 с до конца
|
||||
# срока: слот, освободившийся после обрыва соединения API, сразу занимает
|
||||
# снова psql, а не переподключение пула. Лишние попытки получают отказ и
|
||||
# выходят. Сессии — через сокет ([local]), пользователь контейнера.
|
||||
FILL_PID = "/tmp/fault-fill.pid"
|
||||
FILL_SH = f"""\
|
||||
echo $$ > {FILL_PID}
|
||||
hold() {{
|
||||
PGAPPNAME=fault_fill psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq \\
|
||||
-c "SELECT pg_sleep($1)" >/dev/null 2>&1 &
|
||||
}}
|
||||
end=$(( $(date +%s) + $1 ))
|
||||
slots=$(psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq \\
|
||||
-c 'SHOW max_connections')
|
||||
i=0
|
||||
while [ "$i" -lt "$slots" ]; do hold "$1"; i=$((i + 1)); done
|
||||
while [ "$(date +%s)" -lt "$end" ]; do hold "$1"; sleep 0.05; done
|
||||
"""
|
||||
# Обрыв соединений по TCP (это пулы API) сигналом SIGTERM — то же, что
|
||||
# pg_terminate_backend, но без своего слота. Заголовок процесса backend —
|
||||
# «postgres: <user> <db> <адрес>(<порт>) <состояние>»; сокет ([local]) и
|
||||
# проверку готовности с 127.0.0.1 не трогаем. Печатает число оборванных.
|
||||
KILL_TCP_SH = """\
|
||||
n=0
|
||||
for d in /proc/[0-9]*; do
|
||||
t=$(tr '\\0' ' ' < "$d/cmdline" 2>/dev/null) || continue
|
||||
case "$t" in
|
||||
"postgres: "*" 127.0.0.1("*) ;;
|
||||
"postgres: "*"("*")"*) kill -TERM "${d#/proc/}" 2>/dev/null \\
|
||||
&& n=$((n + 1)) ;;
|
||||
esac
|
||||
done
|
||||
echo "$n"
|
||||
"""
|
||||
CLEAR_FILL_SH = f"""\
|
||||
[ -f {FILL_PID} ] && kill "$(cat {FILL_PID})" 2>/dev/null
|
||||
rm -f {FILL_PID}
|
||||
for d in /proc/[0-9]*; do
|
||||
t=$(tr '\\0' ' ' < "$d/cmdline" 2>/dev/null) || continue
|
||||
case "$t" in
|
||||
"postgres: "*" [local] "*) kill -TERM "${{d#/proc/}}" 2>/dev/null ;;
|
||||
esac
|
||||
done
|
||||
"""
|
||||
PROBE_SQL_SH = (
|
||||
'exec psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq -c "SELECT 1"'
|
||||
)
|
||||
TOO_MANY = "too many clients"
|
||||
FILL_TIMEOUT_S = 20
|
||||
|
||||
|
||||
class HookError(Exception):
|
||||
"""Неверный вызов или проект: код 2 и сообщение в stderr."""
|
||||
@@ -231,6 +287,76 @@ def cache_has_chat(project: str, chat_id: str) -> str:
|
||||
return valkey(project, "EXISTS", key)
|
||||
|
||||
|
||||
def postgres_sh(project: str, script: str, *args: str) -> str:
|
||||
return compose(
|
||||
project,
|
||||
"exec",
|
||||
"-T",
|
||||
"postgres",
|
||||
"sh",
|
||||
"-c",
|
||||
script,
|
||||
"sh",
|
||||
*args,
|
||||
)
|
||||
|
||||
|
||||
def probe_connect(project: str) -> subprocess.CompletedProcess[str]:
|
||||
"""Новое подключение psql и `SELECT 1`."""
|
||||
return compose_run(
|
||||
project,
|
||||
"exec",
|
||||
"-T",
|
||||
"postgres",
|
||||
"sh",
|
||||
"-c",
|
||||
PROBE_SQL_SH,
|
||||
)
|
||||
|
||||
|
||||
def slots_full(project: str) -> bool:
|
||||
"""Новое подключение получает «too many clients»."""
|
||||
probe = probe_connect(project)
|
||||
return probe.returncode != 0 and TOO_MANY in probe.stderr
|
||||
|
||||
|
||||
def fill_connections(project: str, seconds: str) -> str:
|
||||
"""Все слоты заняты psql, соединений API не осталось.
|
||||
|
||||
Готово, когда новое подключение получает отказ, а обрывать уже
|
||||
некого: пул API, переподключаясь, получит 53300.
|
||||
"""
|
||||
if int(seconds) <= 0:
|
||||
raise HookError("seconds must be positive")
|
||||
compose(
|
||||
project,
|
||||
"exec",
|
||||
"-d",
|
||||
"postgres",
|
||||
"sh",
|
||||
"-c",
|
||||
FILL_SH,
|
||||
"sh",
|
||||
str(int(seconds)),
|
||||
)
|
||||
deadline = time.monotonic() + FILL_TIMEOUT_S
|
||||
while time.monotonic() < deadline:
|
||||
if slots_full(project) and postgres_sh(project, KILL_TCP_SH) == "0":
|
||||
return ""
|
||||
time.sleep(0.1)
|
||||
raise HookError(f"connections are not filled in {FILL_TIMEOUT_S}s")
|
||||
|
||||
|
||||
def clear_connections(project: str) -> str:
|
||||
deadline = time.monotonic() + FILL_TIMEOUT_S
|
||||
while time.monotonic() < deadline:
|
||||
postgres_sh(project, CLEAR_FILL_SH)
|
||||
if probe_connect(project).returncode == 0:
|
||||
return ""
|
||||
time.sleep(0.2)
|
||||
raise HookError(f"connections are not freed in {FILL_TIMEOUT_S}s")
|
||||
|
||||
|
||||
def run(project: str, action: str, args: list[str]) -> str:
|
||||
"""Выполнить действие; синтаксис без match: hook запускают и 3.9."""
|
||||
if action in ("stop", "pause") and len(args) == 1:
|
||||
@@ -257,6 +383,10 @@ def run(project: str, action: str, args: list[str]) -> str:
|
||||
return psql(project, CLEAR_FAIL_MESSAGES_SQL)
|
||||
if action == "count-chats" and len(args) == 1:
|
||||
return psql(project, COUNT_CHATS_SQL, title=args[0])
|
||||
if action == "fill-connections" and len(args) == 1:
|
||||
return fill_connections(project, args[0])
|
||||
if action == "clear-connections" and not args:
|
||||
return clear_connections(project)
|
||||
raise HookError(f"unknown action or arguments: {action} {args}")
|
||||
|
||||
|
||||
|
||||
@@ -42,6 +42,9 @@ IDEMPOTENCY_TTL_S = 2
|
||||
POOL_TIMEOUT_S = 1
|
||||
# срок проверки Postgres в /health/ready
|
||||
READINESS_TIMEOUT_S = 2
|
||||
# сколько секунд hook держит слоты max_connections; clear-connections
|
||||
# освобождает их раньше
|
||||
FILL_HOLD_S = 30
|
||||
ME = f"{API}/users/me"
|
||||
|
||||
|
||||
@@ -217,6 +220,29 @@ def test_pool_exhausted(tight_api: Api, stand: Stand) -> None:
|
||||
assert_ok(tight_api.request("GET", ME, actor=fresh), 200, "User")
|
||||
|
||||
|
||||
@pytest.mark.spec("data-storage", "Предел соединений PostgreSQL исчерпан")
|
||||
def test_connection_limit_reached(tight_api: Api, stand: Stand) -> None:
|
||||
actor = tight_api.register()
|
||||
# hook оборвал соединение пула: при выдаче pool_pre_ping
|
||||
# переподключается и получает «too many clients» (SQLSTATE 53300)
|
||||
stand("fill-connections", str(FILL_HOLD_S))
|
||||
try:
|
||||
resp, took = timed(lambda: tight_api.request("GET", ME, actor=actor))
|
||||
error = assert_error(resp, 503)
|
||||
# отказ PostgreSQL мгновенный: ответ не ждёт срока пула
|
||||
assert took < POOL_TIMEOUT_S + 0.5, f"503 took {took:.2f}s"
|
||||
# недоступность хранилища — не отказ в аутентификации
|
||||
assert "WWW-Authenticate" not in resp.headers
|
||||
for word in ("postgres", "sql", "client", "connect"):
|
||||
assert word not in error["message"].lower()
|
||||
finally:
|
||||
stand("clear-connections")
|
||||
# слоты свободны: сервис снова обслуживает запросы без рестарта; срок
|
||||
# сессии 2 с за время заполнения истёк — новый вход
|
||||
fresh = tight_api.register()
|
||||
assert_ok(tight_api.request("GET", ME, actor=fresh), 200, "User")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Readiness
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
Reference in New Issue
Block a user