Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 to lab 4 specs and the
archived lab 1 to lab 4 changes into the lab 5 skeleton, so lab 5
continues the same spec history instead of starting from scratch. The
files come from the lab 4 solution commit d2744bc.
Rewrite AGENTS.md and the openspec context and rules for lab 5: upload
answers 202 queued after the original is in a private staging prefix
and the attachment, the job and the outbox row are committed in one
transaction, a separate relay publishes the outbox to RabbitMQ with
publisher confirms, a separate worker built from the same image
consumes the queue through FastStream with a manual ack after the
result commit, PostgreSQL stays the source of truth for job states,
Out of scope moves to labs 6-7, track 1 and broker HA, and the rules
add the failure windows between PostgreSQL and the broker, the effect
key and the lease to specs and designs.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
4.8 KiB
lab2-session-cache Specification
Purpose
Определяет роль Valkey в лабе 2: read-through кэш сессий поверх PostgreSQL — что в нём лежит, сколько живёт, как инвалидируется при выходе и что происходит при его недоступности, очистке и рестарте.
Requirements
Requirement: Кэш сессий поверх источника истины
Проверка Bearer-токена SHALL сначала обращаться к кэшу Valkey по ключу от SHA-256 токена и только при промахе — к PostgreSQL, после чего заполнять кэш. PostgreSQL SHALL оставаться единственным источником истины: в кэш SHALL NOT попадать ничего, чего нет в БД, а запись кэша SHALL NOT жить дольше expires_at сессии. Токен в открытом виде SHALL NOT храниться в кэше.
Scenario: Повторная проверка обслуживается кэшем
- WHEN пользователь дважды подряд выполняет
GET /api/v1/users/meс одним токеном - THEN второй запрос находит сессию в Valkey: счётчик попаданий
keyspace_hitsрастёт, в кэше есть ключsession:<sha256>
Scenario: Срок записи кэша не превышает срок сессии
- WHEN сессия закэширована
- THEN абсолютный срок жизни ключа (
PEXPIRETIME) не позжеexpires_atсессии
Requirement: Выход инвалидирует кэш
Отзыв сессии SHALL записывать в кэш отметку отзыва на оставшийся срок сессии до удаления строки в БД, а заполнение кэша после промаха SHALL выполняться только при отсутствии ключа. Отозванный токен SHALL получать 401 и при гонке «чтение заполнило кэш после выхода». Если отметку отзыва записать нельзя, выход SHALL отвечать 503 и SHALL NOT удалять сессию.
Scenario: Отозванный токен не оживает из кэша
- WHEN токен закэширован, после чего пользователь выполняет
DELETE /api/v1/auth/sessions/current - THEN ответ
204, а следующий запрос с этим токеном получает401
Scenario: Выход при недоступном кэше
- WHEN Valkey остановлен и пользователь выполняет
DELETE /api/v1/auth/sessions/current - THEN ответ
503с кодомunavailable, а после запуска Valkey повторный выход отвечает204
Requirement: Недоступный кэш обходится, но не открывает доступ
При ошибке или таймауте Valkey проверка сессии SHALL выполняться по PostgreSQL за ограниченное время, а повторные попытки обращения к кэшу SHALL приостанавливаться на короткий интервал. Недействительный токен SHALL получать 401; запрос SHALL NOT приниматься как анонимный. Недоступность Valkey SHALL NOT переводить /health/ready в 503.
Scenario: Valkey остановлен
- WHEN сервис
valkeyостановлен - THEN
GET /api/v1/users/meс действительным токеном отвечает200быстрее 1 с, с неизвестным токеном —401,/health/ready—200, вход поBasic—201
Requirement: Очистка и рестарт кэша безопасны
Потеря содержимого Valkey (FLUSHALL, рестарт без данных) SHALL NOT терять сессии и SHALL NOT оживлять отозванные. Valkey SHALL хранить данные с AOF на именованном volume, чтобы рестарт сохранял тёплый кэш и отметки отзыва.
Scenario: FLUSHALL
- WHEN в Valkey выполнен
FLUSHALL - THEN действующий токен получает
200, отозванный —401
Scenario: Рестарт Valkey
- WHEN сервис
valkeyперезапущен - THEN ключи сессий на месте, действующий токен получает
200, отозванный —401