net-connector 0.4.0 → 0.4.2

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "strategy"
+
+module Net
+  module Connector
+    module Operations
+      module 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 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
+end

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

@@ -13,6 +13,14 @@ module Net
         autoload :PaloAlto, File.expand_path("palo_alto", __dir__)
 
         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
@@ -23,7 +31,7 @@ module Net
           def source_file(value) = value
 
           # 根据设备地址生成默认远端文件名。
-          def default_path(_source_file) = TftpTarget.filename(@device.host, extension: "cfg")
+          def default_path(_source_file) = self.class.filename(@device.host)
 
           # 返回目标中指定的远端文件名。
           def remote_path(target, _result) = target.path
@@ -53,16 +61,6 @@ module Net
             line.match?(/\A100\s+([1-9]\d*(?:\.\d+)?[kMGT]?)\s+0\s+0\s+100\s+\1(?:\s+[\d.:kMGT-]+)*\z/i)
           end
 
-          # H3C 和华为的上传完成消息使用相同的文本及进度格式。
-          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
-
           # Cisco 明确报告复制完成的字节数，可附带耗时和速率。
           def copied_bytes?(line)
             line.match?(/\A

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

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "strategy"
+require_relative "../../engine/terminal_renderer"
+
+module Net
+  module Connector
+    module Operations
+      class Topology
+        # 接口描述立即生效的设备：退出视图、读回、保存是不同阶段，不能在 finish 中提前保存。
+        class ImmediateStrategy < Strategy
+          def verification_commands = @device.config_commands
+          def persistence_commands = @device.profile.save_commands
+
+          # 保留旧扩展查询入口；公共执行流程使用独立阶段，不再执行这份合并列表。
+          def finish_commands = leave_configuration + persistence_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
+end

data/lib/net/connector/operations/topology/strategy.rb

@@ -15,24 +15,58 @@ module Net
 
         # 厂商拓扑规则；默认不提供任何设备能力。
         class Strategy
+          # 保存设备供厂商规则查询档案和会话状态。
           def initialize(device)
             @device = device
           end
 
+          # 声明策略类支持的拓扑能力，默认全部关闭。
           def self.supports?(_capability) = false
+
+          # 将实例级能力查询交给策略类声明。
           def supports?(capability) = self.class.supports?(capability)
 
+          # 返回读取邻居的命令，未定义时不支持发现。
           def neighbor_command = nil
+
+          # 根据原始输出选择邻居解析模板。
           def neighbor_template(_output) = nil
+
+          # 返回当前接口描述所用的解析模板。
           def description_template = nil
+
+          # 返回输出中应解析出的邻居数量，供完整性校验使用。
           def expected_neighbor_count(_output, _template) = 0
+
+          # 只有明确的空表证据才允许返回空邻居列表。
           def empty_neighbor_output?(_output) = false
+
+          # 返回进入设备配置视图的命令。
           def enter_configuration = nil
+
+          # 返回离开配置视图和保存配置所需的命令。
           def finish_commands = []
+
+          # 未声明分阶段契约的旧策略仍可读取，但不能推断其退出、验证和保存的安全边界。
+          def leave_configuration = nil
+          def verification_commands = nil
+          def persistence_commands = nil
+          def persistence_confirmed?(_result) = false
+          def change_error_code = :description_unsupported
+
+          # 只读策略可以没有完整性扩展；立即生效的接口块模型会进一步校验解析数量。
+          def validate_descriptions!(_config, _rows) end
+
+          # 为一条接口描述变更生成厂商命令。
           def change_commands(_change) = []
+
+          # 标明邻居发现使用的协议。
           def protocol = :lldp
+
+          # 在下发前允许厂商调整命令对象及超时。
           def script_command(command) = command
 
+          # 将发现接口名归一为查找当前配置所用的键。
           def interface_key(name) = InterfaceName.key(name)
 
           # 将发现协议常用的接口简称展开为配置视图可识别的名称。