net-connector 0.4.0

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "dialogue"
+
+module Net
+  module Connector
+    # 密码或密钥登录与显式特权认证共用有界对话流程。
+    class Authentication
+      CONNECTION_FAILURES = {
+        /REMOTE HOST IDEN|IDENTIFICATION CHANGED/i => [ConnectionError, :host_key_changed],
+        /Host key verification failed/i => [ConnectionError, :host_key_untrusted],
+        /RSA modulus too small/i => [ConnectionError, :rsa_too_small],
+        /Selected cipher type <unknown> not supported by server/i => [ConnectionError, :unsupported_cipher],
+        /Connection refused/i => [ConnectionError, :connection_refused],
+        /No route to host/i => [ConnectionError, :no_route],
+        /Connection reset/i => [ConnectionError, :connection_reset],
+        /(?:Operation|Connection) timed out/i => [ConnectionError, :connection_timeout]
+      }.freeze
+      SSH_CONFIRMATION = %r{\(yes/no(?:/\[fingerprint\])?\)\?\s*\z}i
+
+      # 保存会话配置，并合并传输失败和设备认证失败模式。
+      def initialize(session, dialogue)
+        @session = session
+        @dialogue = dialogue
+        @config = session.configuration
+        @failures = CONNECTION_FAILURES.merge(
+          dialogue.authentication_errors.to_h { |pattern| [pattern, [AuthenticationError, :authentication_failed]] }
+        ).freeze
+      end
+
+      # 在登录提示或连接失败模式出现前读取登录响应。
+      def login
+        @session.reader.read(
+          prompt: @dialogue.login_prompt, interactions: login_interactions, failures: @failures,
+          timeout: @config.login_timeout, phase: :login
+        )
+      end
+
+      # 发送特权命令，并在截止时间内完成凭据交互。
+      def enable(command, prompt)
+        deadline = Expect.monotonic + @config.login_timeout
+        @session.write("#{command}\n", deadline: deadline, phase: :enable)
+        secret = @config.enable_password || @config.password
+        @session.reader.read(prompt: prompt, interactions: credential_interactions(secret), failures: @failures,
+                             deadline: deadline, phase: :enable)
+      end
+
+      private
+
+      # 为用户名和密码创建一次性敏感交互规则。
+      def credential_interactions(secret)
+        [
+          Interaction.new(@dialogue.username_prompt, ->(_prompt) { input_line(@config.username) },
+                          sensitive: true, limit: 1, capture: false),
+          Interaction.new(@dialogue.password_prompt, ->(_prompt) { input_line(secret) },
+                          sensitive: true, limit: 1, capture: false)
+        ]
+      end
+
+      # 组装主机密钥确认、厂商挑战和凭据交互。
+      def login_interactions
+        host_key = Interaction.new(SSH_CONFIRMATION, lambda { |_prompt|
+          if @config.host_key_policy == :strict
+            raise @session.error(ConnectionError, "host key confirmation rejected",
+                                 phase: :login, code: :host_key_untrusted), cause: nil
+          end
+          "yes\n"
+        }, limit: 1)
+        [host_key, *@dialogue.login_interactions, *@config.challenges.map(&:challenge),
+         *credential_interactions(@config.password)]
+      end
+
+      # 将可选凭据编码为带换行的设备输入。
+      def input_line(secret) = secret && "#{secret}\n"
+    end
+  end
+end

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

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

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "dialogue"
+require "expect/pty"
+
+module Net
+  module Connector
+    # 一条设备命令行，可附带独立截止时间和交互规则。
+    class Command
+      attr_reader :text, :timeout, :interactions, :prompt, :source, :line
+
+      # 在任何输入输出前校验命令、提示、交互和敏感标记，并冻结命令。
+      def initialize(text, timeout: nil, interactions: [], prompt: nil, 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)
+        end
+        unless interactions.is_a?(Array) && interactions.all?(Interaction)
+          raise ArgumentError, "interactions must be an Array of Interaction objects"
+        end
+        valid_prompt = prompt.nil? || (prompt.is_a?(Regexp) && !prompt.match?(""))
+        unless valid_prompt
+          raise ArgumentError, "prompt must be a nonempty Regexp or nil"
+        end
+        raise ArgumentError, "sensitive must be true or false" unless [true, false].include?(sensitive)
+
+        @text = text.dup.freeze
+        @timeout = Expect.duration(timeout)
+        @interactions = interactions.dup.freeze
+        @prompt = prompt
+        @sensitive = sensitive
+        @source = source&.dup&.freeze
+        @line = line
+        freeze
+      end
+
+      # 判断命令文本是否需要脱敏。
+      def sensitive? = @sensitive
+
+      # 复制命令元数据，只替换命令文本。
+      def with_text(text)
+        self.class.new(text, timeout: timeout, interactions: interactions, prompt: prompt,
+                       sensitive: sensitive?, source: source, line: line)
+      end
+
+      # 返回命令来源摘要，不展开命令内容。
+      def inspect = "#<#{self.class} source=#{source.inspect} line=#{line.inspect}>"
+    end
+
+    # 在任何输入输出前解析，不执行脚本，也不改写设备命令中的行内注释。
+    class Script
+      include Enumerable
+
+      attr_reader :name
+
+      # 按行过滤空行和整行注释，再构造带来源信息的命令。
+      def self.parse(text, name: nil)
+        raise ArgumentError, "script must be a String" unless text.is_a?(String)
+
+        commands = text.each_line.with_index(1).filter_map do |line, number|
+          line = line.chomp
+          next if line.strip.empty? || line.lstrip.start_with?("#")
+
+          Command.new(line, source: name, line: number)
+        end
+        new(commands, name: name)
+      end
+
+      # 读取脚本文件；文件错误转换为带来源的脚本错误。
+      def self.load(path)
+        parse(File.binread(path), name: File.expand_path(path))
+      rescue IOError, SystemCallError
+        raise ScriptError.new("unable to read script", phase: :parse, source: path.to_s), cause: nil
+      end
+
+      # 校验并冻结命令数组，给非 Command 输入补充来源和行号。
+      def initialize(commands, name: nil)
+        raise ArgumentError, "commands must be an Array" unless commands.is_a?(Array)
+
+        @name = name&.dup&.freeze
+        @commands = commands.each_with_index.map do |command, index|
+          command.is_a?(Command) ? command : Command.new(command, source: name, line: index + 1)
+        end.freeze
+        freeze
+      end
+
+      # 遍历脚本命令。
+      def each(&) = @commands.each(&)
+
+      # 判断脚本是否没有可执行命令。
+      def empty? = @commands.empty?
+
+      # 返回脚本命令数量。
+      def size = @commands.size
+
+      # 返回脚本名称和命令数量摘要。
+      def inspect = "#<#{self.class} name=#{name.inspect} commands=#{size}>"
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "expect/pty"
+require_relative "dialogue"
+
+module Net
+  module Connector
+    # 显式且不可变的连接设置；环境变量读取由调用库的可执行程序负责。
+    class Configuration
+      attr_reader :host, :username, :password, :enable_password, :protocol, :port, :login_timeout,
+                  :command_timeout, :write_timeout, :max_output_bytes, :log_file, :log_format, :log_level,
+                  :known_hosts, :host_key_policy, :challenges, :logger
+
+      # 校验端点、凭据、超时、日志、主机密钥和挑战配置，然后冻结设置。
+      def initialize(host: nil, username: nil, password: nil, enable_password: nil, protocol: :ssh, port: nil,
+                     login_timeout: 10, command_timeout: nil, write_timeout: 10,
+                     max_output_bytes: 32 * 1024 * 1024, log_file: nil, logger: nil,
+                     log_format: :text, log_level: :info,
+                     known_hosts: nil, host_key_policy: :strict, telnet_fallback: false, legacy_ssh: false,
+                     challenges: [])
+        @host = frozen_string(host)
+        @username = frozen_string(username)
+        @password = single_line_credential(password)
+        @enable_password = single_line_credential(enable_password)
+        @protocol = enum_value(protocol, %i[ssh telnet], :protocol)
+        @port = port
+        valid_port = port.nil? || (port.is_a?(Integer) && (1..65_535).cover?(port))
+        unless valid_port
+          raise ArgumentError, "port must be in 1..65535"
+        end
+
+        @login_timeout = timeout_seconds(login_timeout, :login_timeout)
+        @command_timeout = command_timeout.nil? ? nil : timeout_seconds(command_timeout, :command_timeout)
+        @write_timeout = timeout_seconds(write_timeout, :write_timeout)
+        unless max_output_bytes.is_a?(Integer) && max_output_bytes.positive?
+          raise ArgumentError, "max_output_bytes must be a positive Integer"
+        end
+
+        @max_output_bytes = max_output_bytes
+        @log_file = absolute_path(log_file)
+        if logger && (!logger.respond_to?(:debug) || !logger.respond_to?(:info) ||
+          !logger.respond_to?(:warn) || !logger.respond_to?(:error) ||
+          !logger.respond_to?(:formatter) || !logger.respond_to?(:level))
+          raise ArgumentError, "logger must be Logger-compatible"
+        end
+        raise ArgumentError, "logger and log_file cannot be combined" if logger && @log_file
+        @log_format = enum_value(log_format, %i[raw text], :log_format)
+        raise ArgumentError, "logger cannot be combined with raw logging" if logger && @log_format == :raw
+
+        @logger = logger
+        @log_level = enum_value(log_level, %i[debug info warn error], :log_level)
+        @known_hosts = absolute_path(known_hosts)
+        @host_key_policy = enum_value(host_key_policy, %i[strict accept_new replace], :host_key_policy)
+        if @host_key_policy == :replace && !@known_hosts
+          raise ArgumentError, "host_key_policy :replace requires an explicit known_hosts file"
+        end
+
+        @telnet_fallback = boolean_value(telnet_fallback)
+        @legacy_ssh = boolean_value(legacy_ssh)
+        unless challenges.is_a?(Array) && challenges.all?(Interaction)
+          raise ArgumentError, "challenges must be an Array of Interaction objects"
+        end
+
+        @challenges = challenges.dup.freeze
+        freeze
+      end
+
+      # 判断是否允许 SSH 失败后回退到 Telnet。
+      def telnet_fallback? = @telnet_fallback
+
+      # 判断是否允许使用旧版 SSH 协商参数恢复。
+      def legacy_ssh? = @legacy_ssh
+
+      # 校验最终连接主机和用户名能安全进入外部命令参数。
+      def validate_endpoint!
+        unless host.is_a?(String) && /\A[A-Za-z0-9:][A-Za-z0-9.:%_-]*\z/.match?(host)
+          raise ArgumentError, "host must be a device address or hostname"
+        end
+        return if username.is_a?(String) && /\A[A-Za-z0-9_][A-Za-z0-9_.@$\\-]*\z/.match?(username)
+
+        raise ArgumentError, "username is empty or contains unsupported characters"
+      end
+
+      # 返回不包含凭据的连接配置摘要。
+      def inspect = "#<#{self.class} host=#{host.inspect} protocol=#{protocol.inspect}>"
+
+      private
+
+      # 将可选值校验为字符串副本。
+      def frozen_string(value)
+        return nil if value.nil?
+        raise ArgumentError, "expected a String or nil" unless value.is_a?(String)
+
+        value.dup.freeze
+      end
+
+      # 校验凭据是单行文本。
+      def single_line_credential(value)
+        value = frozen_string(value)
+        raise ArgumentError, "credentials must be a single line" if value&.match?(/[\r\n\x00]/)
+
+        value
+      end
+
+      # 将路径转换为绝对冻结文本。
+      def absolute_path(value) = value.nil? ? nil : File.expand_path(frozen_string(value)).freeze
+
+      # 将超时转换为有限秒数。
+      def timeout_seconds(value, name)
+        result = Expect.duration(value)
+        raise ArgumentError, "#{name} must be finite" unless result
+
+        result
+      end
+
+      # 校验布尔设置只能是 true 或 false。
+      def boolean_value(value)
+        raise ArgumentError, "expected true or false" unless [true, false].include?(value)
+
+        value
+      end
+
+      # 将枚举输入转换为允许的符号。
+      def enum_value(value, choices, name)
+        return value.to_sym if value.respond_to?(:to_sym) && choices.include?(value.to_sym)
+
+        raise ArgumentError, "#{name} must be one of #{choices.join(", ")}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "dialogue"
+require_relative "session"
+require_relative "execution"

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

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "terminal_renderer"
+require "expect/pty"
+
+module Net
+  module Connector
+    # 一组提示与响应规则；可调用响应支持一次性密码等动态挑战。
+    class Interaction
+      attr_reader :pattern, :limit
+
+      # 校验提示模式、响应类型和次数限制，然后冻结规则定义。
+      def initialize(pattern, response, sensitive: false, limit: nil, capture: true)
+        unless pattern.is_a?(Regexp) && !pattern.match?("")
+          raise ArgumentError, "interaction pattern must be a nonempty Regexp"
+        end
+        unless response.is_a?(String) || response.respond_to?(:call)
+          raise ArgumentError, "response must be a String or callable"
+        end
+        valid_limit = limit.nil? || (limit.is_a?(Integer) && limit.positive?)
+        unless valid_limit
+          raise ArgumentError, "limit must be positive or nil"
+        end
+        unless [true, false].include?(sensitive) && [true, false].include?(capture)
+          raise ArgumentError, "sensitive and capture must be true or false"
+        end
+
+        @pattern = pattern
+        @response = response.is_a?(String) ? response.dup.freeze : response
+        @sensitive = sensitive
+        @limit = limit
+        @capture = capture
+        freeze
+      end
+
+      # 根据当前提示计算响应文本或调用动态响应函数。
+      def response(prompt) = @response.respond_to?(:call) ? @response.call(prompt) : @response
+
+      # 判断响应是否需要从日志和错误上下文中脱敏。
+      def sensitive? = @sensitive
+
+      # 判断提示文本是否应保留在响应输出中。
+      def capture? = @capture
+
+      # 返回不包含响应内容的规则摘要。
+      def inspect = "#<#{self.class} sensitive=#{sensitive?}>"
+
+      # 将普通交互转换为一次性的敏感挑战。
+      def challenge
+        self.class.new(pattern, @response, sensitive: true, limit: limit || 1, capture: false)
+      end
+    end
+
+    # 每台设备一份不可变对话语法，由厂商方法组装而不是合并默认值。
+    class Dialogue
+      attr_reader :login_prompt, :command_prompt, :password_prompt, :username_prompt, :enable_prompt,
+                  :authentication_errors, :command_errors, :login_interactions, :command_interactions
+
+      # 校验提示和交互列表，并冻结整套设备对话语法。
+      def initialize(login_prompt:, command_prompt:, password_prompt:, username_prompt:, enable_prompt:,
+                     authentication_errors:, command_errors:, login_interactions:, command_interactions:)
+        @login_prompt = login_prompt
+        @command_prompt = command_prompt
+        @password_prompt = password_prompt
+        @username_prompt = username_prompt
+        @enable_prompt = enable_prompt
+        [login_prompt, command_prompt, password_prompt, username_prompt, enable_prompt].each do |pattern|
+          raise ArgumentError, "prompt must be a nonempty Regexp" unless pattern.is_a?(Regexp) && !pattern.match?("")
+        end
+        @authentication_errors = authentication_errors.freeze
+        @command_errors = command_errors.freeze
+        @login_interactions = login_interactions.freeze
+        @command_interactions = command_interactions.freeze
+        freeze
+      end
+
+      # 从命令输出中返回包含错误模式的诊断行，而不是光标或此前全部输出。
+      def diagnostic(output)
+        return if command_errors.empty?
+
+        # 先保留被回车覆写的失败，再识别颜色或退格处理后的可见诊断。
+        raw = output.gsub(/\r(?!\n)/, "\n")
+        diagnostic_line(raw) || (diagnostic_line(TerminalRenderer.render(output)) if output.match?(/[\e\b]/))
+      end
+
+      private
+
+      def diagnostic_line(output)
+        match = command_errors.lazy.filter_map { |pattern| pattern.match(output) }.first
+        return unless match
+
+        start = match.begin(0).positive? ? output.rindex(/[\r\n]/, match.begin(0) - 1) : nil
+        start = start ? start + 1 : 0
+        finish = output.index(/[\r\n]/, match.end(0)) || output.bytesize
+        output.byteslice(start, finish - start).strip
+      end
+    end
+
+    # 在厂商清理前保留原始字节，供诊断和日志使用。
+    class Response
+      attr_reader :raw, :output, :prompt
+
+      # 保存原始响应、清理后输出和命令结束提示，并冻结三者。
+      def initialize(raw:, output:, prompt:)
+        @raw = raw.freeze
+        @output = output.freeze
+        @prompt = prompt.freeze
+        freeze
+      end
+
+      # 返回响应大小摘要，不展开原始内容。
+      def inspect = "#<#{self.class} bytes=#{raw.bytesize}>"
+    end
+
+    # 在传输层上执行有界对话；收到字节或分页标记不会重置截止时间。
+    class ResponseReader
+      # 保存会话引用，以便读取器使用传输、配置和脱敏上下文。
+      def initialize(session)
+        @session = session
+      end
+
+      # 读取到结束提示、失败模式或超时，并处理交互响应和输出上限。
+      def read(prompt:, interactions:, phase:, timeout: nil, deadline: nil, command: nil, failures: {})
+        deadline ||= Expect.monotonic + timeout
+        patterns = [*failures.keys, *interactions.map(&:pattern), prompt]
+        raw = []
+        output = []
+        counts = Hash.new(0)
+        bytes = 0
+        loop do
+          event = @session.transport.read(patterns, timeout: [deadline - Expect.monotonic, 0].max)
+          raw << event.before unless event.before.empty?
+          output << event.before unless event.before.empty?
+          bytes += event.before.bytesize + event.match.bytesize
+          if bytes > @session.configuration.max_output_bytes
+            raise @session.error(OutputLimitExceeded, "device output exceeded max_output_bytes",
+                                 phase: phase, command: command, output: (raw + [event.match]).join), cause: nil
+          end
+          raise read_error(event, phase, command, raw.join), cause: nil unless event.matched?
+
+          if event.index == patterns.size
+            raw << event.match
+            output << event.match
+          elsif event.index == patterns.size - 1
+            if event.match.empty?
+              raise @session.error(PromptError, "prompt pattern did not consume any output",
+                                   phase: phase, command: command, output: raw.join), cause: nil
+            end
+
+            raw << event.match
+            output << event.match
+            raw_text = raw.join
+            return Response.new(raw: raw_text, output: (output == raw) ? raw_text : output.join, prompt: event.match)
+          elsif event.index < failures.size
+            klass, code = failures.values.fetch(event.index)
+            raise @session.error(klass, "device connection failed (#{code})", phase: phase,
+                                 code: code, command: command), cause: nil
+          else
+            reply = interactions.fetch(event.index - failures.size)
+            raw << event.match
+            output << event.match if reply.capture?
+            counts[reply] += 1
+            if event.match.empty? || (reply.limit && counts[reply] > reply.limit)
+              raise interaction_error("response rejected or repeated", phase, command), cause: nil
+            end
+
+            value = interaction_response(reply, event.match, phase, command)
+            raise interaction_error("response unavailable", phase, command), cause: nil unless value.is_a?(String)
+
+            @session.redactor.remember(value.chomp) if reply.sensitive?
+            @session.write(value, deadline: deadline, phase: phase, command: command)
+          end
+          next if Expect.monotonic < deadline
+
+          raise read_error(nil, phase, command, raw.join), cause: nil
+        end
+      end
+
+      private
+
+      # 动态口令尚未返回时无法加入词表，须在敏感范围内先归一化回调异常。
+      # 成功后由调用方登记响应，临时敏感标记不会影响后续普通命令的诊断。
+      def interaction_response(reply, prompt, phase, command)
+        return reply.response(prompt) unless reply.sensitive?
+
+        @session.redactor.scope(reuse: true) do
+          @session.redactor.sensitive!
+          reply.response(prompt)
+        rescue => error
+          raise @session.normalize_error(error, phase: phase, command: command), cause: nil
+        end
+      end
+
+      # 将交互拒绝或响应缺失转换为认证或脚本错误。
+      def interaction_error(message, phase, command)
+        authenticating = %i[login enable].include?(phase)
+        klass = authenticating ? AuthenticationError : ScriptError
+        label = authenticating ? "authentication" : "command interaction"
+        @session.error(klass, "#{label} #{message}", phase: phase, command: command)
+      end
+
+      # 根据 EOF、提示符、阶段和底层异常选择具体读取错误类型。
+      def read_error(event, phase, command, output)
+        if event&.error.is_a?(Exception)
+          return @session.error(TransportError, "transport read failed", phase: phase, command: command,
+                                underlying: event.error, output: output)
+        end
+        klass = if event&.error == :eof
+                  ConnectionClosed
+                elsif command&.prompt
+                  PromptError
+                elsif %i[login enable].include?(phase)
+                  LoginTimeout
+                else
+                  CommandTimeout
+                end
+        @session.error(klass, "device response #{event&.error || :timeout}", phase: phase,
+                       command: command, output: output)
+      end
+    end
+  end
+end