net-connector 0.8.0 → 0.9.0

data/lib/net/connector/engine/known_hosts.rb

@@ -25,8 +25,8 @@ module Net
         @file.write(@original)
         @file.flush
         remove_host(@path) if @replace
-      rescue Exception # rubocop:disable Lint/RescueException -- Remove the private snapshot on interruption.
-        close
+      rescue Exception # rubocop:disable Lint/RescueException -- 中断时也删除私有快照。
+        close_preserving_failure
         raise
       end
 
@@ -57,13 +57,29 @@ module Net
       end
 
       def close
-        File.unlink(@path + ".old") if @path && File.exist?(@path + ".old")
-        @file&.close!
+        file = @file
         @file = nil
+        File.unlink(@path + ".old") if @path && File.exist?(@path + ".old")
+      rescue Exception # rubocop:disable Lint/RescueException -- 删除附属文件失败或中断后仍须关闭私有快照。
+        failed = true
+        raise
+      ensure
+        begin
+          file&.close!
+        rescue Exception # rubocop:disable Lint/RescueException -- 私有快照清理不能覆盖先发生的删除故障。
+          raise unless failed
+        end
       end
 
       private
 
+      # 初始化失败时保留原始异常，同时尽力清理已经创建的临时文件。
+      def close_preserving_failure
+        close
+      rescue Exception # rubocop:disable Lint/RescueException -- 不让清理异常覆盖初始化故障或用户中断。
+        nil
+      end
+
       def read_shared
         File.open(@destination, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
           raise IOError, "known_hosts must be a regular file" unless file.stat.file?

data/lib/net/connector/engine/log.rb

@@ -39,7 +39,7 @@ module Net
           open_transcript if @io && @configuration.log_level == :debug
         end
       rescue => error
-        close_preserving_error
+        close_preserving_failure
         raise build_error("unable to open session log", error), cause: nil
       end
 
@@ -49,13 +49,13 @@ module Net
         finish_output
         @context = @context.merge(fields).freeze
         yield
-      rescue Exception # rubocop:disable Lint/RescueException -- Preserve only failures propagating from this scope, including interrupts.
+      rescue Exception # rubocop:disable Lint/RescueException -- 保留从当前作用域向外传播的故障，包括中断。
         failed = true
         raise
       ensure
         begin
           finish_output
-        rescue Error
+        rescue Exception # rubocop:disable Lint/RescueException -- 收尾故障或中断不能覆盖当前作用域的原始失败。
           raise unless failed
         ensure
           @context = previous
@@ -171,13 +171,13 @@ module Net
         finish_output
         @transport.log_output = nil if @transport
         yield
-      rescue Exception # rubocop:disable Lint/RescueException -- Restore attachment without replacing this scope's failure or interruption.
+      rescue Exception # rubocop:disable Lint/RescueException -- 恢复日志接线，不覆盖当前作用域的故障或中断。
         failed = true
         raise
       ensure
         begin
           @transport.log_output = self if @transport && @writer && @attached
-        rescue StandardError
+        rescue Exception # rubocop:disable Lint/RescueException -- 接线恢复故障或中断不能覆盖原始操作异常。
           # 恢复接线仍须尝试，但不能盖掉设备失败或用户中断。
           raise unless failed
         end
@@ -188,9 +188,14 @@ module Net
         begin
           @transport.log_output = nil if @transport
           finish_output
+        rescue Exception # rubocop:disable Lint/RescueException -- 脱离日志或刷新失败后仍须关闭文件并清除状态。
+          failed = true
+          raise
         ensure
           begin
             @io&.close
+          rescue Exception # rubocop:disable Lint/RescueException -- 文件关闭不能覆盖首个日志收尾故障或中断。
+            raise unless failed
           ensure
             @writer = @output = @transcript = @logger = @io = @transport = @session_id = nil
             @attached = false
@@ -249,10 +254,10 @@ module Net
           file.binmode
           file.write("\n") if file.size.positive? && @configuration.log_format == :text
           file
-        rescue Exception # rubocop:disable Lint/RescueException -- Release partially configured files on interrupts too.
+        rescue Exception # rubocop:disable Lint/RescueException -- 中断时也释放尚未完成设置的文件。
           begin
             file.close
-          rescue
+          rescue Exception # rubocop:disable Lint/RescueException -- 保留文件设置的原始故障或中断。
             # 保留设置失败的原始原因。
           end
           raise
@@ -260,9 +265,9 @@ module Net
       end
 
       # 在日志打开失败后尽力释放资源。
-      def close_preserving_error
+      def close_preserving_failure
         close
-      rescue
+      rescue Exception # rubocop:disable Lint/RescueException -- 清理故障或中断不能覆盖日志打开失败。
         nil
       end
 

data/lib/net/connector/engine/recovery.rb

@@ -48,7 +48,7 @@ module Net
         @rules.freeze
       end
 
-      # 依次尝试恢复规则，并只返回第一个新传输对象。
+      # 依次尝试恢复规则，只采用首个可用传输；密钥替换可以复用原对象。
       def recover(error, transport)
         @rules.lazy.filter_map { |rule| rule.recover(error, transport) }.first
       end

data/lib/net/connector/engine/session.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "English"
 require_relative "authentication"
 require_relative "log"
 require_relative "redactor"
@@ -182,8 +181,11 @@ module Net
           @state = :interacting
           begin
             transport.interact(**options)
+          rescue Exception # rubocop:disable Lint/RescueException -- 交互失败或中断后仍关闭会话，保留本次原始异常。
+            failed = true
+            raise
           ensure
-            $ERROR_INFO ? close_preserving_failure : close_resources
+            failed ? close_preserving_failure : close_resources
           end
         end
       end
@@ -249,7 +251,7 @@ module Net
           failure = normalize_error(error, phase: phase)
           close_preserving_failure
           raise failure, cause: nil
-        rescue Exception # rubocop:disable Lint/RescueException -- Interrupts release the transport, then propagate.
+        rescue Exception # rubocop:disable Lint/RescueException -- 中断先释放传输资源，再继续向外传播。
           close_preserving_failure
           raise
         ensure
@@ -384,8 +386,15 @@ module Net
         @prompt = nil
         begin
           transport.close
+        rescue Exception # rubocop:disable Lint/RescueException -- 传输关闭失败或中断后仍须尝试关闭日志。
+          failed = true
+          raise
         ensure
-          @log.close
+          begin
+            @log.close
+          rescue Exception # rubocop:disable Lint/RescueException -- 日志收尾不能覆盖传输关闭的首个失败。
+            raise unless failed
+          end
         end
         nil
       rescue => error
@@ -395,7 +404,7 @@ module Net
       # 尝试清理资源但不覆盖原始操作异常。
       def close_preserving_failure
         close_resources
-      rescue
+      rescue Exception # rubocop:disable Lint/RescueException -- 原操作失败时，清理故障或中断均不得覆盖它。
         # 所有清理路径完成后，原始操作异常仍然是权威结果。
         nil
       end

data/lib/net/connector/engine/transport.rb

@@ -65,12 +65,8 @@ module Net
             @channel.spawn(*argv)
           end
           self
-        rescue Exception # rubocop:disable Lint/RescueException -- A half-open PTY must be released on interrupts.
-          begin
-            close
-          rescue
-            # 尝试释放半打开信道后，仍然抛出原始失败。
-          end
+        rescue Exception # rubocop:disable Lint/RescueException -- 中断时也必须释放尚未完成初始化的 PTY。
+          close_preserving_failure
           raise
         end
 
@@ -120,6 +116,13 @@ module Net
 
         private
 
+        # 已有操作异常时仍尝试清理；次级故障或中断不能覆盖原始失败。
+        def close_preserving_failure
+          close
+        rescue Exception # rubocop:disable Lint/RescueException -- 清理后继续传播原始操作异常。
+          nil
+        end
+
         # 检查缓冲上限并把设备输出写入当前日志目标。
         def write_log_output(bytes)
           if @channel.buffer.bytesize > configuration.max_output_bytes
@@ -148,8 +151,8 @@ module Net
             @known_hosts = KnownHosts.new(configuration, replace: @replace_host_key)
           end
           super
-        rescue Exception # rubocop:disable Lint/RescueException -- Release a staged trust file on failed startup.
-          close
+        rescue Exception # rubocop:disable Lint/RescueException -- 启动失败或中断时释放临时信任文件。
+          close_preserving_failure
           raise
         end
 
@@ -159,10 +162,18 @@ module Net
         end
 
         def close
+          known_hosts = @known_hosts
+          @known_hosts = nil
           super
+        rescue Exception # rubocop:disable Lint/RescueException -- 全部资源均须尝试关闭，保留首个失败或中断。
+          failed = true
+          raise
         ensure
-          @known_hosts&.close
-          @known_hosts = nil
+          begin
+            known_hosts&.close
+          rescue Exception # rubocop:disable Lint/RescueException -- 信任文件收尾不能覆盖传输关闭的原始异常。
+            raise unless failed
+          end
         end
 
         # 返回 SSH 协议标识。

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

@@ -14,19 +14,21 @@ module Net
     module Netdisco
       # 人类批次入口：固定配置、预览、执行、保存报告，最后决定输出与退出码。
       class BackupRun
+        # 保存批次模式与调用方 IO，构造阶段不读取清单、不创建目录。
         def initialize(mode: :backup, argv: ARGV, env: ENV, input: $stdin, output: $stdout, error: $stderr)
           raise ArgumentError, "mode must be backup or tftp" unless %i[backup tftp].include?(mode)
 
           @mode, @argv, @env, @input, @output, @error = mode, argv, env, input, output, error
         end
 
+        # 先固定并校验策略，再预览、执行和保存报告；成功判定使用最终报告。
         def run
           options = CLI::Options.parse(argv: @argv, input: @input, output: @output, error: @error)
           return 0 if options[:help]
 
           settings, success_policy, server_root, batch_directory = prepare(options)
           client, credentials = Connection.build(settings, stdin_credentials: options[:stdin_credentials], input: @input)
-          progress = Progress.new(io: @error, enabled: @env.fetch("NC_PROGRESS", "1") != "0", verbose: options[:verbose])
+          progress = Progress.new(io: @error, enabled: !options[:no_progress], verbose: options[:verbose])
           resolver = ->(device) { credentials.call(device)&.merge(on_event: progress.method(:event)) }
           fleet = Fleet.new(client: client, settings: settings, credentials: resolver, result_store: nil)
           progress.reading_inventory
@@ -57,8 +59,9 @@ module Net
 
         private
 
+        # 预检完成后才创建批次目录；补充日志路径时保持原策略快照与动态凭据来源。
         def prepare(options)
-          settings = CLI::Options.settings(options, env: @env)
+          settings = CLI::Options.settings(options, env: @env).for_run(mode: @mode)
           success_policy = options.fetch(:success_policy, :selected)
           raise ArgumentError, "verified policy requires TFTP mode" if success_policy == :verified && @mode != :tftp
           raise ArgumentError, "--tftp-root requires TFTP mode" if options[:tftp_root] && @mode != :tftp
@@ -69,10 +72,10 @@ module Net
           if @mode == :tftp && !settings.log_directory
             settings = settings.with_overrides("NC_LOG_DIRECTORY" => File.join(batch_directory, "logs"))
           end
-          settings = settings.for_run(mode: @mode)
           [settings, success_policy, server_root, batch_directory]
         end
 
+        # 事件流仅记录受控元数据；计划写入后在有界工作线程中执行同一批设备。
         def execute(fleet, settings, plan, batch_directory, progress, success_policy, server_root)
           File.open(File.join(batch_directory, "events.jsonl"), File::WRONLY | File::CREAT | File::EXCL, 0o600) do |events|
             options = { plan: plan, concurrency: settings.concurrency, success_policy: success_policy,
@@ -89,6 +92,7 @@ module Net
           end
         end
 
+        # 将任务结果追加到私有事件流并更新进度；异常由工作线程保留为回调诊断。
         def result_callback(progress, events)
           lock = Mutex.new
           lambda do |outcome|
@@ -102,6 +106,7 @@ module Net
           end
         end
 
+        # 报告先保存，再显示完成信息；终端收尾失败只补写诊断，不重放任务。
         def finish(report, progress, options, batch_directory, plan, concurrency)
           progress.finish(report)
           progress.location(report.report_location) if report.report_location
@@ -121,21 +126,24 @@ module Net
           report.policy_success? ? 0 : 1
         end
 
+        # 输出故障只记录一次，保留已有批次结果和回调错误。
         def record_progress_error(report, progress)
           return report unless progress.output_error && !report.callback_errors.include?(progress.output_error)
 
           report.with(callback_errors: [*report.callback_errors, progress.output_error].freeze)
         end
 
+        # 优先使用显式核验根目录；仅服务器是本机地址时探测本机惯用 TFTP 目录。
         def tftp_root(settings, options)
-          server = settings.tftp_server || (raise ArgumentError, "TFTP_HOST or YAML tftp.server is required")
-          return options[:tftp_root] || @env["TFTP_ROOT"] if options[:tftp_root] || @env["TFTP_ROOT"]
+          server = settings.tftp_server || (raise ArgumentError, "YAML tftp.server is required")
+          return options[:tftp_root] || settings.tftp_root if options[:tftp_root] || settings.tftp_root
           return unless Socket.ip_address_list.any? { |address| address.ip_address == server }
 
           candidate = File.join(Dir.home, "Documents", "TFTP")
           candidate if File.directory?(candidate)
         end
 
+        # 预览来自已有计划，文件名按本次模式计算，不重新请求清单或设备。
         def plan_summary(plan)
           { total: plan.inventory.size, ready: plan.inventory.count(&:ready?),
             vendors: plan.inventory.group_by { |device| device.vendor || :unmapped }.transform_values(&:size),

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

@@ -11,6 +11,7 @@ module Net
       class CLI
         # 可注入参数与输入输出的备份选项，不退出宿主进程。
         class Options
+          # 复制参数数组，返回选项或帮助标记；非法输入抛错，不退出宿主进程。
           def self.parse(argv: ARGV, input: $stdin, output: $stdout, error: $stderr, program: $PROGRAM_NAME)
             values = { environment: {}, json: false, verbose: false, stdin_credentials: false }
             parser = parser_for(values, output: output, program: program)
@@ -22,7 +23,7 @@ module Net
               raise ArgumentError, "--stdin-credentials 不能与命令行凭据或密码提示同时使用"
             end
             read_password(values, :ask_password, "NC_DEVICE_PASSWORD", "设备密码", input: input, output: error)
-            read_password(values, :ask_netdisco_password, "NETDISCO_PASSWORD", "Netdisco 密码", input: input, output: error)
+            read_password(values, :ask_netdisco_password, "ND_PASSWORD", "Netdisco 密码", input: input, output: error)
 
             values
           rescue OptionParser::ParseError
@@ -36,6 +37,7 @@ module Net
               add_execution(opts, values)
               opts.on("--ask-password", "隐藏输入设备密码") { values[:ask_password] = true }
               opts.on("--ask-netdisco-password", "隐藏输入 Netdisco 密码") { values[:ask_netdisco_password] = true }
+              opts.on("--no-progress", "关闭进度显示") { values[:no_progress] = true }
               opts.on("--verbose", "显示逐条登录和命令事件") { values[:verbose] = true }
               opts.on("--json", "在 STDOUT 输出计划和结果 JSON") { values[:json] = true }
               opts.on("--stdin-credentials", "从标准输入读取凭据并等待 RUN") { values[:stdin_credentials] = true }
@@ -43,6 +45,7 @@ module Net
             end
           end
 
+          # 正式 CLI 与批次示例共用并发、抽样、核验和成功策略选项。
           def self.add_execution(opts, values)
             opts.on("-c", "--concurrency N", Integer, "并发设备数，1 至 50") do |count|
               raise OptionParser::InvalidArgument unless (1..Settings::MAX_CONCURRENCY).cover?(count)
@@ -60,14 +63,17 @@ module Net
             end
           end
 
+          # 公开 CLI 参数进入 overrides，凭据留在 environment；内部键不会重新开放已移除环境设置。
           def self.settings(options, env: ENV)
             raise ArgumentError, "--all 不能与抽样同时使用" if options[:all] && options[:limit]
 
             environment = environment(options, env: env)
             path = environment["NC_CONFIG"]
             defaults = path && !path.empty? ? ConfigFile.load(path) : {}
-            overrides = {}
-            { source: "NETDISCO_SOURCE", query: "NETDISCO_QUERY", query_params: "NETDISCO_QUERY_PARAMS",
+            keys = ConfigFile::FIELDS.values.flat_map { |fields| fields.values.map(&:first) }
+            overrides = options.fetch(:environment).slice(*keys)
+            environment = environment.reject { |key, _| overrides.key?(key) && !Settings::ENVIRONMENT_KEYS.include?(key) }
+            { source: "ND_SOURCE", query: "ND_QUERY", query_params: "ND_QUERY_PARAMS",
               max_script_output_bytes: "NC_MAX_SCRIPT_OUTPUT_BYTES", host: "NC_INCLUDE_HOSTS",
               limit: "NC_SAMPLE_PER_VENDOR" }.each do |option, key|
               overrides[key] = options[option].to_s if options.key?(option)
@@ -76,14 +82,15 @@ module Net
             Settings.new(env: environment, defaults: defaults, overrides: overrides)
           end
 
+          # 共用配置与凭据参数登记；具体入口决定后续预览、执行或导出。
           def self.add_settings(opts, values)
             {
               "--username USER" => ["NC_DEVICE_USERNAME", "设备登录用户名"],
               "--password PASSWORD" => ["NC_DEVICE_PASSWORD", "设备登录密码（可改用 --ask-password）"],
               "--enable-password PASSWORD" => ["NC_ENABLE_PASSWORD", "设备提权密码"],
-              "--netdisco-url URL" => ["NETDISCO_URL", "Netdisco 地址"],
-              "--netdisco-username USER" => ["NETDISCO_USERNAME", "Netdisco 用户名"],
-              "--netdisco-password PASSWORD" => ["NETDISCO_PASSWORD", "Netdisco 密码"],
+              "--netdisco-url URL" => ["ND_URL", "Netdisco 地址"],
+              "--netdisco-username USER" => ["ND_USERNAME", "Netdisco 用户名"],
+              "--netdisco-password PASSWORD" => ["ND_PASSWORD", "Netdisco 密码"],
               "--directory DIR" => ["NC_BACKUP_DIRECTORY", "备份目录，相对项目根目录"],
               "--config FILE" => ["NC_CONFIG", "YAML 配置，相对项目根目录"]
             }.each do |flag, (key, description)|
@@ -101,6 +108,7 @@ module Net
             end
           end
 
+          # 复制原环境并合并显式凭据，清除被通用凭据覆盖的厂商值及旧 API key。
           def self.environment(options, env: ENV)
             result = env.to_h.dup
             overrides = options.fetch(:environment)
@@ -114,12 +122,13 @@ module Net
                   (suffix != "PASSWORD" || !name.end_with?("_ENABLE_PASSWORD"))
               end
             end
-            if overrides.key?("NETDISCO_USERNAME") || overrides.key?("NETDISCO_PASSWORD")
-              result.delete("NETDISCO_API_KEY")
+            if overrides.key?("ND_USERNAME") || overrides.key?("ND_PASSWORD")
+              result.delete("ND_API_KEY")
             end
             result.merge(overrides)
           end
 
+          # 隐藏输入只用于交互终端；与显式密码互斥，不输出或记录密码内容。
           def self.read_password(values, flag, key, label, input:, output:)
             return unless values[flag]
 

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

@@ -39,7 +39,7 @@ module Net
             return 0
           end
           if options[:tftp] && !options[:plan] && !settings.tftp_server
-            raise ArgumentError, "TFTP_HOST is required"
+            raise ArgumentError, "YAML tftp.server is required"
           end
 
           fleet = @fleet_factory.call(settings)
@@ -71,7 +71,7 @@ module Net
 
         private
 
-        # 文件、环境变量、命令行按优先级覆盖，凭据仍只来自环境变量。
+        # 公开 CLI 参数覆盖 YAML 与 ND_URL；设备凭据按环境或显式 CLI 参数解析。
         def settings_for(options)
           Options.settings(options, env: @env)
         end
@@ -105,7 +105,7 @@ module Net
             fleet.tftp_backup_all(plan: plan, server: settings.tftp_server,
                                   concurrency: settings.concurrency,
                                   vrfs: settings.tftp_vrfs,
-                                  source_files: settings.tftp_source_files, verification_root: options[:tftp_root] || @env["TFTP_ROOT"], **reporting)
+                                  source_files: settings.tftp_source_files, verification_root: options[:tftp_root] || settings.tftp_root, **reporting)
           else
             fleet.backup_all(plan: plan, directory: settings.backup_directory,
                              concurrency: settings.concurrency, **reporting)

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

@@ -6,20 +6,24 @@ require "yaml"
 module Net
   module Connector
     module Netdisco
-      # 命令行使用的无凭据 YAML 配置，环境变量优先。
+      # 无凭据 YAML 配置；仅 ND_URL 允许从进程环境覆盖，其他策略由 CLI 覆盖。
       class ConfigFile
         FIELDS = {
-          "netdisco" => { "source" => ["NETDISCO_SOURCE", :string],
-                          "query" => ["NETDISCO_QUERY", :string],
-                          "query_params" => ["NETDISCO_QUERY_PARAMS", :json_array],
-                          "url" => ["NETDISCO_URL", :string],
-                          "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] },
+          "netdisco" => { "source" => ["ND_SOURCE", :string],
+                          "query" => ["ND_QUERY", :string],
+                          "query_params" => ["ND_QUERY_PARAMS", :json_array],
+                          "url" => ["ND_URL", :string],
+                          "page_size" => ["ND_PAGE_SIZE", :integer],
+                          "max_pages" => ["ND_MAX_PAGES", :integer],
+                          "max_response_bytes" => ["ND_MAX_RESPONSE_BYTES", :integer],
+                          "max_inventory_bytes" => ["ND_MAX_INVENTORY_BYTES", :integer],
+                          "max_devices" => ["ND_MAX_DEVICES", :integer],
+                          "inventory_timeout" => ["ND_INVENTORY_TIMEOUT", :number],
+                          "allow_insecure_http" => ["ND_ALLOW_INSECURE_HTTP", :boolean],
+                          "db_port" => ["ND_DB_PORT", :integer],
+                          "db_sslmode" => ["ND_DB_SSLMODE", :string],
+                          "db_sslrootcert" => ["ND_DB_SSLROOTCERT", :string],
+                          "db_connect_timeout" => ["ND_DB_CONNECT_TIMEOUT", :integer] },
           "backup" => { "directory" => ["NC_BACKUP_DIRECTORY", :string],
                         "concurrency" => ["NC_CONCURRENCY", :integer],
                         "limit_per_vendor" => ["NC_SAMPLE_PER_VENDOR", :integer] },
@@ -36,14 +40,15 @@ module Net
                      "host_key_policy" => ["NC_HOST_KEY_POLICY", :string],
                      "log_directory" => ["NC_LOG_DIRECTORY", :string],
                      "log_level" => ["NC_LOG_LEVEL", :string] },
-          "tftp" => { "server" => ["TFTP_HOST", :string],
+          "tftp" => { "server" => ["NC_TFTP_HOST", :string],
+                      "verification_root" => ["NC_TFTP_ROOT", :string],
                       "vrfs" => ["NC_TFTP_VRFS", :json],
                       "h3c_source_file" => ["NC_H3C_TFTP_SOURCE_FILE", :string],
                       "h3c_wireless_source_file" => ["NC_H3C_WIRELESS_TFTP_SOURCE_FILE", :string],
                       "huawei_source_file" => ["NC_HUAWEI_TFTP_SOURCE_FILE", :string] }
         }.freeze
 
-        # 安全读取 YAML 配置并映射到环境变量格式。
+        # 安全读取 YAML 配置并编码为 Settings 的内部键值。
         def self.load(path)
           raise ArgumentError, "config path must be a nonempty String" unless path.is_a?(String) && !path.empty?
 

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

@@ -8,15 +8,44 @@ module Net
     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"
+          host: "ND_DB_HOST", dbname: "ND_DB_NAME", user: "ND_DB_USER", password: "ND_DB_PASS"
         }.freeze
+        CONNECTION_OPTIONS = CONNECTION_ENV.merge(
+          port: "netdisco.db_port", sslmode: "netdisco.db_sslmode", sslrootcert: "netdisco.db_sslrootcert",
+          connect_timeout: "netdisco.db_connect_timeout"
+        ).freeze
         REQUIRED_CONNECTION_KEYS = %i[host dbname user password].freeze
+        POLICY_KEYS = (CONNECTION_OPTIONS.keys - REQUIRED_CONNECTION_KEYS).freeze
+        private_constant :POLICY_KEYS
         DEFAULTS = Client::DEFAULTS.except(:allow_insecure_http).freeze
 
+        # 预检与实际连接共用公开策略校验；不读取身份凭据，也不访问文件或数据库。
+        def self.connection_policy(**options)
+          raise ArgumentError, "unknown PostgreSQL connection policy" unless (options.keys - POLICY_KEYS).empty?
+
+          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_OPTIONS.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_OPTIONS.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
+          options.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+        end
+
+        # 纯校验 SQL、绑定参数和清单预算，不连接数据库或打印查询内容。
         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"
@@ -35,6 +64,7 @@ module Net
           ).freeze
         end
 
+        # 复制并校验查询与连接选项；真正连接由 devices 的资源作用域管理。
         def initialize(connection_options:, **options)
           @options = self.class.options(**options)
           @connection_options = validate_connection_options!(connection_options)
@@ -105,36 +135,22 @@ module Net
           end
         end
 
+        # 数据库名不得嵌入 URI/conninfo；合法选项仍受清单总期限及只读查询边界约束。
         def validate_connection_options!(options)
-          unless options.is_a?(Hash) && (options.keys - CONNECTION_ENV.keys).empty?
+          unless options.is_a?(Hash) && (options.keys - CONNECTION_OPTIONS.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"
+              raise ArgumentError, "#{CONNECTION_OPTIONS.fetch(key)} is required"
             end
+            raise ArgumentError, "#{CONNECTION_OPTIONS.fetch(key)} is invalid" if value.include?("\0")
           end
-          if options[:sslmode] && !%w[disable allow prefer require verify-ca verify-full].include?(options[:sslmode])
-            raise ArgumentError, "NETDISCO_DB_SSLMODE is invalid"
-          end
+          self.class.connection_policy(**options.slice(*POLICY_KEYS))
           # 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"
+            raise ArgumentError, "ND_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

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

@@ -17,6 +17,9 @@ module Net
           super(*frozen_values, **frozen_attributes)
         end
 
+        # Ruby 3.2 的 Data#with 不调用初始化；更新也须复制并冻结外部字符串。
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
         # 将 Netdisco 清单记录转换为可规划的设备对象。
         def self.from_row(row, rules:)
           valid = row.is_a?(Hash) && row["ip"].is_a?(String) && !row["ip"].empty? &&

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

@@ -30,6 +30,9 @@ module Net
                 verification: verification == :device_reported ? verification : nil)
         end
 
+        # 更新也经过初始化白名单；Ruby 3.2 的原生 Data#with 会跳过这一边界。
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
         # 读取已知错误的白名单属性后立即丢弃异常引用，不把回调对象保留进批次。
         def self.from(error, backup: nil, phase: nil)
           return unless error
@@ -44,6 +47,7 @@ module Net
           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,