diff --git a/openspec/changes/fix-lab3-review-session-cache-and-errors/.openspec.yaml b/openspec/changes/fix-lab3-review-session-cache-and-errors/.openspec.yaml new file mode 100644 index 00000000..8a94d769 --- /dev/null +++ b/openspec/changes/fix-lab3-review-session-cache-and-errors/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-06 diff --git a/openspec/changes/fix-lab3-review-session-cache-and-errors/design.md b/openspec/changes/fix-lab3-review-session-cache-and-errors/design.md new file mode 100644 index 00000000..590fbb5b --- /dev/null +++ b/openspec/changes/fix-lab3-review-session-cache-and-errors/design.md @@ -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::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). diff --git a/openspec/changes/fix-lab3-review-session-cache-and-errors/proposal.md b/openspec/changes/fix-lab3-review-session-cache-and-errors/proposal.md new file mode 100644 index 00000000..832a6b54 --- /dev/null +++ b/openspec/changes/fix-lab3-review-session-cache-and-errors/proposal.md @@ -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-проверки. diff --git a/openspec/changes/fix-lab3-review-session-cache-and-errors/specs/lab2-session-cache/spec.md b/openspec/changes/fix-lab3-review-session-cache-and-errors/specs/lab2-session-cache/spec.md new file mode 100644 index 00000000..4618a9a8 --- /dev/null +++ b/openspec/changes/fix-lab3-review-session-cache-and-errors/specs/lab2-session-cache/spec.md @@ -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` diff --git a/openspec/changes/fix-lab3-review-session-cache-and-errors/specs/lab3-load-balancing/spec.md b/openspec/changes/fix-lab3-review-session-cache-and-errors/specs/lab3-load-balancing/spec.md new file mode 100644 index 00000000..11a52f67 --- /dev/null +++ b/openspec/changes/fix-lab3-review-session-cache-and-errors/specs/lab3-load-balancing/spec.md @@ -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` diff --git a/openspec/changes/fix-lab3-review-session-cache-and-errors/tasks.md b/openspec/changes/fix-lab3-review-session-cache-and-errors/tasks.md new file mode 100644 index 00000000..b3ce2907 --- /dev/null +++ b/openspec/changes/fix-lab3-review-session-cache-and-errors/tasks.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.