Sparkdo.Configuration 0.0.1-preview.3

Sparkdo.Runtime.Configuration

Sparkdo.Runtime.Configuration 是 Sparkdo 运行时输入的框架无关配置边界。它把调用方已经获得的配置值或机密引用，组织成可验证、不可变且顺序确定的 RuntimeConfigurationSnapshot，并可转换为 CatalogInputs 交给运行时。

该包不读取文件、环境变量或远程配置中心，也不依赖 Microsoft.Extensions.Configuration、依赖注入或宿主模型。它适合以下场景：

• 使用自定义配置系统、命令行参数、数据库、远程控制面或测试夹具为运行时准备输入；
• 希望在接入宿主前先校验输入路由、输入来源、JSON 载荷或机密引用；
• 需要将同一批输入以稳定顺序交给多个运行时组件。

使用 IConfiguration 的应用应优先使用相邻包 Sparkdo.Runtime.Configuration.MicrosoftExtensions；该适配包最终也会生成本包定义的快照。

安装

从 NuGet 引用：

dotnet add package Sparkdo.Runtime.Configuration

在同一仓库中开发时，可直接引用项目：

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

本包会传递引用 Sparkdo.Runtime.Contracts，其中定义了 CapabilityInputValue、CatalogInputs、CapabilityInputRoute、SchemaVersion 等共享模型。

最小可用接线

下面的示例手工构造一个环境来源的 JSON 输入。调用方负责从自己的配置来源取得原始值；CanonicalPayload.FromJson 会把 JSON 转为规范化 UTF-8 载荷。

using Sparkdo.Runtime;
using Sparkdo.Runtime.Configuration;

var route = new CapabilityInputRoute(
    new CapabilityId("orders.service"),
    new InputId("settings"));

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

var value = new CapabilityInputValue(
    route,
    new InputKindId("json"),
    new SchemaVersion(1, 0),
    InputSourceScope.Environment,
    CanonicalPayload.FromJson("{\"region\":\"cn\",\"enabled\":true}"),
    null,
    origin);

RuntimeConfigurationSnapshot snapshot = new RuntimeConfigurationBuilder()
    .Add(value)
    .Build();

CatalogInputs inputs = snapshot.ToCatalogInputs();

RuntimeConfigurationBuilder.Build() 先按 CapabilityId、再按 InputId 的 ordinal 顺序排列输入，因此同一组不同添加顺序的值会得到确定的快照顺序。

核心模型与 API

RuntimeConfigurationBinding

RuntimeConfigurationBinding 描述一个配置输入的声明，不包含配置正文。它由以下字段组成：

• Route：由 CapabilityInputRoute 组成的 Capability 与 Input 路由；
• Kind：输入种类，例如 new InputKindId("json")；
• Schema：输入的 SchemaVersion；
• Source：Application、Host、Environment 或 SecretProvider；
• Key：调用方配置系统中的键名；核心包不解释该键；
• Required：调用方或适配器缺少该输入时应失败还是省略；
• Origin：输入来源身份和配置适配器身份。

核心包本身不会用 RuntimeConfigurationBinding 读取配置；该类型用于让不同适配器使用统一的输入声明。Sparkdo.Runtime.Configuration.MicrosoftExtensions 是其现成实现之一。

RuntimeConfigurationBuilder

• Add(CapabilityInputValue value)：加入一个输入值。若同一批次已有相同路由，立即抛出 ArgumentException。
• Build()：创建并验证 RuntimeConfigurationSnapshot。

构造器可链式调用，构建之后的 RuntimeConfigurationSnapshot.Values 是 ImmutableArray<CapabilityInputValue>。不要在构建后依赖外部集合的可变性来修改快照。

RuntimeConfigurationSnapshot

RuntimeConfigurationSnapshot 是已验证的不可变边界：

• Values 返回快照中的输入值；
• ToCatalogInputs() 将它们包装成运行时使用的 CatalogInputs。

如果已经有按路由排序的 ImmutableArray<CapabilityInputValue>，也可以直接构造 RuntimeConfigurationSnapshot。这种方式同样会执行全部校验，不能绕过输入边界。

Payload 与机密引用

每个 CapabilityInputValue 必须且只能选择以下一个分支：

• Payload：普通输入，使用 CanonicalPayload 保存规范化 JSON 等字节；其 Source 不能是 SecretProvider。
• Secret：机密引用，使用 SecretReference(Store, Key, Version, Access)；其 Source 必须是 SecretProvider。

本包不会解析 SecretReference.Key，也不访问机密存储，更不会把机密正文转换为 Payload。这使调用方能够将机密保留在专用存储中，只把存储标识、引用键、版本和最小访问策略交给运行时模型。

构造机密引用时，访问策略中的操作必须非空、唯一且按 ordinal 顺序排列：

using System.Collections.Immutable;
using Sparkdo.Runtime;

var secret = new SecretReference(
    new SecretStoreId("enterprise-vault"),
    "orders/api-token",
    "2026-08",
    new SecretAccessPolicy(ImmutableArray.Create("read")));

将此引用放入 CapabilityInputValue 时，Payload 必须为 null，Source 必须为 InputSourceScope.SecretProvider。

校验与失败语义

Build() 和 RuntimeConfigurationSnapshot 构造函数会拒绝不完整或歧义的输入。主要规则包括：

• 输入集合、元素和 CanonicalPayload.Utf8 必须已初始化；
• 路由、输入种类、来源身份、适配器 ID 和机密存储 ID 必须是规范化且合法的逻辑 ID；逻辑 ID 仅允许小写 ASCII 字母、数字、.、-、_，不能以非字母数字字符开头或结尾，不能包含连续的 ..；
• 输入路由必须唯一，并已按 CapabilityId/InputId 的 ordinal 顺序排列；
• schema 主版本与次版本必须非负，来源枚举值必须有效；
• CatalogInputOrigin、机密引用键/版本和访问策略必须有效；
• Payload 与 Secret 只能二选一，且必须与 Source 匹配。

违反上述不变量会抛出 ArgumentException。Add 的重复路由也会抛出 ArgumentException。这些错误表示配置输入无效，应在应用启动或重载边界处理，而不是继续使用部分输入。

安全边界

此包是值对象和校验层，不实施配置权限、密钥轮换、加密、审计或机密存储访问。生产调用方仍需负责：

• 仅从受信任来源取得 JSON 载荷与机密引用；
• 不记录 Payload、SecretReference.Key 或由其派生的机密信息；
• 依照最小权限原则构造 SecretAccessPolicy；
• 在将 CatalogInputs 交给运行时前，确认 Route、Kind、Schema 与目标 Catalog 的输入定义一致。

包内不写日志，也不读取外部状态；因此它不能代替宿主侧的访问控制与审计措施。

与相邻包的关系

验证

在仓库根目录执行以下命令可构建本项目并运行覆盖配置边界的规格测试：

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

第二条命令中的测试同时覆盖 Microsoft.Extensions 配置适配行为；它不是该包的传递依赖。