net-connector 0.4.0

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

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require "English"
+require_relative "authentication"
+require_relative "log"
+require_relative "recovery"
+require_relative "transport"
+
+module Net
+  module Connector
+    # 连接状态、传输层和日志的唯一所有者；同一时刻只允许一个操作占用会话。
+    class Session
+      attr_reader :configuration, :transport, :reader, :redactor, :state, :prompt
+
+      # 创建认证、响应读取、脱敏和日志对象，并把会话置于关闭状态。
+      def initialize(configuration:, dialogue:, transport:, recovery:, after_login:)
+        @configuration = configuration
+        @dialogue = dialogue
+        @transport = transport
+        @recovery = recovery
+        @after_login = after_login
+        @redactor = Redactor.new(configuration.password, configuration.enable_password)
+        @reader = ResponseReader.new(self)
+        @authentication = Authentication.new(self, @dialogue)
+        @log = Log.new(configuration, redactor: redactor)
+        @state = :closed
+        @privileged = false
+        @lock = Mutex.new
+      end
+
+      # 判断会话状态和传输层是否都表明连接仍然有效。
+      def connected? = state != :closed && !transport.closed?
+
+      # 返回当前是否已经进入特权模式。
+      def privileged? = @privileged
+
+      # 标记当前会话已进入特权模式。
+      def mark_privileged! = @privileged = true
+
+      # 记录脚本之外的业务结果，例如设备报告的 TFTP 上传状态。
+      def log_event(name, **fields) = @log.event(name, **fields)
+
+      # 在会话锁内建立连接。
+      def connect
+        perform(:connect) { self }
+      end
+
+      # 锁覆盖完整操作而不是单次写入，保证批处理命令不会交错。
+      def perform(phase)
+        if @operation_owner == [Thread.current, Fiber.current] && !@performing
+          return perform_locked(phase) { yield }
+        end
+        unless @lock.try_lock
+          raise error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
+        end
+
+        begin
+          perform_locked(phase) { yield }
+        ensure
+          @lock.unlock
+        end
+      end
+
+      # 业务操作在多次脚本之间持有租约；只有同一线程和 Fiber 可顺序使用。
+      def with_operation(phase)
+        unless @lock.try_lock
+          raise error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
+        end
+        @operation_owner = [Thread.current, Fiber.current]
+        begin
+          yield
+        ensure
+          @operation_owner = nil
+          @lock.unlock
+        end
+      end
+
+      def perform_locked(phase)
+        @performing = true
+        completed = false
+        begin
+          unless connected?
+            close_resources unless state == :closed
+            connect_session
+          end
+          @state = (phase == :connect) ? :ready : :executing
+          result = yield
+          completed = true
+          result
+        rescue => error
+          failure = normalize_error(error, phase: phase)
+          close_preserving_failure
+          raise failure, cause: nil
+        rescue Exception # rubocop:disable Lint/RescueException -- Interrupts release the transport, then propagate.
+          close_preserving_failure
+          raise
+        ensure
+          # throw/catch 也会离开此块；对话未完成时必须关闭连接，不能把
+          # 半途的设备提示符误当成下一条命令的响应。
+          close_preserving_failure unless completed || !connected?
+          @state = :ready if connected?
+          @performing = false
+        end
+      end
+
+      private :perform_locked
+
+      # 独占关闭会话；已有操作占用时返回会话繁忙错误。
+      def close
+        unless @lock.try_lock
+          raise error(SessionBusy, "cannot close a session owned by another operation", phase: :close), cause: nil
+        end
+
+        begin
+          close_resources
+        ensure
+          @lock.unlock
+        end
+      end
+
+      # 执行特权认证，并更新提示符及特权状态。
+      def enable(command, prompt)
+        unless command
+          raise error(UnsupportedOperation, "privilege authentication is not supported", phase: :enable), cause: nil
+        end
+
+        @privileged = false
+        response = @log.pause { @authentication.enable(command, prompt) }
+        @prompt = response.prompt
+        @privileged = true
+        response
+      end
+
+      # 命令准备、交换、后处理及回调共用一份临时词表，退出时一并清除。
+      def command_scope(command)
+        redactor.scope do
+          protect_command(command)
+          yield
+        end
+      end
+
+      # 复用完整命令的脱敏范围；厂商后续查询产生的秘密保留到外层回调结束。
+      def exchange(command, timeout:, prompt: nil)
+        redactor.scope(reuse: true) do
+          protect_command(command)
+          started = Expect.monotonic
+          @log.event("command_start", text: command.sensitive? ? "[REDACTED]" : command.text)
+          sensitive_dialogue = [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
+          @log.event("device_output", level: :debug) if @log.detailed? && !command.sensitive? && !sensitive_dialogue
+          response = exchange_command(command, timeout: timeout, prompt: prompt)
+          @log.response_output(response.raw) unless command.sensitive? || sensitive_dialogue
+          @log.event("command_complete", status: "response_received")
+          @log.event("command_detail", level: :debug,
+                     duration_ms: ((Expect.monotonic - started) * 1000).round,
+                     response_bytes: response.raw.bytesize)
+          response
+        rescue => error
+          failure = normalize_error(error, phase: :command, command: command)
+          @log.event("command_complete", level: :error, status: "failed",
+                     error: failure.class.name, message: failure.message)
+          raise failure, cause: nil
+        end
+      end
+
+      # 在用户钩子运行前标记敏感上下文，动态交互尚未返回时也能保护其异常。
+      def protect_command(command)
+        if command.sensitive? || [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
+          redactor.sensitive!
+        end
+        redactor.remember(command.text) if command.sensitive?
+      end
+
+      private :protect_command
+
+      # 写入命令、读取对话、识别设备诊断，并返回响应对象。
+      def exchange_command(command, timeout:, prompt: nil)
+        deadline = Expect.monotonic + (command.timeout || timeout)
+        interactions = [*command.interactions, *@dialogue.command_interactions]
+        operation = lambda do
+          write("#{command.text}\n", deadline: deadline, phase: :command, command: command)
+          response = reader.read(prompt: command.prompt || prompt || @dialogue.command_prompt,
+                                 interactions: interactions,
+                                 deadline: deadline, phase: :command, command: command)
+          @prompt = response.prompt
+          if (diagnostic = @dialogue.diagnostic(response.raw))
+            raise error(DeviceError, diagnostic, phase: :command, command: command, output: response.raw), cause: nil
+          end
+
+          response
+        end
+        if command.sensitive? || interactions.any?(&:sensitive?)
+          @log.pause(&operation)
+        else
+          operation.call
+        end
+      end
+
+      private :exchange_command
+
+      # 按截止时间限制传输写入，并统一包装底层错误。
+      def write(bytes, deadline:, phase:, command: nil)
+        remaining = [deadline - Expect.monotonic, 0].max
+        transport.write(bytes, timeout: [remaining, configuration.write_timeout].min)
+      rescue => error
+        raise normalize_error(error, phase: phase, command: command), cause: nil
+      end
+
+      # 人工交互会结束当前连接，未完成的输入行不能在之后重放。
+      def interact(**options)
+        perform(:interact) do
+          @state = :interacting
+          begin
+            transport.interact(**options)
+          ensure
+            $ERROR_INFO ? close_preserving_failure : close_resources
+          end
+        end
+      end
+
+      # 创建带脱敏上下文、阶段、命令和输出尾部的领域错误。
+      def error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
+        sensitive = redactor.sensitive? || command&.sensitive?
+        message = safe_error_text(message, sensitive: sensitive)
+        output = safe_error_text(output, sensitive: sensitive)
+        klass.new(message, host: configuration.host, phase: phase,
+                  command: command && (command.sensitive? ? "[REDACTED]" : redactor.call(command.text)),
+                  source: command&.source, line: command&.line,
+                  output: output.byteslice(-4096, 4096) || output,
+                  underlying: underlying && UnderlyingError.new(underlying, redactor, sensitive: sensitive), **context)
+      end
+
+      # 将底层异常映射为连接、传输、超时或内部错误，并保留安全上下文。
+      def normalize_error(exception, phase:, command: nil)
+        if exception.is_a?(Error)
+          sensitive = redactor.sensitive? || command&.sensitive?
+          failed_command = exception.command || command&.text
+          if command&.sensitive? || (sensitive && exception.command && exception.command != command&.text)
+            failed_command = "[REDACTED]"
+          end
+          message = safe_error_text(exception.message, sensitive: sensitive)
+          output = safe_error_text(exception.output, sensitive: sensitive)
+          return exception.class.new(
+            message, code: exception.code,
+            host: exception.host || configuration.host, phase: exception.phase || phase,
+            command: failed_command && redactor.call(failed_command),
+            source: exception.source || command&.source, line: exception.line || command&.line,
+            output: output.byteslice(-4096, 4096) || output,
+            underlying: exception.underlying && UnderlyingError.new(exception.underlying, redactor, sensitive: sensitive)
+          )
+        end
+
+        klass = case exception
+                when Expect::WriteTimeout then WriteTimeout
+                when IOError, SystemCallError, Expect::SpawnError then TransportError
+                else InternalError
+                end
+        error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
+      end
+
+      # 敏感上下文的任意异常和设备输出可能只包含局部秘密，保留类型和错误码诊断。
+      def safe_error_text(text, sensitive:)
+        sensitive && !text.to_s.empty? ? "[REDACTED]".b : redactor.call(text)
+      end
+
+      private :safe_error_text
+
+      # 返回不包含凭据的会话状态摘要。
+      def inspect = "#<#{self.class} state=#{state} host=#{configuration.host.inspect}>"
+
+      private
+
+      # 建立传输并登录；失败时最多执行一次连接级恢复，然后重试登录。
+      def connect_session
+        attempted_recovery = false
+        begin
+          @state = :connecting
+          redactor.reset
+          @log.open(transport)
+          @log.event("connect", host: configuration.host, username: configuration.username,
+                     protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
+          transport.open
+          @state = :authenticating
+          @log.event("login_start", level: :debug)
+          response = @authentication.login
+          safe_response = Response.new(raw: redactor.call(response.raw), output: redactor.call(response.output),
+                                       prompt: response.prompt)
+          @prompt = response.prompt
+          @after_login.call(self, safe_response)
+          @log.authentication_output(response.raw)
+          @log.event("login_complete", status: "ok", prompt: response.prompt)
+          @log.attach
+          @state = :ready
+        rescue => error
+          phase = (@state == :connecting) ? :connect : :login
+          failure = normalize_error(error, phase: phase)
+          @log.event(phase == :connect ? "connect_failed" : "login_complete", level: :error,
+                     status: "failed", error: failure.class.name, message: failure.message, phase: phase)
+          close_preserving_failure
+          replacement = attempted_recovery ? nil : @recovery.recover(failure, transport)
+          if replacement
+            @transport = replacement
+            attempted_recovery = true
+            retry
+          end
+          raise failure, cause: nil
+        end
+      end
+
+      # 清除会话状态并关闭传输和日志资源。
+      def close_resources
+        @state = :closed
+        @privileged = false
+        @prompt = nil
+        begin
+          transport.close
+        ensure
+          @log.close
+        end
+        nil
+      rescue => error
+        raise normalize_error(error, phase: :close), cause: nil
+      end
+
+      # 尝试清理资源但不覆盖原始操作异常。
+      def close_preserving_failure
+        close_resources
+      rescue
+        # 所有清理路径完成后，原始操作异常仍然是权威结果。
+        nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "errors"
+
+module Net
+  module Connector
+    # 把终端编辑控制符渲染成可读、兼容 UTF-8 和二进制的逐行日志。
+    class TerminalRenderer
+      # 将字节流完整渲染为字符串，供测试和一次性转换使用。
+      def self.render(input)
+        output = StringIO.new("".b)
+        renderer = new(output)
+        renderer.write(input)
+        renderer.finish
+        output.string
+      end
+
+      # 初始化当前行、光标和转义序列状态。
+      def initialize(target, max_line_bytes: 32 * 1024 * 1024)
+        raise ArgumentError, "target must respond to write" unless target.respond_to?(:write)
+        unless max_line_bytes.is_a?(Integer) && max_line_bytes.positive?
+          raise ArgumentError, "max_line_bytes must be positive"
+        end
+
+        @target = target
+        @line = "".b
+        @cursor = 0
+        @escape_state = nil
+        @csi_parameters = "".b
+        @max_line_bytes = max_line_bytes
+      end
+
+      # 逐字节消费终端输出，并返回输入字节数。
+      def write(input)
+        bytes = input.to_s.b
+        bytes.each_byte { |byte| consume(byte) }
+        bytes.bytesize
+      end
+
+      # 刷新底层日志目标。
+      def flush
+        @target.flush if @target.respond_to?(:flush)
+      end
+
+      # 写出尚未换行的尾行并刷新目标。
+      def finish
+        emit_line(newline: false) unless @line.empty?
+        flush
+      end
+
+      private
+
+      # 处理普通控制字符、换行、回车和转义序列起始符。
+      def consume(byte)
+        return consume_escape(byte) if @escape_state
+
+        case byte
+        when 7 then nil
+        when 8 then @cursor = [@cursor - 1, 0].max
+        when 10 then emit_line(newline: true)
+        when 13 then @cursor = 0
+        when 27 then @escape_state = :escape
+        else write_byte(byte) if byte == 9 || byte >= 32
+        end
+      end
+
+      # 根据转义序列阶段继续解析终端控制字节。
+      def consume_escape(byte)
+        case @escape_state
+        when :escape
+          start_escape_sequence(byte)
+        when :csi
+          finish_csi(byte)
+        when :osc
+          @escape_state = nil if byte == 7
+          @escape_state = :osc_escape if byte == 27
+        when :osc_escape
+          @escape_state = (byte == 92) ? nil : :osc
+        end
+      end
+
+      # 识别 CSI 或 OSC 序列，并忽略未知的单字节序列。
+      def start_escape_sequence(byte)
+        case byte
+        when 91
+          @csi_parameters.clear
+          @escape_state = :csi
+        when 93 then @escape_state = :osc
+        else
+          @escape_state = nil
+        end
+      end
+
+      # 收集 CSI 参数并在终止字节到达时执行光标操作。
+      def finish_csi(byte)
+        if byte.between?(0x40, 0x7e)
+          apply_csi(byte)
+          @escape_state = nil
+        elsif byte.between?(0x20, 0x3f)
+          raise OutputLimitExceeded, "terminal escape sequence is too long" if @csi_parameters.bytesize >= 64
+
+          @csi_parameters << byte
+        else
+          @escape_state = nil
+        end
+      end
+
+      # 应用有限范围内的光标移动和整行擦除控制。
+      def apply_csi(command)
+        count = Integer(@csi_parameters[/\d+/, 0] || "1", 10)
+        case command
+        when 67 then @cursor += count
+        when 68 then @cursor = [@cursor - count, 0].max
+        when 71 then @cursor = [count - 1, 0].max
+        when 75 then erase_line(Integer(@csi_parameters[/\d+/, 0] || "0", 10))
+        end
+      end
+
+      # 按终端擦除模式修改当前行缓冲区。
+      def erase_line(mode)
+        case mode
+        when 0 then @line = @line.byteslice(0, @cursor)
+        when 1
+          @line = (" " * [@cursor + 1, @line.bytesize].min) + @line.byteslice((@cursor + 1)..).to_s
+        when 2
+          @line.clear
+          @cursor = 0
+        end
+      end
+
+      # 在光标位置写入字节，并限制单行缓冲大小。
+      def write_byte(byte)
+        raise OutputLimitExceeded, "terminal line exceeded max_line_bytes" if @cursor >= @max_line_bytes
+
+        @line << (" " * (@cursor - @line.bytesize)) if @cursor > @line.bytesize
+        (@cursor < @line.bytesize) ? @line.setbyte(@cursor, byte) : @line << byte
+        @cursor += 1
+      end
+
+      # 删除行尾空白，写出当前行并重置光标。
+      def emit_line(newline:)
+        @target.write(utf8_safe(@line.sub(/[ \t]+\z/n, "")))
+        @target.write("\n") if newline
+        @line.clear
+        @cursor = 0
+      end
+
+      # 尽量保持有效 UTF-8；非法字节转义为可读的十六进制文本。
+      def utf8_safe(line)
+        text = line.dup.force_encoding(Encoding::UTF_8)
+        return text.b if text.valid_encoding?
+
+        text.scrub { |invalid| invalid.bytes.map { |byte| format("\\x%02X", byte) }.join }.b
+      end
+    end
+  end
+end

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "open3"
+require "expect/pty"
+
+module Net
+  module Connector
+    # 传输事件使用从零开始的模式索引；最后一个额外索引表示流式数据。
+    Event = Struct.new(:index, :before, :match, :error) do
+      # 规范化事件的默认字节字段，便于读取器统一处理。
+      def initialize(index: nil, before: "".b, match: "".b, error: nil)
+        super
+      end
+
+      # 判断读取是否命中了模式而不是传输错误。
+      def matched? = error.nil?
+
+      # 返回事件索引和错误类型摘要。
+      def inspect = "#<#{self.class} index=#{index.inspect} error=#{error&.class}>"
+    end
+
+    # 可替换的字节传输层；厂商语法属于设备边界，不属于此层。
+    module Transports
+      # Expect 适配器拥有伪终端和进程，在限制未匹配尾部时不丢弃数据。
+      class Pty
+        # 即使读到完整行也保留 32 KiB，因为提示符可能跨越多次读取和多行。
+        STREAM = /\A[\s\S]{32768}(?=[\s\S]{32768})/n
+        attr_reader :configuration
+
+        # 保存配置和可替换的信道工厂，便于测试和设备差异注入。
+        def initialize(configuration, channel_factory: nil, terminal_size: nil)
+          @configuration = configuration
+          @channel_factory = channel_factory
+          @terminal_size = terminal_size
+        end
+
+        # 打开伪终端、设置终端大小并启动设备进程。
+        def open
+          configuration.validate_endpoint!
+          @channel = if @channel_factory
+                       @channel_factory.call
+                     else
+                       Expect.new(raw_pty: true, reset_timeout_on_read: false, buffer_limit: nil,
+                                  preserve_buffer: false, log_stdout: false, log_listeners: false,
+                                  debug_level: 0, write_timeout: configuration.write_timeout)
+                     end
+          # Profile 使用宽、高；PTY 使用行数、列数。
+          @channel.slave.winsize = @terminal_size.reverse if @terminal_size
+          @channel.log_output = method(:record)
+          @channel.spawn(*argv)
+          self
+        rescue Exception # rubocop:disable Lint/RescueException -- A half-open PTY must be released on interrupts.
+          begin
+            close
+          rescue
+            # 尝试释放半打开信道后，仍然抛出原始失败。
+          end
+          raise
+        end
+
+        # 从信道读取下一事件，并把字符串字段转换为字节字符串。
+        def read(patterns, timeout:)
+          result = @channel.expect_result(*patterns, STREAM, timeout: timeout)
+          Event.new(index: result.number && (result.number - 1), before: result.before.to_s.b,
+                    match: result.match.to_s.b, error: result.error)
+        end
+
+        # 临时设置写入超时，完成写入后恢复原设置。
+        def write(bytes, timeout: configuration.write_timeout)
+          previous = @channel.write_timeout
+          @channel.write_timeout = timeout
+          @channel.write(bytes)
+        ensure
+          @channel.write_timeout = previous if @channel
+        end
+
+        # 判断信道尚未建立或已经关闭。
+        def closed? = !@channel || @channel.closed?
+
+        # 设置日志输出目标；nil 表示暂时停止记录。
+        def log_output=(target)
+          @log_target = target
+        end
+
+        # 清除信道和日志目标，并强制关闭底层进程。
+        def close
+          channel = @channel
+          @channel = nil
+          @log_target = nil
+          channel&.hard_close
+        end
+
+        # 把人工交互结果转换为设备 EOF、超时或输入状态。
+        def interact(**)
+          stopped = @channel.interact(**)
+          return :device_eof if stopped.equal?(@channel)
+
+          stopped.nil? ? :timeout : :input
+        end
+
+        # 返回传输主机和关闭状态摘要。
+        def inspect = "#<#{self.class} host=#{configuration.host.inspect} closed=#{closed?}>"
+
+        private
+
+        # 检查缓冲上限并把设备输出写入当前日志目标。
+        def record(bytes)
+          if @channel.buffer.bytesize > configuration.max_output_bytes
+            raise OutputLimitExceeded.new("transport buffer exceeded max_output_bytes",
+                                          phase: :read, output: @channel.buffer.dup), cause: nil
+          end
+
+          @log_target&.write(bytes)
+          @log_target.flush if @log_target.respond_to?(:flush)
+        end
+      end
+
+      # 生成 OpenSSH 参数，并处理显式请求的旧版协商和主机密钥操作。
+      class Ssh < Pty
+        attr_reader :legacy_arguments
+
+        # 保存旧版 SSH 参数并复用伪终端初始化。
+        def initialize(configuration, legacy_arguments: [], **)
+          super(configuration, **)
+          @legacy_arguments = legacy_arguments.dup.freeze
+        end
+
+        # 返回 SSH 协议标识。
+        def protocol = :ssh
+
+        # 根据配置生成经过端点校验的 SSH 参数数组。
+        def argv
+          configuration.validate_endpoint!
+          checking = (configuration.host_key_policy == :strict) ? "yes" : "accept-new"
+          arguments = ["ssh", *legacy_arguments, "-tt", "-o", "StrictHostKeyChecking=#{checking}",
+                       "-o", "NumberOfPasswordPrompts=1",
+                       "-o", "ConnectTimeout=#{[configuration.login_timeout.ceil, 1].max}"]
+          arguments += ["-o", "UserKnownHostsFile=#{configuration.known_hosts}"] if configuration.known_hosts
+          arguments += ["-p", configuration.port.to_s] if configuration.port
+          arguments + ["-l", configuration.username, configuration.host]
+        end
+
+        # 创建带旧版协商参数的同类传输对象。
+        def with_legacy(arguments)
+          self.class.new(configuration, legacy_arguments: arguments, channel_factory: @channel_factory,
+                         terminal_size: @terminal_size)
+        end
+
+        # 创建不继承 SSH 专用端口的 Telnet 传输对象。
+        def as_telnet
+          Telnet.new(configuration, channel_factory: @channel_factory, terminal_size: @terminal_size)
+        end
+
+        # 从指定 known_hosts 文件中删除当前设备的旧主机密钥。
+        def replace_host_key
+          host = configuration.host
+          host = "[#{host}]:#{configuration.port}" if configuration.port && configuration.port != 22
+          _output, status = Open3.capture2e("ssh-keygen", "-f", configuration.known_hosts, "-R", host)
+          raise IOError, "removing device host key failed" unless status.success?
+        end
+      end
+
+      # Telnet 只能显式启用；SSH 专用端口不能带入回退连接。
+      class Telnet < Pty
+        # 返回 Telnet 协议标识。
+        def protocol = :telnet
+
+        # 根据配置生成经过端点校验的 Telnet 参数数组。
+        def argv
+          configuration.validate_endpoint!
+          port = (configuration.protocol == :telnet) ? configuration.port : nil
+          ["telnet", "-l", configuration.username, configuration.host, *(port ? [port.to_s] : [])]
+        end
+      end
+
+      TYPES = { ssh: Ssh, telnet: Telnet }.freeze
+
+      # 按协议选择具体传输实现。
+      def self.build(configuration, **)
+        TYPES.fetch(configuration.protocol).new(configuration, **)
+      end
+    end
+  end
+end

data/lib/net/connector/engine.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# 保留原设备门面入口；只需要会话执行层时加载 engine/core。
+require_relative "device/base"