Files
mtusi2026lab2/openspec/specs/lab2-session-cache/spec.md
T
ArtyomandClaude Opus 5.5 1210dd899c Carry over the agent context and openspec history from lab 4
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>
2026-10-29 00:32:37 +03:00

57 lines
4.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`