54 lines
5.3 KiB
Markdown
54 lines
5.3 KiB
Markdown
# 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` за время ожидания соединения
|