Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e. Contracts, public tests and evidence of lab 5 are not carried over. The compose project, image and CI prefix are renamed to lab6; the first broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the OpenSpec changes of lab 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
203 lines
13 KiB
Markdown
203 lines
13 KiB
Markdown
# data-storage Specification
|
||
|
||
## Purpose
|
||
|
||
Где живут данные мессенджера с лабы 2 и какие гарантии они дают:
|
||
PostgreSQL как источник истины, сохранность после рестарта, целостность
|
||
и транзакции на стороне БД, поведение при недоступности БД и
|
||
ограниченные ресурсы подключения.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Хранение в PostgreSQL
|
||
|
||
Пользователи, чаты, участники чатов, сообщения, сессии, с лабы 4 —
|
||
метаданные вложений и связи сообщений с вложениями, а с лабы 5 — задания
|
||
обработки и метаданные вариантов SHALL храниться в PostgreSQL, он — источник
|
||
истины. Сервис MUST NOT хранить эти данные в памяти процесса, файлах или
|
||
SQLite. Сообщение брокера лишь сообщает о задании: состояние задания MUST NOT
|
||
определяться по брокеру. Байты вложений SHALL храниться в S3 (capability
|
||
`attachments`, `object-storage`), а не в PostgreSQL и не в файлах реплик.
|
||
Подтверждённая запись (ответ 201, 202 или 204) SHALL быть зафиксирована до
|
||
ответа и видна следующему запросу.
|
||
|
||
#### Scenario: Созданное видно сразу
|
||
|
||
- **WHEN** клиент зарегистрировался и следующим запросом входит с теми
|
||
же username и паролем
|
||
- **THEN** вход успешен, и `GET /api/v1/users/me` с выданным токеном
|
||
возвращает этого пользователя
|
||
|
||
#### Scenario: Принятое вложение видно сразу
|
||
|
||
- **WHEN** участник получил ответ 202 на загрузку и сразу запрашивает
|
||
метаданные через другую реплику
|
||
- **THEN** ответ 200 с тем же `id`, а `status` — `queued` или более поздний
|
||
|
||
### Requirement: Данные переживают рестарт
|
||
|
||
После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее
|
||
подтверждённые пользователи, чаты, участники и сообщения SHALL быть
|
||
доступны в прежнем виде. С лабы 4 это относится и к вложениям: их
|
||
метаданные, `attachment_ids` сообщений и оригиналы переживают и
|
||
перезапуск S3 с его volume.
|
||
|
||
#### Scenario: Прежний пользователь после рестарта
|
||
|
||
- **WHEN** стенд перезапущен `scripts/restart.sh`, и клиент использует
|
||
токен, полученный до рестарта
|
||
- **THEN** ответ 200, а история чата этого пользователя содержит те же
|
||
сообщения в том же порядке
|
||
|
||
### Requirement: Параллельные запросы не повреждают состояние
|
||
|
||
Параллельные запросы MUST NOT терять, дублировать или повреждать
|
||
записи. Уникальность `username` SHALL обеспечиваться ограничением БД,
|
||
а не проверкой перед вставкой, поэтому одновременная регистрация
|
||
одного имени создаёт ровно одного пользователя.
|
||
|
||
#### Scenario: 100 сообщений от 10 клиентов
|
||
|
||
- **WHEN** 10 клиентов одновременно отправляют по 10 сообщений в один
|
||
чат
|
||
- **THEN** получено 100 ответов 201, а полный обход истории возвращает
|
||
ровно 100 сообщений с уникальными `id`
|
||
|
||
#### Scenario: Гонка за username
|
||
|
||
- **WHEN** несколько клиентов одновременно регистрируют одинаковый
|
||
`username`
|
||
- **THEN** создан ровно один пользователь
|
||
|
||
### Requirement: Целостность данных в БД
|
||
|
||
Ограничения SHALL проверяться самой БД, а не только сервисом:
|
||
- уникальность `username`;
|
||
- существование пользователей и чатов, на которые ссылаются участники
|
||
и сообщения;
|
||
- уникальность участника в чате;
|
||
- членство отправителя в чате сообщения.
|
||
|
||
С лабы 4 БД SHALL проверять и вложения:
|
||
- владелец вложения — участник его чата;
|
||
- связь сообщения с вложением ссылается на существующие сообщение и
|
||
вложение;
|
||
- вложение не повторяется в одном сообщении, у каждого места в порядке
|
||
одно вложение, мест не больше 10;
|
||
- вложение, на которое ссылается сообщение, удалить нельзя;
|
||
- допустимые значения размера, SHA-256, типа, статуса и длины
|
||
`filename`; ключ объекта уникален.
|
||
|
||
С лабы 5 БД SHALL проверять и обработку:
|
||
- код ошибки есть только у вложения `failed`, и у `failed` он есть;
|
||
- на вложение и версию конвейера одно задание, оно ссылается на существующее
|
||
вложение; вложение с заданием удалить нельзя;
|
||
- допустимые значения состояния и числа попыток задания; число попыток до
|
||
последнего replay не больше числа начатых;
|
||
- вариант уникален по вложению, версии конвейера и имени; он ссылается на
|
||
существующее вложение; допустимые значения имени, типа, размера, ширины,
|
||
высоты и SHA-256; ключ объекта варианта уникален;
|
||
- запись аудита replay ссылается на существующее задание; задание с такой записью
|
||
удалить нельзя.
|
||
|
||
Порядок `member_ids`, заданный при создании чата, и порядок
|
||
`attachment_ids` сообщения SHALL сохраняться. Принадлежность вложения
|
||
чату сообщения проверяет сервис в той же транзакции: чат вложения и
|
||
чат сообщения не меняются после записи.
|
||
|
||
#### Scenario: Порядок участников
|
||
|
||
- **WHEN** чат создан с `member_ids` в порядке `[bob, alice]`
|
||
- **THEN** `GET` этого чата и список чатов возвращают `member_ids` в
|
||
том же порядке, в том числе после рестарта стенда
|
||
|
||
#### Scenario: Порядок вложений
|
||
|
||
- **WHEN** сообщение отправлено с `attachment_ids` `[C, A, B]`
|
||
- **THEN** ответ на отправку, история чата и повтор с тем же ключом
|
||
возвращают `[C, A, B]`
|
||
|
||
#### Scenario: Ограничения обработки в схеме
|
||
|
||
- **WHEN** проверяющий пытается вставить второе задание той же версии конвейера,
|
||
второй вариант с тем же именем, `error_code` у вложения не `failed` и запись аудита
|
||
replay с неизвестным заданием
|
||
- **THEN** PostgreSQL отклоняет каждую вставку нарушением ограничения
|
||
|
||
### Requirement: Составная операция в одной транзакции
|
||
|
||
Создание чата вместе с участниками SHALL выполняться одной
|
||
транзакцией: при ошибке на любом шаге в БД MUST NOT остаться ни чата,
|
||
ни части его участников.
|
||
|
||
#### Scenario: Сбой при добавлении участников
|
||
|
||
- **WHEN** чат уже записан в транзакции, а запись участников
|
||
завершается ошибкой
|
||
- **THEN** транзакция откатывается, чата нет ни в `GET` по его `id`, ни
|
||
в списках чатов участников
|
||
|
||
### 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** после освобождения слотов запросы обслуживаются без
|
||
перезапуска сервиса
|
||
|
||
### Requirement: Ограниченный пул соединений и таймауты
|
||
|
||
Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой.
|
||
Ожидание свободного соединения, подключение и выполнение запроса SHALL
|
||
иметь таймауты из настроек. Истёкший таймаут SHALL давать 503
|
||
`unavailable`.
|
||
|
||
Запрос SHALL занимать соединение только на время шага с PostgreSQL, а не на
|
||
весь запрос (capability `unit-of-work`). Между шагами, на время вычисления
|
||
хэша пароля и передачи ответа соединение SHALL быть в пуле.
|
||
|
||
Пул SHALL держать постоянный набор соединений. Соединение, возвращённое
|
||
в пул после шага, SHALL оставаться открытым и обслуживать следующие
|
||
запросы. При настройках по умолчанию соединений сверх размера пула
|
||
сервис MUST NOT открывать. Запрос, которому не хватило свободного
|
||
соединения, SHALL ждать его в очереди пула не дольше таймаута ожидания,
|
||
а не открывать новое соединение с PostgreSQL. Новое соединение сервис
|
||
открывает, только пока пул не набрал своего размера, и взамен
|
||
соединения, закрытого после обрыва или отказа.
|
||
|
||
#### Scenario: Соединения исчерпаны
|
||
|
||
- **WHEN** все соединения пула заняты дольше таймаута ожидания
|
||
- **THEN** новый запрос получает 503 `unavailable` не позже этого
|
||
таймаута, а не ждёт бесконечно
|
||
|
||
#### Scenario: Соединения пула не переоткрываются
|
||
|
||
- **WHEN** пул прогрет, и сервису раз за разом приходят пачки
|
||
одновременных запросов, которых больше, чем соединений в пуле
|
||
- **THEN** все запросы пачек обслуживаются успешно
|
||
- **AND** PostgreSQL за время пачек не принимает от сервиса ни одного
|
||
нового соединения
|