Свои ключи конфигурации

​

Уровни приложения и ui_config открыты расширениям

• Уровень приложения — элемент массива Veriqa:OpenIddict:Clients в конфигурации хоста. Он читается как узел, по пути: любой член, который вы впишете в запись клиента, читается по адресу, объявленному вашим ключом, независимо от того, есть ли у OidcClientOptions свойство с таким именем.
• Уровень ui_config — динамическая запись. Неизвестные ей поля сохраняются при чтении и записи через [JsonExtensionData], поэтому ваше поле переживает каждый цикл чтения-записи записи.

​

1. Свой каталог

using Veriqa.Core.Configuration;

public static class AcmeConfigKeys
{
    // Инициализируется раньше объявлений, которые его наполняют, — в этом порядке идут инициализаторы.
    private static readonly ConfigKeyCatalog Declared = new();

    /// <summary>Секция конфигурации хоста, в которой живёт уровень ядра этих ключей.</summary>
    public const string CoreSectionName = "Acme:Approvals";

    public static ConfigKey<int> MaxAttempts { get; } = Declared
        .Of<int>("Acme.Approvals.MaxAttempts")
        .At(ConfigLevel.Core, CoreSectionName + ":MaxAttempts")
        .At(ConfigLevel.Application, "AcmeMaxAttempts")
        .At(ConfigLevel.UiConfig, "acme_max_attempts")
        .Default(3)
        .Declare();

    public static ConfigKey<int> WindowSeconds { get; } = Declared
        .Of<int>("Acme.Approvals.WindowSeconds")
        .At(ConfigLevel.Core, CoreSectionName + ":WindowSeconds")
        .At(ConfigLevel.Application, "AcmeWindowSeconds")
        .Default(60)
        .Declare();

    // То, что читает регистратор развёртывания.
    public static ConfigKeyCatalog Catalog => Declared;
}

​

Адреса по уровням

​

2. Зарегистрируйте каталог из своей композиции

public static IServiceCollection AddAcmeApprovals(
    this IServiceCollection services,
    IConfiguration configuration)
{
    // Ваши ключи едут вместе с вашей композицией — единственный момент, который работает для
    // сборки, которую не может назвать ни один корень композиции.
    services.AddVeriqaConfigKeyCatalogs(configuration, AcmeConfigKeys.Catalog);

    // ... остальные ваши регистрации
    return services;
}

builder.Services.AddVeriqaAuthServer(builder.Configuration);
builder.Services.AddAcmeApprovals(builder.Configuration);

• Он идемпотентен, покаталожно. Каталог, который контейнер уже держит, пропускается в одиночку. И композиция, вызванная дважды, и две композиции, назвавшие один каталог, оставляют ровно одну регистрацию.
• Он ничего не подавляет. Ваш вызов регистрирует названное вами и пропускает уже имеющееся — ни один владелец не может выбить каталоги другого, и ни один не регистрируется дважды.
• Порядок не важен. Каждый регистратор объявляет свои ключи до того, как зарегистрирован первый биндинг, поэтому от того, отработала ваша композиция раньше или позже композиции ядра, не зависит, найдёт ли биндинг свой ключ.

​

3. Прочитайте значение

public sealed class AcmeApprovalGate(IConfigurationResolver resolver)
{
    public async ValueTask<int> MaxAttemptsAsync(
        string? applicationId,
        CancellationToken cancellationToken)
    {
        var resolved = await resolver.ResolveAsync(
            AcmeConfigKeys.MaxAttempts,
            ResolutionContext.Of(tenantId: null, applicationId, uiConfigSelector: null),
            ConfigDimensionValues.None,
            cancellationToken);

        // resolved.SourceLevel говорит, какой уровень ответил, — полезно в собственной диагностике.
        return resolved.Value;
    }
}

using var scope = new ConfigResolutionScope(ResolutionContext.ForTenant(tenantId));

var attempts = await resolver.ResolveAsync(
    AcmeConfigKeys.MaxAttempts, scope, ConfigDimensionValues.None, cancellationToken);
var window = await resolver.ResolveAsync(
    AcmeConfigKeys.WindowSeconds, scope, ConfigDimensionValues.None, cancellationToken);

​

4. Что может заявить объявление

public static ConfigKey<int> MaxAttempts { get; } = Declared
    .Of<int>("Acme.Approvals.MaxAttempts")
    .At(ConfigLevel.Core, CoreSectionName + ":MaxAttempts")
    .Domain(new ConfigValueDomain<int>(
        admits: static value => value is > 0 and <= 10,
        boundary: "1…10 attempts",
        correctAt: "Acme:Approvals:MaxAttempts",
        onRejected: ConfigValueRejectionPolicy.FailStart))
    .Default(3)
    .Declare();

​

5. Проверьте, что объявление подхватилось

Configuration schema declares 68 keys: Acme.Approvals.MaxAttempts, AuthPage.Instruction, ...

Configuration key Acme.Approvals.MaxAttempts (Value): levels UiConfig, Application, Core, gated none, dimensions none, cache none, domain 1…10 attempts.

​

Пример в поставляемом коде

​

Где этот путь нужен

• Свой канальный адаптер — его креденшелы, тексты и лимиты по тенантам. Руководство по канальному адаптеру резолвит настройки через IConfigurationResolver; эта страница — про то, откуда берётся резолвимый им ключ.
• Сток аудита, экспортёр метрик, исходящий шлюз — всё, что поставляется отдельной сборкой и что оператору нужно настраивать по приложениям или по тенантам.
• Свой движок политик ограничения. Собственные правила допустимости Veriqa — внутренний контракт, и точкой расширения они не публикуются: интегратор, которому нужен другой движок политик — Rego, Cedar, собственный DSL, — поставляет такую проверку сам, и она держит свою конфигурацию на своих ключах, объявленных ровно так, как описано выше.

​

Дальше