7.4 KiB
Проект хранения данных
Источники истины
PostgreSQL является источником истины для пользователей, чатов, участников, сообщений и сессий.
Redis будет использоваться как cache-aside кэш чатов, но не как источник истины. Потеря Redis не должна приводить к потере данных.
Общие решения
- Идентификаторы создаются приложением как UUID.
- Время назначается PostgreSQL и хранится как
TIMESTAMPTZ. - API возвращает время в UTC в формате RFC 3339.
- Чаты и сообщения упорядочиваются по
(created_at, id). - Используется уровень изоляции
READ COMMITTED. - Все SQL-запросы параметризованы и выполняются с timeout.
- Snapshot между несколькими HTTP-запросами не гарантируется.
Таблицы
users
id UUID PRIMARY KEY
username VARCHAR(32) NOT NULL UNIQUE
display_name TEXT NOT NULL
password_hash TEXT NOT NULL
created_at TIMESTAMPTZ NOT NULL
Ограничения:
usernameсоответствует^[a-z0-9_]{3,32}$;display_nameсодержит 1–100 символов и не состоит только из пробелов;password_hashсодержит PHC-строку Argon2id;- исходный пароль не хранится и не записывается в логи.
Уникальность username окончательно обеспечивает PostgreSQL. При конкурентной
регистрации нарушение уникальности преобразуется в HTTP 409.
chats
id UUID PRIMARY KEY
title TEXT NOT NULL
created_at TIMESTAMPTZ NOT NULL
Ограничения:
titleсодержит 1–100 символов;titleне состоит только из пробелов.
Индекс порядка:
(created_at, id)
chat_members
chat_id UUID NOT NULL REFERENCES chats(id)
user_id UUID NOT NULL REFERENCES users(id)
position SMALLINT NOT NULL
Ограничения:
PRIMARY KEY (chat_id, user_id)
UNIQUE (chat_id, position)
CHECK (position BETWEEN 0 AND 99)
position сохраняет порядок member_ids и ограничивает число участников
чата сотней.
Индекс для поиска чатов пользователя:
(user_id, chat_id)
messages
id UUID PRIMARY KEY
chat_id UUID NOT NULL
sender_id UUID NOT NULL
text TEXT NOT NULL
created_at TIMESTAMPTZ NOT NULL
Ограничения:
textсодержит 1–4000 символов;textне состоит только из пробелов;(chat_id, sender_id)ссылается наchat_members(chat_id, user_id).
Составной внешний ключ гарантирует, что отправитель является участником чата.
Индекс истории:
(chat_id, created_at, id)
sessions
token_hash BYTEA PRIMARY KEY
user_id UUID NOT NULL REFERENCES users(id)
created_at TIMESTAMPTZ NOT NULL
expires_at TIMESTAMPTZ NOT NULL
Ограничения:
CHECK (octet_length(token_hash) = 32)
CHECK (expires_at > created_at)
Клиент получает непрозрачный токен с энтропией не менее 256 бит. В PostgreSQL хранится только его SHA-256 digest.
Сессия действительна, пока строка существует и expires_at больше текущего
времени. Logout физически удаляет строку сессии.
Индекс для очистки истёкших сессий:
(expires_at)
Транзакционные границы
Регистрация
Хеш Argon2id вычисляется до обращения к БД. Пользователь создаётся одним
INSERT. Уникальное ограничение защищает от конкурентной регистрации
одинакового username.
Создание чата
Одна транзакция:
- Проверить существование всех участников.
- Вставить чат.
- Вставить всех участников с позициями.
- Выполнить COMMIT.
Любая ошибка приводит к ROLLBACK всей операции.
Отправка сообщения
Проверка членства и вставка сообщения выполняются согласованно. Предпочтительно
использовать один INSERT ... SELECT ... WHERE EXISTS.
Отсутствующий и чужой чат возвращают одинаковый HTTP 404.
Сессии
При входе приложение проверяет Argon2id, создаёт случайный токен и сохраняет
его digest с абсолютным expires_at.
Аутентификация ищет digest токена и проверяет срок действия. Logout удаляет текущую сессию. После COMMIT новый запрос с этим токеном получает HTTP 401.
Курсорная пагинация
Сообщения
Курсор содержит:
version, created_at, message_id, chat_id
SQL-граница:
WHERE chat_id = $1
AND (created_at, id) > ($2, $3)
ORDER BY created_at, id
LIMIT $4
Чаты
Курсор содержит:
version, created_at, chat_id, user_id
SQL-граница:
WHERE member.user_id = $1
AND (chat.created_at, chat.id) > ($2, $3)
ORDER BY chat.created_at, chat.id
LIMIT $4
В обоих запросах передаётся limit + 1. Дополнительная строка определяет,
нужно ли возвращать next_cursor, без отдельного COUNT(*).
Миграции
Первая миграция создаёт таблицы в порядке:
users;chats;chat_members;messages;sessions.
Откат удаляет таблицы в обратном порядке.
Применённые миграции учитываются в отдельной таблице версий. Повторный запуск не должен повторно создавать схему, дублировать или удалять данные.
Для применения используется golang-migrate версии v4.20.1 как отдельный
Compose-сервис. Миграции не запускаются автоматически каждой API-репликой.
Инструмент хранит текущую версию и состояние применения в служебной таблице
schema_migrations. Неуспешная миграция останавливает запуск API и требует
явного разбора причины, а не автоматического force.