net-connector 0.4.0 → 0.4.2

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

@@ -8,13 +8,13 @@ module Net
     # 显式且不可变的连接设置；环境变量读取由调用库的可执行程序负责。
     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,
+                  :command_timeout, :write_timeout, :max_output_bytes, :max_script_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,
+                     max_output_bytes: 32 * 1024 * 1024, max_script_output_bytes: nil, 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: [])
@@ -32,11 +32,8 @@ module Net
         @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
+        @max_output_bytes = positive_integer(max_output_bytes, :max_output_bytes)
+        @max_script_output_bytes = positive_integer(max_script_output_bytes, :max_script_output_bytes) unless max_script_output_bytes.nil?
         @log_file = absolute_path(log_file)
         if logger && (!logger.respond_to?(:debug) || !logger.respond_to?(:info) ||
           !logger.respond_to?(:warn) || !logger.respond_to?(:error) ||
@@ -86,6 +83,12 @@ module Net
 
       private
 
+      def positive_integer(value, name)
+        raise ArgumentError, "#{name} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+
+        value
+      end
+
       # 将可选值校验为字符串副本。
       def frozen_string(value)
         return nil if value.nil?

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
@@ -129,47 +130,24 @@ module Net
         counts = Hash.new(0)
         bytes = 0
         loop do
-          event = @session.transport.read(patterns, timeout: [deadline - Expect.monotonic, 0].max)
+          event = read_event(patterns, deadline)
           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?
+          validate_event(event, bytes, raw, phase, command)
 
           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)
+            return finish_response(event.match, raw, output, phase, command)
           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
+            raise connection_error(failures.values.fetch(event.index), phase, 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)
+            respond(reply, event.match, counts, deadline, phase, command)
           end
           next if Expect.monotonic < deadline
 
@@ -179,6 +157,53 @@ module Net
 
       private
 
+      # 分页和流式输出只消耗剩余时间，不为下一次读取重新计时。
+      def read_event(patterns, deadline)
+        @session.transport.read(patterns, timeout: [deadline - Expect.monotonic, 0].max)
+      end
+
+      # 连接失败模式携带稳定错误码，供连接级恢复规则选择处理方式。
+      def connection_error(failure, phase, command)
+        klass, code = failure
+        @session.error(klass, "device connection failed (#{code})", phase: phase, code: code, command: command)
+      end
+
+      # 先限制原始字节数，再处理传输失败，避免错误输出绕过总量限制。
+      def validate_event(event, bytes, raw, phase, command)
+        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?
+      end
+
+      # 完整提示符必须消费字节；交互标记可从业务输出排除，但原始响应始终保留。
+      def finish_response(prompt, raw, output, phase, command)
+        if prompt.empty?
+          raise @session.error(PromptError, "prompt pattern did not consume any output",
+                               phase: phase, command: command, output: raw.join), cause: nil
+        end
+
+        raw << prompt
+        output << prompt
+        raw_text = raw.join
+        Response.new(raw: raw_text, output: (output == raw) ? raw_text : output.join, prompt: prompt)
+      end
+
+      # 重复提示和缺失应答必须在写入前失败；所有应答共用读取操作的截止时间。
+      def respond(reply, prompt, counts, deadline, phase, command)
+        counts[reply] += 1
+        if prompt.empty? || (reply.limit && counts[reply] > reply.limit)
+          raise interaction_error("response rejected or repeated", phase, command), cause: nil
+        end
+
+        value = interaction_response(reply, prompt, 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
+
       # 动态口令尚未返回时无法加入词表，须在敏感范围内先归一化回调异常。
       # 成功后由调用方登记响应，临时敏感标记不会影响后续普通命令的诊断。
       def interaction_response(reply, prompt, phase, command)

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

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "expect/redactor"
+
 module Net
   module Connector
-    # 操作错误携带已脱敏上下文；原始配置只存在于明确的结果或日志中。
+    # 操作错误携带已脱敏上下文；敏感配置正文只存在于明确返回的业务结果中。
     class Error < StandardError
       attr_reader :code, :host, :phase, :command, :output, :source, :line, :underlying
 
@@ -48,6 +50,8 @@ module Net
 
     class OutputLimitExceeded < Error; end
 
+    class ScriptOutputLimitExceeded < OutputLimitExceeded; end
+
     class SessionBusy < Error; end
 
     class UnsupportedOperation < Error; end
@@ -72,10 +76,16 @@ module Net
       def inspect = "#<#{self.class} type=#{type}>"
     end
 
-    # 每个会话独立保存脱敏词，包括配置凭据和动态认证响应。
+    # 管理连接器的秘密作用域和输出敏感性；字节过滤统一委托给 expect-pty。
     class Redactor
+      MASK = "[REDACTED]".b.freeze
+
       # 保存初始凭据，并建立第一版脱敏词表。
       def initialize(*secrets)
+        unless Expect.constants(false).include?(:Redactor) && Expect::Redactor.respond_to?(:redact)
+          raise LoadError, "net-connector requires expect-pty with the public Expect::Redactor API"
+        end
+
         @configured = secrets.compact.map(&:b).map(&:freeze).freeze
         reset
       end
@@ -83,9 +93,10 @@ module Net
       # 重置动态词表，同时保留配置中的固定凭据。
       def reset
         @secrets = []
-        @pattern = nil
+        @patterns = nil
         @scoped = false
         @sensitive = false
+        @output_sensitive = false
         @configured.each { |secret| remember(secret) }
       end
 
@@ -94,27 +105,39 @@ module Net
         return yield if reuse && @scoped
 
         previous = @secrets
-        previous_pattern = @pattern
+        previous_patterns = @patterns
         previous_scoped = @scoped
         previous_sensitive = @sensitive
+        previous_output_sensitive = @output_sensitive
         @secrets = previous.dup
         @scoped = true
         begin
           yield
         ensure
           @secrets = previous
-          @pattern = previous_pattern
+          @patterns = previous_patterns
           @scoped = previous_scoped
           @sensitive = previous_sensitive
+          @output_sensitive = previous_output_sensitive
         end
       end
 
       # 敏感命令和交互的异常可能只引用秘密的一部分，不能只依赖完整词匹配。
       def sensitive! = @sensitive = true
 
+      # 判断当前脱敏范围是否包含敏感交互。
       def sensitive? = @sensitive
 
-      # 记住新的敏感字节，并按长度排序避免短词先匹配。
+      # 输出敏感时不把正文加入词表；只在当前范围内屏蔽日志和任意错误正文。
+      def output_sensitive!
+        @output_sensitive = true
+        sensitive!
+      end
+
+      # 后续查询继承输出边界，即使查询命令本身没有敏感标记。
+      def output_sensitive? = @output_sensitive
+
+      # 只维护当前作用域的注册词；匹配次序和重叠区间交给共享过滤器。
       def remember(secret)
         return if secret.nil? || secret.empty?
 
@@ -122,62 +145,26 @@ module Net
         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..)]
+        @patterns = nil
       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..)
+        Expect::Redactor.redact(text.to_s.b, patterns, replacement: MASK)
       end
 
-      # 返回脱敏器类型摘要。
-      def inspect = "#<#{self.class}>"
-
-      private
-
-      # 前瞻保留重叠匹配；跨标记边界的真实秘密不能被已有标记遮蔽。
-      def pattern
-        @pattern ||= /(?=(#{Regexp.union((@secrets + ["[REDACTED]"]).uniq.sort_by { |secret| -secret.bytesize })}))/n
+      # 每个日志目标独占过滤流，跨分片尾部和重叠掩码由依赖库维护。
+      def stream
+        Expect::Redactor.new(patterns, replacement: MASK)
       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
+      # 临时范围恢复时，日志流可以同步恢复注册词表，不缓存配置正文。
+      def patterns
+        @patterns ||= (@secrets.empty? ? [] : (@secrets + [MASK]).uniq).freeze
       end
+
+      # 返回脱敏器类型摘要。
+      def inspect = "#<#{self.class}>"
     end
   end
 end

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

@@ -18,6 +18,8 @@ module Net
         @prompt = prompt
         @context = {}
         @steps = []
+        @output_bytes = 0
+        @output_limit = session.configuration.max_script_output_bytes
       end
 
       # 依次准备、执行和记录脚本命令；失败时保留已完成步骤并统一抛错。
@@ -30,24 +32,38 @@ module Net
 
             @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
+            step = nil
+            response = query(command) do |received|
+              step = CommandResult.new(command: command, output: received.output, prompt: received.prompt,
+                                       duration: Expect.monotonic - started)
+              steps << step
+            end
             # 设备已经完成命令；后处理失败也不能从部分结果中抹去其副作用。
             @after_command.call(command, response, self)
             yield step if block_given?
+            check_output_budget!(@last_query_command, completed: true)
           rescue => error
             raise @session.normalize_error(error, phase: :script, command: @current_command), cause: nil
           end
         end
+        check_output_budget!(@last_query_command, completed: true)
         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))
+        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)
+        @last_query_command = command
+        @output_bytes += response.raw.bytesize
+        # 主命令先记录完整步骤，再检查超额；追加查询同样计入预算，但不改变原 steps 结构。
+        yield response if block_given?
+        check_output_budget!(command, completed: true)
+        response
       end
 
       # 只有当前会话未特权时才执行特权认证。
@@ -59,6 +75,17 @@ module Net
       def failure(message)
         @session.error(ScriptError, message, phase: :script, command: @current_command)
       end
+
+      private
+
+      # 单响应上限仍约束正在读取的命令；累计预算阻止继续发送，不承诺设备尚未执行。
+      def check_output_budget!(command, completed:)
+        return unless @output_limit && (completed ? @output_bytes > @output_limit : @output_bytes >= @output_limit)
+
+        raise @session.error(ScriptOutputLimitExceeded,
+                             "script output reached max_script_output_bytes; commands already sent may have executed",
+                             phase: :script, command: command), cause: nil
+      end
     end
   end
 end

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
@@ -89,10 +89,10 @@ module Net
 
       # 应用注入的日志器没有终端写入器，改由日志器记录完整回显。
       def response_output(bytes)
-        return unless detailed? && !@writer
+        return unless detailed? && !@writer && !@redactor.output_sensitive?
 
         @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,27 +169,32 @@ module Net
 
       # 文件写入边界保留短尾部，避免分片或终端控制符拼出明文凭据。
       class RedactingWriter
+        # 保存目标与作用域；每个日志目标独占 expect-pty 的过滤流。
         def initialize(target, redactor)
           @target = target
           @redactor = redactor
-          @pending = "".b
+          @filter = redactor.stream
         end
 
+        # 写入已确认安全的前缀，暂存可能与下一分片组成秘密的尾部。
         def write(bytes)
-          @pending << bytes.b
-          safe, @pending = @redactor.stream_chunk(@pending)
-          @target.write(safe)
+          @filter.patterns = @redactor.patterns
+          @target.write(@filter.append(bytes.b))
           bytes.bytesize
         end
 
+        # 刷新目标流，仍不提前写出待判断的尾部。
         def flush = @target.flush
 
+        # 在日志结束时脱敏并写出剩余尾部。
         def finish
-          safe, @pending = @redactor.stream_chunk(@pending, final: true)
-          @target.write(safe)
+          @filter.patterns = @redactor.patterns
+          # 保留旧日志的完整词匹配契约；配置正文由 Session 的敏感范围直接隔离。
+          @target.write(@filter.finish(partial: false))
           flush
         end
       end
+
       private_constant :RedactingWriter
 
       # 以私有权限打开设备日志文件。
@@ -220,7 +225,8 @@ module Net
 
       # 将日志异常包装成统一错误并保留脱敏原因。
       def failure(message, error)
-        LogError.new(message, phase: :logging, underlying: UnderlyingError.new(error, @redactor))
+        LogError.new(message, phase: :logging,
+                     underlying: UnderlyingError.new(error, @redactor, sensitive: @redactor.sensitive?))
       end
     end
   end

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

@@ -10,6 +10,8 @@ module Net
   module Connector
     # 连接状态、传输层和日志的唯一所有者；同一时刻只允许一个操作占用会话。
     class Session
+      MAX_ERROR_OUTPUT_BYTES = 4096
+
       attr_reader :configuration, :transport, :reader, :redactor, :state, :prompt
 
       # 创建认证、响应读取、脱敏和日志对象，并把会话置于关闭状态。
@@ -75,6 +77,14 @@ module Net
         end
       end
 
+      # 文件业务必须先取得路径锁，再调用会话；不能持有会话租约去等待另一个备份者。
+      def assert_path_lock_order!(phase)
+        return unless @lock.locked?
+
+        raise error(SessionBusy, "backup path ownership must be acquired before a session operation", phase: phase), cause: nil
+      end
+
+      # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
       def perform_locked(phase)
         @performing = true
         completed = false
@@ -139,6 +149,19 @@ module Net
         end
       end
 
+      # 批次准备和最终清理也可能读取配置；在作用域退出前归一化其异常，
+      # 防止清理钩子的消息或回溯将已完成步骤中的正文带回诊断通道。
+      def output_scope(enabled)
+        return yield unless enabled
+
+        redactor.scope do
+          redactor.output_sensitive!
+          yield
+        rescue => error
+          raise normalize_error(error, phase: :script), cause: nil
+        end
+      end
+
       # 复用完整命令的脱敏范围；厂商后续查询产生的秘密保留到外层回调结束。
       def exchange(command, timeout:, prompt: nil)
         redactor.scope(reuse: true) do
@@ -146,9 +169,10 @@ module Net
           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
+          private_output = command.sensitive? || redactor.output_sensitive? || sensitive_dialogue
+          @log.event("device_output", level: :debug) if @log.detailed? && !private_output
           response = exchange_command(command, timeout: timeout, prompt: prompt)
-          @log.response_output(response.raw) unless command.sensitive? || sensitive_dialogue
+          @log.response_output(response.raw) unless private_output
           @log.event("command_complete", status: "response_received")
           @log.event("command_detail", level: :debug,
                      duration_ms: ((Expect.monotonic - started) * 1000).round,
@@ -164,6 +188,7 @@ module Net
 
       # 在用户钩子运行前标记敏感上下文，动态交互尚未返回时也能保护其异常。
       def protect_command(command)
+        redactor.output_sensitive! if command.output_sensitive?
         if command.sensitive? || [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
           redactor.sensitive!
         end
@@ -188,7 +213,7 @@ module Net
 
           response
         end
-        if command.sensitive? || interactions.any?(&:sensitive?)
+        if command.sensitive? || redactor.output_sensitive? || interactions.any?(&:sensitive?)
           @log.pause(&operation)
         else
           operation.call
@@ -219,20 +244,20 @@ module Net
 
       # 创建带脱敏上下文、阶段、命令和输出尾部的领域错误。
       def error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
-        sensitive = redactor.sensitive? || command&.sensitive?
+        sensitive = redactor.sensitive? || command&.sensitive? || command&.output_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,
+                  output: truncate_output(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?
+          sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
           failed_command = exception.command || command&.text
           if command&.sensitive? || (sensitive && exception.command && exception.command != command&.text)
             failed_command = "[REDACTED]"
@@ -244,7 +269,7 @@ module Net
             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,
+            output: truncate_output(output),
             underlying: exception.underlying && UnderlyingError.new(exception.underlying, redactor, sensitive: sensitive)
           )
         end
@@ -264,6 +289,13 @@ module Net
 
       private :safe_error_text
 
+      # 必须先脱敏再截取尾部，避免截断凭据后逃过完整词匹配。
+      def truncate_output(text)
+        text.byteslice(-MAX_ERROR_OUTPUT_BYTES, MAX_ERROR_OUTPUT_BYTES) || text
+      end
+
+      private :truncate_output
+
       # 返回不包含凭据的会话状态摘要。
       def inspect = "#<#{self.class} state=#{state} host=#{configuration.host.inspect}>"
 

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

@@ -8,20 +8,21 @@ module Net
     # 把终端编辑控制符渲染成可读、兼容 UTF-8 和二进制的逐行日志。
     class TerminalRenderer
       # 将字节流完整渲染为字符串，供测试和一次性转换使用。
-      def self.render(input)
+      def self.render(input, strict_utf8: false)
         output = StringIO.new("".b)
-        renderer = new(output)
+        renderer = new(output, strict_utf8: strict_utf8)
         renderer.write(input)
         renderer.finish
         output.string
       end
 
       # 初始化当前行、光标和转义序列状态。
-      def initialize(target, max_line_bytes: 32 * 1024 * 1024)
+      def initialize(target, max_line_bytes: 32 * 1024 * 1024, strict_utf8: false)
         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
+        raise ArgumentError, "strict_utf8 must be true or false" unless [true, false].include?(strict_utf8)
 
         @target = target
         @line = "".b
@@ -29,6 +30,7 @@ module Net
         @escape_state = nil
         @csi_parameters = "".b
         @max_line_bytes = max_line_bytes
+        @strict_utf8 = strict_utf8
       end
 
       # 逐字节消费终端输出，并返回输入字节数。
@@ -146,10 +148,11 @@ module Net
         @cursor = 0
       end
 
-      # 尽量保持有效 UTF-8；非法字节转义为可读的十六进制文本。
+      # 日志把非法字节转义；解析必须拒绝终端编辑产生的损坏字节，不能制造可写业务证据。
       def utf8_safe(line)
         text = line.dup.force_encoding(Encoding::UTF_8)
         return text.b if text.valid_encoding?
+        raise Encoding::InvalidByteSequenceError, "terminal editing produced invalid UTF-8" if @strict_utf8
 
         text.scrub { |invalid| invalid.bytes.map { |byte| format("\\x%02X", byte) }.join }.b
       end