Files
mtusi2026lab5/openspec/specs/chat-cache/spec.md
T
ricoromaandClaude Opus 5.5 04f859282d chore: port lab 4 solution into the lab 5 skeleton
Source: mtusi2026lab4-safronov, solution/bvt2301-safronov, 2546deb.
Contracts, public tests and evidence of lab 4 are not carried over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 03:09:12 +03:00

6.5 KiB
Raw Blame History

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_<db> при запущенном рабочем стенде
  • THEN ключи карточек тестового прогона отличаются от рабочих префиксом с именем базы