net-connector 0.4.0

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    # 操作错误携带已脱敏上下文；原始配置只存在于明确的结果或日志中。
+    class Error < StandardError
+      attr_reader :code, :host, :phase, :command, :output, :source, :line, :underlying
+
+      # 保存错误阶段、命令和输出尾部，并为缺省错误类生成稳定错误码。
+      def initialize(message, code: nil, host: nil, phase: nil, command: nil, output: "".b,
+                     source: nil, line: nil, underlying: nil)
+        super(message)
+        @code = code || self.class.name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+        @host = host
+        @phase = phase
+        @command = command
+        @output = output.freeze
+        @source = source
+        @line = line
+        @underlying = underlying
+      end
+
+      # 返回不展开命令和输出的错误摘要。
+      def inspect = "#<#{self.class} code=#{code.inspect} phase=#{phase.inspect} host=#{host.inspect}>"
+    end
+
+    class ConnectionError < Error; end
+
+    class AuthenticationError < ConnectionError; end
+
+    class LoginTimeout < AuthenticationError; end
+
+    class CommandTimeout < Error; end
+
+    class WriteTimeout < Error; end
+
+    class PromptError < Error; end
+
+    class ConnectionClosed < ConnectionError; end
+
+    class TransportError < ConnectionError; end
+
+    class DeviceError < Error; end
+
+    class ScriptError < Error; end
+
+    class InternalError < Error; end
+
+    class OutputLimitExceeded < Error; end
+
+    class SessionBusy < Error; end
+
+    class UnsupportedOperation < Error; end
+
+    class LogError < Error; end
+
+    class ParsingError < Error; end
+
+    # 安全保存底层异常，不保留包含凭据的原始消息。
+    class UnderlyingError
+      attr_reader :type, :message, :backtrace
+
+      # 保存脱敏后的异常类型、消息和调用栈。
+      def initialize(error, redactor, sensitive: false)
+        @type = error.is_a?(UnderlyingError) ? error.type : error.class.name
+        @message = (sensitive ? "[REDACTED]" : redactor.call(error.message)).freeze
+        @backtrace = (sensitive ? [] : Array(error.backtrace).map { |line| redactor.call(line).freeze }).freeze
+        freeze
+      end
+
+      # 返回底层异常类型摘要。
+      def inspect = "#<#{self.class} type=#{type}>"
+    end
+
+    # 每个会话独立保存脱敏词，包括配置凭据和动态认证响应。
+    class Redactor
+      # 保存初始凭据，并建立第一版脱敏词表。
+      def initialize(*secrets)
+        @configured = secrets.compact.map(&:b).map(&:freeze).freeze
+        reset
+      end
+
+      # 重置动态词表，同时保留配置中的固定凭据。
+      def reset
+        @secrets = []
+        @pattern = nil
+        @scoped = false
+        @sensitive = false
+        @configured.each { |secret| remember(secret) }
+      end
+
+      # 临时命令响应在错误归一化期间保留，离开作用域后不进入长期会话。
+      def scope(reuse: false)
+        return yield if reuse && @scoped
+
+        previous = @secrets
+        previous_pattern = @pattern
+        previous_scoped = @scoped
+        previous_sensitive = @sensitive
+        @secrets = previous.dup
+        @scoped = true
+        begin
+          yield
+        ensure
+          @secrets = previous
+          @pattern = previous_pattern
+          @scoped = previous_scoped
+          @sensitive = previous_sensitive
+        end
+      end
+
+      # 敏感命令和交互的异常可能只引用秘密的一部分，不能只依赖完整词匹配。
+      def sensitive! = @sensitive = true
+
+      def sensitive? = @sensitive
+
+      # 记住新的敏感字节，并按长度排序避免短词先匹配。
+      def remember(secret)
+        return if secret.nil? || secret.empty?
+
+        bytes = secret.b
+        return if @secrets.include?(bytes)
+
+        @secrets << bytes.freeze
+        @secrets.sort_by! { |value| -value.bytesize }
+        @pattern = nil
+      end
+
+      # 保留可能跨下一分片的尾部；完整匹配始终作为整体脱敏。
+      def stream_chunk(bytes, final: false)
+        return [call(bytes), "".b] if final || @secrets.empty?
+
+        retained = [@secrets.first.bytesize, "[REDACTED]".bytesize].max - 1
+        boundary = [bytes.bytesize - retained, 0].max
+        matches(bytes).each do |start, finish|
+          if start < boundary && finish > boundary
+            boundary = start
+            break
+          end
+        end
+        [call(bytes.byteslice(0, boundary)), bytes.byteslice(boundary..)]
+      end
+
+      # 单次扫描替换所有敏感词，并保留已有脱敏标记。
+      def call(text)
+        text = text.to_s.b
+        return text if @secrets.empty?
+
+        output = +"".b
+        offset = 0
+        matches(text).each do |start, finish|
+          output << text.byteslice(offset, start - offset) << "[REDACTED]"
+          offset = finish
+        end
+        output << text.byteslice(offset..)
+      end
+
+      # 返回脱敏器类型摘要。
+      def inspect = "#<#{self.class}>"
+
+      private
+
+      # 前瞻保留重叠匹配；跨标记边界的真实秘密不能被已有标记遮蔽。
+      def pattern
+        @pattern ||= /(?=(#{Regexp.union((@secrets + ["[REDACTED]"]).uniq.sort_by { |secret| -secret.bytesize })}))/n
+      end
+
+      def matches(text)
+        ranges = []
+        text.to_enum(:scan, pattern).each do
+          match = Regexp.last_match
+          start, finish = match.begin(1), match.end(1)
+          if ranges.last && start < ranges.last.last
+            ranges.last[1] = [ranges.last.last, finish].max
+          else
+            ranges << [start, finish]
+          end
+        end
+        ranges
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "command"
+require_relative "result"
+
+module Net
+  module Connector
+    # 单个脚本的局部状态；执行对象不拥有设备或传输层生命周期。
+    class Execution
+      attr_reader :context, :steps
+
+      # 保存命令准备和后处理钩子，并初始化批次上下文及已完成步骤。
+      def initialize(session:, timeout:, prepare:, after_command:, prompt: nil)
+        @session = session
+        @command_timeout = timeout
+        @prepare_command = prepare
+        @after_command = after_command
+        @prompt = prompt
+        @context = {}
+        @steps = []
+      end
+
+      # 依次准备、执行和记录脚本命令；失败时保留已完成步骤并统一抛错。
+      def execute(script)
+        script.each do |original|
+          @session.command_scope(original) do
+            @current_command = original
+            command = @prepare_command.call(original, self)
+            next unless command
+
+            @current_command = command
+            started = Expect.monotonic
+            response = query(command)
+            step = CommandResult.new(command: command, output: response.output, prompt: response.prompt,
+                                     duration: Expect.monotonic - started)
+            steps << step
+            # 设备已经完成命令；后处理失败也不能从部分结果中抹去其副作用。
+            @after_command.call(command, response, self)
+            yield step if block_given?
+          rescue => error
+            raise @session.normalize_error(error, phase: :script, command: @current_command), cause: nil
+          end
+        end
+        Result.new(steps: steps)
+      end
+
+      # 厂商后续查询复用同一信道和错误处理，不开启新的批处理。
+      def query(command)
+        command = Command.new(command) unless command.is_a?(Command)
+        @session.exchange(command, timeout: @command_timeout, prompt: @prompt&.call(command))
+      end
+
+      # 只有当前会话未特权时才执行特权认证。
+      def enable(command, prompt)
+        @session.enable(command, prompt) unless @session.privileged?
+      end
+
+      # 根据当前命令建立脚本阶段错误。
+      def failure(message)
+        @session.error(ScriptError, message, phase: :script, command: @current_command)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/logger"
+require "active_support/tagged_logging"
+require "fileutils"
+require_relative "terminal_renderer"
+require_relative "log_messages"
+require_relative "errors"
+
+module Net
+  module Connector
+    # 单个设备会话的日志，按级别控制是否包含完整回显。
+    class Log
+      LEVELS = { debug: ::Logger::DEBUG, info: ::Logger::INFO,
+                 warn: ::Logger::WARN, error: ::Logger::ERROR }.freeze
+
+      # 保存日志配置和敏感信息脱敏器。
+      def initialize(configuration, redactor:)
+        @configuration = configuration
+        @redactor = redactor
+      end
+
+      # 为会话打开日志文件或应用日志器。
+      def open(transport)
+        @transport = transport
+        @io = open_file(@configuration.log_file) if @configuration.log_file
+        @output = RedactingWriter.new(@io, @redactor) if @io
+        if @configuration.log_format == :raw
+          @writer = @output
+        elsif @io || @configuration.logger
+          base = @configuration.logger || ActiveSupport::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
+          if @io && @configuration.log_level == :debug
+            @writer = TerminalRenderer.new(@output, max_line_bytes: @configuration.max_output_bytes)
+          end
+        end
+        @line_open = false
+      rescue => error
+        close_preserving_error
+        raise failure("unable to open session log", error), cause: nil
+      end
+
+      # 将终端回显接入当前会话日志。
+      def attach
+        return unless @transport && @writer
+
+        @transport.log_output = self
+        @attached = true
+      end
+
+      # 判断当前日志级别是否需要完整设备回显。
+      def detailed? = @configuration.log_level == :debug && !!(@writer || @logger)
+
+      # 按日志级别写入已脱敏的业务事件。
+      def event(name, level: :info, **fields)
+        return unless @logger
+
+        values = fields.transform_values do |value|
+          value.is_a?(String) ? @redactor.call(value).scrub.gsub(/[[:cntrl:]]+/, " ").strip : value
+        end
+        safe_name = @redactor.call(name.to_s).scrub.gsub(/[[:cntrl:]]+/, " ").strip
+        finish_line
+        @logger.public_send(level, LogMessages.format(safe_name, values))
+      rescue Error
+        raise
+      rescue => error
+        raise failure("unable to write session event", error), cause: nil
+      end
+
+      # 登录完成并收集动态口令后，再记录已脱敏的认证回显。
+      def authentication_output(bytes)
+        return unless detailed?
+
+        event("login_output", level: :debug)
+        if @writer
+          write(@redactor.call(bytes))
+          flush
+        else
+          response_output(bytes)
+        end
+      end
+
+      # 应用注入的日志器没有终端写入器，改由日志器记录完整回显。
+      def response_output(bytes)
+        return unless detailed? && !@writer
+
+        @redactor.call(TerminalRenderer.render(@redactor.call(bytes))).each_line do |line|
+          @logger.debug("  #{line.chomp}")
+        end
+      rescue Error
+        raise
+      rescue => error
+        raise failure("unable to write device output", error), cause: nil
+      end
+
+      # 向终端日志写入已处理的回显字节。
+      def write(bytes)
+        return unless @writer
+
+        @writer.write(bytes)
+        @line_open = !bytes.end_with?("\n") unless bytes.empty?
+      rescue Error
+        raise
+      rescue => error
+        raise failure("unable to write session log", error), cause: nil
+      end
+
+      # 刷新日志缓冲区。
+      def flush
+        @writer&.flush
+        @io&.flush
+      rescue Error
+        raise
+      rescue => error
+        raise failure("unable to flush session log", error), cause: nil
+      end
+
+      # 执行代码块期间暂停自动记录传输回显。
+      def pause
+        finish_output
+        @transport.log_output = nil if @transport
+        yield
+      ensure
+        @transport.log_output = self if @transport && @writer && @attached
+      end
+
+      # 断开回显记录并关闭日志资源。
+      def close
+        begin
+          @transport.log_output = nil if @transport
+          finish_output
+        ensure
+          begin
+            @io&.close
+          ensure
+            @writer = @output = @logger = @io = @transport = nil
+            @attached = false
+          end
+        end
+      rescue Error
+        raise
+      rescue => error
+        raise failure("unable to close session log", error), cause: nil
+      end
+
+      private
+
+      # 结束未换行的回显，保持事件独占一行。
+      def finish_line
+        return unless @writer
+
+        finish_output
+        @io.write("\n") if @line_open
+        @line_open = false
+      end
+
+      # 先完成终端渲染，再写出脱敏流的最后几个字节。
+      def finish_output
+        @writer.finish if @writer.respond_to?(:finish)
+        @output&.finish unless @output.equal?(@writer)
+      end
+
+      # 文件写入边界保留短尾部，避免分片或终端控制符拼出明文凭据。
+      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)
+          @target.write(safe)
+          bytes.bytesize
+        end
+
+        def flush = @target.flush
+
+        def finish
+          safe, @pending = @redactor.stream_chunk(@pending, final: true)
+          @target.write(safe)
+          flush
+        end
+      end
+      private_constant :RedactingWriter
+
+      # 以私有权限打开设备日志文件。
+      def open_file(path)
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        file = File.open(path, File::WRONLY | File::CREAT | File::APPEND | File::NOFOLLOW, 0o600)
+        begin
+          file.chmod(0o600)
+          file.binmode
+          file.write("\n") if file.size.positive? && @configuration.log_format == :text
+          file
+        rescue Exception # rubocop:disable Lint/RescueException -- Release partially configured files on interrupts too.
+          begin
+            file.close
+          rescue
+            # 保留设置失败的原始原因。
+          end
+          raise
+        end
+      end
+
+      # 在日志打开失败后尽力释放资源。
+      def close_preserving_error
+        close
+      rescue
+        nil
+      end
+
+      # 将日志异常包装成统一错误并保留脱敏原因。
+      def failure(message, error)
+        LogError.new(message, phase: :logging, underlying: UnderlyingError.new(error, @redactor))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    # 独立于日志目标的人类可读事件文案。
+    module LogMessages
+      module_function
+
+      # 将结构化会话事件转换为便于人工阅读的中文日志。
+      def format(name, fields)
+        case name
+        when "connect"
+          "开始连接 #{fields[:host]}（#{fields[:protocol].to_s.upcase}，账号 #{fields[:username]}）"
+        when "connect_failed"
+          "连接失败：#{fields[:message]}（#{fields[:error]}）"
+        when "login_start"
+          "等待设备登录提示"
+        when "login_output"
+          "登录过程回显（已脱敏）："
+        when "login_complete"
+          fields[:status] == "ok" ? "登录成功，设备提示符：#{fields[:prompt]}" :
+            "登录失败：#{fields[:message]}（#{fields[:error]}）"
+        when "command_start"
+          "下发命令：#{fields[:text]}"
+        when "device_output"
+          "设备回显："
+        when "command_complete"
+          fields[:status] == "response_received" ? "命令回显结束，已收到设备提示符" :
+            "命令执行失败：#{fields[:message]}（#{fields[:error]}）"
+        when "command_detail"
+          "命令耗时 #{fields[:duration_ms]} 毫秒，收到 #{fields[:response_bytes]} 字节回显"
+        when "tftp_backup"
+          case fields[:status]
+          when "reported_uploaded"
+            "TFTP 备份：设备报告上传成功，目标 #{fields[:server]}/#{fields[:path]}；服务器文件尚未核验"
+          when "transfer_failed"
+            "TFTP 备份失败：设备报告传输失败，服务器 #{fields[:server]}"
+          else
+            "TFTP 备份未确认：设备未报告上传成功，服务器 #{fields[:server]}"
+          end
+        else
+          name.to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# 旧加载路径保留为转发入口；设备定义位于 device/。
+require_relative "../device/profile"

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    # 只选择一次连接级恢复；任何设备命令都不会重放。
+    class Recovery
+      # 只有明确允许的 SSH 拒绝才会建立一次 Telnet 连接。
+      class TelnetFallback
+        # 将连接被拒绝转换为 Telnet 传输，否则不提供恢复。
+        def recover(error, transport)
+          transport.as_telnet if error.code == :connection_refused && transport.respond_to?(:as_telnet)
+        end
+      end
+
+      # 主机密钥替换仅限调用方指定的 known_hosts 文件。
+      class HostKeyReplacement
+        # 删除旧密钥并返回原传输对象，其他错误不触发替换。
+        def recover(error, transport)
+          return unless error.code == :host_key_changed && transport.respond_to?(:replace_host_key)
+
+          transport.replace_host_key
+          transport
+        end
+      end
+
+      # 旧版协商参数来自厂商配置，不能由设备输出决定。
+      class LegacySsh
+        # 保存厂商提供的旧版参数。
+        def initialize(arguments)
+          @arguments = arguments
+        end
+
+        # 根据明确错误码创建一次旧版 SSH 传输。
+        def recover(error, transport)
+          return unless transport.respond_to?(:with_legacy)
+
+          arguments = { rsa_too_small: @arguments, unsupported_cipher: ["-c", "des"] }[error.code]
+          transport.with_legacy(arguments) if arguments
+        end
+      end
+
+      # 按配置顺序建立可用的连接级恢复规则。
+      def initialize(configuration, legacy_arguments:)
+        @rules = []
+        @rules << TelnetFallback.new if configuration.telnet_fallback?
+        @rules << HostKeyReplacement.new if configuration.host_key_policy == :replace
+        @rules << LegacySsh.new(legacy_arguments) if configuration.legacy_ssh?
+        @rules.freeze
+      end
+
+      # 依次尝试恢复规则，并只返回第一个新传输对象。
+      def recover(error, transport)
+        @rules.lazy.filter_map { |rule| rule.recover(error, transport) }.first
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Net
+  module Connector
+    # 一条已完成命令的结果；后续命令失败时仍保留已完成步骤。
+    class CommandResult
+      attr_reader :command, :output, :prompt, :duration
+
+      # 保存命令输出、提示符和耗时，并冻结结果。
+      def initialize(command:, output:, prompt:, duration:)
+        @command = command
+        @output = output.frozen? ? output : output.dup.freeze
+        @prompt = prompt&.dup&.freeze
+        @duration = duration
+        freeze
+      end
+
+      # 返回输出字节数和耗时摘要。
+      def inspect = "#<#{self.class} bytes=#{output.bytesize} duration=#{duration.round(6)}>"
+    end
+
+    # 不可变执行结果；构造结果不会复制已经累计的命令输出前缀。
+    class Result
+      include Enumerable
+
+      attr_reader :steps, :error, :config
+
+      # 校验步骤、错误和配置文本，并冻结结果容器。
+      def initialize(steps: [], error: nil, config: nil)
+        raise ArgumentError, "error must be a Connector::Error or nil" unless error.nil? || error.is_a?(Error)
+        unless steps.is_a?(Array) && steps.all?(CommandResult)
+          raise ArgumentError, "steps must be an Array of CommandResult objects"
+        end
+        raise ArgumentError, "config must be a String or nil" unless config.nil? || config.is_a?(String)
+
+        @steps = steps.dup.freeze
+        @error = error
+        @config = config&.dup&.freeze
+        freeze
+      end
+
+      # 判断执行是否成功。
+      def success? = error.nil?
+
+      # 判断执行是否失败。
+      def failure? = !success?
+
+      # 遍历已完成命令步骤。
+      def each(&) = steps.each(&)
+
+      # 拼接所有已完成步骤的输出字节。
+      def output = steps.map(&:output).join.b
+
+      # 成功时返回配置或输出，失败时重新抛出领域错误。
+      def value!
+        raise error, cause: nil if failure?
+
+        config || output
+      end
+
+      # 返回结果成功状态、步骤数量和错误码摘要。
+      def inspect = "#<#{self.class} success=#{success?} steps=#{steps.size} code=#{error&.code.inspect}>"
+    end
+  end
+end