forked from mtusi2026/mtusi2026lab2
123 lines
17 KiB
Markdown
123 lines
17 KiB
Markdown
# Как работает Лаб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.
|