net-connector 0.4.0 → 0.4.2

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "time"
+require_relative "diagnostic"
 
 module Net
   module Connector
@@ -8,9 +9,29 @@ module Net
       # 单台设备的最终结果，保留状态、配置产物和错误类型。
       Outcome = Data.define(:device, :status, :backup, :error_code, :error_type,
                             :started_at, :finished_at) do
+        attr_reader :diagnostic
+
         # 创建结果，允许计划阶段尚无执行时间。
-        def initialize(device:, status:, backup:, error_code:, error_type:, started_at: nil, finished_at: nil)
-          super
+        def initialize(device:, status:, backup:, error_code:, error_type:, started_at: nil, finished_at: nil,
+                       duration_ms: nil, diagnostic: nil)
+          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"
+          end
+          raise ArgumentError, "diagnostic must be a Diagnostic" unless diagnostic.nil? || diagnostic.instance_of?(Diagnostic)
+
+          @duration_ms, @diagnostic = duration_ms, diagnostic
+          super(device: device, status: status, backup: backup, error_code: error_code, error_type: error_type,
+                started_at: started_at, finished_at: finished_at)
+        end
+
+        # Data 成员保持不变；Worker 加上时间、旧文件迁移调整产物时仍保留内部元数据。
+        def with(**attributes)
+          return self if attributes.empty?
+
+          metadata = { duration_ms: @duration_ms, diagnostic: diagnostic }
+          metadata[:duration_ms] = nil if attributes.key?(:started_at) || attributes.key?(:finished_at)
+          metadata[:diagnostic] = nil if attributes.key?(:error_code) || attributes.key?(:error_type)
+          self.class.new(**to_h, **metadata.merge(attributes))
         end
 
         # 判断设备是否完成配置保存或上报上传成功。
@@ -24,7 +45,9 @@ module Net
 
         # 计算设备任务的耗时，计划阶段没有时间时返回空值。
         def duration_ms
-          ((finished_at - started_at) * 1000).round if started_at && finished_at
+          return @duration_ms unless @duration_ms.nil?
+
+          [((finished_at - started_at) * 1000).round, 0].max if started_at && finished_at
         end
       end
 
@@ -40,6 +63,9 @@ module Net
         # 空清单与已尝试但未全部成功的批次分别标记。
         def status = outcomes.empty? ? :no_devices : (success? ? :succeeded : :incomplete)
 
+        # 单独请求 v2 包装，不改变旧 Data 的成员、解构或默认 summary。
+        def report(policy: :strict) = Report.new(self, policy: policy)
+
         # 生成可写入报告及供命令行展示的结构化摘要。
         def summary
           {
@@ -66,6 +92,8 @@ module Net
           }
         end
       end
+
+      autoload :Report, File.expand_path("report", __dir__)
     end
   end
 end

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

@@ -24,85 +24,123 @@ module Net
           return 0 if options[:done]
 
           validate_options!(options)
-          values = options[:config] ? ConfigFile.load(options[:config]).merge(@env.to_h) : @env.to_h
-          values["NET_CONNECTOR_BACKUP_DIRECTORY"] = options[:directory] if options[:directory]
-          values["NET_CONNECTOR_CONCURRENCY"] = options[:concurrency].to_s if options[:concurrency]
-          values["NET_CONNECTOR_INCLUDE_HOSTS"] = options[:host] if options[:host]
-          settings = Settings.new(env: values)
+          mode = options[:export] ? :export : (options[:tftp] ? :tftp : :backup)
+          settings = settings_for(options).for_run(mode: mode)
 
           if options[:show_config]
             @output.puts JSON.pretty_generate(settings.public_config)
             return 0
           end
           if options[:export]
-            path = Operations::SavedConfig.new(directory: settings.backup_directory)
-                                          .export(host: options[:export], output: options[:output], io: @output)
-            @output.puts JSON.generate(host: options[:export], output: path) if path
+            export_config(settings, options)
             return 0
           end
+          if options[:tftp] && !options[:plan] && !settings.tftp_server
+            raise ArgumentError, "TFTP_HOST is required"
+          end
 
           fleet = @fleet_factory.call(settings)
-          limit = options[:all] ? nil : options[:limit] || settings.limit_per_vendor(tftp: options[:tftp])
-          plan = if options[:tftp]
-                   fleet.plan_tftp_backup(limit_per_vendor: limit)
-                 else
-                   fleet.plan_backup(limit_per_vendor: limit)
-                 end
-          if options[:host]
-            host = IPAddr.new(options[:host]).to_s
-            raise ArgumentError, "host #{options[:host]} was not found in inventory" unless plan.inventory.any? { |device| device.host == host }
-          end
+          plan = backup_plan(fleet, settings, options)
           if options[:plan]
             @output.puts JSON.pretty_generate(plan_summary(plan))
             return 0
           end
 
-          batch = if options[:tftp]
-                    fleet.tftp_backup_all(plan: plan, server: values.fetch("TFTP_HOST"),
-                                          concurrency: settings.concurrency,
-                                          vrfs: settings.tftp_vrfs,
-                                          source_files: settings.tftp_source_files)
-                  else
-                    fleet.backup_all(plan: plan, directory: settings.backup_directory,
-                                     concurrency: settings.concurrency)
-                  end
-          @output.puts JSON.pretty_generate(batch.summary.merge(report_location: batch.report_location,
-                                                                report_error: batch.report_error))
-          batch.success? ? 0 : 1
+          batch = backup(fleet, plan, settings, options)
+          summary = batch.summary
+          summary = summary.merge(report_location: batch.report_location, report_error: batch.report_error) unless batch.instance_of?(Report)
+          @output.puts JSON.pretty_generate(summary)
+          (batch.instance_of?(Report) ? batch.policy_success? : batch.success?) ? 0 : 1
+        rescue Operations::PrivateFile::WriteError => exception
+          message = Operations::PrivateFile.receipt_error?(exception) ? exception.message : exception.class.name
+          @error.puts "net-connector-backup: #{message}"
+          2
         rescue OptionParser::ParseError, ArgumentError, KeyError, Errno::ENOENT,
           Psych::Exception, JSON::ParserError, Client::Error => exception
           @error.puts "net-connector-backup: #{exception.message}"
           2
         rescue StandardError => exception
-          @error.puts "net-connector-backup failed (#{exception.class})"
+          @error.puts "net-connector-backup 失败（#{exception.class}）"
           2
         end
 
         private
 
+        # 文件、环境变量、命令行按优先级覆盖，凭据仍只来自环境变量。
+        def settings_for(options)
+          defaults = options[:config] ? ConfigFile.load(options[:config]) : {}
+          values = {}
+          values["NET_CONNECTOR_BACKUP_DIRECTORY"] = options[:directory] if options[:directory]
+          values["NET_CONNECTOR_CONCURRENCY"] = options[:concurrency].to_s if options[:concurrency]
+          values["NET_CONNECTOR_MAX_SCRIPT_OUTPUT_BYTES"] = options[:max_script_output_bytes].to_s if options[:max_script_output_bytes]
+          values["NET_CONNECTOR_INCLUDE_HOSTS"] = options[:host] if options[:host]
+          values["NET_CONNECTOR_SAMPLE_PER_VENDOR"] = options[:limit].to_s if options[:limit]
+          values["NET_CONNECTOR_SAMPLE_PER_VENDOR"] = nil if options[:all]
+          Settings.new(env: @env, defaults: defaults, overrides: values)
+        end
+
+        # 导出已有配置不创建清单或设备连接。
+        def export_config(settings, options)
+          path = Operations::SavedConfig.new(directory: settings.backup_directory)
+                                        .export(host: options[:export], output: options[:output], io: @output)
+          @output.puts JSON.generate(host: options[:export], output: path) if path
+        end
+
+        # 预览与执行共用计划和主机存在性检查。
+        def backup_plan(fleet, settings, options)
+          limit = options[:all] ? nil : options[:limit] || settings.limit_per_vendor(tftp: options[:tftp])
+          plan = if options[:tftp]
+                   fleet.plan_tftp_backup(limit_per_vendor: limit)
+                 else
+                   fleet.plan_backup(limit_per_vendor: limit)
+                 end
+          if options[:host]
+            host = IPAddr.new(options[:host]).to_s
+            raise ArgumentError, "清单中未找到设备 #{options[:host]}" unless plan.inventory.any? { |device| device.host == host }
+          end
+          plan
+        end
+
+        # 仅执行已经校验的计划，保留本地与 TFTP 两种结果语义。
+        def backup(fleet, plan, settings, options)
+          reporting = options.slice(:success_policy, :report_schema)
+          if options[:tftp]
+            fleet.tftp_backup_all(plan: plan, server: settings.tftp_server,
+                                  concurrency: settings.concurrency,
+                                  vrfs: settings.tftp_vrfs,
+                                  source_files: settings.tftp_source_files, **reporting)
+          else
+            fleet.backup_all(plan: plan, directory: settings.backup_directory,
+                             concurrency: settings.concurrency, **reporting)
+          end
+        end
+
         # 解析命令行参数并处理帮助及版本信息。
         def parse_options
           options = { config: @env["NET_CONNECTOR_CONFIG"] }
           parser = OptionParser.new do |args|
-            args.banner = "Usage: net-connector-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
-            args.on("--config FILE", "Read non-secret YAML settings") { |value| options[:config] = value }
-            args.on("--show-config", "Print effective non-secret settings") { options[:show_config] = true }
-            args.on("--plan", "Preview selected inventory without device connections") { options[:plan] = true }
-            args.on("--tftp", "Use device-initiated TFTP backup") { options[:tftp] = true }
-            args.on("--export IP", "Export a saved local configuration") { |value| options[:export] = value }
-            args.on("--output FILE", "Write exported configuration to a private file") { |value| options[:output] = value }
-            args.on("--directory PATH", "Backup and report directory") { |value| options[:directory] = value }
-            args.on("--host IP", "Select one inventory device by management IP") { |value| options[:host] = value }
-            args.on("--concurrency N", Integer, "Maximum simultaneous devices") { |value| options[:concurrency] = value }
-            args.on("--limit-per-vendor N", Integer, "Select N devices per vendor (1..5)") do |value|
+            args.banner = "用法：net-connector-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
+            args.on("--config FILE", "读取不含凭据的 YAML 设置") { |value| options[:config] = value }
+            args.on("--show-config", "显示生效的非敏感设置") { options[:show_config] = true }
+            args.on("--plan", "预览设备清单，不连接设备") { options[:plan] = true }
+            args.on("--tftp", "由设备发起 TFTP 备份") { options[:tftp] = true }
+            args.on("--export IP", "导出已保存的本地配置") { |value| options[:export] = value }
+            args.on("--output FILE", "将导出配置写入私有文件") { |value| options[:output] = value }
+            args.on("--directory PATH", "备份和报告目录") { |value| options[:directory] = value }
+            args.on("--host IP", "按管理地址选择一台设备") { |value| options[:host] = value }
+            args.on("--concurrency N", Integer, "最大并发设备数") { |value| options[:concurrency] = value }
+            args.on("--max-script-output-bytes N", Integer, "每个脚本的累计响应字节上限") { |value| options[:max_script_output_bytes] = value }
+            args.on("--limit-per-vendor N", Integer, "每厂商选择 N 台设备（1 至 5）") do |value|
               options[:limit] = value
             end
-            args.on("--all", "Select all ready devices") { options[:all] = true }
-            args.on("-v", "--version", "Print version") do
+            args.on("--all", "选择全部就绪设备") { options[:all] = true }
+            args.on("--success-policy POLICY", %w[strict selected], "成功判定：strict（默认）或 selected") { |value| options[:success_policy] = value.to_sym }
+            args.on("--report-schema N", Integer, "报告版本：1（默认）或 2；selected 使用 2") { |value| options[:report_schema] = value }
+            args.on("-v", "--version", "显示版本") do
               @output.puts Net::Connector::VERSION
               options[:done] = true
             end
-            args.on("-h", "--help", "Show help") do
+            args.on("-h", "--help", "显示帮助") do
               @output.puts args
               options[:done] = true
             end
@@ -115,12 +153,16 @@ module Net
 
         # 拒绝互斥或缺少依赖的命令行选项。
         def validate_options!(options)
+          Report.options(policy: options.fetch(:success_policy, :strict), schema: options[:report_schema])
+          Planner.validate_limit!(options[:limit])
+          Worker.new(concurrency: options[:concurrency]) if options[:concurrency]
           modes = [:show_config, :plan, :export].count { |key| options[key] }
-          raise ArgumentError, "choose one of --show-config, --plan, or --export" if modes > 1
-          raise ArgumentError, "--output requires --export" if options[:output] && !options[:export]
-          raise ArgumentError, "--all and --limit-per-vendor cannot be combined" if options[:all] && options[:limit]
-          if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:concurrency] || options[:host])
-            raise ArgumentError, "--export cannot be combined with backup options"
+          raise ArgumentError, "--show-config、--plan 和 --export 只能选择一项" if modes > 1
+          raise ArgumentError, "--output 需要同时指定 --export" if options[:output] && !options[:export]
+          raise ArgumentError, "--all 不能与 --limit-per-vendor 同时使用" if options[:all] && options[:limit]
+          if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:concurrency] || options[:host] ||
+                                  options[:success_policy] || options[:report_schema] || options[:max_script_output_bytes])
+            raise ArgumentError, "--export 不能与备份选项同时使用"
           end
         end
 

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

@@ -3,144 +3,277 @@
 require "json"
 require "net/http"
 require "openssl"
+require "timeout"
 require "uri"
+require_relative "inventory_budget"
 
 module Net
   module Connector
     module Netdisco
-      # 独立于 Rails 的 Netdisco 设备清单客户端。
+      # 独立于 Rails 的 Netdisco 设备清单客户端；失败时不交付部分清单。
       class Client
-        class Error < StandardError; end
+        class Error < StandardError
+          attr_reader :code
+
+          def initialize(message = nil, code: :client_error)
+            @code = code
+            super(message)
+          end
+        end
 
         class QueryRequired < Error; end
 
+        class InventoryTimeout < Error
+          def initialize(_message = nil)
+            super("Netdisco inventory exceeded inventory_timeout", code: :inventory_timeout)
+          end
+        end
+
         FIELDS = %w[ip name dns vendor os model os_ver serial].freeze
         DEFAULT_MAX_PAGES = 10_000
+        DEFAULTS = { page_size: 500, max_pages: DEFAULT_MAX_PAGES, max_response_bytes: 16 * 1024 * 1024,
+                     max_inventory_bytes: 128 * 1024 * 1024, max_devices: 100_000,
+                     inventory_timeout: 300, allow_insecure_http: true }.freeze
 
-        # 校验 Netdisco 地址与凭据并建立请求入口。
-        def initialize(url:, username: nil, password: nil, api_key: nil, page_size: 500,
-                       max_pages: DEFAULT_MAX_PAGES, requester: nil)
-          @url = URI.parse(url.to_s)
-          unless @url.is_a?(URI::HTTP) && @url.host && !@url.userinfo && !@url.query && !@url.fragment
-            raise ArgumentError, "url must be an HTTP(S) base URL without credentials, query or fragment"
-          end
-          unless (api_key.nil? && present?(username) && present?(password)) ||
-                 (present?(api_key) && username.nil? && password.nil?)
-            raise ArgumentError, "provide either username and password or api_key"
+        # 此纯校验入口也供 Settings 使用，避免配置预览与实际执行使用两套范围规则。
+        def self.options(**values)
+          raise ArgumentError, "unknown Netdisco client options" unless (values.keys - DEFAULTS.keys).empty?
+
+          options = DEFAULTS.merge(values)
+          %i[page_size max_pages max_response_bytes max_inventory_bytes max_devices].each do |name|
+            value = options.fetch(name)
+            raise ArgumentError, "#{name} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
           end
-          if [username, password, api_key].compact.any? { |value| value.match?(/[\r\n]/) }
-            raise ArgumentError, "credentials must be single-line strings"
+          duration = options.fetch(:inventory_timeout)
+          unless duration.is_a?(Numeric) && duration.real? && duration.finite? && duration.positive? && duration.to_f.finite?
+            raise ArgumentError, "inventory_timeout must be a positive finite number"
           end
-          unless page_size.is_a?(Integer) && page_size.positive? && max_pages.is_a?(Integer) && max_pages.positive?
-            raise ArgumentError, "page_size and max_pages must be positive integers"
+          unless [true, false].include?(options.fetch(:allow_insecure_http))
+            raise ArgumentError, "allow_insecure_http must be true or false"
           end
+          options.freeze
+        end
 
-          @username, @password, @api_key = username, password, api_key
-          @page_size, @max_pages = page_size, max_pages
-          @requester = requester || method(:default_request)
+        def self.validate_url!(url, allow_insecure_http: true)
+          uri = URI.parse(url.to_s)
+          unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+            raise ArgumentError, "url must be an HTTP(S) base URL without credentials, query or fragment"
+          end
+          if uri.scheme == "http" && !allow_insecure_http
+            raise ArgumentError, "HTTP requires allow_insecure_http: true; use HTTPS"
+          end
+          uri
         rescue URI::InvalidURIError
           raise ArgumentError, "url is invalid", cause: nil
         end
 
-        # 逐页获取并校验完整设备清单。
+        # requester 仍接收 (uri, request)，其自行阻塞的时间由注入方负责。
+        def initialize(url:, username: nil, password: nil, api_key: nil, requester: nil, **options)
+          @options = self.class.options(**options)
+          @url = self.class.validate_url!(url, allow_insecure_http: @options.fetch(:allow_insecure_http)).freeze
+          validate_credentials!(username, password, api_key)
+          raise ArgumentError, "requester must respond to call" if requester && !requester.respond_to?(:call)
+
+          @username, @password, @api_key = [username, password, api_key].map { |value| value&.dup&.freeze }
+          @requester = requester
+        end
+
         def devices
-          token = @api_key || authenticate
+          budget = InventoryBudget.new(@options, clock: method(:monotonic))
+          token = @api_key || authenticate(budget)
+          rows = inventory(token, budget)
+          budget.remaining
+          rows
+        end
+
+        def inspect = "#<#{self.class} url=#{@url.scheme}://#{@url.host}>"
+
+        private
+
+        def inventory(token, budget)
           rows = []
           seen_ips = {}
-          offset = 0
-          @max_pages.times do
+          @options.fetch(:max_pages).times do |index|
             uri = endpoint("api/v1/search/device")
-            uri.query = URI.encode_www_form(fields: FIELDS.join(","), limit: @page_size, offset: offset)
-            page = request_json(uri, authorized_get(uri, token), allow_empty: true)
-            validate_rows!(page)
+            uri.query = URI.encode_www_form(fields: FIELDS.join(","), limit: @options.fetch(:page_size),
+                                           offset: index * @options.fetch(:page_size))
+            page = request_json(uri, authorized_get(uri, token), budget, allow_empty: true, query_fallback: true)
+            validate_rows!(page, budget)
             return rows.uniq if page.empty?
 
-            raise Error, "Netdisco pagination did not advance" if page.all? { |row| seen_ips[row.fetch("ip")] }
-
+            if page.all? { |row| seen_ips[row.fetch("ip")] }
+              raise Error.new("Netdisco pagination did not advance", code: :pagination_stalled), cause: nil
+            end
             page.each { |row| seen_ips[row.fetch("ip")] = true }
             rows.concat(page)
-            offset += @page_size
           end
-          raise Error, "Netdisco inventory exceeded max_pages"
+          raise Error.new("Netdisco inventory exceeded max_pages", code: :max_pages), cause: nil
         rescue QueryRequired
-          legacy_devices(token)
+          legacy_devices(token, budget)
         end
 
-        # 仅显示服务地址，避免凭据进入调试输出。
-        def inspect = "#<#{self.class} url=#{@url.scheme}://#{@url.host}>"
-
-        private
-
-        # 在服务要求查询参数时使用兼容查询获取清单。
-        def legacy_devices(token)
+        def legacy_devices(token, budget)
           uri = endpoint("api/v1/search/device")
           uri.query = URI.encode_www_form(q: "%", seeallcolumns: true)
-          rows = request_json(uri, authorized_get(uri, token), allow_empty: true)
-          validate_rows!(rows)
+          rows = request_json(uri, authorized_get(uri, token), budget, allow_empty: true)
+          validate_rows!(rows, budget)
           rows.map { |row| row.slice(*FIELDS) }.uniq
         end
 
-        # 使用账号密码登录并取得 API 密钥。
-        def authenticate
+        def authenticate(budget)
           uri = endpoint("login")
           request = ::Net::HTTP::Post.new(uri)
           request.basic_auth(@username, @password)
-          data = request_json(uri, request)
+          data = request_json(uri, request, budget)
           token = data["api_key"] if data.is_a?(Hash)
-          raise Error, "Netdisco login did not return an API key" unless present?(token) && !token.match?(/[\r\n]/)
+          raise Error, "Netdisco login did not return an API key" unless present?(token) && !token.match?(/[\r\n\x00]/)
 
           token
         end
 
-        # 为清单查询建立带 API 密钥的请求。
         def authorized_get(uri, token)
-          request = ::Net::HTTP::Get.new(uri)
-          request["Authorization"] = "Apikey #{token}"
-          request
+          ::Net::HTTP::Get.new(uri).tap { |request| request["Authorization"] = "Apikey #{token}" }
         end
 
-        # 以服务根地址构建 API 地址。
         def endpoint(path)
-          uri = @url.dup
-          uri.path = "#{uri.path.chomp("/")}/#{path}"
-          uri
+          @url.dup.tap { |uri| uri.path = "#{uri.path.chomp("/")}/#{path}" }
         end
 
-        # 发起请求并将 HTTP 和 JSON 故障转换为客户端错误。
-        def request_json(uri, request, allow_empty: false)
+        # 只保留稳定错误码及类型，不将服务正文、URI 或底层异常 cause 带进报告。
+        def request_json(uri, request, budget, allow_empty: false, query_fallback: false)
           request["Accept"] = "application/json"
-          response = @requester.call(uri, request)
-          body = response.body.to_s
-          if response.code == "400"
+          budget.remaining
+          response, body = request_body(uri, request, budget)
+          if query_fallback && response.code == "400"
             parsed = JSON.parse(body)
             raise QueryRequired, "Netdisco requires a search query" if parsed.is_a?(Hash) && parsed["error"] == "Missing query"
           end
-          raise Error, "Netdisco request failed (HTTP #{response.code})" unless response.is_a?(::Net::HTTPSuccess)
-          return [] if allow_empty && body.strip.empty?
-
-          JSON.parse(body)
+          unless response.is_a?(::Net::HTTPSuccess)
+            status = response.code.to_s.match?(/\A\d{3}\z/) ? response.code : "invalid"
+            raise Error.new("Netdisco request failed (HTTP #{status})", code: :request_failed), cause: nil
+          end
+          data = allow_empty && body.strip.empty? ? [] : JSON.parse(body)
+          budget.remaining
+          data
+        rescue Error => error
+          raise error, cause: nil
         rescue JSON::ParserError
-          raise Error, "Netdisco returned invalid JSON", cause: nil
-        rescue IOError, SystemCallError, Timeout::Error, SocketError, OpenSSL::SSL::SSLError => error
-          raise Error, "Netdisco connection failed (#{error.class})", cause: nil
+          raise Error.new("Netdisco returned invalid JSON", code: :invalid_json), cause: nil
+        rescue StandardError => error
+          budget.remaining
+          raise Error.new("Netdisco connection failed (#{error.class})", code: :connection_failed), cause: nil
+        end
+
+        def request_body(uri, request, budget)
+          return default_request(uri, request, budget) unless @requester
+
+          response = injected_request(uri, request, budget)
+          budget.remaining
+          body = response.body.to_s
+          budget.consume_bytes(body.bytesize, response_bytes: 0)
+          [response, body]
         end
 
-        # 使用标准库 HTTP 客户端发送请求。
-        def default_request(uri, request)
-          ::Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                            open_timeout: 10, read_timeout: 60, write_timeout: 10) { |http| http.request(request) }
+        # 回调自己抛出的 Client::Error 也可能带正文，不能当成内部安全错误直接透传。
+        def injected_request(uri, request, budget)
+          @requester.call(uri, request)
+        rescue StandardError => error
+          budget.remaining
+          raise Error.new("Netdisco connection failed (#{error.class})", code: :connection_failed), cause: nil
         end
 
-        # 校验清单的字段类型和设备地址。
-        def validate_rows!(rows)
-          valid = rows.is_a?(Array) && rows.all? do |row|
+        # 仅对自有 HTTP 传输施加总期限，覆盖响应头的持续慢速输入；不异步中断用户回调。
+        # start 的块负责关闭连接；禁用隐式 GET 重试，所有阶段同时使用剩余的原生超时。
+        def default_request(uri, request, budget)
+          Timeout.timeout(budget.remaining, InventoryTimeout) do
+            ::Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", max_retries: 0,
+                              **http_timeouts(budget)) do |http|
+              apply_timeouts(http, budget)
+              with_http_deadline(http, budget) { read_response(http, request, budget) }
+            end
+          end
+        end
+
+        # 异步超时展开栈时，Net::HTTP 的 chunked ensure 可能再次等待读取。
+        # 只关闭本次自有连接来解除这类阻塞；结束时唤醒并 join 观察线程，不遗留后台任务。
+        def with_http_deadline(http, budget)
+          mutex = Mutex.new
+          changed = ConditionVariable.new
+          finished = false
+          timer = Thread.new do
+            begin
+              mutex.synchronize { changed.wait(mutex, budget.remaining) until finished }
+            rescue InventoryTimeout
+              begin
+                http.finish
+              rescue IOError, SystemCallError
+                # 主请求可能已先关闭；外层 start 仍负责最终清理，保持原始预算错误。
+                nil
+              end
+            end
+          end
+          yield
+        ensure
+          mutex&.synchronize { finished = true; changed.broadcast }
+          timer&.join
+        end
+
+        def read_response(http, request, budget)
+          body = "".b
+          failure = nil
+          response = http.request(request) do |reply|
+            apply_timeouts(http, budget)
+            reply.read_body do |chunk|
+              budget.consume_bytes(chunk.bytesize, response_bytes: body.bytesize)
+              body << chunk
+              apply_timeouts(http, budget)
+            rescue Error => error
+              failure = error
+              # Net::HTTP 的 chunked 收尾仍会读取分隔符；先关闭连接才能立即停止超额下载。
+              http.finish
+              raise
+            end
+          end
+          budget.remaining
+          [response, body]
+        rescue StandardError => error
+          raise failure || error, cause: nil
+        end
+
+        def http_timeouts(budget)
+          remaining = budget.remaining
+          { open_timeout: [10, remaining].min, read_timeout: [60, remaining].min, write_timeout: [10, remaining].min }
+        end
+
+        def apply_timeouts(http, budget)
+          http_timeouts(budget).each { |name, value| http.public_send(:"#{name}=", value) }
+        end
+
+        def validate_rows!(rows, budget)
+          unless rows.is_a?(Array)
+            raise Error.new("Netdisco returned an invalid device inventory", code: :invalid_inventory), cause: nil
+          end
+          budget.consume_devices(rows.size)
+          valid = rows.all? do |row|
             row.is_a?(Hash) && present?(row["ip"]) &&
               FIELDS.drop(1).all? { |field| row[field].nil? || row[field].is_a?(String) }
           end
-          raise Error, "Netdisco returned an invalid device inventory" unless valid
+          unless valid
+            raise Error.new("Netdisco returned an invalid device inventory", code: :invalid_inventory), cause: nil
+          end
+        end
+
+        def validate_credentials!(username, password, api_key)
+          unless (api_key.nil? && present?(username) && present?(password)) ||
+                 (present?(api_key) && username.nil? && password.nil?)
+            raise ArgumentError, "provide either username and password or api_key"
+          end
+          if [username, password, api_key].compact.any? { |value| value.match?(/[\r\n\x00]/) }
+            raise ArgumentError, "credentials must be single-line strings"
+          end
         end
 
-        # 判断凭据字段是否为非空字符串。
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         def present?(value) = value.is_a?(String) && !value.strip.empty?
       end
     end