# chat-cache Specification ## Purpose Как сервис кэширует карточку чата в Valkey: что хранится в кэше и чего в нём нет, источник истины, срок и вытеснение записей, почему не нужна инвалидация, обход кэша при его недоступности и поведение после очистки. ## Requirements ### Requirement: Кэш карточки чата Карточка чата — `id`, `title`, `member_ids` в порядке создания и `created_at` — SHALL читаться сначала из Valkey, при промахе — из PostgreSQL с записью в кэш. Созданный чат SHALL записываться в кэш после commit. Источник истины — PostgreSQL: кэш MUST NOT содержать карточку, которой нет в PostgreSQL, и ответ API из кэша MUST совпадать с ответом из PostgreSQL. Из той же карточки берётся проверка членства в `GET /api/v1/chats/{chat_id}`, `POST …/messages` и `GET …/messages`. #### Scenario: Повторное чтение чата - **WHEN** участник дважды запрашивает `GET /api/v1/chats/{chat_id}` - **THEN** оба ответа 200 и совпадают с ответом на создание чата, в том числе порядок `member_ids` #### Scenario: Проверка членства по карточке - **WHEN** чат только что создан, его участник пишет в него сообщение, а посторонний запрашивает чат - **THEN** участник получает 201, посторонний — 404 #### Scenario: Чтение из кэша - **WHEN** карточку одного чата читают 50 раз подряд - **THEN** PostgreSQL читает таблицу `chats` для этого чата не больше одного раза, остальные ответы — из Valkey ### Requirement: Граница кэша История сообщений, список чатов пользователя и сессии MUST NOT кэшироваться: история и список меняются с каждой записью, а отзыв сессии обязан действовать сразу. Карточка чата после создания не меняется, поэтому кэш не инвалидируется: устаревшей карточки не бывает. #### Scenario: Сообщение видно сразу - **WHEN** участник отправил сообщение и сразу читает историю - **THEN** сообщение есть в истории #### Scenario: Новый чат в списке - **WHEN** пользователь создал чат и сразу запрашивает `GET /api/v1/chats` - **THEN** чат есть в списке ### Requirement: Срок и вытеснение Запись карточки SHALL храниться не дольше срока из настроек. Память Valkey SHALL быть ограничена, при её нехватке Valkey SHALL вытеснять давно не читанные ключи (LRU). Persistence Valkey выключен: потеря кэша MUST NOT приводить к потере данных. #### Scenario: Срок записи - **WHEN** карточка записана в кэш - **THEN** у её ключа есть срок, не больше настроенного ### Requirement: Обход недоступного кэша Если Valkey недоступен или не ответил за таймаут клиента, запрос SHALL обслуживаться из PostgreSQL с тем же ответом, что и с кэшем. Сервис MUST NOT отвечать 500 и MUST NOT обслуживать запрос как анонимный. Добавка к времени ответа SHALL быть ограничена таймаутом клиента; после отказа кэш SHALL пропускаться на время из настроек, без ожидания таймаута в каждом запросе. Отказ SHALL записываться в журнал с уровнем `warning`. Когда Valkey снова доступен, сервис SHALL использовать кэш без перезапуска. #### Scenario: Valkey остановлен - **WHEN** контейнер Valkey остановлен, и участник читает чат, пишет сообщение и читает историю - **THEN** ответы 200, 201 и 200 с теми же телами, что при работающем кэше #### Scenario: Valkey завис - **WHEN** Valkey принимает соединения, но не отвечает (`docker compose pause`) - **THEN** запросы обслуживаются из PostgreSQL, и время ответа растёт не больше чем на таймаут клиента #### Scenario: Valkey вернулся - **WHEN** Valkey снова запущен, а API не перезапускался - **THEN** через время пропуска кэш снова отдаёт карточки ### Requirement: Очистка и рестарт кэша После `FLUSHALL` или рестарта Valkey сервис SHALL отвечать так же, как до них, и заново заполнять кэш при чтении. #### Scenario: Очистка кэша - **WHEN** выполнен `FLUSHALL` в Valkey, и участник читает чат - **THEN** ответ 200 с той же карточкой, а ключ чата снова есть в кэше ### Requirement: Ключи по базе Ключ карточки SHALL включать имя базы PostgreSQL, из которой она прочитана. Два экземпляра API с разными базами на одном Valkey MUST NOT видеть карточки друг друга. #### Scenario: Временная база - **WHEN** `make test_isolated` работает с базой `test_` при запущенном рабочем стенде - **THEN** ключи карточек тестового прогона отличаются от рабочих префиксом с именем базы