- Хранилище транзакций — состояние транзакций входа/подтверждения (Transaction Engine).
- База OpenIddict — клиенты и токены OIDC-сервера.
Хранилище транзакций
Настраивается вConfigureTransactionEngine. Выберите одно хранилище.
Program.cs
Сам метод
UseEfCoreStore поставляется отдельным пакетом — ядро не подтягивает EF Core
транзитивно. Провайдер EF Core (UseNpgsql, UseSqlServer) и его NuGet-пакет принадлежат
хост-приложению — ядро не зависит от провайдера. Сборка миграций, названная в
MigrationsAssembly(...), поставляется ещё одним пакетом — без него схема не создастся:MigrationsAssembly(...):
Журнал аудита ведёт историю миграций в собственной таблице, чтобы делить БД с хранилищем транзакций:
рядом с
MigrationsAssembly(...) в UseEfCoreSink передайте
MigrationsHistoryTable(AuditMigrationDefaults.MigrationsHistoryTable).
Параметры Redis (RedisTransactionStoreOptions):
Configuration— строка подключения (например,localhost:6379).KeyPrefix— префикс ключей транзакций (по умолчаниюveriqa:tx:).
Veriqa:TransactionEngine:Store:Provider
— PostgreSQL, SqlServer или Redis, а Veriqa:TransactionEngine:Store:ConnectionString — строка
подключения этого хранилища. На Redis она идёт в Configuration, а Veriqa:TransactionEngine:Store:KeyPrefix
задаёт KeyPrefix. Без строки подключения хранилище остаётся в памяти, что бы ни говорил провайдер.
Хранилище на Redis не даёт стоку аудита своей базы (см.
Сток аудита) и не может держать
хранилище собранных claims. У readiness появляется проверка
redis-transactions. Redis, недоступный на старте, останавливает контейнер, если строка подключения
не задаёт abortConnect=false: тогда контейнер поднимается, а сбой видит только readiness.
Новый вход закрывает прежние
Когда пользователь начинает вход заново и приходит в канал тем же аккаунтом, прежние входы этого аккаунта в то же приложение, ещё ждущие ответа, закрываются — см. Повторный вход. Находит их хранилище транзакций, поэтому обновление касается каждого хранилища по-своему:- InMemory — делать ничего не нужно.
- EF Core — миграция
AddSignInSubjectFingerprintдобавляет в таблицу транзакций одну nullable-колонку с неуникальным индексом. Она поставляется в обоих пакетах миграций и применяется как любая другая. Входы, записанные до неё, отпечатка не несут: новый вход их не закрывает, они доживают до своего срока. - Redis — рядом с транзакциями, под тем же
KeyPrefix, хранилище ведёт по одному множеству идентификаторов транзакций на тенант, приложение и аккаунт канала. В ключе лежит хеш, а не идентификатор пользователя в канале; множество истекает само. - Собственное хранилище — реализуйте
GetPendingSignInsAsync, см. Обновление собственного хранилища.
Обновление собственного хранилища
Если вы реализовалиITransactionStore сами, при обновлении с 0.6.1 хранилище перестанет
компилироваться: в интерфейсе семь новых членов, и реализации по умолчанию нет ни у одного.
Встроенные хранилища их уже реализуют.
Шесть членов
Try… — атомарные условные записи. Чтение с последующей записью не подходит: из двух
одновременных вызовов true должен получить только один. UpdateAsync эти значения не пишет и не
стирает, а каждое чтение их возвращает. Все обязательства описаны в README пакета
Veriqa.Core.TransactionEngine, раздел «Собственное хранилище транзакций».
Новое свойство TransactionSnapshot, в отличие от нового члена интерфейса, может прийти, не ломая
сборку. Если вы храните снимок из Transaction.ToSnapshot() одним сериализованным документом и
сериализатор записывает все публичные свойства, новое свойство, которое пишет UpdateAsync,
сохраняется без правок с вашей стороны. Если вы раскладываете свойства по колонкам, после каждого
обновления сверяйте TransactionSnapshot со своим отображением: свойство, которого нет в отображении,
теряется при каждой записи.
Значения членов Try… — исключение в обоих случаях. Новое такое значение может прийти без нового
члена интерфейса (например, новое значение HopObservationMark — это новая отметка, которую пишет
TryMarkHopObservationAsync), и UpdateAsync его не пишет и не стирает. После каждого обновления
убедитесь, что ваши члены Try… пишут каждое новое значение, а UpdateAsync его не затирает; если
UpdateAsync переносит такие значения из сохранённой записи по фиксированному перечню полей,
добавьте в перечень новое.
Канальные хранилища: несколько реплик
Канальный слой держит несколько собственных хранилищ. По умолчанию они в памяти процесса — этого достаточно для одной реплики, но не для двух:
Разворачиваете больше одной реплики — подключите Redis-реализации всех этих хранилищ одним
вызовом на билдере канальных адаптеров:
Program.cs
UseRedisChannelStores всё
остаётся в памяти процесса — реализации по умолчанию не подменяются.
Параметры (RedisChannelStoreOptions):
Configuration— строка подключения. Оставьте пустой, чтобы намеренно переиспользоватьIConnectionMultiplexer, зарегистрированный в контейнере кем-то ещё. Задать её при таком мультиплексоре нельзя: хост тогда не стартует. Ошибка конфигурации называет обе стороны — адреса, номер логической БД, настройки TLS и имя мастера sentinel (учётные данные не печатаются). Без этой проверки заданная строка молча игнорировалась бы, а канальные хранилища оказались бы в чужом Redis. Проверка выполняется на старте хоста, поэтому порядок двух регистраций значения не имеет.PromptKeyPrefix— префикс координат подсказки (по умолчаниюveriqa:ch:prompt:).EmailActionTokenKeyPrefix— префикс action-токенов (по умолчаниюveriqa:ch:email:token:).EmailPushCorrelationKeyPrefix— префикс корреляций Push (по умолчаниюveriqa:ch:email:corr:).ProcessedMessageKeyPrefix— префикс отметок обработанных писем (по умолчаниюveriqa:ch:email:msg:).EmailClaimCompletionKeyPrefix— префикс хранилища добора email (по умолчаниюveriqa:ch:email:claim:). Адреса и аккаунты канала в его ключах — отпечатки SHA-256, коды и токены ссылок хранятся только отпечатками.PhoneRequestCorrelationKeyPrefix— префикс запросов номера телефона (по умолчаниюveriqa:ch:phone:). Остаток ключа — хеш SHA-256 чата, так что идентификатор пользователя канала открытым текстом не хранится.LinkHandleKeyPrefix— префикс ключей handle связки (по умолчаниюveriqa:ch:link:). Остаток ключа — отпечаток SHA-256 от handle; сам handle не хранится.StartCodeKeyPrefix— префикс ключей коротких кодов старта входа (по умолчаниюveriqa:ch:code:). Остаток ключа — хеш SHA-256; сам код в ключ не попадает.WebProviderStateKeyPrefix— префикс ключей состояния страниц на телефоне у каналов входа через аккаунт провайдера (по умолчаниюveriqa:ch:webprovider:). Метка браузера и аккаунт попадают в ключ только хешами SHA-256.ProcessedMessageRetention— срок хранения отметки «письмо обработано» (по умолчанию 24 часа).
Срок жизни записей задаёт сама сущность: токен и корреляция живут ровно до своего
ExpiresAt, координаты подсказки — до истечения самой долгой возможной транзакции плюс запас на
публикацию события истечения (координаты потребляет это событие; публикует его фоновая очистка после
истечения транзакции, если раньше его не опубликовал ответ, пришедший после срока). Единственное исключение — ProcessedMessageRetention:
у отметки о письме собственной сущности нет. Состояние страницы на телефоне живёт до истечения её
транзакции плюс время, которое хранится завершённая транзакция.Veriqa:ChannelStores:Redis:ConnectionString;
без него они остаются в памяти процесса. Параметры выше — ключи той же секции под теми же именами:
Veriqa:ChannelStores:Redis:LinkHandleKeyPrefix, Veriqa:ChannelStores:Redis:ProcessedMessageRetention
(hh:mm:ss) и так далее; строка подключения — ConnectionString, а не Configuration. При хранилище
транзакций на Redis оба делят одно соединение: задайте в обоих ключах одну и ту же строку
подключения. Другая строка останавливает старт сообщением, называющим оба ключа. У readiness
появляется проверка redis-channel-stores, если тот же Redis уже не проверяет другая проверка, а
Redis, недоступный на старте, останавливает контейнер (если строка подключения
не задаёт abortConnect=false: тогда контейнер поднимается, а сбой видит только readiness).
Канальные идентичности: в поставке не хранятся
ПортIChannelIdentityRepository (движок транзакций) сохраняет идентичность канала —
channel_user_id, телефон, email, отображаемое имя — upsert’ом по тройке (TenantId,
ChannelType, ChannelUserId). Контракт не предусматривает ни удаления, ни TTL: запись хранится
бессрочно.
Реализации этого порта в поставке нет, и Veriqa её не регистрирует. Без вашей регистрации не
сохраняется ничего, и вход при этом работает: снапшот разрешённой идентичности хранится вместе с транзакцией.
Хранить эти данные (PII, бессрочно) — ваше решение; зарегистрируйте свою реализацию, и каждый вход
становится upsert’ом:
Program.cs
Scoped-реализация над DbContext безопасна наравне с Singleton. Пример
in-memory реализации есть в samples/dotnet/inproc/login.
Полная картина «что где лежит и сколько живёт», включая этот порт, — в
Безопасности и обработке данных.
Хранилище собранных claims
Когда входу не хватает claim, который приложение требует, Veriqa добирает его сама — телефон запросом в канале, email кодом или ссылкой, поле своей формой (см. Сбор дополнительных claims). Без хранилища всё это хранится столько же, сколько транзакция, и следующий вход спрашивает снова. Хранилище собранных claims держит это по тенанту иsub: что собрала Veriqa, от каких Optional claims пользователь отказался, время
последнего входа, прочитавшего записи, и sub, который получило приложение, если его claims mapper
этот sub поменял. Значения, которые даёт сам канал, не сохраняются.
Пока вы его не включили, не хранится ничего. На отдельном сервере это один ключ,
Veriqa:CollectedClaims:Store:Enabled:
appsettings.json
Enabled: true без
Veriqa:TransactionEngine:Store:ConnectionString останавливает старт с сообщением, называющим оба
ключа, — как и Enabled: true при Veriqa:TransactionEngine:Store:Provider = Redis: у Redis нет
реляционной базы, где можно было бы разместить хранилище.
Во встроенном режиме хранилище — отдельная регистрация, и базу для него выбираете вы:
Program.cs
CollectedClaimsDbContext,
и применяются на старте так же, как миграции транзакций. Не убирайте
MigrationsHistoryTable(CollectedClaimsMigrationDefaults.MigrationsHistoryTable): хранилище может
делить базу с транзакциями, и общая таблица истории смешала бы два набора миграций. Свою реализацию
ICollectedClaimsStore подключает te.UseCollectedClaimsStore<TStore>() — и она получает всё
описанное ниже: эндпоинт, вызов хоста и автоудаление — ровно как реализация на EF Core.
Удаление по sub
Когда пользователь удалил учётную запись или потребовал стереть данные, вы как оператор персональных
данных удаляете всё, что хранилище о нём держит, — все его записи и выданные приложениям sub. Операция одна, способа вызова два, и оба идемпотентны: удаление sub, по которому ничего нет, считается успешным.
Серверный эндпоинт — для приложения, которое не встраивает Veriqa как .NET-библиотеку:
AllowClientCredentials и AllowCollectedClaimsDeletion (см. Клиенты;
флаг без AllowClientCredentials останавливает старт), токен — по grant_type=client_credentials,
как у API подтверждений. sub передаётся в той
форме, в какой его получило приложение: названное в client_id, а без параметра — вызывающий
клиент. sub, выданные этому приложению, ищутся в тенанте вызывающего; не найденный среди них
sub считается ядровым. Своего ограничения частоты у эндпоинта нет — выдавайте флаг только одному
своему серверному клиенту.
Вызов хоста — для приложения, в которое Veriqa встроена:
ICollectedClaimsDeletion регистрируется вместе с хранилищем; без хранилища его в контейнере нет.
Каждое удаление пишет запись CollectedClaimsDeleted в журнал аудита,
когда журнал включён: действующее лицо — вызывающий клиент для эндпоинта и system для вызова хоста и
автоудаления; цель — маскированный ядровый sub; в метаданных — тенант, клиент и основание:
endpoint, host_call или retention. Значения claims в запись не попадают. С выключенным журналом
удаление работает и ничего не пишет. После удаления следующий вход этого пользователя идёт как
первый: Veriqa снова спрашивает недостающее, включая Optional claim, от которого он раньше
отказался.
Удаление неиспользуемых записей
Записиsub, по которому никто не входил заданное число дней, можно удалять автоматически. Срок
отсчитывается от последнего входа, прочитавшего записи, а не от времени сбора значения. По
умолчанию выключено:
appsettings.json
0 выключает; отрицательное значение останавливает старт. На уровне тенанта член
ClaimCompletionCollectedClaimsRetentionDays замещает глобальное значение, так что очистку можно
включить для одного тенанта (ClaimCompletion.CollectedClaimsRetentionDays в
каталоге объявлений). Очистка идёт на
старте и дальше раз в час, пакетами по 100; вход, прочитавший записи между выборкой и удалением,
их сохраняет. Каждый удалённый sub получает запись аудита с основанием retention.
База OpenIddict
Клиенты и токены OIDC-сервера хранятся отдельно и настраиваются секциейVeriqa:OpenIddict:Database:
appsettings.json
Коннектор на одном инстансе без базы данных
Когда Veriqa подключена к другому провайдеру идентичности — Keycloak или вашему собственному, — она участвует только во входе: запрос авторизации, подтверждение в канале, обмен кода и сразу за ним вызов userinfo. Сессия и её refresh-токены дальше принадлежат тому провайдеру, а учётных записей пользователей Veriqa не хранит и так (см. Канальные идентичности). Такое развёртывание может работать одним инстансом со всеми хранилищами в памяти. В self-hosted режиме:appsettings.json
Veriqa:TransactionEngine:Store:ConnectionStringне задавайте — транзакции остаются в памяти;Veriqa:Logging:Modeоставьте по умолчанию или задайте любым, кромеAudit;- клиента объявите без
AllowRefreshTokens(по умолчанию выключен) и безoffline_access.
authServer.UseInMemoryOpenIddictStore() и
te.UseInMemoryStore(). Хост стартует с Warning о волатильном хранилище OpenIddict — для этого
варианта это ожидаемо.
Чего стоит перезапуск:
Развёртывание, обновление образа и перезапуск контейнера — всё это перезапуски: после каждого
происходит всё, что описано в таблице.
Другая СУБД и правка модели
Standalone-образ несёт PostgreSQL и SQL Server (и Redis для хранилища транзакций). Всё остальное — выбор вашего хоста во встроенном режиме, правки Veriqa для этого не нужны.Своя сборка миграций
Четыре контекста EF Core публичны:TransactionDbContext
(Veriqa.Core.TransactionEngine.Store.EfCore), CollectedClaimsDbContext
(Veriqa.Core.TransactionEngine.CollectedClaims.EfCore), AuditDbContext
(Veriqa.Core.AuditTrail.Store.EfCore) и OpenIddictDbContext (Veriqa.Core.AuthServer.Data). Это якоря для миграций, а не API доступа к
данным — таблицы остаются внутренними. Для СУБД, под которую Veriqa миграций не поставляет:
- Создайте библиотеку классов со ссылками на ваш провайдер EF Core,
Microsoft.EntityFrameworkCore.Designи пакет, в котором лежит контекст. - Добавьте
IDesignTimeDbContextFactory<T>на каждый контекст — через неёdotnet efстроит контекст. - Выполните
dotnet ef migrations add Initial --project <ваша библиотека> --context <контекст>и назовите библиотеку вMigrationsAssembly(...)в рантайме.
TransactionDbContextDesignTimeFactory.cs
AuditDbContext рядом с MigrationsAssembly(...) добавьте
MigrationsHistoryTable(AuditMigrationDefaults.MigrationsHistoryTable) — и в фабрике, и в рантайме;
для CollectedClaimsDbContext так же —
MigrationsHistoryTable(CollectedClaimsMigrationDefaults.MigrationsHistoryTable).
Правка модели
Схема, collation, тип колонки — модель меняется штатнымIModelCustomizer EF Core, а не правкой
контекстов Veriqa. Унаследуйтесь от RelationalModelCustomizer:
VeriqaModelCustomizer.cs
ReplaceService<IModelCustomizer, …>() в том же делегате, что выбирает
провайдер:
Program.cs
Публикация событий транзакций
In-process доставка вITransactionEventHandler (см.
Настройку) — часть движка, отдельного
вызова не требует: журнал аудита, push статуса на страницу входа и очистка подсказок получают
события в любой конфигурации. Публикация событий наружу — отдельный и дополняющий выбор
транспорта, тоже в ConfigureTransactionEngine:
Program.cs
RabbitMqEventPublisherOptions: ConnectionString (обязателен, amqp://…), ExchangeName
(по умолчанию veriqa.transactions), плюс параметры очереди и переподключения (QueueCapacity,
MaxReconnectAttempts, ReconnectBaseDelaySeconds).
В standalone-образе публикатор включается ключом Veriqa:Events:RabbitMq:ConnectionString;
остальные параметры — ключи той же секции под теми же именами (Veriqa:Events:RabbitMq:ExchangeName и
так далее). Без строки подключения публикатора нет. С ней у readiness появляется проверка
rabbitmq-events, а брокер, недоступный на старте, останавливает контейнер.
Надёжность того, что уходит из процесса, равна надёжности выбранной шины — ни больше ни меньше.
Своей гарантии доставки поверх транспорта Veriqa не строит: на in-process канале событие может
потеряться при аварии, а с очередью сообщений доставка ровно такая, какую даёт эта очередь.
Дальше
Подготовка к продакшну
Миграции, секреты, ротация ключей.
Настройка и кастомизация
Каналы, дизайн, локализация, точки расширения.