Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e. Contracts, public tests and evidence of lab 5 are not carried over. The compose project, image and CI prefix are renamed to lab6; the first broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the OpenSpec changes of lab 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
120 lines
6.5 KiB
Markdown
120 lines
6.5 KiB
Markdown
# 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** ключи карточек тестового прогона отличаются от рабочих
|
||
префиксом с именем базы
|