net-connector 0.15.0 → 0.16.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.
Files changed (43) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +13 -0
  3. data/docs/architecture.md +16 -6
  4. data/docs/netdisco.md +8 -4
  5. data/docs/netdisco.zh-CN.md +10 -6
  6. data/docs/usage.md +1 -1
  7. data/docs/usage.zh-CN.md +2 -2
  8. data/lib/net/connector/collect/progress.rb +70 -0
  9. data/lib/net/connector/config.rb +367 -0
  10. data/lib/net/connector/device/interfaces/audit.rb +3 -3
  11. data/lib/net/connector/device/interfaces/{interface_blocks.rb → blocks.rb} +1 -1
  12. data/lib/net/connector/device/interfaces/{interface_description.rb → description.rb} +6 -6
  13. data/lib/net/connector/device/interfaces/immediate_strategy.rb +2 -2
  14. data/lib/net/connector/device/interfaces/{interface_name.rb → name.rb} +1 -1
  15. data/lib/net/connector/device/interfaces/stages.rb +2 -2
  16. data/lib/net/connector/device/interfaces/strategy.rb +3 -3
  17. data/lib/net/connector/device/interfaces.rb +5 -5
  18. data/lib/net/connector/engine/errors.rb +4 -4
  19. data/lib/net/connector/engine/result.rb +2 -2
  20. data/lib/net/connector/netdisco/cli/backup.rb +17 -13
  21. data/lib/net/connector/netdisco/cli/help.rb +1 -1
  22. data/lib/net/connector/netdisco/cli/options.rb +49 -16
  23. data/lib/net/connector/netdisco/cli/setup.rb +32 -12
  24. data/lib/net/connector/netdisco/cli/topology.rb +14 -7
  25. data/lib/net/connector/netdisco/cli.rb +27 -8
  26. data/lib/net/connector/netdisco/config/defaults.rb +1 -1
  27. data/lib/net/connector/netdisco/config/initializer.rb +17 -11
  28. data/lib/net/connector/netdisco/config.rb +49 -1
  29. data/lib/net/connector/netdisco/fleet.rb +1 -1
  30. data/lib/net/connector/netdisco/operation.rb +3 -3
  31. data/lib/net/connector/netdisco/progress.rb +41 -283
  32. data/lib/net/connector/netdisco/settings.rb +11 -2
  33. data/lib/net/connector/netdisco/topology/options.rb +3 -3
  34. data/lib/net/connector/parallel/pool.rb +3 -4
  35. data/lib/net/connector/progress.rb +288 -0
  36. data/lib/net/connector/resources.rb +40 -0
  37. data/lib/net/connector/vendor/cisco/topology.rb +1 -1
  38. data/lib/net/connector/vendor/h3c/topology.rb +1 -1
  39. data/lib/net/connector/vendor/hillstone/topology.rb +1 -1
  40. data/lib/net/connector/vendor/huawei/topology.rb +2 -2
  41. data/lib/net/connector/version.rb +1 -1
  42. metadata +23 -6
  43. data/lib/net/connector/netdisco/resources.rb +0 -36
@@ -1,58 +1,54 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require "io/console"
4
- require_relative "../engine/error/metadata"
5
- require_relative "../engine/log/event"
6
- require_relative "../parallel/observer"
3
+ require_relative "../progress"
7
4
  require_relative "topology/presentation"
8
5
  require_relative "diagnostic"
9
6
 
10
7
  module Net
11
8
  module Connector
12
9
  module Netdisco
13
- # 共享一个实例接收并发会话事件和任务回调;人类进度不混入 JSON 输出。
14
- class Progress
15
- # 读取首次终端输出故障的受控诊断,供最终报告保留。
16
- attr_reader :output_error
17
-
18
- # 调用方保留输出 IO 所有权;同一个互斥锁保护心跳、事件和任务计数。
19
- def initialize(io: $stderr, enabled: true, verbose: false)
20
- @io, @enabled, @verbose = io, enabled, verbose
21
- @tty = io.respond_to?(:tty?) && io.tty?
22
- @stages = {}
23
- @task_started = {}
24
- @failures = Hash.new(0)
25
- @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
26
- @succeeded = @failed = @unverified = 0
27
- @mutex = Mutex.new
28
- @total = @completed = @active = 0
10
+ # 将备份与拓扑结果适配到统一的终端进度,不向通用组件引入 Netdisco 依赖。
11
+ class Progress < Net::Connector::Progress
12
+ # 备份入口保留清单对象接口,显示由公共批次组件处理。
13
+ def plan(plan, parallel:, limit_per_vendor: nil)
14
+ @operation_mode = false
15
+ mode = limit_per_vendor ? "抽样(每厂商最多 #{limit_per_vendor} 台)" : "全量"
16
+ super(total: plan.inventory.size, selected: plan.ready.size, parallel: parallel, label: mode)
29
17
  end
30
18
 
31
- # 输出当前开始读取清单的进度提示。
32
- def reading_inventory(config: nil)
33
- write(nil, "正在读取 Netdisco 设备清单#{config ? "(配置:#{config})" : ""}")
19
+ # 设备对象只在领域入口转换为显示身份。
20
+ def start(device, label: "备份")
21
+ super(host: device.host, label: "#{label}(#{device.vendor})")
34
22
  end
35
23
 
36
- # 以实际选中设备初始化进度,清单中被跳过的条目不计入执行任务总数。
37
- def plan(plan, parallel:, limit_per_vendor: nil)
38
- @mutex.synchronize do
39
- @operation_mode = false
40
- @total = plan.ready.size
41
- @completed = @active = 0
42
- @run_started = monotonic
43
- mode = limit_per_vendor ? "抽样(每厂商最多 #{limit_per_vendor} 台)" : "全量"
44
- emit(nil, "#{mode} | 清单 #{plan.inventory.size} 台;本次 #{@total} 台;跳过 #{plan.inventory.size - @total} 台;并发 #{parallel}")
45
- end
24
+ # 分别展示已保存、设备报告上传和服务器核验状态。
25
+ def result(outcome)
26
+ error_code = diagnostic_code(outcome)
27
+ message = case outcome.status
28
+ when :backed_up then "备份已保存(#{outcome.backup.bytes} 字节)"
29
+ when :reported_uploaded
30
+ outcome.backup&.verification == :server_verified ? "配置已归档(#{outcome.backup.server_bytes} 字节)" :
31
+ "设备报告上传完成;服务器文件尚未核验"
32
+ when :saved_with_error then "备份有产物但未完全成功(#{error_code || outcome.status})"
33
+ when :reported_with_error then "设备报告上传但收尾异常(#{error_code || outcome.status})"
34
+ else "未完成(#{error_code || outcome.status})"
35
+ end
36
+ super(host: outcome.device.host, success: outcome.success?, duration_ms: outcome.duration_ms, message: message, error_code: error_code)
46
37
  end
47
38
 
48
- # 任务开始时记录单调时钟与登录阶段,不把开始通知当作连接成功。
49
- def start(device, label: "备份")
50
- @mutex.synchronize do
51
- @active += 1
52
- @stages[device.host] = "登录"
53
- @task_started[device.host] = monotonic
54
- @verbose ? emit(device.host, "开始#{label}(#{device.vendor})") : refresh
55
- end
39
+ # 成功策略、核验状态和回调诊断仍使用备份领域报告。
40
+ def finish(report)
41
+ return unless @enabled
42
+
43
+ summary = report.statistics
44
+ failures = report.outcomes.reject { |item| item.success? || %i[filtered sample_limit].include?(item.status) }
45
+ .group_by { |item| diagnostic_code(item) || item.status }.transform_values(&:size)
46
+ super(success: report.policy_success?, **summary.slice(:succeeded, :partial, :failed, :skipped), failures: failures)
47
+ unverified = summary[:verification]&.fetch(:unverified, 0) || 0
48
+ write(nil, "其中 #{unverified} 台仅设备报告上传完成,服务器文件尚未核验") if unverified.positive?
49
+ return unless !report.callback_errors.empty? || report.report_error
50
+
51
+ write(nil, "回调异常 #{report.callback_errors.size},报告错误 #{summary[:report_error] || "无"}")
56
52
  end
57
53
 
58
54
  # 清空上一阶段计数,初始化本次拓扑操作的任务规模与计时。
@@ -109,256 +105,18 @@ module Net
109
105
  write(nil, "拓扑批次结束:#{counts.map { |status, count| "#{Topology::Presentation.status(status)} #{count} 台" }.join(",")};结果 #{result}")
110
106
  end
111
107
 
112
- # 只显示已脱敏事件中的阶段和安全命令,不显示设备回显或异常原文。
113
- def event(event)
114
- return unless event.is_a?(Log::Event)
115
-
116
- unless @verbose
117
- @mutex.synchronize do
118
- host = event.fields[:host]
119
- @stages[host] = "采集" if @stages.key?(host) && event.name == "login_complete" && event.fields[:status] == "ok"
120
- refresh
121
- end
122
- return
123
- end
124
-
125
- fields = event.fields
126
- message = case event.name
127
- when "connect" then "正在连接并登录(#{fields[:protocol]})"
128
- when "login_complete"
129
- fields[:status] == "ok" ? "登录成功" : "登录失败(#{fields[:code]})"
130
- when "connect_failed" then "连接失败(#{fields[:code]})"
131
- when "command_start" then "执行命令:#{fields[:text]};等待响应"
132
- when "command_complete"
133
- fields[:status] == "response_received" ? "命令响应完成(#{fields[:duration_ms]} ms)" :
134
- "命令失败(#{fields[:code]})"
135
- when "operation_complete"
136
- fields[:status] == "completed" ? "脚本处理完成" : "脚本处理失败(#{fields[:code]})"
137
- end
138
- write(fields[:host], message) if message
139
- end
140
-
141
- # 只消费最终任务结果,分别展示已保存、设备报告上传和服务器核验状态。
142
- def result(outcome)
143
- error_code = diagnostic_code(outcome)
144
- @mutex.synchronize do
145
- @completed += 1
146
- @active -= 1
147
- @stages.delete(outcome.device.host)
148
- @task_started.delete(outcome.device.host)
149
- @failures[error_code || outcome.status] += 1 unless outcome.success?
150
- outcome.success? ? @succeeded += 1 : @failed += 1
151
- @unverified += 1 if outcome.status == :reported_uploaded && outcome.backup&.verification != :server_verified
152
- message = case outcome.status
153
- when :backed_up then "备份已保存(#{outcome.backup.bytes} 字节)"
154
- when :reported_uploaded
155
- outcome.backup&.verification == :server_verified ? "配置已归档(#{outcome.backup.server_bytes} 字节)" :
156
- "设备报告上传完成;服务器文件尚未核验"
157
- when :saved_with_error then "备份有产物但未完全成功(#{error_code || outcome.status})"
158
- when :reported_with_error then "设备报告上传但收尾异常(#{error_code || outcome.status})"
159
- else "未完成(#{error_code || outcome.status})"
160
- end
161
- hint = failure_hint(error_code)
162
- message = "#{message};#{hint}" if hint
163
- if @verbose || !outcome.success?
164
- emit(outcome.device.host, "#{message};耗时 #{outcome.duration_ms} ms")
165
- elsif !@tty && ((@completed % 25).zero? || @completed == @total)
166
- emit(nil, status_line)
167
- end
168
- refresh
169
- end
170
- end
171
-
172
- # 使用报告的成功策略与受控失败分类,进度百分比不代替业务成功判定。
173
- def finish(report)
174
- return unless @enabled
175
-
176
- summary = report.statistics
177
- failures = report.outcomes.reject { |item| item.success? || %i[filtered sample_limit].include?(item.status) }
178
- .group_by { |item| diagnostic_code(item) || item.status }.transform_values(&:size)
179
- unless failures.empty?
180
- write(nil, "未完成分类:#{failures.sort_by { |code, count| [-count, code.to_s] }.map { |code, count| "#{code}=#{count}" }.join(",")}")
181
- end
182
- write(nil, "批次结束:成功 #{summary[:succeeded]},部分成功 #{summary[:partial]},失败 #{summary[:failed]},跳过 #{summary[:skipped]};耗时 #{(Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at).round(1)} 秒;结果 #{report.policy_success? ? "完成" : "未完成"}")
183
- unverified = summary[:verification]&.fetch(:unverified, 0) || 0
184
- write(nil, "其中 #{unverified} 台仅设备报告上传完成,服务器文件尚未核验") if unverified.positive?
185
- return unless !report.callback_errors.empty? || report.report_error
186
-
187
- write(nil, "回调异常 #{report.callback_errors.size},报告错误 #{summary[:report_error] || "无"}")
188
- end
189
-
190
- # 心跳只负责显示;退出、异常或中断时先唤醒并回收线程。
191
- def with_updates(&)
192
- return yield unless @enabled && @tty && !@verbose
193
-
194
- lock = Mutex.new
195
- signal = ConditionVariable.new
196
- stopped = false
197
- task = lambda do
198
- loop do
199
- stop = lock.synchronize do
200
- signal.wait(lock, 1) unless stopped
201
- stopped
202
- end
203
- break if stop
204
-
205
- tick
206
- end
207
- rescue StandardError => error
208
- # 非 IO 的显示故障也只停用进度;完整报告仍记录这一受控诊断。
209
- @mutex.synchronize { record_output_error(error) }
210
- end
211
- stop = -> { lock.synchronize { stopped = true; signal.broadcast } }
212
- Parallel::Observer.run(task: task, stop: stop, &)
213
- rescue Exception => error # rubocop:disable Lint/RescueException -- 后台已回收,最后清屏也不能覆盖原业务故障或取消。
214
- primary_failure = error
215
- raise
216
- ensure
217
- begin
218
- Thread.handle_interrupt(Exception => :never) { @mutex.synchronize { clear_refresh } if task }
219
- rescue Exception => error # rubocop:disable Lint/RescueException -- 清屏中的取消正常传播,已有主故障时保持其身份。
220
- raise error unless primary_failure
221
- end
222
- end
223
-
224
- # 心跳仅在持锁后刷新显示,不改变设备任务或完成计数。
225
- def tick
226
- @mutex.synchronize { refresh(force: true) }
227
- end
108
+ private
228
109
 
229
- # 显示已保存报告的位置与可读标签。
230
- def location(path, label: "报告")
231
- write(nil, "#{label}:#{path}")
110
+ # 拓扑进度保留待核实项计数,备份使用通用成功与失败计数。
111
+ def progress_counts
112
+ @operation_mode ? "完成 #{@completed} 待核实 #{@operation_pending} 失败 #{@failed}" : super
232
113
  end
233
114
 
234
- private
235
-
236
115
  # 与持久化摘要采用同一诊断白名单,保留领域结果自身的原始错误字段。
237
116
  def diagnostic_code(outcome)
238
117
  (outcome.diagnostic || Diagnostic.new(error_code: outcome.error_code)).error_code
239
118
  end
240
119
 
241
- # 根据已知错误码返回简短排查建议,不展示任意异常正文。
242
- def failure_hint(code)
243
- case code
244
- when :authentication_failed then "设备拒绝认证,请核对账号、密码或 AAA 策略"
245
- when :authentication_error then "认证交互未完成,请核对认证方式或设备 AAA 日志"
246
- when :host_key_untrusted then "主机密钥尚未信任,请确认指纹并登记"
247
- when :host_key_changed then "已登记主机密钥发生变化,请核实设备身份"
248
- when :login_timeout then "未在期限内获得登录提示,请检查 SSH 握手与登录交互"
249
- when :connection_timeout then "SSH 连接或握手超时,请检查服务与网络"
250
- when :device_error then "设备拒绝命令,请核对厂商映射和账号权限"
251
- end
252
- end
253
-
254
- # 生成已完成、成功、失败、当前阶段和排队数量摘要。
255
- def status_line
256
- percent = @total.positive? ? @completed * 100 / @total : 0
257
- counts = @operation_mode ? "完成 #{@completed} 待核实 #{@operation_pending} 失败 #{@failed}" : "成功 #{@succeeded} 未完成 #{@failed}"
258
- "#{@completed}/#{@total} #{percent}% | #{counts} | 登录 #{@stages.values.count("登录")} 采集 #{@stages.values.count("采集")} 排队 #{[@total - @completed - @active, 0].max}"
259
- end
260
-
261
- # 读取单调时钟秒数,避免系统校时影响期限与耗时计算。
262
- def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
263
-
264
- # 将秒数格式化为小时、分钟和秒。
265
- def duration(seconds)
266
- total = seconds.round
267
- format("%02d:%02d:%02d", total / 3600, total / 60 % 60, total % 60)
268
- end
269
-
270
- # 吞吐与预计剩余时间使用单调时钟;异构设备的估算不能视为任务期限。
271
- def timing_line
272
- elapsed = [monotonic - (@run_started || @started_at), 0].max
273
- rate = elapsed.positive? ? @completed / elapsed : 0
274
- eta = if @completed == @total && @total.positive?
275
- "00:00:00"
276
- elsif @completed >= 5 && rate.positive?
277
- "约 #{duration((@total - @completed) / rate)}"
278
- else
279
- "估算中"
280
- end
281
- line = "耗时 #{duration(elapsed)} | #{format("%.1f", rate)} 台/秒 | 剩余 #{eta}"
282
- host, started = @task_started.min_by { |_key, value| value }
283
- if started && monotonic - started >= 10
284
- line += " | 最久 #{host} #{@stages[host]} #{(monotonic - started).floor}s"
285
- end
286
- line
287
- end
288
-
289
- # TTY 原地刷新最多每秒五次;详细事件和重定向输出采用独立显示路径。
290
- def refresh(force: false)
291
- return unless @enabled && @tty && !@verbose
292
-
293
- now = monotonic
294
- return if !force && @refreshing && @completed < @total && @last_refresh && now - @last_refresh < 0.2
295
-
296
- @last_refresh = now
297
- divider = fit_terminal("-" * 100)
298
- lines = [divider, fit_terminal(status_line), fit_terminal(timing_line), divider]
299
- return if @refreshing && @last_status == lines
300
-
301
- clear_refresh
302
- @last_status = lines
303
- @refreshing = write_output(lines.join("\n"))
304
- end
305
-
306
- # 留一列避免终端自动换行,窄窗口也不会留下旧进度行。
307
- def fit_terminal(line)
308
- columns = @io.respond_to?(:winsize) ? @io.winsize.last : 120
309
- columns = 120 unless columns.positive?
310
- width = 0
311
- text = line.gsub(/[[:cntrl:]]/, " ")
312
- text.each_char.take_while do |character|
313
- width += character.ord > 255 ? 2 : 1
314
- width < columns
315
- end.join("")
316
- rescue IOError, SystemCallError
317
- line
318
- end
319
-
320
- # 擦除前一次实际显示的行数,避免短文本或窄终端留下旧状态。
321
- def clear_refresh
322
- return unless @refreshing
323
-
324
- write_output("\r\e[2K" + ("\e[1A\r\e[2K" * (@last_status.length - 1)))
325
- @refreshing = false
326
- end
327
-
328
- # 在进度互斥锁内输出一条消息,避免多线程交错刷新。
329
- def write(host, message)
330
- @mutex.synchronize { emit(host, message) }
331
- end
332
-
333
- # 清除旧进度后输出经过控制符过滤的单行消息。
334
- def emit(host, message)
335
- return unless @enabled
336
-
337
- percent = @total.positive? ? " #{(@completed * 100.0 / @total).floor}%" : ""
338
- clear_refresh
339
- line = "[#{Time.now.strftime("%H:%M:%S")}] [#{@completed}/#{@total}#{percent} 执行中 #{@active}] [#{host || "批次"}] #{message}"
340
- line = "[#{Time.now.strftime("%H:%M:%S")}] #{host ? "#{host} " : ""}#{message}" unless @verbose
341
- write_output(line.gsub(/[[:cntrl:]]/, " ") + "\n")
342
- end
343
-
344
- # 显示失败只停用进度输出;批次仍保存回执和事件,并记录一次受控回调诊断。
345
- # 所有调用均持有 @mutex,心跳与设备线程不会重复访问已失败的输出。
346
- def write_output(text)
347
- return false unless @enabled
348
-
349
- @io.write(text)
350
- @io.flush
351
- true
352
- rescue StandardError => error
353
- record_output_error(error)
354
- false
355
- end
356
-
357
- # 保存一次受控输出错误并停用进度,设备任务仍继续保存结果。
358
- def record_output_error(error)
359
- @output_error = { host: nil, error_type: Error::Metadata.type(error.class.name) || "StandardError" }.freeze
360
- @enabled = false
361
- end
362
120
  end
363
121
  end
364
122
  end
@@ -502,8 +502,17 @@ module Net
502
502
  raise ArgumentError, "#{key} must be valid JSON", cause: nil
503
503
  end
504
504
 
505
- # 将有效逗号分隔配置拆分为去空白的非空条目列表。
506
- def list(key) = (value(key) || "").split(",").map(&:strip).reject(&:empty?)
505
+ # 显式空列表可清除筛选;空白或逗号空项不得被删掉后扩大选择范围。
506
+ def list(key)
507
+ text = raw(key)
508
+ return [] if text.nil? || text == ""
509
+ raise ArgumentError, "#{key} must be a String" unless text.is_a?(String)
510
+
511
+ items = text.split(",", -1).map(&:strip)
512
+ raise ArgumentError, "#{key} must not contain empty list entries" if items.any?(&:empty?)
513
+
514
+ items
515
+ end
507
516
 
508
517
  # 将配置转换为正整数,无效时只报告配置键和类型要求。
509
518
  def integer(key, default)
@@ -1,7 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "../../parallel/pool"
4
- require_relative "../../device/interfaces/interface_description"
4
+ require_relative "../../device/interfaces/description"
5
5
 
6
6
  module Net
7
7
  module Connector
@@ -52,14 +52,14 @@ module Net
52
52
  # 使用当前模板和端口展示策略生成缺失或确需修正的目标描述。
53
53
  def description_for(neighbor)
54
54
  port = neighbor.neighbor_interface
55
- port = Net::Connector::Interfaces::InterfaceName.short(port) if abbreviate_ports
55
+ port = Net::Connector::Interfaces::Name.short(port) if abbreviate_ports
56
56
  port = port.downcase if lowercase_ports
57
57
  format(neighbor: neighbor.neighbor_name, port: port)
58
58
  end
59
59
 
60
60
  # 仅显式声明的旧名称前缀可保留;不把未知名称、包含匹配或不同编号当作同一邻居。
61
61
  def description_matches?(current, expected, neighbor)
62
- comparison = Net::Connector::Interfaces::InterfaceDescription
62
+ comparison = Net::Connector::Interfaces::Description
63
63
  return true if comparison.equivalent?(current, expected)
64
64
 
65
65
  neighbor_name_prefixes.any? do |prefix|
@@ -42,7 +42,7 @@ module Net
42
42
 
43
43
  items = items.dup
44
44
  queue = Queue.new
45
- items.each_with_index { |item, index| queue << [index, item] }
45
+ items.each_index { |index| queue << index }
46
46
  count = [items.size, @parallel].min
47
47
  count.times { queue << nil }
48
48
  gate = Queue.new
@@ -62,9 +62,8 @@ module Net
62
62
  # 全部线程成功建立后才允许设备操作,创建失败不能留下已发送的变更。
63
63
  Thread.handle_interrupt(Exception => :immediate) do
64
64
  gate.pop
65
- while (task = queue.pop)
66
- index, item = task
67
- results[index] = yield item
65
+ while (index = queue.pop)
66
+ results[index] = yield items[index]
68
67
  end
69
68
  exhausted = true
70
69
  end