# Проект хранения данных ## Источники истины PostgreSQL является источником истины для пользователей, чатов, участников, сообщений и сессий. Redis используется как cache-aside кэш неизменяемых карточек чатов, но не как источник истины. Потеря Redis не приводит к потере данных или сессий. ## Redis cache-aside Ключ: ```text chat:v1: ``` Значение — 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`.