net-connector 0.4.0

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Net
+  module Connector
+    module Netdisco
+      # 使用时从环境中读取配置，并提供明确的默认值。
+      class Settings
+        DEFAULT_BACKUP_DIRECTORY = "backups"
+        DEFAULT_CONCURRENCY = 4
+        MAX_CONCURRENCY = 50
+        DEFAULT_PAGE_SIZE = 500
+
+        # 加载 YAML 配置，并使环境变量覆盖文件配置。
+        def self.from_file(path, env: ENV)
+          new(env: ConfigFile.load(path).merge(env.to_h))
+        end
+
+        # 保存当前批次读取配置所用的环境映射。
+        def initialize(env: ENV)
+          @env = env
+        end
+
+        # 使用 Netdisco 地址和认证信息创建客户端。
+        def client
+          options = { url: required("NETDISCO_URL"), page_size: integer("NETDISCO_PAGE_SIZE", DEFAULT_PAGE_SIZE) }
+          if present?(@env["NETDISCO_API_KEY"])
+            options[:api_key] = @env["NETDISCO_API_KEY"]
+          else
+            options[:username] = required("NETDISCO_USERNAME")
+            options[:password] = required("NETDISCO_PASSWORD")
+          end
+          Client.new(**options)
+        end
+
+        # 读取清单筛选和厂商映射规则。
+        def rules
+          Rules.new(include_hosts: list("NET_CONNECTOR_INCLUDE_HOSTS"),
+                    exclude_hosts: list("NET_CONNECTOR_EXCLUDE_HOSTS"),
+                    include_vendors: list("NET_CONNECTOR_INCLUDE_VENDORS"),
+                    vendor_overrides: json("NET_CONNECTOR_VENDOR_OVERRIDES", {}),
+                    host_overrides: json("NET_CONNECTOR_HOST_OVERRIDES", {}),
+                    mappings: json("NET_CONNECTOR_DEVICE_RULES", []))
+        end
+
+        # 读取并展开本地备份目录。
+        def backup_directory
+          path = @env.fetch("NET_CONNECTOR_BACKUP_DIRECTORY", DEFAULT_BACKUP_DIRECTORY)
+          raise ArgumentError, "NET_CONNECTOR_BACKUP_DIRECTORY must be nonempty" unless present?(path)
+
+          File.expand_path(path)
+        end
+
+        # 读取并限制设备任务并发数。
+        def concurrency
+          count = integer("NET_CONNECTOR_CONCURRENCY", DEFAULT_CONCURRENCY)
+          raise ArgumentError, "NET_CONNECTOR_CONCURRENCY must be at most #{MAX_CONCURRENCY}" if count > MAX_CONCURRENCY
+
+          count
+        end
+
+        # 确定厂商采样数量：本地默认全量，TFTP 默认每厂商五台。
+        def limit_per_vendor(tftp: false)
+          return integer("NET_CONNECTOR_SAMPLE_PER_VENDOR", 5) if @env.key?("NET_CONNECTOR_SAMPLE_PER_VENDOR")
+
+          5 if tftp
+        end
+
+        # 读取厂商的 TFTP 源文件配置，并提供华为启动配置默认路径。
+        def tftp_source_files
+          files = { huawei: @env.fetch("NET_CONNECTOR_HUAWEI_TFTP_SOURCE_FILE", "flash:/startup.cfg") }
+          %i[h3c h3c_wireless].each do |vendor|
+            key = "NET_CONNECTOR_#{vendor.to_s.upcase}_TFTP_SOURCE_FILE"
+            files[vendor] = @env.fetch(key) if @env.key?(key)
+          end
+          files
+        end
+
+        # 读取各厂商 TFTP 出口 VRF 的名称映射。
+        def tftp_vrfs
+          raw = json("NET_CONNECTOR_TFTP_VRFS", {})
+          raise ArgumentError, "NET_CONNECTOR_TFTP_VRFS must be a JSON object" unless raw.is_a?(Hash)
+
+          raw.transform_keys(&:to_sym)
+        end
+
+        # 每台设备执行时读取凭据，使新批次可使用轮换后的环境变量。
+        # 按厂商优先级读取设备账号与密码。
+        def credentials_for(device)
+          prefix = "NET_CONNECTOR_#{device.vendor.to_s.upcase}_"
+          username = value(prefix + "USERNAME") || value("NET_CONNECTOR_DEVICE_USERNAME")
+          return nil unless username
+
+          {
+            username: username,
+            password: value(prefix + "PASSWORD") || value("NET_CONNECTOR_DEVICE_PASSWORD"),
+            enable_password: value(prefix + "ENABLE_PASSWORD") || value("NET_CONNECTOR_ENABLE_PASSWORD"),
+            protocol: (value(prefix + "PROTOCOL") || value("NET_CONNECTOR_PROTOCOL") || "ssh").to_sym,
+            log_level: (value("NET_CONNECTOR_LOG_LEVEL") || "info").to_sym,
+            known_hosts: value("NET_CONNECTOR_KNOWN_HOSTS"),
+            host_key_policy: (value("NET_CONNECTOR_HOST_KEY_POLICY") || "strict").to_sym
+          }
+        end
+
+        # 读取并展开设备日志目录。
+        def log_directory
+          path = value("NET_CONNECTOR_LOG_DIRECTORY")
+          File.expand_path(path) if path
+        end
+
+        # 仅展示非敏感配置，不输出设备凭据或 API 密钥。
+        # 生成不包含凭据的可展示配置。
+        def public_config
+          rules
+          url = value("NETDISCO_URL")
+          if url
+            uri = URI.parse(url)
+            unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+              raise ArgumentError, "NETDISCO_URL must be a base URL without credentials or query"
+            end
+          end
+          {
+            netdisco: { url: url, page_size: integer("NETDISCO_PAGE_SIZE", DEFAULT_PAGE_SIZE) },
+            backup: { directory: backup_directory, concurrency: concurrency,
+                      limit_per_vendor: limit_per_vendor },
+            inventory: { include_hosts: list("NET_CONNECTOR_INCLUDE_HOSTS"),
+                         exclude_hosts: list("NET_CONNECTOR_EXCLUDE_HOSTS"),
+                         include_vendors: list("NET_CONNECTOR_INCLUDE_VENDORS"),
+                         vendor_overrides: json("NET_CONNECTOR_VENDOR_OVERRIDES", {}),
+                         host_overrides: json("NET_CONNECTOR_HOST_OVERRIDES", {}),
+                         device_rules: json("NET_CONNECTOR_DEVICE_RULES", []) },
+            ssh: { protocol: value("NET_CONNECTOR_PROTOCOL") || "ssh",
+                   known_hosts: value("NET_CONNECTOR_KNOWN_HOSTS"),
+                   host_key_policy: value("NET_CONNECTOR_HOST_KEY_POLICY") || "strict",
+                   log_directory: log_directory,
+                   log_level: value("NET_CONNECTOR_LOG_LEVEL") || "info" },
+            tftp: { server: value("TFTP_HOST"), vrfs: tftp_vrfs.transform_keys(&:to_s) }
+          }
+        rescue URI::InvalidURIError
+          raise ArgumentError, "NETDISCO_URL is invalid"
+        end
+
+        private
+
+        # 解析指定环境变量中的 JSON 配置。
+        def json(key, default)
+          raw = value(key)
+          raw ? JSON.parse(raw) : default
+        rescue JSON::ParserError
+          raise ArgumentError, "#{key} must be valid JSON"
+        end
+
+        # 解析逗号分隔的环境变量列表。
+        def list(key) = @env.fetch(key, "").split(",").map(&:strip).reject(&:empty?)
+
+        # 读取正整数配置并统一错误信息。
+        def integer(key, default)
+          raw = @env.fetch(key, default)
+          value = Integer(raw.to_s, 10)
+          raise ArgumentError, "#{key} must be a positive integer" unless value.positive?
+
+          value
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "#{key} must be a positive integer"
+        end
+
+        # 读取非空字符串配置。
+        def value(key)
+          result = @env[key]
+          result if present?(result)
+        end
+
+        # 读取必填环境变量。
+        def required(key) = value(key) || (raise ArgumentError, "#{key} is required")
+
+        # 判断环境变量是否为非空字符串。
+        def present?(value) = value.is_a?(String) && !value.strip.empty?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Netdisco
+      # 以固定并发上限执行相互隔离的设备任务。
+      class Worker
+        # 校验并保存最大设备并发数。
+        def initialize(concurrency:)
+          unless concurrency.is_a?(Integer) && (1..Settings::MAX_CONCURRENCY).cover?(concurrency)
+            raise ArgumentError, "concurrency must be an Integer in 1..#{Settings::MAX_CONCURRENCY}"
+          end
+
+          @concurrency = concurrency
+        end
+
+        # 按清单顺序收集结果，并隔离设备及回调异常。
+        def run(tasks, outcomes:, on_error:, on_start: nil, on_result: nil)
+          queue = Queue.new
+          tasks.each { |task| queue << task }
+          worker_count = [tasks.size, @concurrency].min
+          worker_count.times { queue << nil }
+          callback_errors = Queue.new
+          threads = Array.new(worker_count) do
+            Thread.new do
+              Thread.current.report_on_exception = false
+              while (task = queue.pop)
+                index, device = task
+                started_at = Time.now.utc
+                begin
+                  on_start&.call(device)
+                rescue StandardError => error
+                  callback_errors << { host: device.host, error_type: error.class.name }.freeze
+                end
+                result = begin
+                           yield device
+                         rescue StandardError => error
+                           on_error.call(device, error)
+                         end
+                result = result.with(started_at: started_at, finished_at: Time.now.utc)
+                outcomes[index] = result
+                Array(on_result).each do |callback|
+                  begin
+                    callback.call(result)
+                  rescue StandardError => error
+                    callback_errors << { host: device.host, error_type: error.class.name }.freeze
+                  end
+                end
+              end
+            end
+          end
+          completed = false
+          begin
+            threads.each(&:value)
+            completed = true
+          ensure
+            # 中断或某个 worker 抛出非 StandardError 时，不让其他设备任务
+            # 在调用方已经退出后继续运行；Thread#kill 会执行任务自身的 ensure。
+            unless completed
+              threads.each(&:kill)
+              threads.each do |thread|
+                begin
+                  thread.join
+                rescue Exception # rubocop:disable Lint/RescueException -- Preserve the original interruption after all workers stop.
+                  nil
+                end
+              end
+            end
+          end
+          Array.new(callback_errors.size) { callback_errors.pop }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "../connector"
+require_relative "netdisco/client"
+require_relative "netdisco/rules"
+require_relative "netdisco/device"
+require_relative "netdisco/config_file"
+require_relative "netdisco/settings"
+require_relative "netdisco/worker"
+require_relative "netdisco/result_store"
+require_relative "netdisco/batch"
+require_relative "netdisco/planner"
+require_relative "netdisco/fleet"
+require_relative "netdisco/cli"

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "private_file"
+
+module Net
+  module Connector
+    Backup = Data.define(:path, :bytes, :sha256, :collected_at, :change, :previous_sha256) do
+      # 保存配置备份的路径、摘要和变更状态。
+      def initialize(path:, bytes:, sha256:, collected_at:, change: nil, previous_sha256: nil)
+        super
+      end
+
+      # 判断本次采集是否产生新的配置内容。
+      def changed? = [:created, :changed].include?(change)
+    end
+
+    module Operations
+      class LocalBackup
+        # 保存执行配置采集的设备对象。
+        def initialize(device) = @device = device
+
+        # 采集配置、识别变更并原子写入私有文件。
+        def call(path:)
+          raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?
+
+          contents = @device.running_config.value!
+          destination = File.expand_path(path)
+          digest = Digest::SHA256.hexdigest(contents)
+          previous_digest = Digest::SHA256.file(destination).hexdigest if File.file?(destination) && !File.symlink?(destination)
+          change = if previous_digest.nil?
+                     :created
+                   elsif previous_digest == digest
+                     :unchanged
+                   else
+                     :changed
+                   end
+
+          if change != :unchanged || (File.stat(destination).mode & 0o777) != 0o600
+            PrivateFile.write(destination, contents)
+          end
+          Backup.new(path: destination, bytes: contents.bytesize,
+                     sha256: digest, collected_at: Time.now.utc, change: change,
+                     previous_sha256: previous_digest)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "textfsm"
+require_relative "../engine/errors"
+require_relative "../engine/terminal_renderer"
+
+module Net
+  module Connector
+    module Operations
+      # 将设备命令回显或配置文本按 TextFSM 模板转换为结构化记录。
+      class ParseOutput
+        DEFAULT_TEMPLATE_DIR = File.expand_path("../templates", __dir__).freeze
+
+        # 配置模板目录和 Netmiko 风格的命令索引文件。
+        def initialize(template_dir: nil, index: "index")
+          template_dir ||= DEFAULT_TEMPLATE_DIR
+          raise ArgumentError, "template_dir must be a nonempty String" unless template_dir.is_a?(String) && !template_dir.empty?
+          raise ArgumentError, "index must be a nonempty String" unless index.is_a?(String) && !index.empty?
+
+          @template_dir = File.expand_path(template_dir)
+          @index = index
+        end
+
+        # 显式模板按路径读取；未指定时按厂商和命令从索引选择模板。
+        def call(text, template: nil, vendor: nil, command: nil, host: nil)
+          raise ArgumentError, "text must be a String" unless text.is_a?(String)
+
+          text = TerminalRenderer.render(text).force_encoding(Encoding::UTF_8)
+          if template
+            raise ArgumentError, "template must be a nonempty String" unless template.is_a?(String) && !template.empty?
+
+            TextFSM::Parser.from_file(File.expand_path(template, @template_dir)).parse_hashes(text)
+          else
+            raise ArgumentError, "vendor and command are required for template lookup" unless vendor && command.is_a?(String) && !command.empty?
+
+            attributes = { "Vendor" => vendor.to_s, "Command" => command }
+            table = TextFSM::CliTable.new(index: @index, template_dir: @template_dir)
+            unless table.index.match(attributes)
+              raise ParsingError.new("no TextFSM template matches this vendor and command",
+                                     code: :template_missing, host: host, phase: :parse)
+            end
+            table.parse(text, attributes: attributes).to_hashes
+          end
+        rescue TextFSM::IndexError
+          raise ParsingError.new("TextFSM template index is invalid",
+                                 code: :template_invalid, host: host, phase: :parse), cause: nil
+        rescue TextFSM::TemplateError
+          raise ParsingError.new("TextFSM template is invalid",
+                                 code: :template_invalid, host: host, phase: :parse), cause: nil
+        rescue TextFSM::ParseError
+          raise ParsingError.new("TextFSM could not parse the device output",
+                                 code: :parse_failed, host: host, phase: :parse), cause: nil
+        rescue IOError, SystemCallError
+          raise ParsingError.new("unable to read TextFSM template",
+                                 code: :template_unreadable, host: host, phase: :parse), cause: nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module Net
+  module Connector
+    module Operations
+      # 将配置写入同目录的私有临时文件，再原子替换目标文件。
+      module PrivateFile
+        # 写入完整内容并同步到磁盘，避免覆盖失败留下半份配置。
+        def self.write(path, contents)
+          Tempfile.create([".net-connector-", ".tmp"], File.dirname(path)) do |file|
+            file.binmode
+            file.chmod(0o600)
+            file.write(contents)
+            file.flush
+            file.fsync
+            File.rename(file.path, path)
+          end
+          path
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "../running_config"
+require_relative "../../vendor/cisco_ios/running_config"
+require_relative "../../vendor/cisco_nxos/running_config"
+
+module Net
+  module Connector
+    module Operations
+      RunningConfig::Cisco = Net::Connector::CiscoIos::RunningConfig
+      RunningConfig::CiscoNxos = Net::Connector::CiscoNxos::RunningConfig
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../running_config"
+require_relative "../../vendor/hillstone/running_config"
+
+module Net
+  module Connector
+    module Operations
+      RunningConfig::Hillstone = Net::Connector::Hillstone::RunningConfig
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../running_config"
+require_relative "../../vendor/palo_alto/running_config"
+
+module Net
+  module Connector
+    module Operations
+      RunningConfig::PaloAlto = Net::Connector::PaloAlto::RunningConfig
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../running_config"

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../device/running_config"
+
+module Net
+  module Connector
+    module Operations
+      # 旧常量与新能力共享同一实现，不维护第二套采集流程。
+      RunningConfig = Net::Connector::RunningConfig
+      RunningConfig.autoload :Cisco, File.expand_path("running_config/cisco", __dir__)
+      RunningConfig.autoload :CiscoNxos, File.expand_path("running_config/cisco", __dir__)
+      RunningConfig.autoload :Hillstone, File.expand_path("running_config/hillstone", __dir__)
+      RunningConfig.autoload :PaloAlto, File.expand_path("running_config/palo_alto", __dir__)
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "ipaddr"
+require_relative "private_file"
+require_relative "parse_output"
+
+module Net
+  module Connector
+    module Operations
+      # 直接导出已有本地配置，无需访问 Netdisco。
+      class SavedConfig
+        # 只用规范化的管理地址标识配置，避免设备改名改变备份身份。
+        def self.filename(host)
+          raise ArgumentError, "host must be an IP address" unless host.is_a?(String) && !host.include?("/")
+
+          "#{IPAddr.new(host).to_s.tr(":", "_")}.txt"
+        rescue IPAddr::Error
+          raise ArgumentError, "host must be an IP address"
+        end
+
+        # 保存已有配置文件所在目录。
+        def initialize(directory:)
+          raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty?
+
+          @directory = File.expand_path(directory)
+        end
+
+        # 优先查找固定文件名；仅在不存在时兼容唯一的旧命名文件。
+        def find(host, required: true)
+          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}") }
+            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)
+          end
+          raise ArgumentError, "saved configuration is not a regular file" unless File.file?(path) && !File.symlink?(path)
+
+          path
+        end
+
+        # 将已保存配置写入目标文件或标准输出。
+        def export(host:, output: nil, io: $stdout)
+          contents = File.binread(find(host))
+          if output
+            raise ArgumentError, "output must be a nonempty String" unless output.is_a?(String) && !output.empty?
+
+            destination = File.expand_path(output)
+            directory = File.dirname(destination)
+            FileUtils.mkdir_p(directory, mode: 0o700)
+            PrivateFile.write(destination, contents)
+          else
+            io.binmode if io.respond_to?(:binmode)
+            io.write(contents)
+            nil
+          end
+        end
+
+        # 使用指定模板解析已有配置，无需访问设备或 Netdisco。
+        def parse(host:, template:, template_dir: nil)
+          parser = ParseOutput.new(template_dir: template_dir)
+          parser.call(File.binread(find(host)), template: template, host: host)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# 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

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

@@ -0,0 +1,11 @@
+# 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

@@ -0,0 +1,11 @@
+# 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

@@ -0,0 +1,11 @@
+# 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

@@ -0,0 +1,11 @@
+# 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

@@ -0,0 +1,11 @@
+# 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