net-connector 0.4.2 → 0.6.0

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

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "client"
+
+module Net
+  module Connector
+    module Netdisco
+      # SQL 负责业务选择和列别名；适配器只管理只读查询、清单预算与连接生命周期。
+      class DatabaseClient
+        CONNECTION_ENV = {
+          host: "NETDISCO_DB_HOST", port: "NETDISCO_DB_PORT", dbname: "NETDISCO_DB_NAME",
+          user: "NETDISCO_DB_USER", password: "NETDISCO_DB_PASS",
+          sslmode: "NETDISCO_DB_SSLMODE", sslrootcert: "NETDISCO_DB_SSLROOTCERT",
+          connect_timeout: "NETDISCO_DB_CONNECT_TIMEOUT"
+        }.freeze
+        REQUIRED_CONNECTION_KEYS = %i[host dbname user password].freeze
+        DEFAULTS = Client::DEFAULTS.except(:allow_insecure_http).freeze
+
+        def self.options(query:, query_params: [], **values)
+          unless query.is_a?(String) && !query.strip.empty? && !query.include?("\0")
+            raise ArgumentError, "query must be a nonempty SQL string without NUL"
+          end
+          unless query_params.is_a?(Array) && query_params.all? { |value|
+            value.nil? || value == true || value == false || value.is_a?(Integer) ||
+              (value.is_a?(Float) && value.finite?) || (value.is_a?(String) && !value.include?("\0"))
+          }
+            raise ArgumentError, "query_params must be an array of JSON scalar values without NUL"
+          end
+          raise ArgumentError, "unknown database inventory options" unless (values.keys - DEFAULTS.keys).empty?
+
+          Client.options(**values).slice(*DEFAULTS.keys).merge(
+            query: query.dup.freeze,
+            query_params: query_params.map { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+          ).freeze
+        end
+
+        def initialize(connection_options:, **options)
+          @options = self.class.options(**options)
+          @connection_options = validate_connection_options(connection_options)
+        end
+
+        # 每次查询独占连接和游标；只有全部结果验证成功后才把清单交给 Fleet。
+        def devices
+          require "pg"
+          budget = InventoryBudget.new(@options, clock: method(:monotonic))
+          connection = nil
+          connected = false
+          begin
+            Timeout.timeout(budget.remaining, Client::InventoryTimeout) do
+              # 从握手开始持有连接；PG.connect 尚未返回时被超时中断，调用方无法负责关闭它。
+              connection = PG::Connection.connect_start(@connection_options)
+              # PostgreSQL NOTICE 可能包含 SQL 或数据，不交给 libpq 默认的 stderr 输出器。
+              connection.set_notice_processor { |_notice| nil }
+              wait_for_connection(connection, budget)
+              connected = true
+              # 使用 pg 可中断的 Ruby 等待接口；底层 socket 仍以非阻塞方式工作。
+              connection.setnonblocking(false)
+              connection.set_client_encoding("UTF8")
+              connection.exec("BEGIN READ ONLY").clear
+              set_statement_timeout(connection, budget)
+              # 即使没有参数也走扩展查询协议，由 PostgreSQL 拒绝多语句和非查询命令。
+              connection.exec_params("DECLARE net_connector_inventory NO SCROLL CURSOR FOR\n#{@options.fetch(:query)}",
+                                     @options.fetch(:query_params)).clear
+              rows = inventory(connection, budget)
+              connection.exec("ROLLBACK").clear
+              budget.remaining
+              rows
+            end
+          rescue Client::Error => error
+            raise error, cause: nil
+          rescue PG::QueryCanceled
+            raise Client::InventoryTimeout, cause: nil
+          rescue PG::Error, IOError, SystemCallError
+            code = connected ? :query_failed : :connection_failed
+            raise Client::Error.new("Netdisco database #{code.to_s.tr("_", " ")}", code: code), cause: nil
+          ensure
+            connection&.finish
+          end
+        end
+
+        def inspect = "#<#{self.class}>"
+
+        private
+
+        def wait_for_connection(connection, budget)
+          deadline = monotonic + @connection_options.fetch(:connect_timeout, budget.remaining).to_f
+          loop do
+            status = connection.connect_poll
+            return if status == PG::PGRES_POLLING_OK
+            raise PG::ConnectionBad unless [PG::PGRES_POLLING_READING, PG::PGRES_POLLING_WRITING].include?(status)
+
+            remaining = [budget.remaining, deadline - monotonic].min
+            raise PG::ConnectionBad if remaining <= 0
+
+            socket = connection.socket_io
+            readers = status == PG::PGRES_POLLING_READING ? [socket] : nil
+            writers = status == PG::PGRES_POLLING_WRITING ? [socket] : nil
+            next if IO.select(readers, writers, [socket], remaining)
+
+            budget.remaining
+            raise PG::ConnectionBad
+          end
+        end
+
+        def validate_connection_options(options)
+          unless options.is_a?(Hash) && (options.keys - CONNECTION_ENV.keys).empty?
+            raise ArgumentError, "connection_options must contain supported PostgreSQL connection keys"
+          end
+          REQUIRED_CONNECTION_KEYS.each do |key|
+            value = options[key]
+            unless value.is_a?(String) && !value.strip.empty?
+              raise ArgumentError, "#{CONNECTION_ENV.fetch(key)} is required"
+            end
+          end
+          options.each do |key, value|
+            valid = value.is_a?(String) && !value.empty? && !value.include?("\0")
+            valid ||= %i[port connect_timeout].include?(key) && value.is_a?(Integer)
+            raise ArgumentError, "#{CONNECTION_ENV.fetch(key)} is invalid" unless valid
+          end
+          %i[port connect_timeout].each do |key|
+            next unless options.key?(key)
+
+            value = options.fetch(key).to_s
+            maximum = key == :port ? 65_535 : 2_147_483_647
+            unless value.match?(/\A\d+\z/) && value.to_i.between?(1, maximum)
+              raise ArgumentError, "#{CONNECTION_ENV.fetch(key)} must be a positive integer within range"
+            end
+          end
+          if options[:sslmode] && !%w[disable allow prefer require verify-ca verify-full].include?(options[:sslmode])
+            raise ArgumentError, "NETDISCO_DB_SSLMODE is invalid"
+          end
+          # libpq 会把 dbname 中的 URI/conninfo 再解释为连接参数，不能借此绕过凭据来源。
+          if options.fetch(:dbname).match?(/=|\Apostgres(?:ql)?:\/\//)
+            raise ArgumentError, "NETDISCO_DB_NAME must be a database name, not a connection string"
+          end
+          options.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+        end
+
+        def set_statement_timeout(connection, budget)
+          milliseconds = [(budget.remaining * 1000).ceil, 2_147_483_647].min
+          connection.exec_params("SELECT set_config('statement_timeout', $1, true)", [milliseconds.to_s]).clear
+        end
+
+        def inventory(connection, budget)
+          rows = []
+          @options.fetch(:max_pages).times do
+            set_statement_timeout(connection, budget)
+            count = fetch_page(connection, rows, budget)
+            return rows if count < @options.fetch(:page_size)
+          end
+          raise Client::Error.new("Netdisco inventory exceeded max_pages", code: :max_pages), cause: nil
+        end
+
+        # 单行模式避免 libpq 先缓存整页；Ruby 只积累已经通过预算检查的白名单字段。
+        def fetch_page(connection, rows, budget)
+          connection.send_query_params("FETCH FORWARD #{@options.fetch(:page_size)} FROM net_connector_inventory", [])
+          connection.set_single_row_mode
+          count = 0
+          response_bytes = 0
+          while (result = connection.get_result)
+            begin
+              result.check
+              response_bytes = append_rows(result, rows, budget, response_bytes)
+              count += result.ntuples
+            ensure
+              result.clear
+            end
+          end
+          count
+        end
+
+        def append_rows(result, rows, budget, response_bytes)
+          fields = result.fields
+          unless fields.include?("ip") && fields.uniq == fields
+            raise Client::Error.new("Netdisco database query must return unique column names including ip",
+                                    code: :invalid_inventory), cause: nil
+          end
+          budget.consume_devices(result.ntuples)
+          result.each do |row|
+            # 未选用的列也占传输预算，但不会进入清单、计划或报告。
+            size = row.sum { |key, value| key.bytesize + (value&.bytesize || 0) }
+            budget.consume_bytes(size, response_bytes: response_bytes)
+            response_bytes += size
+            unless row["ip"].is_a?(String) && !row["ip"].strip.empty?
+              raise Client::Error.new("Netdisco returned an invalid device inventory", code: :invalid_inventory), cause: nil
+            end
+            rows << row.slice(*Client::FIELDS)
+          end
+          response_bytes
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "ipaddr"
-require_relative "../operations/saved_config"
+require_relative "../storage/saved_config"
 
 module Net
   module Connector
@@ -44,7 +44,7 @@ module Net
         def ready? = issue.nil?
 
         # 生成不随名称或厂商信息改变的本地文本文件名。
-        def backup_filename = Operations::SavedConfig.filename(host)
+        def backup_filename = Storage::SavedConfig.filename(host)
 
         # 生成设备 CLI 可用的 ASCII 远端文件名。
         def tftp_filename
@@ -53,13 +53,12 @@ module Net
                       .gsub(/\A[._-]+|[._-]+\z/, "")
           label = vendor&.to_s || "device" if label.empty?
           strategy = Net::Connector.vendor_class(vendor).profile.tftp_strategy if vendor
-          # 旧版自定义策略只需实现实例接口，缺少命名接口时沿用通用 cfg 名称。
-          strategy = Operations::Tftp::Strategy unless strategy.respond_to?(:filename)
+          raise UnsupportedOperation, "device has no TFTP strategy" unless strategy
           TftpTarget.validate_path!(strategy.filename(host, label: label))
         end
 
         # 按厂商及设备地址实例化连接器。
-        def connector(**settings)
+        def build_connector(**settings)
           raise ArgumentError, "device is not ready: #{issue}" unless ready?
           raise ArgumentError, "host cannot be overridden" if settings.key?(:host)
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../engine/error_metadata"
+
 module Net
   module Connector
     module Netdisco
@@ -8,59 +10,27 @@ module Net
                                :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
+        private_constant :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),
+          super(error_code: ErrorMetadata.code(error_code),
+                error_type: ErrorMetadata.type(error_type), phase: ErrorMetadata.phase(phase),
+                underlying_type: ErrorMetadata.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 }
+          fields = { error_type: ErrorMetadata.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)
@@ -74,10 +44,10 @@ module Net
           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)
+          elsif error.instance_of?(TftpCompletionError) && backup.instance_of?(TftpReceipt) && error.receipt.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)
+          elsif phase == :report && Storage::PrivateFile.receipt_error?(error)
             { error_code: error.code, artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,
               underlying_type: error.underlying_type }
           else

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

@@ -18,7 +18,7 @@ module Net
           @client = client
           @rules = rules
           @credentials = credentials
-          @connector_factory = connector_factory || ->(device, connection_settings) { device.connector(**connection_settings) }
+          @connector_factory = connector_factory || ->(device, connection_settings) { device.build_connector(**connection_settings) }
           @result_store = result_store
           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)
@@ -42,8 +42,8 @@ module Net
         # 先拉取完整清单，再并发采集并保存设备配置。
         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)
+                       success_policy: :strict)
+          reporting = Report.validate_policy!(success_policy)
           policy = @settings.snapshot(mode: :backup)
           directory = policy.backup_directory if directory.equal?(DEFAULT_SETTING)
           concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
@@ -59,19 +59,18 @@ module Net
           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, 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)
+            backup_one(device, target_directory, log_directory, policy)
           end
         end
 
         # 让设备主动导出配置，在执行前检查同批目标文件名冲突。
         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: DEFAULT_SETTING, success_policy: :strict, report_schema: nil)
-          reporting = Report.options(policy: success_policy, schema: report_schema)
+                            report_directory: DEFAULT_SETTING, success_policy: :strict)
+          reporting = Report.validate_policy!(success_policy)
           policy = @settings.snapshot(mode: :tftp)
           concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
           report_directory = policy.backup_directory if report_directory.equal?(DEFAULT_SETTING)
@@ -121,15 +120,13 @@ module Net
           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|
+                                       on_error: ->(device, error) { build_outcome(device, :failed, error: error) }) do |device|
             yield device, log_directory
           end
           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
+          batch = Report.new(batch, policy: reporting, duration_ms: ((monotonic - started) * 1000).round)
           save_report(batch, directory: report_directory)
         end
 
@@ -145,16 +142,12 @@ module Net
           return batch unless @result_store
 
           batch.with(report_location: @result_store.write(batch, directory: directory))
-        rescue Operations::PrivateFile::WriteError => error
+        rescue Storage::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)
+          location = error.receipt.path if Storage::PrivateFile.receipt_error?(error) && error.receipt.committed?
+          batch.with_report_error(error, location: location)
         rescue StandardError => error
-          return batch.with_report_error(error) if batch.instance_of?(Report)
-
-          batch.with(report_error: error.class.name)
+          batch.with_report_error(error)
         end
 
         # 确认传入计划属于当前备份模式。
@@ -165,7 +158,7 @@ module Net
         end
 
         # 构造包含错误类型的单台设备结果。
-        def outcome(device, status, backup: nil, error: nil)
+        def build_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, diagnostic: Diagnostic.from(error, backup: backup))
@@ -174,7 +167,7 @@ module Net
         # 执行单台设备的 TFTP 导出。
         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|
+                  close_error_status: :reported_with_error, backup_class: TftpReceipt) do |connector|
             source_file = source_files.fetch(device.vendor, nil)
             transfer_settings = { host: server, path: device.tftp_filename, source_file: source_file }
             transfer_settings[:vrf] = vrfs.fetch(device.vendor) if vrfs.key?(device.vendor)
@@ -183,27 +176,21 @@ module Net
         end
 
         # 执行单台设备的本地配置采集。
-        def backup_one(device, directory, log_directory, policy, saved_config)
+        def backup_one(device, directory, log_directory, policy)
           destination = File.join(directory, device.backup_filename)
-          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) }
+          Storage::BackupLock.synchronize(destination, host: device.host) do |path_lock|
+            Storage::SafeFile.open(destination, missing: true) { |_file, _stat| nil }
+            run_one(device, log_directory, policy, success_status: :backed_up,
+                    close_error_status: :saved_with_error, backup_class: Backup) do |connector|
+              path_lock.with_delegated_lock { 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, 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?
+          return build_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? &&
                  !connection_settings.key?(:host)
@@ -217,11 +204,11 @@ module Net
           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
+          return build_outcome(device, success_status, backup: backup) unless failure
 
-          outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
+          build_outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
         rescue StandardError => error
-          outcome(device, :failed, error: error)
+          build_outcome(device, :failed, error: error)
         end
 
         # 仅信任库定义且产物类型匹配的提交后错误；普通第三方异常上的 backup 字段不代表完成。
@@ -237,8 +224,8 @@ module Net
             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
+            elsif backup_class == TftpReceipt && error.instance_of?(TftpCompletionError) && error.receipt.instance_of?(TftpReceipt)
+              backup = error.receipt
             end
           ensure
             begin

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

@@ -6,7 +6,7 @@ require_relative "batch"
 module Net
   module Connector
     module Netdisco
-      # v2 显式包装旧 Batch；成功策略与清单覆盖分开，默认 Batch JSON 不增加字段。
+      # 唯一的批量报告契约，分开呈现成功策略、清单覆盖和受控诊断。
       class Report
         extend Forwardable
         SUCCESS = %i[backed_up reported_uploaded].freeze
@@ -17,19 +17,14 @@ module Net
         attr_reader :batch, :policy, :duration_ms, :report_diagnostic
         def_delegators :@batch, *Batch.members, :success?, :status, :counts
 
-        # selected 必须使用带策略和覆盖信息的 v2；默认 strict 继续使用旧 schema。
-        def self.options(policy: :strict, schema: nil)
+        def self.validate_policy!(policy)
           raise ArgumentError, "success_policy must be strict or selected" unless %i[strict selected].include?(policy)
 
-          schema = policy == :selected ? 2 : 1 if schema.nil?
-          raise ArgumentError, "report_schema must be 1 or 2" unless schema.is_a?(Integer) && [1, 2].include?(schema)
-          raise ArgumentError, "selected success policy requires report schema 2" if policy == :selected && schema != 2
-
-          { policy: policy, schema: schema }.freeze
+          policy
         end
 
         def initialize(batch, policy: :strict, duration_ms: nil, report_diagnostic: nil)
-          self.class.options(policy: policy, schema: 2)
+          self.class.validate_policy!(policy)
           raise ArgumentError, "report requires a Batch" unless batch.instance_of?(Batch)
           unless duration_ms.nil? || (duration_ms.is_a?(Numeric) && duration_ms.real? && duration_ms.finite? && duration_ms >= 0)
             raise ArgumentError, "duration_ms must be nonnegative and finite"
@@ -42,7 +37,7 @@ module Net
           freeze
         end
 
-        # 旧 success?/status 委托给 Batch；新策略绝不把未知状态当作可忽略跳过。
+        # 严格完成情况与所选成功策略分别保留，未知状态不能当作可忽略跳过。
         def policy_success?
           return batch.success? if policy == :strict
           return false unless callback_errors.empty? && report_error.nil?
@@ -62,17 +57,17 @@ module Net
                           policy: policy, duration_ms: duration_ms, report_diagnostic: diagnostic)
         end
 
-        # 复用旧业务数据，但重新白名单化所有诊断字段，包括手工构造的旧 Batch。
+        # 手工构造的批次同样经过诊断白名单，不序列化任意异常内容。
         def summary
-          legacy = batch.summary
-          legacy.merge(
+          data = batch_summary
+          data.merge(
             schema_version: 2, policy: policy, policy_success: policy_success?, duration_ms: duration_ms,
             coverage: { complete: !outcomes.empty? && outcomes.all? { |item| ATTEMPTED.include?(item.status) },
                         attempted: outcomes.count { |item| ATTEMPTED.include?(item.status) },
                         skipped: outcomes.count { |item| !ATTEMPTED.include?(item.status) } },
-            devices: device_summaries(legacy.fetch(:devices)),
-            callback_errors: callback_errors.map { |entry| { host: entry[:host], error_type: Diagnostic.type(entry[:error_type]) } },
-            report_location: report_location, report_error: Diagnostic.type(report_error),
+            devices: device_summaries(data.fetch(:devices)),
+            callback_errors: callback_errors.map { |entry| { host: entry[:host], error_type: ErrorMetadata.type(entry[:error_type]) } },
+            report_location: report_location, report_error: ErrorMetadata.type(report_error),
             report_diagnostic: report_diagnostic&.to_h
           )
         end
@@ -81,6 +76,32 @@ module Net
 
         private
 
+        # 生成可写入报告及供命令行展示的结构化摘要。
+        def batch_summary
+          {
+            mode: mode, status: status, started_at: started_at.iso8601, finished_at: finished_at.iso8601,
+            total: outcomes.size,
+            succeeded: outcomes.count(&:success?),
+            partial: outcomes.count(&:partial?),
+            failed: outcomes.count { |item| item.status == :failed },
+            skipped: outcomes.count(&:skipped?),
+            counts: counts,
+            callback_errors: callback_errors,
+            devices: outcomes.map do |item|
+              { host: item.device.host || item.device.source_ip, name: item.device.name,
+                vendor: item.device.vendor,
+                status: item.status, path: item.backup&.path,
+                bytes: item.backup.is_a?(Backup) ? item.backup.bytes : nil,
+                sha256: item.backup.is_a?(Backup) ? item.backup.sha256 : nil,
+                change: item.backup.is_a?(Backup) ? item.backup.change : nil,
+                previous_sha256: item.backup.is_a?(Backup) ? item.backup.previous_sha256 : nil,
+                started_at: item.started_at&.iso8601, finished_at: item.finished_at&.iso8601,
+                duration_ms: item.duration_ms,
+                error_code: item.error_code, error_type: item.error_type }
+            end
+          }
+        end
+
         def device_summaries(entries)
           entries.zip(outcomes).map do |entry, item|
             diagnostic = item.diagnostic || Diagnostic.new(error_code: item.error_code, error_type: item.error_type)

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

@@ -3,7 +3,7 @@
 require "json"
 require "fileutils"
 require "securerandom"
-require_relative "../operations/private_file"
+require_relative "../storage/private_file"
 
 module Net
   module Connector
@@ -17,7 +17,7 @@ module Net
             FileUtils.mkdir_p(destination, mode: 0o700)
             filename = "netdisco-#{batch.mode}-#{batch.started_at.strftime("%Y%m%dT%H%M%SZ")}-#{SecureRandom.hex(4)}.json"
             path = File.join(destination, filename)
-            Operations::PrivateFile.write(path, JSON.pretty_generate(batch.summary))
+            Storage::PrivateFile.write(path, JSON.pretty_generate(batch.summary)).path
           end
         end