Files
mtusi2026lab3/docs/decisions/0001-postgres-sessions-shards.md
T

6.1 KiB
Raw Blame History

ADR-0001: PostgreSQL, сессии и шардированный Valkey

Статус: реализовано, проверено локально и развёрнуто в Kubernetes dev / highload-applications.

Контекст

Задание требует устойчивого состояния и аутентификации. Дополнительные требования: общий limiter с группами, пользовательские лимиты и демонстрация consistent hashing на 2–3 шардах.

Решение

PostgreSQL хранит пользователей, credentials, чаты, участников, сообщения и hash сессионного токена с абсолютным expiry. Пароли обрабатывает библиотечный Argon2id: 19 MiB, 2 прохода, один поток, salt 16 bytes, hash 32 bytes. Bearer содержит 32 случайных bytes; хранится только SHA-256 digest. Сессия проверяется по PostgreSQL на каждом запросе. Logout удаляет запись до ответа 204.

Valkey кэширует неизменяемые профили с TTL 5 минут. Кэш не хранит историю и не определяет действительность сессии. Cache miss, повреждённая запись и ошибка чтения профиля ведут к PostgreSQL. Поскольку Valkey одновременно обслуживает обязательный limiter, отказ его узла закрывает admission; обход кэша не означает обход лимитера.

Клиентское кольцо использует SHA-256 → 64-bit координату и 256 виртуальных узлов на стабильный ID шарда. Глобальные бюджеты имеют постоянного координатора shard0; пользовательские бюджеты и профили распределяются по кольцу. Недоступный шард не исключается автоматически: такое исключение сбросило бы активный пользовательский лимит.

Lua атомарно проверяет и резервирует два бюджета на одном узле: общий и соответствующей группы. Глобальная резервация предшествует аутентификации, пользовательская следует за ней. Это последовательное консервативное резервирование, а не распределённая транзакция: отклонённый пользовательский запрос уже расходует глобальный rate budget; глобальный slot освобождается. Успешных запросов сверх лимита такой порядок не допускает.

Rate использует фиксированное окно 1 секунда от первого запроса; на границе возможны два burst подряд. Slots представлены sorted sets с уникальными lease ID, освобождением через ZREM и expiry 30 секунд. HTTP timeout ограничен 15 секундами, по умолчанию 3. Отказ освобождения оставляет временно занятый slot до expiry. Длительная приостановка процесса свыше lease и скачки часов Valkey выходят за гарантию строгой одновременности; это не распределённая блокировка для изменения обязательных данных.

Смена кольца: остановить все API, дождаться drain и 31 секунду, добавить шард, изменить конфигурацию, сбросить только guard topology, запустить API. Fingerprint стабильных ID проверяется при старте/readiness. Значения профилей на старых владельцах истекают; новые владельцы прогреваются из PostgreSQL. Миграция обязательных данных не нужна. В этой демонстрации расширение требует короткого окна недоступности, online resharding не заявляется.

Альтернативы и последствия

Redis Cluster использует фиксированные hash slots и собственный протокол маршрутизации; это другая модель, чем реализуемое клиентское кольцо. Перенос authoritative sessions в Valkey усложнил бы проверку persistence и инвалидацию при смене кольца. Здесь PostgreSQL остаётся единственным источником истины.

Один PostgreSQL, один глобальный координатор и локальные PVC не обеспечивают HA. Глобальный координатор ограничивает масштабирование строгого общего лимита. Для lab2 это намеренная, явно проверяемая граница.

Проверки и источники

Проверки кольца, атомарности и групп находятся в internal/hashring и internal/valkey; сценарии отказов и результаты — в REPORT.

Первичные материалы: Redis rate limiter, pgx StrictNamedArgs. Собственные Lua-операции и ring реализованы в этом репозитории.