net-connector 0.4.2 → 0.6.0

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

@@ -1,109 +0,0 @@
-# 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/tftp/cisco_ios.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/cisco_ios/tftp_backup"
-
-module Net
-  module Connector
-    module Operations
-      Tftp::CiscoIos = Net::Connector::CiscoIos::TftpBackup
-    end
-  end
-end

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/cisco_nxos/tftp_backup"
-
-module Net
-  module Connector
-    module Operations
-      Tftp::CiscoNxos = Net::Connector::CiscoNxos::TftpBackup
-    end
-  end
-end

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

@@ -1,55 +0,0 @@
-# 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/h3c.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/h3c/tftp_backup"
-
-module Net
-  module Connector
-    module Operations
-      Tftp::H3c = Net::Connector::H3c::TftpBackup
-    end
-  end
-end

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/hillstone/tftp_backup"
-
-module Net
-  module Connector
-    module Operations
-      Tftp::Hillstone = Net::Connector::Hillstone::TftpBackup
-    end
-  end
-end

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/huawei/tftp_backup"
-
-module Net
-  module Connector
-    module Operations
-      Tftp::Huawei = Net::Connector::Huawei::TftpBackup
-    end
-  end
-end

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/palo_alto/tftp_backup"
-
-module Net
-  module Connector
-    module Operations
-      Tftp::PaloAlto = Net::Connector::PaloAlto::TftpBackup
-    end
-  end
-end

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/radware/tftp_backup"
-
-module Net
-  module Connector
-    module Operations
-      Tftp::Radware = Net::Connector::Radware::TftpBackup
-    end
-  end
-end

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

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module Net
-  module Connector
-    module Operations
-      module Tftp
-        autoload :H3c, File.expand_path("h3c", __dir__)
-        autoload :CiscoIos, File.expand_path("cisco_ios", __dir__)
-        autoload :CiscoNxos, File.expand_path("cisco_nxos", __dir__)
-        autoload :Huawei, File.expand_path("huawei", __dir__)
-        autoload :Hillstone, File.expand_path("hillstone", __dir__)
-        autoload :Radware, File.expand_path("radware", __dir__)
-        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
-            @responses = []
-          end
-
-          # 返回调用方指定的配置源文件。
-          def 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
-end

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

@@ -1,183 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-require_relative "tftp/strategy"
-require_relative "tftp_receipt"
-
-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
-
-    TftpBackup = Data.define(:server, :path, :completed_at)
-
-    module Operations
-      class TftpBackup
-        # 保存执行 TFTP 导出的设备对象。
-        def initialize(device) = @device = device
-
-        # 保留原有返回结构；扩展元数据由 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.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?)
-          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
-        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
-end

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/cisco_ios/topology"
-
-module Net
-  module Connector
-    module Operations
-      Topology::Cisco = Net::Connector::CiscoIos::Topology
-    end
-  end
-end

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/h3c/topology"
-
-module Net
-  module Connector
-    module Operations
-      Topology::H3c = Net::Connector::H3c::Topology
-    end
-  end
-end

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/hillstone/topology"
-
-module Net
-  module Connector
-    module Operations
-      Topology::Hillstone = Net::Connector::Hillstone::Topology
-    end
-  end
-end

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

@@ -1,45 +0,0 @@
-# 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/palo_alto.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/palo_alto/topology"
-
-module Net
-  module Connector
-    module Operations
-      Topology::PaloAlto = Net::Connector::PaloAlto::Topology
-    end
-  end
-end

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../vendor/radware/topology"
-
-module Net
-  module Connector
-    module Operations
-      Topology::Radware = Net::Connector::Radware::Topology
-    end
-  end
-end