expect-pty 0.7.5 → 0.7.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 472fea69b87e58d9b08004f799da6d584508c87832227da3385301953a20070f
-  data.tar.gz: fc6720abad1ee0daff9943e9c0f19dc144e949bb543a67b590a32500a1088688
+  metadata.gz: 45e6676261fec4b5bcd7db41298fd513a47da86308a29f53702311a6b5219f59
+  data.tar.gz: 19354431d871147ebd778424288ea2d3a2f788d92e8674f6c779b8c560b23f1b
 SHA512:
-  metadata.gz: 8074ccf919b4f5a8d73d55a6acf8c40c3069a253cc5cd4e4acacec17f5277b157a62235987430519c2204d783b736d134b92963d29994aea56d639ceab1d3dd3
-  data.tar.gz: 9b8879d3c0291ceeedb77624d352c8fa2f13a04412f777d45b6d4b0ed2dea3e32cb56cef041c65e297bc4687515a8772e29d42ca8a45993ae1ba21d7a7289b21
+  metadata.gz: efdb068466acf441e74d839e9830d31f59ab18bf989726319dc6f97fb049d34a913ef53fdc399b6287bebc94d3993a5b97fb8fe41965c3c1a5e6ed3fb9aba924
+  data.tar.gz: c4c4d20ef93293c8958da3ffcf6f2ebc0245b37b07caea6fe5f2af3b9ef73ba29d365134f5c7be1a693a43a3c163724143a805ad4f19d27266df7ec7e9485717

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.7.7 - 2026-10-11
+
+- 修复人工接管时终端模式交接中断、恢复异常覆盖业务主异常的问题；分别尝试恢复两侧输出、转义规则和终端模式。
+- 修复 Matcher 与 Relay 在缓冲移交或归还期间被取消时丢失未消费输入的问题，仅在内部所有权交接期间延迟异步中断。
+- 使用对象身份索引选择背压读取来源，减少多会话互为转发目标时的重复遍历，保持来源顺序和背压行为。
+- SSH 示例保留 known_hosts 路径中的百分号，并在启动前拒绝 OpenSSH 会再次展开的 `${` 路径表达式。
+
+## 0.7.6 - 2026-10-09
+
+- 修复会话关闭时日志异常覆盖原始错误的问题，保留进程等待、线程中断或句柄关闭的失败原因，并继续尝试完成诊断与 transcript 收尾。
+- 优化长秘密的流尾脱敏和长字面转义扫描，减少近似前缀输入下的耗时与临时对象，保持分片、重叠和部分秘密的过滤行为。
+
 ## 0.7.5 - 2026-10-08
 
 - 修复 PTY、启动错误管道和工厂初始化的异步中断交接窗口；线程中断或终止后立即关闭已取得的句柄，保持用户初始化协议可中断。

data/docs/API.md

@@ -114,6 +114,7 @@ DEBUG 关闭期间仍推进分片脱敏，但这些字节不会在重新启用
 
 `interact(input: $stdin, escape: nil, output: nil, timeout: nil, raw: true)` 临时建立双向转接，退出后恢复
 outputs、转义和本地终端模式。
+各项恢复都会尝试；恢复中的常规错误不会覆盖已有的业务异常，没有业务异常时仍报告恢复错误。
 `output: nil` 使用默认输出，`escape: nil` 不注册退出序列；显式 false 不是缺省值，非法输出或转义会在转发前报错。
 `raw: false` 将终端设置留给调用方。transcript、logger 及自定义 writer 同步执行，应及时返回。
 

data/lib/expect/interaction.rb

@@ -2,6 +2,7 @@
 
 require_relative "relay_writer"
 require_relative "relay"
+require_relative "literal_prefix"
 
 # 为会话补充人工接管和多路 IO 转接；核心会话定义位于 session.rb。
 module Expect
@@ -63,20 +64,14 @@ module Expect
       saved_self = outputs
       saved_source = [source.outputs, source.sequences.dup]
       terminal_state = prepare_interact_terminal(source) if raw
-      display = interact_display(source, output, terminal_state)
-      # 临时建立“用户输入 -> 子进程 -> 显示输出”的双向连接，原监听关系在 ensure 中恢复。
-      self.outputs = [display]
-      source.outputs = [self]
-      source.on_sequence(escape) unless escape.nil?
-      Relay.new([self, source], timeout).run
-    ensure
-      begin
-        if saved_self
-          self.outputs = saved_self
-          source.outputs, source.sequences = saved_source
-        end
-      ensure
-        restore_interact_terminal(terminal_state)
+      # 先持有恢复快照，再在同一清理作用域内切换终端；返回值交接中断不能留下 raw 模式。
+      Cleanup.always(-> { restore_interact(source, saved_self, saved_source, terminal_state) }) do
+        terminal_state&.first&.raw!
+        display = interact_display(source, output, terminal_state)
+        self.outputs = [display]
+        source.outputs = [self]
+        source.on_sequence(escape) unless escape.nil?
+        Relay.new([self, source], timeout).run
       end
     end
 
@@ -179,59 +174,12 @@ module Expect
       sequences.each_key do |key|
         next if key.is_a?(Regexp)
 
-        prefix_length = literal_prefix_suffix(buffer, key, prefix_tables)
+        prefix_length = LiteralPrefix.length(buffer, key, prefix_tables)
         held = prefix_length if prefix_length > held
       end
       held
     end
 
-    # KMP 在缓冲尾部寻找规则前缀，长规则只扫描相关字节一次，避免逐短前缀反复复制和比较。
-    # 短规则使用原生字符串操作，避免为小输入建立前缀表。
-    def self.literal_prefix_suffix(buffer, key, prefix_tables = {})
-      maximum = [key.bytesize - 1, buffer.bytesize].min
-      return 0 unless maximum.positive?
-      return short_literal_prefix_suffix(buffer, key, maximum) if maximum < 64
-
-      failure = key.frozen? ? (prefix_tables[key] ||= []) : []
-      literal_prefix_failure_table(key, failure, maximum)
-      matched = 0
-      index = buffer.bytesize - maximum
-      while index < buffer.bytesize
-        byte = buffer.getbyte(index)
-        matched = failure[matched - 1] while matched.positive? && byte != key.getbyte(matched)
-        matched += 1 if byte == key.getbyte(matched)
-        index += 1
-      end
-      matched
-    end
-
-    def self.literal_prefix_failure_table(key, failure, length)
-      failure << 0 if failure.empty?
-      matched = failure.last
-      index = failure.length
-      while index < length
-        byte = key.getbyte(index)
-        if byte == key.getbyte(matched)
-          matched += 1
-          failure << matched
-          index += 1
-        elsif matched.positive?
-          matched = failure[matched - 1]
-        else
-          failure << 0
-          index += 1
-        end
-      end
-      failure
-    end
-
-    def self.short_literal_prefix_suffix(buffer, key, maximum)
-      maximum.downto(1) do |length|
-        return length if buffer.end_with?(key.byteslice(0, length))
-      end
-      0
-    end
-
     # 已转发历史有界保留，固定 UTF-8 正则不能从续字节开始匹配。
     def self.trim_history(history, data, limit:, utf8:)
       history << data
@@ -243,9 +191,7 @@ module Expect
       history.slice!(0) while (byte = history.getbyte(0)) && (0x80..0xBF).cover?(byte)
     end
 
-    private_class_method :expired?, :handle_escape, :scan_sequences, :hold_literal_prefix,
-                         :literal_prefix_suffix, :literal_prefix_failure_table,
-                         :short_literal_prefix_suffix, :trim_history
+    private_class_method :expired?, :handle_escape, :scan_sequences, :hold_literal_prefix, :trim_history
 
     # 为当前数据块冻结目标选择并各建一个发送游标；此后修改 outputs 只影响后续数据。
     # 调用方须先排空旧游标；显示转换也只做一次，短写重试时不能重复转换 CRLF。
@@ -316,16 +262,20 @@ module Expect
       @interact_inputs[input] ||= Expect.open(input)
     end
 
-    # 只有 interact 知道哪个流是本地键盘；通用 interconnect 不修改终端模式。
+    # 只取得快照；实际 raw! 由持有快照的 interact 在清理作用域内执行。
     def prepare_interact_terminal(source)
       return unless source.tty?
 
-      state = nil
-      Cleanup.on_failure(-> { restore_interact_terminal(state) }) do
-        io = source.to_io
-        state = [io, io.console_mode]
-        io.raw!
-        state
+      io = source.to_io
+      [io, io.console_mode]
+    end
+
+    # 独立尝试每项恢复；常规恢复错误不能覆盖业务主异常，新的中断仍按 Cleanup 契约传播。
+    def restore_interact(source, saved_self, saved_source, terminal_state)
+      Cleanup.always(-> { restore_interact_terminal(terminal_state) }) do
+        Cleanup.always(-> { source.sequences = saved_source.last }) do
+          Cleanup.always(-> { source.outputs = saved_source.first }) { self.outputs = saved_self }
+        end
       end
     end
 

data/lib/expect/literal_prefix.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Expect
+  # 计算字节窗口尾部与规则真前缀重合的最长长度；转义暂存和流尾脱敏使用同一边界判断。
+  # 不持有输入或修改缓冲，调用方可为冻结规则提供前缀表缓存；短规则不建立表。
+  # @api private
+  module LiteralPrefix
+    def self.length(buffer, pattern, prefix_tables = nil)
+      maximum = [pattern.bytesize - 1, buffer.bytesize].min
+      return 0 unless maximum.positive?
+
+      # 尾字节不在候选前缀内时无需扫描；最长候选本身命中时也不必构造 KMP 表。
+      ending = pattern.rindex(buffer.byteslice(-1, 1), maximum - 1)
+      return 0 unless ending
+
+      maximum = ending + 1
+      return maximum if buffer.end_with?(pattern.byteslice(0, maximum))
+      return short_length(buffer, pattern, maximum - 1) if maximum < 64
+
+      failure = prefix_tables && pattern.frozen? ? (prefix_tables[pattern] ||= []) : []
+      extend_failure_table(pattern, failure, maximum)
+      matched = 0
+      index = buffer.bytesize - maximum
+      while index < buffer.bytesize
+        byte = buffer.getbyte(index)
+        matched = failure[matched - 1] while matched.positive? && byte != pattern.getbyte(matched)
+        matched += 1 if byte == pattern.getbyte(matched)
+        index += 1
+      end
+      matched
+    end
+
+    def self.extend_failure_table(pattern, failure, length)
+      failure << 0 if failure.empty?
+      matched = failure.last
+      index = failure.length
+      while index < length
+        byte = pattern.getbyte(index)
+        if byte == pattern.getbyte(matched)
+          matched += 1
+          failure << matched
+          index += 1
+        elsif matched.positive?
+          matched = failure[matched - 1]
+        else
+          failure << 0
+          index += 1
+        end
+      end
+    end
+
+    def self.short_length(buffer, pattern, maximum)
+      maximum.downto(1) do |length|
+        return length if buffer.end_with?(pattern.byteslice(0, length))
+      end
+      0
+    end
+
+    private_class_method :extend_failure_table, :short_length
+  end
+
+  private_constant :LiteralPrefix
+end

data/lib/expect/logging.rb

@@ -87,6 +87,12 @@ module Expect
 
     private
 
+    # 关闭时两种记录都要尝试完成；后续 writer 的常规异常不能覆盖先发生的诊断异常。
+    # 不关闭借用目标，新的 Interrupt/SystemExit 仍由 Cleanup 原样传播。
+    def finish_logging
+      Cleanup.always(-> { self.transcript = nil }) { flush_diagnostics }
+    end
+
     # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
     # 这里遵循同步写入协议，不受 Matcher 的 IO 等待期限中断；慢目标转接应使用 Relay。
     # 短写只推进已确认的字节数；目标抛错时不猜测它是否已经产生副作用。

data/lib/expect/matcher.rb

@@ -25,17 +25,7 @@ module Expect
     # 运行匹配状态机；内部 :retry 表示继续循环，最终返回一个 Result。
     def run
       @relay_buffers = {}.compare_by_identity
-      @sessions.each do |session|
-        buffer = session.interaction_buffer
-        if buffer
-          # 转义回调中的显式匹配临时接管读取，先消费转接已经预读的尾部。
-          @relay_buffers[session] = buffer
-          session.interaction_buffer = nil
-          session.restore_relay_buffer(buffer)
-          buffer.clear
-        end
-        session.reset_result
-      end
+      prepare_sessions
       loop do
         # 先消费已缓冲的匹配，再处理 EOF，最后读取；避免进程退出时丢失最后一个匹配。
         result = if !@expired_eof_continuation && !hard_expired? && (matched = find_match)
@@ -50,15 +40,39 @@ module Expect
         return result unless result == :retry
       end
     ensure
-      # 嵌套 expect 即使异常退出，也要把未消费尾部还给原 Relay 的同一个缓冲对象。
-      @relay_buffers.each do |session, buffer|
-        buffer.replace(session.take_buffer)
-        session.interaction_buffer = buffer
-      end
+      restore_relay_buffers
     end
 
     private
 
+    # 转义回调中的匹配临时接管预读尾部；缓冲登记和移交是一个不可拆开的状态变更。
+    # 仅内部所有权操作延迟异步取消，扫描、IO、日志及用户回调仍可立即中断。
+    def prepare_sessions
+      @sessions.each do |session|
+        if (buffer = session.interaction_buffer)
+          Thread.handle_interrupt(Object => :never) do
+            @relay_buffers[session] = buffer
+            session.interaction_buffer = nil
+            session.restore_relay_buffer(buffer)
+            buffer.clear
+          end
+        end
+        session.reset_result
+      end
+    end
+
+    # 先归还所有借用来源再交付新的取消；返回尾部与恢复原缓冲对象不能被中断拆开。
+    def restore_relay_buffers
+      return if @relay_buffers.empty?
+
+      Thread.handle_interrupt(Object => :never) do
+        @relay_buffers.each do |session, buffer|
+          buffer.replace(session.take_buffer)
+          session.interaction_buffer = buffer
+        end
+      end
+    end
+
     # 按声明组、会话、模式的顺序寻找首个匹配，不按文本中的出现位置重新排序。
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 声明优先级与单轮缓冲须在同一次扫描保持一致。
     def find_match

data/lib/expect/redactor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "literal_prefix"
+
 module Expect
   # 单个日志字节流的过滤器。保留最长秘密长度减一的尾部，跨 write/read 分片仍可识别。
   # 掩码与原字节一起留存；重叠命中的区间取并集，已经输出的掩码不重复生成。
@@ -78,20 +80,13 @@ module Expect
 
     # 流关闭时无法再等待后续字节，默认隐藏与秘密开头一致的未完成尾部。
     def mark_partial_secrets
-      tail = @pending.byteslice(-1, 1)
-      return unless tail
+      return if @pending.empty?
 
       @patterns.each do |pattern|
-        length = [pattern.bytesize - 1, @pending.bytesize].min
-        # 前缀必须以当前尾字节结束；只收紧最高候选长度，密集候选仍沿用简单倒序扫描。
-        next unless length.positive? && (offset = pattern.rindex(tail, length - 1))
-
-        (offset + 1).downto(1) do |candidate|
-          next unless @pending.end_with?(pattern.byteslice(0, candidate))
+        length = LiteralPrefix.length(@pending, pattern)
+        next unless length.positive?
 
-          @hidden[-candidate, candidate] = "\1" * candidate
-          break
-        end
+        @hidden[-length, length] = "\1" * length
       end
     end
 

data/lib/expect/relay.rb

@@ -142,21 +142,27 @@ module Expect
 
         @sessions.each { |session| session.relay_owner = @token }
       end
-      @sessions.each do |session|
-        @previous[session] = session.interaction_buffer
-        @buffers[session] = session.take_buffer
-        session.interaction_buffer = @buffers.fetch(session)
+      # take_buffer 已移出会话后，必须先登记到本轮账本才能交付异步取消；此处不执行 IO 或用户回调。
+      Thread.handle_interrupt(Object => :never) do
+        @sessions.each do |session|
+          @previous[session] = session.interaction_buffer
+          @buffers[session] = session.take_buffer
+          session.interaction_buffer = @buffers.fetch(session)
+        end
       end
     end
 
     # 未处理输入还给会话，已排队字节仍归游标；构造中断也只恢复已转移的缓冲及自己的标记。
     def restore_sources
-      @previous.each { |session, buffer| session.interaction_buffer = buffer }
-      @buffers.each { |session, buffer| session.restore_relay_buffer(buffer) }
-    ensure
-      OWNERSHIP_MUTEX.synchronize do
-        @sessions.each do |session|
-          session.relay_owner = nil if session.relay_owner.equal?(@token)
+      # 归还多来源缓冲和释放 token 属于同一交接，不能只恢复前几个来源就响应取消。
+      Thread.handle_interrupt(Object => :never) do
+        @previous.each { |session, buffer| session.interaction_buffer = buffer }
+        @buffers.each { |session, buffer| session.restore_relay_buffer(buffer) }
+      ensure
+        OWNERSHIP_MUTEX.synchronize do
+          @sessions.each do |session|
+            session.relay_owner = nil if session.relay_owner.equal?(@token)
+          end
         end
       end
     end
@@ -184,13 +190,13 @@ module Expect
     # 背压源暂停吸收新输入，限制排队增长；作为写入目标的会话仍需读取以解除双向等待。
     def read_sources(pending)
       # 输出目标可能也在等待我们读取；这些来源即使有待发送数据也必须继续排空。
-      targets = pending.filter_map do |output|
-        output.target if output.target.is_a?(Session)
+      targets = pending.each_with_object({}.compare_by_identity) do |output, index|
+        index[output.target] = true if output.target.is_a?(Session)
       end
       sources = @active.reject do |session|
-        session.pending_output? && targets.none? { |target| target.equal?(session) }
+        session.pending_output? && !targets.key?(session)
       end
-      (sources + targets).uniq { |session| session.to_io.object_id }.reject(&:eof?)
+      (sources + targets.keys).uniq { |session| session.to_io.object_id }.reject(&:eof?)
     end
 
     # 总期限结束时将可交付尾部转为发送游标，至多尝试一轮交付；余量由源会话保存。

data/lib/expect/session.rb

@@ -503,30 +503,26 @@ module Expect
         failure ||= error
         nil
       end
-      # IO 关闭与进程退出独立记录：软关闭可能已经 closed?，但仍保留活跃 PID。
-      cleanup.call { @resources.close_handles }
-      @closed = true
-      @interact_inputs&.delete_if do |_io, input|
-        cleanup.call do
-          input.close(graceful: false)
-          true
+      # 日志收尾是本作用域的清理：不能覆盖进程等待/中断或已记录的句柄错误。
+      Cleanup.always(-> { finish_logging }) do
+        # IO 关闭与进程退出独立记录：软关闭可能已经 closed?，但仍保留活跃 PID。
+        cleanup.call { @resources.close_handles }
+        @closed = true
+        @interact_inputs&.delete_if do |_io, input|
+          cleanup.call do
+            input.close(graceful: false)
+            true
+          end
         end
+        @interact_output = nil
+        @pending_writes&.clear
+        @relay_history&.clear
+        @relay_callback = nil
+        status = close_child(timeout:, term_timeout:, force:)
+        raise failure if failure
+
+        status
       end
-      @interact_output = nil
-      @pending_writes&.clear
-      @relay_history&.clear
-      @relay_callback = nil
-      status = close_child(timeout:, term_timeout:, force:)
-      completed = true
-      status
-    ensure
-      begin
-        cleanup.call { flush_diagnostics }
-      ensure
-        cleanup.call { self.transcript = nil }
-      end
-      # 用本次流程的完成状态判断异常传播，不能误把调用者 rescue 中的异常当成当前错误。
-      raise failure if failure && completed
     end
 
     # 句柄清理失败不改变进程策略；未回收 PID 保留给重复关闭或终结器继续处理。

data/lib/expect/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: expect-pty
 version: !ruby/object:Gem::Version
-  version: 0.7.5
+  version: 0.7.7
 platform: ruby
 authors:
 - expect-pty contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-08 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: io-console
@@ -67,6 +67,7 @@ files:
 - lib/expect.rb
 - lib/expect/cleanup.rb
 - lib/expect/interaction.rb
+- lib/expect/literal_prefix.rb
 - lib/expect/logging.rb
 - lib/expect/matcher.rb
 - lib/expect/pattern.rb