# Как работает Лаб2 ## Связь с первой лабораторной В Лаб1 запросы уже умели создавать пользователя, чат, сообщения и читать историю страницами. Но данные жили в Dictionary внутри процесса, а X-User-Id позволял выбрать любого пользователя. После остановки процесса всё исчезало. В Лаб2 маршруты и модели сохранены. Меняются реализация хранилища и способ получения текущего пользователя. Это и есть польза интерфейсов: endpoint вызывает `IMessengerStore`, не зная, Dictionary там или PostgreSQL. `ICurrentUser` теперь проверяет Bearer, а не доверяет заголовку с UUID. ## Устройство ```mermaid flowchart TD Client["Клиент: curl или Python"] --> API["ASP.NET Core API"] API --> PG["PostgreSQL: данные и сессии"] API --> Redis["Redis: кэш профилей, TTL 300 с"] PG --> Volume["Именованный том PostgreSQL"] Redis --> CacheVolume["Том Redis, AOF"] ``` PostgreSQL — источник истины. Redis ускоряет повторное получение профиля (id, username, display_name, created_at). Проверка действительности сессии ВСЕГДА идёт в PostgreSQL, даже когда профиль есть в Redis. История сообщений не кэшируется: подтверждённая запись сразу видна при следующем чтении из БД. Выбор кэша намеренно небольшой. Профиль в текущем API нельзя изменять или удалять, поэтому нет гонки обновления профиля и устаревшего значения. Ключ `profile:v1:`, TTL 300 секунд. Cache miss → SELECT → заполнение кэша. Отказ Redis → тот же SELECT без кэша. После FLUSHDB сессия остаётся действительной, профиль будет прочитан и закэширован заново. Если появится редактирование пользователей, понадобится политика инвалидации; нынешнюю схему нельзя без изменений считать корректной для mutable-профилей. Выигрыш производительности здесь не измерен и не обещается. ## Путь одного сообщения 1. Клиент отправляет POST `/api/v1/chats/{id}/messages` с Bearer и JSON `{"text":"Привет"}`. 2. Middleware назначает X-Request-Id, чтобы связать запрос, ответ и лог. 3. `BearerCurrentUser` извлекает токен; `Sessions` вычисляет SHA-256 токена и ищет неистёкшую сессию в PostgreSQL. 4. Из сессии берётся user_id. Профиль читается из Redis или БД. Переданный клиентом X-User-Id не участвует. 5. Endpoint проверяет доступ к чату и входной JSON. sender_id клиент не задаёт. 6. SQL делает INSERT только при существующем членстве. Составной внешний ключ дополнительно запрещает запись от неучастника. 7. После завершения INSERT в autocommit приложение возвращает 201 с записью из RETURNING. До ответа 201 запрос должен дойти до успешного завершения операции БД. При потере соединения после COMMIT, но до ответа клиент может не знать, что запись состоялась. В Лаб2 нет идемпотентности повторной отправки; это тема Лаб3. ## Таблицы и связи | Таблица | Содержание | Основная защита | |---|---|---| | users | Профиль и hash пароля | PK id, UNIQUE username, CHECK формата | | chats | Название и время создания | PK id | | chat_members | Связь пользователя и чата | PK(chat_id,user_id), два FK | | messages | Текст, автор, чат, время | PK id, FK чат, FK(chat_id,sender_id) | | sessions | SHA-256 токена, пользователь, срок | PK token_hash, FK user_id | | schema_migrations | Применённые версии схемы | PK version | PK — первичный ключ, уникальный идентификатор строки. FK — внешний ключ, ссылка на существующую строку. UNIQUE — ограничение уникальности. Эти правила действуют при любой API-реплике; обычный lock в C# защищал бы только один процесс. Создание чата — транзакция: сначала INSERT chats, затем несколько INSERT chat_members, затем COMMIT. Если неизвестный участник нарушает FK, исключение превращается в 400; `await using` освобождает незавершённую транзакцию с rollback. Поэтому не остаётся пустой родительский чат. Проверка специально обращается к SQL и считает строки по уникальному названию. ## Пароли и сессии При регистрации пароль пропускается через библиотечный Argon2id: соль 16 случайных байт, память 64 MiB, 3 итерации, параллелизм 2, результат 32 байта. В БД сохраняется `argon2id-v1$$`; v1 фиксирует эти параметры в коде. Это собственная простая упаковка, не стандартная PHC-строка. При смене параметров нужен новый version и совместимая проверка старых записей. Соль не секретная: она делает одинаковые пароли разными hash. Argon2id намеренно дорогой, чтобы затруднить перебор украденной БД. Одновременно выполняются максимум два KDF на API-процесс; ожидание слота — до 2 секунд, затем 503. Это ограничивает память KDF, но не заменяет полноценную защиту входа от перебора. Проверка неизвестного username тоже выполняет KDF. Сравнение результатов — FixedTimeEquals. Login использует Basic: Base64 от UTF-8 `username:password`. Разделяем только по первому двоеточию, поэтому двоеточия в пароле разрешены. Base64 не шифрование. В учебном локальном стенде используются синтетические данные; для удалённого доступа нужен HTTPS. Токен создаётся криптографическим генератором из 32 байт (256 бит). Это opaque token: клиент не извлекает из него user_id и права. В sessions хранится только SHA-256 токена. Здесь быстрый SHA-256 уместен: токен случайный, обладает высокой энтропией; пользовательский пароль требует дорогого KDF. Токен не JWT. Expiry вычисляет PostgreSQL: `clock_timestamp()+TTL`. Проверка сравнивает expires_at с часами БД. Время не продлевается при использовании или рестарте. Logout удаляет строку сессии. Любой следующий запрос с этим токеном получает 401. Уже начавшийся запрос, прошедший проверку до logout, может завершиться — глобальной отмены таких запросов нет. Истёкшие строки не дают доступ, но пока остаются в таблице; для длительной эксплуатации нужен периодический DELETE по expires_at. ## Пагинация без чтения всей истории Индекс `messages(chat_id,created_at,id)` соответствует запросу: ```sql SELECT id,chat_id,sender_id,text,created_at FROM messages WHERE chat_id=$1 AND (created_at,id)>($2,$3) ORDER BY created_at,id LIMIT $4; ``` Первым фиксируется чат, затем БД переходит к позиции после курсора и берёт `limit+1`. Лишняя строка нужна только чтобы понять, есть ли следующая страница. Клиент получает не более limit строк. OFFSET не используется. Для первой страницы начальная граница — минимальное время. CursorCodec кодирует scope, время и UUID, подписывая HMAC-SHA256. Scope включает id чата (или пользователя для списка чатов), поэтому чужой cursor не подходит. Base64 не скрывает значения, но клиент должен считать курсор непрозрачным; подпись защищает от изменений. Ключ сохраняется в `secrets/cursor_key`, поэтому после рестарта курсоры работают. Время берётся из RETURNING БД, с PostgreSQL-точностью микросекунд: не конструируем курсор по более точному времени до INSERT. Сортировка по времени и UUID задаёт порядок даже при одинаковом времени. Для неизменной истории пропусков и повторов нет. Для конкурентных INSERT нет общего snapshot между HTTP-запросами: поздно закоммиченная строка с временем до уже пройденного курсора может не попасть в текущий обход. Перевод часов назад имеет похожее ограничение. Это не строгая очередь и не порядок COMMIT. `explain.sql` вставляет 10 000 сообщений в транзакции, запускает ANALYZE и EXPLAIN (ANALYZE, BUFFERS) для глубокой страницы, затем ROLLBACK. Читать результат нужно так: имя индекса показывает выбранный путь; actual rows — сколько вернули; Buffers — работа с буферами; execution time — время данного запуска, не универсальная производительность. Индекс ускоряет SELECT, но занимает место и увеличивает работу INSERT. ## Карта файлов и используемые библиотеки | Файл/библиотека | Для чего | |---|---| | Program.cs | DI, конфигурация, logging, миграции, запуск HTTP | | Api/Endpoints.cs | Связывает маршруты, проверку входа, идентификацию и хранилище | | Api/Input.cs | Строгие JSON-поля, UUID, Unicode, limit | | Api/ApiMiddleware.cs | Единый формат ошибок, request_id, безопасные логи | | Api/CurrentUser.cs | Только Bearer, без доверия X-User-Id | | Storage/PostgresMessengerStore.cs | SQL, транзакция чата, keyset, кэш профилей | | Storage/Sessions.cs | Login, срок сессии, проверка и logout | | Storage/Passwords.cs | Ограниченный по параллелизму Argon2id | | Storage/Migrations.cs | Транзакционное применение версий под advisory lock | | Npgsql 9.0.4 | Драйвер PostgreSQL, pool, параметры SQL | | StackExchange.Redis 2.8.31 | Один общий multiplexer для Redis | | Konscious.Security.Cryptography.Argon2 1.3.1 | Реализация Argon2id | | tests/client.py | Предоставленный преподавателем HTTP-клиент и проверки схем | Singleton означает один экземпляр сервиса на процесс. NpgsqlDataSource и Redis multiplexer рассчитаны на совместное использование. Singleton хранилища не означает одно соединение: операция берёт соединение из pool и возвращает через DisposeAsync. Максимум pool — 20, connection timeout — 3 секунды, command timeout — 3 секунды. Несколько последовательных операций могут суммарно занять больше 3 секунд. Для Redis connect/async timeout — 1 секунда, backlog отключён; фактический timeout зависит от обслуживания таймеров клиента. Все пользовательские данные идут через SQL-параметры `$1`, `$2`, … . Конкатенация в ChatSelect соединяет только постоянные SQL-фрагменты, а не текст пользователя. Локальные проверочные SQL используют сгенерированные UUID/hex-метки, не внешний ввод. ## Миграции и запуск Compose поднимает PostgreSQL, Redis, API. Именованные тома переживают удаление контейнеров. API ждёт healthchecks при первоначальном старте и перед HTTP применяет миграции. `schema_migrations` хранит имя версии; повторный запуск пропускает применённый файл. Advisory transaction lock сериализует одновременный запуск миграций несколькими API. Уже применённый SQL не редактируют: добавляют 002 и далее. Контроль checksum миграций пока не реализован. Логическое соответствие настроек: APP_HOST/APP_PORT управляют внутренним HTTP; внешний APP_PORT из .env управляет port mapping. APP_ENV — метка в логе. SESSION_TTL_SECONDS — срок новой сессии. DATABASE_URL_FILE и CACHE_URL_FILE — пути к секретам, а не URL прямо в compose. DATABASE_URL содержит Npgsql connection string. CURSOR_KEY_FILE — добавленный секрет подписи курсоров. SESSION_STORE из skeleton не нужен: сессии всегда PostgreSQL, что явно выбрано в реализации. Readiness требует PostgreSQL; Redis — необязательная для корректности зависимость после старта. Liveness не проверяет БД. При потере БД защищённый запрос возвращает 503: мы не превращаем отсутствие проверки в успешную аутентификацию. Redis в compose включён с AOF everysec и томом, но возможная потеря последней секунды кэша не теряет сессии или сообщения: их источник истины — PostgreSQL. ## Источники - https://www.npgsql.org/doc/basic-usage.html - https://www.npgsql.org/doc/connection-string-parameters.html - https://github.com/StackExchange/StackExchange.Redis/blob/main/docs/Configuration.md - https://github.com/kmaragon/Konscious.Security.Cryptography - https://www.postgresql.org/docs/17/tutorial-transactions.html - https://www.postgresql.org/docs/17/using-explain.html - https://www.rfc-editor.org/rfc/rfc7617 - Контракт, README и публичные tests из приложенного архива Лаб2.