Files
mtusi2026lab6/openspec/specs/chat-cache/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
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>
2026-11-11 04:46:56 +03:00

120 lines
6.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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** ключи карточек тестового прогона отличаются от рабочих
префиксом с именем базы