302 lines
11 KiB
Markdown
302 lines
11 KiB
Markdown
# Проект хранения данных
|
||
|
||
## Источники истины
|
||
|
||
PostgreSQL является источником истины для пользователей, чатов, участников,
|
||
сообщений и сессий.
|
||
|
||
Redis используется как cache-aside кэш неизменяемых карточек чатов, но не как
|
||
источник истины. Потеря Redis не приводит к потере данных или сессий.
|
||
|
||
## Redis cache-aside
|
||
|
||
Ключ:
|
||
|
||
```text
|
||
chat:v1:<chat_uuid>
|
||
```
|
||
|
||
Значение — JSON-представление `domain.Chat`: идентификатор, заголовок,
|
||
упорядоченный список участников и время создания. TTL по умолчанию — 5 минут.
|
||
Префикс `v1` версионирует внутренний формат независимо от HTTP API.
|
||
|
||
Алгоритм чтения:
|
||
|
||
1. Прочитать и проверить значение Redis.
|
||
2. При hit проверить, что вызывающий пользователь есть в `member_ids`.
|
||
3. При miss прочитать PostgreSQL и best-effort заполнить Redis.
|
||
4. При timeout/ошибке Redis прочитать PostgreSQL и не повторять cache write в
|
||
том же запросе.
|
||
|
||
Создание чата сначала полностью фиксируется транзакцией PostgreSQL, после чего
|
||
выполняется best-effort запись в Redis. Контракт не содержит изменения
|
||
заголовка или состава участников и удаления чата, поэтому write-инвалидация
|
||
сейчас не требуется. TTL удаляет забытые копии, а повреждённое значение
|
||
удаляется при чтении.
|
||
|
||
Redis работает без RDB/AOF и volume, с лимитом 64 MiB и `allkeys-lru`.
|
||
Это намеренная политика для производного кэша. Readiness зависит только от
|
||
PostgreSQL; при очистке или restart 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. Для каждого участника выполнить параметризованный
|
||
`INSERT ... SELECT FROM users WHERE id = $2`.
|
||
3. Проверить, что каждая команда вставила ровно одну строку.
|
||
4. Выполнить COMMIT.
|
||
|
||
Если пользователя нет, `RowsAffected() == 0`: функция возвращает
|
||
`ErrNotFound`, а deferred `ROLLBACK` удаляет уже вставленный чат и предыдущие
|
||
membership-строки. Автотест отправляет существующего вызывающего и
|
||
несуществующий UUID, проверяет отсутствие частичного чата, затем успешно
|
||
создаёт другой чат через то же приложение.
|
||
|
||
### Отправка сообщения
|
||
|
||
Проверка членства и вставка сообщения выполняются согласованно. Предпочтительно
|
||
использовать один `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(*)`.
|
||
|
||
## План истории на 10 000 сообщений
|
||
|
||
Команда `make explain-history` открывает транзакцию, добавляет отдельные
|
||
синтетические user/chat и ровно 10 000 сообщений, выполняет `ANALYZE`, печатает
|
||
два `EXPLAIN (ANALYZE, BUFFERS)` и завершает всё `ROLLBACK`. Поэтому измерение
|
||
повторяемо и не оставляет нагрузочные строки в постоянной БД.
|
||
|
||
Для первой страницы наблюдался план:
|
||
|
||
```text
|
||
Limit (actual rows=101)
|
||
-> Index Scan using messages_chat_created_at_id_idx
|
||
Index Cond: (chat_id = ...)
|
||
Buffers: shared hit=5
|
||
Execution Time: 0.068 ms
|
||
```
|
||
|
||
Для страницы после 5000-го сообщения:
|
||
|
||
```text
|
||
Limit (actual rows=101)
|
||
-> Index Scan using messages_chat_created_at_id_idx
|
||
Index Cond: chat_id = ... AND ROW(created_at, id) > ROW(...)
|
||
Buffers: shared hit=6
|
||
Execution Time: 0.111 ms
|
||
```
|
||
|
||
Составной индекс `(chat_id, created_at, id)` одновременно соответствует
|
||
фильтру одного чата, tuple-границе keyset cursor и порядку выдачи. Поэтому
|
||
PostgreSQL не делает `Seq Scan` и не сортирует всю историю для каждой страницы.
|
||
Времена относятся только к указанному WSL2-стенду и не являются универсальным
|
||
production-бенчмарком.
|
||
|
||
## Миграции
|
||
|
||
Первая миграция создаёт таблицы в порядке:
|
||
|
||
1. `users`;
|
||
2. `chats`;
|
||
3. `chat_members`;
|
||
4. `messages`;
|
||
5. `sessions`.
|
||
|
||
Откат удаляет таблицы в обратном порядке.
|
||
|
||
Применённые миграции учитываются в отдельной таблице версий. Повторный запуск
|
||
не должен повторно создавать схему, дублировать или удалять данные.
|
||
|
||
Для применения используется `golang-migrate` версии `v4.20.1` как отдельный
|
||
Compose-сервис. Миграции не запускаются автоматически каждой API-репликой.
|
||
|
||
Инструмент хранит текущую версию и состояние применения в служебной таблице
|
||
`schema_migrations`. Неуспешная миграция останавливает запуск API и требует
|
||
явного разбора причины, а не автоматического `force`.
|