net-connector 0.4.0 → 0.4.2

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

@@ -172,8 +172,9 @@ module Net
 
       # 采集配置并以原子方式保存为私有文件。
       # 采集失败时保留已有备份文件。
-      def backup(path:)
-        Operations::LocalBackup.new(self).call(path: path)
+      def backup(path:, lock_timeout: 0)
+        @session.assert_path_lock_order!(:backup)
+        Operations::LocalBackup.new(self).call(path: path, lock_timeout: lock_timeout)
       end
 
       # 要求设备直接向 TFTP 服务器导出原生配置。
@@ -182,6 +183,11 @@ module Net
         Operations::TftpBackup.new(self).call(host: host, path: path, source_file: source_file, vrf: vrf)
       end
 
+      # 明确请求来源、格式及设备报告等级；旧入口继续返回原有三字段对象。
+      def tftp_backup_receipt(host:, path: nil, source_file: nil, vrf: nil)
+        Operations::TftpBackup.new(self).call_receipt(host: host, path: path, source_file: source_file, vrf: vrf)
+      end
+
       # 配置采集是设备的基础能力，两个公共入口共享同一流程。
       def collect_config = RunningConfig.new(self).call
 
@@ -325,6 +331,7 @@ module Net
         @config_strategy_scope = previous
       end
 
+      # 只允许当前 Fiber 复用采集中的策略；离线调用创建独立策略。
       def config_strategy
         scope = @config_strategy_scope
         scope && scope.first.equal?(Fiber.current) ? scope.last : RunningConfig.strategy(self)
@@ -355,10 +362,11 @@ module Net
                                   prepare: method(:prepare_command), after_command: finish_step, prompt: prompt)
         execution.context[:operation] = operation if operation
         execution.context[:privilege] = privilege
+        output_sensitive = script.any?(&:output_sensitive?)
         @session.perform(:script) do
-          before_batch(execution)
+          @session.output_scope(output_sensitive) { before_batch(execution) }
           result = execution.execute(script, &on_step)
-          finalize ? finalize.call(result) : result
+          @session.output_scope(output_sensitive) { finalize ? finalize.call(result) : result }
         end
       rescue Error => error
         Result.new(steps: execution ? execution.steps : [], error: error)

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

@@ -6,6 +6,7 @@ module Net
   module Connector
     # 描述文本与常见接口视图命令的纯构造方法，不连接或修改设备。
     module InterfaceDescription
+      # 将邻居名称和接口拼成默认描述；只缩写邻居接口，保留原始大小写。
       def self.format(neighbor, abbreviate: true, lowercase: false)
         port = if abbreviate
                  InterfaceName.short(neighbor.neighbor_interface, lowercase: lowercase)
@@ -15,6 +16,7 @@ module Net
         validate!("To #{neighbor.neighbor_name} #{port}")
       end
 
+      # 生成进入接口、设置描述和退出视图的命令，不执行设备操作。
       def self.commands(interface:, description:, leave: "exit")
         validate_interface!(interface)
         validate!(description)
@@ -31,6 +33,7 @@ module Net
         raise ArgumentError, "description must be 1-80 bytes of plain interface text"
       end
 
+      # 拒绝可能把描述命令拆成多条命令的不安全接口名。
       def self.validate_interface!(value)
         return value if value.is_a?(String) && value.match?(/\A[A-Za-z][A-Za-z0-9.\/-]*\z/)
 

data/lib/net/connector/device/profile/builder.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Profile
+      # 构造器把声明块中的领域语言转换为设备档案字段。
+      class Builder
+        # 保存继承值并提供 commands、prompts 等有限的声明入口。
+        def initialize(parent)
+          @values = parent.to_h
+        end
+
+        # 声明运行配置和保存配置命令。
+        def commands(&definition)
+          check_block!(:commands, definition)
+          commands = Commands.new(
+            @values[:config_commands], @values[:save_commands]
+          )
+          commands.instance_eval(&definition)
+          @values[:config_commands] = commands.config_commands
+          @values[:save_commands] = commands.save_commands
+          self
+        end
+
+        # 声明登录、命令、凭据和提权提示符。
+        def prompts(&definition)
+          check_block!(:prompts, definition)
+          Prompts.new(@values).instance_eval(&definition)
+          self
+        end
+
+        # 声明分页模式及自动翻页响应。
+        def pager(&definition)
+          check_block!(:pager, definition)
+          Pager.new(@values).instance_eval(&definition)
+          self
+        end
+
+        # 声明认证失败和命令失败的输出模式。
+        def errors(&definition)
+          check_block!(:errors, definition)
+          Errors.new(@values).instance_eval(&definition)
+          self
+        end
+
+        # 声明登录挑战和命令确认交互。
+        def interactions(&definition)
+          check_block!(:interactions, definition)
+          interactions = Interactions.new(@values)
+          interactions.instance_eval(&definition)
+          @values[:login_interactions] = interactions.login_interactions
+          @values[:confirmation_interactions] = interactions.confirmation_interactions
+          self
+        end
+
+        # 声明进入特权模式所需的命令和提示符。
+        def privilege(&definition)
+          check_block!(:privilege, definition)
+          Privilege.new(@values).instance_eval(&definition)
+          self
+        end
+
+        # 声明旧版 SSH 协商参数。
+        def ssh(&definition)
+          check_block!(:ssh, definition)
+          Ssh.new(@values).instance_eval(&definition)
+          self
+        end
+
+        # 设置设备命令的默认超时秒数。
+        def command_timeout(seconds)
+          @values[:command_timeout] = seconds
+          self
+        end
+
+        # 设置避免设备自动换行的终端宽高。
+        def terminal_size(width, height = nil)
+          @values[:terminal_size] = height.nil? ? width : [width, height]
+          self
+        end
+
+        # 绑定已加载的策略类；nil 明确关闭继承的业务能力。
+        def tftp_strategy(klass)
+          @values[:tftp_strategy] = klass
+          self
+        end
+
+        # 指定运行配置采集策略，覆盖继承的厂商规则。
+        def running_config_strategy(klass)
+          @values[:running_config_strategy] = klass
+          self
+        end
+
+        # 指定邻居发现和描述下发策略，nil 表示关闭能力。
+        def topology_strategy(klass)
+          @values[:topology_strategy] = klass
+          self
+        end
+
+        # 将声明字段校验并构造成不可变档案。
+        def build = Profile.new(**@values)
+
+        private
+
+        # 块式声明入口必须有明确的子 DSL，避免静默忽略配置。
+        def check_block!(name, definition)
+          raise ArgumentError, "#{name} requires a block" unless definition
+        end
+
+        # 命令集合的声明对象。
+        class Commands
+          attr_reader :config_commands, :save_commands
+
+          # 复制继承的命令，后续修改不会污染父类档案。
+          def initialize(config_commands, save_commands)
+            @config_commands = config_commands&.dup
+            @save_commands = save_commands.dup
+          end
+
+          # 声明读取运行配置的命令序列。
+          def running_config(*commands)
+            @config_commands = commands.flatten
+          end
+
+          # 声明保存配置的命令序列。
+          def save_config(*commands)
+            @save_commands = commands.flatten
+          end
+        end
+
+        # 提示符的声明对象。
+        class Prompts
+          # 将登录、命令、用户名、密码和特权提示写入当前档案。
+          def initialize(values)
+            @values = values
+          end
+
+          # 声明登录结束提示符。
+          def login(pattern) = @values[:login_prompt] = pattern
+
+          # 声明普通命令结束提示符。
+          def command(pattern) = @values[:command_prompt] = pattern
+
+          # 声明用户名输入提示。
+          def username(pattern) = @values[:username_prompt] = pattern
+
+          # 声明密码输入提示。
+          def password(pattern) = @values[:password_prompt] = pattern
+
+          # 声明特权模式提示符。
+          def privilege(pattern) = @values[:privilege_prompt] = pattern
+        end
+
+        # 分页规则的声明对象。
+        class Pager
+          # 将分页模式和响应写入当前档案。
+          def initialize(values)
+            @values = values
+          end
+
+          # 声明分页提示匹配模式。
+          def pattern(value) = @values[:pager_pattern] = value
+
+          # 声明匹配分页提示后发送的字节。
+          def response(value) = @values[:pager_response] = value
+        end
+
+        # 设备错误模式的声明对象。
+        class Errors
+          # 将错误模式列表写入当前档案。
+          def initialize(values)
+            @values = values
+          end
+
+          # 替换认证失败模式列表。
+          def authentication(*patterns)
+            @values[:authentication_error_patterns] = patterns.flatten
+          end
+
+          # 替换命令失败模式列表。
+          def command(*patterns)
+            @values[:command_error_patterns] = patterns.flatten
+          end
+        end
+
+        # 登录和命令交互的声明对象。
+        class Interactions
+          attr_reader :login_interactions, :confirmation_interactions
+
+          # 复制继承的交互规则，子类可以在其上追加设备差异。
+          def initialize(values)
+            @login_interactions = values[:login_interactions].dup
+            @confirmation_interactions = values[:confirmation_interactions].dup
+          end
+
+          # 声明登录阶段的一次性应答。
+          def login(pattern, response:, sensitive: false, limit: 1, capture: true)
+            @login_interactions << Interaction.new(pattern, response, sensitive: sensitive,
+                                                   limit: limit, capture: capture)
+          end
+
+          # 声明命令阶段的确认应答。
+          def confirm(pattern, response:, sensitive: false, limit: nil, capture: true)
+            @confirmation_interactions << Interaction.new(pattern, response, sensitive: sensitive,
+                                                          limit: limit, capture: capture)
+          end
+        end
+
+        # 特权认证规则的声明对象。
+        class Privilege
+          # 将特权命令和结束提示写入当前档案。
+          def initialize(values)
+            @values = values
+          end
+
+          # 声明进入特权模式的设备命令。
+          def command(value) = @values[:privilege_command] = value
+
+          # 声明特权命令完成后的提示符。
+          def prompt(value) = @values[:privilege_prompt] = value
+        end
+
+        # SSH 兼容参数的声明对象。
+        class Ssh
+          # 将旧版 SSH 参数写入当前档案。
+          def initialize(values)
+            @values = values
+          end
+
+          # 声明连接旧版设备所需的参数序列。
+          def legacy_arguments(*arguments) = @values[:legacy_ssh_arguments] = arguments.flatten
+        end
+      end
+    end
+  end
+end

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

@@ -110,233 +110,6 @@ module Net
           "save_commands=#{save_commands.size}>"
       end
 
-      # 构造器把声明块中的领域语言转换为设备档案字段。
-      class Builder
-        # 保存继承值并提供 commands、prompts 等有限的声明入口。
-        def initialize(parent)
-          @values = parent.to_h
-        end
-
-        # 声明运行配置和保存配置命令。
-        def commands(&definition)
-          check_block!(:commands, definition)
-          commands = Commands.new(
-            @values[:config_commands], @values[:save_commands]
-          )
-          commands.instance_eval(&definition)
-          @values[:config_commands] = commands.config_commands
-          @values[:save_commands] = commands.save_commands
-          self
-        end
-
-        # 声明登录、命令、凭据和提权提示符。
-        def prompts(&definition)
-          check_block!(:prompts, definition)
-          Prompts.new(@values).instance_eval(&definition)
-          self
-        end
-
-        # 声明分页模式及自动翻页响应。
-        def pager(&definition)
-          check_block!(:pager, definition)
-          Pager.new(@values).instance_eval(&definition)
-          self
-        end
-
-        # 声明认证失败和命令失败的输出模式。
-        def errors(&definition)
-          check_block!(:errors, definition)
-          Errors.new(@values).instance_eval(&definition)
-          self
-        end
-
-        # 声明登录挑战和命令确认交互。
-        def interactions(&definition)
-          check_block!(:interactions, definition)
-          interactions = Interactions.new(@values)
-          interactions.instance_eval(&definition)
-          @values[:login_interactions] = interactions.login_interactions
-          @values[:confirmation_interactions] = interactions.confirmation_interactions
-          self
-        end
-
-        # 声明进入特权模式所需的命令和提示符。
-        def privilege(&definition)
-          check_block!(:privilege, definition)
-          Privilege.new(@values).instance_eval(&definition)
-          self
-        end
-
-        # 声明旧版 SSH 协商参数。
-        def ssh(&definition)
-          check_block!(:ssh, definition)
-          Ssh.new(@values).instance_eval(&definition)
-          self
-        end
-
-        # 设置设备命令的默认超时秒数。
-        def command_timeout(seconds)
-          @values[:command_timeout] = seconds
-          self
-        end
-
-        # 设置避免设备自动换行的终端宽高。
-        def terminal_size(width, height = nil)
-          @values[:terminal_size] = height.nil? ? width : [width, height]
-          self
-        end
-
-        # 绑定已加载的策略类；nil 明确关闭继承的业务能力。
-        def tftp_strategy(klass)
-          @values[:tftp_strategy] = klass
-          self
-        end
-
-        def running_config_strategy(klass)
-          @values[:running_config_strategy] = klass
-          self
-        end
-
-        def topology_strategy(klass)
-          @values[:topology_strategy] = klass
-          self
-        end
-
-        # 将声明字段校验并构造成不可变档案。
-        def build = Profile.new(**@values)
-
-        private
-
-        # 块式声明入口必须有明确的子 DSL，避免静默忽略配置。
-        def check_block!(name, definition)
-          raise ArgumentError, "#{name} requires a block" unless definition
-        end
-
-        # 命令集合的声明对象。
-        class Commands
-          attr_reader :config_commands, :save_commands
-
-          # 复制继承的命令，后续修改不会污染父类档案。
-          def initialize(config_commands, save_commands)
-            @config_commands = config_commands&.dup
-            @save_commands = save_commands.dup
-          end
-
-          # 声明读取运行配置的命令序列。
-          def running_config(*commands)
-            @config_commands = commands.flatten
-          end
-
-          # 声明保存配置的命令序列。
-          def save_config(*commands)
-            @save_commands = commands.flatten
-          end
-        end
-
-        # 提示符的声明对象。
-        class Prompts
-          # 将登录、命令、用户名、密码和特权提示写入当前档案。
-          def initialize(values)
-            @values = values
-          end
-
-          # 声明登录结束提示符。
-          def login(pattern) = @values[:login_prompt] = pattern
-
-          # 声明普通命令结束提示符。
-          def command(pattern) = @values[:command_prompt] = pattern
-
-          # 声明用户名输入提示。
-          def username(pattern) = @values[:username_prompt] = pattern
-
-          # 声明密码输入提示。
-          def password(pattern) = @values[:password_prompt] = pattern
-
-          # 声明特权模式提示符。
-          def privilege(pattern) = @values[:privilege_prompt] = pattern
-        end
-
-        # 分页规则的声明对象。
-        class Pager
-          # 将分页模式和响应写入当前档案。
-          def initialize(values)
-            @values = values
-          end
-
-          # 声明分页提示匹配模式。
-          def pattern(value) = @values[:pager_pattern] = value
-
-          # 声明匹配分页提示后发送的字节。
-          def response(value) = @values[:pager_response] = value
-        end
-
-        # 设备错误模式的声明对象。
-        class Errors
-          # 将错误模式列表写入当前档案。
-          def initialize(values)
-            @values = values
-          end
-
-          # 追加认证失败模式。
-          def authentication(*patterns)
-            @values[:authentication_error_patterns] = patterns.flatten
-          end
-
-          # 追加命令失败模式。
-          def command(*patterns)
-            @values[:command_error_patterns] = patterns.flatten
-          end
-        end
-
-        # 登录和命令交互的声明对象。
-        class Interactions
-          attr_reader :login_interactions, :confirmation_interactions
-
-          # 复制继承的交互规则，子类可以在其上追加设备差异。
-          def initialize(values)
-            @login_interactions = values[:login_interactions].dup
-            @confirmation_interactions = values[:confirmation_interactions].dup
-          end
-
-          # 声明登录阶段的一次性应答。
-          def login(pattern, response:, sensitive: false, limit: 1, capture: true)
-            @login_interactions << Interaction.new(pattern, response, sensitive: sensitive,
-                                                   limit: limit, capture: capture)
-          end
-
-          # 声明命令阶段的确认应答。
-          def confirm(pattern, response:, sensitive: false, limit: nil, capture: true)
-            @confirmation_interactions << Interaction.new(pattern, response, sensitive: sensitive,
-                                                          limit: limit, capture: capture)
-          end
-        end
-
-        # 特权认证规则的声明对象。
-        class Privilege
-          # 将特权命令和结束提示写入当前档案。
-          def initialize(values)
-            @values = values
-          end
-
-          # 声明进入特权模式的设备命令。
-          def command(value) = @values[:privilege_command] = value
-
-          # 声明特权命令完成后的提示符。
-          def prompt(value) = @values[:privilege_prompt] = value
-        end
-
-        # SSH 兼容参数的声明对象。
-        class Ssh
-          # 将旧版 SSH 参数写入当前档案。
-          def initialize(values)
-            @values = values
-          end
-
-          # 声明连接旧版设备所需的参数序列。
-          def legacy_arguments(*arguments) = @values[:legacy_ssh_arguments] = arguments.flatten
-        end
-      end
-
       private
 
       # 校验静态接口，不构造策略实例或触发设备 I/O。
@@ -444,3 +217,5 @@ module Net
     end
   end
 end
+
+require_relative "profile/builder"

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

@@ -6,10 +6,13 @@ module Net
   module Connector
     class RunningConfig
       class Strategy
+        # 保存策略所属设备，供提示符和厂商校验使用。
         def initialize(device) = @device = device
 
+        # 默认保留设备响应原文。
         def clean(text) = text
 
+        # 默认取脚本最后一个完成步骤作为运行配置。
         def result_step(result) = result.steps.last
 
         # 普通采集命令保持视图不变；需要切换视图的采集策略显式调整。
@@ -17,11 +20,13 @@ module Net
           TerminalRenderer.render(@device.current_prompt.to_s).lines.last.to_s.strip
         end
 
+        # 公共策略不增加逐命令响应检查。
         def check_response(_command, _response, _execution) end
       end
 
       # 使用终端行编辑规则渲染 H3C、Huawei 和 Radware 配置。
       class Rendered < Strategy
+        # 应用终端行编辑规则，还原设备最终显示的配置文本。
         def clean(text) = TerminalRenderer.render(text)
       end
     end

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

@@ -12,6 +12,7 @@ module Net
         @device = device
       end
 
+      # 从设备档案选定本次采集策略；无厂商规则时使用公共策略。
       def self.strategy(device)
         (device.profile.running_config_strategy || Strategy).new(device)
       end
@@ -21,6 +22,8 @@ module Net
         script = Script.new(@device.config_commands)
         return Result.new(error: incomplete("configuration collection has no commands")) if script.empty?
 
+        # 所有厂商的采集步骤都收紧输出边界，包括候选差异、模式切换及扩展查询。
+        script = Script.new(script.map(&:with_output_sensitive))
         strategy = self.class.strategy(@device)
         prompt = ->(command) { prompt_for(command, strategy) }
         @device.execute_operation(script, name: :running_config, prompt: prompt,
@@ -33,6 +36,7 @@ module Net
 
       private
 
+      # 只从完成的配置步骤提取非空内容，并保留此前所有步骤。
       def finish(result)
         step = @device.send(:config_result_step, result)
         raise incomplete("configuration collection has no completed configuration step") unless step
@@ -44,6 +48,7 @@ module Net
         Result.new(steps: result.steps, config: content)
       end
 
+      # 用当前完整提示符构建结束匹配，避免配置正文中的单个 # 提前结束采集。
       def prompt_for(command, strategy)
         return command.prompt if command.prompt
 
@@ -54,6 +59,7 @@ module Net
         /(?:\A|(?<=[\r\n]))[ \t\x00]*#{Regexp.escape(prompt)}[ \t\x00]*[\r\n]*\z/
       end
 
+      # 排除命令回显和提示符，确认响应确实包含配置正文。
       def content?(step)
         body = TerminalRenderer.render(step.output.delete_suffix(step.prompt.to_s)).strip
         lines = body.lines
@@ -61,6 +67,7 @@ module Net
         !lines.join.strip.empty?
       end
 
+      # 将缺少配置的情况统一映射为可识别的设备错误码。
       def incomplete(message)
         DeviceError.new(message, code: :incomplete_configuration, host: @device.host, phase: :collect)
       end

data/lib/net/connector/engine/command.rb

@@ -11,7 +11,8 @@ module Net
       attr_reader :text, :timeout, :interactions, :prompt, :source, :line
 
       # 在任何输入输出前校验命令、提示、交互和敏感标记，并冻结命令。
-      def initialize(text, timeout: nil, interactions: [], prompt: nil, sensitive: false, source: nil, line: nil)
+      def initialize(text, timeout: nil, interactions: [], prompt: nil, sensitive: false, output_sensitive: false,
+                     source: nil, line: nil)
         unless text.is_a?(String) && !text.strip.empty? && !text.match?(/[\r\n\x00]/)
           raise ScriptError.new("a command must contain exactly one nonempty CLI line", phase: :parse,
                                 source: source, line: line)
@@ -24,12 +25,14 @@ module Net
           raise ArgumentError, "prompt must be a nonempty Regexp or nil"
         end
         raise ArgumentError, "sensitive must be true or false" unless [true, false].include?(sensitive)
+        raise ArgumentError, "output_sensitive must be true or false" unless [true, false].include?(output_sensitive)
 
         @text = text.dup.freeze
         @timeout = Expect.duration(timeout)
         @interactions = interactions.dup.freeze
         @prompt = prompt
         @sensitive = sensitive
+        @output_sensitive = output_sensitive
         @source = source&.dup&.freeze
         @line = line
         freeze
@@ -38,10 +41,19 @@ module Net
       # 判断命令文本是否需要脱敏。
       def sensitive? = @sensitive
 
+      # 响应正文可能包含尚未登记的秘密，与命令文本是否敏感无关。
+      def output_sensitive? = @output_sensitive
+
       # 复制命令元数据，只替换命令文本。
       def with_text(text)
         self.class.new(text, timeout: timeout, interactions: interactions, prompt: prompt,
-                       sensitive: sensitive?, source: source, line: line)
+                       sensitive: sensitive?, output_sensitive: output_sensitive?, source: source, line: line)
+      end
+
+      # 配置采集保留调用方的全部命令元数据，只收紧输出的诊断边界。
+      def with_output_sensitive
+        self.class.new(text, timeout: timeout, interactions: interactions, prompt: prompt,
+                       sensitive: sensitive?, output_sensitive: true, source: source, line: line)
       end
 
       # 返回命令来源摘要，不展开命令内容。