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