5.3 KiB
lab2-dependency-failures Specification
Purpose
Определяет поведение API при отказе PostgreSQL и при исчерпании пула соединений: ограниченная по времени ошибка 503 вместо зависания, 500 или анонимного доступа, и восстановление без рестарта процесса.
Requirements
Requirement: Отказ PostgreSQL даёт ограниченную ошибку
При недоступном 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через 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 восстанавливать чтение и запись без перезапуска своего процесса за счёт переподключения пула. Закрытое сервером простаивающее соединение SHALL заменяться до выполнения новой операции; его повторная выдача SHALL NOT приводить к 503 при доступной БД. Уже начатые операции SHALL NOT автоматически повторяться. Требование сохраняет минимум lab2 и минимум ЛР3 (критерий 3.9 README.md ЛР4).
Scenario: PostgreSQL снова запущен
- WHEN сервис
postgresзапущен после остановки - THEN в течение 30 с
/health/readyотвечает200, а прежний токен читает свои данные - AND после возвращения всех реплик в ротацию валидные новые
POST /api/v1/usersчерез LB возвращают201, без перезапуска API
Scenario: Сервер закрыл простаивающее соединение
- WHEN PostgreSQL доступен, но закрыл ранее возвращённое в пул соединение, и приходит валидный
POST /api/v1/users - THEN запрос возвращает
201сUser,X-Request-IdиX-Instance-Id; создаётся ровно один пользователь
Scenario: БД ещё недоступна
- WHEN соединение закрыто и PostgreSQL всё ещё недоступен
- THEN запрос получает ограниченную ошибку
503сerror.code=unavailable,error.message,error.request_id,X-Request-IdиX-Instance-Idсогласно общему контракту
Requirement: Ограниченный пул соединений
Каждый процесс API SHALL держать не больше заданного числа соединений с PostgreSQL. Запрос, не получивший соединение за заданное время, SHALL получать 503 и SHALL NOT ждать бесконечно. Все SQL-запросы SHALL быть параметризованными.
Scenario: Пул исчерпан
- WHEN все соединения пула заняты и приходит запрос, требующий БД
- THEN ответ
503 unavailableза время ожидания соединения