net-connector 0.4.0 → 0.4.1

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
@@ -33,6 +34,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 +46,7 @@ module Net
         Result.new(steps: result.steps, config: content)
       end
 
+      # 用当前完整提示符构建结束匹配，避免配置正文中的单个 # 提前结束采集。
       def prompt_for(command, strategy)
         return command.prompt if command.prompt
 
@@ -54,6 +57,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 +65,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/dialogue.rb

@@ -86,6 +86,7 @@ module Net
 
       private
 
+      # 只截取命中错误模式的当前行，避免把整段设备配置写进诊断信息。
       def diagnostic_line(output)
         match = command_errors.lazy.filter_map { |pattern| pattern.match(output) }.first
         return unless match

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

@@ -112,6 +112,7 @@ module Net
       # 敏感命令和交互的异常可能只引用秘密的一部分，不能只依赖完整词匹配。
       def sensitive! = @sensitive = true
 
+      # 判断当前脱敏范围是否包含敏感交互。
       def sensitive? = @sensitive
 
       # 记住新的敏感字节，并按长度排序避免短词先匹配。
@@ -165,6 +166,7 @@ module Net
         @pattern ||= /(?=(#{Regexp.union((@secrets + ["[REDACTED]"]).uniq.sort_by { |secret| -secret.bytesize })}))/n
       end
 
+      # 合并重叠的秘密匹配区间，防止替换顺序露出部分凭据。
       def matches(text)
         ranges = []
         text.to_enum(:scan, pattern).each do

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

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-require "active_support"
-require "active_support/logger"
-require "active_support/tagged_logging"
 require "fileutils"
+require "logger"
 require_relative "terminal_renderer"
 require_relative "log_messages"
 require_relative "errors"
@@ -29,14 +27,16 @@ module Net
         if @configuration.log_format == :raw
           @writer = @output
         elsif @io || @configuration.logger
-          base = @configuration.logger || ActiveSupport::Logger.new(@io)
+          base = @configuration.logger || ::Logger.new(@io)
           unless @configuration.logger
             base.formatter = proc do |severity, time, _program, message|
               "[#{time.getlocal.strftime("%Y-%m-%d %H:%M:%S %:z")}] #{severity} #{message}\n"
             end
           end
-          @logger = ActiveSupport::TaggedLogging.new(base).tagged("host=#{@configuration.host}")
-          @logger.level = [base.level, LEVELS.fetch(@configuration.log_level)].max
+          # 前缀直接写入消息，不克隆或修改调用方注入的日志器。
+          @logger = base
+          @event_level = [base.level, LEVELS.fetch(@configuration.log_level)].max
+          @tag = "[host=#{@configuration.host}] "
           if @io && @configuration.log_level == :debug
             @writer = TerminalRenderer.new(@output, max_line_bytes: @configuration.max_output_bytes)
           end
@@ -67,7 +67,7 @@ module Net
         end
         safe_name = @redactor.call(name.to_s).scrub.gsub(/[[:cntrl:]]+/, " ").strip
         finish_line
-        @logger.public_send(level, LogMessages.format(safe_name, values))
+        @logger.public_send(level, "#{@tag}#{LogMessages.format(safe_name, values)}") if LEVELS.fetch(level) >= @event_level
       rescue Error
         raise
       rescue => error
@@ -92,7 +92,7 @@ module Net
         return unless detailed? && !@writer
 
         @redactor.call(TerminalRenderer.render(@redactor.call(bytes))).each_line do |line|
-          @logger.debug("  #{line.chomp}")
+          @logger.debug("#{@tag}  #{line.chomp}") if ::Logger::DEBUG >= @event_level
         end
       rescue Error
         raise
@@ -140,7 +140,7 @@ module Net
           begin
             @io&.close
           ensure
-            @writer = @output = @logger = @io = @transport = nil
+            @writer = @output = @logger = @io = @transport = @tag = @event_level = nil
             @attached = false
           end
         end
@@ -169,12 +169,14 @@ module Net
 
       # 文件写入边界保留短尾部，避免分片或终端控制符拼出明文凭据。
       class RedactingWriter
+        # 保存目标流、脱敏器和等待下一分片的尾部。
         def initialize(target, redactor)
           @target = target
           @redactor = redactor
           @pending = "".b
         end
 
+        # 写入已确认安全的前缀，暂存可能与下一分片组成秘密的尾部。
         def write(bytes)
           @pending << bytes.b
           safe, @pending = @redactor.stream_chunk(@pending)
@@ -182,8 +184,10 @@ module Net
           bytes.bytesize
         end
 
+        # 刷新目标流，仍不提前写出待判断的尾部。
         def flush = @target.flush
 
+        # 在日志结束时脱敏并写出剩余尾部。
         def finish
           safe, @pending = @redactor.stream_chunk(@pending, final: true)
           @target.write(safe)

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

@@ -75,6 +75,7 @@ module Net
         end
       end
 
+      # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
       def perform_locked(phase)
         @performing = true
         completed = false