net-connector 0.4.0

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Net
+  module Connector
+    module Netdisco
+      # 单台设备的最终结果，保留状态、配置产物和错误类型。
+      Outcome = Data.define(:device, :status, :backup, :error_code, :error_type,
+                            :started_at, :finished_at) do
+        # 创建结果，允许计划阶段尚无执行时间。
+        def initialize(device:, status:, backup:, error_code:, error_type:, started_at: nil, finished_at: nil)
+          super
+        end
+
+        # 判断设备是否完成配置保存或上报上传成功。
+        def success? = [:backed_up, :reported_uploaded].include?(status)
+
+        # 判断配置已产生但收尾过程是否出错。
+        def partial? = [:saved_with_error, :reported_with_error].include?(status)
+
+        # 判断设备是否因为清单或采样规则未执行。
+        def skipped? = !success? && !partial? && status != :failed
+
+        # 计算设备任务的耗时，计划阶段没有时间时返回空值。
+        def duration_ms
+          ((finished_at - started_at) * 1000).round if started_at && finished_at
+        end
+      end
+
+      # 汇总一次批量任务的设备结果、回调故障和报告写入状态。
+      Batch = Data.define(:mode, :outcomes, :started_at, :finished_at, :callback_errors,
+                          :report_location, :report_error) do
+        # 按设备最终状态统计数量。
+        def counts = outcomes.group_by(&:status).transform_values(&:size)
+
+        # 仅在所有设备成功且回调、报告均正常时判定整批成功。
+        def success? = !outcomes.empty? && outcomes.all?(&:success?) && callback_errors.empty? && report_error.nil?
+
+        # 空清单与已尝试但未全部成功的批次分别标记。
+        def status = outcomes.empty? ? :no_devices : (success? ? :succeeded : :incomplete)
+
+        # 生成可写入报告及供命令行展示的结构化摘要。
+        def summary
+          {
+            mode: mode, status: status, started_at: started_at.iso8601, finished_at: finished_at.iso8601,
+            total: outcomes.size,
+            succeeded: outcomes.count(&:success?),
+            partial: outcomes.count(&:partial?),
+            failed: outcomes.count { |item| item.status == :failed },
+            skipped: outcomes.count(&:skipped?),
+            counts: counts,
+            callback_errors: callback_errors,
+            devices: outcomes.map do |item|
+              { host: item.device.host || item.device.source_ip, name: item.device.name,
+                vendor: item.device.vendor,
+                status: item.status, path: item.backup&.path,
+                bytes: item.backup.is_a?(Backup) ? item.backup.bytes : nil,
+                sha256: item.backup.is_a?(Backup) ? item.backup.sha256 : nil,
+                change: item.backup.is_a?(Backup) ? item.backup.change : nil,
+                previous_sha256: item.backup.is_a?(Backup) ? item.backup.previous_sha256 : nil,
+                started_at: item.started_at&.iso8601, finished_at: item.finished_at&.iso8601,
+                duration_ms: item.duration_ms,
+                error_code: item.error_code, error_type: item.error_type }
+            end
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "json"
+require "ipaddr"
+require "optparse"
+
+module Net
+  module Connector
+    module Netdisco
+      class CLI
+        # 保存命令行输入输出和清单任务工厂。
+        def initialize(argv: ARGV, env: ENV, output: $stdout, error: $stderr,
+                       fleet_factory: ->(settings) { Fleet.new(settings: settings) })
+          @argv = argv.dup
+          @env = env
+          @output = output
+          @error = error
+          @fleet_factory = fleet_factory
+        end
+
+        # 解析参数并执行预览、导出或批量备份。
+        def run
+          options = parse_options
+          return 0 if options[:done]
+
+          validate_options!(options)
+          values = options[:config] ? ConfigFile.load(options[:config]).merge(@env.to_h) : @env.to_h
+          values["NET_CONNECTOR_BACKUP_DIRECTORY"] = options[:directory] if options[:directory]
+          values["NET_CONNECTOR_CONCURRENCY"] = options[:concurrency].to_s if options[:concurrency]
+          values["NET_CONNECTOR_INCLUDE_HOSTS"] = options[:host] if options[:host]
+          settings = Settings.new(env: values)
+
+          if options[:show_config]
+            @output.puts JSON.pretty_generate(settings.public_config)
+            return 0
+          end
+          if options[:export]
+            path = Operations::SavedConfig.new(directory: settings.backup_directory)
+                                          .export(host: options[:export], output: options[:output], io: @output)
+            @output.puts JSON.generate(host: options[:export], output: path) if path
+            return 0
+          end
+
+          fleet = @fleet_factory.call(settings)
+          limit = options[:all] ? nil : options[:limit] || settings.limit_per_vendor(tftp: options[:tftp])
+          plan = if options[:tftp]
+                   fleet.plan_tftp_backup(limit_per_vendor: limit)
+                 else
+                   fleet.plan_backup(limit_per_vendor: limit)
+                 end
+          if options[:host]
+            host = IPAddr.new(options[:host]).to_s
+            raise ArgumentError, "host #{options[:host]} was not found in inventory" unless plan.inventory.any? { |device| device.host == host }
+          end
+          if options[:plan]
+            @output.puts JSON.pretty_generate(plan_summary(plan))
+            return 0
+          end
+
+          batch = if options[:tftp]
+                    fleet.tftp_backup_all(plan: plan, server: values.fetch("TFTP_HOST"),
+                                          concurrency: settings.concurrency,
+                                          vrfs: settings.tftp_vrfs,
+                                          source_files: settings.tftp_source_files)
+                  else
+                    fleet.backup_all(plan: plan, directory: settings.backup_directory,
+                                     concurrency: settings.concurrency)
+                  end
+          @output.puts JSON.pretty_generate(batch.summary.merge(report_location: batch.report_location,
+                                                                report_error: batch.report_error))
+          batch.success? ? 0 : 1
+        rescue OptionParser::ParseError, ArgumentError, KeyError, Errno::ENOENT,
+          Psych::Exception, JSON::ParserError, Client::Error => exception
+          @error.puts "net-connector-backup: #{exception.message}"
+          2
+        rescue StandardError => exception
+          @error.puts "net-connector-backup failed (#{exception.class})"
+          2
+        end
+
+        private
+
+        # 解析命令行参数并处理帮助及版本信息。
+        def parse_options
+          options = { config: @env["NET_CONNECTOR_CONFIG"] }
+          parser = OptionParser.new do |args|
+            args.banner = "Usage: net-connector-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
+            args.on("--config FILE", "Read non-secret YAML settings") { |value| options[:config] = value }
+            args.on("--show-config", "Print effective non-secret settings") { options[:show_config] = true }
+            args.on("--plan", "Preview selected inventory without device connections") { options[:plan] = true }
+            args.on("--tftp", "Use device-initiated TFTP backup") { options[:tftp] = true }
+            args.on("--export IP", "Export a saved local configuration") { |value| options[:export] = value }
+            args.on("--output FILE", "Write exported configuration to a private file") { |value| options[:output] = value }
+            args.on("--directory PATH", "Backup and report directory") { |value| options[:directory] = value }
+            args.on("--host IP", "Select one inventory device by management IP") { |value| options[:host] = value }
+            args.on("--concurrency N", Integer, "Maximum simultaneous devices") { |value| options[:concurrency] = value }
+            args.on("--limit-per-vendor N", Integer, "Select N devices per vendor (1..5)") do |value|
+              options[:limit] = value
+            end
+            args.on("--all", "Select all ready devices") { options[:all] = true }
+            args.on("-v", "--version", "Print version") do
+              @output.puts Net::Connector::VERSION
+              options[:done] = true
+            end
+            args.on("-h", "--help", "Show help") do
+              @output.puts args
+              options[:done] = true
+            end
+          end
+          parser.parse!(@argv)
+          raise OptionParser::InvalidOption, @argv.join(" ") unless @argv.empty?
+
+          options
+        end
+
+        # 拒绝互斥或缺少依赖的命令行选项。
+        def validate_options!(options)
+          modes = [:show_config, :plan, :export].count { |key| options[key] }
+          raise ArgumentError, "choose one of --show-config, --plan, or --export" if modes > 1
+          raise ArgumentError, "--output requires --export" if options[:output] && !options[:export]
+          raise ArgumentError, "--all and --limit-per-vendor cannot be combined" if options[:all] && options[:limit]
+          if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:concurrency] || options[:host])
+            raise ArgumentError, "--export cannot be combined with backup options"
+          end
+        end
+
+        # 整理备份计划供命令行预览。
+        def plan_summary(plan)
+          {
+            total: plan.inventory.size,
+            ready: plan.inventory.count(&:ready?),
+            selected: plan.selected.map do |device|
+              { host: device.host, name: device.name, connector: device.vendor,
+                filename: plan.mode == :backup ? device.backup_filename : device.tftp_filename }
+            end,
+            skipped: plan.outcomes.compact.group_by(&:status).transform_values(&:size)
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Net
+  module Connector
+    module Netdisco
+      # 独立于 Rails 的 Netdisco 设备清单客户端。
+      class Client
+        class Error < StandardError; end
+
+        class QueryRequired < Error; end
+
+        FIELDS = %w[ip name dns vendor os model os_ver serial].freeze
+        DEFAULT_MAX_PAGES = 10_000
+
+        # 校验 Netdisco 地址与凭据并建立请求入口。
+        def initialize(url:, username: nil, password: nil, api_key: nil, page_size: 500,
+                       max_pages: DEFAULT_MAX_PAGES, requester: nil)
+          @url = URI.parse(url.to_s)
+          unless @url.is_a?(URI::HTTP) && @url.host && !@url.userinfo && !@url.query && !@url.fragment
+            raise ArgumentError, "url must be an HTTP(S) base URL without credentials, query or fragment"
+          end
+          unless (api_key.nil? && present?(username) && present?(password)) ||
+                 (present?(api_key) && username.nil? && password.nil?)
+            raise ArgumentError, "provide either username and password or api_key"
+          end
+          if [username, password, api_key].compact.any? { |value| value.match?(/[\r\n]/) }
+            raise ArgumentError, "credentials must be single-line strings"
+          end
+          unless page_size.is_a?(Integer) && page_size.positive? && max_pages.is_a?(Integer) && max_pages.positive?
+            raise ArgumentError, "page_size and max_pages must be positive integers"
+          end
+
+          @username, @password, @api_key = username, password, api_key
+          @page_size, @max_pages = page_size, max_pages
+          @requester = requester || method(:default_request)
+        rescue URI::InvalidURIError
+          raise ArgumentError, "url is invalid", cause: nil
+        end
+
+        # 逐页获取并校验完整设备清单。
+        def devices
+          token = @api_key || authenticate
+          rows = []
+          seen_ips = {}
+          offset = 0
+          @max_pages.times do
+            uri = endpoint("api/v1/search/device")
+            uri.query = URI.encode_www_form(fields: FIELDS.join(","), limit: @page_size, offset: offset)
+            page = request_json(uri, authorized_get(uri, token), allow_empty: true)
+            validate_rows!(page)
+            return rows.uniq if page.empty?
+
+            raise Error, "Netdisco pagination did not advance" if page.all? { |row| seen_ips[row.fetch("ip")] }
+
+            page.each { |row| seen_ips[row.fetch("ip")] = true }
+            rows.concat(page)
+            offset += @page_size
+          end
+          raise Error, "Netdisco inventory exceeded max_pages"
+        rescue QueryRequired
+          legacy_devices(token)
+        end
+
+        # 仅显示服务地址，避免凭据进入调试输出。
+        def inspect = "#<#{self.class} url=#{@url.scheme}://#{@url.host}>"
+
+        private
+
+        # 在服务要求查询参数时使用兼容查询获取清单。
+        def legacy_devices(token)
+          uri = endpoint("api/v1/search/device")
+          uri.query = URI.encode_www_form(q: "%", seeallcolumns: true)
+          rows = request_json(uri, authorized_get(uri, token), allow_empty: true)
+          validate_rows!(rows)
+          rows.map { |row| row.slice(*FIELDS) }.uniq
+        end
+
+        # 使用账号密码登录并取得 API 密钥。
+        def authenticate
+          uri = endpoint("login")
+          request = ::Net::HTTP::Post.new(uri)
+          request.basic_auth(@username, @password)
+          data = request_json(uri, request)
+          token = data["api_key"] if data.is_a?(Hash)
+          raise Error, "Netdisco login did not return an API key" unless present?(token) && !token.match?(/[\r\n]/)
+
+          token
+        end
+
+        # 为清单查询建立带 API 密钥的请求。
+        def authorized_get(uri, token)
+          request = ::Net::HTTP::Get.new(uri)
+          request["Authorization"] = "Apikey #{token}"
+          request
+        end
+
+        # 以服务根地址构建 API 地址。
+        def endpoint(path)
+          uri = @url.dup
+          uri.path = "#{uri.path.chomp("/")}/#{path}"
+          uri
+        end
+
+        # 发起请求并将 HTTP 和 JSON 故障转换为客户端错误。
+        def request_json(uri, request, allow_empty: false)
+          request["Accept"] = "application/json"
+          response = @requester.call(uri, request)
+          body = response.body.to_s
+          if response.code == "400"
+            parsed = JSON.parse(body)
+            raise QueryRequired, "Netdisco requires a search query" if parsed.is_a?(Hash) && parsed["error"] == "Missing query"
+          end
+          raise Error, "Netdisco request failed (HTTP #{response.code})" unless response.is_a?(::Net::HTTPSuccess)
+          return [] if allow_empty && body.strip.empty?
+
+          JSON.parse(body)
+        rescue JSON::ParserError
+          raise Error, "Netdisco returned invalid JSON", cause: nil
+        rescue IOError, SystemCallError, Timeout::Error, SocketError, OpenSSL::SSL::SSLError => error
+          raise Error, "Netdisco connection failed (#{error.class})", cause: nil
+        end
+
+        # 使用标准库 HTTP 客户端发送请求。
+        def default_request(uri, request)
+          ::Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                            open_timeout: 10, read_timeout: 60, write_timeout: 10) { |http| http.request(request) }
+        end
+
+        # 校验清单的字段类型和设备地址。
+        def validate_rows!(rows)
+          valid = rows.is_a?(Array) && rows.all? do |row|
+            row.is_a?(Hash) && present?(row["ip"]) &&
+              FIELDS.drop(1).all? { |field| row[field].nil? || row[field].is_a?(String) }
+          end
+          raise Error, "Netdisco returned an invalid device inventory" unless valid
+        end
+
+        # 判断凭据字段是否为非空字符串。
+        def present?(value) = value.is_a?(String) && !value.strip.empty?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Net
+  module Connector
+    module Netdisco
+      # 命令行使用的无凭据 YAML 配置，环境变量优先。
+      class ConfigFile
+        FIELDS = {
+          "netdisco" => { "url" => ["NETDISCO_URL", :string],
+                          "page_size" => ["NETDISCO_PAGE_SIZE", :integer] },
+          "backup" => { "directory" => ["NET_CONNECTOR_BACKUP_DIRECTORY", :string],
+                        "concurrency" => ["NET_CONNECTOR_CONCURRENCY", :integer],
+                        "limit_per_vendor" => ["NET_CONNECTOR_SAMPLE_PER_VENDOR", :integer] },
+          "inventory" => { "include_hosts" => ["NET_CONNECTOR_INCLUDE_HOSTS", :list],
+                           "exclude_hosts" => ["NET_CONNECTOR_EXCLUDE_HOSTS", :list],
+                           "include_vendors" => ["NET_CONNECTOR_INCLUDE_VENDORS", :list],
+                           "vendor_overrides" => ["NET_CONNECTOR_VENDOR_OVERRIDES", :json],
+                           "host_overrides" => ["NET_CONNECTOR_HOST_OVERRIDES", :json],
+                           "device_rules" => ["NET_CONNECTOR_DEVICE_RULES", :json] },
+          "ssh" => { "protocol" => ["NET_CONNECTOR_PROTOCOL", :string],
+                     "known_hosts" => ["NET_CONNECTOR_KNOWN_HOSTS", :string],
+                     "host_key_policy" => ["NET_CONNECTOR_HOST_KEY_POLICY", :string],
+                     "log_directory" => ["NET_CONNECTOR_LOG_DIRECTORY", :string],
+                     "log_level" => ["NET_CONNECTOR_LOG_LEVEL", :string] },
+          "tftp" => { "server" => ["TFTP_HOST", :string],
+                      "vrfs" => ["NET_CONNECTOR_TFTP_VRFS", :json] }
+        }.freeze
+
+        # 安全读取 YAML 配置并映射到环境变量格式。
+        def self.load(path)
+          raise ArgumentError, "config path must be a nonempty String" unless path.is_a?(String) && !path.empty?
+
+          document = YAML.safe_load(File.read(path), permitted_classes: [], permitted_symbols: [], aliases: false)
+          raise ArgumentError, "config must be a YAML mapping" unless document.is_a?(Hash)
+
+          unknown_sections = document.keys - FIELDS.keys
+          raise ArgumentError, "unknown config sections: #{unknown_sections.join(", ")}" unless unknown_sections.empty?
+
+          document.each_with_object({}) do |(section, values), result|
+            fields = FIELDS.fetch(section)
+            raise ArgumentError, "#{section} must be a mapping" unless values.is_a?(Hash)
+
+            unknown = values.keys - fields.keys
+            raise ArgumentError, "unknown #{section} settings: #{unknown.join(", ")}" unless unknown.empty?
+
+            values.each do |name, value|
+              key, type = fields.fetch(name)
+              result[key] = encode(section, name, type, value)
+            end
+          end
+        rescue Psych::Exception => error
+          raise ArgumentError, "invalid YAML config (#{error.class})"
+        end
+
+        # 按字段类型校验并编码单项配置。
+        def self.encode(section, name, type, value)
+          case type
+          when :string
+            raise ArgumentError, "#{section}.#{name} must be a nonempty String" unless value.is_a?(String) && !value.strip.empty?
+
+            value
+          when :integer
+            raise ArgumentError, "#{section}.#{name} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+
+            value.to_s
+          when :list
+            unless value.is_a?(Array) && value.all? { |item| item.is_a?(String) && !item.empty? && !item.include?(",") }
+              raise ArgumentError, "#{section}.#{name} must be a list of strings without commas"
+            end
+
+            value.join(",")
+          when :json
+            expected = name == "device_rules" ? Array : Hash
+            raise ArgumentError, "#{section}.#{name} must be a #{expected}" unless value.is_a?(expected)
+
+            JSON.generate(value)
+          end
+        end
+
+        private_class_method :encode
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require_relative "../operations/saved_config"
+
+module Net
+  module Connector
+    module Netdisco
+      # 仅保存清单元数据，设备凭据由调用方管理。
+      Device = Data.define(:host, :source_ip, :name, :vendor, :source_vendor, :model, :os, :os_version, :serial, :issue) do
+        # 清单行来自可变的外部数据；设备快照不共享其中的字符串。
+        def initialize(*values, **attributes)
+          frozen_values = values.map { |value| value.is_a?(String) ? value.dup.freeze : value }
+          frozen_attributes = attributes.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }
+          super(*frozen_values, **frozen_attributes)
+        end
+
+        # 将 Netdisco 清单记录转换为可规划的设备对象。
+        def self.from_row(row, rules:)
+          valid = row.is_a?(Hash) && row["ip"].is_a?(String) && !row["ip"].empty? &&
+                  Client::FIELDS.drop(1).all? { |field| row[field].nil? || row[field].is_a?(String) }
+          raise Client::Error, "Netdisco returned an invalid device inventory" unless valid
+
+          source_ip = row.fetch("ip")
+          host = nil
+          issue = nil
+          begin
+            raise IPAddr::InvalidAddressError, "address includes a prefix" if source_ip.include?("/")
+
+            host = IPAddr.new(source_ip).to_s
+          rescue IPAddr::Error
+            issue = :invalid_address
+          end
+          vendor = rules.resolve(row)
+          issue ||= :unsupported_vendor unless vendor
+          issue ||= :filtered unless rules.selected?(host, vendor)
+          name = [row["name"], row["dns"]].find { |value| value && !value.strip.empty? }
+          new(host: host, source_ip: source_ip, name: name&.strip, vendor: vendor,
+              source_vendor: row["vendor"], model: row["model"], os: row["os"],
+              os_version: row["os_ver"], serial: row["serial"], issue: issue)
+        end
+
+        # 判断设备是否满足备份选择条件。
+        def ready? = issue.nil?
+
+        # 生成不随名称或厂商信息改变的本地文本文件名。
+        def backup_filename = Operations::SavedConfig.filename(host)
+
+        # 生成设备 CLI 可用的 ASCII 远端文件名。
+        def tftp_filename
+          return "running-config.xml" if vendor == :palo_alto
+
+          label = name.to_s.encode(Encoding::US_ASCII, invalid: :replace, undef: :replace, replace: "-")
+                      .gsub(/[^A-Za-z0-9._-]+/, "-").byteslice(0, 180)
+                      .gsub(/\A[._-]+|[._-]+\z/, "")
+          label = vendor&.to_s || "device" if label.empty?
+          extension = case vendor
+                      when :radware then "tgz"
+                      when :hillstone then "dat"
+                      else "cfg"
+                      end
+          TftpTarget.filename(host, extension: extension, label: label)
+        end
+
+        # 按厂商及设备地址实例化连接器。
+        def connector(**settings)
+          raise ArgumentError, "device is not ready: #{issue}" unless ready?
+          raise ArgumentError, "host cannot be overridden" if settings.key?(:host)
+
+          Net::Connector.build(vendor, host: host, **settings)
+        end
+      end
+    end
+  end
+end