expect-pty 0.9.2 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d6ae394cf13d882d00a78b0684c158551e08896bf572272790d68cc7850d804
-  data.tar.gz: 2cada03b8804a8402bec3dfdbc54f705650d1b47d57b410e3e6c83d35af4cd9c
+  metadata.gz: bd51e466710a92cea41212f9cb4477f73f586ff44f53fa57676be9562b59f037
+  data.tar.gz: a848149d3069fafefffe5618c9293eed72b569dab3879a783edee292271a25c2
 SHA512:
-  metadata.gz: 64dbb1fbbed803a50dedda414a59f662121adcfee88de614f563e1de1d2f7c195f82d77f415a3a0fc545b420f5158e252637dada211c8ac35a98fa1728868748
-  data.tar.gz: d060fd85a2344e4e18d15257506844908f332100538517edbf6b5395e2a6bef0c98e0c12c44d21d26074eccb690ef6d1f81b4508056e85107239c84de3d7a09e
+  metadata.gz: 19709a17b0f7a69db8d8eac19e6bec88259bd37475394a4a0d27e1406a33244bef839cc6627696c8b72a1df5b873b27c2ef55004003a07e66b3e82323d5322be
+  data.tar.gz: f2806cb9db50e6b82bfe0c72a7affd28f1ab50b716688c1dc027aa75fff5c049fffe2f20348695b32a06cb41f1ec2fba426ccef8b4789a2304a388a1908d0e93

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.9.4 - 2026-10-19
+
+- 将字面未命中进度归一为内部 LiteralScan，供匹配与转接复用；大缓冲分块转接不再反复搜索已排除的范围，保留跨块转义与回调修改规则的行为。
+- 转接活跃来源改用按对象身份维护的有序索引，避免批量 EOF 继续处理时反复遍历剩余来源。
+- 修复句柄关闭和进程回收同时失败时后一个系统错误覆盖首个错误的问题；后续致命中断仍原样传播，失败资源可重试清理。
+
+- 新增公开的 `Session#buffer_bytesize`，以常数时间查询当前主缓冲字节数，避免容量检查创建正文快照；原 `buffer` 的防御性复制契约不变。
+
+## 0.9.3 - 2026-10-18
+
+- 结果的 inspect 与 to_s 仅输出匹配序号和错误状态，避免诊断、字符串插值泄露匹配文本、捕获内容或异常消息；原始结果字段保持不变。
+- 工厂块异常、取消或非局部退出时跳过 graceful 读尾，直接硬关闭；正常返回（包括 nil/false）仍可收取尾部输出。
+
 ## 0.9.2 - 2026-10-18
 
 - 减少显式搜索窗口下字面量匹配的内存分配，保留原始字节偏移、声明优先级和正则窗口语义。

data/docs/API.md

@@ -19,6 +19,8 @@ Session 构造器不接收命令或操作参数。同一会话只能启动一次
 `Expect.open(io, writer: io, own: false, graceful: false, **settings)` 适配真实可 select 的 IO，默认借用。
 `own: true` 接管关闭责任，包括初始化中已知设置的非法值导致的失败；未知关键字在 Ruby 方法入口拒绝，此时不接管 IO。
 `spawn`、`open` 无块时返回 Session，有块时返回块结果并确保按 `graceful:` 关闭；非局部返回也清理。
+工厂块正常返回时才执行 graceful 读尾；异常、线程取消以及 return/break/throw 等非局部退出直接硬关闭，避免读尾延迟退出。
+块正常返回 nil 或 false 仍属于正常完成；调用方 rescue 中已处理的异常不影响此判断。
 清理中的 StandardError 不覆盖本次作用域已有的主异常；没有主异常时照常传播。新发生的 Interrupt/SystemExit 不会被清理包装吞掉。
 
 `close(graceful: false)` 最终硬关闭兜底，返回 nil；`soft_close(timeout: 15, term_timeout: 1)` 收取尾部、关闭句柄并最多发送
@@ -65,6 +67,8 @@ nil 保留全缓冲扫描；指定时，字符串和正则只搜索最新的尾
 固定 UTF-8 正则跳过边界切开的合法首字符，等待合法未完成尾字符；窗口内非法字节及 EOF 未完成字符仍报错。
 二进制正则按原始字节匹配。
 
+Result 的 `inspect` 与 `to_s` 仅显示匹配序号和错误状态，不打印原始文本、异常消息或来源对象。
+需要原始结果时显式读取字段；`redact` 不改变这些字段。
 Result 字段为 `number`、`error`、`match`、`before`、`after`、`session`、`captures`。对象、文本及捕获数组均不可变，未参与捕获为
 nil。
 错误为 nil、`:timeout`、`:eof` 或原始 IO 异常；来源会话与异常不复制、不冻结。使用 `matched?`、`timeout?`、`eof?` 查询，
@@ -130,7 +134,7 @@ end
 | outputs                | []     | 复制可写目标数组，原样转发接收字节   |
 
 操作参数 `raw`、`consume`、`reset_timeout_on_read`、`graceful` 不持久化为会话设置。
-`buffer` 返回副本，`buffer=` 复制并应用上限，`clear_buffer` 移交并清空缓冲；`buffer_discarded_bytes` 累计窗口裁剪量，匹配消费不计入。
+`buffer` 返回副本；只检查容量时使用 `buffer_bytesize`，以常数时间取得当前未消费主缓冲的字节数，不复制正文、不读取 IO，也不包含 Relay 待写数据或历史窗口。`buffer=` 复制并应用上限，`clear_buffer` 移交并清空缓冲；`buffer_discarded_bytes` 累计窗口裁剪量，匹配消费不计入。
 显式替换/清空、实际裁剪和消费输入会清除正则转义历史；非消费匹配、未裁剪的等待与内部缓冲交接保持连续历史。
 正则转接历史默认保留至多 65,536 字节，设置 `buffer_limit` 后采用该上限。存在固定 UTF-8 正则时，历史预算至少为 3 字节，以保留四字节字符尚未接收完整的前缀；这不扩大普通匹配缓冲的上限，也不延迟协议转发。
 

data/docs/COMPATIBILITY.md

@@ -46,7 +46,8 @@ PID。`hard_close` 不等待输出，必要时 TERM、KILL 并回收子进程。
 
 Ruby 使用关键字指定各阶段期限，关闭方法返回 `Process::Status` 或 `nil`。`close(graceful: true)` 或工厂块的
 `graceful: true`
-先尝试软关闭，再在 `ensure` 中硬关闭；这对应原版销毁时可选软关闭、随后硬关闭的清理策略。`close` 返回 `nil`；GC
+先尝试软关闭，再在 `ensure` 中硬关闭；工厂块仅正常返回时读尾，异常、取消及非局部退出直接硬关闭。
+显式 `close(graceful: true)` 仍按调用参数读尾。`close` 返回 `nil`；GC
 兜底直接强制清理，不阻塞等待。
 
 ## 有意采用的 Ruby 语义

data/lib/expect/interaction.rb

@@ -3,6 +3,7 @@
 require_relative "relay/writer"
 require_relative "relay"
 require_relative "literal_prefix"
+require_relative "literal_scan"
 
 # 为会话补充人工接管和多路 IO 转接；核心会话定义位于 session.rb。
 module Expect
@@ -81,14 +82,17 @@ module Expect
     # 将待处理输入排入唯一的转接发送队列；返回 :ready、:queued、:stopped 或 :timeout。
     # 字面序列暂存潜在前缀，正则序列结合历史匹配；final 为真时不再等待后续字节。
     # @api private
-    def self.queue_input(session, buffer, final: false, deadline: nil)
+    def self.queue_input(session, buffer, final: false, deadline: nil, literal_scan: nil)
       loop do
         sequences = session.sequences.except(:eof)
         history = session.relay_history
-        found, regexp_scanned, utf8_regexp = scan_sequences(buffer, sequences, history, final:)
+        found, regexp_scanned, utf8_regexp = scan_sequences(
+          buffer, sequences, history, final:, literal_scan:, generation: session.buffer_generation
+        )
         return :timeout if expired?(deadline)
 
         if found
+          literal_scan&.reset
           result = handle_escape(session, buffer, history, found)
           return result unless result == :ready
           return :timeout if expired?(deadline)
@@ -108,7 +112,10 @@ module Expect
         end
         # 排队前缀与尾部可共享原字节；替换窗口而非删除前缀，避免逐块复制整个余量。
         # 保留缓冲对象身份，嵌套 Matcher 仍把尾部交回 Relay 借用的同一个对象。
-        buffer.replace(buffer.byteslice(count..)) if count.positive?
+        if count.positive?
+          buffer.replace(buffer.byteslice(count..))
+          literal_scan&.advance(count)
+        end
         return count.positive? ? :queued : :ready
       end
     end
@@ -134,7 +141,7 @@ module Expect
     end
 
     # 单轮正则共用一个组合文本；回调返回后下一轮重新取得规则和历史。
-    def self.scan_sequences(buffer, sequences, history, final:)
+    def self.scan_sequences(buffer, sequences, history, final:, literal_scan: nil, generation: nil)
       text = nil
       utf8_regexp = false
       earliest = nil
@@ -153,7 +160,7 @@ module Expect
           # 历史前缀已实时转发，不能撤回；负偏移表示本次只需消费转义尚未转发的部分。
           offset -= history.bytesize
         else
-          offset = buffer.index(key)
+          offset = literal_scan ? literal_scan.index(buffer, key, generation:) : buffer.index(key)
           next unless offset
 
           length = key.bytesize

data/lib/expect/literal_scan.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Expect
+  # 一个连续字节窗口的字面未命中进度；不持有输入、会话或 IO。
+  # Matcher 的窗口只追加，Relay 还会移出安全前缀，两者共用绝对字节坐标。
+  # @api private
+  class LiteralScan
+    def initialize
+      @misses = {}.compare_by_identity
+      @consumed = 0
+      @generation = nil
+    end
+
+    # 返回相对当前窗口的字节位置；新输入只重扫可能跨越旧尾部的重叠区。
+    # literal 须为冻结的二进制 String，generation 变化表示窗口被替换、裁剪或外部消费。
+    def index(buffer, literal, generation:)
+      if @generation != generation
+        reset
+        @generation = generation
+      end
+      ending = @consumed + buffer.bytesize
+      previous = @misses[literal]
+      return nil if previous == ending
+
+      offset = previous ? [previous - @consumed - literal.bytesize + 1, 0].max : 0
+      position = buffer.index(literal, offset)
+      if position
+        @misses.delete(literal)
+      else
+        @misses[literal] = ending
+      end
+      position
+    end
+
+    # Relay 仅移出已扫描的安全前缀；未命中范围仍有效，无须逐规则调整偏移。
+    def advance(count)
+      @consumed += count
+    end
+
+    # 转义消费或外部修改建立新边界，后续扫描不能复用旧输入的结论。
+    def reset
+      @misses.clear
+      @consumed = 0
+      @generation = nil
+    end
+  end
+  private_constant :LiteralScan
+end

data/lib/expect/matcher.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "literal_scan"
+
 module Expect
   # 驱动一次单会话或多会话匹配，管理模式优先级、EOF 和共享期限，不接管 IO 所有权。
   # 调度只在扫描、回调和 IO 操作之间检查期限，不强行中断用户代码或单次正则计算。
@@ -124,27 +126,10 @@ module Expect
     # 仅复用同一缓冲代次中的字面未命中。保留模式长度减一的重叠区，覆盖跨读取命中。
     # 不保存整个文本，也不对正则推断扫描窗口；回调替换、消费或转接恢复会改变代次。
     def locate_literal(session, pattern, buffer)
-      @literal_misses ||= {}.compare_by_identity
-      misses = (@literal_misses[session] ||= {}.compare_by_identity)
-      previous = misses[pattern]
-      generation = session.buffer_generation
-      # 模式已冻结；缓冲代次未变意味着只有尾部追加。
-      offset = if previous && previous[0] == generation
-                 return nil if previous[1] == buffer.bytesize
-
-                 [previous[1] - pattern.value.bytesize + 1, 0].max
-               else
-                 0
-               end
-      position = pattern.locate(buffer, offset:)
-      if position
-        misses.delete(pattern)
-      else
-        entry = (misses[pattern] ||= [])
-        entry[0] = generation
-        entry[1] = buffer.bytesize
-      end
-      position
+      @literal_scans ||= {}.compare_by_identity
+      scan = (@literal_scans[session] ||= LiteralScan.new)
+      offset = scan.index(buffer, pattern.value, generation: session.buffer_generation)
+      [offset, pattern.value.bytesize, []] if offset
     end
 
     # 先记录并消费匹配，再执行回调；回调可选择结束、重置期限或保留期限继续。

data/lib/expect/pty.rb

@@ -66,12 +66,12 @@ module Expect
               timeout: nil, write_timeout: nil, buffer_limit: nil, logger: nil, transcript: nil, outputs: [])
       session = nil
       spawned = false
-      cleanup = lambda do
+      cleanup = lambda do |completed|
         if session && (block_given? || !spawned)
-          session.cleanup_session(nil, writer: nil, own: false, graceful: spawned && graceful)
+          session.cleanup_session(nil, writer: nil, own: false, graceful: spawned && graceful && completed)
         end
       end
-      Cleanup.always(cleanup) do
+      Cleanup.always(cleanup, report_completion: true) do
         # 工厂在构造期间处理失败；成功对象的返回与登记不可被中断拆开。
         Thread.handle_interrupt(Object => :never) do
           session = SessionFactory.pty(timeout:, write_timeout:, buffer_limit:, logger:, transcript:, outputs:)
@@ -89,14 +89,14 @@ module Expect
       session = nil
       initialized = false
       constructing = false
-      cleanup = lambda do
+      cleanup = lambda do |completed|
         if session && (block_given? || !initialized)
-          session.cleanup_session(io, writer:, own:, graceful: initialized && graceful)
+          session.cleanup_session(io, writer:, own:, graceful: initialized && graceful && completed)
         elsif !session && own && !constructing
           ResourceOwner.close_handles(io, writer)
         end
       end
-      Cleanup.always(cleanup) do
+      Cleanup.always(cleanup, report_completion: true) do
         Thread.handle_interrupt(Object => :never) do
           constructing = true
           session = SessionFactory.io(io, writer:, own:, timeout:, write_timeout:, buffer_limit:,

data/lib/expect/relay.rb

@@ -12,7 +12,8 @@ module Expect
     # 这里只校验参数；run 取得所有来源后才转移缓冲，不关闭或接管任何外部 IO。
     def initialize(sessions, timeout)
       @sessions = sessions.uniq(&:object_id)
-      @active = @sessions.dup
+      # 按对象身份保留声明顺序；每个 EOF 仅删除自身，避免逐个重扫剩余来源。
+      @active = @sessions.each_with_object({}.compare_by_identity) { |session, active| active[session] = true }
       period = Expect.duration(timeout)
       @deadline = period && (Expect.monotonic + period)
       # 零超时保留首轮缓冲及一次轮询；正预算在扫描和每次回调之间重新检查。
@@ -20,6 +21,7 @@ module Expect
       @token = Object.new
       @buffers = {}.compare_by_identity
       @previous = {}.compare_by_identity
+      @literal_scans = {}.compare_by_identity
     end
 
     # 每轮先处理转义和已排队输出，再共同选择读写；停止返回来源会话，总期限到达返回 nil。
@@ -52,7 +54,7 @@ module Expect
     def dispatch_sources
       idle = []
       queued = false
-      @active.dup.each do |session|
+      @active.each_key do |session|
         return [:timeout, idle, queued] if dispatch_expired?
 
         next if session.pending_output?
@@ -72,7 +74,7 @@ module Expect
         callback = session.sequences[:eof]
         return [session, idle, queued] unless callback&.call
 
-        @active.delete_if { |active| active.equal?(session) }
+        @active.delete(session)
         return [:timeout, idle, queued] if dispatch_expired?
       end
       [nil, idle, queued]
@@ -82,11 +84,18 @@ module Expect
     def dispatch_input(session)
       if (callback = session.relay_callback)
         session.relay_callback = nil
+        @literal_scans[session]&.reset
         return :stopped unless callback.call
         return :timeout if dispatch_expired?
       end
 
-      Interaction.queue_input(session, @buffers.fetch(session), final: session.eof?, deadline: @dispatch_deadline)
+      # 正则与空规则不分配字面缓存；回调可追加规则，每轮按当前声明选择。
+      literal_scan = @literal_scans[session]
+      if !literal_scan && session.sequences.any? { |key, _handler| key.is_a?(String) }
+        literal_scan = (@literal_scans[session] ||= LiteralScan.new)
+      end
+      Interaction.queue_input(session, @buffers.fetch(session), final: session.eof?, deadline: @dispatch_deadline,
+                                                                literal_scan:)
     end
 
     # 共同等待来源与目标，每轮读每个就绪来源一次；EINTR 返回原期限循环。
@@ -198,7 +207,7 @@ module Expect
       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|
+      sources = @active.each_key.reject do |session|
         session.pending_output? && !targets.key?(session)
       end
       (sources + targets.keys).uniq { |session| session.to_io.object_id }.reject(&:eof?)

data/lib/expect/result.rb

@@ -30,6 +30,22 @@ module Expect
             captures: captures.map { |value| value&.dup&.freeze }.freeze)
     end
 
+    # 诊断只显示匹配序号和错误状态，不检查原始文本、异常或来源对象。
+    # @return [String] 不包含协议内容的结果摘要。
+    def inspect
+      state = if error.nil? then "none"
+              elsif error.equal?(:eof) then "eof"
+              elsif error.equal?(:timeout) then "timeout"
+              else "exception"
+              end
+      index = number.is_a?(Integer) ? number.to_s : "nil"
+      "#<#{self.class} number=#{index} error=#{state}>"
+    end
+
+    # Data 的默认 to_s 独立于 inspect；字符串插值同样只使用安全摘要。
+    # @return [String] 与 inspect 相同的结果摘要。
+    def to_s = inspect
+
     # 是否命中文本；EOF 和超时没有模式序号。
     def matched? = !number.nil?
 

data/lib/expect/session.rb

@@ -130,6 +130,10 @@ module Expect
     # 返回缓冲副本，防止调用方原地修改绕过裁剪规则。
     def buffer = @buffer.dup
 
+    # 读取当前未消费主缓冲的字节数，不复制正文、不读取 IO，也不包含转接中的待写数据。
+    # @return [Integer] 当前主缓冲占用的字节数。
+    def buffer_bytesize = @buffer.bytesize
+
     # Matcher 仅在无回调的当前扫描借用原字节，避免副本使下一次追加复制整个窗口。
     # 不得修改或跨读取、回调保留；公开 buffer 和继续回调的快照仍独立复制。
     # @api private
@@ -508,7 +512,7 @@ module Expect
         @pending_writes&.clear
         @relay_history&.clear
         @relay_callback = nil
-        status = close_child(timeout:, term_timeout:, force:)
+        status = cleanup.call { close_child(timeout:, term_timeout:, force:) }
         raise failure if failure
 
         status

data/lib/expect/version.rb

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

data/sig/expect.rbs

@@ -102,6 +102,8 @@ module Expect
 
     def buffer: () -> String
 
+    def buffer_bytesize: () -> Integer
+
     def buffer=: (String value) -> void
 
     def clear_buffer: () -> String
@@ -238,6 +240,10 @@ module Expect
 
     def eof?: () -> bool
 
+    def inspect: () -> String
+
+    def to_s: () -> String
+
     def deconstruct: () -> [Integer?, result_error, String?, String?, String?, Session?, Array[String?]]
 
     def with: (

metadata

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