Sparkdo.Configuration.MicrosoftExtensions 0.0.1-preview.3

Sparkdo.Runtime.Configuration.MicrosoftExtensions

Sparkdo.Runtime.Configuration.MicrosoftExtensions 将 Microsoft.Extensions.Configuration.IConfiguration 中显式声明的键绑定为 Sparkdo 运行时输入。它读取配置值、将 JSON 规范化为 CanonicalPayload，并返回 RuntimeConfigurationSnapshot 或 CatalogInputs。

当应用已经使用 ASP.NET Core、Generic Host、ConfigurationBuilder 或任意 IConfiguration 提供程序，并且需要把配置接入 Sparkdo Runtime 时使用此包。它不是通用对象绑定器：每个运行时输入都必须通过 RuntimeConfigurationBinding 明确声明路由、来源、schema、配置键和来源身份。

对于不使用 IConfiguration 的应用，请直接使用 Sparkdo.Runtime.Configuration 构造输入快照。

安装

从 NuGet 引用适配包：

dotnet add package Sparkdo.Runtime.Configuration.MicrosoftExtensions

如果新项目需要从 appsettings.json 创建 IConfiguration，还需要相应配置提供程序，例如：

dotnet add package Microsoft.Extensions.Configuration.Json

在同一仓库中开发时，引用本项目即可；它会传递引用核心配置包和运行时契约包：

<ItemGroup>
  <ProjectReference Include="..\Sparkdo.Runtime.Configuration.MicrosoftExtensions\Sparkdo.Runtime.Configuration.MicrosoftExtensions.csproj" />
</ItemGroup>

最小可用接线

配置文件中的运行时输入必须是 JSON 文本，而不是供 Bind 自动映射的任意对象。下面的 appsettings.json 将 JSON 作为字符串保存：

{
  "Sparkdo": {
    "Orders": {
      "Settings": "{\"enabled\":true,\"region\":\"cn\"}"
    }
  }
}

创建 IConfiguration，声明输入绑定并读取快照：

using Microsoft.Extensions.Configuration;
using Sparkdo.Runtime;
using Sparkdo.Runtime.Configuration;
using Sparkdo.Runtime.Configuration.MicrosoftExtensions;

IConfiguration configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: false)
    .Build();

var binding = new RuntimeConfigurationBinding(
    new CapabilityInputRoute(
        new CapabilityId("orders.service"),
        new InputId("settings")),
    new InputKindId("json"),
    new SchemaVersion(1, 0),
    InputSourceScope.Environment,
    "Sparkdo:Orders:Settings",
    required: true,
    new CatalogInputOrigin(
        new SourceIdentity(SourceKind.Application, "orders.application", "1.0.0"),
        "orders.configuration",
        "1.0.0"));

RuntimeConfigurationSnapshot snapshot =
    configuration.BindSparkdoRuntime([binding]);

CatalogInputs inputs = snapshot.ToCatalogInputs();

对于不需要检查已注册 Catalog 的应用，也可直接调用：

CatalogInputs inputs = configuration.BindSparkdoRuntimeInputs([binding]);

绑定器读取 binding.Key 对应的单个字符串值，验证其为 JSON 后将其规范化。对象属性顺序、空白等非语义差异不会保留在最终 CanonicalPayload 中。

声明模型

RuntimeConfigurationBinding 来自 Sparkdo.Runtime.Configuration，其字段含义如下：

两个带 Catalog 参数的重载会额外检查路由是否存在、输入种类和 schema 是否匹配、以及 Source 是否在输入定义的允许来源中：

RuntimeConfigurationSnapshot snapshot =
    configuration.BindSparkdoRuntime(catalog, [binding]);

在生产宿主中，当 Catalog 已可用时应使用该重载，以便在运行时启动前拒绝与注册输入定义不一致的配置。

可用 API

同步 API 仅适用于普通 JSON 输入：

• BindSparkdoRuntime(this IConfiguration, IEnumerable<RuntimeConfigurationBinding>)
• BindSparkdoRuntime(this IConfiguration, Catalog, IEnumerable<RuntimeConfigurationBinding>)
• BindSparkdoRuntimeInputs(this IConfiguration, IEnumerable<RuntimeConfigurationBinding>)
• BindSparkdoRuntimeInputs(this IConfiguration, Catalog, IEnumerable<RuntimeConfigurationBinding>)

异步 API 用于包含 InputSourceScope.SecretProvider 的输入；它们都接收机密策略、引用解析器和调用方取消令牌：

• BindSparkdoRuntimeAsync(...)
• BindSparkdoRuntimeInputsAsync(...)

同步入口若遇到 SecretProvider 输入会失败。不要把机密输入降级为普通 JSON 配置来绕过这一限制。

SecretProvider 绑定

机密配置不读取 IConfiguration[binding.Key] 的值。异步入口要求为每个 SecretProvider 路由声明一个 RuntimeConfigurationSecretBinding，并提供 IRuntimeConfigurationSecretReferenceResolver。解析器只能返回目标机密存储中的引用键，不能返回机密正文。

using System.Collections.Immutable;
using System.Threading;
using Sparkdo.Runtime;
using Sparkdo.Runtime.Configuration;
using Sparkdo.Runtime.Configuration.MicrosoftExtensions;

var origin = new CatalogInputOrigin(
    new SourceIdentity(SourceKind.Application, "orders.application", "1.0.0"),
    "orders.configuration",
    "1.0.0");

var secretInput = new RuntimeConfigurationBinding(
    new CapabilityInputRoute(
        new CapabilityId("orders.service"),
        new InputId("api-token")),
    new InputKindId("json"),
    new SchemaVersion(1, 0),
    InputSourceScope.SecretProvider,
    "Sparkdo:Orders:ApiToken",
    required: true,
    origin);

var secretPolicy = new RuntimeConfigurationSecretBinding(
    secretInput.Route,
    new SecretStoreId("enterprise-vault"),
    "2026-08",
    new SecretAccessPolicy(ImmutableArray.Create("read")));

CancellationToken cancellationToken = CancellationToken.None;

CatalogInputs inputs = await configuration.BindSparkdoRuntimeInputsAsync(
    [secretInput],
    [secretPolicy],
    new VaultReferenceResolver(),
    cancellationToken);

sealed class VaultReferenceResolver : IRuntimeConfigurationSecretReferenceResolver
{
    public ValueTask<string?> ResolveSecretKeyAsync(
        RuntimeConfigurationSecretReferenceRequest request,
        CancellationToken cancellationToken)
    {
        cancellationToken.ThrowIfCancellationRequested();

        // 只返回机密存储中的引用键，绝不返回机密正文。
        return ValueTask.FromResult<string?>("orders/api-token");
    }
}

解析器收到的 RuntimeConfigurationSecretReferenceRequest 只包含 Binding 与 SecretBinding 元数据。适配器把成功解析的键写入 SecretReference.Key，并让 CapabilityInputValue.Payload 保持为 null。

若可选机密缺失，解析器可以返回 null 或空白值；必需输入会失败，非必需输入会被省略。每个 SecretProvider 路由必须恰好有一个对应的机密策略，策略中的操作必须非空、唯一且按 ordinal 顺序排列。

校验、资源边界与失败语义

适配器在读取前校验绑定，在读取后校验输入快照。它会失败关闭，而不会返回部分或未验证的结果。主要边界如下：

• 最多 256 个配置绑定，且每个路由只能出现一次；
• 配置键最长 512 个字符，路由和身份 ID 必须是规范化的小写逻辑 ID；
• 仅支持 json 输入种类；JSON 采用严格 UTF-8，并会被规范化；
• 单项 JSON 原始字节最多 64 KiB，单批总量最多 1 MiB，最大嵌套深度为 64，属性数最多 2048，数组项数最多 4096；
• Secret 引用键最多 1024 个 UTF-8 字节，不能包含控制字符；
• 读取过程中会在前后检查 IConfiguration.GetReloadToken()，最多尝试三次获得一致快照；
• Secret 引用解析在五秒预算内完成；调用方取消会传递给解析器。

下列情况通常抛出 InvalidOperationException：缺少必需键、JSON 无效或超限、绑定或机密策略无效、路由重复、与 Catalog 不匹配、配置重载导致无法取得一致快照、解析器失败或超时。调用方取消会以 OperationCanceledException 传播。传入 null 的必要参数会抛出 ArgumentNullException。

错误信息用于诊断类别与配置键，不会包含 JSON 正文、机密引用键或解析器抛出的原始异常消息。调用方仍应将异常视为可能携带业务元数据的诊断信息，并按本应用的日志脱敏策略处理。

安全边界

该包负责将受控配置元数据转为运行时输入，不负责认证、授权、密钥读取、轮换或审计。生产实现必须：

• 让 IRuntimeConfigurationSecretReferenceResolver 从受信任控制面解析引用，并在其内部实施权限校验；
• 让解析器返回存储引用键，不返回机密正文，也不读取或记录 IConfiguration 中可能存在的机密正文；
• 为每个机密输入指定最小化的 SecretAccessPolicy；
• 不在应用日志、遥测、异常包装或调试输出中写入 JSON 正文和 SecretReference.Key；
• 在 Catalog 已注册时使用带 Catalog 的重载，以阻止错误路由、来源或 schema 进入运行时。

SecretProvider 的设计只保证适配器不会从 IConfiguration 读取该路由对应的正文。它无法验证解析器返回的字符串是否实际为引用键，因此解析器实现是机密边界的一部分。

与相邻包的关系

验证

在仓库根目录执行以下命令可构建适配包并运行覆盖 JSON、重载一致性和 SecretProvider 边界的规格测试：

dotnet build src/runtime/src/Sparkdo.Runtime.Configuration.MicrosoftExtensions/Sparkdo.Runtime.Configuration.MicrosoftExtensions.csproj -c Release
dotnet test src/runtime/test/Sparkdo.Runtime.Specification.Tests/Sparkdo.Runtime.Specification.Tests.csproj --filter FullyQualifiedName~RuntimeConfigurationTests

这些命令用于本地验证；部署时仍应针对实际的配置提供程序、Catalog 和机密解析器执行集成测试。