forked from mtusi2026/mtusi2026lab3
Propose session cache and load balancer review fixes
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-06
|
||||
@@ -0,0 +1,32 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в proposal.md. Зона identity уже имеет порты `SessionDirectory` и `SessionRevocations`, адаптеры `PostgresSessionDirectory`/`CachedSessionDirectory`, сборку в `identity/entrypoints/ioc.py`. Меняются только эти адаптеры и порядок операций `CloseSessionHandler`; messaging и shared не расширяются.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
Сохранить один GET Valkey на попадание и PostgreSQL как источник истины. Защитить промах от запоздавшей записи при очистке и вытеснении ключей, в том числе до COMMIT logout. Не менять схему, миграции и API.
|
||||
|
||||
## Decisions
|
||||
|
||||
1. Перед чтением БД создать `session:<sha256>:fill` с уникальным nonce через SET NX и абсолютным TTL не больше лимита кэша. Параллельный читатель без собственного маркера читает БД, но не заполняет кэш. Lua атомарно сравнивает nonce, удаляет собственный маркер и выполняет SET NX сессии. Отсутствие/смена маркера запрещает заполнение. Отзыв одним Lua устанавливает прежнее значение `-` и удаляет маркер. Отдельный ключ сохраняет прежний формат положительного кэша; токен в открытом виде не хранится. Повторная проверка БД на каждом попадании отвергнута: она устраняет пользу кэша. Одного SET NX недостаточно после потери tombstone.
|
||||
2. Logout выполняет DELETE строки в транзакции PostgreSQL, затем отзыв кэша, затем COMMIT. Ошибка откатывает DELETE и снимает отметку, как прежде. Чтение сессии использует `FOR KEY SHARE`, который не блокирует другие чтения, но ждёт незавершённый DELETE. Если маркер создан после очистки кэша во время logout, чтение дождётся COMMIT и увидит отсутствие строки. Если чтение завершилось до DELETE, последующий отзыв удалит его маркер. Блокировка снимается при закрытии AsyncSession до обращения к Valkey. Одного маркера без этого порядка недостаточно при FLUSHALL до COMMIT.
|
||||
3. Существующая таблица `sessions`: PK `token_hash bytea`, FK `user_id`, неизменные `created_at`/`expires_at`; SELECT по PK с фильтром абсолютного TTL. Ожидается индексный поиск с LockRows; EXPLAIN здесь не выполняется. SQLAlchemy 2.0.45: `with_for_update(read=True, key_share=True)`, без сырого SQL и без Alembic revision.
|
||||
4. В теле трёх ошибок HAProxy использовать `json(ascii)`: байты HTTP-заголовка экранируются без потери, кавычки, обратная косая черта и управляющие символы не ломают JSON. Заголовок остаётся исходным. Режим ascii соответствует байтовой/Latin-1 интерпретации HTTP-заголовков; utf8s может молча отбросить байты. Round robin, readiness, retries, DNS, таймауты и контейнерные лимиты не меняются.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Промах требует дополнительного SET и Lua вместо прежнего SET; чтение БД получает короткую разделяемую блокировку. Попадание не меняется. Цена должна быть проверена финальным нагрузочным агентом, прежние RPS не являются измерениями исправленного SHA.
|
||||
- Сбой кэша обходит заполнение; ошибка отзыва ведёт к rollback и `503`. TTL маркера ограничивает последствия отменённого чтения; нет локальной координации между репликами.
|
||||
- Прерванный запрос, прочитавший сессию до logout, может завершиться успешно. После `204` новые запросы обязаны получать `401`.
|
||||
- Старые реплики всё ещё умеют небезопасное заполнение. Формат данных совместим, но гарантия исправления наступает после замены всех реплик и очистки прежнего кэша сессий в выделенном стенде. Новые volumes не нужны; существующие сохраняются.
|
||||
- Offline-модель проверяет порядок вызовов и исходы гонок, но не выполнение Lua/блокировок реальными серверами. Для них добавляются интеграционные тесты, запуск — отдельным финальным этапом.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Применить код и конфигурацию LB, выполнить полный финальный прогон из чистого clone; старые evidence сохранить с SHA. Откат к прежнему образу возвращает дефект отзыва и не считается исправлением.
|
||||
|
||||
## References
|
||||
|
||||
- Context7: `/sqlalchemy/sqlalchemy/rel_2_0_45`, `/websites/valkey_io`, `/haproxy/haproxy`.
|
||||
- [PostgreSQL 17: row locks](https://www.postgresql.org/docs/17/explicit-locking.html#LOCKING-ROWS).
|
||||
- [HAProxy 3.2: JSON converter](https://docs.haproxy.org/3.2/configuration.html#7.3.1-json).
|
||||
@@ -0,0 +1,29 @@
|
||||
## Why
|
||||
|
||||
Ревью snapshot `4513d90e482e9bb7bb1fd0402cfec45aa7f52d36` выявило восстановление отозванной сессии запоздавшим заполнением после потери кэша и невалидный JSON ошибок HAProxy при кавычке в `X-Request-Id`. Исправление сохраняет обязательный минимум lab2 и уровень «3» lab3: общие сессии и корректные ответы через LB.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Связать заполнение кэша с одноразовым маркером, созданным перед чтением PostgreSQL; потеря или смена маркера запрещает запись старой сессии.
|
||||
- Согласовать чтение сессии и отзыв внутри транзакции, включая очистку кэша до COMMIT logout.
|
||||
- Экранировать `request_id` в JSON ошибок 502/503/504, сохранив исходный заголовок.
|
||||
- Добавить регрессионные проверки и список обязательных динамических прогонов следующего этапа.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
Нет.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `lab2-session-cache`: отзыв остаётся действующим при совмещённой гонке чтения, logout и потери/смены кэша.
|
||||
- `lab3-load-balancing`: JSON ошибок LB корректен для специальных символов в идентификаторе запроса.
|
||||
|
||||
## Impact
|
||||
|
||||
Зона identity: адаптеры Valkey/PostgreSQL и обработчик закрытия сессии; инфраструктура: конфигурация HAProxy. Схема, Alembic, зависимости и HTTP-контракт неизменны. Трассировка: `README.md`, уровень «3», сохранение минимума lab2; строки `REPORT.md` о сессиях/кэше и единой точке входа. Прежние измерения относятся к прежнему SHA; новые нагрузочные результаты здесь не заявляются.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Без возможностей из Out of scope `openspec/config.yaml`, изменения нормативных файлов, Docker, нагрузки, публикации и финального отчёта. Этот этап исправляет код и выполняет только offline-проверки.
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### 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`
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Готовность backend и обновление адресов
|
||||
|
||||
Балансировщик SHALL активно проверять каждую реплику запросом `GET /health/ready` и SHALL исключать из ротации реплику, которая не отвечает `200`. Адреса реплик SHALL обновляться через DNS без перезапуска балансировщика: остановленная реплика исчезает из ротации, запущенная или пересозданная появляется сама. Ответы, сформированные самим балансировщиком (`502`, `503`, `504`), SHALL иметь тело в общем формате ошибки с `request_id`, равным заголовку `X-Request-Id`.
|
||||
|
||||
#### Scenario: Реплика возвращается в ротацию
|
||||
|
||||
- **WHEN** остановленная реплика снова запущена
|
||||
- **THEN** после успешных проверок готовности балансировщик снова направляет на неё запросы без перезапуска `lb`
|
||||
|
||||
#### Scenario: Нет ни одной готовой реплики
|
||||
|
||||
- **WHEN** все реплики API остановлены
|
||||
- **THEN** запрос через LB получает `503` с телом `{"error":{"code":"unavailable",...}}`
|
||||
|
||||
#### Scenario: Специальные символы идентификатора в ошибке LB
|
||||
|
||||
- **WHEN** запрос с допустимым `X-Request-Id`, содержащим кавычку, обратную косую черту или табуляцию, получает ошибку `502`, `503` или `504` от балансировщика
|
||||
- **THEN** заголовок ответа сохраняет исходное значение, тело является валидным JSON, а декодированное `error.request_id` совпадает с заголовком
|
||||
- **AND** сохраняется общий формат ошибки из `contracts/README.md`; требование относится к единой точке входа уровня «3» `README.md`
|
||||
@@ -0,0 +1,14 @@
|
||||
## 1. Identity: сохранение минимума уровня «3»
|
||||
|
||||
- [ ] 1.1 Добавить одноразовый маркер заполнения и атомарную проверку/инвалидацию в Valkey; согласовать DELETE, отзыв и COMMIT с блокирующим чтением сессии.
|
||||
- [ ] 1.2 Добавить offline-регрессии потери/смены маркера и интеграционные сценарии logout + очистка/вытеснение, включая очистку до COMMIT; выполнить только offline-подмножество pytest.
|
||||
|
||||
## 2. Инфраструктура LB
|
||||
|
||||
- [ ] 2.1 Применить JSON-конвертер в телах 502/503/504, сохранить заголовок; проверить шаблоны offline на специальных символах.
|
||||
|
||||
## 3. Проверки и передача следующему этапу
|
||||
|
||||
- [ ] 3.1 Выполнить make check, make validate, make lint, offline unit tests и openspec validate --all --strict, сохранить фактический вывод.
|
||||
- [ ] 3.2 Записать в evidence ограничения проверки и обязательные динамические команды для финального агента; сохранить старые измерения с исходными SHA.
|
||||
- [ ] 3.3 Синхронизировать дельты спецификаций, архивировать change с датой и lab: 3; make lint перед английскими коммитами, без push.
|
||||
Reference in New Issue
Block a user