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

34 lines
6.1 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.
# ADR-0001: PostgreSQL, сессии и шардированный Valkey
Статус: реализовано, проверено локально и развёрнуто в Kubernetes dev / highload-applications.
## Контекст
[Задание](../../README.md) требует устойчивого состояния и аутентификации. Дополнительные требования: общий 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](../../REPORT.md).
Первичные материалы: [Redis rate limiter](https://redis.io/docs/latest/develop/use-cases/rate-limiter/), [pgx StrictNamedArgs](https://pkg.go.dev/github.com/jackc/pgx/v5#StrictNamedArgs). Собственные Lua-операции и ring реализованы в этом репозитории.