net-connector 0.7.3 → 0.9.0

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "English"
 require "forwardable"
 require_relative "../engine/core"
 require_relative "profile"
@@ -67,12 +66,14 @@ module Net
         begin
           device.connect
           yield device
+        rescue Exception # rubocop:disable Lint/RescueException -- 本次连接或块失败时仍关闭设备，并保留原始故障或中断。
+          failed = true
+          raise
         ensure
-          active_error = $ERROR_INFO
           begin
             device.close
-          rescue StandardError
-            raise unless active_error
+          rescue Exception # rubocop:disable Lint/RescueException -- 只保留本次作用域的原始异常，不受外层已处理异常影响。
+            raise unless failed
           end
         end
       end
@@ -249,17 +250,23 @@ module Net
 
         execution = build_execution(operation: operation, prompt: prompt, after_command: after_command, privilege: privilege)
         output_sensitive = script.any?(&:output_sensitive?)
+        result = nil
         @session.perform(:script) do
           @session.log_script(operation: operation, steps: execution.steps) do
             @session.with_sensitive_output(output_sensitive) { before_batch(execution) }
             result = execution.execute_script(script, &on_step)
             sensitive_result = output_sensitive || script.any?(&:sensitive?) || execution.sensitive?
             @session.with_sensitive_output(sensitive_result) do
-              finalize_script_result(result, finalize)
+              result = finalize_script_result(result, finalize)
             end
           end
         end
       rescue Error => error
+        # 脚本完成后的日志收尾仍可能失败，已经生成的配置与主错误保持权威。
+        if result.is_a?(Result)
+          return Result.new(steps: result.steps, config: result.config, error: result.error || error)
+        end
+
         Result.new(steps: execution ? execution.steps : [], error: error)
       end
 

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

@@ -39,6 +39,7 @@ module Net
       end
     end
 
+    # 先取得路径锁再采集和原子写入；提交后的收尾错误仍保留备份元数据。
     class LocalBackup
       # 设备入口与功能实现共置，Base 只组合能力，不重复业务流程。
       module Capability
@@ -77,12 +78,14 @@ module Net
         backup = Backup.new(path: destination, bytes: contents.bytesize,
                             sha256: digest, collected_at: Time.now.utc, change: change,
                             previous_sha256: previous_digest)
+        # 内容未变也须核对权限与目录项身份；只在两者仍有效时保留原文件和 mtime。
         if change != :unchanged || previous.mode != 0o600 || !Storage::SafeFile.same_entry?(destination, previous)
           write_backup(backup, contents)
         end
         backup
       end
 
+      # 替换后失败仍交付已提交的备份回执，不能让调用方误判为没有产物。
       def write_backup(backup, contents)
         Storage::PrivateFile.write(backup.path, contents)
       rescue Storage::PrivateFile::WriteError => error

data/lib/net/connector/device/running_config/strategy.rb

@@ -5,6 +5,7 @@ require_relative "../../engine/terminal_renderer"
 module Net
   module Connector
     class RunningConfig
+      # 采集策略决定业务步骤、视图提示符和响应校验；默认不改写配置正文。
       class Strategy
         # 保存策略所属设备，供提示符和厂商校验使用。
         def initialize(device) = @device = device
@@ -24,7 +25,7 @@ module Net
         def validate_response!(_command, _response, _execution) end
       end
 
-      # 使用终端行编辑规则渲染 H3C、Huawei 和 Radware 配置。
+      # 按终端行编辑规则还原配置画面，厂商子类只清理已识别的响应头。
       class Rendered < Strategy
         # 应用终端行编辑规则，还原设备最终显示的配置文本。
         def clean(text) = TerminalRenderer.render(text)

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

@@ -6,6 +6,7 @@ require_relative "running_config/strategy"
 
 module Net
   module Connector
+    # 单次运行配置采集的协调器；策略状态仅在当前会话租约与 Fiber 内可见。
     class RunningConfig
       # 设备只引入此能力；采集入口和策略作用域与采集流程一起维护。
       module Capability
@@ -40,6 +41,7 @@ module Net
           @config_strategy_scope = previous
         end
 
+        # 离线清理使用新策略；只有当前 Fiber 可复用正在采集的策略状态。
         def config_strategy
           scope = @config_strategy_scope
           scope && scope.first.equal?(Fiber.current) ? scope.last : RunningConfig.strategy(self)

data/lib/net/connector/device/tftp/receipt.rb

@@ -15,6 +15,7 @@ module Net
       FORMATS = %i[cfg xml dat tgz unknown].freeze
       private_constant :KINDS, :FORMATS
 
+      # 校验目标、配置种类和核验状态，只有服务器核验成功才允许携带文件摘要与归档路径。
       def initialize(server:, path:, completed_at:, configuration_kind: :unknown, source_file: nil,
                      format: :unknown, requested_path: nil, verification: :device_reported, server_sha256: nil,
                      server_bytes: nil, local_path: nil, archive_path: nil)

data/lib/net/connector/device/tftp/strategy.rb

@@ -5,8 +5,9 @@ require_relative "target"
 module Net
   module Connector
     class Tftp
+      # 厂商声明命名、交互与完成证据；公共层统一过滤精确回显和保留失败历史。
       class Strategy
-        # 厂商只声明格式差异，清单规划与设备直连共用同一命名规则。
+        # 声明默认配置扩展名，清单规划与设备直连共用同一命名规则。
         def self.file_extension = "cfg"
 
         # 不创建会话即可生成目标名，供批量计划检查文件覆盖风险。
@@ -15,10 +16,7 @@ module Net
         end
 
         # 保存 TFTP 厂商策略使用的设备对象。
-        def initialize(device)
-          @device = device
-          @responses = []
-        end
+        def initialize(device) = @device = device
 
         # 返回调用方指定的配置源文件。
         def resolve_source_file(value) = value
@@ -29,11 +27,21 @@ module Net
         # 返回目标中指定的远端文件名。
         def remote_path(target, _result) = target.path
 
+        # 原文、历史和终端画面共同保存失败证据；仅过滤精确输入回显与提示符。
+        def failure_outputs(result)
+          return enum_for(__method__, result) unless block_given?
+
+          result.steps.each do |step|
+            yield evidence_lines(step, step.output).join("\n")
+            yield evidence_lines(step, TerminalRenderer.render(step.output.gsub(/\r(?!\n)/, "\n"))).join("\n")
+            yield evidence_lines(step, TerminalRenderer.render(step.output)).join("\n")
+          end
+        end
+
         private
 
-        # 记录脚本的静态响应，避免文件名或 VRF 回显成为传输完成证据。
+        # 静态交互不进入业务输出，证据过滤从完成步骤读取原始声明。
         def interaction(pattern, response)
-          @responses << response.chomp
           Interaction.new(pattern, response, capture: false)
         end
 
@@ -45,8 +53,19 @@ module Net
           output = TerminalRenderer.render(step.output)
           prompt = TerminalRenderer.render(step.prompt.to_s)
           output = output.delete_suffix(prompt) unless prompt.empty?
-          echoes = [step.command.text, "#{prompt.strip}#{step.command.text}", *@responses]
-          output.each_line.map(&:strip).reject { |line| line.empty? || echoes.include?(line) }
+          evidence_lines(step, output)
+        end
+
+        # 移除精确命令、静态响应和提示符，保留回车重绘前后的设备消息。
+        def evidence_lines(step, output)
+          prompt = TerminalRenderer.render(step.prompt.to_s).strip
+          responses = step.command.interactions.filter_map { |reply| reply.static_response&.chomp }
+          echoes = [step.command.text, "#{prompt}#{step.command.text}", *responses]
+          # 原文中的每次回车分开核对，避免重绘回显误报，也保留被覆盖的诊断。
+          output.each_line.flat_map { |line| line.split(/\r(?!\n)/) }.map do |line|
+            # 样式不改变字符历史；光标移动和擦除不能拿来删掉原始失败消息。
+            line.gsub(/\e\[[0-9;:]*m/, "").strip
+          end.reject { |line| line.empty? || line == prompt || echoes.include?(line) }
         end
 
         # 只接受字节数非零、已发送量与总量相同的 curl 完成进度行。

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

@@ -5,6 +5,7 @@ require_relative "tftp/receipt"
 
 module Net
   module Connector
+    # 协调原生上传与设备证据核对；设备报告完成和服务器文件核验分别处理。
     class Tftp
       # 设备入口与功能实现共置，Base 只组合能力，不重复业务流程。
       module Capability
@@ -66,6 +67,7 @@ module Net
 
       private
 
+      # 只接受厂商声明的固定元数据字段，沿用已确认的上传与路径回执。
       def build_receipt(strategy, target, source_file, explicit_source, receipt)
         metadata = strategy.receipt_metadata(target, source_file: source_file, explicit_source: explicit_source)
         unless metadata.is_a?(Hash) && (metadata.keys - %i[configuration_kind source_file format requested_path]).empty?
@@ -74,6 +76,7 @@ module Net
         receipt.with(**{ source_file: source_file, requested_path: target.path }.merge(metadata))
       end
 
+      # 实际目标必须重新校验；解析失败保留上传事实，但不推测远端路径。
       def remote_path(strategy, target, result, receipt)
         TftpTarget.validate_path!(strategy.remote_path(target, result))
       rescue StandardError => error
@@ -83,33 +86,37 @@ module Net
 
       # 失败证据优先；步骤中的明确完成行可在随后清理失败时证明设备已经报告上传。
       def confirm_transfer!(strategy, target, result)
-        if transfer_failed?(result)
-          @device.log_event("tftp_backup", level: :error, status: "transfer_failed", phase: :tftp_backup,
-                                code: :transfer_failed, server: target.host)
-          raise DeviceError.new("device reported TFTP backup failure",
-                                code: :transfer_failed, host: @device.host, phase: :tftp_backup)
+        if transfer_failed?(strategy, result)
+          reject_transfer!(target, :transfer_failed, "device reported TFTP backup failure")
         end
         return if strategy.device_reported_complete?(result)
 
         result.value! if result.failure?
-        @device.log_event("tftp_backup", level: :error, status: "transfer_unconfirmed", phase: :tftp_backup,
-                              code: :transfer_unconfirmed, server: target.host)
-        raise DeviceError.new("device did not confirm TFTP backup completion",
-                              code: :transfer_unconfirmed, host: @device.host, phase: :tftp_backup)
+        reject_transfer!(target, :transfer_unconfirmed, "device did not confirm TFTP backup completion")
       end
 
-      # 识别设备回显中的传输失败信息。
-      def transfer_failed?(result)
-        result.steps.any? do |step|
+      # 设备证据先决定业务失败；事件记录失败不能把明确的上传状态替换为日志故障。
+      def reject_transfer!(target, code, message)
+        failure = DeviceError.new(message, code: code, host: @device.host, phase: :tftp_backup)
+        begin
+          @device.log_event("tftp_backup", level: :error, status: code.to_s, phase: :tftp_backup,
+                            code: code, server: target.host)
+        rescue Error
+          # 主错误仍在下方抛出，不重试事件或设备命令。
+        end
+        raise failure, cause: nil
+      end
+
+      # 已有厂商策略可提供证据枚举；其他策略复用公共证据过滤，不重跑交互回调。
+      def transfer_failed?(strategy, result)
+        evidence = strategy.respond_to?(:failure_outputs) ? strategy : Strategy.new(@device)
+        evidence.failure_outputs(result).any? do |output|
           # 文件名中的 failed.cfg、error-backup 等不属于诊断词；句末标点仍是词边界。
           pattern = %r{(?<![\w./-])
             (?:error|failed|failure|aborted|denied|timed\ out|timeout|not\ found|no\ such\ file|
                unable\ to|network\ is\ unreachable|can't\ open)
             (?![\w/-]|\.[\w])}ix
-          # 原始诊断不能被回车抹除，颜色控制符也不能掩盖失败词。
-          history = step.output.gsub(/\r(?!\n)/, "\n")
-          step.output.match?(pattern) || TerminalRenderer.render(history).match?(pattern) ||
-            TerminalRenderer.render(step.output).match?(pattern)
+          output.match?(pattern)
         end
       end
     end

data/lib/net/connector/device/topology/immediate_strategy.rb

@@ -24,9 +24,10 @@ module Net
         def persistence_confirmed?(result)
           !result.steps.empty? && result.steps.all? do |step|
             raw = step.output.delete_suffix(step.prompt.to_s)
+            history = raw.gsub(/\e\[[0-9;:]*m/, "").gsub(/\r(?!\n)/, "\n")
             rendered = TerminalRenderer.render(raw)
             failure = /\b(?:error|failed|failure|denied|cannot|unable|unsuccessful|aborted)\b/i
-            next false if raw.match?(failure) || rendered.match?(failure)
+            next false if history.match?(failure) || TerminalRenderer.render(history).match?(failure) || rendered.match?(failure)
 
             rendered.lines.any? { |line| line.strip.match?(persistence_pattern) }
           end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "expect/pty"
 require_relative "dialogue"
 
 module Net

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# 组合设备会话需要的引擎组件；厂商策略和清单客户端由各自入口按需加载。
 require_relative "configuration"
 require_relative "dialogue"
 require_relative "session"

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

@@ -2,7 +2,6 @@
 
 require_relative "errors"
 require_relative "terminal_renderer"
-require "expect/pty"
 
 module Net
   module Connector
@@ -37,6 +36,9 @@ module Net
       # 根据当前提示计算响应文本或调用动态响应函数。
       def response(prompt) = @response.respond_to?(:call) ? @response.call(prompt) : @response
 
+      # 证据核对只能读取声明的静态响应，不能重新执行动态挑战回调。
+      def static_response = (@response if @response.is_a?(String))
+
       # 判断响应是否需要从日志和错误上下文中脱敏。
       def sensitive? = @sensitive
 
@@ -79,8 +81,8 @@ module Net
       def diagnostic(output)
         return if command_errors.empty?
 
-        # 先保留被回车覆写的失败，再识别颜色或退格处理后的可见诊断。
-        raw = output.gsub(/\r(?!\n)/, "\n")
+        # 样式不改变诊断历史；先拼回被颜色拆开的词，再保留重绘之前的失败。
+        raw = output.gsub(/\e\[[0-9;:]*m/, "").gsub(/\r(?!\n)/, "\n")
         diagnostic_line(raw) || (diagnostic_line(TerminalRenderer.render(output)) if output.match?(/[\e\b]/))
       end
 
@@ -113,136 +115,5 @@ module Net
       # 返回响应大小摘要，不展开原始内容。
       def inspect = "#<#{self.class} bytes=#{raw.bytesize}>"
     end
-
-    # 在传输层上执行有界对话；收到字节或分页标记不会重置截止时间。
-    class ResponseReader
-      # 保存会话引用，以便读取器使用传输、配置和脱敏上下文。
-      def initialize(session)
-        @session = session
-      end
-
-      # 读取到结束提示、失败模式或超时，并处理交互响应和输出上限。
-      def read(prompt:, interactions:, phase:, timeout: nil, deadline: nil, command: nil, failures: {})
-        deadline ||= Expect.monotonic + timeout
-        patterns = [*failures.keys, *interactions.map(&:pattern), prompt]
-        raw = []
-        output = []
-        counts = Hash.new(0)
-        bytes = 0
-        loop do
-          event = read_event(patterns, deadline)
-          raw << event.before unless event.before.empty?
-          output << event.before unless event.before.empty?
-          bytes += event.before.bytesize + event.match.bytesize
-          validate_event!(event, bytes, raw, phase, command)
-
-          if event.index == patterns.size
-            raw << event.match
-            output << event.match
-          elsif event.index == patterns.size - 1
-            return finish_response(event.match, raw, output, phase, command)
-          elsif event.index < failures.size
-            raise build_connection_error(failures.values.fetch(event.index), phase, command), cause: nil
-          else
-            reply = interactions.fetch(event.index - failures.size)
-            raw << event.match
-            output << event.match if reply.capture?
-            respond(reply, event.match, counts, deadline, phase, command)
-          end
-          next if Expect.monotonic < deadline
-
-          raise build_read_error(nil, phase, command, raw.join), cause: nil
-        end
-      end
-
-      private
-
-      # 分页和流式输出只消耗剩余时间，不为下一次读取重新计时。
-      def read_event(patterns, deadline)
-        @session.transport.read(patterns, timeout: [deadline - Expect.monotonic, 0].max)
-      end
-
-      # 连接失败模式携带稳定错误码，供连接级恢复规则选择处理方式。
-      def build_connection_error(failure, phase, command)
-        klass, code = failure
-        @session.build_error(klass, "device connection failed (#{code})", phase: phase, code: code, command: command)
-      end
-
-      # 先限制原始字节数，再处理传输失败，避免错误输出绕过总量限制。
-      def validate_event!(event, bytes, raw, phase, command)
-        if bytes > @session.configuration.max_output_bytes
-          raise @session.build_error(OutputLimitExceeded, "device output exceeded max_output_bytes",
-                                     phase: phase, command: command, output: (raw + [event.match]).join), cause: nil
-        end
-        raise build_read_error(event, phase, command, raw.join), cause: nil unless event.matched?
-      end
-
-      # 完整提示符必须消费字节；交互标记可从业务输出排除，但原始响应始终保留。
-      def finish_response(prompt, raw, output, phase, command)
-        if prompt.empty?
-          raise @session.build_error(PromptError, "prompt pattern did not consume any output",
-                                     phase: phase, command: command, output: raw.join), cause: nil
-        end
-
-        raw << prompt
-        output << prompt
-        raw_text = raw.join
-        Response.new(raw: raw_text, output: (output == raw) ? raw_text : output.join, prompt: prompt)
-      end
-
-      # 重复提示和缺失应答必须在写入前失败；所有应答共用读取操作的截止时间。
-      def respond(reply, prompt, counts, deadline, phase, command)
-        counts[reply] += 1
-        if prompt.empty? || (reply.limit && counts[reply] > reply.limit)
-          raise build_interaction_error("response rejected or repeated", phase, command), cause: nil
-        end
-
-        value = interaction_response(reply, prompt, phase, command)
-        raise build_interaction_error("response unavailable", phase, command), cause: nil unless value.is_a?(String)
-
-        @session.redactor.remember(value.chomp) if reply.sensitive?
-        @session.write(value, deadline: deadline, phase: phase, command: command)
-      end
-
-      # 动态口令尚未返回时无法加入词表，须在敏感范围内先归一化回调异常。
-      # 成功后由调用方登记响应，临时敏感标记不会影响后续普通命令的诊断。
-      def interaction_response(reply, prompt, phase, command)
-        return reply.response(prompt) unless reply.sensitive?
-
-        @session.redactor.with_scope(reuse: true) do
-          @session.redactor.sensitive!
-          reply.response(prompt)
-        rescue => error
-          raise @session.normalize_error(error, phase: phase, command: command), cause: nil
-        end
-      end
-
-      # 将交互拒绝或响应缺失转换为认证或脚本错误。
-      def build_interaction_error(message, phase, command)
-        authenticating = %i[login enable].include?(phase)
-        klass = authenticating ? AuthenticationError : ScriptError
-        label = authenticating ? "authentication" : "command interaction"
-        @session.build_error(klass, "#{label} #{message}", phase: phase, command: command)
-      end
-
-      # 根据 EOF、提示符、阶段和底层异常选择具体读取错误类型。
-      def build_read_error(event, phase, command, output)
-        if event&.error.is_a?(Exception)
-          return @session.build_error(TransportError, "transport read failed", phase: phase, command: command,
-                                      underlying: event.error, output: output)
-        end
-        klass = if event&.error == :eof
-                  ConnectionClosed
-                elsif command&.prompt
-                  PromptError
-                elsif %i[login enable].include?(phase)
-                  LoginTimeout
-                else
-                  CommandTimeout
-                end
-        @session.build_error(klass, "device response #{event&.error || :timeout}", phase: phase,
-                             command: command, output: output)
-      end
-    end
   end
 end

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "expect/redactor"
 require_relative "error_metadata"
 
 module Net
@@ -89,96 +88,5 @@ module Net
       # 返回底层异常类型摘要。
       def inspect = "#<#{self.class} type=#{type}>"
     end
-
-    # 管理连接器的秘密作用域和输出敏感性；字节过滤统一委托给 expect-pty。
-    class Redactor
-      MASK = "[REDACTED]".b.freeze
-
-      # 保存初始凭据，并建立第一版脱敏词表。
-      def initialize(*secrets)
-        unless Expect.constants(false).include?(:Redactor) && Expect::Redactor.respond_to?(:redact)
-          raise LoadError, "net-connector requires expect-pty with the public Expect::Redactor API"
-        end
-
-        @configured = secrets.compact.map(&:b).map(&:freeze).freeze
-        reset
-      end
-
-      # 重置动态词表，同时保留配置中的固定凭据。
-      def reset
-        @secrets = []
-        @patterns = nil
-        @scoped = false
-        @sensitive = false
-        @output_sensitive = false
-        @configured.each { |secret| remember(secret) }
-      end
-
-      # 临时命令响应在错误归一化期间保留，离开作用域后不进入长期会话。
-      def with_scope(reuse: false)
-        return yield if reuse && @scoped
-
-        previous = @secrets
-        previous_patterns = @patterns
-        previous_scoped = @scoped
-        previous_sensitive = @sensitive
-        previous_output_sensitive = @output_sensitive
-        @secrets = previous.dup
-        @scoped = true
-        begin
-          yield
-        ensure
-          @secrets = previous
-          @patterns = previous_patterns
-          @scoped = previous_scoped
-          @sensitive = previous_sensitive
-          @output_sensitive = previous_output_sensitive
-        end
-      end
-
-      # 敏感命令和交互的异常可能只引用秘密的一部分，不能只依赖完整词匹配。
-      def sensitive! = @sensitive = true
-
-      # 判断当前脱敏范围是否包含敏感交互。
-      def sensitive? = @sensitive
-
-      # 输出敏感时不把正文加入词表；只在当前范围内屏蔽日志和任意错误正文。
-      def output_sensitive!
-        @output_sensitive = true
-        sensitive!
-      end
-
-      # 后续查询继承输出边界，即使查询命令本身没有敏感标记。
-      def output_sensitive? = @output_sensitive
-
-      # 只维护当前作用域的注册词；匹配次序和重叠区间交给共享过滤器。
-      def remember(secret)
-        return if secret.nil? || secret.empty?
-
-        bytes = secret.b
-        return if @secrets.include?(bytes)
-
-        @secrets << bytes.freeze
-        @patterns = nil
-      end
-
-      # 一次性诊断不共享流状态；原标记作为不透明区间，避免再次展开它。
-      def call(text)
-        Expect::Redactor.redact(text.to_s.b, patterns, replacement: MASK)
-      end
-
-      # 每个日志目标独占过滤流，跨分片尾部和重叠掩码由依赖库维护。
-      def stream
-        Expect::Redactor.new(patterns, replacement: MASK)
-      end
-
-      # 临时范围恢复时，日志流可以同步恢复注册词表，不缓存配置正文。
-      def patterns
-        @patterns ||= (@secrets.empty? ? [] : (@secrets + [MASK]).uniq).freeze
-      end
-
-      # 返回脱敏器类型摘要。
-      def inspect = "#<#{self.class}>"
-    end
   end
 end

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?