forked from mtusi2026/mtusi2026lab4
Bring the Claude Code settings, the lint hook, the opsx commands and skills, the architecture notes, the lab 1 to lab 3 specs and the archived lab 1 to lab 3 changes into the lab 4 skeleton, so lab 4 continues the same spec history instead of starting from scratch. The files come from the lab 3 solution commit 61c0c28. Rewrite AGENTS.md and the openspec context and rules for lab 4: image attachments with metadata in PostgreSQL and bytes in a private RustFS bucket inside the stand, a third domain zone for attachments that asks the messaging zone about chat membership through a port wired in main.py, upload limits applied before unbounded reading or decoding, 201 only after both the object write and the commit, Out of scope moved to labs 5-7 plus presigned uploads, and rules on the write order between the two stores and on root S3 keys staying out of the API. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
44 lines
3.8 KiB
Markdown
44 lines
3.8 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 восстанавливать обслуживание без перезапуска своего процесса за счёт переподключения пула.
|
||
|
||
#### Scenario: PostgreSQL снова запущен
|
||
|
||
- **WHEN** сервис `postgres` запущен после остановки
|
||
- **THEN** в течение 30 с `/health/ready` отвечает `200`, а прежний токен читает свои данные
|
||
|
||
### Requirement: Ограниченный пул соединений
|
||
|
||
Каждый процесс API SHALL держать не больше заданного числа соединений с PostgreSQL. Запрос, не получивший соединение за заданное время, SHALL получать `503` и SHALL NOT ждать бесконечно. Все SQL-запросы SHALL быть параметризованными.
|
||
|
||
#### Scenario: Пул исчерпан
|
||
|
||
- **WHEN** все соединения пула заняты и приходит запрос, требующий БД
|
||
- **THEN** ответ `503 unavailable` за время ожидания соединения
|
||
|