expect-pty 0.3.2 → 0.4.0

data/lib/expect/interaction.rb

@@ -5,11 +5,13 @@ require_relative "relay"
 
 # 为会话补充人工接管和多路 IO 转接；核心会话定义位于 lib/expect.rb。
 class Expect
+  # 正则没有“潜在部分匹配”接口，只保留有限历史；已转发的历史字节不能撤回。
   REGEXP_ESCAPE_HISTORY_LIMIT = 65_536
   private_constant :REGEXP_ESCAPE_HISTORY_LIMIT
 
-  # Presents remote text on a raw local terminal without changing existing CRLF sequences.
+  # 在 raw 本地终端显示远端文本，补齐 LF 所需的 CR，同时保留已有 CRLF。
   class InteractOutput
+    # 包装器借用目标，不复制或关闭其描述符；换行状态属于这个目标的连续显示流。
     def initialize(target)
       @target = target
       @previous_carriage_return = false
@@ -17,6 +19,7 @@ class Expect
 
     attr_reader :target
 
+    # 只改变显示字节，不改写匹配输入；记住上一块的 CR，避免分块的 CRLF 被扩成 CRCRLF。
     def render(data)
       bytes = data.to_s.b
       rendered = bytes.gsub(/(?<!\r)\n/n, "\r\n")
@@ -25,6 +28,7 @@ class Expect
       rendered
     end
 
+    # 提供普通可写对象接口；Relay 会先 render，再按转换后字节数维护独立发送游标。
     def write(data)
       @target.write(render(data))
     end
@@ -169,10 +173,12 @@ class Expect
       return block_given? && count.positive? ? :pending : true
     end
   end
+
   # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
   private_class_method :relay_buffer
 
+  # 同一输入 IO 重用一个借用会话，以保留上次接管预读的尾部并避免不断积累包装器。
   def interact_source(input)
     return input if input.is_a?(Expect)
 
@@ -181,6 +187,8 @@ class Expect
     @interact_inputs[input] ||= Expect.open(input)
   end
 
+  # 为当前数据块冻结目标选择并各建一个发送游标；此后修改 listeners 只影响后续数据。
+  # 调用方须先排空旧游标；显示转换也只做一次，短写重试时不能重复转换 CRLF。
   def queue_output(data)
     targets = []
     targets << $stdout if log_stdout?
@@ -196,7 +204,7 @@ class Expect
 
   private :interact_source, :queue_output
 
-  # Only interact knows which stream is the local keyboard. Generic interconnect leaves terminals alone.
+  # 只有 interact 知道哪个流是本地键盘；通用 interconnect 不修改终端模式。
   def prepare_interact_terminal(source)
     return unless source.raw_terminal? && source.tty?
 
@@ -204,11 +212,12 @@ class Expect
     state = [io, io.console_mode]
     io.raw!
     state
-  rescue Exception # rubocop:disable Lint/RescueException -- Restore a partially changed terminal on interrupts.
+  rescue Exception # rubocop:disable Lint/RescueException -- 中断时也恢复可能已部分修改的终端。
     restore_interact_terminal(state)
     raise
   end
 
+  # 还原 prepare 保存的完整终端模式；没有切换过或句柄已关闭时无需恢复。
   def restore_interact_terminal(state)
     return unless state
 
@@ -216,6 +225,7 @@ class Expect
     io.console_mode = mode unless io.closed?
   end
 
+  # 仅为已切为 raw 的同一个本地终端补齐换行，文件、管道和其他终端保留原字节。
   def interact_display(source, output, terminal_state)
     @interact_output = nil unless terminal_state && @interact_output&.target.equal?(output)
     return output unless terminal_state
@@ -238,7 +248,11 @@ class Expect
   attr_accessor :sequences
   # 让同步写入的背压读取遵守当前转接的数据所有权，退出后恢复普通匹配缓冲。
   attr_accessor :interaction_buffer
+  # 只有裁剪、替换和消费才改变代次；同一代次只会追加，供字面扫描复用已排除的前缀。
+  attr_reader :buffer_generation
+  # 待交付游标随源会话保存，Relay 的超时或异常退出不会丢失各目标已经写出的进度。
   attr_reader :relay_outputs
+  # 数组包装区分“没有待执行回调”与“已识别无处理器的停止转义”，前缀交付后只派发一次。
   attr_accessor :relay_callback
 
   # 历史属于产生它的转义规则；同规则重入继续匹配，换规则不能重放已转发输入。
@@ -252,5 +266,6 @@ class Expect
   # 转接尚未处理的输入不能被匹配窗口上限裁掉；下次 expect 会重新应用该上限。
   def restore_relay_buffer(buffer)
     @buffer = buffer + @buffer
+    @buffer_generation += 1
   end
 end

data/lib/expect/logging.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require_relative "redactor"
+
+# 管理日志目标、监听器及同步输出；资源所有权仍由会话的 SessionResources 统一保存。
+# 接收日志、诊断和协议转发是三条独立通道；脱敏只改变前两条，不改变匹配或转发字节。
+class Expect
+  # 读取当前日志目标，可能为库打开的文件、借用的 IO、回调或 nil。
+  attr_reader :log_output, :diagnostic_output
+
+  # 诊断目标仅借用；nil 沿用 stderr，Logger 使用 info/debug，回调接收冻结的事件 Hash。
+  # 先校验再冲刷旧流；校验或冲刷失败时保留旧目标，避免把暂存尾部交给错误的接收方。
+  def diagnostic_output=(target)
+    unless target.nil? || (target.respond_to?(:info) && target.respond_to?(:debug)) ||
+           target.respond_to?(:write) || target.respond_to?(:call)
+      raise ArgumentError, "diagnostic output must support info/debug, write or call, or be nil"
+    end
+    return if @diagnostic_output.equal?(target)
+
+    flush_diagnostics
+    @diagnostic_output = target
+  end
+
+  # 秘密仅作用于本会话的日志和诊断，不改写匹配、stdout 显示或 listeners 的协议字节。
+  # 先校验全部值再发布；注册是追加操作，应在首次通信前完成，不能追溯已交付的日志。
+  def redact(*secrets)
+    unless secrets.any? && secrets.all? { |secret| secret.is_a?(String) && !secret.empty? }
+      raise ArgumentError, "secrets must be nonempty Strings"
+    end
+
+    @secrets = ((@secrets || []) + secrets.map { |secret| secret.b.freeze }).uniq.freeze
+    @log_redactor.patterns = @secrets if @log_redactor
+    @diagnostic_redactors&.each_value { |redactor| redactor.patterns = @secrets }
+    self
+  end
+
+  # 替换借用的日志目标或停止日志；先校验新目标，失败时保留旧目标。
+  def log_output=(target)
+    unless target.nil? || target.respond_to?(:write) || target.respond_to?(:call)
+      raise ArgumentError, "log output must support write or call, or be nil"
+    end
+
+    replace_log(target)
+  end
+
+  # 打开追加/覆盖日志文件，或注册接收字节的日志块；同一次只能指定一种目标。
+  def log_to(target = nil, mode: "a", &block)
+    raise ArgumentError, "provide a log target or a block, not both" if block && target
+
+    target = block if block
+    if target.respond_to?(:to_path) || target.is_a?(String)
+      raise ArgumentError, "log mode must be a or w" unless %w[a w].include?(mode)
+
+      # 先交付旧过滤尾部，再允许新路径截断；同一文件不能在截断后被旧句柄写回。
+      flush_log
+      # 库打开的文件由 SessionResources 持有，替换日志或关闭会话时释放；外部 IO 只借用。
+      replace_log(File.open(target, "#{mode}b", 0o600), owned: true)
+    else
+      raise ArgumentError, "provide a log target or a block" unless target
+
+      self.log_output = target
+    end
+  end
+
+  # 向当前日志目标补写内容，支持 IO 和回调，不发送给子进程或监听器。
+  # 启用脱敏后可能暂存末尾字节，因此一次调用不保证触发一次日志写入或回调。
+  def write_log(*objects)
+    target = log_output
+    return unless target
+
+    data = objects.map { |object| object.to_s.b }.join
+    if @secrets
+      @log_redactor ||= Redactor.new(@secrets)
+      data = @log_redactor.append(data)
+      return if data.empty?
+    end
+    target.respond_to?(:call) ? target.call(data) : emit(target, data)
+  end
+
+  # 返回监听器列表副本，避免外部原地修改转发关系。
+  def listeners = @listeners.dup
+
+  # 校验所有监听器均可写后一次性替换列表，外部数组后续修改不会影响会话。
+  def listeners=(outputs)
+    outputs = Array(outputs)
+    raise ArgumentError, "listeners must support write" unless outputs.all? { |output| output.respond_to?(:write) }
+
+    @listeners = outputs.dup
+  end
+
+  private
+
+  # 按各自开关将接收字节转发到 stdout 和监听器，不重复写日志。
+  def propagate(data)
+    emit($stdout, data) if log_stdout?
+    @listeners.each { |listener| emit(listener, data) } if log_listeners?
+  end
+
+  # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
+  # 这里遵循同步写入协议，不受 Matcher 的 IO 等待期限中断；慢目标转接应使用 Relay。
+  # 短写只推进已确认的字节数；目标抛错时不猜测它是否已经产生副作用。
+  def emit(target, data)
+    offset = 0
+    while offset < data.bytesize
+      count = target.write(data.byteslice(offset..))
+      unless count.is_a?(Integer) && count.positive? && count <= data.bytesize - offset
+        raise IOError, "write must return the number of accepted bytes"
+      end
+
+      offset += count
+    end
+    target.flush if target.respond_to?(:flush)
+  end
+
+  # 字节诊断在 inspect 转义之前过滤；缓冲快照可能只含秘密中间片段，启用脱敏时不展开。
+  def trace_data(event, data, level:)
+    if @secrets
+      return trace("buffer [FILTERED]", level: level, event: event) if event == :buffer
+
+      @diagnostic_redactors ||= {}
+      redactor = (@diagnostic_redactors[event] ||= Redactor.new(@secrets))
+      data = redactor.append(data)
+      return if data.empty?
+    end
+    trace("#{event} #{data.inspect}", level: level, event: event)
+  end
+
+  # 诊断与接收字节日志分开；回调元数据不含会话对象，避免格式化时意外展开原始缓冲。
+  def trace(message, level: 1, event: :matched)
+    return unless debug_level >= level
+
+    severity = level == 1 ? :info : :debug
+    target = diagnostic_output
+    if target.respond_to?(:info) && target.respond_to?(:debug)
+      target.public_send(severity, "#{inspect}: #{message}")
+    elsif target.respond_to?(:call)
+      target.call({ event: event, level: severity, pid: pid, fd: fileno, message: message.freeze }.freeze)
+    elsif target
+      emit(target, "#{inspect}: #{message}\n")
+    else
+      warn("#{inspect}: #{message}")
+    end
+  end
+
+  # 结束当前日志片段并交付过滤器尾部；重复调用不会重放已释放字节，写入异常原样传播。
+  def flush_log
+    loop do
+      return unless @log_redactor && log_output
+
+      data = @log_redactor.finish
+      return if data.empty?
+
+      log_output.respond_to?(:call) ? log_output.call(data) : emit(log_output, data)
+      # 回调可能轮换目标并追加新尾部；先结束它，再允许外层截断文件或关闭日志。
+    end
+  end
+
+  # EOF 只结束接收诊断；目标替换或显式关闭结束全部方向，发送与接收不能拼成一个秘密。
+  # GC 终结器不进入本方法，避免在回收阶段调用用户回调或持有会话对象。
+  def flush_diagnostics(event = nil)
+    return unless @diagnostic_redactors
+
+    loop do
+      delivered = false
+      # 回调可能首次创建另一个方向，也可能写入本轮已经处理的方向。
+      @diagnostic_redactors.to_a.each do |name, redactor|
+        next if event && name != event
+
+        data = redactor.finish
+        next if data.empty?
+
+        delivered = true
+        trace("#{name} #{data.inspect}", level: 2, event: name)
+      end
+      # 目标尚未交接，新产生的尾部仍归旧诊断流；排空后才结束这次冲刷。
+      break unless delivered
+    end
+  end
+
+  # 交接日志目标和所有权，只关闭库拥有的旧文件；失败时释放新打开的文件。
+  def replace_log(target, owned: false)
+    # 重复赋值同一目标时保留原所有权，防止将库打开的文件误变成借用资源。
+    return target if log_output.equal?(target)
+
+    flush_log
+    # 尾部回调可以重入并替换目标；交接时重新读取目标和所有权，不能关闭旧的回调对象。
+    return target if log_output.equal?(target)
+
+    previous = @resources.owned_log
+    previous.close if previous && !previous.closed?
+    # 终结器只持有所属文件；借用回调可能捕获会话，不能让它经资源对象成为 GC 根。
+    @resources.owned_log = owned ? target : nil
+    @log_output = target
+    @log_redactor = nil
+    target
+  rescue Exception # rubocop:disable Lint/RescueException -- 替换失败时仍释放刚打开的文件。
+    target.close if owned && target && !target.closed?
+    raise
+  end
+end

data/lib/expect/matcher.rb

@@ -2,16 +2,20 @@
 
 class Expect
   # 驱动一次单会话或多会话匹配，管理模式优先级、EOF 和共享期限，不接管 IO 所有权。
+  # 调度只在扫描、回调和 IO 操作之间检查期限，不强行中断用户代码或单次正则计算。
   class Matcher
     # 固定本次参与的会话及初始期限；已处理 EOF 的会话仅从本次等待中移除。
-    def initialize(patterns, timeout)
+    def initialize(patterns, timeout, deadline: nil)
       @patterns = patterns
       @sessions = patterns.sessions
       @timeout = Expect.duration(timeout)
+      # 相对期限可因接收或 continue 重算，总期限始终固定；两者共用单调时钟。
+      @hard_deadline = deadline
       @deadline = next_deadline
       @handled_eof = []
       @stalled_matches = {}
       @polled = false
+      @expired_eof_continuation = false
     end
 
     # 运行匹配状态机；内部 :retry 表示继续循环，最终返回一个 Result。
@@ -30,16 +34,19 @@ class Expect
       end
       loop do
         # 先消费已缓冲的匹配，再处理 EOF，最后读取；避免进程退出时丢失最后一个匹配。
-        result = if (matched = find_match)
+        result = if !@expired_eof_continuation && !hard_expired? && (matched = find_match)
                    handle_match(*matched)
                  elsif (session = unhandled_eof)
                    handle_eof(session)
+                 elsif @expired_eof_continuation || hard_expired?
+                   handle_timeout
                  else
                    read_next
                  end
         return result unless result == :retry
       end
     ensure
+      # 嵌套 expect 即使异常退出，也要把未消费尾部还给原 Relay 的同一个缓冲对象。
       @relay_buffers.each do |session, buffer|
         buffer.replace(session.clear_buffer)
         session.__send__(:interaction_buffer=, buffer)
@@ -67,17 +74,52 @@ class Expect
             stalled = nil
           end
           patterns.each do |pattern|
+            return nil if hard_expired?
             next if stalled && stalled[:patterns].include?(pattern)
 
-            position = pattern.locate(buffer, final: session.eof?)
+            position = if pattern.value.is_a?(String)
+                         locate_literal(session, pattern, buffer)
+                       else
+                         pattern.locate(buffer, final: session.eof?)
+                       end
+            # 正则本身不可由 IO 期限中断；恢复控制后也不能消费已过总期限的匹配。
+            return nil if hard_expired?
             return [session, pattern, position] if position
           end
         end
       end
       nil
     end
+
     # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
+    # 仅复用同一缓冲代次中的字面未命中。保留模式长度减一的重叠区，覆盖跨读取命中。
+    # 不保存整个文本，也不对正则推断扫描窗口；回调替换、消费或转接恢复会改变代次。
+    def locate_literal(session, pattern, buffer)
+      @literal_misses ||= {}.compare_by_identity
+      misses = (@literal_misses[session] ||= {}.compare_by_identity)
+      previous = misses[pattern]
+      generation = session.__send__(:buffer_generation)
+      # 缓冲代次未变意味着只有尾部追加；模式对象的 value 被替换时也不能沿用旧扫描位置。
+      offset = if previous && previous[0] == generation && previous[2].equal?(pattern.value)
+                 return nil if previous[1] == buffer.bytesize
+
+                 [previous[1] - pattern.value.bytesize + 1, 0].max
+               else
+                 0
+               end
+      position = pattern.locate(buffer, offset: offset)
+      if position
+        misses.delete(pattern)
+      else
+        entry = (misses[pattern] ||= [])
+        entry[0] = generation
+        entry[1] = buffer.bytesize
+        entry[2] = pattern.value
+      end
+      position
+    end
+
     # 先记录并消费匹配，再执行回调；回调可选择结束、重置期限或保留期限继续。
     def handle_match(session, pattern, position)
       previous_buffer = session.buffer
@@ -91,7 +133,8 @@ class Expect
         stalled[:patterns] << pattern
       end
       @deadline = next_deadline if action == CONTINUE
-      return handle_timeout if action == CONTINUE_WITHOUT_RESET && expired?
+      # 总期限到达时回主循环先派发已知 EOF；仅相对期限延续原有立即超时语义。
+      return handle_timeout if action == CONTINUE_WITHOUT_RESET && expired? && !hard_expired?
 
       :retry
     end
@@ -109,12 +152,17 @@ class Expect
       return result unless actions.any? { |action| continuing?(action) }
 
       @deadline = next_deadline if actions.include?(CONTINUE)
-      @sessions.all? { |candidate| @handled_eof.include?(candidate) } ? result : :retry
+      return result if @sessions.all? { |candidate| @handled_eof.include?(candidate) }
+
+      # 期限已过时不再扫描文本，但先派发已知 EOF；最后一个源结束不能被误报为超时。
+      @expired_eof_continuation = !actions.include?(CONTINUE) && expired?
+
+      :retry
     end
 
     # 在剩余期限内等待可读 IO；零超时仍允许首次非阻塞轮询，EINTR 重试不重新计时。
     def read_next
-      return handle_timeout if @polled && expired?
+      return handle_timeout if hard_expired? || (@polled && expired?)
 
       readers = active_sessions
       begin
@@ -139,6 +187,8 @@ class Expect
         sessions.each { |session| by_io[session.to_io] ||= session }
       end
       readable.each do |io|
+        break if hard_expired?
+
         session = by_io ? by_io.fetch(io) : sessions.find { |candidate| candidate.to_io.equal?(io) }
         begin
           # 转接回调消费匹配内容，余下字节交回 Relay，不能在这里提前转发两次。
@@ -161,7 +211,14 @@ class Expect
     def continuing?(action) = [CONTINUE, CONTINUE_WITHOUT_RESET].include?(action)
 
     # 使用单调时钟计算期限；nil 一直表示无限等待，不受系统时间调整影响。
-    def next_deadline = @timeout && (Expect.monotonic + @timeout)
+    # 每次重置都重新与总期限取较早者，避免连续输入或继续回调无限推迟结束。
+    def next_deadline
+      relative = @timeout && (Expect.monotonic + @timeout)
+      return @hard_deadline unless relative
+      return relative unless @hard_deadline
+
+      [relative, @hard_deadline].min
+    end
 
     # 计算传给 select 的非负等待秒数，避免计时跨过边界时产生负数。
     def remaining = @deadline && [@deadline - Expect.monotonic, 0].max
@@ -169,19 +226,24 @@ class Expect
     # 判断有限期限是否已到达；无限等待不会触发超时。
     def expired? = @deadline && Expect.monotonic >= @deadline
 
+    # 绝对总期限不受接收数据和 continue 重置；已知 EOF 仍按原顺序派发。
+    def hard_expired? = @hard_deadline && Expect.monotonic >= @hard_deadline
+
     # select 失败时无法归属单个源，为本次会话记录同一原始异常并返回首个结果。
     def record_error(error)
       @sessions.map { |session| session.__send__(:record_error, error) }.first
     end
 
     # 为活跃会话记录超时，回调接收全部活跃源；只有重置计时的继续符号能重新等待。
+    # 已到总期限仍通知超时回调，但不接受继续请求，且不消费尚未匹配的字节。
     def handle_timeout
       results = active_sessions.map { |session| session.__send__(:record_error, :timeout) }
       action = @patterns.timeout_pattern&.call(active_sessions)
-      return results.first unless action == CONTINUE
+      return results.first unless action == CONTINUE && !hard_expired?
 
       @deadline = next_deadline
       @polled = false
+      @expired_eof_continuation = false
       :retry
     end
   end

data/lib/expect/pattern.rb

@@ -12,14 +12,20 @@ class Expect
     def eof? = value == :eof
 
     # 在缓冲中定位字符串或正则，返回 [字节偏移, 字节长度, 捕获组]；事件或未匹配返回 nil。
-    def locate(buffer, final: false)
+    # buffer 应为二进制字符串，offset 仅用于字面扫描；正则始终看到完整窗口以保留锚点语义。
+    # final 表示不会再有新输入，此时不完整的编码尾部也必须报错，不能永远当作等待分片。
+    def locate(buffer, final: false, offset: 0)
       case value
       when String
-        offset = buffer.index(value)
+        offset = buffer.index(value, offset)
         return [offset, value.bytesize, []] if offset
       when Regexp
-        text = buffer.dup
-        text.force_encoding(value.encoding) if value.fixed_encoding?
+        # 正则只读取输入；只有编码标记不同才复制，避免每个模式额外分配缓冲对象。
+        text = if value.fixed_encoding? && value.encoding != buffer.encoding
+                 buffer.dup.force_encoding(value.encoding)
+               else
+                 buffer
+               end
         unless text.valid_encoding?
           # 不完整的尾字符可能改变锚点或前瞻结果，必须等字符收齐后再匹配。
           validate_incomplete_suffix!(text, final: final)
@@ -38,6 +44,7 @@ class Expect
     private
 
     # 仅容忍末尾尚未收全的 UTF-8 字符，其他非法编码直接报错，不静默替换接收字节。
+    # 转码仅用于区分“不完整尾部”和“非法字节”，结果不回写缓冲，也不做编码归一化。
     def validate_incomplete_suffix!(text, final:)
       if !final && text.encoding == Encoding::UTF_8
         incomplete = begin

data/lib/expect/pattern_list.rb

@@ -2,6 +2,7 @@
 
 class Expect
   # 将 Ruby 模式和块回调整理为有序会话组；注册阶段不读取 IO、不执行匹配回调。
+  # 分组结构直接决定 Matcher 的“声明组 → 会话 → 模式”优先级，不能按匹配位置重排。
   class PatternList
     attr_reader :groups, :timeout_pattern
 
@@ -34,6 +35,7 @@ class Expect
     end
 
     # 注册一次等待的唯一超时回调，重复定义直接报错，避免悄悄覆盖业务处理。
+    # 超时是整次等待的事件，回调收到全部活跃会话，不归属于某一个来源组。
     def timeout(&block)
       raise ArgumentError, "timeout callback already registered" if @timeout_pattern
 
@@ -42,6 +44,7 @@ class Expect
     end
 
     # 汇总并去重读取源，同一会话出现在多个模式组时仍只读取一次。
+    # 这里只去重会话对象；不同会话包装同一 IO 时的读取归属由 Matcher 决定。
     def sessions = groups.flat_map(&:first).uniq
 
     # 收集指定会话的所有 EOF 处理器，保留原注册顺序。

data/lib/expect/redactor.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+class Expect
+  # 单个日志字节流的过滤器。保留最长秘密长度减一的尾部，跨 write/read 分片仍可识别。
+  # 掩码与原字节一起留存；重叠命中的区间取并集，已经输出的掩码不重复生成。
+  # 上层负责传入已复制的非空二进制秘密，每个日志目标或诊断方向使用独立实例。
+  class Redactor
+    # pending 保存尚不能安全输出的原字节，hidden 的对应字节用 0/1 表示是否需要遮盖。
+    def initialize(patterns)
+      self.patterns = patterns
+      @pending = "".b
+      @hidden = "".b
+      @masking = false
+    end
+
+    # 更新后续匹配规则并保留已有尾部与掩码；不能追溯修改已经交付给日志目标的内容。
+    def patterns=(patterns)
+      @patterns = patterns
+      @lookbehind = patterns.map(&:bytesize).max - 1
+    end
+
+    # 追加一个原始字节块，返回已经可以确定的安全前缀；新秘密可能跨越此前保留的尾部。
+    def append(data)
+      @pending << data
+      @hidden << ("\0" * data.bytesize)
+      mark_secrets
+      release([@pending.bytesize - @lookbehind, 0].max)
+    end
+
+    # EOF、日志目标替换及关闭是流边界；尾部疑似秘密前缀也遮盖，不能因 flush 泄露片段。
+    def finish
+      mark_secrets
+      @patterns.each do |pattern|
+        [pattern.bytesize - 1, @pending.bytesize].min.downto(1) do |length|
+          next unless @pending.end_with?(pattern.byteslice(0, length))
+
+          @hidden[-length, length] = "\1" * length
+          break
+        end
+      end
+      output = release(@pending.bytesize)
+      @masking = false
+      output
+    end
+
+    private
+
+    # 每次只将命中区域标为隐藏，不清除旧掩码；偏移逐字节推进以识别相互重叠的秘密。
+    def mark_secrets
+      @patterns.each do |pattern|
+        offset = -1
+        while (offset = @pending.index(pattern, offset + 1))
+          @hidden[offset, pattern.bytesize] = "\1" * pattern.bytesize
+        end
+      end
+    end
+
+    # 按连续区间输出，避免逐字节构造字符串；只保存尚可能与下一块组成秘密的后缀。
+    # masking 跨 append 保留，使被分成多个块的同一隐藏区间只输出一次 [FILTERED]。
+    def release(length)
+      output = "".b
+      cursor = 0
+      while cursor < length
+        hidden = @hidden.getbyte(cursor) == 1
+        ending = [@hidden.index(hidden ? "\0" : "\1", cursor) || length, length].min
+        if hidden
+          output << "[FILTERED]" unless @masking
+        else
+          output << @pending.byteslice(cursor, ending - cursor)
+        end
+        @masking = hidden
+        cursor = ending
+      end
+      @pending = @pending.byteslice(length..)
+      @hidden = @hidden.byteslice(length..)
+      output
+    end
+  end
+
+  private_constant :Redactor
+end

data/lib/expect/relay.rb

@@ -2,7 +2,9 @@
 
 class Expect
   # 一次转接的共同读写循环；发送游标留在源会话中，调用结束后仍可继续。
+  # 本对象只暂借未处理输入；读缓冲、发送进度与转义回调分开保存，避免重入时重复交付。
   class Relay
+    # 将普通匹配缓冲移入本轮转接，并记住上层交互缓冲；不关闭或接管任何外部 IO。
     def initialize(sessions, timeout)
       @sessions = sessions.uniq
       @active = @sessions.dup
@@ -12,6 +14,8 @@ class Expect
       @previous = @sessions.to_h { |session| [session, session.__send__(:interaction_buffer)] }
     end
 
+    # 每轮先处理转义和已排队输出，再共同选择读写；停止返回来源会话，总期限到达返回 nil。
+    # 真实 IO 的写入由非阻塞游标推进，用户日志和回调仍同步执行，须由调用方保证及时返回。
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 共享读写循环统一维护来源和目标期限。
     def run
       @sessions.each { |session| session.__send__(:interaction_buffer=, @buffers.fetch(session)) }
@@ -85,15 +89,19 @@ class Expect
         end
       end
     ensure
+      # 未处理输入还给会话，已排队字节仍归发送游标；两者不能合并，否则恢复会重放前缀。
       @previous.each { |session, buffer| session.__send__(:interaction_buffer=, buffer) }
       @buffers.each { |session, buffer| session.__send__(:restore_relay_buffer, buffer) }
     end
+
     # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     private
 
+    # 只收集尚未完成的目标，供共同 select 以及最早写入期限计算使用。
     def outputs = @sessions.flat_map { |session| session.__send__(:relay_outputs) }.reject(&:done?)
 
+    # 每个目标每轮最多推进一个片段；移除已完成游标，并告知主循环是否值得立即继续轮询。
     def advance_outputs(check_timeout: true)
       progress = false
       @sessions.each do |session|
@@ -104,8 +112,10 @@ class Expect
       progress
     end
 
+    # 转接总期限不因持续输入或某个目标的写入进展而重置。
     def expired? = @deadline && Expect.monotonic >= @deadline
 
+    # 背压源暂停吸收新输入，限制排队增长；作为写入目标的会话仍需读取以解除双向等待。
     def read_sources(pending)
       # 输出目标可能也在等待我们读取；这些来源即使有待发送数据也必须继续排空。
       targets = pending.map(&:target).grep(Expect)
@@ -113,6 +123,8 @@ class Expect
       (sources + targets).uniq(&:to_io).reject(&:eof?)
     end
 
+    # 总期限结束时将可交付尾部转为发送游标，至多尝试一轮交付；余量由源会话保存。
+    # 目标的写期限更早到达时保留 WriteTimeout 语义，不能被转接的普通超时掩盖。
     def finish_timeout(idle)
       # 调度延迟可能让两种期限均已到达，仍按先到的期限决定结果。
       outputs.each { |output| output.check_timeout! if output.deadline && output.deadline < @deadline }