- carry the lab 3 solution over from mtusi2026lab3-safronov (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests, bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts, Dockerfile, compose, pyproject and uv lock - merge Makefile, .gitignore and .dockerignore (the lab 3 versions only add lines to the skeleton, which is the same in lab 4) and .env.example (lab 4 skeleton names listed in the header) - rename the compose project to mtusi-lab4 and the image to :lab4 so the stand does not reuse the lab 3 containers and volumes - update AGENTS.md for lab 4: current lab, origin commit, contract and test files of the new skeleton Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.5 KiB
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 ключи карточек тестового прогона отличаются от рабочих префиксом с именем базы