Files
mtusi2026lab6/openspec/specs/data-storage/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
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>
2026-11-11 04:46:56 +03:00

203 lines
13 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.
# 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 за время пачек не принимает от сервиса ни одного
нового соединения