net-connector 0.4.2 → 0.5.0

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

@@ -18,7 +18,7 @@ module Net
           @client = client
           @rules = rules
           @credentials = credentials
-          @connector_factory = connector_factory || ->(device, connection_settings) { device.connector(**connection_settings) }
+          @connector_factory = connector_factory || ->(device, connection_settings) { device.build_connector(**connection_settings) }
           @result_store = result_store
           raise ArgumentError, "credentials must respond to call" if @credentials && !@credentials.respond_to?(:call)
           raise ArgumentError, "result_store must respond to write" if result_store && !result_store.respond_to?(:write)
@@ -42,8 +42,8 @@ module Net
         # 先拉取完整清单，再并发采集并保存设备配置。
         def backup_all(directory: DEFAULT_SETTING, concurrency: DEFAULT_SETTING,
                        limit_per_vendor: nil, plan: nil, on_start: nil, on_result: nil, on_change: nil,
-                       success_policy: :strict, report_schema: nil)
-          reporting = Report.options(policy: success_policy, schema: report_schema)
+                       success_policy: :strict)
+          reporting = Report.validate_policy!(success_policy)
           policy = @settings.snapshot(mode: :backup)
           directory = policy.backup_directory if directory.equal?(DEFAULT_SETTING)
           concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
@@ -59,19 +59,18 @@ module Net
           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)
-          saved_config = Operations::SavedConfig.new(directory: target_directory, indexed: true)
           run_batch(:backup, plan, concurrency: concurrency, report_directory: directory,
                     output_directory: target_directory, policy: policy, reporting: reporting,
                     on_start: on_start, on_result: callbacks.compact) do |device, log_directory|
-            backup_one(device, target_directory, log_directory, policy, saved_config)
+            backup_one(device, target_directory, log_directory, policy)
           end
         end
 
         # 让设备主动导出配置，在执行前检查同批目标文件名冲突。
         def tftp_backup_all(server:, source_files: {}, concurrency: DEFAULT_SETTING,
                             limit_per_vendor: 5, vrfs: {}, on_start: nil, on_result: nil, plan: nil,
-                            report_directory: DEFAULT_SETTING, success_policy: :strict, report_schema: nil)
-          reporting = Report.options(policy: success_policy, schema: report_schema)
+                            report_directory: DEFAULT_SETTING, success_policy: :strict)
+          reporting = Report.validate_policy!(success_policy)
           policy = @settings.snapshot(mode: :tftp)
           concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
           report_directory = policy.backup_directory if report_directory.equal?(DEFAULT_SETTING)
@@ -121,15 +120,13 @@ module Net
           log_directory = policy.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|
+                                       on_error: ->(device, error) { build_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)
-          if reporting.fetch(:schema) == 2
-            batch = Report.new(batch, policy: reporting.fetch(:policy), duration_ms: ((monotonic - started) * 1000).round)
-          end
+          batch = Report.new(batch, policy: reporting, duration_ms: ((monotonic - started) * 1000).round)
           save_report(batch, directory: report_directory)
         end
 
@@ -145,16 +142,12 @@ module Net
           return batch unless @result_store
 
           batch.with(report_location: @result_store.write(batch, directory: directory))
-        rescue Operations::PrivateFile::WriteError => error
+        rescue Storage::PrivateFile::WriteError => error
           # 报告也可能已经原子替换；保留已知位置，不将持久性失败误写成完全没有产物。
-          location = error.receipt.path if Operations::PrivateFile.receipt_error?(error) && error.receipt.committed?
-          return batch.with_report_error(error, location: location) if batch.instance_of?(Report)
-
-          batch.with(report_location: location, report_error: error.class.name)
+          location = error.receipt.path if Storage::PrivateFile.receipt_error?(error) && error.receipt.committed?
+          batch.with_report_error(error, location: location)
         rescue StandardError => error
-          return batch.with_report_error(error) if batch.instance_of?(Report)
-
-          batch.with(report_error: error.class.name)
+          batch.with_report_error(error)
         end
 
         # 确认传入计划属于当前备份模式。
@@ -165,7 +158,7 @@ module Net
         end
 
         # 构造包含错误类型的单台设备结果。
-        def outcome(device, status, backup: nil, error: nil)
+        def build_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, diagnostic: Diagnostic.from(error, backup: backup))
@@ -174,7 +167,7 @@ module Net
         # 执行单台设备的 TFTP 导出。
         def tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
           run_one(device, log_directory, policy, success_status: :reported_uploaded,
-                  close_error_status: :reported_with_error, backup_class: TftpBackup) do |connector|
+                  close_error_status: :reported_with_error, backup_class: TftpReceipt) 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)
@@ -183,27 +176,21 @@ module Net
         end
 
         # 执行单台设备的本地配置采集。
-        def backup_one(device, directory, log_directory, policy, saved_config)
+        def backup_one(device, directory, log_directory, policy)
           destination = File.join(directory, device.backup_filename)
-          Operations::BackupLock.synchronize(destination, host: device.host) do |path_lock|
-            previous = saved_config.fingerprint(device.host, required: false)
-            previous_digest = previous.sha256 if previous && previous.path != destination
-            result = run_one(device, log_directory, policy, success_status: :backed_up,
-                             close_error_status: :saved_with_error, backup_class: Backup) do |connector|
-              path_lock.delegate { connector.backup(path: destination) }
+          Storage::BackupLock.synchronize(destination, host: device.host) do |path_lock|
+            Storage::SafeFile.open(destination, missing: true) { |_file, _stat| nil }
+            run_one(device, log_directory, policy, success_status: :backed_up,
+                    close_error_status: :saved_with_error, backup_class: Backup) do |connector|
+              path_lock.with_delegated_lock { connector.backup(path: destination) }
             end
-            backup = result.backup
-            next result unless backup.is_a?(Backup) && backup.change == :created && previous_digest
-
-            result.with(backup: backup.with(previous_sha256: previous_digest,
-                                           change: backup.sha256 == previous_digest ? :unchanged : :changed))
           end
         end
 
         # 隔离单台设备的凭据、连接、操作和关闭异常。
         def run_one(device, log_directory, policy, success_status:, close_error_status:, backup_class:)
           connection_settings = @credentials ? @credentials.call(device) : @settings.device_credentials_for(device)
-          return outcome(device, :missing_credentials) if connection_settings.nil?
+          return build_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)
@@ -217,11 +204,11 @@ module Net
           end
           connector = @connector_factory.call(device, connection_settings)
           backup, failure = perform_one(connector, backup_class) { yield connector }
-          return outcome(device, success_status, backup: backup) unless failure
+          return build_outcome(device, success_status, backup: backup) unless failure
 
-          outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
+          build_outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
         rescue StandardError => error
-          outcome(device, :failed, error: error)
+          build_outcome(device, :failed, error: error)
         end
 
         # 仅信任库定义且产物类型匹配的提交后错误；普通第三方异常上的 backup 字段不代表完成。
@@ -237,8 +224,8 @@ module Net
             failure = error
             if backup_class == Backup && error.instance_of?(BackupPersistenceError) && error.backup.instance_of?(Backup)
               backup = error.backup
-            elsif backup_class == TftpBackup && error.instance_of?(TftpCompletionError) && error.transfer.instance_of?(TftpBackup)
-              backup = error.transfer
+            elsif backup_class == TftpReceipt && error.instance_of?(TftpCompletionError) && error.receipt.instance_of?(TftpReceipt)
+              backup = error.receipt
             end
           ensure
             begin

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

@@ -6,7 +6,7 @@ require_relative "batch"
 module Net
   module Connector
     module Netdisco
-      # v2 显式包装旧 Batch；成功策略与清单覆盖分开，默认 Batch JSON 不增加字段。
+      # 唯一的批量报告契约，分开呈现成功策略、清单覆盖和受控诊断。
       class Report
         extend Forwardable
         SUCCESS = %i[backed_up reported_uploaded].freeze
@@ -17,19 +17,14 @@ module Net
         attr_reader :batch, :policy, :duration_ms, :report_diagnostic
         def_delegators :@batch, *Batch.members, :success?, :status, :counts
 
-        # selected 必须使用带策略和覆盖信息的 v2；默认 strict 继续使用旧 schema。
-        def self.options(policy: :strict, schema: nil)
+        def self.validate_policy!(policy)
           raise ArgumentError, "success_policy must be strict or selected" unless %i[strict selected].include?(policy)
 
-          schema = policy == :selected ? 2 : 1 if schema.nil?
-          raise ArgumentError, "report_schema must be 1 or 2" unless schema.is_a?(Integer) && [1, 2].include?(schema)
-          raise ArgumentError, "selected success policy requires report schema 2" if policy == :selected && schema != 2
-
-          { policy: policy, schema: schema }.freeze
+          policy
         end
 
         def initialize(batch, policy: :strict, duration_ms: nil, report_diagnostic: nil)
-          self.class.options(policy: policy, schema: 2)
+          self.class.validate_policy!(policy)
           raise ArgumentError, "report requires a Batch" unless batch.instance_of?(Batch)
           unless duration_ms.nil? || (duration_ms.is_a?(Numeric) && duration_ms.real? && duration_ms.finite? && duration_ms >= 0)
             raise ArgumentError, "duration_ms must be nonnegative and finite"
@@ -42,7 +37,7 @@ module Net
           freeze
         end
 
-        # 旧 success?/status 委托给 Batch；新策略绝不把未知状态当作可忽略跳过。
+        # 严格完成情况与所选成功策略分别保留，未知状态不能当作可忽略跳过。
         def policy_success?
           return batch.success? if policy == :strict
           return false unless callback_errors.empty? && report_error.nil?
@@ -62,17 +57,17 @@ module Net
                           policy: policy, duration_ms: duration_ms, report_diagnostic: diagnostic)
         end
 
-        # 复用旧业务数据，但重新白名单化所有诊断字段，包括手工构造的旧 Batch。
+        # 手工构造的批次同样经过诊断白名单，不序列化任意异常内容。
         def summary
-          legacy = batch.summary
-          legacy.merge(
+          data = batch_summary
+          data.merge(
             schema_version: 2, policy: policy, policy_success: policy_success?, duration_ms: duration_ms,
             coverage: { complete: !outcomes.empty? && outcomes.all? { |item| ATTEMPTED.include?(item.status) },
                         attempted: outcomes.count { |item| ATTEMPTED.include?(item.status) },
                         skipped: outcomes.count { |item| !ATTEMPTED.include?(item.status) } },
-            devices: device_summaries(legacy.fetch(:devices)),
-            callback_errors: callback_errors.map { |entry| { host: entry[:host], error_type: Diagnostic.type(entry[:error_type]) } },
-            report_location: report_location, report_error: Diagnostic.type(report_error),
+            devices: device_summaries(data.fetch(:devices)),
+            callback_errors: callback_errors.map { |entry| { host: entry[:host], error_type: ErrorMetadata.type(entry[:error_type]) } },
+            report_location: report_location, report_error: ErrorMetadata.type(report_error),
             report_diagnostic: report_diagnostic&.to_h
           )
         end
@@ -81,6 +76,32 @@ module Net
 
         private
 
+        # 生成可写入报告及供命令行展示的结构化摘要。
+        def batch_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
+
         def device_summaries(entries)
           entries.zip(outcomes).map do |entry, item|
             diagnostic = item.diagnostic || Diagnostic.new(error_code: item.error_code, error_type: item.error_type)

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

@@ -3,7 +3,7 @@
 require "json"
 require "fileutils"
 require "securerandom"
-require_relative "../operations/private_file"
+require_relative "../storage/private_file"
 
 module Net
   module Connector
@@ -17,7 +17,7 @@ module Net
             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))
+            Storage::PrivateFile.write(path, JSON.pretty_generate(batch.summary)).path
           end
         end
 

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

@@ -164,12 +164,6 @@ module Net
           options.freeze
         end
 
-        # 兼容原入口；Fleet 传入本批策略，独立调用则读取当前策略和当前秘密。
-        def credentials_for(device, policy: snapshot(mode: :backup))
-          credentials = device_credentials_for(device)
-          policy.connection_options(device.vendor).merge(credentials) if credentials
-        end
-
         def device_credentials_for(device)
           prefix = "NET_CONNECTOR_#{device.vendor.to_s.upcase}_"
           username = secret_value(prefix + "USERNAME") || secret_value("NET_CONNECTOR_DEVICE_USERNAME")

data/lib/net/connector/{operations → storage}/backup_lock.rb

@@ -7,7 +7,7 @@ module Net
   module Connector
     class BackupBusy < Error; end
 
-    module Operations
+    module Storage
       # 路径锁在设备采集之前取得；锁文件长期保留，避免等待者落在已经删除的 inode 上。
       class BackupLock
         STORAGE_KEY = :net_connector_backup_delegation
@@ -61,7 +61,7 @@ module Net
         end
 
         # 仅持有实际 flock 的同一 Fiber 可授权一次内层采集，避免把路径锁变成任意可重入锁。
-        def delegate
+        def with_delegated_lock
           raise ThreadError, "backup path delegation requires lock ownership" unless @owner == [Process.pid, Fiber.current]
 
           previous = Thread.current[STORAGE_KEY]

data/lib/net/connector/{operations → storage}/private_file.rb

@@ -4,7 +4,7 @@ require "tempfile"
 
 module Net
   module Connector
-    module Operations
+    module Storage
       # 文件同步和目录项同步分别记录；原子可见不等于断电后仍能恢复新目录项。
       module PrivateFile
         Receipt = Data.define(:path, :state, :phase) do
@@ -62,13 +62,8 @@ module Net
           [WriteError, PersistenceError, DirectorySyncUnsupported].any? { |type| error.instance_of?(type) }
         end
 
-        # 保留原路径返回值；失败时可从异常 receipt 判断目录项是否已经替换。
+        # 统一返回写入回执；失败时从异常 receipt 判断目录项是否已经替换。
         def self.write(path, contents)
-          write_receipt(path, contents)
-          path
-        end
-
-        def self.write_receipt(path, contents)
           raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?
 
           receipt = Receipt.new(path: File.expand_path(path), state: :not_committed, phase: :resolve_parent)

data/lib/net/connector/{operations → storage}/safe_file.rb

@@ -4,7 +4,7 @@ require "digest"
 
 module Net
   module Connector
-    module Operations
+    module Storage
       # 对同一 FD 做类型检查和读取；NOFOLLOW 只保护最后一个路径分量，目录由调用方保护。
       module SafeFile
         Fingerprint = Data.define(:path, :sha256, :mode, :dev, :ino)

data/lib/net/connector/{operations → storage}/saved_config.rb

@@ -4,11 +4,10 @@ require "fileutils"
 require "ipaddr"
 require_relative "private_file"
 require_relative "safe_file"
-require_relative "saved_config/legacy_index"
 
 module Net
   module Connector
-    module Operations
+    module Storage
       # 直接导出已有本地配置，无需访问 Netdisco。
       class SavedConfig
         # 只用规范化的管理地址标识配置，避免设备改名改变备份身份。
@@ -20,16 +19,14 @@ module Net
           raise ArgumentError, "host must be an IP address"
         end
 
-        # 默认每次实时查找；批次显式 indexed 时共享一份惰性的旧命名文件快照。
-        def initialize(directory:, indexed: false)
+        # 只读取规范设备地址对应的文件，不维护第二套历史文件命名。
+        def initialize(directory:)
           raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty?
-          raise ArgumentError, "indexed must be true or false" unless [true, false].include?(indexed)
 
           @directory = File.expand_path(directory).freeze
-          @legacy_index = LegacyIndex.new(@directory) if indexed
         end
 
-        # 优先查找固定文件名；仅在不存在时兼容唯一的旧命名文件。
+        # 从同一已验证文件描述符取得路径或内容。
         def find(host, required: true)
           with_file(host, required: required) { |path, _file, _stat| path }
         end
@@ -43,34 +40,12 @@ module Net
           with_file(host) { |_path, file, _stat| file.read }
         end
 
-        def resolve_path(host, required:)
-          filename = self.class.filename(host)
-          path = File.join(@directory, filename)
-          unless File.exist?(path) || File.symlink?(path)
-            entries = if @legacy_index
-                        @legacy_index.candidates(filename)
-                      else
-                        Dir.children(@directory).select { |name| name.end_with?("-#{filename}") }
-                      end
-            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 = @legacy_index ? entries.first : File.join(@directory, entries.first)
-          end
-          path
-        end
-
         def with_file(host, required: true)
-          path = resolve_path(host, required: required)
-          return nil unless path
-          return @legacy_index.open(path) { |name, file, stat| yield name, file, stat } if path.is_a?(LegacyIndex::Entry)
-
-          SafeFile.open(path) { |file, stat| yield path, file, stat }
+          path = File.join(@directory, self.class.filename(host))
+          SafeFile.open(path, missing: !required) { |file, stat| yield path, file, stat }
         end
 
-        private :resolve_path, :with_file
+        private :with_file
 
         # 将已保存配置写入目标文件或标准输出。
         def export(host:, output: nil, io: $stdout)
@@ -81,7 +56,7 @@ module Net
             destination = File.expand_path(output)
             directory = File.dirname(destination)
             FileUtils.mkdir_p(directory, mode: 0o700)
-            PrivateFile.write(destination, contents)
+            PrivateFile.write(destination, contents).path
           else
             io.binmode if io.respond_to?(:binmode)
             io.write(contents)
@@ -91,9 +66,9 @@ module Net
 
         # 使用指定模板解析已有配置，无需访问设备或 Netdisco。
         def parse(host:, template:, template_dir: nil)
-          require_relative "parse_output"
+          require_relative "../textfsm"
 
-          parser = ParseOutput.new(template_dir: template_dir)
+          parser = TextFSM.new(template_dir: template_dir)
           parser.call(read(host), template: template, host: host)
         end
       end

data/lib/net/connector/storage.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    # 文件存储不依赖设备连接；备份、离线导出和批量报告共享这些原语。
+    module Storage
+      autoload :BackupLock, File.expand_path("storage/backup_lock", __dir__)
+      autoload :PrivateFile, File.expand_path("storage/private_file", __dir__)
+      autoload :SafeFile, File.expand_path("storage/safe_file", __dir__)
+      autoload :SavedConfig, File.expand_path("storage/saved_config", __dir__)
+    end
+
+    autoload :BackupBusy, File.expand_path("storage/backup_lock", __dir__)
+  end
+end

data/lib/net/connector/textfsm.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "engine/errors"
+require_relative "engine/terminal_text"
+
+module Net
+  module Connector
+    # 将设备命令回显或配置文本按 TextFSM 模板转换为结构化记录。
+    class TextFSM
+      # 设备入口与功能实现共置，Base 只组合能力，不重复业务流程。
+      module Capability
+        # 执行命令并按厂商、命令或显式 TextFSM 模板返回结构化记录。
+        def parse_command(command, template: nil, template_dir: nil)
+          parser = TextFSM.new(template_dir: template_dir)
+          parser.call(execute_command(command).value!, template: template, vendor: vendor, command: command, host: host)
+        end
+
+        # 采集运行配置并使用指定 TextFSM 模板提取结构化记录。
+        def parse_config(template:, template_dir: nil)
+          parser = TextFSM.new(template_dir: template_dir)
+          parser.call(running_config.value!, template: template, host: host)
+        end
+      end
+
+      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)
+        require "textfsm"
+
+        text = TerminalText.render(text, host: host)
+        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

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

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/tftp/strategy"
+require_relative "../../device/tftp/strategy"
 
 module Net
   module Connector
     module CiscoIos
-      class TftpBackup < Operations::Tftp::Strategy
+      class TftpBackup < Tftp::Strategy
         # 在连接前拒绝当前厂商不支持的参数组合。
         def validate_options!(_target, source_file:, vrf: nil)
           raise ArgumentError, "Cisco IOS does not use source_file" unless source_file.nil?
@@ -28,7 +28,7 @@ module Net
         end
 
         # 检查设备回显是否确认 TFTP 传输完成。
-        def complete?(result)
+        def device_reported_complete?(result)
           completion_lines(result).any? do |line|
             copied_bytes?(line) || line.match?(/\A\[OK(?:\s*-\s*[1-9]\d*\s+bytes)?\]\z/i)
           end

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

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/topology/immediate_strategy"
+require_relative "../../device/topology/immediate_strategy"
 
 module Net
   module Connector
     module CiscoIos
-      class Topology < Operations::Topology::ImmediateStrategy
+      class Topology < Topology::ImmediateStrategy
         # IOS 提供 CDP 邻居、配置描述读取和描述变更。
         def self.supports?(capability)
           %i[neighbors interface_descriptions interface_description_changes].include?(capability)
@@ -21,10 +21,10 @@ module Net
         def protocol = :cdp
 
         # 进入全局配置视图。
-        def enter_configuration = "configure terminal"
+        def enter_configuration_command = "configure terminal"
 
         # 先回到执行视图读回，随后才执行档案中的保存命令。
-        def leave_configuration = ["end"]
+        def leave_configuration_commands = ["end"]
 
         def persistence_pattern = /\A(?:\[OK\]|Copy complete\.)\z/i
 
@@ -40,7 +40,7 @@ module Net
 
         # 复用公共接口描述命令，保留本机接口原名。
         def change_commands(change)
-          InterfaceDescription.commands(interface: change.interface, description: change.new_description)
+          Net::Connector::Topology::InterfaceDescription.commands(interface: change.interface, description: change.new_description)
         end
       end
     end

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

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/tftp/strategy"
+require_relative "../../device/tftp/strategy"
 
 module Net
   module Connector
     module CiscoNxos
-      class TftpBackup < Operations::Tftp::Strategy
+      class TftpBackup < Tftp::Strategy
         # 在连接前拒绝当前厂商不支持的参数组合。
         def validate_options!(_target, source_file:, **)
           raise ArgumentError, "Cisco NX-OS does not use source_file" unless source_file.nil?
@@ -27,7 +27,7 @@ module Net
         end
 
         # 检查设备回显是否确认 TFTP 传输完成。
-        def complete?(result)
+        def device_reported_complete?(result)
           completion_lines(result).any? do |line|
             line.match?(/\A
               (?:transfer|copy)(?:\s+operation)?\s+

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

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/tftp/file_upload"
+require_relative "../../device/tftp/file_upload"
 
 module Net
   module Connector
     module H3c
-      class TftpBackup < Operations::Tftp::FileUpload
+      class TftpBackup < Tftp::FileUpload
         # 自动探测选择的是启动配置；显式文件仍不能推断为运行或启动配置。
         def receipt_metadata(target, source_file:, explicit_source:)
           super.merge(configuration_kind: explicit_source ? :saved_file : :startup)
         end
 
         # 选取并校验 H3C 启动配置文件路径。
-        def source_file(value)
+        def resolve_source_file(value)
           return TftpTarget.validate_source_file!(value) if value
 
-          output = @device.execute("display startup").value!
+          output = @device.execute_command("display startup").value!
           rendered = TerminalRenderer.render(output)
           path = rendered[/^\s*Next main startup saved-configuration file:\s*(\S+)/i, 1]
           path ||= rendered[/^\s*Current startup saved-configuration file:\s*(\S+)/i, 1]