ctx_runner 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +4 -0
- data/README.md +4 -0
- data/docs/contracts-2026-10-29.md +2 -0
- data/docs/contracts-2026-10-30.md +58 -0
- data/examples/execution.rb +1 -1
- data/examples/report.rb +1 -1
- data/lib/ctx_runner/batch.rb +23 -6
- data/lib/ctx_runner/configuration_session.rb +43 -0
- data/lib/ctx_runner/evidence.rb +16 -12
- data/lib/ctx_runner/execution.rb +2 -2
- data/lib/ctx_runner/fingerprint.rb +1 -1
- data/lib/ctx_runner/observation.rb +9 -4
- data/lib/ctx_runner/report.rb +3 -3
- data/lib/ctx_runner/snapshot.rb +4 -3
- data/lib/ctx_runner/target.rb +21 -6
- data/lib/ctx_runner/version.rb +1 -1
- data/lib/ctx_runner.rb +1 -0
- metadata +7 -5
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 309468f8b97d51e31739cf478abc3af96885ba53453366837c1b7dba56518a9f
|
|
4
|
+
data.tar.gz: 80edf1ff1d91b7de2f5cd3618346e55d1761f4c5a3940ecd2bb4eaa5af8287f6
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 72f558b4857909003298d7593574a2c913face19002e9afd980a832fc69572e3a88fa603358b9ac434a019267dc022ae93a9cc89b8736fbe68fbd964757bf048
|
|
7
|
+
data.tar.gz: 762d6e943fc55eeba9f4989098bb23804233590d3f743445782506330146d02f689b1be8b0cb0ada2ba235b5c632a4d9051a24e174f1e6c6b89dfba146a4a223
|
data/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
## 0.5.0 (2026-10-30)
|
|
6
|
+
|
|
7
|
+
- Adopt immutable `Target` identity values and typed observation sources; share `records(name)` and configuration session behavior. Schema 4 uses `target`, validates aggregate status and full identity, and rejects empty applicability proof. Reject duplicate/unrequested batch work and mismatched returned snapshots. Align fingerprint depth with Document.
|
|
8
|
+
|
|
5
9
|
## 0.4.0 (2026-10-29)
|
|
6
10
|
|
|
7
11
|
- Add composed Snapshot and public Target contracts, independent collection status, and typed UTC times. Empty requests remain not_requested.
|
data/README.md
CHANGED
|
@@ -70,3 +70,7 @@ ruby script/verify_package.rb pkg/ctx_runner-0.1.0.gem
|
|
|
70
70
|
首个版本为 0.1.0。发布流程复用 CI 制品,验证 GitHub Release 与 RubyGems 下载字节。
|
|
71
71
|
|
|
72
72
|
模块契约、破坏性迁移与版本矩阵见 [契约迁移](docs/contracts-2026-10-29.md)。
|
|
73
|
+
|
|
74
|
+
## Domain contract migration (2026-10-30)
|
|
75
|
+
|
|
76
|
+
Adopt immutable `Target` identity values and typed observation sources; share `records(name)` and configuration session behavior. Schema 4 uses `target`, validates aggregate status and full identity, and rejects empty applicability proof. Reject duplicate/unrequested batch work and mismatched returned snapshots. Align fingerprint depth with Document. See the [schema 4 migration and module contracts](https://github.com/gatework/ctx_runner/blob/main/docs/contracts-2026-10-30.md). Regenerate old collection reports and change plans; changing only their version number is not supported.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# 领域契约与 schema 4 迁移
|
|
2
|
+
|
|
3
|
+
本轮一次性切换公共接口,不保留旧字段别名。旧报告、变更计划必须重新采集或生成;仅把 schema_version 改为 4 无法补足身份、来源和聚合证据。
|
|
4
|
+
|
|
5
|
+
## 模块职责
|
|
6
|
+
|
|
7
|
+
| 模块 | 拥有的领域责任 | 不承担的责任 |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| expect-pty | PTY、IO、进程、匹配与终端恢复 | 设备健康、业务策略 |
|
|
10
|
+
| net-connector | 会话、登录、操作租约、资产与库存、邻居发现 | 公共观察结论和领域配置验收 |
|
|
11
|
+
| ctx_parser | 纯值、解析完整性、命令声明、语法注册 | 连接与报告交付 |
|
|
12
|
+
| ctx_driver | 单命令回执、来源摘要、借用会话读写 | 重连、健康判断、厂商配置策略 |
|
|
13
|
+
| ctx_runner | Target、Observation、Snapshot、采集交付、配置会话、受控执行 | 厂商语法、资产持久化 |
|
|
14
|
+
| ctx_checker | 运行事实、维度身份、健康与覆盖规则 | 配置下发 |
|
|
15
|
+
| vxlan | NX-OS、Fabric、配置依赖、可验证变更 | PTY 和公共交付状态机 |
|
|
16
|
+
| wireless-rb | AP/Radio/客户端、模板、AP 转接、无线变更 | 公共报告持久性与终端确认 |
|
|
17
|
+
| ctx_cli | 配置发现、用户输入输出、宿主入口编排 | 领域身份、采集完整性、网络会话 |
|
|
18
|
+
|
|
19
|
+
## 公共 Ruby 协议
|
|
20
|
+
|
|
21
|
+
- `Target.coerce(hash)` 接受明确的公开字段,内部使用 Symbol 键;`host` 必填,其他字段为 `platform/name/model/software_version/id`。对象深度不可变,支持 `with`、相等性、Hash 键和模式匹配。`same_identity?` 只比较 host/platform/id;显示名变化不改变身份。平台由领域 Registry 归一化,采集前拒绝目标与连接平台冲突。
|
|
22
|
+
- `Snapshot#target` 返回 Target;`to_h` 投影为普通数据。三个领域都提供 `observations`、`observation(name)`、`records(name)`、`collection_status`、`same_target?`。
|
|
23
|
+
- `Observation#evidence` 返回 `CtxDriver::Source` 数组。Source 的核心字段为 command、sha256、bytes、reference、observed_at、status、context;摘要和非负字节数必须同时存在。空 Hash 或仅有时间的来源无效,`not_applicable` 至少需要一份带摘要的来源。
|
|
24
|
+
- Source 属性 observed_at 是 UTC Time,`to_h` 将它输出为 ISO8601;领域附加属性放在 context。来源的摘要取自原始输出,不是解析后的正文。时间读取失败不得丢弃已经取得的摘要。
|
|
25
|
+
- Checker Observation 继承公共不可变值语义,但每次 `new`/`with` 都重新执行领域字段、身份和状态校验。
|
|
26
|
+
- `ConfigurationSession` 借用会话,接受领域注入的准备命令、配置查询和解析器。准备、写入和读取都验证单命令回执;失败不自动重放、不关闭借用会话。领域保留操作租约和前后配置验收。
|
|
27
|
+
- 变更对象提供 `to_h`、`commands`、`rollback`、`eligible?`、`satisfied?`;工厂提供 `build`、`candidate`。无线配置索引只构建一次,重复模板名仍是歧义,不能选第一条执行。
|
|
28
|
+
|
|
29
|
+
## 序列化与字段切换
|
|
30
|
+
|
|
31
|
+
| 旧接口 | 新接口 |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| 报告/计划/执行的 device | target |
|
|
34
|
+
| Hash 形式 snapshot.target | Target 值对象,序列化后仍是映射 |
|
|
35
|
+
| 任意 Hash 来源附加字段 | Source.context |
|
|
36
|
+
| neighbor_name / neighbor_interface / chassis_id | remote_name / remote_interface / remote_chassis_id |
|
|
37
|
+
| CDP interface | local_interface |
|
|
38
|
+
| BGP peer / peer_ip | peer_address |
|
|
39
|
+
| VXLAN BGP address_family: L2VPN EVPN | afi_safi: l2vpn_evpn |
|
|
40
|
+
| prefixes_received | received_prefixes |
|
|
41
|
+
| BGP 字符串状态 | Symbol 状态,管理关闭为 :shutdown |
|
|
42
|
+
| AP 原始状态文本 | :online / :offline / :unknown |
|
|
43
|
+
| channel_width / utilization | channel_width_mhz / utilization_percent |
|
|
44
|
+
| 无线报告平台 h3c_wireless | h3c |
|
|
45
|
+
|
|
46
|
+
厂商 CLI 原文和命令名称不改写。Netdisco 的 vendor、连接器凭据命名空间仍保留 h3c_wireless;无线 CLI 在领域平台边界进行映射。Netdisco 资产 Device 仍是资产对象。
|
|
47
|
+
|
|
48
|
+
schema 4 集合报告的顶层 status 必须与快照实际聚合结果一致;target 与 snapshot.target 的 host/platform/id 必须一致。无快照只能报告 failed。计划的目标平台必须匹配计划平台。Batch 在执行前拒绝重复和未请求目标,返回快照身份不符时不发布其事实。
|
|
49
|
+
|
|
50
|
+
纯数据和 JSON 使用 128 层深度预算;Fingerprint 不再受 JSON 默认 100 层限制。对象循环、键归一化碰撞和非有限数字仍被拒绝。
|
|
51
|
+
|
|
52
|
+
## 升级与验证
|
|
53
|
+
|
|
54
|
+
候选版本:ctx_cli/ctx_driver/ctx_runner 0.5.0,ctx_checker 0.6.0,net-connector 0.21.0,vxlan 0.8.0,wireless-rb 0.9.0。ctx_parser 继续 0.4.0,expect-pty 继续 0.9.6;没有为了统一命名而改动其稳定执行内核。
|
|
55
|
+
|
|
56
|
+
按 ctx_cli → ctx_driver → ctx_runner → 消费模块更新依赖;net-connector 0.21 依赖 ctx_cli 0.5。Parser 继续使用 0.4 系列。锁文件必须同步,避免把源码联调误当成已安装依赖兼容。
|
|
57
|
+
|
|
58
|
+
使用 RVM Ruby 4.0.6 执行各仓库 `bundle exec rake`。`script/verify_stack.rb WORKSPACE OUTPUT` 构建九个候选,在临时 GEM_HOME 验证依赖、普通入口、领域 Batch/schema 往返、本地 PTY 和最小 Bundler 消费方。无线 `benchmark/review.rb` 测完整审查序列化,`benchmark/configuration_index.rb` 测候选索引;合成性能不代表实机吞吐或型号认证。
|
data/examples/execution.rb
CHANGED
|
@@ -22,7 +22,7 @@ end
|
|
|
22
22
|
|
|
23
23
|
Dir.mktmpdir do |root|
|
|
24
24
|
report = CtxRunner::Report.new(File.join(root, "execution"))
|
|
25
|
-
plan = { "
|
|
25
|
+
plan = { "target" => { "host" => "192.0.2.1" }, "expected_config_sha256" => CtxRunner::Fingerprint.call("mode" => "disabled") }
|
|
26
26
|
execution = CtxRunner::Execution.new(plan: plan, change: ExampleChange.new, journal: report, plan_sha256: "a" * 64)
|
|
27
27
|
result = execution.run { |operation| operation.call(ExampleSession.new) }
|
|
28
28
|
raise "Unverified configuration" unless result["status"] == "configuration_verified"
|
data/examples/report.rb
CHANGED
|
@@ -8,7 +8,7 @@ Dir.mktmpdir do |root|
|
|
|
8
8
|
report = CtxRunner::Report.new(File.join(root, "reports"))
|
|
9
9
|
report.publish("evidence.json", JSON.generate(source: "synthetic", records: []))
|
|
10
10
|
device = { "host" => "192.0.2.1", "name" => "example" }
|
|
11
|
-
summary = report.finish([ {
|
|
11
|
+
summary = report.finish([ { target: device, status: :complete, report_saved: true } ], requested: [ device ]) do |value|
|
|
12
12
|
"Evidence: #{value.fetch('status')}; health was not evaluated.\n"
|
|
13
13
|
end
|
|
14
14
|
raise "Report incomplete" unless summary.fetch("status") == "complete"
|
data/lib/ctx_runner/batch.rb
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
require "ctx_parser/immutable"
|
|
4
4
|
require "ctx_driver/failure"
|
|
5
5
|
require_relative "document"
|
|
6
|
+
require_relative "target"
|
|
6
7
|
|
|
7
8
|
module CtxRunner
|
|
8
9
|
# 批量采集的交付账本;调度器负责并发与回收,领域块只返回设备快照。
|
|
@@ -73,26 +74,42 @@ module CtxRunner
|
|
|
73
74
|
end
|
|
74
75
|
|
|
75
76
|
def initialize(report:, progress:, requested:)
|
|
76
|
-
|
|
77
|
+
raise ArgumentError, "Requested targets must be a list" unless requested.is_a?(Array)
|
|
78
|
+
targets = requested.map { |value| Target.coerce(value) }
|
|
79
|
+
@identities = targets.to_h { |target| [ target.identity_key, true ] }.freeze
|
|
80
|
+
raise ArgumentError, "Duplicate requested target" unless targets.size == @identities.size
|
|
81
|
+
@requested = Document.call(targets)
|
|
82
|
+
@claimed = {}
|
|
77
83
|
@report, @progress = report, progress
|
|
78
84
|
@results, @lock = [], Mutex.new
|
|
79
85
|
end
|
|
80
86
|
|
|
81
87
|
# 先登记设备事实,再保存报告;报告失败仍可在最终摘要中定位未交付结果。
|
|
82
88
|
def collect(device)
|
|
83
|
-
|
|
84
|
-
device =
|
|
89
|
+
identity = Target.coerce(device)
|
|
90
|
+
device = Document.call(identity)
|
|
91
|
+
@lock.synchronize do
|
|
92
|
+
raise ArgumentError, "Batch is closed" if @closed
|
|
93
|
+
unless @identities.key?(identity.identity_key) && !@claimed.key?(identity.identity_key)
|
|
94
|
+
raise ArgumentError, "Target must be requested exactly once"
|
|
95
|
+
end
|
|
96
|
+
@claimed[identity.identity_key] = true
|
|
97
|
+
end
|
|
85
98
|
started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
|
|
86
99
|
@progress.start(device)
|
|
87
100
|
snapshot = nil
|
|
88
101
|
begin
|
|
89
102
|
snapshot = yield
|
|
103
|
+
unless snapshot.respond_to?(:target) && identity.same_identity?(snapshot.target)
|
|
104
|
+
snapshot = nil
|
|
105
|
+
raise ArgumentError, "Snapshot identity differs from the requested target"
|
|
106
|
+
end
|
|
90
107
|
dimensions = snapshot.observations.transform_values do |value|
|
|
91
108
|
{ status: value.status, records: value.records.size, issues: value.issues.map { |issue| issue[:code] }.uniq }
|
|
92
109
|
end
|
|
93
|
-
result = {
|
|
110
|
+
result = { target: device, status: snapshot.collection_status, dimensions: dimensions }
|
|
94
111
|
rescue StandardError => error
|
|
95
|
-
result = {
|
|
112
|
+
result = { target: device, status: :failed, error: CtxDriver::Failure.code(error, :collection_failed), dimensions: {} }
|
|
96
113
|
end
|
|
97
114
|
result[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
|
|
98
115
|
result[:report_saved] = false
|
|
@@ -105,7 +122,7 @@ module CtxRunner
|
|
|
105
122
|
end
|
|
106
123
|
|
|
107
124
|
def results
|
|
108
|
-
@lock.synchronize { CtxParser::Immutable.copy(@results).sort_by { |result| result[:
|
|
125
|
+
@lock.synchronize { CtxParser::Immutable.copy(@results).sort_by { |result| result[:target].fetch("host") }.freeze }
|
|
109
126
|
end
|
|
110
127
|
|
|
111
128
|
# 调度器回收后调用;输出诊断只补写报告,绝不重新执行设备操作。
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "ctx_driver"
|
|
4
|
+
require "ctx_driver/receipt"
|
|
5
|
+
require "ctx_parser/commands"
|
|
6
|
+
require_relative "document"
|
|
7
|
+
|
|
8
|
+
module CtxRunner
|
|
9
|
+
# 借用领域已取得租约的会话;查询策略和配置解析器由领域显式注入。
|
|
10
|
+
class ConfigurationSession
|
|
11
|
+
def initialize(session:, preparation_commands:, configuration_command:, parser:, clock: -> { Time.now.utc })
|
|
12
|
+
unless preparation_commands.is_a?(Array) && parser.respond_to?(:parse) && session.respond_to?(:write_command)
|
|
13
|
+
raise ArgumentError, "Configuration session requires a writer and parser"
|
|
14
|
+
end
|
|
15
|
+
@preparation = preparation_commands.map { |command| CtxParser::Commands.command_text(command) }.freeze
|
|
16
|
+
@command = CtxParser::Commands.command_text(configuration_command)
|
|
17
|
+
@session, @parser = session, parser
|
|
18
|
+
@reader = CtxDriver::Reader.new(session: session, clock: clock)
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
def read_configuration
|
|
22
|
+
@preparation.each { |command| write(command) }
|
|
23
|
+
capture = @reader.read(@command)
|
|
24
|
+
raise IOError, "Configuration readback failed" unless capture.success?
|
|
25
|
+
observation = @parser.parse(capture.body, complete: true)
|
|
26
|
+
unless observation.complete? && observation.records.one?
|
|
27
|
+
raise ArgumentError, "Configuration evidence is incomplete"
|
|
28
|
+
end
|
|
29
|
+
Document.call(observation.records.first)
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
def write(command)
|
|
33
|
+
command = CtxParser::Commands.command_text(command).strip
|
|
34
|
+
receipt = @session.write_command(command)
|
|
35
|
+
raise IOError, "Device command is unconfirmed" unless CtxDriver::Receipt.validate(receipt, command: command)
|
|
36
|
+
true
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
def inspect = "#<#{self.class.name}>"
|
|
40
|
+
alias to_s inspect
|
|
41
|
+
def pretty_print(printer) = printer.text(inspect)
|
|
42
|
+
end
|
|
43
|
+
end
|
data/lib/ctx_runner/evidence.rb
CHANGED
|
@@ -9,7 +9,7 @@ require_relative "snapshot"
|
|
|
9
9
|
module CtxRunner
|
|
10
10
|
# 离线证据的公共外壳;记录字段和领域语义交给消费模块校验。
|
|
11
11
|
module Evidence
|
|
12
|
-
VERSION =
|
|
12
|
+
VERSION = 4
|
|
13
13
|
KINDS = %w[collection batch change_plan change execution review recommendations fabric_review].freeze
|
|
14
14
|
|
|
15
15
|
def self.wrap(value, kind:)
|
|
@@ -33,8 +33,9 @@ module CtxRunner
|
|
|
33
33
|
selected = document["changes"].fetch(item)
|
|
34
34
|
validate_version!(selected, kind: "change")
|
|
35
35
|
raise ArgumentError, "Change platform differs from its plan" unless selected["platform"] == platform
|
|
36
|
-
identity = Target.
|
|
37
|
-
|
|
36
|
+
identity = Target.coerce(selected.fetch("target"))
|
|
37
|
+
raise ArgumentError, "Change target platform differs from its plan" unless identity.platform == platform
|
|
38
|
+
host = identity.host
|
|
38
39
|
unless !host.include?("/") && IPAddr.new(host).to_s == host &&
|
|
39
40
|
selected["expected_config_sha256"].is_a?(String) && selected["expected_config_sha256"].match?(/\A[0-9a-f]{64}\z/)
|
|
40
41
|
raise ArgumentError, "Invalid change target or configuration fingerprint"
|
|
@@ -44,15 +45,18 @@ module CtxRunner
|
|
|
44
45
|
|
|
45
46
|
def self.validate(document, names:)
|
|
46
47
|
validate_version!(document, kind: "collection")
|
|
47
|
-
unless document.is_a?(Hash) && document["
|
|
48
|
-
%w[name host].all? { |key| document["
|
|
48
|
+
unless document.is_a?(Hash) && document["target"].is_a?(Hash) &&
|
|
49
|
+
%w[name host].all? { |key| document["target"][key].is_a?(String) && !document["target"][key].empty? }
|
|
49
50
|
raise ArgumentError, "Device identity is missing"
|
|
50
51
|
end
|
|
51
|
-
host = document["
|
|
52
|
-
Target.
|
|
52
|
+
host = document["target"]["host"]
|
|
53
|
+
Target.coerce(document["target"])
|
|
53
54
|
raise ArgumentError, "Target address must be a canonical host address" unless !host.include?("/") && IPAddr.new(host).to_s == host
|
|
54
55
|
snapshot = document.fetch("snapshot")
|
|
55
|
-
|
|
56
|
+
if snapshot.nil?
|
|
57
|
+
raise ArgumentError, "Missing snapshots cannot claim successful collection" unless document["status"] == "failed"
|
|
58
|
+
return
|
|
59
|
+
end
|
|
56
60
|
unless snapshot.is_a?(Hash) && snapshot["observations"].is_a?(Hash) &&
|
|
57
61
|
%w[complete partial failed not_requested].include?(snapshot["collection_status"])
|
|
58
62
|
raise ArgumentError, "Invalid snapshot structure"
|
|
@@ -60,9 +64,9 @@ module CtxRunner
|
|
|
60
64
|
if !snapshot["target"].is_a?(Hash) || snapshot["target"]["host"] != host
|
|
61
65
|
raise ArgumentError, "Device identity does not match the collection target"
|
|
62
66
|
end
|
|
63
|
-
identity = Target.
|
|
67
|
+
identity = Target.coerce(snapshot["target"])
|
|
64
68
|
%w[platform id].each do |field|
|
|
65
|
-
if document["
|
|
69
|
+
if document["target"][field] != snapshot["target"][field]
|
|
66
70
|
raise ArgumentError, "Device identity does not match the collection target"
|
|
67
71
|
end
|
|
68
72
|
end
|
|
@@ -73,7 +77,7 @@ module CtxRunner
|
|
|
73
77
|
end
|
|
74
78
|
records = array(observation.fetch("records"))
|
|
75
79
|
value = Observation.new(name: dimension.to_sym, status: observation["status"].to_sym, records: records,
|
|
76
|
-
issues: array(observation.fetch("issues", [])), evidence: array(observation.fetch("evidence", []))
|
|
80
|
+
issues: array(observation.fetch("issues", [])), evidence: array(observation.fetch("evidence", [])),
|
|
77
81
|
covered_scopes: array(observation.fetch("covered_scopes", [])),
|
|
78
82
|
started_at: observation["started_at"] && CtxParser::Values.timestamp(observation["started_at"]),
|
|
79
83
|
completed_at: observation["completed_at"] && CtxParser::Values.timestamp(observation["completed_at"]))
|
|
@@ -82,7 +86,7 @@ module CtxRunner
|
|
|
82
86
|
end
|
|
83
87
|
value = Snapshot.new(target: identity, observations: observations, names: names,
|
|
84
88
|
observed_at: CtxParser::Values.timestamp(snapshot.fetch("observed_at")), issues: array(snapshot.fetch("issues", [])))
|
|
85
|
-
unless value.collection_status.to_s == snapshot["collection_status"]
|
|
89
|
+
unless value.collection_status.to_s == snapshot["collection_status"] && document["status"] == snapshot["collection_status"]
|
|
86
90
|
raise ArgumentError, "Collection status differs from its evidence"
|
|
87
91
|
end
|
|
88
92
|
end
|
data/lib/ctx_runner/execution.rb
CHANGED
|
@@ -13,7 +13,7 @@ module CtxRunner
|
|
|
13
13
|
# 领域动作负责有限命令及前后置条件;日志接收独立的不可变检查点。
|
|
14
14
|
def initialize(plan:, change:, journal:, plan_sha256:, item: nil)
|
|
15
15
|
@plan = CtxParser::Immutable.copy(plan)
|
|
16
|
-
unless @plan.is_a?(Hash) && @plan["
|
|
16
|
+
unless @plan.is_a?(Hash) && @plan["target"].is_a?(Hash) &&
|
|
17
17
|
[ @plan["expected_config_sha256"], plan_sha256 ].all? { |value| value.is_a?(String) && /\A[0-9a-f]{64}\z/.match?(value) }
|
|
18
18
|
raise ArgumentError, "Execution requires a verified plan and fingerprints"
|
|
19
19
|
end
|
|
@@ -26,7 +26,7 @@ module CtxRunner
|
|
|
26
26
|
end
|
|
27
27
|
@commands.each { |command| CtxParser::Commands.command_text(command) }
|
|
28
28
|
@change, @journal = change, journal
|
|
29
|
-
@state = { "schema_version" => Evidence::VERSION, "kind" => "execution", "status" => "confirmed", "
|
|
29
|
+
@state = { "schema_version" => Evidence::VERSION, "kind" => "execution", "status" => "confirmed", "target" => @plan["target"], "plan_sha256" => plan_sha256.dup.freeze,
|
|
30
30
|
"expected_config_sha256" => @plan["expected_config_sha256"], "commands" => @commands, "steps" => [] }
|
|
31
31
|
@state["plan_item"] = CtxParser::Immutable.copy(item) if item
|
|
32
32
|
@started = @used = @journal_failed = false
|
|
@@ -7,7 +7,7 @@ require "ctx_parser/immutable"
|
|
|
7
7
|
module CtxRunner
|
|
8
8
|
# 配置映射顺序不影响身份;列表顺序和全部字段仍参与旧版摘要协议。
|
|
9
9
|
module Fingerprint
|
|
10
|
-
def self.call(value) = Digest::SHA256.hexdigest(JSON.generate(canonical(value)))
|
|
10
|
+
def self.call(value) = Digest::SHA256.hexdigest(JSON.generate(canonical(value), max_nesting: false))
|
|
11
11
|
|
|
12
12
|
# 先拒绝非纯数据与循环,再将键归一化;重名键不能静默覆盖来源事实。
|
|
13
13
|
def self.canonical(value)
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require "ctx_parser/immutable"
|
|
4
|
+
require "ctx_driver/source"
|
|
4
5
|
require "ctx_parser/values"
|
|
5
6
|
require "time"
|
|
6
7
|
|
|
@@ -12,7 +13,7 @@ module CtxRunner
|
|
|
12
13
|
def self.validate(name:, status:, records:, issues:, evidence:, statuses: STATUSES)
|
|
13
14
|
raise ArgumentError, "Observation name must be a symbol" unless name.is_a?(Symbol)
|
|
14
15
|
raise ArgumentError, "Invalid observation status" unless statuses.include?(status)
|
|
15
|
-
unless [ records, issues
|
|
16
|
+
unless [ records, issues ].all? { |entries| entries.is_a?(Array) && entries.all? { |entry| entry.is_a?(Hash) } }
|
|
16
17
|
raise ArgumentError, "Observation entries must be arrays of hashes"
|
|
17
18
|
end
|
|
18
19
|
if %i[failed unsupported not_requested not_applicable].include?(status) && records.any?
|
|
@@ -29,16 +30,20 @@ module CtxRunner
|
|
|
29
30
|
(covered_scopes.empty? || %i[complete partial].include?(status))
|
|
30
31
|
raise ArgumentError, "Covered scopes require available observations and unique hashes"
|
|
31
32
|
end
|
|
32
|
-
|
|
33
|
+
raise ArgumentError, "Evidence must be a list of sources" unless evidence.is_a?(Array)
|
|
34
|
+
evidence = evidence.map { |entry| CtxDriver::Source.coerce(entry) }.freeze
|
|
35
|
+
if status == :not_applicable && !evidence.any?(&:verified?)
|
|
33
36
|
raise ArgumentError, "Not applicable observations require evidence"
|
|
34
37
|
end
|
|
35
|
-
@observed_at = evidence.filter_map
|
|
38
|
+
@observed_at = evidence.filter_map(&:observed_at).max
|
|
36
39
|
super(name: name, status: status, records: CtxParser::Immutable.copy(records),
|
|
37
|
-
issues: CtxParser::Immutable.copy(issues), evidence:
|
|
40
|
+
issues: CtxParser::Immutable.copy(issues), evidence: evidence,
|
|
38
41
|
started_at: started_at&.getutc&.freeze, completed_at: completed_at&.getutc&.freeze,
|
|
39
42
|
covered_scopes: CtxParser::Immutable.copy(covered_scopes))
|
|
40
43
|
end
|
|
41
44
|
|
|
45
|
+
def to_h = super.merge(evidence: evidence.map(&:to_h))
|
|
46
|
+
|
|
42
47
|
def complete? = status == :complete
|
|
43
48
|
def partial? = status == :partial
|
|
44
49
|
def available? = complete? || partial?
|
data/lib/ctx_runner/report.rb
CHANGED
|
@@ -55,9 +55,9 @@ module CtxRunner
|
|
|
55
55
|
summary = checkpoint = nil
|
|
56
56
|
# 转换和编码也属于发布;失败或取消不能让上一轮完成结论继续生效。
|
|
57
57
|
checkpoint_body = publish_checkpoint("summary.json") do
|
|
58
|
-
#
|
|
59
|
-
|
|
60
|
-
pending = requested.reject { |
|
|
58
|
+
# 按完整目标身份索引一次,不让同地址的其他平台或资产替代待采集目标。
|
|
59
|
+
completed_targets = results.to_h { |result| [ Target.coerce(result.fetch(:target)).identity_key, true ] }
|
|
60
|
+
pending = requested.reject { |target| completed_targets.key?(Target.coerce(target).identity_key) }
|
|
61
61
|
complete = !report_error && !execution_error && !output_error && pending.empty? && results.any? && results.all? { |r| r[:status] == :complete && r[:report_saved] != false }
|
|
62
62
|
summary = { status: interrupted ? :interrupted : (complete ? :complete : :incomplete),
|
|
63
63
|
total: [ requested.size, results.size ].max, completed: results.size, pending: pending, counts: results.map { |r| r[:status] }.tally, devices: results,
|
data/lib/ctx_runner/snapshot.rb
CHANGED
|
@@ -23,7 +23,7 @@ module CtxRunner
|
|
|
23
23
|
unless issues.is_a?(Array) && issues.all? { |issue| issue.is_a?(Hash) }
|
|
24
24
|
raise ArgumentError, "Snapshot issues must be hashes"
|
|
25
25
|
end
|
|
26
|
-
@target = Target.
|
|
26
|
+
@target = Target.coerce(target)
|
|
27
27
|
@names = names.dup.freeze
|
|
28
28
|
@observations = observations.to_h { |name, value| [ name, value ] }.freeze
|
|
29
29
|
@observed_at = observed_at.getutc.freeze
|
|
@@ -38,10 +38,11 @@ module CtxRunner
|
|
|
38
38
|
end
|
|
39
39
|
|
|
40
40
|
def complete? = collection_status == :complete
|
|
41
|
-
def same_target?(other) = other.respond_to?(:target) &&
|
|
41
|
+
def same_target?(other) = other.respond_to?(:target) && target.same_identity?(other.target)
|
|
42
|
+
def records(name) = observation(name).records
|
|
42
43
|
|
|
43
44
|
def to_h
|
|
44
|
-
{ target: target, observations: observations.transform_values(&:to_h), observed_at: observed_at,
|
|
45
|
+
{ target: target.to_h, observations: observations.transform_values(&:to_h), observed_at: observed_at,
|
|
45
46
|
issues: issues, collection_status: collection_status }
|
|
46
47
|
end
|
|
47
48
|
|
data/lib/ctx_runner/target.rb
CHANGED
|
@@ -4,22 +4,37 @@ require "ctx_parser/immutable"
|
|
|
4
4
|
|
|
5
5
|
module CtxRunner
|
|
6
6
|
# 设备身份与连接设置分离;边界只接受公开字段,Ruby 内部统一符号键。
|
|
7
|
-
|
|
7
|
+
class Target < Data.define(:host, :platform, :name, :model, :software_version, :id)
|
|
8
8
|
FIELDS = %i[host platform name model software_version id].freeze
|
|
9
9
|
|
|
10
|
-
def self.
|
|
10
|
+
def self.coerce(value)
|
|
11
|
+
return value if value.is_a?(self)
|
|
11
12
|
raise ArgumentError, "Target must be a mapping of public identity fields" unless value.is_a?(Hash)
|
|
12
13
|
result = value.each_with_object({}) do |(key, entry), target|
|
|
13
14
|
unless (key.is_a?(String) || key.is_a?(Symbol)) && FIELDS.include?(key.to_sym) && !target.key?(key.to_sym)
|
|
14
15
|
raise ArgumentError, "Target contains unknown or duplicate identity fields"
|
|
15
16
|
end
|
|
16
|
-
unless entry.nil? || entry.is_a?(String) && !entry.strip.empty? && !/[\x00-\x1f\x7f]/.match?(entry) || key.to_sym == :id && entry.is_a?(Integer) && entry >= 0
|
|
17
|
-
raise ArgumentError, "Invalid target identity value"
|
|
18
|
-
end
|
|
19
17
|
target[key.to_sym] = entry
|
|
20
18
|
end
|
|
21
19
|
raise ArgumentError, "Target requires a host" unless result[:host].is_a?(String)
|
|
22
|
-
|
|
20
|
+
new(**result)
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
def initialize(host:, platform: nil, name: nil, model: nil, software_version: nil, id: nil)
|
|
24
|
+
attributes = { host: host, platform: platform, name: name, model: model, software_version: software_version, id: id }
|
|
25
|
+
unless host.is_a?(String) && attributes.all? do |key, value|
|
|
26
|
+
value.nil? || value.is_a?(String) && !value.strip.empty? && !/[\x00-\x1f\x7f]/.match?(value) || key == :id && value.is_a?(Integer) && value >= 0
|
|
27
|
+
end
|
|
28
|
+
raise ArgumentError, "Invalid target identity value"
|
|
29
|
+
end
|
|
30
|
+
super(**CtxParser::Immutable.copy(attributes))
|
|
23
31
|
end
|
|
32
|
+
|
|
33
|
+
def identity_key = [ host, platform, id ].freeze
|
|
34
|
+
def same_identity?(other) = other.is_a?(Target) && identity_key == other.identity_key
|
|
35
|
+
def to_h = super.compact
|
|
36
|
+
def inspect = "#<#{self.class.name}>"
|
|
37
|
+
alias to_s inspect
|
|
38
|
+
def pretty_print(printer) = printer.text(inspect)
|
|
24
39
|
end
|
|
25
40
|
end
|
data/lib/ctx_runner/version.rb
CHANGED
data/lib/ctx_runner.rb
CHANGED
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: ctx_runner
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.5.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Gatework contributors
|
|
@@ -35,20 +35,20 @@ dependencies:
|
|
|
35
35
|
requirements:
|
|
36
36
|
- - ">="
|
|
37
37
|
- !ruby/object:Gem::Version
|
|
38
|
-
version: 0.
|
|
38
|
+
version: 0.5.0
|
|
39
39
|
- - "<"
|
|
40
40
|
- !ruby/object:Gem::Version
|
|
41
|
-
version: '0.
|
|
41
|
+
version: '0.6'
|
|
42
42
|
type: :runtime
|
|
43
43
|
prerelease: false
|
|
44
44
|
version_requirements: !ruby/object:Gem::Requirement
|
|
45
45
|
requirements:
|
|
46
46
|
- - ">="
|
|
47
47
|
- !ruby/object:Gem::Version
|
|
48
|
-
version: 0.
|
|
48
|
+
version: 0.5.0
|
|
49
49
|
- - "<"
|
|
50
50
|
- !ruby/object:Gem::Version
|
|
51
|
-
version: '0.
|
|
51
|
+
version: '0.6'
|
|
52
52
|
- !ruby/object:Gem::Dependency
|
|
53
53
|
name: digest
|
|
54
54
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -143,6 +143,7 @@ files:
|
|
|
143
143
|
- LICENSE
|
|
144
144
|
- README.md
|
|
145
145
|
- docs/contracts-2026-10-29.md
|
|
146
|
+
- docs/contracts-2026-10-30.md
|
|
146
147
|
- docs/module-boundaries.md
|
|
147
148
|
- docs/superpowers/plans/2026-10-21-runner.md
|
|
148
149
|
- docs/superpowers/plans/2026-10-23-report-documents.md
|
|
@@ -155,6 +156,7 @@ files:
|
|
|
155
156
|
- lib/ctx_runner.rb
|
|
156
157
|
- lib/ctx_runner/batch.rb
|
|
157
158
|
- lib/ctx_runner/collection.rb
|
|
159
|
+
- lib/ctx_runner/configuration_session.rb
|
|
158
160
|
- lib/ctx_runner/document.rb
|
|
159
161
|
- lib/ctx_runner/evidence.rb
|
|
160
162
|
- lib/ctx_runner/execution.rb
|