forked from mtusi2026/mtusi2026lab2
233 lines
7.4 KiB
Markdown
233 lines
7.4 KiB
Markdown
# Проект хранения данных
|
||
|
||
## Источники истины
|
||
|
||
PostgreSQL является источником истины для пользователей, чатов, участников,
|
||
сообщений и сессий.
|
||
|
||
Redis будет использоваться как cache-aside кэш чатов, но не как источник
|
||
истины. Потеря Redis не должна приводить к потере данных.
|
||
|
||
## Общие решения
|
||
|
||
- Идентификаторы создаются приложением как UUID.
|
||
- Время назначается PostgreSQL и хранится как `TIMESTAMPTZ`.
|
||
- API возвращает время в UTC в формате RFC 3339.
|
||
- Чаты и сообщения упорядочиваются по `(created_at, id)`.
|
||
- Используется уровень изоляции `READ COMMITTED`.
|
||
- Все SQL-запросы параметризованы и выполняются с timeout.
|
||
- Snapshot между несколькими HTTP-запросами не гарантируется.
|
||
|
||
## Таблицы
|
||
|
||
### `users`
|
||
|
||
```text
|
||
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`
|
||
|
||
```text
|
||
id UUID PRIMARY KEY
|
||
title TEXT NOT NULL
|
||
created_at TIMESTAMPTZ NOT NULL
|
||
```
|
||
|
||
Ограничения:
|
||
|
||
- `title` содержит 1–100 символов;
|
||
- `title` не состоит только из пробелов.
|
||
|
||
Индекс порядка:
|
||
|
||
```text
|
||
(created_at, id)
|
||
```
|
||
|
||
### `chat_members`
|
||
|
||
```text
|
||
chat_id UUID NOT NULL REFERENCES chats(id)
|
||
user_id UUID NOT NULL REFERENCES users(id)
|
||
position SMALLINT NOT NULL
|
||
```
|
||
|
||
Ограничения:
|
||
|
||
```text
|
||
PRIMARY KEY (chat_id, user_id)
|
||
UNIQUE (chat_id, position)
|
||
CHECK (position BETWEEN 0 AND 99)
|
||
```
|
||
|
||
`position` сохраняет порядок `member_ids` и ограничивает число участников
|
||
чата сотней.
|
||
|
||
Индекс для поиска чатов пользователя:
|
||
|
||
```text
|
||
(user_id, chat_id)
|
||
```
|
||
|
||
### `messages`
|
||
|
||
```text
|
||
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)`.
|
||
|
||
Составной внешний ключ гарантирует, что отправитель является участником чата.
|
||
|
||
Индекс истории:
|
||
|
||
```text
|
||
(chat_id, created_at, id)
|
||
```
|
||
|
||
### `sessions`
|
||
|
||
```text
|
||
token_hash BYTEA PRIMARY KEY
|
||
user_id UUID NOT NULL REFERENCES users(id)
|
||
created_at TIMESTAMPTZ NOT NULL
|
||
expires_at TIMESTAMPTZ NOT NULL
|
||
```
|
||
|
||
Ограничения:
|
||
|
||
```text
|
||
CHECK (octet_length(token_hash) = 32)
|
||
CHECK (expires_at > created_at)
|
||
```
|
||
|
||
Клиент получает непрозрачный токен с энтропией не менее 256 бит. В PostgreSQL
|
||
хранится только его SHA-256 digest.
|
||
|
||
Сессия действительна, пока строка существует и `expires_at` больше текущего
|
||
времени. Logout физически удаляет строку сессии.
|
||
|
||
Индекс для очистки истёкших сессий:
|
||
|
||
```text
|
||
(expires_at)
|
||
```
|
||
|
||
## Транзакционные границы
|
||
|
||
### Регистрация
|
||
|
||
Хеш Argon2id вычисляется до обращения к БД. Пользователь создаётся одним
|
||
`INSERT`. Уникальное ограничение защищает от конкурентной регистрации
|
||
одинакового `username`.
|
||
|
||
### Создание чата
|
||
|
||
Одна транзакция:
|
||
|
||
1. Проверить существование всех участников.
|
||
2. Вставить чат.
|
||
3. Вставить всех участников с позициями.
|
||
4. Выполнить COMMIT.
|
||
|
||
Любая ошибка приводит к ROLLBACK всей операции.
|
||
|
||
### Отправка сообщения
|
||
|
||
Проверка членства и вставка сообщения выполняются согласованно. Предпочтительно
|
||
использовать один `INSERT ... SELECT ... WHERE EXISTS`.
|
||
|
||
Отсутствующий и чужой чат возвращают одинаковый HTTP 404.
|
||
|
||
### Сессии
|
||
|
||
При входе приложение проверяет Argon2id, создаёт случайный токен и сохраняет
|
||
его digest с абсолютным `expires_at`.
|
||
|
||
Аутентификация ищет digest токена и проверяет срок действия. Logout удаляет
|
||
текущую сессию. После COMMIT новый запрос с этим токеном получает HTTP 401.
|
||
|
||
## Курсорная пагинация
|
||
|
||
### Сообщения
|
||
|
||
Курсор содержит:
|
||
|
||
```text
|
||
version, created_at, message_id, chat_id
|
||
```
|
||
|
||
SQL-граница:
|
||
|
||
```sql
|
||
WHERE chat_id = $1
|
||
AND (created_at, id) > ($2, $3)
|
||
ORDER BY created_at, id
|
||
LIMIT $4
|
||
```
|
||
|
||
### Чаты
|
||
|
||
Курсор содержит:
|
||
|
||
```text
|
||
version, created_at, chat_id, user_id
|
||
```
|
||
|
||
SQL-граница:
|
||
|
||
```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(*)`.
|
||
|
||
## Миграции
|
||
|
||
Первая миграция создаёт таблицы в порядке:
|
||
|
||
1. `users`;
|
||
2. `chats`;
|
||
3. `chat_members`;
|
||
4. `messages`;
|
||
5. `sessions`.
|
||
|
||
Откат удаляет таблицы в обратном порядке.
|
||
|
||
Применённые миграции учитываются в отдельной таблице версий. Повторный запуск
|
||
не должен повторно создавать схему, дублировать или удалять данные.
|
||
|
||
Для применения используется `golang-migrate` версии `v4.20.1` как отдельный
|
||
Compose-сервис. Миграции не запускаются автоматически каждой API-репликой.
|
||
|
||
Инструмент хранит текущую версию и состояние применения в служебной таблице
|
||
`schema_migrations`. Неуспешная миграция останавливает запуск API и требует
|
||
явного разбора причины, а не автоматического `force`. |