net-connector 0.9.0 → 0.10.0

data/lib/net/connector/netdisco/operations.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "time"
+require "fileutils"
+require_relative "../execution_pool"
+require_relative "../device_session"
+require_relative "../device/topology"
+require_relative "settings"
+require_relative "operation_batch"
+
+module Net
+  module Connector
+    module Netdisco
+      # 配置执行与接口修正共用设备生命周期，各业务仍保留自己的审批和结果。
+      class Operations
+        DEFAULT_SETTING = Object.new.freeze
+        MissingCredentials = Class.new(StandardError)
+        private_constant :DEFAULT_SETTING, :MissingCredentials
+
+        def initialize(settings:, inventory:, credentials: nil, connector_factory: nil)
+          raise ArgumentError, "inventory must respond to call" unless inventory.respond_to?(:call)
+          raise ArgumentError, "credentials must respond to call" unless credentials.nil? || credentials.respond_to?(:call)
+          unless connector_factory.nil? || connector_factory.respond_to?(:call)
+            raise ArgumentError, "connector_factory must respond to call"
+          end
+
+          @settings, @inventory, @credentials = settings, inventory, credentials
+          @connector_factory = connector_factory || ->(device, options) { device.build_connector(**options) }
+        end
+
+        # 全批脚本先解析并固定，明确确认后才查询清单和读取逐设备凭据。
+        def execute_scripts(scripts:, confirmed: false, concurrency: DEFAULT_SETTING, on_start: nil, on_result: nil)
+          validate_confirmation!(confirmed)
+          tasks = normalize_mapping(scripts, :scripts) do |script|
+            script.is_a?(String) ? Script.parse(script) : (script.is_a?(Script) ? script : Script.new(script))
+          end
+          run(:execute_scripts, tasks, concurrency: concurrency, on_start: on_start, on_result: on_result) do |connector, script|
+            result = connector.execute_script(script)
+            raise TypeError, "configuration operation must return a Result" unless result.is_a?(Result)
+
+            result
+          end
+        end
+
+        # 一次调用完成邻居发现与描述同步；每台设备独占会话，普通失败互不影响。
+        def sync_interface_descriptions(hosts:, abbreviate: true, lowercase: false, concurrency: DEFAULT_SETTING,
+                                        on_start: nil, on_result: nil, &formatter)
+          tasks = description_targets(hosts, abbreviate, lowercase)
+          run(:sync_interface_descriptions, tasks, concurrency: concurrency, on_start: on_start, on_result: on_result) do |connector, _|
+            result = connector.sync_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+            raise TypeError, "description synchronization must return a Result" unless result.is_a?(Result)
+
+            result
+          end
+        end
+
+        # 规划只读取现场证据；格式化回调并发执行，不承担设备连接或审批职责。
+        def plan_interface_descriptions(hosts:, abbreviate: true, lowercase: false, concurrency: DEFAULT_SETTING,
+                                        on_start: nil, on_result: nil, &formatter)
+          tasks = description_targets(hosts, abbreviate, lowercase)
+
+          run(:plan_interface_descriptions, tasks, concurrency: concurrency, on_start: on_start, on_result: on_result) do |connector, _|
+            result = connector.plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+            raise TypeError, "description planning must return a Topology::Plan" unless result.is_a?(Topology::Plan)
+
+            copy_plan(result)
+          end
+        end
+
+        # 审批计划整体复制并验证；单设备应用仍执行现场重验、读回和保存，不直接重放 commands。
+        def apply_interface_descriptions(plans:, confirmed: false, concurrency: DEFAULT_SETTING, on_start: nil, on_result: nil)
+          validate_confirmation!(confirmed)
+          tasks = normalize_mapping(plans, :plans) { |plan| copy_plan(plan) }
+          tasks.each do |host, plan|
+            raise ArgumentError, "plan host does not match its target" unless normalize_host(plan.host) == host
+          end
+          run(:apply_interface_descriptions, tasks, concurrency: concurrency, on_start: on_start, on_result: on_result) do |connector, plan|
+            result = connector.apply_interface_descriptions(plan, confirmed: true)
+            raise TypeError, "description application must return a Result" unless result.is_a?(Result)
+
+            result
+          end
+        end
+
+        private
+
+        # 规划与同步共用目标校验，整批输入在清单与连接之前固定。
+        def description_targets(hosts, abbreviate, lowercase)
+          raise ArgumentError, "hosts must be an Array" unless hosts.is_a?(Array)
+          unless [abbreviate, lowercase].all? { |value| value == true || value == false }
+            raise ArgumentError, "description formatting options must be boolean"
+          end
+
+          tasks = normalize_mapping(hosts.to_h { |host| [host, nil] }, :hosts)
+          raise ArgumentError, "hosts must be unique" unless tasks.size == hosts.size
+
+          tasks
+        end
+
+        def validate_confirmation!(confirmed)
+          raise ArgumentError, "configuration changes require confirmed: true" unless confirmed == true
+        end
+
+        # 管理地址规范化之后再检查重复，等价的 IPv6 写法不能创建两个并行写会话。
+        def normalize_host(host)
+          unless host.is_a?(String) && !host.empty? && !host.include?("/")
+            raise ArgumentError, "targets must be IP address Strings without a prefix"
+          end
+
+          IPAddr.new(host).to_s.freeze
+        rescue IPAddr::Error
+          raise ArgumentError, "target contains an invalid IP address", cause: nil
+        end
+
+        def normalize_mapping(mapping, name)
+          raise ArgumentError, "#{name} must be a Hash" unless mapping.is_a?(Hash)
+
+          mapping.each_with_object({}) do |(host, value), tasks|
+            host = normalize_host(host)
+            raise ArgumentError, "targets must be unique" if tasks.key?(host)
+
+            tasks[host] = block_given? ? yield(value) : value
+          end.freeze
+        end
+
+        # 外部审批容器不与执行共享可变子对象，非法领域结构在任何连接前拒绝。
+        def copy_plan(plan)
+          raise ArgumentError, "plans must contain Topology::Plan values" unless plan.is_a?(Topology::Plan)
+          normalize_host(plan.host)
+          unless Net::Connector.vendors.include?(plan.vendor) && plan.evidence.is_a?(Hash) &&
+                 plan.changes.is_a?(Array) && plan.commands.is_a?(Array) && plan.commands.all?(String)
+            raise ArgumentError, "description plan contains invalid fields"
+          end
+          commands = Script.new(plan.commands).map { |command| command.text.dup.freeze }.freeze
+          evidence = plan.evidence.to_h do |interface, fields|
+            unless interface.is_a?(String) && fields.is_a?(Array) && fields.size == 3 && fields.all?(String)
+              raise ArgumentError, "description plan contains invalid evidence"
+            end
+            [interface.dup.freeze, fields.map { |field| field.dup.freeze }.freeze]
+          end.freeze
+          changes = plan.changes.map { |change| copy_change(change) }.freeze
+          raise ArgumentError, "empty description plan cannot contain commands" if changes.empty? && !commands.empty?
+
+          Topology::Plan.new(host: normalize_host(plan.host), vendor: plan.vendor, evidence: evidence,
+                             changes: changes, commands: commands).freeze
+        end
+
+        def copy_change(change)
+          unless change.is_a?(Topology::Change) && change.old_description.is_a?(String) &&
+                 change.neighbor.is_a?(Topology::Neighbor) && change.neighbor.to_h.values.all? { |value| value.is_a?(String) || value.is_a?(Symbol) }
+            raise ArgumentError, "description plan contains an invalid change"
+          end
+          Topology::InterfaceDescription.validate_interface!(change.interface)
+          Topology::InterfaceDescription.validate!(change.new_description)
+          neighbor = Topology::Neighbor.new(**change.neighbor.to_h.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }).freeze
+          Topology::Change.new(interface: change.interface.dup.freeze, old_description: change.old_description.dup.freeze,
+                               new_description: change.new_description.dup.freeze, neighbor: neighbor).freeze
+        end
+
+        # 策略只固定一次；清单与连接使用同一快照，凭据仍在每台任务开始时动态读取。
+        def run(operation, tasks, concurrency:, on_start:, on_result:)
+          [on_start, on_result].each do |callback|
+            raise ArgumentError, "callbacks must respond to call" unless callback.nil? || callback.respond_to?(:call)
+          end
+          ExecutionPool.validate_concurrency!(concurrency) unless concurrency.equal?(DEFAULT_SETTING)
+          snapshot = @settings.snapshot(mode: :inventory)
+          concurrency = snapshot.concurrency if concurrency.equal?(DEFAULT_SETTING)
+          ExecutionPool.validate_concurrency!(concurrency)
+          return empty_batch(operation) if tasks.empty?
+
+          devices = select_devices(tasks, snapshot)
+          FileUtils.mkdir_p(snapshot.log_directory, mode: 0o700) if snapshot.log_directory
+          started_at = Time.now.utc
+          callback_errors = Queue.new
+          outcomes = ExecutionPool.new(concurrency: concurrency).map(devices) do |device|
+            perform(device, snapshot, callback_errors, on_start, on_result) { |connector| yield connector, tasks.fetch(device.host) }
+          end
+          errors = Array.new(callback_errors.size) { callback_errors.pop }
+          OperationBatch.new(operation: operation, outcomes: outcomes, callback_errors: errors,
+                             started_at: started_at, finished_at: Time.now.utc)
+        end
+
+        def empty_batch(operation)
+          now = Time.now.utc
+          OperationBatch.new(operation: operation, outcomes: [], callback_errors: [], started_at: now, finished_at: now)
+        end
+
+        # 所有目标必须唯一、可执行且厂商匹配；后面的无效目标不能在前面设备已写后才发现。
+        def select_devices(tasks, snapshot)
+          inventory = @inventory.call(snapshot)
+          raise ArgumentError, "inventory must return an Array of Devices" unless inventory.is_a?(Array) && inventory.all?(Device)
+
+          by_host = {}
+          duplicates = {}
+          inventory.each do |device|
+            next unless tasks.key?(device.host)
+
+            duplicates[device.host] = true if by_host.key?(device.host)
+            by_host[device.host] = device
+          end
+          tasks.map do |host, value|
+            device = by_host[host]
+            unless device&.ready? && !duplicates.key?(host)
+              raise ArgumentError, "target must identify exactly one ready inventory device"
+            end
+            if value.is_a?(Topology::Plan)
+              Topology.validate_plan!(value, host: device.host, vendor: device.vendor)
+            elsif value.nil?
+              Topology.validate_vendor_support!(host: device.host, vendor: device.vendor, phase: :plan)
+            end
+            device
+          end
+        end
+
+        # 返回失败的 Result 仍携带已完成步骤；设备关闭故障也不能覆盖原操作错误。
+        def perform(device, snapshot, callback_errors, on_start, on_result, &operation)
+          started_at = Time.now.utc
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          notify(on_start, device, callback_errors, device.host)
+          value, error = DeviceSession.call(factory: -> { build_connector(device, snapshot) }) do |connector|
+            result = operation.call(connector)
+            if result.is_a?(Topology::Plan) && (result.host != device.host || result.vendor != device.vendor)
+              raise ArgumentError, "planned evidence does not match its inventory device"
+            end
+            result
+          end
+          error = value.error || error if value.is_a?(Result)
+          status = if error.is_a?(MissingCredentials)
+                     error = nil
+                     :missing_credentials
+                   elsif error
+                     value && (!value.is_a?(Result) || value.success? || !value.steps.empty?) ? :partial : :failed
+                   else
+                     :succeeded
+                   end
+          outcome = OperationOutcome.new(device: device, status: status, value: value, error: error,
+                                         started_at: started_at, finished_at: Time.now.utc,
+                                         duration_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round)
+          notify(on_result, outcome, callback_errors, device.host)
+          outcome
+        end
+
+        def build_connector(device, snapshot)
+          options = @credentials ? @credentials.call(device) : @settings.device_credentials_for(device)
+          raise MissingCredentials if options.nil?
+
+          unless options.is_a?(Hash) && options.keys.all?(Symbol) && !options.key?(:host) &&
+                 options[:username].is_a?(String) && !options[:username].empty?
+            raise ArgumentError, "credential resolver must return settings with username and without host"
+          end
+          options = snapshot.connection_options(device.vendor).merge(options)
+          if snapshot.log_directory
+            options[:log_file] = File.join(snapshot.log_directory, "#{device.host.tr(":", "_")}.log")
+          end
+          @connector_factory.call(device, options)
+        end
+
+        # 普通通知故障只保存白名单类型；中断仍由线程池回收整批设备会话。
+        def notify(callback, value, errors, host)
+          callback&.call(value)
+        rescue StandardError => error
+          errors << { host: host, error_type: Diagnostic.from(error).error_type }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/planner.rb

@@ -16,28 +16,16 @@ module Net
         # 生成本地或 TFTP 备份计划，明确记录每台未执行设备的原因。
         def call(mode:, limit_per_vendor:, allow_fixed_name_reuse: false)
           self.class.validate_limit!(limit_per_vendor)
-          ready_tasks = @inventory.each_with_index.filter_map do |device, index|
-            [index, device] if device.ready?
-          end
-          selected_tasks = if limit_per_vendor
-                             ready_tasks.group_by { |_index, device| device.vendor }.values.flat_map do |tasks|
-                               tasks.min_by(limit_per_vendor) { |_index, device| device.host }
-                             end
-                           else
-                             ready_tasks
-                           end
-          selected_indices = selected_tasks.to_h { |index, _device| [index, true] }
-          first_index_by_filename = {}
-          if mode == :tftp
-            # 先按采样顺序保留每个目标的首台设备，再按清单顺序输出结果。
-            selected_tasks.each { |index, device| first_index_by_filename[device.tftp_filename] ||= index }
-          end
+          # 默认全量不构造采样任务副本或逐设备选择索引；只保留最终计划需要的槽位。
+          selected_tasks = sample_tasks(limit_per_vendor)
+          selected_indices = selected_tasks&.to_h { |index, _device| [index, true] }
+          first_index_by_filename = mode == :tftp ? tftp_target_indices(selected_tasks) : {}
           outcomes = Array.new(@inventory.size)
           ready = @inventory.each_with_index.filter_map do |device, index|
             if !device.ready?
               outcomes[index] = skipped(device, device.issue)
               nil
-            elsif !selected_indices.key?(index)
+            elsif selected_indices && !selected_indices.key?(index)
               outcomes[index] = skipped(device, :sample_limit)
               nil
             elsif mode == :tftp && first_index_by_filename.fetch(device.tftp_filename) != index &&
@@ -61,6 +49,27 @@ module Net
 
         private
 
+        # 只有显式采样才分组；厂商组内仍按管理地址选择，与全量输出顺序分开。
+        def sample_tasks(limit)
+          return unless limit
+
+          tasks = @inventory.each_with_index.filter_map { |device, index| [index, device] if device.ready? }
+          tasks.group_by { |_index, device| device.vendor }.values.flat_map do |group|
+            group.min_by(limit) { |_index, device| device.host }
+          end
+        end
+
+        # 采样模式按采样顺序仲裁目标，全量模式直接扫描清单；输出仍保留清单顺序。
+        def tftp_target_indices(selected_tasks)
+          found = {}
+          if selected_tasks
+            selected_tasks.each { |index, device| found[device.tftp_filename] ||= index }
+          else
+            @inventory.each_with_index { |device, index| found[device.tftp_filename] ||= index if device.ready? }
+          end
+          found
+        end
+
         # 构建计划阶段无需设备连接的跳过结果。
         def skipped(device, status)
           Outcome.new(device: device, status: status, backup: nil, error_code: nil, error_type: nil)

data/lib/net/connector/netdisco/progress.rb

@@ -3,6 +3,7 @@
 require "io/console"
 require_relative "../engine/error_metadata"
 require_relative "../engine/log/event"
+require_relative "../background_task"
 
 module Net
   module Connector
@@ -127,13 +128,13 @@ module Net
         end
 
         # 心跳只负责显示；退出、异常或中断时先唤醒并回收线程。
-        def with_updates
+        def with_updates(&)
           return yield unless @enabled && @tty && !@verbose
 
           lock = Mutex.new
           signal = ConditionVariable.new
           stopped = false
-          worker = Thread.new do
+          task = lambda do
             loop do
               stop = lock.synchronize do
                 signal.wait(lock, 1) unless stopped
@@ -143,13 +144,20 @@ module Net
 
               tick
             end
+          rescue StandardError => error
+            # 非 IO 的显示故障也只停用进度；完整报告仍记录这一受控诊断。
+            @mutex.synchronize { record_output_error(error) }
           end
-          yield
+          stop = -> { lock.synchronize { stopped = true; signal.broadcast } }
+          BackgroundTask.run(task: task, stop: stop, &)
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 后台已回收，最后清屏也不能覆盖原业务故障或取消。
+          primary_failure = error
+          raise
         ensure
-          if worker
-            lock.synchronize { stopped = true; signal.broadcast }
-            worker.value
-            @mutex.synchronize { clear_refresh }
+          begin
+            Thread.handle_interrupt(Exception => :never) { @mutex.synchronize { clear_refresh } if task }
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 清屏中的取消正常传播，已有主故障时保持其身份。
+            raise error unless primary_failure
           end
         end
 
@@ -268,11 +276,15 @@ module Net
           @io.write(text)
           @io.flush
           true
-        rescue IOError, SystemCallError => error
-          @output_error = { host: nil, error_type: ErrorMetadata.type(error.class.name) }.freeze
-          @enabled = false
+        rescue StandardError => error
+          record_output_error(error)
           false
         end
+
+        def record_output_error(error)
+          @output_error = { host: nil, error_type: ErrorMetadata.type(error.class.name) || "StandardError" }.freeze
+          @enabled = false
+        end
       end
     end
   end

data/lib/net/connector/netdisco/settings.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require "json"
+require "digest"
 require_relative "../../connector"
+require_relative "../execution_pool"
 require_relative "client"
 require_relative "database_client"
+require_relative "inventory_cache"
 require_relative "config_file"
 require_relative "rules"
 require_relative "planner"
@@ -14,10 +17,10 @@ module Net
       # 活的凭据来源与不可变的批次策略分开保存；只有明确列出的非敏感字段进入快照。
       class Settings
         DEFAULT_BACKUP_DIRECTORY = "backups"
-        DEFAULT_CONCURRENCY = 4
-        MAX_CONCURRENCY = 50
+        DEFAULT_CONCURRENCY = ExecutionPool::DEFAULT_CONCURRENCY
+        MAX_CONCURRENCY = ExecutionPool::MAX_CONCURRENCY
         # 这里只列可从环境读取的公开策略；凭据单独动态读取，其他内部键只供 YAML/CLI 使用。
-        ENVIRONMENT_KEYS = %w[ND_URL].freeze
+        ENVIRONMENT_KEYS = %w[ND_URL ND_CACHE_TTL NC_CONCURRENCY].freeze
         DEFAULT_PAGE_SIZE = Client::DEFAULTS.fetch(:page_size)
         UNSET = Object.new.freeze
         private_constant :UNSET
@@ -80,6 +83,7 @@ module Net
           return self if mode == :export
 
           client_options
+          inventory_cache_options
           rules
           concurrency
           limit_per_vendor
@@ -107,7 +111,9 @@ module Net
               values[key] = item if item
             end
             connection.merge!(user: credentials[:username], password: credentials[:password]) if credentials
-            return DatabaseClient.new(connection_options: connection, **options)
+            client = DatabaseClient.new(connection_options: connection, **options)
+            identity = [:postgres, connection.except(:password), options.slice(:query, :query_params)]
+            return cached_client(client, policy, identity)
           end
           raise ArgumentError, "ND_URL is required" unless options.fetch(:url)
 
@@ -118,7 +124,9 @@ module Net
                            else
                              { username: required_secret("ND_USERNAME"), password: required_secret("ND_PASSWORD") }
                            end
-          Client.new(**options, **authentication)
+          client = Client.new(**options, **authentication)
+          identity = [:http, Client.validate_url!(options.fetch(:url)).normalize.to_s, authentication.except(:password)]
+          cached_client(client, policy, identity)
         end
 
         # 清单来源来自 YAML/CLI，HTTP 与 PostgreSQL 共用后续计划和执行接口。
@@ -136,6 +144,16 @@ module Net
           inventory_source == :postgres ? postgres_options(options) : http_options(options)
         end
 
+        # 默认三天，可由环境覆盖；缓存策略随批次固定，不缓存设备凭据或业务计划。
+        def inventory_cache_options
+          directory = raw("ND_CACHE_DIRECTORY", ".cache/net-connector/inventory")
+          unless directory.is_a?(String) && !directory.empty? && !directory.include?("\0")
+            raise ArgumentError, "netdisco.cache_directory must be a nonempty path without NUL"
+          end
+          { directory: File.expand_path(directory), ttl: number("ND_CACHE_TTL", InventoryCache::DEFAULT_TTL),
+            enabled: boolean("ND_CACHE_ENABLED", true) }.freeze
+        end
+
         # 将筛选和映射策略交给 Rules 校验，未识别设备由清单结果单独标记。
         def rules
           Rules.new(include_hosts: list("NC_INCLUDE_HOSTS"),
@@ -278,7 +296,7 @@ module Net
         # 只输出公开策略；数据库身份和设备凭据不得通过配置摘要进入报告。
         def config_hash
           {
-            netdisco: client_options.merge(source: inventory_source, database: database_options),
+            netdisco: client_options.merge(source: inventory_source, database: database_options, cache: inventory_cache_options),
             backup: { directory: backup_directory, concurrency: concurrency, limit_per_vendor: limit_per_vendor },
             inventory: { include_hosts: list("NC_INCLUDE_HOSTS"),
                          exclude_hosts: list("NC_EXCLUDE_HOSTS"),
@@ -310,6 +328,18 @@ module Net
 
         private
 
+        # 身份指纹只用于隔离缓存；凭据、SQL 和参数均不写入缓存文件或摘要。
+        def cached_client(client, policy, identity)
+          cache = policy.inventory_cache_options
+          return client unless cache.fetch(:enabled)
+
+          options = policy.client_options
+          InventoryCache.new(client: client, **cache.except(:enabled),
+                             identity: Digest::SHA256.hexdigest(JSON.generate(identity)),
+                             **options.slice(:max_inventory_bytes, :max_devices),
+                             lock_timeout: [5, options.fetch(:inventory_timeout)].min)
+        end
+
         def client_budget_options(defaults)
           defaults.to_h do |name, default|
             key = "ND_#{name.to_s.upcase}"

data/lib/net/connector/netdisco/tftp_archive.rb

@@ -68,7 +68,8 @@ module Net
             receipt = outcome.backup
             return outcome unless receipt.is_a?(TftpReceipt) && receipt.path
 
-            verified = @verifier.verify_outcome(outcome.with(started_at: started_at), started_at: upload_started_at, previous: previous)
+            verified = @verifier.verify_outcome(outcome.with(started_at: started_at), started_at: upload_started_at,
+                                                previous: previous, expected_path: remote_filename)
             return outcome.success? ? archive_failure(outcome) : outcome unless verified.backup.verification == :server_verified
 
             archive_uploaded_file(verified)

data/lib/net/connector/netdisco/tftp_verification.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "../storage/safe_file"
+require_relative "../storage/backup_lock"
 require_relative "../device/tftp/receipt"
+require_relative "diagnostic"
+require "tempfile"
 
 module Net
   module Connector
@@ -12,31 +15,53 @@ module Net
           @root = root && File.realpath(root)
         end
 
-        def call(report)
-          return report unless @root
+        # 基线、设备上传和核验共用目标锁；只有上传后变化的文件才属于本次任务。
+        def upload_and_verify(device, path: device.tftp_filename)
+          outcome = nil
+          raise ArgumentError, "upload requires a block" unless block_given?
 
-          outcomes = report.outcomes.map do |outcome|
-            receipt = outcome.backup
-            next outcome unless receipt.is_a?(TftpReceipt) && receipt.path && outcome.started_at
+          TftpTarget.validate_path!(path)
+          return yield path unless @root
 
-            verify(outcome, receipt)
+          destination = server_path(path)
+          Storage::BackupLock.synchronize(destination, host: device.host, timeout: 240) do
+            previous = Storage::SafeFile.open(destination, missing: true) { |_file, stat| stat }
+            started_at = Tempfile.create(".net-connector-upload-", @root) { |file| file.stat.mtime }
+            outcome = yield path
+            outcome = verify_outcome(outcome, started_at: started_at, previous: previous, expected_path: path)
           end
-          report.with(outcomes: outcomes.freeze)
+        rescue StandardError => error
+          raise unless outcome
+          return outcome unless outcome.success?
+
+          # 上传后的核验或解锁故障保留回执，不能让 Worker 把已上传结果退回普通失败。
+          diagnostic = Diagnostic.from(error, backup: outcome.backup, phase: :tftp_backup)
+          outcome.with(status: :reported_with_error, error_code: diagnostic.error_code,
+                       error_type: diagnostic.error_type, diagnostic: diagnostic)
         end
 
-        def verify_outcome(outcome, started_at: outcome.started_at, previous: nil)
+        # 调用者必须在目标锁内先捕获基线；nil 明确表示上传前文件缺失，不能事后猜测。
+        def verify_outcome(outcome, started_at:, previous:, expected_path:)
           return outcome unless @root && started_at && outcome.backup.is_a?(TftpReceipt) && outcome.backup.path
+          return outcome unless outcome.backup.path == expected_path
 
           verify(outcome, outcome.backup, started_at: started_at, previous: previous)
         end
 
         private
 
-        def verify(outcome, receipt, started_at: outcome.started_at, previous: nil)
-          path = File.join(@root, receipt.path)
+        def server_path(relative_path)
+          path = File.join(@root, relative_path)
           parent = File.realpath(File.dirname(path))
-          return outcome unless parent == @root || parent.start_with?(@root + File::SEPARATOR)
+          unless parent == @root || parent.start_with?(@root + File::SEPARATOR)
+            raise ArgumentError, "TFTP verification path escaped its root"
+          end
+
+          path
+        end
 
+        def verify(outcome, receipt, started_at:, previous:)
+          path = server_path(receipt.path)
           size = nil
           fingerprint = Storage::SafeFile.open(path, missing: true) do |file, stat|
             next unless stat.size.positive? && stat.mtime >= started_at

data/lib/net/connector/netdisco/worker.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "settings"
+require_relative "../execution_pool"
 
 module Net
   module Connector
@@ -9,11 +9,7 @@ module Net
       class Worker
         # 内部预检与实际执行共用规则，不为校验创建工作线程池对象。
         def self.validate_concurrency!(concurrency)
-          unless concurrency.is_a?(Integer) && (1..Settings::MAX_CONCURRENCY).cover?(concurrency)
-            raise ArgumentError, "concurrency must be an Integer in 1..#{Settings::MAX_CONCURRENCY}"
-          end
-
-          concurrency
+          ExecutionPool.validate_concurrency!(concurrency)
         end
 
         # 校验并保存最大设备并发数。
@@ -23,47 +19,12 @@ module Net
 
         # 按清单顺序收集结果，并隔离设备及回调异常。
         def run(tasks, outcomes:, on_error:, on_start: nil, on_result: nil)
-          queue = Queue.new
-          tasks.each { |task| queue << task }
-          worker_count = [tasks.size, @concurrency].min
-          worker_count.times { queue << nil }
           callback_errors = Queue.new
-          finished = Queue.new
-          threads = []
-          completed = false
-          begin
-            # 创建线程也属于批次生命周期；后续创建失败时要关闭已有任务。
-            worker_count.times do
-              threads << Thread.new do
-                Thread.current.report_on_exception = false
-                while (task = queue.pop)
-                  index, device = task
-                  result = run_task(device, on_error, on_start, callback_errors) { yield device }
-                  outcomes[index] = result
-                  Array(on_result).each do |callback|
-                    notify(callback, result, host: device.host, errors: callback_errors)
-                  end
-                end
-              ensure
-                finished << Thread.current
-              end
-            end
-            # 按完成顺序观察失败，避免后启动线程的中断被前面的慢设备阻塞。
-            # 结果仍写回清单槽位，完成通知不会改变公开结果的顺序。
-            worker_count.times { finished.pop.value }
-            completed = true
-          ensure
-            # 中断或某个 worker 抛出非 StandardError 时，不让其他设备任务
-            # 在调用方已经退出后继续运行；Thread#kill 会执行任务自身的 ensure。
-            unless completed
-              threads.each(&:kill)
-              threads.each do |thread|
-                begin
-                  thread.join
-                rescue Exception # rubocop:disable Lint/RescueException -- 等待全部工作线程停止，不让收尾异常覆盖原中断。
-                  nil
-                end
-              end
+          ExecutionPool.new(concurrency: @concurrency).map(tasks) do |index, device|
+            result = run_task(device, on_error, on_start, callback_errors) { yield device }
+            outcomes[index] = result
+            Array(on_result).each do |callback|
+              notify(callback, result, host: device.host, errors: callback_errors)
             end
           end
           Array.new(callback_errors.size) { callback_errors.pop }.freeze

data/lib/net/connector/vendor/h3c/topology.rb

@@ -43,7 +43,7 @@ module Net
           lines = neighbor_lines(output)
           return unless lines.all? do |line|
             interface = line.split.fetch(local_column, nil)
-            interface&.match?(/\A[A-Za-z][A-Za-z-]*\d+(?:\/\d+)+\z/)
+            interface&.match?(/\A(?:[A-Za-z][A-Za-z-]*\d+(?:\/\d+)+|(?:Bridge-Aggregation|BAGG|Route-Aggregation|RAGG)\d+)(?:[:.]\d+)*\z/i)
           end
 
           lines.size