net-connector 0.7.3 → 0.9.0

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

@@ -8,21 +8,20 @@ require_relative "../storage/private_file"
 module Net
   module Connector
     module Netdisco
+      # 调用方选择结果持久化方式；所有写入器接收同一份 Report，不再次执行设备任务。
       module ResultStore
         # 每批保存一份私有 JSON 报告，通过重命名防止半写文件。
         class Json
           # 以临时文件和重命名原子写入私有 JSON 报告。
-          def write(batch, directory:)
+          def write(report, 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"
+            filename = "netdisco-#{report.mode}-#{report.started_at.strftime("%Y%m%dT%H%M%SZ")}-#{SecureRandom.hex(4)}.json"
             path = File.join(destination, filename)
-            Storage::PrivateFile.write(path, JSON.pretty_generate(batch.summary)).path
+            Storage::PrivateFile.write(path, JSON.pretty_generate(report.summary)).path
           end
         end
 
-        Text = Json # Compatibility with the former name of the JSON writer.
-
         # 数据库仓储由调用方提供，可使用 Active Record 或其他对象。
         # 仓储须实现 create!，本项目不负责数据库表结构。
         class Database
@@ -34,8 +33,8 @@ module Net
           end
 
           # 把批量摘要写入调用方仓储并返回记录位置。
-          def write(batch, **_options)
-            record = @repository.create!(batch.summary)
+          def write(report, **_options)
+            record = @repository.create!(report.summary)
             record.respond_to?(:id) ? "database:#{record.id}" : "database"
           end
         end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "ipaddr"
+require_relative "../../connector"
 
 module Net
   module Connector
@@ -93,11 +94,13 @@ module Net
 
         # 根据地址、显式规则和厂商信息识别连接器。
         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 标记。
+          unless @host_overrides.empty?
+            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
           end
           label = normalize(row["vendor"])
           os = normalize(row["os"])

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

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../../connector"
+require_relative "client"
+require_relative "database_client"
+require_relative "config_file"
+require_relative "rules"
+require_relative "planner"
 
 module Net
   module Connector
@@ -10,21 +16,24 @@ module Net
         DEFAULT_BACKUP_DIRECTORY = "backups"
         DEFAULT_CONCURRENCY = 4
         MAX_CONCURRENCY = 50
-        ENVIRONMENT_KEYS = %w[NETDISCO_URL NC_BACKUP_DIRECTORY NC_CONCURRENCY NC_SAMPLE_PER_VENDOR
-                              NC_PROTOCOL NC_KNOWN_HOSTS NC_HOST_KEY_POLICY NC_LOG_DIRECTORY NC_LOG_LEVEL TFTP_HOST].freeze
+        # 这里只列可从环境读取的公开策略；凭据单独动态读取，其他内部键只供 YAML/CLI 使用。
+        ENVIRONMENT_KEYS = %w[ND_URL].freeze
         DEFAULT_PAGE_SIZE = Client::DEFAULTS.fetch(:page_size)
         UNSET = Object.new.freeze
         private_constant :UNSET
 
+        # 加载无凭据 YAML 作为默认策略，保留传入环境作为动态凭据来源。
         def self.from_file(path, env: ENV)
           new(env: env, defaults: ConfigFile.load(path))
         end
 
+        # 只有 NC_CONFIG 显式指定时才读取文件，不隐式加载 .env。
         def self.from_env(env: ENV)
           path = env["NC_CONFIG"]
           path && !path.empty? ? from_file(path, env: env) : new(env: env)
         end
 
+        # 分开保存默认策略、显式覆盖与凭据来源；fixed 实例只承载已复制的公开快照。
         def initialize(env: ENV, defaults: {}, overrides: {}, policy: nil, fixed: false)
           @env, @defaults, @overrides = env, defaults, overrides
           @policy, @fixed = policy, fixed
@@ -32,7 +41,14 @@ module Net
 
         # 调用入口补充运行目录等非敏感覆盖，凭据仍从同一来源读取。
         def with_overrides(values)
-          self.class.new(env: @env, defaults: @defaults, overrides: @overrides.merge(values))
+          if @fixed
+            public_values = @env.merge(@overrides).merge(values).slice(*non_secret_keys)
+                                .transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+            return self.class.new(env: public_values, fixed: true).freeze
+          end
+
+          policy = @policy.with_overrides(values) if @policy
+          self.class.new(env: @env, defaults: @defaults, overrides: @overrides.merge(values), policy: policy)
         end
 
         # 快照自身不保留 ENV、凭据 resolver 或原 Settings 的引用，不能携带秘密进入摘要。
@@ -55,6 +71,7 @@ module Net
           self.class.new(env: @env, defaults: @defaults, overrides: @overrides, policy: snapshot(mode: mode))
         end
 
+        # 按业务模式预检所有策略；离线导出仅验证目录，不读取清单或设备凭据。
         def validate!(mode:)
           unless %i[backup tftp inventory show_config export].include?(mode)
             raise ArgumentError, "unknown settings validation mode"
@@ -67,7 +84,9 @@ module Net
           concurrency
           limit_per_vendor
           log_directory
+          tftp_root
           connection_options
+          database_options
           Net::Connector.vendors.each { |vendor| connection_options(vendor) }
           tftp_source_files.each_value { |source| TftpTarget.validate_source_file!(source) }
           tftp_vrfs
@@ -75,6 +94,7 @@ module Net
           self
         end
 
+        # 用固定策略创建清单客户端，但每次读取最新身份凭据；显式认证覆盖默认认证来源。
         def client(policy: snapshot(mode: :inventory), credentials: nil)
           if credentials && (!credentials.is_a?(Hash) || credentials.keys.sort != %i[password username] ||
             !credentials.values.all? { |value| present?(value) })
@@ -82,28 +102,29 @@ module Net
           end
           options = policy.client_options
           if policy.inventory_source == :postgres
-            connection = DatabaseClient::CONNECTION_ENV.each_with_object({}) do |(key, name), values|
+            connection = DatabaseClient::CONNECTION_ENV.each_with_object(policy.database_options.dup) do |(key, name), values|
               item = secret_value(name)
               values[key] = item if item
             end
             connection.merge!(user: credentials[:username], password: credentials[:password]) if credentials
             return DatabaseClient.new(connection_options: connection, **options)
           end
-          raise ArgumentError, "NETDISCO_URL is required" unless options.fetch(:url)
+          raise ArgumentError, "ND_URL is required" unless options.fetch(:url)
 
           authentication = if credentials
                              credentials
-                           elsif (token = secret_value("NETDISCO_API_KEY"))
+                           elsif (token = secret_value("ND_API_KEY"))
                              { api_key: token }
                            else
-                             { username: required_secret("NETDISCO_USERNAME"), password: required_secret("NETDISCO_PASSWORD") }
+                             { username: required_secret("ND_USERNAME"), password: required_secret("ND_PASSWORD") }
                            end
           Client.new(**options, **authentication)
         end
 
+        # 清单来源来自 YAML/CLI，HTTP 与 PostgreSQL 共用后续计划和执行接口。
         def inventory_source
-          source = value("NETDISCO_SOURCE") || "http"
-          raise ArgumentError, "NETDISCO_SOURCE must be http or postgres" unless %w[http postgres].include?(source)
+          source = value("ND_SOURCE") || "http"
+          raise ArgumentError, "ND_SOURCE must be http or postgres" unless %w[http postgres].include?(source)
 
           source.to_sym
         end
@@ -115,6 +136,7 @@ module Net
           inventory_source == :postgres ? postgres_options(options) : http_options(options)
         end
 
+        # 将筛选和映射策略交给 Rules 校验，未识别设备由清单结果单独标记。
         def rules
           Rules.new(include_hosts: list("NC_INCLUDE_HOSTS"),
                     exclude_hosts: list("NC_EXCLUDE_HOSTS"),
@@ -124,6 +146,7 @@ module Net
                     mappings: json("NC_DEVICE_RULES", []))
         end
 
+        # 将备份目录解析为绝对路径；这里只校验配置，不创建目录。
         def backup_directory
           path = raw("NC_BACKUP_DIRECTORY", DEFAULT_BACKUP_DIRECTORY)
           raise ArgumentError, "NC_BACKUP_DIRECTORY must be nonempty" unless present?(path)
@@ -131,6 +154,7 @@ module Net
           File.expand_path(path)
         end
 
+        # 与 Worker 共用并发上限，非法值在任务与目录创建前失败。
         def concurrency
           count = integer("NC_CONCURRENCY", DEFAULT_CONCURRENCY)
           raise ArgumentError, "NC_CONCURRENCY must be at most #{MAX_CONCURRENCY}" if count > MAX_CONCURRENCY
@@ -138,6 +162,7 @@ module Net
           count
         end
 
+        # 显式 nil 表示全量；tftp: true 且未设置时采用五台上限，示例入口另外选择全量。
         def limit_per_vendor(tftp: false)
           count = if configured?("NC_SAMPLE_PER_VENDOR")
                     integer("NC_SAMPLE_PER_VENDOR", 5) unless raw("NC_SAMPLE_PER_VENDOR").nil?
@@ -148,6 +173,7 @@ module Net
           count
         end
 
+        # 华为批次默认上传 startup.cfg；H3C 省略源文件时由设备策略探测。
         def tftp_source_files
           files = { huawei: raw("NC_HUAWEI_TFTP_SOURCE_FILE", "flash:/startup.cfg") }
           %i[h3c h3c_wireless].each do |vendor|
@@ -157,6 +183,7 @@ module Net
           files
         end
 
+        # 按厂商读取 VRF 映射，不能把不支持 VRF 的厂商静默忽略。
         def tftp_vrfs
           mapping = json("NC_TFTP_VRFS", {})
           raise ArgumentError, "NC_TFTP_VRFS must be a JSON object" unless mapping.is_a?(Hash)
@@ -164,6 +191,7 @@ module Net
           self.class.validate_vrfs!(mapping.transform_keys(&:to_sym))
         end
 
+        # 只允许 NX-OS、山石的安全单一 VRF 名称，禁止命令拼接字符。
         def self.validate_vrfs!(vrfs)
           unless vrfs.is_a?(Hash) && vrfs.all? { |vendor, name|
             %i[cisco_nxos hillstone].include?(vendor) && name.is_a?(String) &&
@@ -174,8 +202,32 @@ module Net
           vrfs
         end
 
-        def tftp_server = value("TFTP_HOST")
+        # 服务器地址只来自 YAML/CLI 的公开策略，不从 NC_TFTP_HOST 环境变量读取。
+        def tftp_server = value("NC_TFTP_HOST")
+
+        # 本机核验根目录属于策略快照，解析路径不证明文件已经上传。
+        def tftp_root
+          path = value("NC_TFTP_ROOT")
+          File.expand_path(path) if path
+        end
+
+        # 端口、TLS 与连接超时进入固定策略；主机、数据库名和登录凭据仍从环境读取。
+        def database_options
+          options = {}
+          %i[port connect_timeout].each do |name|
+            key = "ND_DB_#{name.to_s.upcase}"
+            next unless configured?(key)
 
+            options[name] = integer(key, nil)
+          end
+          %i[sslmode sslrootcert].each do |name|
+            item = value("ND_DB_#{name.to_s.upcase}")
+            options[name] = item if item
+          end
+          DatabaseClient.connection_policy(**options)
+        end
+
+        # 经 Configuration 复用连接校验；厂商协议覆盖通用协议，不包含设备凭据。
         def connection_options(vendor = nil)
           configuration = Configuration.new(
             protocol: vendor_protocols[vendor.to_s] || value("NC_PROTOCOL") || "ssh",
@@ -188,6 +240,7 @@ module Net
           options.freeze
         end
 
+        # 厂商协议必须使用已登记的厂商键和 ssh/telnet，不接受未知映射。
         def vendor_protocols
           values = json("NC_VENDOR_PROTOCOLS", {})
           unless values.is_a?(Hash) && values.all? { |vendor, protocol| Net::Connector.vendors.map(&:to_s).include?(vendor) && %w[ssh telnet].include?(protocol) }
@@ -196,6 +249,7 @@ module Net
           values
         end
 
+        # 每台任务读取最新厂商凭据，缺失字段回退到通用凭据；无用户名时跳过设备。
         def device_credentials_for(device)
           prefix = "NC_#{device.vendor.to_s.upcase}_"
           username = secret_value(prefix + "USERNAME") || secret_value("NC_DEVICE_USERNAME")
@@ -206,11 +260,13 @@ module Net
             enable_password: secret_value(prefix + "ENABLE_PASSWORD") || secret_value("NC_ENABLE_PASSWORD") }
         end
 
+        # 会话日志目录属于公开策略；调用方和批次入口负责实际创建。
         def log_directory
           path = value("NC_LOG_DIRECTORY")
           File.expand_path(path) if path
         end
 
+        # 生成已验证的无凭据配置摘要，不展开原环境或 resolver。
         def public_config
           snapshot(mode: :show_config).config_hash
         end
@@ -219,9 +275,10 @@ module Net
 
         protected
 
+        # 只输出公开策略；数据库身份和设备凭据不得通过配置摘要进入报告。
         def config_hash
           {
-            netdisco: client_options.merge(source: inventory_source),
+            netdisco: client_options.merge(source: inventory_source, database: database_options),
             backup: { directory: backup_directory, concurrency: concurrency, limit_per_vendor: limit_per_vendor },
             inventory: { include_hosts: list("NC_INCLUDE_HOSTS"),
                          exclude_hosts: list("NC_EXCLUDE_HOSTS"),
@@ -233,10 +290,11 @@ module Net
               log_directory: log_directory,
               vendor_protocols: vendor_protocols
             ),
-            tftp: { server: tftp_server, vrfs: tftp_vrfs.transform_keys(&:to_s), source_files: tftp_source_files }
+            tftp: { server: tftp_server, verification_root: tftp_root, vrfs: tftp_vrfs.transform_keys(&:to_s), source_files: tftp_source_files }
           }
         end
 
+        # 优先读取固定策略或显式覆盖；内部键的名称不表示该键可由进程环境配置。
         def raw(key, default = nil)
           return @policy.raw(key, default) if @policy
           return @overrides.fetch(key) if @overrides.key?(key)
@@ -254,7 +312,7 @@ module Net
 
         def client_budget_options(defaults)
           defaults.to_h do |name, default|
-            key = "NETDISCO_#{name.to_s.upcase}"
+            key = "ND_#{name.to_s.upcase}"
             parsed = case name
                      when :inventory_timeout then number(key, default)
                      when :allow_insecure_http then boolean(key, default)
@@ -265,16 +323,16 @@ module Net
         end
 
         def postgres_options(options)
-          query = value("NETDISCO_QUERY") || (raise ArgumentError, "NETDISCO_QUERY is required for postgres")
-          DatabaseClient.options(query: query, query_params: json("NETDISCO_QUERY_PARAMS", []), **options)
+          query = value("ND_QUERY") || (raise ArgumentError, "ND_QUERY is required for postgres")
+          DatabaseClient.options(query: query, query_params: json("ND_QUERY_PARAMS", []), **options)
         end
 
         def http_options(options)
-          if value("NETDISCO_QUERY") || value("NETDISCO_QUERY_PARAMS")
-            raise ArgumentError, "SQL query settings require NETDISCO_SOURCE=postgres"
+          if value("ND_QUERY") || value("ND_QUERY_PARAMS")
+            raise ArgumentError, "SQL query settings require ND_SOURCE=postgres"
           end
           options = Client.options(**options)
-          url = value("NETDISCO_URL")
+          url = value("ND_URL")
           Client.validate_url!(url, allow_insecure_http: options.fetch(:allow_insecure_http)) if url
           options.merge(url: url).freeze
         end
@@ -283,11 +341,16 @@ module Net
           ConfigFile::FIELDS.values.flat_map { |section| section.values.map(&:first) }
         end
 
+        # 旧前缀和已移除策略明确报错；错误只包含变量名，不泄露变量值。
         def validate_environment!
           legacy = @env.keys.find { |key| key.start_with?("NET_CONNECTOR_") }
-          raise ArgumentError, "#{legacy} has been renamed to #{legacy.sub("NET_CONNECTOR_", "NC_")}" if legacy
+          raise ArgumentError, "#{legacy} is unsupported; use NC_ credentials or YAML via NC_CONFIG" if legacy
+
+          legacy = @env.keys.find { |key| key.start_with?("NETDISCO_", "TFTP_") }
+          raise ArgumentError, "#{legacy} is unsupported; use ND_ credentials or YAML via NC_CONFIG" if legacy
 
           removed = non_secret_keys - ENVIRONMENT_KEYS
+          removed << "NC_PROGRESS"
           removed += Net::Connector.vendors.map { |vendor| "NC_#{vendor.to_s.upcase}_PROTOCOL" }
           key = removed.find { |name| @env.key?(name) }
           raise ArgumentError, "#{key} is no longer an environment setting; use YAML via NC_CONFIG or CLI options" if key
@@ -343,6 +406,7 @@ module Net
           result if present?(result)
         end
 
+        # 凭据只从活的环境映射读取并复制，不允许 defaults/overrides 充当秘密来源。
         def secret_value(key)
           result = @env[key]
           raise ArgumentError, "#{key} must be a String" unless result.nil? || result.is_a?(String)

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

@@ -2,10 +2,12 @@
 
 require "fileutils"
 require "tempfile"
+require "digest"
 require_relative "../storage/backup_lock"
 require_relative "../storage/private_file"
 require_relative "../storage/safe_file"
 require_relative "tftp_verification"
+require_relative "diagnostic"
 
 module Net
   module Connector
@@ -15,6 +17,7 @@ module Net
         BATCH_DIRECTORY_NAME = /\A\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}(?:_\d{2})?\z/
         private_constant :BATCH_DIRECTORY_NAME
 
+        # 固定名上传无法保留历史时，在设备上传之前拒绝执行。
         class Unavailable < Net::Connector::Error
           def initialize(host: nil)
             super("a local TFTP root is required to retain a fixed-name upload", code: :tftp_history_unavailable,
@@ -22,6 +25,7 @@ module Net
           end
         end
 
+        # 设备可能已经上传，归档失败不能撤销或重新执行设备命令。
         class ArchiveFailed < Net::Connector::Error
           def initialize(host: nil)
             super("the uploaded file could not be retained in the batch", code: :tftp_archive_failed,
@@ -38,6 +42,7 @@ module Net
           @verifier = TftpVerification.new(root: @server_root)
         end
 
+        # 有本机根目录时保留原名并归档；远端服务器使用批次后缀避免重复覆盖。
         def upload_filename(device)
           name = device.tftp_filename
           return name if @server_root || device.vendor == :palo_alto
@@ -48,6 +53,7 @@ module Net
           TftpTarget.validate_path!("#{stem.byteslice(0, TftpTarget::MAX_PATH_BYTES - suffix.bytesize)}#{suffix}")
         end
 
+        # 上传与归档在同一目标锁内完成，后续失败仍保留可确认的上传回执和提交路径。
         def upload_and_archive(device, started_at:)
           raise Unavailable.new(host: device.host) if device.vendor == :palo_alto && !@server_root
 
@@ -69,9 +75,6 @@ module Net
           end
         end
 
-        alias path_for upload_filename
-        alias capture upload_and_archive
-
         private
 
         # 文件系统的 mtime 可能落后于 Time.now；用同一服务器目录的时间建立上传边界。

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../storage/safe_file"
+require_relative "../device/tftp/receipt"
 
 module Net
   module Connector

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "settings"
+
 module Net
   module Connector
     module Netdisco
@@ -58,7 +60,7 @@ module Net
               threads.each do |thread|
                 begin
                   thread.join
-                rescue Exception # rubocop:disable Lint/RescueException -- Preserve the original interruption after all workers stop.
+                rescue Exception # rubocop:disable Lint/RescueException -- 等待全部工作线程停止，不让收尾异常覆盖原中断。
                   nil
                 end
               end

data/lib/net/connector/netdisco.rb

@@ -1,25 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../connector"
-require_relative "netdisco/client"
-require_relative "netdisco/database_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/progress"
+# 公共入口只组合应用流程；每个模块自行声明依赖，不要求调用方维护加载顺序。
 require_relative "netdisco/cli"
-require_relative "storage/batch_directory"
-require_relative "netdisco/report/text"
-require_relative "netdisco/connection"
-require_relative "netdisco/cli/options"
-require_relative "netdisco/report/files"
-require_relative "netdisco/tftp_verification"
-require_relative "netdisco/tftp_archive"
-require_relative "netdisco/tftp_history"
 require_relative "netdisco/backup_run"

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

@@ -18,8 +18,12 @@ module Net
 
           def committed? = state != :not_committed
           def durable? = state == :durable
+
+          # 阶段更新仍校验状态并冻结路径，Ruby 3.2 也不能绕过初始化约束。
+          def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
         end
 
+        # 写入失败仍携带阶段与提交回执，调用方据此区分未替换和已替换文件。
         class WriteError < IOError
           attr_reader :receipt, :code, :underlying_type
 
@@ -41,8 +45,10 @@ module Net
           def inspect = "#<#{self.class} state=#{receipt.state} phase=#{receipt.phase}>"
         end
 
+        # 替换已经提交后的持久化或收尾失败，不能按尚未写入处理。
         class PersistenceError < WriteError; end
 
+        # 目录同步能力缺失只表示持久性未确认，已替换的目标文件仍然保留。
         class DirectorySyncUnsupported < WriteError
           def initialize(**options)
             super

data/lib/net/connector/vendor/cisco_ios/running_config.rb

@@ -5,6 +5,7 @@ require_relative "../../device/running_config/strategy"
 module Net
   module Connector
     module CiscoIos
+      # 清理 IOS 响应头，保留 banner 和配置正文内的命令、时间等原始内容。
       class RunningConfig < Net::Connector::RunningConfig::Rendered
         # 每条命令已有独立响应；正文中的命令示例属于配置，不能按会话回显删除。
         # 只清理首个配置语句之前的时间注释，避免改写 banner 等多行文本。

data/lib/net/connector/vendor/cisco_ios/tftp_backup.rb

@@ -5,6 +5,7 @@ require_relative "../../device/tftp/strategy"
 module Net
   module Connector
     module CiscoIos
+      # 通过交互复制运行配置，以设备的复制完成行确认上传。
       class TftpBackup < Tftp::Strategy
         # 在连接前拒绝当前厂商不支持的参数组合。
         def validate_options!(_target, source_file:, vrf: nil)
@@ -12,6 +13,7 @@ module Net
           raise ArgumentError, "Cisco IOS TFTP backup does not use vrf" unless vrf.nil?
         end
 
+        # 声明本厂商实际导出的配置种类与格式，不推断服务器文件已核验。
         def receipt_metadata(_target, **) = { configuration_kind: :running, format: :cfg }
 
         # 构造当前厂商的 TFTP 导出交互脚本。

data/lib/net/connector/vendor/cisco_ios/topology.rb

@@ -5,6 +5,7 @@ require_relative "../../device/topology/immediate_strategy"
 module Net
   module Connector
     module CiscoIos
+      # 基于 CDP 证据规划接口描述，变更后读回确认，再执行独立保存阶段。
       class Topology < Topology::ImmediateStrategy
         # IOS 提供 CDP 邻居、配置描述读取和描述变更。
         def self.supports?(capability)
@@ -26,6 +27,7 @@ module Net
         # 先回到执行视图读回，随后才执行档案中的保存命令。
         def leave_configuration_commands = ["end"]
 
+        # 只认可本厂商明确的保存完成行，设备提示符返回本身不能证明持久化。
         def persistence_pattern = /\A(?:\[OK\]|Copy complete\.)\z/i
 
         # 每个 Device ID 表示一条应由模板解析的邻居记录。

data/lib/net/connector/vendor/cisco_nxos/tftp_backup.rb

@@ -5,12 +5,14 @@ require_relative "../../device/tftp/strategy"
 module Net
   module Connector
     module CiscoNxos
+      # 在指定 VRF 上传 NX-OS 运行配置，默认使用 management。
       class TftpBackup < Tftp::Strategy
         # 在连接前拒绝当前厂商不支持的参数组合。
         def validate_options!(_target, source_file:, **)
           raise ArgumentError, "Cisco NX-OS does not use source_file" unless source_file.nil?
         end
 
+        # 声明本厂商实际导出的配置种类与格式，不推断服务器文件已核验。
         def receipt_metadata(_target, **) = { configuration_kind: :running, format: :cfg }
 
         # 构造当前厂商的 TFTP 导出交互脚本。

data/lib/net/connector/vendor/h3c/tftp_backup.rb

@@ -5,6 +5,7 @@ require_relative "../../device/tftp/file_upload"
 module Net
   module Connector
     module H3c
+      # 未指定源文件时探测 H3C 启动配置，显式文件不推断配置种类。
       class TftpBackup < Tftp::FileUpload
         # 自动探测选择的是启动配置；显式文件仍不能推断为运行或启动配置。
         def receipt_metadata(target, source_file:, explicit_source:)

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

@@ -5,6 +5,7 @@ require_relative "../../device/topology/immediate_strategy"
 module Net
   module Connector
     module H3c
+      # 适配 H3C LLDP 表头与接口视图，数量核对失败时禁止继续规划变更。
       class Topology < Topology::ImmediateStrategy
         TABLE_HEADER = /^\s*(?:System Name\s+Local Interface\b|(?:Local Interface|LocalIf)\s+)/i
         # H3C 提供 LLDP 邻居、配置描述读取和描述变更。
@@ -24,6 +25,7 @@ module Net
         # 返回用户视图读回；保存交给后续独立阶段。
         def leave_configuration_commands = ["return"]
 
+        # 只认可本厂商明确的保存完成行，设备提示符返回本身不能证明持久化。
         def persistence_pattern = /\ASaved the current configuration to mainboard device successfully\.\z/i
 
         # H3C 不同版本的列顺序不同，按表头选对应模板。

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

@@ -5,6 +5,7 @@ require_relative "../../device/running_config/strategy"
 module Net
   module Connector
     module Hillstone
+      # 山石配置保持原始文本，仅删除已识别的退格分页痕迹。
       class RunningConfig < Net::Connector::RunningConfig::Strategy
         # 去掉山石 CLI 用退格控制符绘制的分页痕迹。
         def clean(text) = text.gsub(/\x00?\x08+[ \t]+\x08+/, "")

data/lib/net/connector/vendor/hillstone/tftp_backup.rb

@@ -5,6 +5,7 @@ require_relative "../../device/tftp/strategy"
 module Net
   module Connector
     module Hillstone
+      # 导出山石启动配置，并从完成行确认设备实际使用的 dat 文件名。
       class TftpBackup < Tftp::Strategy
         # 山石原生导出的配置文件使用 dat 扩展名。
         def self.file_extension = "dat"
@@ -17,6 +18,7 @@ module Net
           raise ArgumentError, "Hillstone TFTP filename cannot contain a directory"
         end
 
+        # 声明本厂商实际导出的配置种类与格式，不推断服务器文件已核验。
         def receipt_metadata(target, **)
           { configuration_kind: :startup, format: :dat, requested_path: target.explicit_path? ? target.path : nil }
         end

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

@@ -5,6 +5,7 @@ require_relative "../../device/topology/immediate_strategy"
 module Net
   module Connector
     module Hillstone
+      # 核对山石 LLDP 数据与总数，接口描述读回一致后才保存配置。
       class Topology < Topology::ImmediateStrategy
         # 山石提供 LLDP 邻居、配置描述读取和描述变更。
         def self.supports?(capability)
@@ -23,6 +24,7 @@ module Net
         # 退出配置视图后先读回，保存动作随后单独执行。
         def leave_configuration_commands = ["exit"]
 
+        # 只认可本厂商明确的保存完成行，设备提示符返回本身不能证明持久化。
         def persistence_pattern = /\ASaving configuration is finished\.?\z/i
 
         # 用数据行和设备报告的总数交叉核对，避免遗漏邻居。

data/lib/net/connector/vendor/huawei/tftp_backup.rb

@@ -5,6 +5,7 @@ require_relative "../../device/tftp/file_upload"
 module Net
   module Connector
     module Huawei
+      # 上传调用方明确指定的华为保存文件，连接前拒绝缺少源文件的请求。
       class TftpBackup < Tftp::FileUpload
         # 缺少源文件也必须在首次设备 I/O 之前拒绝。
         def validate_options!(target, source_file:, vrf: nil)
@@ -12,7 +13,7 @@ module Net
           raise ArgumentError, "Huawei TFTP backup requires source_file" if source_file.nil?
         end
 
-        # 要求调用方提供合法的华为启动配置文件路径。
+        # 读取调用方明确指定的合法保存文件路径，不根据文件名推断为启动配置。
         def resolve_source_file(value)
           raise ArgumentError, "Huawei TFTP backup requires source_file" unless value