Files
mtusi2026lab5/openspec/specs/data-storage/spec.md
T
ricoromaandClaude Opus 5.5 ff1a83b6ff feat: process attachments asynchronously with RabbitMQ and a worker
Upload answers 202 after staging, a queued job in PostgreSQL and a broker
confirm; a separate worker publishes the original and a thumbnail with
bounded retries. Adds the job and variant tables, the broker service, the
worker S3 user, cleanup and reconcile support for staging and variants,
the failure stand with broker and worker, bench and driver updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 06:48:20 +03:00

12 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 он есть;
  • на вложение и версию конвейера одно задание, оно ссылается на существующее вложение; вложение с заданием удалить нельзя;
  • допустимые значения состояния и числа попыток задания;
  • вариант уникален по вложению, версии конвейера и имени; он ссылается на существующее вложение; допустимые значения имени, типа, размера, ширины, высоты и SHA-256; ключ объекта варианта уникален.

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