forked from mtusi2026/mtusi2026lab3
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
63 lines
5.7 KiB
Markdown
63 lines
5.7 KiB
Markdown
# 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`
|
||
|