expect-pty 0.7.6 → 0.7.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1052a03b9bb9ac46051468e651c168d714f6be11aabd4bd8e2171dd390e2065a
-  data.tar.gz: 7c178220cc65517015144b2711679a3a26739efe1156dd144a26cb64fdfd6b46
+  metadata.gz: ad46afe78b754e37c5aa6995b9b1235d732a1f9faf372077b572e584ad186613
+  data.tar.gz: 7a3165503b1543396abde0d77713134296b7f2d818911c8bbca9e4b505d85227
 SHA512:
-  metadata.gz: 31b82ff772bc59ec35a4e3318be96b2b9c4b240898395c1bd8c543ed67515461d9ba282da415a1e208fbd9fb8f03390445cec132725873a039b3d75181fc552d
-  data.tar.gz: 1a7d7adfd64345c4e0d405657edd252e841430f65c335dc638708f43cdf20c4c12b4b8da28fe70b235801f8af50905595a6f982035a5ff73e9baafd02c8453d3
+  metadata.gz: 78b96691fcf4e0ab916286bfec7a978c3bb1de6fdc082af0ac3e5408eba3f2119c06789fd867b6f3552460ef0acee1aa45302ebb4081c21943197bd124f714c5
+  data.tar.gz: 9c7f6b06eb593608b4474fac1b0a06464cda52965221e815fd921677af1d889cdbed29aefc801d9e08383685517df293a290dc97de92e724b473608b21165c94

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.7.8 - 2026-10-11
+
+- 将内部资源所有权对象命名为 ResourceOwner，并统一源码、示例和测试辅助代码的中文注释。
+- 补齐字节前缀算法、脱敏窗口及基准、API 校验和示例辅助方法的契约注释，明确缓存、输入和副作用边界。
+
+## 0.7.7 - 2026-10-11
+
+- 修复人工接管时终端模式交接中断、恢复异常覆盖业务主异常的问题；分别尝试恢复两侧输出、转义规则和终端模式。
+- 修复 Matcher 与 Relay 在缓冲移交或归还期间被取消时丢失未消费输入的问题，仅在内部所有权交接期间延迟异步中断。
+- 使用对象身份索引选择背压读取来源，减少多会话互为转发目标时的重复遍历，保持来源顺序和背压行为。
+- SSH 示例保留 known_hosts 路径中的百分号，并在启动前拒绝 OpenSSH 会再次展开的 `${` 路径表达式。
+
 ## 0.7.6 - 2026-10-09
 
 - 修复会话关闭时日志异常覆盖原始错误的问题，保留进程等待、线程中断或句柄关闭的失败原因，并继续尝试完成诊断与 transcript 收尾。

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

@@ -64,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
 
@@ -268,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

@@ -2,14 +2,19 @@
 
 module Expect
   # 计算字节窗口尾部与规则真前缀重合的最长长度；转义暂存和流尾脱敏使用同一边界判断。
-  # 不持有输入或修改缓冲，调用方可为冻结规则提供前缀表缓存；短规则不建立表。
+  # 不持有输入或修改缓冲；仅长候选的扫描需要 KMP 回退表，冻结规则可跨调用缓存该表。
   # @api private
   module LiteralPrefix
+    # 返回 buffer 后缀与 pattern 真前缀重合的最大字节数；真前缀不包含完整 pattern。
+    # 例如 "xAB" 与 "ABC" 返回 2；空输入、长度不足 2 的规则或没有重合时返回 0。
+    # 两个字符串须由调用方转为二进制编码；此处不转码、不校验，也不修改它们。
+    # prefix_tables 为可选的可变 Hash；仅冻结 pattern 使用缓存，否则为本次调用建立临时表。
     def self.length(buffer, pattern, prefix_tables = nil)
       maximum = [pattern.bytesize - 1, buffer.bytesize].min
       return 0 unless maximum.positive?
 
-      # 尾字节不在候选前缀内时无需扫描；最长候选本身命中时也不必构造 KMP 表。
+      # 重合前缀的末字节必须等于输入尾字节；排除无法结束在该字节上的更长候选。
+      # 最长候选直接命中时不必构造回退表；小于 64 字节的候选改用有界枚举。
       ending = pattern.rindex(buffer.byteslice(-1, 1), maximum - 1)
       return 0 unless ending
 
@@ -19,6 +24,7 @@ module Expect
 
       failure = prefix_tables && pattern.frozen? ? (prefix_tables[pattern] ||= []) : []
       extend_failure_table(pattern, failure, maximum)
+      # 只扫描可能重合的尾部；不匹配时沿回退表保留已有重合，避免从每个候选起点重扫。
       matched = 0
       index = buffer.bytesize - maximum
       while index < buffer.bytesize
@@ -30,6 +36,9 @@ module Expect
       matched
     end
 
+    # 将同一规则的可变回退表补齐到 length 项，已有项不重算，较长的缓存也不截断。
+    # failure[i] 是 pattern[0..i] 的最长真前缀与后缀重合长度，供失配时选择下一匹配状态。
+    # length 不超过规则的真前缀长度；表只能用于生成它的同一规则内容。
     def self.extend_failure_table(pattern, failure, length)
       failure << 0 if failure.empty?
       matched = failure.last
@@ -49,6 +58,8 @@ module Expect
       end
     end
 
+    # 从 maximum 向下枚举短候选，返回首个后缀重合长度，无命中时返回 0。
+    # 调用方已限制候选规模；每次比较只切取规则前缀，不创建完整输入的副本或回退表。
     def self.short_length(buffer, pattern, maximum)
       maximum.downto(1) do |length|
         return length if buffer.end_with?(pattern.byteslice(0, length))

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

@@ -13,7 +13,7 @@ module Expect
       filter.append(data) + filter.finish(partial: false)
     end
 
-    # pending 保存尚不能安全输出的原字节，hidden 的对应字节用 0/1 表示是否需要遮盖。
+    # 复制冻结替换文本与规则；pending 保存尚不能安全输出的原字节，hidden 用 0/1 标记遮盖。
     def initialize(patterns, replacement: "[FILTERED]")
       unless replacement.is_a?(String) && !replacement.empty?
         raise ArgumentError, "replacement must be a nonempty String"
@@ -67,6 +67,7 @@ module Expect
     private
 
     # 输出资格与秘密掩码分开保存；仅遇到被抑制的分片时才分配额外字节图。
+    # 三个字节窗口始终对齐；先标记完整命中，再释放最长规则长度减一之外的安全前缀。
     def append_chunk(data, visible:)
       raise ArgumentError, "data must be a String" unless data.is_a?(String)
 
@@ -147,6 +148,7 @@ module Expect
     end
 
     # 仅级别切换后的流需要按输出资格再分段，普通过滤不承担额外区间调用。
+    # 将指定掩码区间中可见的字节追加到 output；被抑制的明文会断开 masking，隐藏字节不会。
     def release_suppressed(output, starting, ending, hidden:)
       while starting < ending
         suppressed = @suppressed.getbyte(starting) == 1

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_resources.rb → resource_owner.rb}

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 module Expect
-  # 独立保存句柄和 PID 所有权，让终结器无需直接捕获会话即可清理遗弃资源。
-  # IO 是否关闭与子进程是否退出分别记录；不能仅凭句柄状态清空 PID 或伪造退出状态。
+  # 管理 IO 关闭责任和直属子进程归属，供显式关闭与 GC 回收共用。
+  # 不直接引用 Session、日志目标或用户回调；句柄关闭与进程退出分别记录。
   # @api private
-  class SessionResources
-    # 缓存已取得的状态；被外部回收的进程仍保留未知状态，不伪造成功。
+  class ResourceOwner
+    # 缓存已取得的 Process::Status；被外部回收的进程仍保留未知状态，不伪造成功。
     attr_accessor :status
     # own 控制句柄关闭责任，owner 控制进程回收责任；fork 后两者不能混为一谈。
     attr_reader :pid, :reader, :writer, :slave, :owner, :own
@@ -60,7 +60,7 @@ module Expect
       status
     end
 
-    # GC 兜底关闭所属句柄并终止尚存活的子进程；不执行用户代码或软关闭等待。
+    # GC 兜底关闭所属句柄并终止尚存活的子进程；不调用会话日志或转义回调，也不进行软关闭等待。
     # 可直接用绑定到资源对象的 Method 注册终结器，忽略 Ruby 传来的被回收对象 ID。
     def finalize(_object_id = nil)
       return unless owner == Process.pid
@@ -77,7 +77,7 @@ module Expect
 
     private
 
-    # GC 只做一次非阻塞回收和最多两次信号尝试；失败也把等待交给 detach，不运行用户回调。
+    # GC 只做一次非阻塞回收和最多两次信号尝试；失败也把等待交给 detach，不调用会话日志或转义回调。
     def finalize_child
       begin
         reap

data/lib/expect/session.rb

@@ -5,7 +5,7 @@ require_relative "interaction"
 
 module Expect
   # 一个真实 PTY 或 IO 会话；缓冲、最近结果和所属进程都保存在本对象中。
-  # SessionResources 保存可独立回收的资源账本；Matcher、Relay 仅在操作期间借用会话状态。
+  # ResourceOwner 保存可独立回收的资源账本；Matcher、Relay 仅在操作期间借用会话状态。
   # 日志与协议目标属于调用方，显式关闭和 GC 均不得接管这些借用对象。
   class Session
     include Logging
@@ -58,7 +58,7 @@ module Expect
 
       @slave.raw! if raw
       from_child = to_parent = nil
-      Cleanup.always(-> { SessionResources.close_handles(from_child, to_parent) }) do
+      Cleanup.always(-> { ResourceOwner.close_handles(from_child, to_parent) }) do
         # 错误管道的写端在 exec 成功时自动关闭；父进程据此区分成功启动与 exec 前失败。
         # 管道返回到多重赋值之间也属于接管区间，确保 ensure 始终能找到两个端点。
         Thread.handle_interrupt(Object => :never) { from_child, to_parent = IO.pipe }
@@ -290,7 +290,7 @@ module Expect
       if @resources
         close(graceful:)
       elsif own
-        SessionResources.close_handles(reader, writer, slave)
+        ResourceOwner.close_handles(reader, writer, slave)
       end
     end
 
@@ -386,7 +386,7 @@ module Expect
     # 初始化前先登记所有权；参数校验失败也能释放已取得的端点。
     def initialize_io(reader, writer:, slave: nil, own: false, timeout: nil, write_timeout: nil,
                       buffer_limit: nil, logger: nil, transcript: nil, outputs: [])
-      @resources = SessionResources.new(reader, writer:, slave:, own:)
+      @resources = ResourceOwner.new(reader, writer:, slave:, own:)
       raise ArgumentError, "reader must be a real IO" unless reader.is_a?(IO) && !reader.closed?
       raise ArgumentError, "writer must be a real IO" unless writer.is_a?(IO) && !writer.closed?
 

data/lib/expect/version.rb

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

data/lib/expect.rb

@@ -5,7 +5,7 @@ require "io/console"
 require "stringio"
 require_relative "expect/version"
 require_relative "expect/result"
-require_relative "expect/session_resources"
+require_relative "expect/resource_owner"
 require_relative "expect/pattern"
 require_relative "expect/pattern_list"
 require_relative "expect/matcher"
@@ -72,7 +72,7 @@ module Expect
         if session && (block_given? || !initialized)
           session.cleanup_session(io, writer:, own:, graceful: initialized && graceful)
         elsif !session && own
-          SessionResources.close_handles(io, writer)
+          ResourceOwner.close_handles(io, writer)
         end
       end
       Cleanup.always(cleanup) do

data/sig/expect.rbs

@@ -1,4 +1,4 @@
-# Public Session API; internal matching and relay protocols are documented with @api private.
+# 公开 Session 接口；内部匹配与转接协议在源码中标记为 @api private。
 module Expect
   type duration = Numeric | String
   type pattern = String | Regexp | :eof | :timeout

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: expect-pty
 version: !ruby/object:Gem::Version
-  version: 0.7.6
+  version: 0.7.8
 platform: ruby
 authors:
 - expect-pty contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-09 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: io-console
@@ -76,9 +76,9 @@ files:
 - lib/expect/redactor.rb
 - lib/expect/relay.rb
 - lib/expect/relay_writer.rb
+- lib/expect/resource_owner.rb
 - lib/expect/result.rb
 - lib/expect/session.rb
-- lib/expect/session_resources.rb
 - lib/expect/version.rb
 - sig/expect.rbs
 homepage: https://github.com/gatework/expect-ruby