net-connector 0.4.2 → 0.5.0

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "expect/redactor"
+require_relative "error_metadata"
 
 module Net
   module Connector
@@ -22,6 +23,19 @@ module Net
         @underlying = underlying
       end
 
+      # 内置错误保留业务回执，但不复制可能含秘密的原生 cause 和调用栈。
+      # 自定义子类重新构造，避免其 message 等方法继续读取未脱敏的私有字段。
+      def with_diagnostics(message:, **context)
+        context = { code: code, host: host, phase: phase, command: command, output: output,
+                    source: source, line: line, underlying: underlying }.merge(context)
+        return self.class.new(message, **context) unless ErrorMetadata.known_type?(self.class.name)
+
+        copy = self.class.allocate
+        instance_variables.each { |name| copy.instance_variable_set(name, instance_variable_get(name)) }
+        Error.instance_method(:initialize).bind_call(copy, message, **context)
+        copy
+      end
+
       # 返回不展开命令和输出的错误摘要。
       def inspect = "#<#{self.class} code=#{code.inspect} phase=#{phase.inspect} host=#{host.inspect}>"
     end
@@ -101,7 +115,7 @@ module Net
       end
 
       # 临时命令响应在错误归一化期间保留，离开作用域后不进入长期会话。
-      def scope(reuse: false)
+      def with_scope(reuse: false)
         return yield if reuse && @scoped
 
         previous = @secrets

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

@@ -20,12 +20,16 @@ module Net
         @steps = []
         @output_bytes = 0
         @output_limit = session.configuration.max_script_output_bytes
+        @sensitive = false
       end
 
+      # 汇总实际执行的命令及交互，包括批次准备和厂商追加查询。
+      def sensitive? = @sensitive
+
       # 依次准备、执行和记录脚本命令；失败时保留已完成步骤并统一抛错。
-      def execute(script)
+      def execute_script(script)
         script.each do |original|
-          @session.command_scope(original) do
+          @session.with_command_redaction(original) do
             @current_command = original
             command = @prepare_command.call(original, self)
             next unless command
@@ -33,7 +37,7 @@ module Net
             @current_command = command
             started = Expect.monotonic
             step = nil
-            response = query(command) do |received|
+            response = execute_command(command) do |received|
               step = CommandResult.new(command: command, output: received.output, prompt: received.prompt,
                                        duration: Expect.monotonic - started)
               steps << step
@@ -51,13 +55,16 @@ module Net
       end
 
       # 厂商后续查询复用同一信道和错误处理，不开启新的批处理。
-      def query(command)
+      def execute_command(command)
         command = Command.new(command) unless command.is_a?(Command)
         check_output_budget!(command, completed: false)
         prompt = @prompt&.call(command)
         # 提示符回调也可能追加查询，实际发送前重新检查它消耗的预算。
         check_output_budget!(command, completed: false) if @prompt
-        response = @session.exchange(command, timeout: @command_timeout, prompt: prompt)
+        response = @session.execute_command(command, timeout: @command_timeout, prompt: prompt) do
+          # 必须在 Session 恢复命令词表前读取；最终处理只能继承敏感性，不长期保留秘密。
+          @sensitive ||= @session.redactor.sensitive?
+        end
         @last_query_command = command
         @output_bytes += response.raw.bytesize
         # 主命令先记录完整步骤，再检查超额；追加查询同样计入预算，但不改变原 steps 结构。
@@ -72,8 +79,8 @@ module Net
       end
 
       # 根据当前命令建立脚本阶段错误。
-      def failure(message)
-        @session.error(ScriptError, message, phase: :script, command: @current_command)
+      def build_error(message)
+        @session.build_error(ScriptError, message, phase: :script, command: @current_command)
       end
 
       private
@@ -82,7 +89,7 @@ module Net
       def check_output_budget!(command, completed:)
         return unless @output_limit && (completed ? @output_bytes > @output_limit : @output_bytes >= @output_limit)
 
-        raise @session.error(ScriptOutputLimitExceeded,
+        raise @session.build_error(ScriptOutputLimitExceeded,
                              "script output reached max_script_output_bytes; commands already sent may have executed",
                              phase: :script, command: command), cause: nil
       end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../terminal_renderer"
+require_relative "messages"
+
+module Net
+  module Connector
+    class Log
+      # 在敏感作用域结束前冻结安全副本；应用 formatter 可直接读取字段。
+      class Event
+        attr_reader :name, :fields
+
+        def initialize(name, fields, redactor:)
+          @name = safe_text(name.is_a?(String) || name.is_a?(Symbol) ? name.to_s : "custom", redactor).freeze
+          @fields = fields.each_with_object({}) do |(key, value), result|
+            next unless (key.is_a?(Symbol) || key.is_a?(String)) && key.to_s.match?(/\A[a-z][a-z0-9_]{0,63}\z/)
+            next unless redactor.call(key.to_s) == key.to_s
+            next if key.to_s == "event"
+
+            result[key.to_sym] = safe_value(value, redactor)
+          end.freeze
+          freeze
+        end
+
+        # 与文本呈现共用同一安全记录，调用方不能借 formatter 取得原始秘密。
+        def to_h = { event: name, **fields }.freeze
+
+        def to_s
+          details = to_h.reject { |key, _| key == :host }.map { |key, value| "#{key}=#{token(value)}" }.join(" ")
+          "[host=#{token(fields[:host])}] #{Messages.format(name, fields)} | #{details}"
+        end
+
+        # Ruby Logger 的默认 formatter 对非 String 消息调用 inspect。
+        alias inspect to_s
+
+        private
+
+        def safe_value(value, redactor)
+          case value
+          when String, Symbol
+            safe_text(value.to_s, redactor).freeze
+          when Float
+            value.finite? && redactor.call(value.to_s) == value.to_s ? value : "[REDACTED]"
+          when Integer, TrueClass, FalseClass, NilClass
+            redactor.call(value.to_s) == value.to_s ? value : "[REDACTED]"
+          else
+            # 不调用任意对象的 inspect/to_s，避免展开异常、配置对象或容器中的秘密。
+            "[REDACTED]"
+          end
+        end
+
+        def safe_text(text, redactor)
+          rendered = TerminalRenderer.render(redactor.call(text))
+          redactor.call(rendered).force_encoding(Encoding::UTF_8).scrub.gsub(/[[:cntrl:]]+/, " ").strip
+        end
+
+        def token(value)
+          return "nil" if value.nil?
+
+          text = value.to_s
+          text.match?(/\A[A-Za-z0-9_.:\/-]+\z/) ? text : text.inspect
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Net
+  module Connector
+    class Log
+      # 只安装在连接器自有的 Logger 上；注入的日志器保留应用自己的格式。
+      class Formatter < ::Logger::Formatter
+        def call(severity, time, _program, message)
+          "[#{time.getlocal.strftime("%Y-%m-%d %H:%M:%S.%L %:z")}] #{severity} #{message}\n"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Log
+      # 独立于日志目标的人类可读事件文案。
+      module Messages
+        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 "operation_start"
+            "开始处理设备脚本"
+          when "operation_complete"
+            fields[:status] == "completed" ? "设备脚本处理完成" :
+              "设备脚本处理失败：#{fields[:message]}（#{fields[:error]}）"
+          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
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Log
+      # 每个目标独占 expect-pty 的过滤流；此层只适配 IO，不实现匹配算法。
+      class RedactingWriter
+        def initialize(target, redactor)
+          @target = target
+          @redactor = redactor
+          @filter = redactor.stream
+        end
+
+        def write(bytes)
+          @filter.patterns = @redactor.patterns
+          @target.write(@filter.append(bytes.b))
+          bytes.bytesize
+        end
+
+        def flush = @target.flush
+
+        def finish
+          @filter.patterns = @redactor.patterns
+          # 配置正文由 Session 的敏感范围隔离；保留完整词匹配的收尾契约。
+          @target.write(@filter.finish(partial: false))
+          flush
+        end
+      end
+
+      # 已渲染、已脱敏的字节按行变成事件，半行在上下文切换前收尾。
+      class Transcript
+        def initialize(&on_line)
+          @on_line = on_line
+          @buffer = +"".b
+        end
+
+        def write(bytes)
+          @buffer << bytes
+          while (ending = @buffer.index("\n"))
+            @on_line.call(@buffer.slice!(0, ending + 1).chomp)
+          end
+          bytes.bytesize
+        end
+
+        def flush; end
+
+        def finish
+          @on_line.call(@buffer) unless @buffer.empty?
+          @buffer = +"".b
+        end
+      end
+
+      private_constant :RedactingWriter, :Transcript
+    end
+  end
+end

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

@@ -2,9 +2,13 @@
 
 require "fileutils"
 require "logger"
+require "securerandom"
 require_relative "terminal_renderer"
-require_relative "log_messages"
+require_relative "log/event"
+require_relative "log/formatter"
+require_relative "log/stream"
 require_relative "errors"
+require_relative "error_metadata"
 
 module Net
   module Connector
@@ -12,39 +16,56 @@ module Net
     class Log
       LEVELS = { debug: ::Logger::DEBUG, info: ::Logger::INFO,
                  warn: ::Logger::WARN, error: ::Logger::ERROR }.freeze
+      CONTEXT_FIELDS = %w[host session_id operation command_id text source line].freeze
+      private_constant :CONTEXT_FIELDS
 
       # 保存日志配置和敏感信息脱敏器。
       def initialize(configuration, redactor:)
         @configuration = configuration
         @redactor = redactor
+        @context = {}.freeze
       end
 
       # 为会话打开日志文件或应用日志器。
       def open(transport)
         @transport = transport
+        @session_id = SecureRandom.hex(8).freeze
+        @command_sequence = 0
         @io = open_file(@configuration.log_file) if @configuration.log_file
-        @output = RedactingWriter.new(@io, @redactor) if @io
         if @configuration.log_format == :raw
-          @writer = @output
+          @writer = @output = RedactingWriter.new(@io, @redactor) if @io
         elsif @io || @configuration.logger
-          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 = 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
+          @logger = @configuration.logger || ::Logger.new(@io, formatter: Formatter.new)
+          open_transcript if @io && @configuration.log_level == :debug
         end
-        @line_open = false
       rescue => error
         close_preserving_error
-        raise failure("unable to open session log", error), cause: nil
+        raise build_error("unable to open session log", error), cause: nil
+      end
+
+      # 上下文只在持有会话锁期间使用；收尾必须先于恢复父上下文。
+      def with_context(**fields)
+        previous = @context
+        finish_output
+        @context = @context.merge(fields).freeze
+        yield
+      ensure
+        begin
+          finish_output
+        ensure
+          @context = previous
+        end
+      end
+
+      def with_operation_context(name, &block)
+        with_context(operation: name || @context[:operation] || :script, &block)
+      end
+
+      def with_command_context(command, &block)
+        @command_sequence += 1
+        with_context(command_id: @command_sequence, phase: :command,
+                     text: command.sensitive? ? "[REDACTED]" : command.text,
+                     source: command.source, line: command.line, &block)
       end
 
       # 将终端回显接入当前会话日志。
@@ -56,60 +77,75 @@ module Net
       end
 
       # 判断当前日志级别是否需要完整设备回显。
-      def detailed? = @configuration.log_level == :debug && !!(@writer || @logger)
+      def debug? = @configuration.log_level == :debug && (!!@writer || enabled?(:debug))
 
       # 按日志级别写入已脱敏的业务事件。
-      def event(name, level: :info, **fields)
+      def log_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, "#{@tag}#{LogMessages.format(safe_name, values)}") if LEVELS.fetch(level) >= @event_level
+        finish_output
+        write_event(name, level: level, **fields)
       rescue Error
         raise
       rescue => error
-        raise failure("unable to write session event", error), cause: nil
+        raise build_error("unable to write session event", error), cause: nil
       end
 
-      # 登录完成并收集动态口令后，再记录已脱敏的认证回显。
-      def authentication_output(bytes)
-        return unless detailed?
+      # 异常正文由会话先脱敏；类型、错误码和阶段只允许共享词表中的值进入日志。
+      def log_failure(name, failure, phase: nil, **fields)
+        log_event(name, level: :error, **fields,
+                  error: ErrorMetadata.type(failure.class.name) || "StandardError",
+                  code: ErrorMetadata.code(failure.code),
+                  phase: ErrorMetadata.phase(failure.phase) || ErrorMetadata.phase(phase),
+                  message: failure.message)
+      end
 
-        event("login_output", level: :debug)
-        if @writer
-          write(@redactor.call(bytes))
-          flush
+      # 用户钩子可能把未登记的配置片段放进事件名、字段名或值；敏感范围统一隐藏。
+      def log_custom_event(name, level: :info, **fields)
+        if @redactor.sensitive?
+          log_event("custom", level: level, details: "[REDACTED]")
         else
-          response_output(bytes)
+          log_event(name, level: level, **fields)
         end
       end
 
-      # 应用注入的日志器没有终端写入器，改由日志器记录完整回显。
-      def response_output(bytes)
-        return unless detailed? && !@writer && !@redactor.output_sensitive?
+      # 登录完成并收集动态口令后，再记录已脱敏的认证回显。
+      def log_authentication_output(bytes)
+        return unless debug?
+
+        with_context(phase: :login) do
+          log_event("login_output", level: :debug)
+          if @writer
+            write(@redactor.call(bytes))
+            flush
+          else
+            log_response_output(bytes)
+          end
+        end
+      end
+
+      # 注入日志器与文件回显共用事件格式；两次脱敏覆盖终端控制符拼接。
+      def log_response_output(bytes)
+        return unless debug? && !@writer && !@redactor.output_sensitive?
 
         @redactor.call(TerminalRenderer.render(@redactor.call(bytes))).each_line do |line|
-          @logger.debug("#{@tag}  #{line.chomp}") if ::Logger::DEBUG >= @event_level
+          write_event("device_output", level: :debug, output: line.chomp)
         end
       rescue Error
         raise
       rescue => error
-        raise failure("unable to write device output", error), cause: nil
+        raise build_error("unable to write device output", error), cause: nil
       end
 
       # 向终端日志写入已处理的回显字节。
       def write(bytes)
-        return unless @writer
+        return unless @writer && !@redactor.output_sensitive?
 
         @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
+        raise build_error("unable to write session log", error), cause: nil
       end
 
       # 刷新日志缓冲区。
@@ -119,7 +155,7 @@ module Net
       rescue Error
         raise
       rescue => error
-        raise failure("unable to flush session log", error), cause: nil
+        raise build_error("unable to flush session log", error), cause: nil
       end
 
       # 执行代码块期间暂停自动记录传输回显。
@@ -140,63 +176,48 @@ module Net
           begin
             @io&.close
           ensure
-            @writer = @output = @logger = @io = @transport = @tag = @event_level = nil
+            @writer = @output = @transcript = @logger = @io = @transport = @session_id = nil
             @attached = false
           end
         end
       rescue Error
         raise
       rescue => error
-        raise failure("unable to close session log", error), cause: nil
+        raise build_error("unable to close session log", error), cause: nil
       end
 
       private
 
-      # 结束未换行的回显，保持事件独占一行。
-      def finish_line
-        return unless @writer
+      # 每次读取调用方的当前阈值，不缓存级别、不改写共享 Logger。
+      def enabled?(level)
+        @logger && LEVELS.fetch(level) >= [@logger.level, LEVELS.fetch(@configuration.log_level)].max
+      end
 
-        finish_output
-        @io.write("\n") if @line_open
-        @line_open = false
+      def write_event(name, level:, **fields)
+        return unless enabled?(level)
+
+        values = @context.compact.merge(fields.reject { |key, _| CONTEXT_FIELDS.include?(key.to_s) })
+        values = values.merge(host: @configuration.host, session_id: @session_id)
+        @logger.public_send(level, Event.new(name, values, redactor: @redactor))
+      end
+
+      def open_transcript
+        @transcript = Transcript.new { |line| write_event("device_output", level: :debug, output: line) }
+        @output = RedactingWriter.new(@transcript, @redactor)
+        @writer = TerminalRenderer.new(@output, max_line_bytes: @configuration.max_output_bytes)
       end
 
-      # 先完成终端渲染，再写出脱敏流的最后几个字节。
+      # 先渲染，再结束过滤流，最后发出半行事件；顺序不能反转。
       def finish_output
         @writer.finish if @writer.respond_to?(:finish)
         @output&.finish unless @output.equal?(@writer)
+        @transcript&.finish
+      rescue Error
+        raise
+      rescue => error
+        raise build_error("unable to finish session output", error), cause: nil
       end
 
-      # 文件写入边界保留短尾部，避免分片或终端控制符拼出明文凭据。
-      class RedactingWriter
-        # 保存目标与作用域；每个日志目标独占 expect-pty 的过滤流。
-        def initialize(target, redactor)
-          @target = target
-          @redactor = redactor
-          @filter = redactor.stream
-        end
-
-        # 写入已确认安全的前缀，暂存可能与下一分片组成秘密的尾部。
-        def write(bytes)
-          @filter.patterns = @redactor.patterns
-          @target.write(@filter.append(bytes.b))
-          bytes.bytesize
-        end
-
-        # 刷新目标流，仍不提前写出待判断的尾部。
-        def flush = @target.flush
-
-        # 在日志结束时脱敏并写出剩余尾部。
-        def finish
-          @filter.patterns = @redactor.patterns
-          # 保留旧日志的完整词匹配契约；配置正文由 Session 的敏感范围直接隔离。
-          @target.write(@filter.finish(partial: false))
-          flush
-        end
-      end
-
-      private_constant :RedactingWriter
-
       # 以私有权限打开设备日志文件。
       def open_file(path)
         FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
@@ -224,7 +245,7 @@ module Net
       end
 
       # 将日志异常包装成统一错误并保留脱敏原因。
-      def failure(message, error)
+      def build_error(message, error)
         LogError.new(message, phase: :logging,
                      underlying: UnderlyingError.new(error, @redactor, sensitive: @redactor.sensitive?))
       end