net-connector 0.4.0

data/lib/net/connector/netdisco/fleet.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "digest"
+
+module Net
+  module Connector
+    module Netdisco
+      # 基于已验证的清单快照组织有上限的并发备份。
+      class Fleet
+        # 组装清单客户端、规则、凭据与结果存储。
+        def initialize(client: nil, settings: Settings.new, rules: nil, credentials: nil, connector_factory: nil,
+                       result_store: ResultStore::Text.new)
+          @settings = settings
+          @client = client || settings.client
+          @rules = rules || settings.rules
+          @credentials = credentials || settings.method(:credentials_for)
+          @connector_factory = connector_factory || ->(device, connection_settings) { device.connector(**connection_settings) }
+          @result_store = result_store
+          raise ArgumentError, "credentials must respond to call" unless @credentials.respond_to?(:call)
+          raise ArgumentError, "result_store must respond to write" if result_store && !result_store.respond_to?(:write)
+        end
+
+        # 拉取并标记重复管理地址的设备清单。
+        def devices
+          rows = @client.devices
+          raise Client::Error, "Netdisco returned an invalid device inventory" unless rows.is_a?(Array)
+
+          devices = rows.map { |row| Device.from_row(row, rules: @rules) }
+          duplicates = devices.group_by(&:host).reject { |host, entries| host.nil? || entries.size == 1 }
+          devices.map do |device|
+            duplicates.key?(device.host) ? device.with(issue: :duplicate_host) : device
+          end.freeze
+        end
+
+        # 规划本地配置备份的设备集合。
+        def plan_backup(limit_per_vendor: nil)
+          Planner.new(devices).call(mode: :backup, limit_per_vendor: limit_per_vendor)
+        end
+
+        # 规划 TFTP 配置备份的设备集合。
+        def plan_tftp_backup(limit_per_vendor: 5)
+          Planner.new(devices).call(mode: :tftp, limit_per_vendor: limit_per_vendor)
+        end
+
+        # 先拉取完整清单，再并发采集并保存设备配置。
+        def backup_all(directory: @settings.backup_directory, concurrency: @settings.concurrency,
+                       limit_per_vendor: nil, plan: nil, on_start: nil, on_result: nil, on_change: nil)
+          raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty?
+          Planner.validate_limit!(limit_per_vendor)
+          validate_callback!(on_result, :on_result)
+          validate_callback!(on_start, :on_start)
+          validate_callback!(on_change, :on_change)
+
+          plan ||= plan_backup(limit_per_vendor: limit_per_vendor)
+          validate_plan!(plan, :backup)
+          callbacks = [on_result]
+          callbacks << ->(item) { on_change.call(item) if item.backup.is_a?(Backup) && item.backup.changed? } if on_change
+          target_directory = File.expand_path(directory)
+          run_batch(:backup, plan, concurrency: concurrency, report_directory: directory,
+                   output_directory: target_directory, on_start: on_start, on_result: callbacks.compact) do |device, log_directory|
+            backup_one(device, target_directory, log_directory)
+          end
+        end
+
+        # 让设备主动导出配置，避免 PAN-OS 固定远端文件名在同批任务中冲突。
+        def tftp_backup_all(server:, source_files: {}, concurrency: @settings.concurrency,
+                            limit_per_vendor: 5, vrfs: {}, on_start: nil, on_result: nil, plan: nil,
+                            report_directory: @settings.backup_directory)
+          TftpTarget.new(host: server, path: "preflight.cfg")
+          raise ArgumentError, "source_files must be a Hash" unless source_files.is_a?(Hash)
+          source_files.each_value { |source_file| TftpTarget.validate_source_file!(source_file) }
+          validate_vrfs!(vrfs)
+          Planner.validate_limit!(limit_per_vendor)
+          validate_callback!(on_result, :on_result)
+          validate_callback!(on_start, :on_start)
+
+          plan ||= plan_tftp_backup(limit_per_vendor: limit_per_vendor)
+          validate_plan!(plan, :tftp)
+          run_batch(:tftp, plan, concurrency: concurrency, report_directory: report_directory,
+                    on_start: on_start, on_result: on_result) do |device, log_directory|
+            tftp_backup_one(device, server, source_files, log_directory, vrfs)
+          end
+        end
+
+        private
+
+        # 统一组织设备任务、日志目录与报告；Worker 保证单台设备失败不影响其他设备。
+        def run_batch(mode, plan, concurrency:, report_directory:, on_start:, on_result:, output_directory: nil)
+          worker = Worker.new(concurrency: concurrency)
+          started_at = Time.now.utc
+          outcomes = plan.outcomes.dup
+          FileUtils.mkdir_p(output_directory, mode: 0o700) if output_directory && !plan.ready.empty?
+          log_directory = @settings.log_directory
+          FileUtils.mkdir_p(log_directory, mode: 0o700) if log_directory && !plan.ready.empty?
+          callback_errors = worker.run(plan.ready, outcomes: outcomes, on_start: on_start, on_result: on_result,
+                                       on_error: ->(device, error) { outcome(device, :failed, error: error) }) do |device|
+            yield device, log_directory
+          end
+          batch = Batch.new(mode: mode, outcomes: outcomes.freeze, started_at: started_at,
+                            finished_at: Time.now.utc, callback_errors: callback_errors,
+                            report_location: nil, report_error: nil)
+          save_report(batch, directory: report_directory)
+        end
+
+        # 校验批量任务回调接口。
+        def validate_callback!(callback, name)
+          raise ArgumentError, "#{name} must respond to call" if callback && !callback.respond_to?(:call)
+        end
+
+        # 保存批量报告，记录写入失败而不覆盖设备结果。
+        def save_report(batch, directory:)
+          return batch unless @result_store
+
+          batch.with(report_location: @result_store.write(batch, directory: directory))
+        rescue StandardError => error
+          batch.with(report_error: error.class.name)
+        end
+
+        # 校验厂商 VRF 映射和名称。
+        def validate_vrfs!(vrfs)
+          unless vrfs.is_a?(Hash) && vrfs.all? { |vendor, value|
+            %i[cisco_nxos hillstone].include?(vendor) && value.is_a?(String) &&
+              value.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/)
+          }
+            raise ArgumentError, "vrfs must map supported vendor names to safe VRF names"
+          end
+        end
+
+        # 确认传入计划属于当前备份模式。
+        def validate_plan!(plan, mode)
+          raise ArgumentError, "plan must be a #{mode} Netdisco plan" unless plan.is_a?(Plan) && plan.mode == mode
+
+          inventory = plan.inventory
+          ready = plan.ready
+          outcomes = plan.outcomes
+          unless inventory.is_a?(Array) && inventory.all?(Device) && ready.is_a?(Array) &&
+                 outcomes.is_a?(Array) && outcomes.size == inventory.size
+            raise ArgumentError, "plan inventory and outcomes must have the same device slots"
+          end
+
+          selected = {}
+          previous_index = -1
+          ready.each do |task|
+            unless task.is_a?(Array) && task.size == 2 && task.first.is_a?(Integer)
+              raise ArgumentError, "plan contains an invalid device task"
+            end
+
+            index, device = task
+            unless index > previous_index && index < inventory.size && inventory[index].equal?(device) && device.ready?
+              raise ArgumentError, "plan tasks must reference ready inventory devices in order"
+            end
+
+            selected[index] = true
+            previous_index = index
+          end
+          if mode == :tftp && ready.count { |_index, device| device.vendor == :palo_alto } > 1
+            raise ArgumentError, "plan cannot upload multiple Palo Alto devices to one TFTP filename"
+          end
+
+          inventory.each_with_index do |device, index|
+            result = outcomes[index]
+            next if selected[index] && result.nil?
+
+            unless !selected[index] && valid_skipped_outcome?(result, device, mode)
+              raise ArgumentError, "plan outcome does not match its inventory slot"
+            end
+          end
+        end
+
+        # 未执行设备必须保留与清单一致的跳过原因，且不能带有执行产物。
+        def valid_skipped_outcome?(result, device, mode)
+          return false unless result.is_a?(Outcome) && result.device.equal?(device) && result.backup.nil? &&
+                              result.error_code.nil? && result.error_type.nil? &&
+                              result.started_at.nil? && result.finished_at.nil?
+
+          return result.status == device.issue unless device.ready?
+
+          result.status == :sample_limit ||
+            (mode == :tftp && device.vendor == :palo_alto && result.status == :remote_filename_collision)
+        end
+
+        # 构造包含错误类型的单台设备结果。
+        def outcome(device, status, backup: nil, error: nil)
+          Outcome.new(device: device, status: status, backup: backup,
+                      error_code: error.respond_to?(:code) ? error.code : nil,
+                      error_type: error&.class&.name)
+        end
+
+        # 执行单台设备的 TFTP 导出。
+        def tftp_backup_one(device, server, source_files, log_directory, vrfs)
+          run_one(device, log_directory, success_status: :reported_uploaded,
+                  close_error_status: :reported_with_error, backup_class: TftpBackup) do |connector|
+            source_file = source_files.fetch(device.vendor, nil)
+            transfer_settings = { host: server, path: device.tftp_filename, source_file: source_file }
+            transfer_settings[:vrf] = vrfs.fetch(device.vendor) if vrfs.key?(device.vendor)
+            connector.tftp_backup(**transfer_settings)
+          end
+        end
+
+        # 执行单台设备的本地配置采集。
+        def backup_one(device, directory, log_directory)
+          destination = File.join(directory, device.backup_filename)
+          previous = Operations::SavedConfig.new(directory: directory).find(device.host, required: false)
+          previous_digest = Digest::SHA256.file(previous).hexdigest if previous && previous != destination
+          run_one(device, log_directory, success_status: :backed_up,
+                  close_error_status: :saved_with_error, backup_class: Backup) do |connector|
+            backup = connector.backup(path: destination)
+            if backup.is_a?(Backup) && backup.change == :created && previous_digest
+              backup.with(previous_sha256: previous_digest,
+                          change: backup.sha256 == previous_digest ? :unchanged : :changed)
+            else
+              backup
+            end
+          end
+        end
+
+        # 隔离单台设备的凭据、连接、操作和关闭异常。
+        def run_one(device, log_directory, success_status:, close_error_status:, backup_class:)
+          connection_settings = @credentials.call(device)
+          return outcome(device, :missing_credentials) if connection_settings.nil?
+          unless connection_settings.is_a?(Hash) && connection_settings.keys.all?(Symbol) &&
+                 connection_settings[:username].is_a?(String) && !connection_settings[:username].empty? &&
+                 !connection_settings.key?(:host)
+            raise ArgumentError, "credential resolver must return settings with username and without host"
+          end
+
+          log_name = device.host.tr(":", "_")
+          if log_directory
+            connection_settings = connection_settings.merge(log_file: File.join(log_directory, "#{log_name}.log"))
+          end
+          connector = @connector_factory.call(device, connection_settings)
+          backup = nil
+          failure = nil
+          begin
+            result = yield connector
+            raise TypeError, "backup operation did not return #{backup_class}" unless result.is_a?(backup_class)
+
+            backup = result
+          rescue StandardError => error
+            failure = error
+          ensure
+            begin
+              connector.close
+            rescue StandardError => error
+              failure ||= error
+            end
+          end
+          return outcome(device, success_status, backup: backup) unless failure
+
+          outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
+        rescue StandardError => error
+          outcome(device, :failed, error: error)
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/planner.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Netdisco
+      # 固定一份清单上的选择结果与跳过原因，供预览和执行复用。
+      Plan = Data.define(:mode, :inventory, :ready, :outcomes) do
+        # Data 只冻结对象自身；这里复制并冻结可能由调用方修改的计划容器。
+        def initialize(mode:, inventory:, ready:, outcomes:)
+          unless inventory.is_a?(Array) && ready.is_a?(Array) && outcomes.is_a?(Array)
+            raise ArgumentError, "plan inventory, ready tasks, and outcomes must be Arrays"
+          end
+
+          tasks = ready.map { |task| task.is_a?(Array) ? task.dup.freeze : task }.freeze
+          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze)
+        end
+
+        # 按清单顺序返回选中的设备。
+        def selected = ready.map(&:last)
+      end
+
+      # 根据设备就绪状态、厂商采样及远端文件冲突建立备份计划。
+      class Planner
+        # 保存本次规划使用的清单快照。
+        def initialize(inventory)
+          @inventory = inventory.dup.freeze
+        end
+
+        # 生成本地或 TFTP 备份计划，明确记录每台未执行设备的原因。
+        def call(mode:, limit_per_vendor:)
+          self.class.validate_limit!(limit_per_vendor)
+          candidates = @inventory.each_with_index.select { |device, _index| device.ready? }
+          selected = if limit_per_vendor
+                       candidates.group_by { |device, _index| device.vendor }.values.flat_map do |entries|
+                         entries.sort_by { |device, _index| device.host }.first(limit_per_vendor)
+                       end
+                     else
+                       candidates
+                     end
+          # PAN-OS 导出使用固定远端文件名，同批只允许一台设备写入。
+          palo_alto_index = selected.find { |device, _index| device.vendor == :palo_alto }&.last if mode == :tftp
+          selected_indices = selected.to_h { |_device, index| [index, true] }
+          outcomes = Array.new(@inventory.size)
+          ready = @inventory.each_with_index.filter_map do |device, index|
+            if !device.ready?
+              outcomes[index] = skipped(device, device.issue)
+              nil
+            elsif mode == :tftp && device.vendor == :palo_alto && index != palo_alto_index
+              outcomes[index] = skipped(device, :remote_filename_collision)
+              nil
+            elsif selected_indices.key?(index)
+              [index, device].freeze
+            else
+              outcomes[index] = skipped(device, :sample_limit)
+              nil
+            end
+          end
+          Plan.new(mode: mode, inventory: @inventory, ready: ready.freeze, outcomes: outcomes.freeze)
+        end
+
+        # 限制单厂商采样数，空值表示选择所有就绪设备。
+        def self.validate_limit!(limit)
+          return if limit.nil? || (limit.is_a?(Integer) && (1..5).cover?(limit))
+
+          raise ArgumentError, "limit_per_vendor must be nil or an Integer in 1..5"
+        end
+
+        private
+
+        # 构建计划阶段无需设备连接的跳过结果。
+        def skipped(device, status)
+          Outcome.new(device: device, status: status, backup: nil, error_code: nil, error_type: nil)
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/result_store.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "securerandom"
+require_relative "../operations/private_file"
+
+module Net
+  module Connector
+    module Netdisco
+      module ResultStore
+        # 每批保存一份私有 JSON 报告，通过重命名防止半写文件。
+        class Text
+          # 以临时文件和重命名原子写入私有 JSON 报告。
+          def write(batch, directory:)
+            destination = File.expand_path(directory)
+            FileUtils.mkdir_p(destination, mode: 0o700)
+            filename = "netdisco-#{batch.mode}-#{batch.started_at.strftime("%Y%m%dT%H%M%SZ")}-#{SecureRandom.hex(4)}.json"
+            path = File.join(destination, filename)
+            Operations::PrivateFile.write(path, JSON.pretty_generate(batch.summary))
+          end
+        end
+
+        # 数据库仓储由调用方提供，可使用 Active Record 或其他对象。
+        # 仓储须实现 create!，本项目不负责数据库表结构。
+        class Database
+          # 校验并保存调用方提供的数据库仓储。
+          def initialize(repository:)
+            raise ArgumentError, "repository must respond to create!" unless repository.respond_to?(:create!)
+
+            @repository = repository
+          end
+
+          # 把批量摘要写入调用方仓储并返回记录位置。
+          def write(batch, **_options)
+            record = @repository.create!(batch.summary)
+            record.respond_to?(:id) ? "database:#{record.id}" : "database"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/rules.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Net
+  module Connector
+    module Netdisco
+      # 将 Netdisco 标签映射到连接器并筛选清单。
+      class Rules
+        # 校验并保存清单过滤和厂商映射规则。
+        def initialize(include_hosts: [], exclude_hosts: [], include_vendors: [], vendor_overrides: {},
+                       host_overrides: {}, mappings: [])
+          @include_hosts = string_list(include_hosts)
+          @exclude_hosts = string_list(exclude_hosts)
+          raise ArgumentError, "include_vendors must be an Array" unless include_vendors.is_a?(Array)
+
+          @include_vendors = include_vendors.map do |vendor|
+            raise ArgumentError, "include_vendors contains an invalid value" unless vendor.is_a?(String) || vendor.is_a?(Symbol)
+
+            vendor.to_sym
+          end.freeze
+          unless @include_vendors.all? { |vendor| Net::Connector.vendors.include?(vendor) }
+            raise ArgumentError, "include_vendors contains an unsupported connector"
+          end
+          unless vendor_overrides.is_a?(Hash)
+            raise ArgumentError, "vendor_overrides must be a Hash"
+          end
+          @vendor_overrides = vendor_overrides.to_h do |label, vendor|
+            unless label.is_a?(String) && vendor.is_a?(String) && !label.empty?
+              raise ArgumentError, "vendor_overrides must map labels to connector names"
+            end
+            key = normalize(label)
+            value = vendor.to_sym
+            raise ArgumentError, "vendor_overrides contains an unsupported connector" unless Net::Connector.vendors.include?(value)
+
+            [key, value]
+          end.freeze
+          raise ArgumentError, "host_overrides must be a Hash" unless host_overrides.is_a?(Hash)
+
+          @host_overrides = host_overrides.to_h do |host, vendor|
+            unless host.is_a?(String) && !host.include?("/") && vendor.is_a?(String)
+              raise ArgumentError, "host_overrides must map IP addresses to connector names"
+            end
+            begin
+              address = IPAddr.new(host).to_s
+            rescue IPAddr::Error
+              raise ArgumentError, "host_overrides contains an invalid IP address"
+            end
+            connector = vendor.to_sym
+            raise ArgumentError, "host_overrides contains an unsupported connector" unless Net::Connector.vendors.include?(connector)
+
+            [address, connector]
+          end.freeze
+          raise ArgumentError, "mappings must be an Array" unless mappings.is_a?(Array)
+
+          @mappings = mappings.map do |rule|
+            unless rule.is_a?(Hash) && rule["vendor"].is_a?(String) && !rule["vendor"].empty? &&
+                   rule["connector"].is_a?(String) &&
+                   (rule.keys - %w[vendor os model_prefix connector]).empty? &&
+                   %w[os model_prefix].all? { |key| rule[key].nil? || rule[key].is_a?(String) }
+              raise ArgumentError, "each mapping requires vendor and connector strings"
+            end
+            connector = rule.fetch("connector").to_sym
+            raise ArgumentError, "mapping contains an unsupported connector" unless Net::Connector.vendors.include?(connector)
+
+            { vendor: normalize(rule.fetch("vendor")), os: rule["os"] && normalize(rule["os"]),
+              model_prefix: rule["model_prefix"] && normalize(rule["model_prefix"]), connector: connector }.freeze
+          end.freeze
+        end
+
+        # 根据地址、显式规则和厂商信息识别连接器。
+        def resolve(row)
+          begin
+            address = IPAddr.new(row["ip"]).to_s
+            return @host_overrides.fetch(address) if @host_overrides.key?(address)
+          rescue IPAddr::Error, TypeError
+            # 无效的管理地址交由 Device.from_row 标记。
+          end
+          label = normalize(row["vendor"])
+          os = normalize(row["os"])
+          model = normalize(row["model"])
+          match = @mappings.find do |rule|
+            rule[:vendor] == label && (rule[:os].nil? || rule[:os] == os) &&
+              (rule[:model_prefix].nil? || model.start_with?(rule[:model_prefix]))
+          end
+          return match[:connector] if match
+          return @vendor_overrides[label] if @vendor_overrides.key?(label)
+
+          case label
+          when /\bh3c\b/ then (os.match?(/wireless|wlan/) || model.match?(/\A(?:wx|ac)\s*\d/)) ? :h3c_wireless : :h3c
+          when /\bcisco\b/
+            return :cisco_nxos if os.match?(/nx\s*os|nexus/) || model.match?(/\bnexus\b|\bn\s*[3579]k\b/)
+            return :cisco_ios if os.match?(/\bios\b|\bios\s*xe\b/)
+          when /\bradware\b/ then :radware
+          when /palo\s*alto|paloalto/ then :palo_alto
+          when /\bhuawei\b/ then :huawei
+          when /\bhillstone\b/ then :hillstone
+          end
+        end
+
+        # 判断设备是否通过地址和厂商过滤。
+        def selected?(host, vendor)
+          return false if @exclude_hosts.include?(host)
+          return false if !@include_hosts.empty? && !@include_hosts.include?(host)
+          return false if !@include_vendors.empty? && !@include_vendors.include?(vendor)
+
+          true
+        end
+
+        private
+
+        # 校验并标准化管理地址列表。
+        def string_list(values)
+          raise ArgumentError, "host lists must be Arrays" unless values.is_a?(Array)
+
+          values.map do |value|
+            raise ArgumentError, "host list entries must be Strings" unless value.is_a?(String) && !value.empty?
+            raise ArgumentError, "host list entries must be IP addresses" if value.include?("/")
+
+            IPAddr.new(value).to_s.freeze
+          rescue IPAddr::Error
+            raise ArgumentError, "host list entries must be IP addresses"
+          end.freeze
+        end
+
+        # 将设备标签转为便于匹配的小写词串。
+        def normalize(value) = value.to_s.downcase.gsub(/[^a-z0-9]+/, " ").strip
+      end
+    end
+  end
+end