Files
mtusi2026lab5/openspec/specs/data-storage/spec.md
T
ricoromaandClaude Opus 5.5 e2a6427c24 feat: add job outbox, relay, leases and image variants to the pipeline
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>
2026-10-31 15:36:15 +03:00

13 KiB
Raw Blame History

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 держать постоянный набор соединений. Соединение, возвращённое в пул после запроса, SHALL оставаться открытым и обслуживать следующие запросы. При настройках по умолчанию соединений сверх размера пула сервис MUST NOT открывать. Запрос, которому не хватило свободного соединения, SHALL ждать его в очереди пула не дольше таймаута ожидания, а не открывать новое соединение с PostgreSQL. Новое соединение сервис открывает, только пока пул не набрал своего размера, и взамен соединения, закрытого после обрыва или отказа.

Scenario: Соединения исчерпаны

  • WHEN все соединения пула заняты дольше таймаута ожидания
  • THEN новый запрос получает 503 unavailable не позже этого таймаута, а не ждёт бесконечно

Scenario: Соединения пула не переоткрываются

  • WHEN пул прогрет, и сервису раз за разом приходят пачки одновременных запросов, которых больше, чем соединений в пуле
  • THEN все запросы пачек обслуживаются успешно
  • AND PostgreSQL за время пачек не принимает от сервиса ни одного нового соединения