expect-pty 0.8.2 → 0.9.0

data/lib/expect/relay/writer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Expect
+  class Relay
+    # 向单个转接目标写入数据，维护发送进度与期限；恢复时不重放已成功写出的前缀。
+    # 只借用目标，不 dup 描述符，也不负责读取；所有就绪等待统一交给 Relay 调度。
+    # @api private
+    class Writer
+      # target 始终借用；deadline 是本轮背压预算，不表示整块数据已交付。
+      attr_reader :target, :deadline
+
+      # data 在本游标存活期间由上层保持不变，offset 始终以实际交付的字节数计量。
+      def initialize(target, data)
+        @target = target
+        @data = data
+        @offset = 0
+        @flushed = false
+        restart_timeout
+      end
+
+      # 初次排队或重新进入 interconnect 时开始新的写入预算；普通短写不会刷新期限。
+      # 只有 Expect 目标提供 write_timeout，原生 IO 和自定义目标只受转接总期限约束。
+      def restart_timeout
+        period = target.write_timeout if target.is_a?(Session)
+        @deadline = period && (Expect.monotonic + period)
+      end
+
+      # 真实 IO 可参与共同 select；自定义可写对象返回 nil，沿用其同步 write/flush 协议。
+      def io
+        return target.writer if target.is_a?(Session)
+
+        target if target.is_a?(IO)
+      end
+
+      # 数据交付完但 flush 失败仍未完成；重试只补 flush，不重新发送已接受的数据。
+      def done? = @offset == @data.bytesize && @flushed
+
+      # 每轮每目标至多一次写入；真实 IO 永不在此等待，交给 Relay 的共同 select。
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 游标、短写、flush 和期限按单个目标推进。
+      def advance(check_timeout: true)
+        return false if done?
+        raise IOError, "closed Expect session" if target.is_a?(Session) && target.closed?
+
+        if @offset < @data.bytesize
+          bytes = @data.byteslice(@offset, READ_SIZE)
+          count = io ? io.write_nonblock(bytes, exception: false) : target.write(bytes)
+          if io && count == :wait_writable
+            check_timeout! if check_timeout
+            return false
+          end
+          unless count.is_a?(Integer) && count.positive? && count <= bytes.bytesize
+            raise IOError, "write must return the number of accepted bytes"
+          end
+
+          @offset += count
+          # 先登记底层已接受的进度，再通知诊断；logger 失败后恢复只补未发送后缀。
+          trace_delivery(bytes.byteslice(0, count)) if target.is_a?(Session)
+        end
+        if @offset == @data.bytesize
+          # write_nonblock 已直接写到底层；普通 write 对象仍遵守自身 flush 协议。
+          target.flush if !io && target.respond_to?(:flush)
+          @flushed = true
+        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
+
+        raise WriteTimeout.new("relay target write timed out", bytes_written: @offset)
+      end
+
+      private
+
+      # 诊断可嵌套写入；外层只报告本游标的进度，原超时及其内层进度保留在 cause。
+      def trace_delivery(data)
+        target.__send__(:trace_data, :sending, data)
+      rescue WriteTimeout
+        raise WriteTimeout.new("relay interrupted by a diagnostic timeout", bytes_written: @offset)
+      end
+    end
+  end
+end

data/lib/expect/resource_owner.rb

@@ -108,4 +108,5 @@ module Expect
       @pid = nil
     end
   end
+  private_constant :ResourceOwner
 end

data/lib/expect/responder.rb

@@ -31,7 +31,8 @@ module Expect
     # 等待完成模式或 EOF，同时自动处理提示；timeout 沿用会话默认值，应答不重置期限。
     # 完成块使用 PatternList DSL；Result 只描述最后一次匹配，全文请用会话 transcript 保存。
     # 每次等待快照规则，回调修改规则仅影响后续等待；不接管或关闭会话。
-    def expect(session, *patterns, timeout: (session.timeout if session.is_a?(Session)), deadline: nil, &block)
+    def expect(session, *patterns, timeout: (session.timeout if session.is_a?(Session)), deadline: nil,
+               search_window: nil, &block)
       raise ArgumentError, "responder requires a Session" unless session.is_a?(Session)
 
       raise ArgumentError, "provide patterns or a pattern block, not both" if block && !patterns.empty?
@@ -39,7 +40,7 @@ module Expect
       rules = @rules.dup.freeze
       Expect.__send__(
         :run_expect, [session], [], timeout, deadline:, consume: true,
-                                             reset_timeout_on_read: false, match_by_position: true
+                                             reset_timeout_on_read: false, match_by_position: true, search_window:
       ) do |list|
         patterns.each do |pattern|
           case pattern

data/lib/expect/session.rb

@@ -48,34 +48,25 @@ module Expect
     end
 
     # 等待自身输入，返回 Result；匹配消费和接收重置策略只对本轮有效。
-    def expect(*patterns, timeout: self.timeout, deadline: nil, consume: true, reset_timeout_on_read: false, &)
-      Expect.__send__(:run_expect, [self], patterns, timeout, deadline:, consume:, reset_timeout_on_read:, &)
+    def expect(*patterns, timeout: self.timeout, deadline: nil, consume: true, reset_timeout_on_read: false,
+               search_window: nil, &)
+      Expect.__send__(:run_expect, [self], patterns, timeout,
+                      deadline:, consume:, reset_timeout_on_read:, search_window:, &)
     end
 
     # 在新控制终端中执行命令并同步确认 exec 结果；同一会话只能启动一次。
-    def spawn(*command, env: {}, chdir: nil, raw: false)
+    def spawn(*command, env: {}, chdir: nil, raw: false, shell: false)
       validate_spawn!(command)
+      raise ArgumentError, "shell must be true or false" unless [true, false].include?(shell)
+      raise ArgumentError, "shell requires one command string" if shell && command.size != 1
 
       @slave.raw! if raw
-      from_child = to_parent = nil
-      Cleanup.always(-> { ResourceOwner.close_handles(from_child, to_parent) }) do
-        # 错误管道的写端在 exec 成功时自动关闭；父进程据此区分成功启动与 exec 前失败。
-        # 管道返回到多重赋值之间也属于接管区间，确保 ensure 始终能找到两个端点。
-        Thread.handle_interrupt(Object => :never) { from_child, to_parent = IO.pipe }
-        to_parent.close_on_exec = true
-        @command = command.map { |part| part.dup.freeze }.freeze
-        # 原生 fork 返回后先登记 PID，再交付线程中断或终止，避免清理时遗漏新子进程。
-        child = Thread.handle_interrupt(Object => :never) do
-          @resources.pid = fork do
-            # 子进程不继承父侧登记临界区，执行前仍可立即响应异步异常。
-            Thread.handle_interrupt(Object => :immediate) { exec_child(command, env:, chdir:, from_child:, to_parent:) }
-          end
+      @command = command.map { |part| part.dup.freeze }.freeze
+      Cleanup.on_failure(-> { hard_close }) do
+        child = @child_process.spawn(command, env:, chdir:, shell:) do |from_child, to_parent|
+          exec_child(command, env:, chdir:, from_child:, to_parent:, shell:)
         end
-        to_parent.close
-        @slave.close
-        failure = from_child.read
-        Cleanup.always(-> { hard_close }) { raise SpawnError, failure } unless failure.empty?
-        trace("spawned pid=#{child}", event: :spawned)
+        trace(event: :spawned) { "spawned pid=#{child}" }
         self
       end
     end
@@ -100,10 +91,7 @@ module Expect
 
     # 非阻塞回收并缓存子进程状态；未退出或仅适配 IO 时返回 nil。
     def process_status
-      @resources.reap
-    rescue Errno::EINTR
-      # 单次轮询被中断时状态仍未知；wait/close 会在原期限内继续，不在这里无限重试。
-      @resources.status
+      @child_process.status
     end
 
     # 已知进程退出码；尚未回收或信号退出时为 nil。
@@ -182,7 +170,7 @@ module Expect
 
       begin
         # 单对象不需要中间数组与 join 副本；to_s、诊断和部分写入仍经过同一条路径。
-        data = objects.size == 1 ? objects.first.to_s.b : objects.map { |object| object.to_s.b }.join
+        data = objects.size == 1 ? objects.first.to_s.b : objects.map { |object| object.to_s.b }.join("") # rubocop:disable Style/RedundantArgument -- 显式空分隔符隔离全局 $,。
         check_writable!
         trace_data(:sending, data)
       rescue WriteTimeout
@@ -328,7 +316,7 @@ module Expect
       end
       # 诊断回调可能嵌套等待；恢复本次结果后再交给正式模式回调，不能返回内层等待的结果。
       result = @last_result
-      trace("matched pattern #{pattern.number}")
+      trace { "matched pattern #{pattern.number}" }
       @last_result = result
     end
 
@@ -400,6 +388,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 = ResourceOwner.new(reader, writer:, slave:, own:)
+      @child_process = ChildProcess.new(@resources)
       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?
 
@@ -444,28 +433,9 @@ module Expect
       raise ArgumentError, "command is empty" if command.first.empty?
     end
 
-    # 子进程独占控制终端；成功 exec 关闭错误管道，失败时回传后立即退出。
-    def exec_child(command, env:, chdir:, from_child:, to_parent:)
-      from_child.close
-      Process.setsid
-      # 创建独立进程会话后重新打开 slave，使它成为子进程的控制终端。
-      File.open(@tty_name, File::RDWR) do |terminal|
-        # 重定向操作系统的标准描述符；即使宿主替换过 Ruby 标准流，也能正确连接子进程。
-        # rubocop:disable Style/GlobalStdStream
-        STDIN.reopen(terminal)
-        STDOUT.reopen(terminal)
-        STDERR.reopen(terminal)
-        # rubocop:enable Style/GlobalStdStream
-      end
-      @resources.close_handles
-      Dir.chdir(chdir) if chdir
-      exec(env, *command, close_others: true)
-    rescue Exception => error # rubocop:disable Lint/RescueException -- 子进程回传启动异常后立即退出。
-      begin
-        to_parent.write("#{error.class}: #{error.message}")
-      ensure
-        exit! 127
-      end
+    # 保留 Session 子类的启动钩子；进程对象管理控制终端和错误协议。
+    def exec_child(command, **)
+      @child_process.exec_child(command, **)
     end
 
     # EINTR 未确认交付时不移动游标；其他写入计数必须落在当前块范围内。
@@ -559,28 +529,9 @@ module Expect
       wait_for_child(1, signal: "KILL")
     end
 
-    # 每阶段只计算一次期限；回收或信号被中断后仍沿用剩余预算，零预算也先做一次尝试。
+    # Session 的 sleep 钩子保留给受控时钟；期限与信号状态属于进程对象。
     def wait_for_child(period, signal: nil)
-      deadline = period && (Expect.monotonic + period)
-      loop do
-        status = process_status
-        return status if status || !pid || @resources.owner != Process.pid
-
-        begin
-          signal_child(signal) if signal
-          signal = nil
-        rescue Errno::EINTR
-          # 下轮先回收再重试信号，避免在无限等待或持续中断时忙等。
-          nil
-        end
-        # ESRCH 后可能已完成回收；即使预算耗尽，也要返回刚获得的状态。
-        return process_status unless pid
-
-        remaining = deadline && (deadline - Expect.monotonic)
-        return nil if remaining && remaining <= 0
-
-        sleep(remaining ? [0.01, remaining].min : 0.01)
-      end
+      @child_process.wait(period, signal:) { |pause| sleep(pause) }
     end
 
     # 只结束读取方向并冲刷接收记录；EOF 不代表子进程已经退出或写端已经关闭。
@@ -603,14 +554,5 @@ module Expect
       # 丢弃的前缀使当前窗口与已转发历史之间不再连续。
       @relay_history.clear
     end
-
-    # 仅由资源创建者向仍未回收的子进程发送信号；若进程刚好退出，则尝试回收。
-    def signal_child(signal)
-      return unless pid && @resources.owner == Process.pid
-
-      Process.kill(signal, pid)
-    rescue Errno::ESRCH
-      @resources.reap
-    end
   end
 end

data/lib/expect/session_factory.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Expect
+  # 统一管理部分构造对象；调用方只在受保护的移交区间接收已初始化会话。
+  # @api private
+  module SessionFactory
+    def self.pty(**)
+      session = nil
+      Cleanup.on_failure(-> { session&.cleanup_session(nil, writer: nil, own: false) }) do
+        session = Session.allocate
+        Thread.handle_interrupt(Object => :immediate) { session.__send__(:initialize, **) }
+        session
+      end
+    end
+
+    def self.io(reader, writer:, own:, **)
+      session = nil
+      cleanup = lambda do
+        if session
+          session.cleanup_session(reader, writer:, own:)
+        elsif own
+          ResourceOwner.close_handles(reader, writer)
+        end
+      end
+      Cleanup.on_failure(cleanup) do
+        session = Session.allocate
+        Thread.handle_interrupt(Object => :immediate) do
+          session.__send__(:initialize_io, reader, writer:, own:, **)
+        end
+        session
+      end
+    end
+  end
+  private_constant :SessionFactory
+end

data/lib/expect/version.rb

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

data/sig/expect.rbs

@@ -1,6 +1,6 @@
 # 公开 Session 接口；内部匹配与转接协议在源码中标记为 @api private。
 module Expect
-  type duration = Numeric | String
+  type duration = Numeric
   type pattern = String | Regexp | :eof | :timeout
   type result_error = :eof | :timeout | Exception | nil
   type result_fields = { number: Integer?, error: result_error, match: String?, before: String?, after: String?, session: Session?, captures: Array[String?] }
@@ -21,6 +21,9 @@ module Expect
   CONTINUE_WITHOUT_RESET: :continue_without_reset
 
   class SpawnError < StandardError
+    attr_reader errno: Integer?
+
+    def initialize: (?String message, ?errno: Integer?) -> void
   end
 
   class ReentrancyError < StandardError
@@ -33,12 +36,12 @@ module Expect
   end
 
   def self.spawn: (
-      *String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool, ?graceful: bool,
+      *String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool, ?shell: bool, ?graceful: bool,
       ?timeout: duration?, ?write_timeout: duration?, ?buffer_limit: Integer?,
       ?logger: _Logger?, ?transcript: _Writer?, ?outputs: Array[_Writer]
     ) -> Session
     | [A] (
-      *String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool, ?graceful: bool,
+      *String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool, ?shell: bool, ?graceful: bool,
       ?timeout: duration?, ?write_timeout: duration?, ?buffer_limit: Integer?,
       ?logger: _Logger?, ?transcript: _Writer?, ?outputs: Array[_Writer]
     ) { (Session) -> A } -> A
@@ -66,7 +69,7 @@ module Expect
 
   def self.expect: (
       *pattern patterns, ?from: (Session | Array[Session]), ?timeout: duration?, ?deadline: duration?,
-      ?consume: bool, ?reset_timeout_on_read: bool
+      ?consume: bool, ?reset_timeout_on_read: bool, ?search_window: Integer?
     ) ?{ (PatternList) -> untyped } -> Result
 
   class Session
@@ -75,10 +78,10 @@ module Expect
         ?logger: _Logger?, ?transcript: _Writer?, ?outputs: Array[_Writer]
       ) -> void
 
-    def spawn: (*String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool) -> Session
+    def spawn: (*String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool, ?shell: bool) -> Session
 
     def expect: (
-        *pattern patterns, ?timeout: duration?, ?deadline: duration?, ?consume: bool, ?reset_timeout_on_read: bool
+        *pattern patterns, ?timeout: duration?, ?deadline: duration?, ?consume: bool, ?reset_timeout_on_read: bool, ?search_window: Integer?
       ) ?{ (PatternList) -> untyped } -> Result
 
     def after: () -> String?
@@ -272,7 +275,7 @@ module Expect
     def on: ((String | Regexp) pattern, ?reply: String?, ?limit: Integer?)
       ?{ (Session) -> untyped } -> Responder
 
-    def expect: (Session session, *pattern patterns, ?timeout: duration?, ?deadline: duration?)
+    def expect: (Session session, *pattern patterns, ?timeout: duration?, ?deadline: duration?, ?search_window: Integer?)
       ?{ (PatternList) -> untyped } -> Result
 
     def inspect: () -> String

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: expect-pty
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.0
 platform: ruby
 authors:
 - expect-pty contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-11 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: io-console
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -64,7 +78,7 @@ files:
 - docs/API.md
 - docs/COMPATIBILITY.md
 - docs/MIGRATION.md
-- lib/expect.rb
+- lib/expect/child_process.rb
 - lib/expect/cleanup.rb
 - lib/expect/interaction.rb
 - lib/expect/literal_prefix.rb
@@ -75,11 +89,12 @@ files:
 - lib/expect/pty.rb
 - lib/expect/redactor.rb
 - lib/expect/relay.rb
-- lib/expect/relay_writer.rb
+- lib/expect/relay/writer.rb
 - lib/expect/resource_owner.rb
 - lib/expect/responder.rb
 - lib/expect/result.rb
 - lib/expect/session.rb
+- lib/expect/session_factory.rb
 - lib/expect/version.rb
 - sig/expect.rbs
 homepage: https://github.com/gatework/expect-ruby

data/lib/expect/relay_writer.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-module Expect
-  # 向单个转接目标写入数据，维护发送进度与期限；恢复时不重放已成功写出的前缀。
-  # 只借用目标，不 dup 描述符，也不负责读取；所有就绪等待统一交给 Relay 调度。
-  # @api private
-  class RelayWriter
-    # target 始终借用；deadline 是本轮背压预算，不表示整块数据已交付。
-    attr_reader :target, :deadline
-
-    # data 在本游标存活期间由上层保持不变，offset 始终以实际交付的字节数计量。
-    def initialize(target, data)
-      @target = target
-      @data = data
-      @offset = 0
-      @flushed = false
-      restart_timeout
-    end
-
-    # 初次排队或重新进入 interconnect 时开始新的写入预算；普通短写不会刷新期限。
-    # 只有 Expect 目标提供 write_timeout，原生 IO 和自定义目标只受转接总期限约束。
-    def restart_timeout
-      period = target.write_timeout if target.is_a?(Session)
-      @deadline = period && (Expect.monotonic + period)
-    end
-
-    # 真实 IO 可参与共同 select；自定义可写对象返回 nil，沿用其同步 write/flush 协议。
-    def io
-      return target.writer if target.is_a?(Session)
-
-      target if target.is_a?(IO)
-    end
-
-    # 数据交付完但 flush 失败仍未完成；重试只补 flush，不重新发送已接受的数据。
-    def done? = @offset == @data.bytesize && @flushed
-
-    # 每轮每目标至多一次写入；真实 IO 永不在此等待，交给 Relay 的共同 select。
-    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 游标、短写、flush 和期限按单个目标推进。
-    def advance(check_timeout: true)
-      return false if done?
-      raise IOError, "closed Expect session" if target.is_a?(Session) && target.closed?
-
-      if @offset < @data.bytesize
-        bytes = @data.byteslice(@offset, READ_SIZE)
-        count = io ? io.write_nonblock(bytes, exception: false) : target.write(bytes)
-        if io && count == :wait_writable
-          check_timeout! if check_timeout
-          return false
-        end
-        unless count.is_a?(Integer) && count.positive? && count <= bytes.bytesize
-          raise IOError, "write must return the number of accepted bytes"
-        end
-
-        @offset += count
-        # 先登记底层已接受的进度，再通知诊断；logger 失败后恢复只补未发送后缀。
-        trace_delivery(bytes.byteslice(0, count)) if target.is_a?(Session)
-      end
-      if @offset == @data.bytesize
-        # write_nonblock 已直接写到底层；普通 write 对象仍遵守自身 flush 协议。
-        target.flush if !io && target.respond_to?(:flush)
-        @flushed = true
-      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
-
-      raise WriteTimeout.new("relay target write timed out", bytes_written: @offset)
-    end
-
-    private
-
-    # 诊断可嵌套写入；外层只报告本游标的进度，原超时及其内层进度保留在 cause。
-    def trace_delivery(data)
-      target.__send__(:trace_data, :sending, data)
-    rescue WriteTimeout
-      raise WriteTimeout.new("relay interrupted by a diagnostic timeout", bytes_written: @offset)
-    end
-  end
-
-  private_constant :RelayWriter
-end