net-connector 0.4.0 → 0.4.2

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

@@ -10,7 +10,13 @@ module Net
       class ConfigFile
         FIELDS = {
           "netdisco" => { "url" => ["NETDISCO_URL", :string],
-                          "page_size" => ["NETDISCO_PAGE_SIZE", :integer] },
+                          "page_size" => ["NETDISCO_PAGE_SIZE", :integer],
+                          "max_pages" => ["NETDISCO_MAX_PAGES", :integer],
+                          "max_response_bytes" => ["NETDISCO_MAX_RESPONSE_BYTES", :integer],
+                          "max_inventory_bytes" => ["NETDISCO_MAX_INVENTORY_BYTES", :integer],
+                          "max_devices" => ["NETDISCO_MAX_DEVICES", :integer],
+                          "inventory_timeout" => ["NETDISCO_INVENTORY_TIMEOUT", :number],
+                          "allow_insecure_http" => ["NETDISCO_ALLOW_INSECURE_HTTP", :boolean] },
           "backup" => { "directory" => ["NET_CONNECTOR_BACKUP_DIRECTORY", :string],
                         "concurrency" => ["NET_CONNECTOR_CONCURRENCY", :integer],
                         "limit_per_vendor" => ["NET_CONNECTOR_SAMPLE_PER_VENDOR", :integer] },
@@ -21,12 +27,16 @@ module Net
                            "host_overrides" => ["NET_CONNECTOR_HOST_OVERRIDES", :json],
                            "device_rules" => ["NET_CONNECTOR_DEVICE_RULES", :json] },
           "ssh" => { "protocol" => ["NET_CONNECTOR_PROTOCOL", :string],
+                     "max_script_output_bytes" => ["NET_CONNECTOR_MAX_SCRIPT_OUTPUT_BYTES", :optional_integer],
                      "known_hosts" => ["NET_CONNECTOR_KNOWN_HOSTS", :string],
                      "host_key_policy" => ["NET_CONNECTOR_HOST_KEY_POLICY", :string],
                      "log_directory" => ["NET_CONNECTOR_LOG_DIRECTORY", :string],
                      "log_level" => ["NET_CONNECTOR_LOG_LEVEL", :string] },
           "tftp" => { "server" => ["TFTP_HOST", :string],
-                      "vrfs" => ["NET_CONNECTOR_TFTP_VRFS", :json] }
+                      "vrfs" => ["NET_CONNECTOR_TFTP_VRFS", :json],
+                      "h3c_source_file" => ["NET_CONNECTOR_H3C_TFTP_SOURCE_FILE", :string],
+                      "h3c_wireless_source_file" => ["NET_CONNECTOR_H3C_WIRELESS_TFTP_SOURCE_FILE", :string],
+                      "huawei_source_file" => ["NET_CONNECTOR_HUAWEI_TFTP_SOURCE_FILE", :string] }
         }.freeze
 
         # 安全读取 YAML 配置并映射到环境变量格式。
@@ -52,7 +62,7 @@ module Net
             end
           end
         rescue Psych::Exception => error
-          raise ArgumentError, "invalid YAML config (#{error.class})"
+          raise ArgumentError, "invalid YAML config (#{error.class})", cause: nil
         end
 
         # 按字段类型校验并编码单项配置。
@@ -62,9 +72,21 @@ module Net
             raise ArgumentError, "#{section}.#{name} must be a nonempty String" unless value.is_a?(String) && !value.strip.empty?
 
             value
-          when :integer
+          when :integer, :optional_integer
+            return nil if type == :optional_integer && value.nil?
+
             raise ArgumentError, "#{section}.#{name} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
 
+            value.to_s
+          when :number
+            unless value.is_a?(Numeric) && value.real? && value.finite? && value.positive? && value.to_f.finite?
+              raise ArgumentError, "#{section}.#{name} must be a positive finite number"
+            end
+
+            value.to_s
+          when :boolean
+            raise ArgumentError, "#{section}.#{name} must be true or false" unless [true, false].include?(value)
+
             value.to_s
           when :list
             unless value.is_a?(Array) && value.all? { |item| item.is_a?(String) && !item.empty? && !item.include?(",") }

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

@@ -48,18 +48,14 @@ module Net
 
         # 生成设备 CLI 可用的 ASCII 远端文件名。
         def tftp_filename
-          return "running-config.xml" if vendor == :palo_alto
-
           label = name.to_s.encode(Encoding::US_ASCII, invalid: :replace, undef: :replace, replace: "-")
                       .gsub(/[^A-Za-z0-9._-]+/, "-").byteslice(0, 180)
                       .gsub(/\A[._-]+|[._-]+\z/, "")
           label = vendor&.to_s || "device" if label.empty?
-          extension = case vendor
-                      when :radware then "tgz"
-                      when :hillstone then "dat"
-                      else "cfg"
-                      end
-          TftpTarget.filename(host, extension: extension, label: label)
+          strategy = Net::Connector.vendor_class(vendor).profile.tftp_strategy if vendor
+          # 旧版自定义策略只需实现实例接口，缺少命名接口时沿用通用 cfg 名称。
+          strategy = Operations::Tftp::Strategy unless strategy.respond_to?(:filename)
+          TftpTarget.validate_path!(strategy.filename(host, label: label))
         end
 
         # 按厂商及设备地址实例化连接器。

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Netdisco
+      # 报告是新的诊断通道：只接受固定词表，不展开异常消息、调用栈、命令、source 或 line。
+      Diagnostic = Data.define(:error_code, :error_type, :phase, :underlying_type,
+                               :artifact_state, :artifact_phase, :verification)
+
+      class Diagnostic
+        CONNECTOR_TYPES = %w[Error ConnectionError AuthenticationError LoginTimeout CommandTimeout WriteTimeout
+                             PromptError ConnectionClosed TransportError DeviceError ScriptError InternalError
+                             OutputLimitExceeded ScriptOutputLimitExceeded SessionBusy UnsupportedOperation LogError ParsingError BackupBusy
+                             BackupPersistenceError TftpCompletionError SavedConfigChanged].freeze
+        TYPES = (CONNECTOR_TYPES.map { |name| "Net::Connector::#{name}" } +
+          %w[StandardError RuntimeError ArgumentError TypeError IOError EOFError SystemCallError ThreadError
+             RangeError KeyError IndexError NoMethodError NameError FrozenError NotImplementedError
+             Timeout::Error IO::TimeoutError Errno::EIO Errno::EACCES Errno::EPERM Errno::ENOSPC Errno::EROFS
+             Errno::ENOENT Errno::ENOTDIR Errno::EISDIR Errno::ELOOP Errno::EINVAL Errno::ENOSYS
+             Errno::ENOTSUP Errno::EOPNOTSUPP Errno::ETIMEDOUT Errno::ECONNREFUSED Errno::ECONNRESET
+             Net::Connector::Operations::PrivateFile::WriteError
+             Net::Connector::Operations::PrivateFile::PersistenceError
+             Net::Connector::Operations::PrivateFile::DirectorySyncUnsupported]).freeze
+        CODES = (CONNECTOR_TYPES.map { |name| name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym } +
+          %i[authentication_failed connection_failed connection_refused no_route connection_reset
+             connection_timeout host_key_changed host_key_untrusted rsa_too_small unsupported_cipher
+             ambiguous_description ambiguous_neighbor confirmation_required description_stages_unsupported
+             description_unconfirmed description_unsupported incomplete_configuration interface_missing
+             neighbor_discovery_unsupported parse_failed invalid_output_encoding persistence_unconfirmed stale_plan startup_config_missing
+             template_invalid template_missing template_unreadable transfer_failed transfer_finalize_failed
+             transfer_path_mismatch transfer_path_unconfirmed transfer_unconfirmed uncommitted_configuration
+             unrecognized_output unsupported_configuration_format verification_plan_changed candidate_isolation_unavailable
+             backup_durability_unsupported backup_finalize_failed backup_persistence_unconfirmed
+             file_finalize_failed file_persistence_unconfirmed file_write_failed directory_sync_unsupported]).freeze
+        PHASES = %i[connect login enable command script read write close logging backup collect discover parse
+                    plan apply verify persist tftp_backup report callback].freeze
+        ARTIFACT_STATES = %i[not_committed committed durable reported_uploaded].freeze
+        ARTIFACT_PHASES = %i[resolve_parent temporary_file write file_sync rename directory_open directory_sync
+                            cleanup complete path finalize].freeze
+        private_constant :CONNECTOR_TYPES, :TYPES, :CODES, :PHASES, :ARTIFACT_STATES, :ARTIFACT_PHASES
+
+        # 包括手工构造的结果在内，v2 都不能携带自由文本诊断值。
+        def initialize(error_code: nil, error_type: nil, phase: nil, underlying_type: nil,
+                       artifact_state: nil, artifact_phase: nil, verification: nil)
+          super(error_code: CODES.include?(error_code) ? error_code : nil,
+                error_type: self.class.type(error_type), phase: PHASES.include?(phase) ? phase : nil,
+                underlying_type: self.class.type(underlying_type),
+                artifact_state: ARTIFACT_STATES.include?(artifact_state) ? artifact_state : nil,
+                artifact_phase: ARTIFACT_PHASES.include?(artifact_phase) ? artifact_phase : nil,
+                verification: verification == :device_reported ? verification : nil)
+        end
+
+        def self.type(name)
+          return if name.nil?
+
+          name.instance_of?(String) && TYPES.include?(name) ? name.dup.freeze : "StandardError"
+        end
+
+        # 读取已知错误的白名单属性后立即丢弃异常引用，不把回调对象保留进批次。
+        def self.from(error, backup: nil, phase: nil)
+          return unless error
+
+          fields = { error_type: type(error.class.name) || "StandardError", phase: phase }
+          if error.is_a?(Net::Connector::Error)
+            fields.merge!(error_code: error.code, phase: phase || error.phase)
+            fields[:underlying_type] = error.underlying.type if error.underlying.instance_of?(UnderlyingError)
+          end
+          new(**fields.merge(completion_fields(error, backup, phase)))
+        rescue StandardError
+          new(error_type: "StandardError", phase: phase)
+        end
+
+        def self.completion_fields(error, backup, phase)
+          if error.instance_of?(BackupPersistenceError) && backup.instance_of?(Backup) && error.backup.equal?(backup)
+            { artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,
+              underlying_type: error.underlying_type }
+          elsif error.instance_of?(TftpCompletionError) && backup.instance_of?(TftpBackup) && error.transfer.equal?(backup)
+            { artifact_state: :reported_uploaded, artifact_phase: error.code == :transfer_finalize_failed ? :finalize : :path,
+              verification: :device_reported, underlying_type: error.underlying_type }
+          elsif phase == :report && Operations::PrivateFile.receipt_error?(error)
+            { error_code: error.code, artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,
+              underlying_type: error.underlying_type }
+          else
+            {}
+          end
+        end
+        private_class_method :completion_fields
+      end
+    end
+  end
+end

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

@@ -8,90 +8,117 @@ module Net
     module Netdisco
       # 基于已验证的清单快照组织有上限的并发备份。
       class Fleet
+        DEFAULT_SETTING = Object.new.freeze
+        private_constant :DEFAULT_SETTING
+
         # 组装清单客户端、规则、凭据与结果存储。
         def initialize(client: nil, settings: Settings.new, rules: nil, credentials: nil, connector_factory: nil,
                        result_store: ResultStore::Text.new)
           @settings = settings
-          @client = client || settings.client
-          @rules = rules || settings.rules
-          @credentials = credentials || settings.method(:credentials_for)
+          @client = client
+          @rules = rules
+          @credentials = credentials
           @connector_factory = connector_factory || ->(device, connection_settings) { device.connector(**connection_settings) }
           @result_store = result_store
-          raise ArgumentError, "credentials must respond to call" unless @credentials.respond_to?(:call)
+          raise ArgumentError, "credentials must respond to call" if @credentials && !@credentials.respond_to?(:call)
           raise ArgumentError, "result_store must respond to write" if result_store && !result_store.respond_to?(:write)
         end
 
         # 拉取并标记重复管理地址的设备清单。
         def devices
-          rows = @client.devices
-          raise Client::Error, "Netdisco returned an invalid device inventory" unless rows.is_a?(Array)
-
-          devices = rows.map { |row| Device.from_row(row, rules: @rules) }
-          duplicates = devices.group_by(&:host).reject { |host, entries| host.nil? || entries.size == 1 }
-          devices.map do |device|
-            duplicates.key?(device.host) ? device.with(issue: :duplicate_host) : device
-          end.freeze
+          inventory(@settings.snapshot(mode: :inventory))
         end
 
         # 规划本地配置备份的设备集合。
         def plan_backup(limit_per_vendor: nil)
-          Planner.new(devices).call(mode: :backup, limit_per_vendor: limit_per_vendor)
+          build_plan(:backup, limit_per_vendor, @settings.snapshot(mode: :backup))
         end
 
         # 规划 TFTP 配置备份的设备集合。
         def plan_tftp_backup(limit_per_vendor: 5)
-          Planner.new(devices).call(mode: :tftp, limit_per_vendor: limit_per_vendor)
+          build_plan(:tftp, limit_per_vendor, @settings.snapshot(mode: :tftp))
         end
 
         # 先拉取完整清单，再并发采集并保存设备配置。
-        def backup_all(directory: @settings.backup_directory, concurrency: @settings.concurrency,
-                       limit_per_vendor: nil, plan: nil, on_start: nil, on_result: nil, on_change: nil)
+        def backup_all(directory: DEFAULT_SETTING, concurrency: DEFAULT_SETTING,
+                       limit_per_vendor: nil, plan: nil, on_start: nil, on_result: nil, on_change: nil,
+                       success_policy: :strict, report_schema: nil)
+          reporting = Report.options(policy: success_policy, schema: report_schema)
+          policy = @settings.snapshot(mode: :backup)
+          directory = policy.backup_directory if directory.equal?(DEFAULT_SETTING)
+          concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
           raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty?
+          Worker.new(concurrency: concurrency)
           Planner.validate_limit!(limit_per_vendor)
           validate_callback!(on_result, :on_result)
           validate_callback!(on_start, :on_start)
           validate_callback!(on_change, :on_change)
 
-          plan ||= plan_backup(limit_per_vendor: limit_per_vendor)
+          plan ||= build_plan(:backup, limit_per_vendor, policy)
           validate_plan!(plan, :backup)
           callbacks = [on_result]
           callbacks << ->(item) { on_change.call(item) if item.backup.is_a?(Backup) && item.backup.changed? } if on_change
           target_directory = File.expand_path(directory)
+          saved_config = Operations::SavedConfig.new(directory: target_directory, indexed: true)
           run_batch(:backup, plan, concurrency: concurrency, report_directory: directory,
-                   output_directory: target_directory, on_start: on_start, on_result: callbacks.compact) do |device, log_directory|
-            backup_one(device, target_directory, log_directory)
+                    output_directory: target_directory, policy: policy, reporting: reporting,
+                    on_start: on_start, on_result: callbacks.compact) do |device, log_directory|
+            backup_one(device, target_directory, log_directory, policy, saved_config)
           end
         end
 
-        # 让设备主动导出配置，避免 PAN-OS 固定远端文件名在同批任务中冲突。
-        def tftp_backup_all(server:, source_files: {}, concurrency: @settings.concurrency,
+        # 让设备主动导出配置，在执行前检查同批目标文件名冲突。
+        def tftp_backup_all(server:, source_files: {}, concurrency: DEFAULT_SETTING,
                             limit_per_vendor: 5, vrfs: {}, on_start: nil, on_result: nil, plan: nil,
-                            report_directory: @settings.backup_directory)
-          TftpTarget.new(host: server, path: "preflight.cfg")
+                            report_directory: DEFAULT_SETTING, success_policy: :strict, report_schema: nil)
+          reporting = Report.options(policy: success_policy, schema: report_schema)
+          policy = @settings.snapshot(mode: :tftp)
+          concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
+          report_directory = policy.backup_directory if report_directory.equal?(DEFAULT_SETTING)
+          Worker.new(concurrency: concurrency)
+          server = TftpTarget.new(host: server, path: "preflight.cfg").host
           raise ArgumentError, "source_files must be a Hash" unless source_files.is_a?(Hash)
           source_files.each_value { |source_file| TftpTarget.validate_source_file!(source_file) }
-          validate_vrfs!(vrfs)
+          source_files = source_files.transform_values { |value| value.dup.freeze }.freeze
+          vrfs = Settings.validate_vrfs!(vrfs).transform_values { |value| value.dup.freeze }.freeze
           Planner.validate_limit!(limit_per_vendor)
           validate_callback!(on_result, :on_result)
           validate_callback!(on_start, :on_start)
 
-          plan ||= plan_tftp_backup(limit_per_vendor: limit_per_vendor)
+          plan ||= build_plan(:tftp, limit_per_vendor, policy)
           validate_plan!(plan, :tftp)
           run_batch(:tftp, plan, concurrency: concurrency, report_directory: report_directory,
-                    on_start: on_start, on_result: on_result) do |device, log_directory|
-            tftp_backup_one(device, server, source_files, log_directory, vrfs)
+                    policy: policy, reporting: reporting, on_start: on_start, on_result: on_result) do |device, log_directory|
+            tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
           end
         end
 
         private
 
+        # 策略在清单请求之前固定；注入的清单客户端仍由调用方负责其自身生命周期。
+        def inventory(policy)
+          rows = (@client || @settings.client(policy: policy)).devices
+          raise Client::Error, "Netdisco returned an invalid device inventory" unless rows.is_a?(Array)
+
+          rules = @rules || policy.rules
+          devices = rows.map { |row| Device.from_row(row, rules: rules) }
+          duplicates = devices.group_by(&:host).reject { |host, entries| host.nil? || entries.size == 1 }
+          devices.map { |device| duplicates.key?(device.host) ? device.with(issue: :duplicate_host) : device }.freeze
+        end
+
+        def build_plan(mode, limit, policy)
+          Planner.validate_limit!(limit)
+          Planner.new(inventory(policy)).call(mode: mode, limit_per_vendor: limit)
+        end
+
         # 统一组织设备任务、日志目录与报告；Worker 保证单台设备失败不影响其他设备。
-        def run_batch(mode, plan, concurrency:, report_directory:, on_start:, on_result:, output_directory: nil)
+        def run_batch(mode, plan, concurrency:, report_directory:, policy:, reporting:, on_start:, on_result:, output_directory: nil)
           worker = Worker.new(concurrency: concurrency)
           started_at = Time.now.utc
+          started = monotonic
           outcomes = plan.outcomes.dup
           FileUtils.mkdir_p(output_directory, mode: 0o700) if output_directory && !plan.ready.empty?
-          log_directory = @settings.log_directory
+          log_directory = policy.log_directory
           FileUtils.mkdir_p(log_directory, mode: 0o700) if log_directory && !plan.ready.empty?
           callback_errors = worker.run(plan.ready, outcomes: outcomes, on_start: on_start, on_result: on_result,
                                        on_error: ->(device, error) { outcome(device, :failed, error: error) }) do |device|
@@ -100,9 +127,14 @@ module Net
           batch = Batch.new(mode: mode, outcomes: outcomes.freeze, started_at: started_at,
                             finished_at: Time.now.utc, callback_errors: callback_errors,
                             report_location: nil, report_error: nil)
+          if reporting.fetch(:schema) == 2
+            batch = Report.new(batch, policy: reporting.fetch(:policy), duration_ms: ((monotonic - started) * 1000).round)
+          end
           save_report(batch, directory: report_directory)
         end
 
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         # 校验批量任务回调接口。
         def validate_callback!(callback, name)
           raise ArgumentError, "#{name} must respond to call" if callback && !callback.respond_to?(:call)
@@ -113,83 +145,35 @@ module Net
           return batch unless @result_store
 
           batch.with(report_location: @result_store.write(batch, directory: directory))
+        rescue Operations::PrivateFile::WriteError => error
+          # 报告也可能已经原子替换；保留已知位置，不将持久性失败误写成完全没有产物。
+          location = error.receipt.path if Operations::PrivateFile.receipt_error?(error) && error.receipt.committed?
+          return batch.with_report_error(error, location: location) if batch.instance_of?(Report)
+
+          batch.with(report_location: location, report_error: error.class.name)
         rescue StandardError => error
-          batch.with(report_error: error.class.name)
-        end
+          return batch.with_report_error(error) if batch.instance_of?(Report)
 
-        # 校验厂商 VRF 映射和名称。
-        def validate_vrfs!(vrfs)
-          unless vrfs.is_a?(Hash) && vrfs.all? { |vendor, value|
-            %i[cisco_nxos hillstone].include?(vendor) && value.is_a?(String) &&
-              value.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/)
-          }
-            raise ArgumentError, "vrfs must map supported vendor names to safe VRF names"
-          end
+          batch.with(report_error: error.class.name)
         end
 
         # 确认传入计划属于当前备份模式。
         def validate_plan!(plan, mode)
           raise ArgumentError, "plan must be a #{mode} Netdisco plan" unless plan.is_a?(Plan) && plan.mode == mode
 
-          inventory = plan.inventory
-          ready = plan.ready
-          outcomes = plan.outcomes
-          unless inventory.is_a?(Array) && inventory.all?(Device) && ready.is_a?(Array) &&
-                 outcomes.is_a?(Array) && outcomes.size == inventory.size
-            raise ArgumentError, "plan inventory and outcomes must have the same device slots"
-          end
-
-          selected = {}
-          previous_index = -1
-          ready.each do |task|
-            unless task.is_a?(Array) && task.size == 2 && task.first.is_a?(Integer)
-              raise ArgumentError, "plan contains an invalid device task"
-            end
-
-            index, device = task
-            unless index > previous_index && index < inventory.size && inventory[index].equal?(device) && device.ready?
-              raise ArgumentError, "plan tasks must reference ready inventory devices in order"
-            end
-
-            selected[index] = true
-            previous_index = index
-          end
-          if mode == :tftp && ready.count { |_index, device| device.vendor == :palo_alto } > 1
-            raise ArgumentError, "plan cannot upload multiple Palo Alto devices to one TFTP filename"
-          end
-
-          inventory.each_with_index do |device, index|
-            result = outcomes[index]
-            next if selected[index] && result.nil?
-
-            unless !selected[index] && valid_skipped_outcome?(result, device, mode)
-              raise ArgumentError, "plan outcome does not match its inventory slot"
-            end
-          end
-        end
-
-        # 未执行设备必须保留与清单一致的跳过原因，且不能带有执行产物。
-        def valid_skipped_outcome?(result, device, mode)
-          return false unless result.is_a?(Outcome) && result.device.equal?(device) && result.backup.nil? &&
-                              result.error_code.nil? && result.error_type.nil? &&
-                              result.started_at.nil? && result.finished_at.nil?
-
-          return result.status == device.issue unless device.ready?
-
-          result.status == :sample_limit ||
-            (mode == :tftp && device.vendor == :palo_alto && result.status == :remote_filename_collision)
+          plan.validate!
         end
 
         # 构造包含错误类型的单台设备结果。
         def outcome(device, status, backup: nil, error: nil)
           Outcome.new(device: device, status: status, backup: backup,
                       error_code: error.respond_to?(:code) ? error.code : nil,
-                      error_type: error&.class&.name)
+                      error_type: error&.class&.name, diagnostic: Diagnostic.from(error, backup: backup))
         end
 
         # 执行单台设备的 TFTP 导出。
-        def tftp_backup_one(device, server, source_files, log_directory, vrfs)
-          run_one(device, log_directory, success_status: :reported_uploaded,
+        def tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
+          run_one(device, log_directory, policy, success_status: :reported_uploaded,
                   close_error_status: :reported_with_error, backup_class: TftpBackup) do |connector|
             source_file = source_files.fetch(device.vendor, nil)
             transfer_settings = { host: server, path: device.tftp_filename, source_file: source_file }
@@ -199,25 +183,26 @@ module Net
         end
 
         # 执行单台设备的本地配置采集。
-        def backup_one(device, directory, log_directory)
+        def backup_one(device, directory, log_directory, policy, saved_config)
           destination = File.join(directory, device.backup_filename)
-          previous = Operations::SavedConfig.new(directory: directory).find(device.host, required: false)
-          previous_digest = Digest::SHA256.file(previous).hexdigest if previous && previous != destination
-          run_one(device, log_directory, success_status: :backed_up,
-                  close_error_status: :saved_with_error, backup_class: Backup) do |connector|
-            backup = connector.backup(path: destination)
-            if backup.is_a?(Backup) && backup.change == :created && previous_digest
-              backup.with(previous_sha256: previous_digest,
-                          change: backup.sha256 == previous_digest ? :unchanged : :changed)
-            else
-              backup
+          Operations::BackupLock.synchronize(destination, host: device.host) do |path_lock|
+            previous = saved_config.fingerprint(device.host, required: false)
+            previous_digest = previous.sha256 if previous && previous.path != destination
+            result = run_one(device, log_directory, policy, success_status: :backed_up,
+                             close_error_status: :saved_with_error, backup_class: Backup) do |connector|
+              path_lock.delegate { connector.backup(path: destination) }
             end
+            backup = result.backup
+            next result unless backup.is_a?(Backup) && backup.change == :created && previous_digest
+
+            result.with(backup: backup.with(previous_sha256: previous_digest,
+                                           change: backup.sha256 == previous_digest ? :unchanged : :changed))
           end
         end
 
         # 隔离单台设备的凭据、连接、操作和关闭异常。
-        def run_one(device, log_directory, success_status:, close_error_status:, backup_class:)
-          connection_settings = @credentials.call(device)
+        def run_one(device, log_directory, policy, success_status:, close_error_status:, backup_class:)
+          connection_settings = @credentials ? @credentials.call(device) : @settings.device_credentials_for(device)
           return outcome(device, :missing_credentials) if connection_settings.nil?
           unless connection_settings.is_a?(Hash) && connection_settings.keys.all?(Symbol) &&
                  connection_settings[:username].is_a?(String) && !connection_settings[:username].empty? &&
@@ -225,20 +210,36 @@ module Net
             raise ArgumentError, "credential resolver must return settings with username and without host"
           end
 
+          connection_settings = policy.connection_options(device.vendor).merge(connection_settings)
           log_name = device.host.tr(":", "_")
           if log_directory
             connection_settings = connection_settings.merge(log_file: File.join(log_directory, "#{log_name}.log"))
           end
           connector = @connector_factory.call(device, connection_settings)
+          backup, failure = perform_one(connector, backup_class) { yield connector }
+          return outcome(device, success_status, backup: backup) unless failure
+
+          outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
+        rescue StandardError => error
+          outcome(device, :failed, error: error)
+        end
+
+        # 仅信任库定义且产物类型匹配的提交后错误；普通第三方异常上的 backup 字段不代表完成。
+        def perform_one(connector, backup_class)
           backup = nil
           failure = nil
           begin
-            result = yield connector
+            result = yield
             raise TypeError, "backup operation did not return #{backup_class}" unless result.is_a?(backup_class)
 
             backup = result
           rescue StandardError => error
             failure = error
+            if backup_class == Backup && error.instance_of?(BackupPersistenceError) && error.backup.instance_of?(Backup)
+              backup = error.backup
+            elsif backup_class == TftpBackup && error.instance_of?(TftpCompletionError) && error.transfer.instance_of?(TftpBackup)
+              backup = error.transfer
+            end
           ensure
             begin
               connector.close
@@ -246,11 +247,7 @@ module Net
               failure ||= error
             end
           end
-          return outcome(device, success_status, backup: backup) unless failure
-
-          outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
-        rescue StandardError => error
-          outcome(device, :failed, error: error)
+          [backup, failure]
         end
       end
     end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Netdisco
+      # 每次 devices 调用独占一个预算，认证、分页和兼容查询不得重置已用资源或期限。
+      class InventoryBudget
+        def initialize(options, clock:)
+          @options = options
+          @clock = clock
+          @deadline = @clock.call + options.fetch(:inventory_timeout)
+          @bytes = 0
+          @devices = 0
+        end
+
+        def remaining
+          seconds = @deadline - @clock.call
+          raise Client::InventoryTimeout, cause: nil if seconds <= 0
+
+          seconds
+        end
+
+        # 在追加正文前计数；不能靠 Content-Length 或 JSON 解析后的大小限制内存。
+        def consume_bytes(size, response_bytes:)
+          remaining
+          check_limit!(:max_response_bytes, response_bytes + size)
+          check_limit!(:max_inventory_bytes, @bytes + size)
+          @bytes += size
+        end
+
+        # 去重前的记录同样占用清单内存；兼容查询也使用这个累计计数。
+        def consume_devices(size)
+          remaining
+          check_limit!(:max_devices, @devices + size)
+          @devices += size
+        end
+
+        private
+
+        def check_limit!(name, value)
+          return if value <= @options.fetch(name)
+
+          raise Client::Error.new("Netdisco inventory exceeded #{name}", code: name), cause: nil
+        end
+      end
+      private_constant :InventoryBudget
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Netdisco
+      # 固定一份清单上的选择结果与跳过原因，供预览和执行复用。
+      Plan = Data.define(:mode, :inventory, :ready, :outcomes) do
+        # Data 只冻结对象自身；这里复制并冻结可能由调用方修改的计划容器。
+        def initialize(mode:, inventory:, ready:, outcomes:)
+          unless inventory.is_a?(Array) && ready.is_a?(Array) && outcomes.is_a?(Array)
+            raise ArgumentError, "plan inventory, ready tasks, and outcomes must be Arrays"
+          end
+
+          tasks = ready.map { |task| task.is_a?(Array) ? task.dup.freeze : task }.freeze
+          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze)
+        end
+
+        # 按清单顺序返回选中的设备。
+        def selected = ready.map(&:last)
+
+        # 在任何设备 I/O 前校验完整快照，外部构造或修改的计划也必须遵守相同约束。
+        def validate!
+          raise ArgumentError, "plan mode must be backup or tftp" unless %i[backup tftp].include?(mode)
+          unless inventory.all?(Device) && outcomes.size == inventory.size
+            raise ArgumentError, "plan inventory and outcomes must have the same device slots"
+          end
+
+          selected_indices = {}
+          filenames = {}
+          previous_index = -1
+          ready.each do |task|
+            unless task.is_a?(Array) && task.size == 2 && task.first.is_a?(Integer)
+              raise ArgumentError, "plan contains an invalid device task"
+            end
+
+            index, device = task
+            unless index > previous_index && index < inventory.size && inventory[index].equal?(device) && device.ready?
+              raise ArgumentError, "plan tasks must reference ready inventory devices in order"
+            end
+            if mode == :tftp
+              filename = device.tftp_filename
+              raise ArgumentError, "plan cannot upload multiple devices to one TFTP filename" if filenames.key?(filename)
+
+              filenames[filename] = true
+            end
+            selected_indices[index] = true
+            previous_index = index
+          end
+
+          inventory.each_with_index do |device, index|
+            result = outcomes[index]
+            next if selected_indices[index] && result.nil?
+
+            unless !selected_indices[index] && valid_skipped_outcome?(result, device, filenames)
+              raise ArgumentError, "plan outcome does not match its inventory slot"
+            end
+          end
+          self
+        end
+
+        private
+
+        # 跳过结果不携带执行产物；文件冲突必须有本批次实际执行的目标作为依据。
+        def valid_skipped_outcome?(result, device, filenames)
+          return false unless result.is_a?(Outcome) && result.device.equal?(device) && result.backup.nil? &&
+                              result.error_code.nil? && result.error_type.nil? &&
+                              result.started_at.nil? && result.finished_at.nil?
+
+          return result.status == device.issue unless device.ready?
+
+          result.status == :sample_limit ||
+            (mode == :tftp && result.status == :remote_filename_collision && filenames.key?(device.tftp_filename))
+        end
+      end
+    end
+  end
+end