net-connector 0.4.2 → 0.5.0

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../engine/errors"
+require_relative "../storage"
+
+module Net
+  module Connector
+    Backup = Data.define(:path, :bytes, :sha256, :collected_at, :change, :previous_sha256) do
+      # 保存配置备份的路径、摘要和变更状态。
+      def initialize(path:, bytes:, sha256:, collected_at:, change: nil, previous_sha256: nil)
+        super
+      end
+
+      # 判断本次采集是否产生新的配置内容。
+      def changed? = [:created, :changed].include?(change)
+    end
+
+    # 只携带库自身的提交回执和配置元数据，不携带正文或原始文件系统异常。
+    class BackupPersistenceError < Error
+      attr_reader :backup, :receipt, :underlying_type
+
+      def initialize(backup:, write_error:, host: nil)
+        unless backup.instance_of?(Backup) && Storage::PrivateFile.receipt_error?(write_error) &&
+               write_error.receipt.committed? && write_error.receipt.path == backup.path
+          raise ArgumentError, "backup persistence error requires a matching committed backup receipt"
+        end
+
+        @backup, @receipt = backup, write_error.receipt
+        @underlying_type = write_error.underlying_type
+        code = if write_error.instance_of?(Storage::PrivateFile::DirectorySyncUnsupported)
+                 :backup_durability_unsupported
+               elsif receipt.durable?
+                 :backup_finalize_failed
+               else
+                 :backup_persistence_unconfirmed
+               end
+        super(write_error.message, code: code, host: host, phase: :backup)
+      end
+    end
+
+    class LocalBackup
+      # 设备入口与功能实现共置，Base 只组合能力，不重复业务流程。
+      module Capability
+        # 采集配置并以原子方式保存为私有文件。
+        # 采集失败时保留已有备份文件。
+        def backup(path:, lock_timeout: 0)
+          @session.assert_path_lock_order!(:backup)
+          LocalBackup.new(self).call(path: path, lock_timeout: lock_timeout)
+        end
+      end
+
+      # 保存执行配置采集的设备对象。
+      def initialize(device) = @device = device
+
+      # 采集配置、识别变更并原子写入私有文件。
+      def call(path:, lock_timeout: 0)
+        host = @device.host if @device.respond_to?(:host)
+        Storage::BackupLock.synchronize(path, timeout: lock_timeout, host: host) { |lock| collect_and_write(lock.path) }
+      end
+
+      private
+
+      def collect_and_write(destination)
+        contents = @device.running_config.value!
+        digest = Digest::SHA256.hexdigest(contents)
+        previous = Storage::SafeFile.fingerprint(destination, missing: true, replace_symlink: true)
+        previous_digest = previous&.sha256
+        change = if previous_digest.nil?
+                   :created
+                 elsif previous_digest == digest
+                   :unchanged
+                 else
+                   :changed
+                 end
+
+        backup = Backup.new(path: destination, bytes: contents.bytesize,
+                            sha256: digest, collected_at: Time.now.utc, change: change,
+                            previous_sha256: previous_digest)
+        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
+        raise unless Storage::PrivateFile.receipt_error?(error) && error.receipt.committed?
+
+        host = @device.host if @device.respond_to?(:host)
+        raise BackupPersistenceError.new(backup: backup, write_error: error, host: host), cause: nil
+      end
+    end
+  end
+end

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

@@ -65,13 +65,18 @@ module Net
         @command_timeout = duration(command_timeout, :command_timeout)
         @terminal_size = validate_terminal_size(terminal_size)
         @running_config_strategy = strategy_class(running_config_strategy, :running_config_strategy,
-                                                  %i[clean result_step prompt_text check_response])
+                                                  %i[clean result_step prompt_text validate_response!])
         @tftp_strategy = strategy_class(tftp_strategy, :tftp_strategy,
-                                        %i[source_file default_path remote_path script complete?])
+                                        %i[resolve_source_file default_path remote_path script device_reported_complete? validate_options! receipt_metadata])
+        if @tftp_strategy && !@tftp_strategy.respond_to?(:filename)
+          raise ArgumentError, "tftp_strategy must expose filename"
+        end
         @topology_strategy = strategy_class(topology_strategy, :topology_strategy,
                                             %i[neighbor_command neighbor_template expected_neighbor_count empty_neighbor_output?
                                                protocol description_template interface_key configuration_interface
-                                               decode_description enter_configuration change_commands finish_commands script_command])
+                                               decode_description validate_descriptions! change_error_code supports?
+                                               enter_configuration_command change_commands script_command
+                                               leave_configuration_commands verification_commands persistence_commands persistence_confirmed?])
         if @topology_strategy && !@topology_strategy.respond_to?(:supports?)
           raise ArgumentError, "topology_strategy must expose supports?"
         end

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

@@ -21,7 +21,7 @@ module Net
         end
 
         # 公共策略不增加逐命令响应检查。
-        def check_response(_command, _response, _execution) end
+        def validate_response!(_command, _response, _execution) end
       end
 
       # 使用终端行编辑规则渲染 H3C、Huawei 和 Radware 配置。

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

@@ -7,6 +7,45 @@ require_relative "running_config/strategy"
 module Net
   module Connector
     class RunningConfig
+      # 设备只引入此能力；采集入口和策略作用域与采集流程一起维护。
+      module Capability
+        # 每次采集使用独立执行对象，设备只提供这一采集入口。
+        def running_config = RunningConfig.new(self).call
+
+        # 返回读取运行配置所需的设备命令；厂商必须声明。
+        def config_commands
+          commands = profile.config_commands
+          return commands if commands
+
+          raise NotImplementedError, "#{self.class} must define running configuration commands"
+        end
+
+        # 子类可覆盖并调用 super，复用本次响应检查积累的策略状态。
+        def clean_config(text) = config_strategy.clean(text)
+
+        protected
+
+        # 默认取最后一个完成步骤；厂商策略可选择配置所在的业务步骤。
+        def config_result_step(result) = config_strategy.result_step(result)
+
+        private
+
+        # 仅在持有会话锁的结果处理阶段绑定策略，退出时恢复原有作用域。
+        # 同一设备上其他 Fiber 的离线清理不能借用此次采集状态。
+        def with_config_strategy(strategy)
+          previous = @config_strategy_scope
+          @config_strategy_scope = [Fiber.current, strategy]
+          yield
+        ensure
+          @config_strategy_scope = previous
+        end
+
+        def config_strategy
+          scope = @config_strategy_scope
+          scope && scope.first.equal?(Fiber.current) ? scope.last : RunningConfig.strategy(self)
+        end
+      end
+
       # 保存需要读取运行配置的设备对象。
       def initialize(device)
         @device = device
@@ -20,14 +59,14 @@ module Net
       # 每次采集创建独立策略；响应校验、选择与清理共享状态，均在同一脚本锁内完成。
       def call
         script = Script.new(@device.config_commands)
-        return Result.new(error: incomplete("configuration collection has no commands")) if script.empty?
+        return Result.new(error: build_incomplete_error("configuration collection has no commands")) if script.empty?
 
         # 所有厂商的采集步骤都收紧输出边界，包括候选差异、模式切换及扩展查询。
         script = Script.new(script.map(&:with_output_sensitive))
         strategy = self.class.strategy(@device)
         prompt = ->(command) { prompt_for(command, strategy) }
         @device.execute_operation(script, name: :running_config, prompt: prompt,
-                                  after_command: strategy.method(:check_response)) do |result|
+                                  after_command: strategy.method(:validate_response!)) do |result|
           @device.send(:with_config_strategy, strategy) do
             finish(result)
           end
@@ -39,11 +78,11 @@ module Net
       # 只从完成的配置步骤提取非空内容，并保留此前所有步骤。
       def finish(result)
         step = @device.send(:config_result_step, result)
-        raise incomplete("configuration collection has no completed configuration step") unless step
+        raise build_incomplete_error("configuration collection has no completed configuration step") unless step
 
         content = @device.clean_config(step.output)
         unless content.is_a?(String) && !content.strip.empty? && content?(step)
-          raise incomplete("configuration collection returned empty content")
+          raise build_incomplete_error("configuration collection returned empty content")
         end
         Result.new(steps: result.steps, config: content)
       end
@@ -68,7 +107,7 @@ module Net
       end
 
       # 将缺少配置的情况统一映射为可识别的设备错误码。
-      def incomplete(message)
+      def build_incomplete_error(message)
         DeviceError.new(message, code: :incomplete_configuration, host: @device.host, phase: :collect)
       end
     end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    # 保存命令及能力入口，响应语义由通用执行器负责。
+    module SaveConfig
+      # 执行厂商保存配置命令；不支持时返回显式失败结果。
+      def save_config
+        if save_commands.empty?
+          return Result.new(error: @session.build_error(UnsupportedOperation, "saving configuration is not supported",
+                                                  phase: :save))
+        end
+
+        execute_script(save_commands)
+      end
+
+      # 返回保存配置命令；空数组表示设备不支持保存。
+      def save_commands = profile.save_commands
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "strategy"
+
+module Net
+  module Connector
+    class Tftp
+      # H3C 和华为共用已保存文件上传流程，源文件发现仍由厂商策略负责。
+      class FileUpload < Strategy
+        # 未指定目标名时，设备使用配置源文件的 basename。
+        def default_path(source_file) = File.basename(source_file)
+
+        # H3C 探测源文件之前先拒绝不支持的参数；探测本身不能放进纯校验钩子。
+        def validate_options!(_target, source_file:, vrf: nil)
+          raise ArgumentError, "TFTP file upload does not use vrf" unless vrf.nil?
+
+          TftpTarget.validate_source_file!(source_file) unless source_file.nil?
+        end
+
+        # 指定文件的内容与格式未知，不能仅凭 .cfg 后缀声称是当前运行配置。
+        def receipt_metadata(_target, source_file:, **)
+          { configuration_kind: :saved_file, source_file: source_file, format: :unknown }
+        end
+
+        # 仅在调用方指定目标名时追加参数，保留设备原生命名行为。
+        def script(target, source_file:, vrf: nil)
+          validate_options!(target, source_file: source_file, vrf: vrf)
+          TftpTarget.validate_source_file!(source_file)
+
+          destination = target.explicit_path? ? " #{target.path}" : ""
+          Script.new([Command.new("tftp #{target.host} put #{source_file}#{destination}", timeout: 180)])
+        end
+
+        # 只接受明确的成功消息、非零传输字节数或完整进度行。
+        def device_reported_complete?(result)
+          completion_lines(result).any? { |line| completed_upload?(line) }
+        end
+
+        private
+
+        # 两个厂商的上传完成消息使用相同的文本及进度格式。
+        def completed_upload?(line)
+          line.match?(/\A
+            (?:File\s+)?(?:transfer|upload)(?:\s+(?:is|was))?\s+
+            (?:success(?:ful(?:ly)?)?|succeeded|complete(?:d)?(?:\s+successfully)?)[.!]?
+            \z/ix) ||
+            line.match?(/\A[1-9]\d*\s+bytes?\s+sent(?:\s+in\s+[\d.]+\s+(?:secs?|seconds?))?[.!]?\z/i) ||
+            completed_progress?(line)
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/{operations/tftp_receipt.rb → device/tftp/receipt.rb}

@@ -1,43 +1,43 @@
 # frozen_string_literal: true
 
-require_relative "../engine/errors"
+require_relative "../../engine/errors"
+require_relative "target"
 
 module Net
   module Connector
-    # 元数据采用组合，不改变 TftpBackup 的位置参数、成员或解构契约。
+    # 一次设备上报上传的不可变回执；path 是实际目标，未知时保持 nil。
+    TftpReceipt = Data.define(:server, :path, :completed_at, :configuration_kind, :source_file,
+                             :format, :requested_path, :verification, :server_sha256)
+
     class TftpReceipt
       KINDS = %i[running startup saved_file native_archive unknown].freeze
       FORMATS = %i[cfg xml dat tgz unknown].freeze
       private_constant :KINDS, :FORMATS
 
-      attr_reader :transfer, :configuration_kind, :source_file, :format, :requested_path, :actual_path,
-                  :verification, :server_sha256
+      def initialize(server:, path:, completed_at:, configuration_kind: :unknown, source_file: nil,
+                     format: :unknown, requested_path: nil, verification: :device_reported, server_sha256: nil)
+        raise ArgumentError, "completed_at must be a Time" unless completed_at.is_a?(Time)
 
-      def initialize(transfer:, configuration_kind: :unknown, source_file: nil, format: :unknown,
-                     requested_path: nil, actual_path:, verification: :device_reported, server_sha256: nil)
-        unless transfer.instance_of?(TftpBackup) && transfer.completed_at.is_a?(Time) && transfer.path == actual_path
-          raise ArgumentError, "TFTP receipt requires a matching transfer"
-        end
-        TftpTarget.new(host: transfer.server, path: actual_path.nil? ? "unconfirmed" : actual_path)
+        TftpTarget.new(host: server, path: path.nil? ? "unconfirmed" : path)
         TftpTarget.validate_path!(requested_path) unless requested_path.nil?
         TftpTarget.validate_source_file!(source_file) unless source_file.nil?
         unless KINDS.include?(configuration_kind) && FORMATS.include?(format)
           raise ArgumentError, "invalid TFTP configuration kind or format"
         end
         valid_verification = (verification == :device_reported && server_sha256.nil?) ||
-          (verification == :server_verified && !actual_path.nil? && server_sha256.is_a?(String) &&
+          (verification == :server_verified && !path.nil? && server_sha256.is_a?(String) &&
             server_sha256.match?(/\A[0-9a-f]{64}\z/))
         raise ArgumentError, "invalid TFTP verification evidence" unless valid_verification
 
-        @actual_path, @requested_path = actual_path&.dup&.freeze, requested_path&.dup&.freeze
-        @source_file, @server_sha256 = source_file&.dup&.freeze, server_sha256&.dup&.freeze
-        @configuration_kind, @format, @verification = configuration_kind, format, verification
-        @transfer = transfer.with(server: transfer.server.dup.freeze, path: @actual_path,
-                                  completed_at: transfer.completed_at.dup.freeze)
-        freeze
+        super(server: server.dup.freeze, path: path&.dup&.freeze, completed_at: completed_at.dup.freeze,
+              configuration_kind: configuration_kind, source_file: source_file&.dup&.freeze, format: format,
+              requested_path: requested_path&.dup&.freeze, verification: verification,
+              server_sha256: server_sha256&.dup&.freeze)
       end
 
-      # 摘要不展开设备输出或调用方的源文件名。
+      # Ruby 3.2 的 Data#with 不调用 initialize；所有更新都重新校验并冻结字段。
+      def with(**attributes) = self.class.new(**to_h.merge(attributes))
+
       def inspect = "#<#{self.class} kind=#{configuration_kind} format=#{format} verification=#{verification}>"
     end
 
@@ -66,8 +66,6 @@ module Net
         @underlying_type = type&.match?(/\A[A-Za-z_]\w*(?:::[A-Za-z_]\w*)*\z/) && type.bytesize <= 128 ? type.freeze : nil
         super(MESSAGES.fetch(code), code: code, host: host, phase: :tftp_backup)
       end
-
-      def transfer = receipt.transfer
     end
   end
 end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../../engine/command"
+require_relative "target"
+module Net
+  module Connector
+    class Tftp
+      class Strategy
+        # 厂商只声明格式差异，清单规划与设备直连共用同一命名规则。
+        def self.file_extension = "cfg"
+
+        # 不创建会话即可生成目标名，供批量计划检查文件覆盖风险。
+        def self.filename(host, label: nil)
+          TftpTarget.filename(host, extension: file_extension, label: label)
+        end
+
+        # 保存 TFTP 厂商策略使用的设备对象。
+        def initialize(device)
+          @device = device
+          @responses = []
+        end
+
+        # 返回调用方指定的配置源文件。
+        def resolve_source_file(value) = value
+
+        # 根据设备地址生成默认远端文件名。
+        def default_path(_source_file) = self.class.filename(@device.host)
+
+        # 返回目标中指定的远端文件名。
+        def remote_path(target, _result) = target.path
+
+        private
+
+        # 记录脚本的静态响应，避免文件名或 VRF 回显成为传输完成证据。
+        def interaction(pattern, response)
+          @responses << response.chomp
+          Interaction.new(pattern, response, capture: false)
+        end
+
+        # 只从设备消息中核对完成状态；命令、交互响应和最终提示均不是传输证据。
+        def completion_lines(result)
+          step = result.steps.last
+          return [] unless step
+
+          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) }
+        end
+
+        # 只接受字节数非零、已发送量与总量相同的 curl 完成进度行。
+        def completed_progress?(line)
+          line.match?(/\A100\s+([1-9]\d*(?:\.\d+)?[kMGT]?)\s+0\s+0\s+100\s+\1(?:\s+[\d.:kMGT-]+)*\z/i)
+        end
+
+        # Cisco 明确报告复制完成的字节数，可附带耗时和速率。
+        def copied_bytes?(line)
+          line.match?(/\A
+            [1-9]\d*\s+bytes?\s+copied
+            (?:\s+in\s+[\d.]+\s+(?:secs?|seconds?)(?:\s+\([\d.]+\s+bytes\/sec\))?)?[.!]?
+            \z/ix)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Net
+  module Connector
+    # 设备主动上传使用的 TFTP 目标，服务器必须能被设备访问。
+    class TftpTarget
+      MAX_PATH_BYTES = 220
+
+      attr_reader :host, :path
+
+      # 校验并保存 TFTP 服务器、远端路径及显式文件名标记。
+      def initialize(host:, path:, explicit_path: true)
+        unless host.is_a?(String) && host.bytesize <= 253 &&
+               host.match?(/\A[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?\z/) && !host.include?("..")
+          raise ArgumentError, "TFTP host must be an IPv4 address or DNS name"
+        end
+        self.class.validate_path!(path)
+        @host, @path = host.dup.freeze, path.dup.freeze
+        @explicit_path = explicit_path
+        freeze
+      end
+
+      # 判断调用方是否明确指定了远端文件名。
+      def explicit_path? = @explicit_path
+
+      # 校验设备或调用方给出的远端相对路径。
+      def self.validate_path!(path)
+        unless path.is_a?(String) && path.bytesize <= MAX_PATH_BYTES &&
+               path.match?(/\A[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\z/) &&
+               path.split("/").none? { |part| %w[. ..].include?(part) }
+          raise ArgumentError, "TFTP path must be a relative filename or path without traversal"
+        end
+        path
+      end
+
+      # 设备地址和可选清单名称共用目标长度限制；极长地址用稳定摘要表示。
+      def self.filename(host, extension:, label: nil)
+        if label && (!label.is_a?(String) || !label.ascii_only?)
+          raise ArgumentError, "TFTP label must be an ASCII String"
+        end
+
+        address = host.gsub(/[^A-Za-z0-9._-]/, "_")
+        suffix = "#{address}.#{extension}"
+        if suffix.bytesize > MAX_PATH_BYTES - (label ? 2 : 0)
+          suffix = "#{Digest::SHA256.hexdigest(host)}.#{extension}"
+        end
+        path = label ? "#{label.byteslice(0, MAX_PATH_BYTES - suffix.bytesize - 1)}-#{suffix}" : suffix
+        validate_path!(path)
+      end
+
+      # 校验设备源文件路径是否符合命令安全约束。
+      def self.validate_source_file!(value)
+        unless value.is_a?(String) && value.match?(/\A[A-Za-z0-9._:\/-]+\z/) &&
+               !value.split("/").include?("..")
+          raise ArgumentError, "source_file must be a device file path without spaces or traversal"
+        end
+        value
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "tftp/strategy"
+require_relative "tftp/receipt"
+
+module Net
+  module Connector
+    class Tftp
+      # 设备入口与功能实现共置，Base 只组合能力，不重复业务流程。
+      module Capability
+        # 要求设备直接向 TFTP 服务器导出原生配置。
+        # 完成仅表示设备报告传输成功，未读取服务器端文件。
+        def tftp_backup(host:, path: nil, source_file: nil, vrf: nil)
+          Tftp.new(self).call(host: host, path: path, source_file: source_file, vrf: vrf)
+        end
+      end
+
+      # 保存执行 TFTP 导出的设备对象。
+      def initialize(device) = @device = device
+
+      # 参数先纯校验；源探测、上传、证据核对及收尾共用一次会话租约。
+      def call(host:, path: nil, source_file: nil, vrf: nil)
+        receipt = nil
+        strategy_class = @device.profile.tftp_strategy
+        unless strategy_class
+          raise UnsupportedOperation.new("native TFTP backup is not supported for this vendor",
+                                         host: @device.host, phase: :tftp_backup)
+        end
+        strategy = strategy_class.new(@device)
+        if !vrf.nil? && (!vrf.is_a?(String) || !vrf.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/))
+          raise ArgumentError, "vrf must be a single safe name"
+        end
+        source_file = TftpTarget.validate_source_file!(source_file).dup.freeze unless source_file.nil?
+        vrf = vrf&.dup&.freeze
+        target = TftpTarget.new(host: host, path: path.nil? ? "preflight.cfg" : path, explicit_path: !path.nil?)
+        strategy.validate_options!(target, source_file: source_file, vrf: vrf)
+        @device.with_operation(:tftp_backup) do
+          source = strategy.resolve_source_file(source_file)
+          source = TftpTarget.validate_source_file!(source).dup.freeze unless source.nil?
+          target = TftpTarget.new(host: target.host, path: strategy.default_path(source), explicit_path: false) if path.nil?
+          result = @device.execute_operation(strategy.script(target, source_file: source, vrf: vrf),
+                                             name: :tftp_backup, privilege: false)
+          confirm_transfer!(strategy, target, result)
+          # 一旦看到明确完成证据就保存回执；路径解析或用户钩子失败也不能抹去上传事实。
+          requested_path = target.explicit_path? ? target.path : nil
+          receipt = TftpReceipt.new(server: target.host, path: nil, completed_at: Time.now.utc,
+                                    requested_path: requested_path, source_file: source)
+          actual_path = remote_path(strategy, target, result, receipt)
+          receipt = receipt.with(path: actual_path)
+          receipt = build_receipt(strategy, target, source, !source_file.nil?, receipt)
+          if target.explicit_path? && target.path != receipt.path
+            raise TftpCompletionError.new(receipt: receipt, code: :transfer_path_mismatch, host: @device.host), cause: nil
+          end
+          # 已完成步骤仍可能伴随后处理/清理错误；上面的回执要先构造，再重新抛出。
+          result.value! if result.failure?
+          @device.log_event("tftp_backup", status: "reported_uploaded", phase: :tftp_backup,
+                                server: target.host, path: receipt.path)
+          receipt
+        end
+      rescue StandardError => error
+        raise unless receipt
+        raise if error.instance_of?(TftpCompletionError) && error.receipt.equal?(receipt)
+
+        raise TftpCompletionError.new(receipt: receipt, host: @device.host, underlying: error), cause: nil
+      end
+
+      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?
+          raise ArgumentError, "invalid TFTP strategy receipt metadata"
+        end
+        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
+        raise TftpCompletionError.new(receipt: receipt, code: :transfer_path_unconfirmed,
+                                       host: @device.host, underlying: error), cause: nil
+      end
+
+      # 失败证据优先；步骤中的明确完成行可在随后清理失败时证明设备已经报告上传。
+      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)
+        end
+        unless 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)
+        end
+      end
+
+      # 识别设备回显中的传输失败信息。
+      def transfer_failed?(result)
+        result.steps.any? do |step|
+          # 文件名中的 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)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "strategy"
+require_relative "../../engine/terminal_renderer"
+
+module Net
+  module Connector
+    class Topology
+      # 接口描述立即生效的设备：退出视图、读回、保存是不同阶段，不能在 finish 中提前保存。
+      class ImmediateStrategy < Strategy
+        def verification_commands = @device.config_commands
+        def persistence_commands = @device.profile.save_commands
+
+        # TextFSM 不能静默跳过未知接口头；否则目标行正确也不足以证明读回证据完整。
+        def validate_descriptions!(config, rows)
+          expected = config.scan(/^interface[ \t]+([^\r\n]*)/).flatten.map(&:strip)
+          return if expected == rows.map { |row| row.fetch("INTERFACE").strip }
+
+          raise ParsingError.new("interface description output was not fully recognized", code: :unrecognized_output,
+                                 host: @device.host, phase: :verify)
+        end
+
+        # 完成提示必须来自保存步骤；原文和渲染文本中的失败优先，单独提示符/进度不算确认。
+        def persistence_confirmed?(result)
+          !result.steps.empty? && result.steps.all? do |step|
+            raw = step.output.delete_suffix(step.prompt.to_s)
+            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)
+
+            rendered.lines.any? { |line| line.strip.match?(persistence_pattern) }
+          end
+        end
+
+        # 没有明确完成证据的策略不能借用一个泛化的成功关键词。
+        def persistence_pattern = /\A\b\B\z/
+      end
+    end
+  end
+end