Files
mtusi2026lab2/openspec/specs/lab2-session-cache/spec.md
T
ArtyomandClaude Opus 5.5 ac15b2ff62 Archive the carry over of the lab 2 fixes change
Lab 3 now stands on the finished lab 2. The deltas are synced to
openspec/specs: the zones meet only in the schema and Valkey is needed
only to confirm a logout; an outsider does not wait for a chat lock;
an empty cursor is 400 on history and on the chat list; a stuck request
at SIGTERM gets 500 from the server itself within the 6 s budget, which
still leaves 3 s after the drain window for the database timeouts; a
chunked body is limited by the bytes received; a logout rejected by
PostgreSQL withdraws its revocation mark. The event publication purpose
follows lab 2.

On a stand rebuilt from empty volumes: make test passes, failover
recovers the first write in 3.1 s with 0 failed attempts, persistence
passes, test-faults 12 passed including the full restart with logout
and the shortened session after an API restart, detection passes all
four scenarios with SIGTERM detected in 0.82 s and the stop done in
2.44 s, and the cache evidence finds a tombstone and a key that does
not outlive its session.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
2026-10-30 02:38:45 +03:00

5.7 KiB
Raw Blame History

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 удалять сессию. Если после записи отметки удалить сессию в PostgreSQL не удалось, выход SHALL отвечать 503 и SHALL снимать отметку отзыва: ответ 503 означает, что сессия осталась действующей и в БД, и для проверки токена.

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

Scenario: Выход при сбое PostgreSQL

  • WHEN отметка отзыва записана, но удаление сессии в PostgreSQL завершилось ошибкой
  • THEN выход отвечает 503 с кодом unavailable, токен по-прежнему получает 200, отметки отзыва в кэше нет
  • AND после возвращения PostgreSQL повторный выход отвечает 204, а токен затем получает 401

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