Move publishing out of the upload path: a relay process publishes queued jobs with confirms. Add lease and attempt fencing, backoff with jitter, a per-job render process with CPU and memory limits, crop and optimized variants, the failed registry with audited replay, and staging cleanup. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
13 KiB
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_connectionsPostgreSQL заняты, и пулу сервиса для запроса нужно новое соединение - THEN PostgreSQL отказывает в подключении («too many clients»,
SQLSTATE
53300), а клиент получает 503unavailableбез деталей вmessage, а не 500 - AND после освобождения слотов запросы обслуживаются без перезапуска сервиса
Requirement: Ограниченный пул соединений и таймауты
Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой.
Ожидание свободного соединения, подключение и выполнение запроса SHALL
иметь таймауты из настроек. Истёкший таймаут SHALL давать 503
unavailable.
Пул SHALL держать постоянный набор соединений. Соединение, возвращённое в пул после запроса, SHALL оставаться открытым и обслуживать следующие запросы. При настройках по умолчанию соединений сверх размера пула сервис MUST NOT открывать. Запрос, которому не хватило свободного соединения, SHALL ждать его в очереди пула не дольше таймаута ожидания, а не открывать новое соединение с PostgreSQL. Новое соединение сервис открывает, только пока пул не набрал своего размера, и взамен соединения, закрытого после обрыва или отказа.
Scenario: Соединения исчерпаны
- WHEN все соединения пула заняты дольше таймаута ожидания
- THEN новый запрос получает 503
unavailableне позже этого таймаута, а не ждёт бесконечно
Scenario: Соединения пула не переоткрываются
- WHEN пул прогрет, и сервису раз за разом приходят пачки одновременных запросов, которых больше, чем соединений в пуле
- THEN все запросы пачек обслуживаются успешно
- AND PostgreSQL за время пачек не принимает от сервиса ни одного нового соединения