Files
2026-11-13 11:08:23 +03:00

123 lines
17 KiB
Markdown
Raw Permalink 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.
# Как работает Лаб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:<uuid>`, 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$<salt>$<hash>`; 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.