# 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:` #### Scenario: Срок записи кэша не превышает срок сессии - **WHEN** сессия закэширована - **THEN** абсолютный срок жизни ключа (`PEXPIRETIME`) не позже `expires_at` сессии ### Requirement: Выход инвалидирует кэш Отзыв сессии SHALL инвалидировать кэш до фиксации удаления в PostgreSQL. Отозванный токен SHALL получать `401` и при гонке «чтение заполнило кэш после выхода», включая потерю или смену состояния кэша. Если инвалидация невозможна, выход SHALL отвечать `503` и SHALL NOT фиксировать удаление сессии. Если транзакция удаления не завершилась, выход SHALL отвечать `503` и SHALL снимать отметку отзыва: сессия остаётся действующей. Основание: `contracts/README.md`, выход и абсолютный TTL; `README.md`, уровень «3», сохранение минимума lab2. #### 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` #### Scenario: Запоздавшее чтение после выхода и потери кэша - **WHEN** чтение действующей сессии задержалось, другая реплика завершила logout с `204`, затем очистка или вытеснение удалили отметку отзыва и задержанное чтение продолжилось - **THEN** новый `GET /api/v1/users/me` с тем же токеном получает `401` с `WWW-Authenticate: Bearer realm="messenger"` и телом общей ошибки, даже если другая проверка успела заново обратиться к кэшу #### Scenario: Очистка кэша до завершения выхода - **WHEN** кэш очищен после инвалидации, но до COMMIT удаления сессии, и параллельно начинается новая проверка токена - **THEN** эта проверка не оставляет действующую сессию в кэше после успешного logout, следующие запросы получают `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`