Files
mtusi2026lab2/openspec/specs/lab2-dependency-failures/spec.md
T

54 lines
5.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` за время ожидания соединения