Sparkdo.Runtime.Inspection 0.0.1-preview.3

Sparkdo.Runtime.Inspection

Sparkdo.Runtime.Inspection 为进程内 Runtime 提供只读检查投影。它将已捕获的运行时状态表示为 RuntimeInspection，包含目录修订、可用性、活动快照处置状态、宿主绑定修订、受控设置、能力状态、依赖图和近期 Observation。

该项目不执行启动、协调、重载、停止、导出获取或 Host Binding 修改。它不暴露 Provider、Export、机密正文或 Host Binding 对象本身，只提供适合运维诊断和受控管理端点消费的值投影。

何时选用

在以下场景选用本项目：

• 需要在同一进程内读取已经发布的 Runtime 状态。
• 需要向健康检查、诊断端点或受控运维界面提供能力、依赖和近期 Observation 的快照。
• 需要从 RuntimePlan 取得独立的 DependencyGraphView 副本。
• 希望诊断代码只依赖 IRuntimeInspector 或 IPlanInspector，而不是直接访问 Runtime 内部状态。

在以下场景不要选用本项目：

• 需要修改 Catalog、重载能力、打开 Scope、获取 Export 或停止 Runtime；这些操作应通过 Runtime 的正式生命周期 API 执行。
• 需要跨进程、远程或代理 Runtime 的详情；本项目只对本进程的实际 RuntimeEngine 提供详细投影。
• 需要持续订阅状态变化；Inspect() 返回一次性快照，不是事件流，也不会在返回后保持锁定。

引用方式

Sparkdo.Runtime.Inspection 提供可发布的只读检查包，也支持同仓项目引用。隔离 feed consumer 使用 PackageReference 验证发布资产；源码联调也可以使用项目引用：

<ItemGroup>
  <ProjectReference Include="path/to/Sparkdo.Runtime/Sparkdo.Runtime.csproj" />
  <ProjectReference Include="path/to/Sparkdo.Runtime.Inspection/Sparkdo.Runtime.Inspection.csproj" />
</ItemGroup>

发布包消费者可将第二项替换为 PackageReference Include="Sparkdo.Runtime.Inspection"，并从批准的隔离 feed 解析与 Runtime 完全一致的版本。

项目目标框架为 net10.0，直接依赖 Sparkdo.Runtime.Contracts 与 Sparkdo.Runtime。生产应用应将它与产生实际 IRuntimeRegistrationTable 的组合项目一起构建。

下方可运行示例额外使用 Sparkdo.Runtime.Testing 的静态注册表，因此还需要：

<ProjectReference Include="path/to/Sparkdo.Runtime.Testing/Sparkdo.Runtime.Testing.csproj" />

最小可运行示例

该示例先创建 Runtime，再发布一个 Catalog，最后读取只读投影。StaticRuntimeRegistrationTable 仅用于让示例具备完整的可运行输入；生产中请替换为应用实际的注册表和 Catalog 输入。

using Sparkdo.Runtime;
using Sparkdo.Runtime.Inspection;
using Sparkdo.Runtime.Testing;

var registrations = StaticRuntimeRegistrationTable.Create();
var creation = RuntimeFactory.Create(registrations);
if (!creation.Succeeded || creation.Runtime is not { } runtime)
{
    Console.Error.WriteLine(creation.Reason?.Code ?? "runtime.creation.rejected");
    return 1;
}

await using var lifetime = (IAsyncDisposable)runtime;

var catalogResult = registrations.CreateCatalog(CatalogInputs.Empty);
if (!catalogResult.Succeeded || catalogResult.Catalog is not { } catalog)
{
    Console.Error.WriteLine(catalogResult.Reason?.Code ?? "runtime.catalog.rejected");
    return 2;
}

var reconciliation = await runtime.SubmitReconciliationAsync(
    new ReconciliationRequest(catalog));
if (reconciliation.Outcome != ReconciliationOutcome.Published)
{
    Console.Error.WriteLine(reconciliation.Reason?.Code ?? "runtime.reconciliation.rejected");
    return 3;
}

var inspection = runtime.CreateInspector().Inspect();
Console.WriteLine($"可用性：{inspection.Availability}");
Console.WriteLine($"目录修订：{inspection.Revision}");
Console.WriteLine($"能力数量：{inspection.Capabilities.Length}");
Console.WriteLine($"依赖边数量：{inspection.Dependencies.Edges.Length}");

return inspection.Availability == RuntimeAvailability.Available ? 0 : 4;

公共 API 与只读边界

应用通常通过扩展方法创建检查器：

IRuntimeInspector inspector = runtime.CreateInspector();
RuntimeInspection inspection = inspector.Inspect();

也可以直接构造 RuntimeInspector。它实现两个职责明确的接口：

RuntimeInspection 的字段含义如下：

不可用状态与失败关闭

Inspect() 不把“尚未有可读快照”视为异常。以下情况会返回失败关闭的空投影：

• IRuntime 不是实际 RuntimeEngine，例如代理、装饰器或远程实现。
• Runtime 尚未成功发布活动 Snapshot。
• Runtime 处于无活动 Snapshot 的不可用状态。

此时结果具有 Availability == RuntimeAvailability.Unavailable、Snapshot == ActiveSnapshotDisposition.NoActiveSnapshot、Revision == null 和 HostBindings == null；能力、依赖和近期 Observation 均为空，Settings 的数值均为零。调用方应把该结果作为可预期的运行状态处理，并在诊断端点中明确呈现，而不是假定所有检查请求都有可用数据。

详细投影只在 RuntimeEngine.CaptureInspection() 的一次内部捕获基础上生成。捕获完成后 Runtime 仍可并发协调或停止，因此不能将一次 Inspect() 的结果当作跨多个后续调用的事务一致性保证。

生产注意事项

• 将检查投影限制在进程内受信任组件，或为诊断端点实施认证、授权和字段脱敏；能力标识、实例标识、版本、依赖关系和 Observation 都可能暴露部署拓扑。
• 不要用 RuntimeInspection 驱动写操作或替代正式生命周期结果。读取到的快照可能在下一次协调后失效。
• 对 Unavailable、空数组和可空修订做显式分支，避免把运行时尚未发布或已经停止误报为程序故障。
• 若应用通过包装器暴露 IRuntime，不要期待该包装器得到详细投影；应在拥有实际 Runtime 的组件内创建检查器。
• 需要外部监控时，使用投影构造受控 DTO；不要直接把整个对象图无筛选地写入日志、缓存或公开 HTTP 响应。

验证

验证同仓 Inspection 规格：

dotnet test ./src/runtime/test/Sparkdo.Runtime.Specification.Tests/Sparkdo.Runtime.Specification.Tests.csproj `
  --configuration Release `
  --filter "FullyQualifiedName~RuntimeInspectionTests"

验证引用该项目的应用：

dotnet build --configuration Release
dotnet run --configuration Release