net-connector 0.4.1 → 0.4.2

data/lib/net/connector/operations/parse_output.rb

@@ -21,11 +21,19 @@ module Net
           @index = index
         end
 
-        # 显式模板按路径读取；未指定时按厂商和命令从索引选择模板。
-        def call(text, template: nil, vendor: nil, command: nil, host: nil)
+        # 解析按 UTF-8 字节处理副本，先验证原文，避免回车或转义序列隐藏非法字节。
+        # 拓扑选模板和计数也使用这份副本，但仍保留未经终端渲染的完整证据。
+        def utf8(text, host: nil)
           raise ArgumentError, "text must be a String" unless text.is_a?(String)
 
-          text = TerminalRenderer.render(text).force_encoding(Encoding::UTF_8)
+          text = text.b.force_encoding(Encoding::UTF_8)
+          invalid_encoding!(host) unless text.valid_encoding?
+          text
+        end
+
+        # 显式模板按路径读取；未指定时按厂商和命令从索引选择模板。
+        def call(text, template: nil, vendor: nil, command: nil, host: nil)
+          text = TerminalRenderer.render(utf8(text, host: host), strict_utf8: true).force_encoding(Encoding::UTF_8)
           if template
             raise ArgumentError, "template must be a nonempty String" unless template.is_a?(String) && !template.empty?
 
@@ -41,6 +49,8 @@ module Net
             end
             table.parse(text, attributes: attributes).to_hashes
           end
+        rescue Encoding::InvalidByteSequenceError
+          invalid_encoding!(host)
         rescue TextFSM::IndexError
           raise ParsingError.new("TextFSM template index is invalid",
                                  code: :template_invalid, host: host, phase: :parse), cause: nil
@@ -54,6 +64,13 @@ module Net
           raise ParsingError.new("unable to read TextFSM template",
                                  code: :template_unreadable, host: host, phase: :parse), cause: nil
         end
+
+        private
+
+        def invalid_encoding!(host)
+          raise ParsingError.new("device output is not valid UTF-8", code: :invalid_output_encoding,
+                                 host: host, phase: :parse), cause: nil
+        end
       end
     end
   end

data/lib/net/connector/operations/private_file.rb

@@ -5,19 +5,108 @@ require "tempfile"
 module Net
   module Connector
     module Operations
-      # 将配置写入同目录的私有临时文件，再原子替换目标文件。
+      # 文件同步和目录项同步分别记录；原子可见不等于断电后仍能恢复新目录项。
       module PrivateFile
-        # 写入完整内容并同步到磁盘，避免覆盖失败留下半份配置。
+        Receipt = Data.define(:path, :state, :phase) do
+          def initialize(path:, state:, phase:)
+            unless path.is_a?(String) && !path.empty? && %i[not_committed committed durable].include?(state) &&
+                   %i[resolve_parent temporary_file write file_sync rename directory_open directory_sync cleanup complete].include?(phase)
+              raise ArgumentError, "invalid file write receipt"
+            end
+            super(path: path.dup.freeze, state: state, phase: phase)
+          end
+
+          def committed? = state != :not_committed
+          def durable? = state == :durable
+        end
+
+        class WriteError < IOError
+          attr_reader :receipt, :code, :underlying_type
+
+          def initialize(receipt:, underlying_type:)
+            raise ArgumentError, "receipt must be a file write receipt" unless receipt.instance_of?(Receipt)
+
+            @receipt = receipt
+            @underlying_type = underlying_type.dup.freeze
+            @code, message = if receipt.durable?
+                               [:file_finalize_failed, "file replacement is durable; finalization failed"]
+                             elsif receipt.committed?
+                               [:file_persistence_unconfirmed, "file replacement is committed; durability is unconfirmed"]
+                             else
+                               [:file_write_failed, "file write failed before replacement was committed"]
+                             end
+            super(message)
+          end
+
+          def inspect = "#<#{self.class} state=#{receipt.state} phase=#{receipt.phase}>"
+        end
+
+        class PersistenceError < WriteError; end
+
+        class DirectorySyncUnsupported < WriteError
+          def initialize(**options)
+            super
+            @code = :directory_sync_unsupported
+          end
+
+          def message = "file replacement is committed; directory synchronization is unsupported"
+          alias to_s message
+        end
+
+        UNSUPPORTED_DIRECTORY_SYNC = [Errno::EINVAL, Errno::ENOSYS, Errno::ENOTSUP, Errno::EOPNOTSUPP,
+                                      NotImplementedError].uniq.freeze
+        private_constant :UNSUPPORTED_DIRECTORY_SYNC
+
+        # 外部子类可重写消息或回执；只有本写入器定义的具体错误类型可提供完成事实。
+        def self.receipt_error?(error)
+          [WriteError, PersistenceError, DirectorySyncUnsupported].any? { |type| error.instance_of?(type) }
+        end
+
+        # 保留原路径返回值；失败时可从异常 receipt 判断目录项是否已经替换。
         def self.write(path, contents)
-          Tempfile.create([".net-connector-", ".tmp"], File.dirname(path)) do |file|
+          write_receipt(path, contents)
+          path
+        end
+
+        def self.write_receipt(path, contents)
+          raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?
+
+          receipt = Receipt.new(path: File.expand_path(path), state: :not_committed, phase: :resolve_parent)
+          directory = File.realpath(File.dirname(receipt.path))
+          destination = File.join(directory, File.basename(receipt.path))
+          receipt = receipt.with(phase: :temporary_file)
+          Tempfile.create([".net-connector-", ".tmp"], directory) do |file|
             file.binmode
             file.chmod(0o600)
+            receipt = receipt.with(phase: :write)
             file.write(contents)
+            receipt = receipt.with(phase: :file_sync)
             file.flush
             file.fsync
-            File.rename(file.path, path)
+            receipt = receipt.with(phase: :rename)
+            File.rename(file.path, destination)
+            receipt = receipt.with(state: :committed, phase: :directory_open)
+            File.open(directory, File::RDONLY | File::NOFOLLOW) do |parent|
+              raise IOError, "parent is not a directory" unless parent.stat.directory?
+
+              receipt = receipt.with(phase: :directory_sync)
+              parent.fsync
+              receipt = receipt.with(state: :durable, phase: :cleanup)
+            end
           end
-          path
+          receipt.with(phase: :complete)
+        rescue StandardError, NotImplementedError => error
+          raise unless receipt
+
+          unsupported = receipt.phase == :directory_sync && UNSUPPORTED_DIRECTORY_SYNC.any? { |type| error.is_a?(type) }
+          klass = if unsupported
+                    DirectorySyncUnsupported
+                  elsif receipt.committed?
+                    PersistenceError
+                  else
+                    WriteError
+                  end
+          raise klass.new(receipt: receipt, underlying_type: error.class.name.to_s), cause: nil
         end
       end
     end

data/lib/net/connector/operations/safe_file.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Net
+  module Connector
+    module Operations
+      # 对同一 FD 做类型检查和读取；NOFOLLOW 只保护最后一个路径分量，目录由调用方保护。
+      module SafeFile
+        Fingerprint = Data.define(:path, :sha256, :mode, :dev, :ino)
+
+        def self.open(path, missing: false, replace_symlink: false)
+          file = open_handle(path, missing: missing, replace_symlink: replace_symlink)
+          return nil unless file
+
+          begin
+            stat = file.stat
+            raise ArgumentError, "saved configuration is not a regular file" unless stat.file?
+
+            file.binmode
+            yield file, stat
+          ensure
+            file.close
+          end
+        end
+
+        def self.fingerprint(path, **options)
+          self.open(path, **options) { |file, stat| fingerprint_io(path, file, stat) }
+        end
+
+        def self.fingerprint_io(path, file, stat)
+          digest = Digest::SHA256.new
+          while (chunk = file.read(64 * 1024))
+            digest << chunk
+          end
+          Fingerprint.new(path: path.dup.freeze, sha256: digest.hexdigest.freeze,
+                          mode: stat.mode & 0o7777, dev: stat.dev, ino: stat.ino)
+        end
+
+        # 未变内容可保留 mtime，但不能把已替换的目录项误认成刚读取的旧文件。
+        def self.same_entry?(path, fingerprint)
+          stat = File.lstat(path)
+          stat.file? && stat.dev == fingerprint.dev && stat.ino == fingerprint.ino
+        rescue Errno::ENOENT
+          false
+        end
+
+        def self.open_handle(path, missing:, replace_symlink:)
+          File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+        rescue Errno::ENOENT
+          raise unless missing
+        rescue Errno::ELOOP
+          raise ArgumentError, "saved configuration is not a regular file", cause: nil unless replace_symlink
+        rescue Errno::ENXIO
+          raise ArgumentError, "saved configuration is not a regular file", cause: nil
+        end
+
+        private_class_method :open_handle
+      end
+    end
+  end
+end

data/lib/net/connector/operations/saved_config/legacy_index.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "../../engine/errors"
+require_relative "../safe_file"
+
+module Net
+  module Connector
+    class SavedConfigChanged < Error; end
+
+    module Operations
+      class SavedConfig
+        # 每批只发布一份只读目录快照。记录文件身份而不读取正文；不跨批次缓存。
+        class LegacyIndex
+          Entry = Data.define(:name, :identity, :regular)
+          EMPTY = [].freeze
+
+          def initialize(directory)
+            @directory = directory
+            @mutex = Mutex.new
+            @entries = nil
+            @failed = false
+          end
+
+          def candidates(filename)
+            @mutex.synchronize do
+              raise IOError, "unable to index saved configurations", cause: nil if @failed
+
+              @entries ||= snapshot
+              @entries.fetch(filename, EMPTY)
+            rescue IOError, SystemCallError
+              @failed = true
+              raise IOError, "unable to index saved configurations", cause: nil
+            end
+          end
+
+          # 目录快照不是锁：同一 FD 读取前后及最终目录项都必须仍匹配快照。
+          # 非合作写入者仍可在检查之后修改文件，调用方必须保护整个备份目录。
+          def open(entry)
+            path = File.join(@directory, entry.name)
+            verify!(entry, File.lstat(path))
+            SafeFile.open(path) do |file, stat|
+              verify!(entry, stat)
+              value = yield path, file, stat
+              verify!(entry, file.stat)
+              verify!(entry, File.lstat(path))
+              value
+            end
+          rescue IOError, SystemCallError
+            changed!
+          rescue ArgumentError
+            raise unless entry.regular
+
+            changed!
+          end
+
+          private
+
+          def snapshot
+            entries = {}
+            Dir.children(@directory).each do |name|
+              filename = canonical_suffix(name)
+              next unless filename
+
+              (entries[filename] ||= []) << snapshot_entry(name)
+            end
+            entries.each_value(&:freeze)
+            entries.freeze
+          end
+
+          # 下划线仅还原地址部分，IPv6 zone 中的下划线保持原义；合法性仍由 IPAddr 判断。
+          def canonical_suffix(name)
+            suffix = name.b[/-([0-9a-f_.]+(?:%[a-z0-9_.-]+)?)\.txt\z/in, 1]
+            return unless suffix
+
+            address, zone = suffix.split("%", 2)
+            host = address.tr("_", ":")
+            host += "%#{zone}" if zone
+            SavedConfig.filename(host).freeze
+          rescue ArgumentError
+            nil
+          end
+
+          def snapshot_entry(name)
+            stat = File.lstat(File.join(@directory, name))
+            Entry.new(name: name.freeze, identity: identity(stat), regular: stat.file?)
+          rescue SystemCallError
+            # 列表与 lstat 之间消失的候选仍占据该身份，不能把后来出现的文件当作旧快照。
+            Entry.new(name: name.freeze, identity: nil, regular: false)
+          end
+
+          def identity(stat)
+            [stat.dev, stat.ino, stat.mode, stat.size, stat.mtime.to_r, stat.ctime.to_r].freeze
+          end
+
+          def verify!(entry, stat)
+            changed! unless entry.identity == identity(stat)
+          end
+
+          def changed!
+            raise SavedConfigChanged.new("legacy saved configuration changed or became unavailable after indexing",
+                                         code: :saved_config_changed, phase: :backup), cause: nil
+          end
+        end
+
+        private_constant :LegacyIndex
+      end
+    end
+  end
+end

data/lib/net/connector/operations/saved_config.rb

@@ -3,7 +3,8 @@
 require "fileutils"
 require "ipaddr"
 require_relative "private_file"
-require_relative "parse_output"
+require_relative "safe_file"
+require_relative "saved_config/legacy_index"
 
 module Net
   module Connector
@@ -19,34 +20,61 @@ module Net
           raise ArgumentError, "host must be an IP address"
         end
 
-        # 保存已有配置文件所在目录。
-        def initialize(directory:)
+        # 默认每次实时查找；批次显式 indexed 时共享一份惰性的旧命名文件快照。
+        def initialize(directory:, indexed: false)
           raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty?
+          raise ArgumentError, "indexed must be true or false" unless [true, false].include?(indexed)
 
-          @directory = File.expand_path(directory)
+          @directory = File.expand_path(directory).freeze
+          @legacy_index = LegacyIndex.new(@directory) if indexed
         end
 
         # 优先查找固定文件名；仅在不存在时兼容唯一的旧命名文件。
         def find(host, required: true)
+          with_file(host, required: required) { |path, _file, _stat| path }
+        end
+
+        # 比较基线也从经过 fstat 的同一 FD 读取，不在 find 后重新按路径打开。
+        def fingerprint(host, required: true)
+          with_file(host, required: required) { |path, file, stat| SafeFile.fingerprint_io(path, file, stat) }
+        end
+
+        def read(host)
+          with_file(host) { |_path, file, _stat| file.read }
+        end
+
+        def resolve_path(host, required:)
           filename = self.class.filename(host)
           path = File.join(@directory, filename)
           unless File.exist?(path) || File.symlink?(path)
-            entries = Dir.children(@directory).select { |name| name.end_with?("-#{filename}") }
+            entries = if @legacy_index
+                        @legacy_index.candidates(filename)
+                      else
+                        Dir.children(@directory).select { |name| name.end_with?("-#{filename}") }
+                      end
             return nil if entries.empty? && !required
 
             raise ArgumentError, "no saved configuration for #{host}" if entries.empty?
             raise ArgumentError, "multiple saved configurations for #{host}" if entries.size > 1
 
-            path = File.join(@directory, entries.first)
+            path = @legacy_index ? entries.first : File.join(@directory, entries.first)
           end
-          raise ArgumentError, "saved configuration is not a regular file" unless File.file?(path) && !File.symlink?(path)
-
           path
         end
 
+        def with_file(host, required: true)
+          path = resolve_path(host, required: required)
+          return nil unless path
+          return @legacy_index.open(path) { |name, file, stat| yield name, file, stat } if path.is_a?(LegacyIndex::Entry)
+
+          SafeFile.open(path) { |file, stat| yield path, file, stat }
+        end
+
+        private :resolve_path, :with_file
+
         # 将已保存配置写入目标文件或标准输出。
         def export(host:, output: nil, io: $stdout)
-          contents = File.binread(find(host))
+          contents = read(host)
           if output
             raise ArgumentError, "output must be a nonempty String" unless output.is_a?(String) && !output.empty?
 
@@ -63,8 +91,10 @@ module Net
 
         # 使用指定模板解析已有配置，无需访问设备或 Netdisco。
         def parse(host:, template:, template_dir: nil)
+          require_relative "parse_output"
+
           parser = ParseOutput.new(template_dir: template_dir)
-          parser.call(File.binread(find(host)), template: template, host: host)
+          parser.call(read(host), template: template, host: host)
         end
       end
     end

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

@@ -11,9 +11,22 @@ module Net
           # 未指定目标名时，设备使用配置源文件的 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)
-            raise ArgumentError, "TFTP file upload does not use vrf" if vrf
+            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)])

data/lib/net/connector/operations/tftp_backup.rb

@@ -2,6 +2,7 @@
 
 require "digest"
 require_relative "tftp/strategy"
+require_relative "tftp_receipt"
 
 module Net
   module Connector
@@ -38,6 +39,10 @@ module Net
 
       # 设备地址和可选清单名称共用目标长度限制；极长地址用稳定摘要表示。
       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)
@@ -64,42 +69,100 @@ module Net
         # 保存执行 TFTP 导出的设备对象。
         def initialize(device) = @device = device
 
-        # 执行设备原生 TFTP 导出并核对完成回显。
+        # 保留原有返回结构；扩展元数据由 call_receipt 单独提供。
         def call(host:, path: nil, source_file: nil, vrf: nil)
+          call_receipt(host: host, path: path, source_file: source_file, vrf: vrf).transfer
+        end
+
+        # 参数先纯校验；源探测、上传、证据核对及收尾共用一次会话租约。
+        def call_receipt(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 && (!vrf.is_a?(String) || !vrf.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/))
+          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
-          # H3C 在解析源文件时可能连接设备，因此先验证调用方提供的目标。
-          target = TftpTarget.new(host: host, path: path || "preflight.cfg", explicit_path: !path.nil?)
-          source_file = strategy.source_file(source_file)
-          target = TftpTarget.new(host: host, path: strategy.default_path(source_file), explicit_path: false) unless path
-          result = @device.execute_operation(strategy.script(target, source_file: source_file, vrf: vrf),
-                                             name: :tftp_backup, privilege: false)
-          result.value!
+          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?)
+          if strategy_hook?(strategy, :validate_options!)
+            strategy.validate_options!(target, source_file: source_file, vrf: vrf)
+          end
+          @device.with_operation(:tftp_backup) do
+            source = strategy.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)
+            # 一旦看到明确完成证据就保存回执；路径解析或用户钩子失败也不能抹去上传事实。
+            transfer = Net::Connector::TftpBackup.new(server: target.host, path: nil, completed_at: Time.now.utc)
+            requested_path = target.explicit_path? ? target.path : nil
+            receipt = TftpReceipt.new(transfer: transfer, actual_path: nil, requested_path: requested_path, source_file: source)
+            actual_path = remote_path(strategy, target, result, receipt)
+            receipt = TftpReceipt.new(transfer: transfer.with(path: actual_path), actual_path: actual_path,
+                                      requested_path: requested_path, source_file: source)
+            receipt = receipt_metadata(strategy, target, source, !source_file.nil?, receipt)
+            if target.explicit_path? && target.path != receipt.actual_path
+              raise TftpCompletionError.new(receipt: receipt, code: :transfer_path_mismatch, host: @device.host), cause: nil
+            end
+            # 已完成步骤仍可能伴随后处理/清理错误；上面的回执要先构造，再重新抛出。
+            result.value! if result.failure?
+            @device.record_event("tftp_backup", status: "reported_uploaded", server: target.host, path: receipt.actual_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
+
+        # 旧扩展若重写 script，不继承父厂商新增的参数限制或配置来源声明。
+        # 同时重写相应钩子才表示扩展已为自己的脚本实现这项契约。
+        def strategy_hook?(strategy, name)
+          strategy.respond_to?(name) && !!(strategy.method(name).owner <= strategy.method(:script).owner)
+        end
+
+        def receipt_metadata(strategy, target, source_file, explicit_source, receipt)
+          return receipt unless strategy_hook?(strategy, :receipt_metadata)
+
+          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
+          TftpReceipt.new(transfer: receipt.transfer, actual_path: receipt.actual_path,
+                          **{ 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.record_event("tftp_backup", level: :error, status: "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.complete?(result)
+            result.value! if result.failure?
             @device.record_event("tftp_backup", level: :error, status: "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
-
-          remote_path = strategy.remote_path(target, result)
-          @device.record_event("tftp_backup", status: "reported_uploaded", server: target.host, path: remote_path)
-          Net::Connector::TftpBackup.new(server: target.host, path: remote_path, completed_at: Time.now.utc)
         end
 
-        private
-
         # 识别设备回显中的传输失败信息。
         def transfer_failed?(result)
           result.steps.any? do |step|

data/lib/net/connector/operations/tftp_receipt.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "../engine/errors"
+
+module Net
+  module Connector
+    # 元数据采用组合，不改变 TftpBackup 的位置参数、成员或解构契约。
+    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(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.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) &&
+            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
+      end
+
+      # 摘要不展开设备输出或调用方的源文件名。
+      def inspect = "#<#{self.class} kind=#{configuration_kind} format=#{format} verification=#{verification}>"
+    end
+
+    # 上传已确认后的失败不能被解释为“尚未上传”，也不能携带原始诊断正文。
+    class TftpCompletionError < Error
+      MESSAGES = {
+        transfer_finalize_failed: "device reported TFTP completion but finalization failed",
+        transfer_path_unconfirmed: "device reported TFTP completion but its remote path is unconfirmed",
+        transfer_path_mismatch: "device reported TFTP completion at a different remote path"
+      }.freeze
+      private_constant :MESSAGES
+
+      attr_reader :receipt, :underlying_type
+
+      def initialize(receipt:, code: :transfer_finalize_failed, host: nil, underlying: nil)
+        unless receipt.instance_of?(TftpReceipt) && MESSAGES.key?(code)
+          raise ArgumentError, "TFTP completion error requires a transfer receipt and a known failure code"
+        end
+
+        @receipt = receipt
+        type = if underlying.is_a?(Error) && underlying.underlying.instance_of?(UnderlyingError)
+                 underlying.underlying.type
+               else
+                 underlying&.class&.name
+               end
+        @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