Files
mtusi2026lab2/openspec/specs/lab2-session-cache/spec.md
T
ArtyomandClaude Opus 5.5 8cd30488d2 Archive the carry over of the lab 3 fixes change
Sync the delta specs into the main specs: zones are linked by the
schema and the ports main.py assembles, the event bus and the network
dependencies name S3 and Valkey, an outsider does not wait for chat
locks, an empty cursor is rejected, a request cancelled at shutdown gets
503 in the contract format, the body limit counts received bytes per
route, logout withdraws the revocation mark on a database failure,
detection runs three times, failover-each records the stopped replica,
lost answers are retried on the stand, posting checks its input in a
fixed order and make up waits for every replica in the balancer.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
2026-10-30 06:25:44 +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