expect-pty 0.3.3 → 0.5.0

data/lib/expect/logging.rb

@@ -1,9 +1,38 @@
 # frozen_string_literal: true
 
+require_relative "redactor"
+
 # 管理日志目标、监听器及同步输出；资源所有权仍由会话的 SessionResources 统一保存。
+# 接收日志、诊断和协议转发是三条独立通道；脱敏只改变前两条，不改变匹配或转发字节。
 class Expect
   # 读取当前日志目标，可能为库打开的文件、借用的 IO、回调或 nil。
-  attr_reader :log_output
+  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)
@@ -22,6 +51,8 @@ class Expect
     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
@@ -32,11 +63,17 @@ class Expect
   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
 
@@ -60,6 +97,8 @@ class Expect
   end
 
   # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
+  # 这里遵循同步写入协议，不受 Matcher 的 IO 等待期限中断；慢目标转接应使用 Relay。
+  # 短写只推进已确认的字节数；目标抛错时不猜测它是否已经产生副作用。
   def emit(target, data)
     offset = 0
     while offset < data.bytesize
@@ -73,21 +112,86 @@ class Expect
     target.flush if target.respond_to?(:flush)
   end
 
-  # 按诊断级别向 stderr 输出会话标识和消息。
-  def trace(message, level: 1)
-    warn("#{inspect}: #{message}") if debug_level >= level
+  # 字节诊断在 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)
-    previous = log_output
     # 重复赋值同一目标时保留原所有权，防止将库打开的文件误变成借用资源。
-    return target if previous.equal?(target)
+    return target if log_output.equal?(target)
+
+    flush_log
+    # 尾部回调可以重入并替换目标；交接时重新读取目标和所有权，不能关闭旧的回调对象。
+    return target if log_output.equal?(target)
 
-    previous.close if @resources.owned_log && previous && !previous.closed?
+    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?

data/lib/expect/matcher.rb

@@ -2,12 +2,15 @@
 
 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 = {}
@@ -31,11 +34,11 @@ class Expect
       end
       loop do
         # 先消费已缓冲的匹配，再处理 EOF，最后读取；避免进程退出时丢失最后一个匹配。
-        result = if !@expired_eof_continuation && (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
+                 elsif @expired_eof_continuation || hard_expired?
                    handle_timeout
                  else
                    read_next
@@ -43,6 +46,7 @@ class Expect
         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)
@@ -70,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
@@ -94,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
@@ -122,7 +162,7 @@ class Expect
 
     # 在剩余期限内等待可读 IO；零超时仍允许首次非阻塞轮询，EINTR 重试不重新计时。
     def read_next
-      return handle_timeout if @polled && expired?
+      return handle_timeout if hard_expired? || (@polled && expired?)
 
       readers = active_sessions
       begin
@@ -147,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，不能在这里提前转发两次。
@@ -169,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
@@ -177,16 +226,20 @@ 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

data/lib/expect/pattern.rb

@@ -12,10 +12,12 @@ 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
         # 正则只读取输入；只有编码标记不同才复制，避免每个模式额外分配缓冲对象。
@@ -42,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,106 @@
+# frozen_string_literal: true
+
+class Expect
+  # 单个日志字节流的过滤器。保留最长秘密长度减一的尾部，跨 write/read 分片仍可识别。
+  # 掩码与原字节一起留存；重叠命中的区间取并集，已经输出的掩码不重复生成。
+  # 不依赖会话或 IO；每个日志目标或诊断方向使用独立实例。
+  class Redactor
+    # 完整诊断文本只匹配完整秘密；流边界的疑似秘密前缀由 finish 的默认策略保护。
+    def self.redact(data, patterns, replacement: "[FILTERED]")
+      filter = new(patterns, replacement: replacement)
+      filter.append(data) + filter.finish(partial: false)
+    end
+
+    # pending 保存尚不能安全输出的原字节，hidden 的对应字节用 0/1 表示是否需要遮盖。
+    def initialize(patterns, replacement: "[FILTERED]")
+      unless replacement.is_a?(String) && !replacement.empty?
+        raise ArgumentError, "replacement must be a nonempty String"
+      end
+
+      @replacement = replacement.b.freeze
+      self.patterns = patterns
+      @pending = "".b
+      @hidden = "".b
+      @masking = false
+    end
+
+    # 更新后续匹配规则并保留已有尾部与掩码；不能追溯修改已经交付给日志目标的内容。
+    def patterns=(patterns)
+      unless patterns.is_a?(Array) && patterns.all? { |pattern| pattern.is_a?(String) && !pattern.empty? }
+        raise ArgumentError, "patterns must be an Array of nonempty Strings"
+      end
+
+      @patterns = patterns.map { |pattern| pattern.b.freeze }.uniq.freeze
+      @lookbehind = [(@patterns.map(&:bytesize).max || 0) - 1, 0].max
+    end
+
+    # 追加一个原始字节块，返回已经可以确定的安全前缀；新秘密可能跨越此前保留的尾部。
+    def append(data)
+      raise ArgumentError, "data must be a String" unless data.is_a?(String)
+
+      @pending << data.b
+      @hidden << ("\0" * data.bytesize)
+      mark_secrets
+      release([@pending.bytesize - @lookbehind, 0].max)
+    end
+
+    # EOF、日志目标替换及关闭是流边界；尾部疑似秘密前缀也遮盖，不能因 flush 泄露片段。
+    def finish(partial: true)
+      raise ArgumentError, "partial must be true or false" unless [true, false].include?(partial)
+
+      mark_secrets
+      mark_partial_secrets if partial
+      output = release(@pending.bytesize)
+      @masking = false
+      output
+    end
+
+    # 过滤器公开后仍不在诊断摘要中展开注册秘密或尚未交付的原始字节。
+    def inspect = "#<#{self.class}>"
+
+    private
+
+    # 流关闭时无法再等待后续字节，默认隐藏与秘密开头一致的未完成尾部。
+    def mark_partial_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
+    end
+
+    # 每次只将命中区域标为隐藏，不清除旧掩码；偏移逐字节推进以识别相互重叠的秘密。
+    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 保留，使被分成多个块的同一隐藏区间只输出一次替换标记。
+    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 << @replacement 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
+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 }

data/lib/expect/relay_writer.rb

@@ -2,9 +2,11 @@
 
 class Expect
   # 向单个转接目标写入数据，维护发送进度与期限；恢复时不重放已成功写出的前缀。
+  # 只借用目标，不 dup 描述符，也不负责读取；所有就绪等待统一交给 Relay 调度。
   class RelayWriter
     attr_reader :target, :deadline
 
+    # data 在本游标存活期间由上层保持不变，offset 始终以实际交付的字节数计量。
     def initialize(target, data)
       @target = target
       @data = data
@@ -13,17 +15,21 @@ class Expect
       restart_timeout
     end
 
+    # 初次排队或重新进入 interconnect 时开始新的写入预算；普通短写不会刷新期限。
+    # 只有 Expect 目标提供 write_timeout，原生 IO 和自定义目标只受转接总期限约束。
     def restart_timeout
       period = target.write_timeout if target.is_a?(Expect)
       @deadline = period && (Expect.monotonic + period)
     end
 
+    # 真实 IO 可参与共同 select；自定义可写对象返回 nil，沿用其同步 write/flush 协议。
     def io
       return target.writer if target.is_a?(Expect)
 
       target if target.is_a?(IO)
     end
 
+    # 数据交付完但 flush 失败仍未完成；重试只补 flush，不重新发送已接受的数据。
     def done? = @offset == @data.bytesize && @flushed
 
     # 每轮每目标至多一次写入；真实 IO 永不在此等待，交给 Relay 的共同 select。
@@ -52,11 +58,14 @@ class Expect
       end
       true
     rescue Errno::EINTR
+      # 未获得写入计数就不移动游标；先检查原期限，再让共同循环轮询输入并重试。
       check_timeout! if check_timeout
       true
     end
+
     # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
+    # 保留本数据块已交付的进度，便于调用方区分未写入和部分写入；不清空恢复用的游标。
     def check_timeout!
       return unless deadline && Expect.monotonic >= deadline
 

data/lib/expect/result.rb

@@ -3,6 +3,8 @@
 class Expect
   # 保存一次等待的结果，保留 Struct 原生数组、Hash 转换和模式解构能力。
   # number 仅在文本匹配时存在；error 为 :timeout、:eof 或原始 IO 异常，文本字段均为字节串。
+  # before/match/after 是产生结果时的快照，后续读取不追加到旧结果；captures 保留未参与捕获的 nil。
+  # 结果对象仍采用普通可变 Struct 语义；session 只引用来源，不取得 IO 或子进程所有权。
   Result = Struct.new(:number, :error, :match, :before, :after, :session, :captures, keyword_init: true) do
     # 是否命中文本模式；事件不会返回模式序号。
     def matched? = !number.nil?

data/lib/expect/session_resources.rb

@@ -2,7 +2,9 @@
 
 class Expect
   # 独立保存句柄、PID 和日志所有权，让终结器无需直接捕获会话即可清理遗弃资源。
+  # IO 是否关闭与子进程是否退出分别记录；不能仅凭句柄状态清空 PID 或伪造退出状态。
   class SessionResources
+    # owned_log 只保存库打开的文件；借用的 IO/日志回调留在会话中，不能成为终结器的引用根。
     attr_accessor :pid, :status, :owned_log
     attr_reader :reader, :writer, :slave, :owner, :own
 
@@ -16,6 +18,7 @@ class Expect
     end
 
     # 只关闭由本库拥有的 IO；借用的 reader、writer 由调用方管理。
+    # 常规关闭错误延后到所有句柄尝试完再抛出，失败句柄仍留在账本内供下一次关闭重试。
     def close_handles
       return unless own
 
@@ -40,6 +43,7 @@ class Expect
       status
     rescue Errno::ECHILD
       # 子进程可能已被调用方或其他线程回收，不再保留可能被系统复用的 PID。
+      # 无法获取别人已取走的 Process::Status，保留未知状态而不是推断成功或失败。
       @pid = nil
       status
     end

data/lib/expect/terminal.rb

@@ -5,6 +5,7 @@ require "shellwords"
 # 会话终端的模式和窗口尺寸接口；人工接管期间的临时恢复由 interaction.rb 负责。
 class Expect
   # 查询可恢复的终端模式字符串，或通过系统 stty 设置模式；参数按数组传递，不经 shell。
+  # 非终端返回空字符串；命令不存在或执行失败抛出 IOError，管道在所有退出路径关闭。
   def stty(*modes)
     return "" unless tty?
 
@@ -25,7 +26,7 @@ class Expect
     sink&.close unless sink&.closed?
   end
 
-  # 读取终端的 [行数, 列数]。
+  # 读取终端的 [行数, 列数]；底层并非终端或句柄已关闭时保留原生 IO 异常。
   def winsize = to_io.winsize
 
   # 更新终端尺寸，由内核通知前台进程。

data/lib/expect/version.rb

@@ -2,5 +2,5 @@
 
 class Expect
   # Gem 与库共用的版本号；独立文件使 gemspec 无需加载完整会话实现。
-  VERSION = "0.3.3"
+  VERSION = "0.5.0"
 end