expect-pty 0.2.0 → 0.3.1

data/lib/expect.rb

@@ -9,10 +9,10 @@ require "forwardable"
 require_relative "expect/version"
 require_relative "expect/configuration"
 require_relative "expect/result"
-require_relative "expect/resources"
+require_relative "expect/session_resources"
 require_relative "expect/pattern"
 require_relative "expect/pattern_list"
-require_relative "expect/engine"
+require_relative "expect/matcher"
 
 # 自动化交互会话：可以拥有一个 PTY 子进程，也可以适配已有可 select 的 IO。
 # 缓冲和匹配统一保留原始字节，配置、匹配结果与资源生命周期分别管理。
@@ -23,7 +23,16 @@ class Expect
   READ_SIZE = 16_384
 
   class SpawnError < StandardError; end
-  class WriteTimeout < IOError; end
+
+  # 已被底层接受的字节不可撤回；调用方可据此只处理尚未写出的后缀。
+  class WriteTimeout < IOError
+    attr_reader :bytes_written
+
+    def initialize(message = "write timed out", bytes_written: 0)
+      @bytes_written = bytes_written
+      super(message)
+    end
+  end
 
   class << self
     # 读取冻结的默认配置；子类未单独配置时继承父类快照。
@@ -78,6 +87,7 @@ class Expect
 
     # 返回继续等待的控制符，reset_timeout 决定是否重新计算匹配期限。
     def continue(reset_timeout: true) = reset_timeout ? CONTINUE : CONTINUE_WITHOUT_RESET
+
     # 读取不受系统时间调整影响的单调时钟，所有相对超时共用此计时基准。
     def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
@@ -99,7 +109,20 @@ class Expect
       active = sessions.uniq.reject(&:closed?)
       return [] if active.empty?
 
-      ready = IO.select(active.map(&:to_io), nil, nil, timeout)
+      deadline = timeout && (monotonic + timeout)
+      polled = false
+      ready = nil
+      loop do
+        remaining = deadline && [deadline - monotonic, 0].max
+        return [] if polled && remaining&.zero?
+
+        begin
+          ready = IO.select(active.map(&:to_io), nil, nil, remaining)
+          break
+        rescue Errno::EINTR
+          polled = true
+        end
+      end
       return [] unless ready
 
       active.select { |session| ready.first.include?(session.to_io) }
@@ -116,7 +139,7 @@ class Expect
       if block
         block.parameters.empty? ? pattern_list.instance_exec(&block) : block.call(pattern_list)
       end
-      Engine.new(pattern_list.validate!, timeout).run
+      Matcher.new(pattern_list.validate!, timeout).run
     end
   end
 
@@ -214,14 +237,21 @@ class Expect
 
   # 暴露底层读写 IO 与终端属性，供 select、终端设置及 IO 适配使用。
   def to_io = @resources.reader
+
   def writer = @resources.writer
+
   def fileno = closed? ? nil : to_io.fileno
+
   def tty? = !closed? && to_io.tty?
+
   # 诊断时仅显示进程和描述符状态，避免默认对象展开泄露缓冲或日志内容。
   def inspect = "#<#{self.class} pid=#{pid.inspect} fd=#{fileno.inspect} closed=#{closed?}>"
+
   def pid = @resources.pid
+
   # 非阻塞回收并缓存子进程状态；未退出或仅适配 IO 时返回 nil。
   def process_status = @resources.reap
+
   def exit_code = process_status&.exitstatus
 
   # 先刷新回收状态，再判断是否仍有未回收的子进程；不以 IO 是否关闭代替进程状态。
@@ -232,14 +262,22 @@ class Expect
 
   # 区分会话关闭和输入结束，已关闭会话也不能继续读取。
   def closed? = @closed || to_io.closed?
+
   def eof? = @eof || closed?
+
   # 以下访问器读取最近一次等待结果；未发生匹配时捕获组返回空数组。
   def before = @last_result&.before
+
   def after = @last_result&.after
+
   def match = @last_result&.match
+
   def match_number = @last_result&.number
+
   def captures = @last_result&.captures || []
+
   def error = @last_result&.error
+
   # 返回缓冲副本，防止调用方原地修改绕过裁剪规则。
   def buffer = @buffer.dup
 
@@ -263,21 +301,38 @@ class Expect
     raise IOError, "closed Expect session" if closed? || writer.closed?
 
     data = objects.map { |object| object.to_s.b }.join
-    trace("sending #{data.inspect}", level: 2)
+    trace("sending #{data.inspect}", level: 2) if debug_level >= 2
     deadline = write_timeout && (Expect.monotonic + write_timeout)
     offset = 0
     while offset < data.bytesize
-      count = writer.write_nonblock(data.byteslice(offset, READ_SIZE), exception: false)
+      begin
+        count = writer.write_nonblock(data.byteslice(offset, READ_SIZE), exception: false)
+      rescue Errno::EINTR
+        raise WriteTimeout.new(bytes_written: offset) if deadline && Expect.monotonic >= deadline
+
+        next
+      end
       if count == :wait_writable
-        raise WriteTimeout, "write timed out after #{write_timeout} seconds" if deadline && Expect.monotonic >= deadline
+        raise WriteTimeout.new(bytes_written: offset) if deadline && Expect.monotonic >= deadline
 
         remaining = deadline && [deadline - Expect.monotonic, 0].max
         # 子进程也可能因输出管道填满而停止读取；等可写时同时排空它的输出，避免双向死锁。
         readers = eof? ? [] : [to_io]
-        ready = IO.select(readers, [writer], nil, remaining)
-        raise WriteTimeout, "write timed out after #{write_timeout} seconds" unless ready
-
-        read_available if ready[0].include?(to_io)
+        begin
+          ready = IO.select(readers, [writer], nil, remaining)
+          raise WriteTimeout.new(bytes_written: offset) unless ready
+
+          if ready[0].include?(to_io)
+            begin
+              read_available
+            rescue WriteTimeout
+              # 日志或监听器可嵌套写入；对外报告本次写入进度，原异常通过 cause 保留。
+              raise WriteTimeout.new("write interrupted by an output timeout", bytes_written: offset)
+            end
+          end
+        rescue Errno::EINTR
+          next
+        end
       else
         offset += count
       end
@@ -316,7 +371,7 @@ class Expect
   end
 
   # 读取当前日志目标，可能为库打开的文件、借用的 IO、回调或 nil。
-  def log_output = @resources.log
+  attr_reader :log_output
 
   # 替换借用的日志目标或停止日志；先校验新目标，失败时保留旧目标。
   def log_output=(target)
@@ -335,8 +390,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)
 
-      # 库打开的文件由 Resources 持有，替换日志或关闭会话时释放；外部 IO 只借用。
-      replace_log(File.open(target, "#{mode}b"), owned: true)
+      # 库打开的文件由 SessionResources 持有，替换日志或关闭会话时释放；外部 IO 只借用。
+      replace_log(File.open(target, "#{mode}b", 0o600), owned: true)
     else
       raise ArgumentError, "provide a log target or a block" unless target
 
@@ -445,6 +500,12 @@ class Expect
     # IO 关闭与进程退出独立记录：软关闭可能已经 closed?，但仍保留活跃 PID。
     @resources.close_handles
     @closed = true
+    @interact_inputs&.each_value { |input| input.close(graceful: false) }
+    @interact_inputs&.clear
+    @interact_output = nil
+    @relay_outputs&.clear
+    @relay_history&.clear
+    @relay_callback = nil
     return process_status unless @resources.owner == Process.pid && pid
     return process_status if wait(timeout: timeout)
 
@@ -464,15 +525,16 @@ class Expect
     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?
 
-    @resources = Resources.new(reader, writer: writer, slave: slave, own: own)
+    @resources = SessionResources.new(reader, writer: writer, slave: slave, own: own)
     @pty = reader.tty?
     @slave = slave
     @configuration = Configuration.new(**self.class.configuration.to_h, **)
     @buffer = "".b
     @listeners = []
     @sequences = {}
+    @relay_outputs = []
     @closed = @eof = false
-    ObjectSpace.define_finalizer(self, Resources.finalizer(@resources))
+    ObjectSpace.define_finalizer(self, SessionResources.finalizer(@resources))
   end
 
   # 开始新一轮等待时清除旧结果并应用缓冲上限，尚未消费的输入继续保留。
@@ -505,10 +567,16 @@ class Expect
     @last_result
   end
 
-  # 进行一次非阻塞读取并记录日志；accumulate/propagate 决定是否交给匹配缓冲和监听器。
-  def read_available(propagate: true, accumulate: true)
+  # 先将读取字节交给匹配或转接缓冲，再记录日志；日志失败也能恢复输入。
+  def read_available(propagate: true, buffer: @buffer)
     return nil if eof?
 
+    # 写入背压也会读取；转接期间统一交给转义处理器，不能直接转发或另存匹配缓冲。
+    if @interaction_buffer
+      buffer = @interaction_buffer
+      propagate = false
+    end
+
     begin
       data = to_io.read_nonblock(READ_SIZE, exception: false)
     rescue Errno::EIO
@@ -528,12 +596,10 @@ class Expect
       return nil
     end
     data = data.b
-    if accumulate
-      @buffer << data
-      trim_buffer
-    end
-    trace("received #{data.inspect}", level: 2)
-    trace("buffer #{@buffer.inspect}", level: 3)
+    buffer << data
+    trim_buffer if buffer.equal?(@buffer)
+    trace("received #{data.inspect}", level: 2) if debug_level >= 2
+    trace("buffer #{@buffer.inspect}", level: 3) if debug_level >= 3
     # 仅在真实读取时记录日志，后续匹配或人工转接重用缓冲时不会重复记录。
     write_log(data)
     propagate(data) if propagate
@@ -554,7 +620,15 @@ class Expect
 
   # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
   def emit(target, data)
-    target.write(data)
+    offset = 0
+    while offset < data.bytesize
+      count = target.write(data.byteslice(offset..))
+      unless count.is_a?(Integer) && count.positive? && count <= data.bytesize - offset
+        raise IOError, "write must return the number of accepted bytes"
+      end
+
+      offset += count
+    end
     target.flush if target.respond_to?(:flush)
   end
 
@@ -569,9 +643,10 @@ class Expect
     # 重复赋值同一目标时保留原所有权，防止将库打开的文件误变成借用资源。
     return target if previous.equal?(target)
 
-    previous.close if @resources.own_log && previous && !previous.closed?
-    @resources.log = target
-    @resources.own_log = owned
+    previous.close if @resources.owned_log && previous && !previous.closed?
+    # 终结器只持有所属文件；借用回调可能捕获会话，不能让它经资源对象成为 GC 根。
+    @resources.owned_log = owned ? target : nil
+    @log_output = target
     target
   rescue Exception # rubocop:disable Lint/RescueException -- 替换失败时仍释放刚打开的文件。
     target.close if owned && target && !target.closed?
@@ -588,4 +663,4 @@ class Expect
   end
 end
 
-require_relative "expect/interconnect"
+require_relative "expect/interaction"

data/script/ci

@@ -6,9 +6,9 @@ cd "$(dirname "${BASH_SOURCE[0]}")/.."
 bundle exec rake
 bundle exec ruby examples/dialogue.rb
 
-mkdir -p pkg/ci
+mkdir -p tmp/ci
 gem_version="$(ruby -Ilib -rexpect/version -e 'print Expect::VERSION')"
-gem_file="pkg/ci/expect-pty-${gem_version}.gem"
+gem_file="tmp/ci/expect-pty-${gem_version}.gem"
 if git rev-parse --git-dir >/dev/null 2>&1; then
   export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
 fi
@@ -17,20 +17,44 @@ gem build expect-pty.gemspec --output "$gem_file"
 # 在独立目录安装刚构建的包，避免源码路径或 Bundler 掩盖打包遗漏。
 smoke_dir="$(mktemp -d)"
 trap 'rm -rf "$smoke_dir"' EXIT
-gem install --local --no-document --install-dir "$smoke_dir/gems" "$gem_file"
+gem_file="$(pwd)/$gem_file"
+bundler_version="$(bundle exec ruby -rbundler -e 'print Bundler::VERSION')"
+bundler_gem="$(bundle exec ruby -e 'print Gem.loaded_specs.fetch("bundler").cache_file')"
 
 (
   cd "$smoke_dir"
-  unset BUNDLE_GEMFILE BUNDLE_BIN_PATH RUBYOPT RUBYLIB
+  # 清除 Bundler 的自动加载与路径设置；Ruby 4 还会通过 BUNDLER_SETUP 自动启用 Bundler。
+  for bundle_variable in ${!BUNDLE_@} ${!BUNDLER_@}; do
+    unset "$bundle_variable"
+  done
+  unset RUBYOPT RUBYLIB RUBYGEMS_GEMDEPS
   export GEM_HOME="$smoke_dir/gems" GEM_PATH="$smoke_dir/gems"
-  ruby -r expect/pty -r rbconfig <<'RUBY'
+  gem install --local --no-document "$gem_file"
+
+  cat > smoke.rb <<'RUBY'
+require "expect/pty"
+require "rbconfig"
+
 spec = Gem.loaded_specs.fetch("expect-pty")
 # 临时目录可能经由符号链接访问，先统一为实际路径再检查。
 install_root = File.realpath(ENV.fetch("GEM_HOME"))
 abort "gem was loaded outside the isolated install" unless File.realpath(spec.full_gem_path).start_with?("#{install_root}/")
+abort "Bundler leaked into the plain gem smoke" if ARGV.first == "plain" && defined?(Bundler)
+unexpected = %w[minitest rake rubocop parallel].select { |name| Gem.loaded_specs.key?(name) }
+abort "development dependencies leaked into the application: #{unexpected.join(', ')}" unless unexpected.empty?
+spec.runtime_dependencies.each do |dependency|
+  loaded = Gem.loaded_specs.fetch(dependency.name)
+  abort "incompatible dependency: #{dependency}" unless dependency.matches_spec?(loaded)
+end
 
+# 检查实际使用的标准库已在包元数据中声明，默认 gem 可加载不能代替依赖声明。
+%w[forwardable io-console io-wait shellwords stringio].each do |name|
+  abort "undeclared runtime dependency: #{name}" unless spec.runtime_dependencies.any? { |dependency| dependency.name == name }
+end
 child = 'STDOUT.sync = true; puts "ready"; puts "reply:#{$stdin.gets&.strip}"'
-Expect.spawn(RbConfig.ruby, "--disable-gems", "-e", child, log_stdout: false) do |session|
+Expect.spawn(RbConfig.ruby, "--disable-gems", "-e", child, raw_pty: true, log_stdout: false) do |session|
+  session.winsize = [30, 100]
+  abort "io-console terminal size failed" unless session.winsize == [30, 100]
   abort "installed gem did not receive the PTY prompt" unless session.expect("ready", timeout: 5)
 
   session.puts("expect-ruby")
@@ -39,6 +63,19 @@ Expect.spawn(RbConfig.ruby, "--disable-gems", "-e", child, log_stdout: false) do
   abort "installed gem child did not exit successfully" unless status&.success?
 end
 
-puts "Installed #{spec.full_name}: PTY dialogue and process cleanup passed"
+puts "Installed #{spec.full_name}: #{ARGV.fetch(0)} PTY and runtime dependencies passed"
 RUBY
+  ruby smoke.rb plain
+
+  # 消费方仅声明当前 Gem，不能借用项目 Gemfile 中的测试和发布依赖。
+  # 单独安装本次开发检查使用的 Bundler，避免依赖宿主 Ruby 的默认 Bundler 副本。
+  if [ -f "$bundler_gem" ]; then
+    gem install --local --no-document "$bundler_gem"
+  else
+    gem install --no-document bundler --version "$bundler_version"
+  fi
+  export BUNDLE_IGNORE_CONFIG=true
+  printf 'source "https://rubygems.org"\ngem "expect-pty", "= %s", require: "expect/pty"\n' "$gem_version" > Gemfile
+  bundle lock --local
+  bundle exec ruby -rbundler -e 'Bundler.require; load "smoke.rb"' bundler
 )

data/script/release.rb

@@ -16,11 +16,12 @@ class Release
   REPOSITORY = "gatework/expect-ruby"
   GEM_HOST = "https://rubygems.org"
 
-  def initialize(artifact: nil, dry_run: false)
+  def initialize(artifact: nil, dry_run: false, rubygems_only: false)
     @version = Expect::VERSION
     @tag = "v#{@version}"
-    @artifact = File.expand_path(artifact || "pkg/ci/expect-pty-#{@version}.gem")
+    @artifact = File.expand_path(artifact || "tmp/ci/expect-pty-#{@version}.gem")
     @dry_run = dry_run
+    @rubygems_only = rubygems_only
     @build = artifact.nil?
   end
 
@@ -34,7 +35,7 @@ class Release
 
     command("bash", "script/ci") if @build
     # 独占目录中的副本贯穿校验和上传，其他构建不会改变本次发布的字节。
-    directory = File.join("pkg", "release", @version)
+    directory = File.join("tmp", "release", @version)
     FileUtils.mkdir_p(directory)
     directory = Dir.mktmpdir("candidate-", directory)
     candidate = File.join(directory, "expect-pty-#{@version}.gem")
@@ -49,9 +50,13 @@ class Release
     puts "Verified #{@tag}: #{@sha256}\nArtifact: #{@artifact}"
     return puts "Dry run complete: #{@artifact}" if @dry_run
 
-    verify_remote_source
-    verify_registry_checksum(registry_version)
-    publish_github
+    if @rubygems_only
+      verify_local_source
+    else
+      verify_remote_source
+      verify_registry_checksum(registry_version)
+      publish_github
+    end
     publish_rubygems
   end
 
@@ -97,10 +102,14 @@ class Release
     JSON.parse(output)
   end
 
+  def verify_local_source
+    return if capture("git", "rev-parse", "HEAD") == @commit && capture("git", "status", "--porcelain").empty?
+
+    raise "Source changed during verification; commit the changes and start again"
+  end
+
   def verify_remote_source
-    unless capture("git", "rev-parse", "HEAD") == @commit && capture("git", "status", "--porcelain").empty?
-      raise "Source changed during verification; commit the changes and start again"
-    end
+    verify_local_source
 
     comparison = github("compare/#{@commit}...main")
     raise "Push this commit to #{REPOSITORY}/main first" unless %w[ahead identical].include?(comparison.fetch("status"))
@@ -249,7 +258,10 @@ end
 if $PROGRAM_NAME == __FILE__
   options = {}
   parser = OptionParser.new do |arguments|
-    arguments.banner = "Usage: ruby script/release.rb [--dry-run] [--artifact PATH]"
+    arguments.banner = "Usage: ruby script/release.rb [--rubygems-only] [--dry-run] [--artifact PATH]"
+    arguments.on("--rubygems-only", "Publish only to RubyGems using the existing gem login; no GitHub access") do
+      options[:rubygems_only] = true
+    end
     arguments.on("--artifact PATH", "Publish an already verified gem without rebuilding") do |path|
       options[:artifact] = File.expand_path(path)
     end

data/test/edge_case_test.rb

@@ -13,6 +13,74 @@ class EdgeCaseTest < ExpectTest
     assert result.timeout?
   end
 
+  def test_zero_width_continuation_waits_for_new_input_before_matching_again
+    session, = pipe_session
+    session.buffer = "ready"
+    calls = 0
+
+    result = bounded(1) do
+      session.expect_result(timeout: 0.01) do
+        on(/(?=ready)/) do
+          calls += 1
+          Expect.continue
+        end
+      end
+    end
+
+    assert result.timeout?
+    assert_equal 1, calls
+  end
+
+  def test_stalled_pattern_can_match_again_after_new_input
+    session, writer = pipe_session
+    session.buffer = "ready"
+    first_match = Queue.new
+    background do
+      first_match.pop
+      writer.write("!")
+    end
+    calls = 0
+
+    result = bounded(1) do
+      session.expect_result(timeout: 0.5) do
+        on(/(?=ready)/) do
+          calls += 1
+          first_match << true if calls == 1
+          calls == 1 ? Expect.continue : nil
+        end
+      end
+    end
+
+    assert result.matched?
+    assert_equal 2, calls
+    assert_equal "ready!", session.buffer
+  end
+
+  def test_stalled_pattern_can_match_again_after_timeout_callback_changes_buffer
+    session, = pipe_session
+    session.buffer = "ready"
+    calls = 0
+    timeouts = 0
+
+    result = bounded(1) do
+      session.expect_result(timeout: 0.01) do
+        on(/(?=ready)/) do
+          calls += 1
+          calls == 1 ? Expect.continue : nil
+        end
+        timeout do
+          timeouts += 1
+          session.buffer = "ready!"
+          timeouts == 1 ? Expect.continue : nil
+        end
+      end
+    end
+
+    assert result.matched?
+    assert_equal 2, calls
+    assert_equal 1, timeouts
+  end
+
   def test_stdout_works_with_utf8_banner_and_ascii_regexp
     session, writer = pipe_session
     writer.write("欢迎登录\nprompt>")
@@ -130,11 +198,44 @@ class EdgeCaseTest < ExpectTest
   end
 
   def test_gc_reclaims_abandoned_child
+    assert_gc_reclaims_abandoned_child
+  end
+
+  def test_gc_reclaims_abandoned_child_with_log_callback_capturing_session
+    assert_gc_reclaims_abandoned_child(log_callback: true)
+  end
+
+  def test_invalid_options_raise_before_spawning
+    assert_raises(ArgumentError) { Expect.new(typo: true) }
+    session, = pipe_session
+    assert_raises(ArgumentError) { session.expect(0, "x") }
+    assert_raises(ArgumentError) { session.expect(["-unknown", "x"], timeout: 0) }
+    assert_raises(ArgumentError) { session.on_sequence("") }
+  end
+
+  def test_entrypoint_can_coexist_with_standard_library_expect
+    entrypoint = File.expand_path("../lib/expect/pty.rb", __dir__)
+    script = <<~RUBY
+      require "rbconfig"
+      require File.join(RbConfig::CONFIG.fetch("rubylibdir"), "expect.rb")
+      require ARGV.fetch(0)
+      puts [IO.method_defined?(:expect), defined?(Expect), Expect::VERSION].join(":")
+    RUBY
+    environment = { "RUBYOPT" => nil, "RUBYLIB" => nil, "BUNDLE_GEMFILE" => nil }
+    output, status = Open3.capture2e(environment, RbConfig.ruby, "-e", script, entrypoint)
+    assert status.success?, output
+    assert_equal "true:constant:#{Expect::VERSION}\n", output
+  end
+
+  private
+
+  def assert_gc_reclaims_abandoned_child(log_callback: false)
     script = <<~RUBY
       require "expect"
       require "rbconfig"
       def abandoned
         session = Expect.spawn(RbConfig.ruby, "--disable-gems", "-e", "sleep 60", log_stdout: false)
+        session.log_to { |bytes| [session.pid, bytes] } if #{log_callback}
         session.pid
       end
       # Ruby 的保守 GC 可能扫描到创建线程栈上残留的引用；先结束该线程，确保会话确实不可达。
@@ -158,26 +259,4 @@ class EdgeCaseTest < ExpectTest
     assert status.success?, output
     assert_equal "reaped\n", output
   end
-
-  def test_invalid_options_raise_before_spawning
-    assert_raises(ArgumentError) { Expect.new(typo: true) }
-    session, = pipe_session
-    assert_raises(ArgumentError) { session.expect(0, "x") }
-    assert_raises(ArgumentError) { session.expect(["-unknown", "x"], timeout: 0) }
-    assert_raises(ArgumentError) { session.on_sequence("") }
-  end
-
-  def test_entrypoint_can_coexist_with_standard_library_expect
-    entrypoint = File.expand_path("../lib/expect/pty.rb", __dir__)
-    script = <<~RUBY
-      require "rbconfig"
-      require File.join(RbConfig::CONFIG.fetch("rubylibdir"), "expect.rb")
-      require ARGV.fetch(0)
-      puts [IO.method_defined?(:expect), defined?(Expect), Expect::VERSION].join(":")
-    RUBY
-    environment = { "RUBYOPT" => nil, "RUBYLIB" => nil, "BUNDLE_GEMFILE" => nil }
-    output, status = Open3.capture2e(environment, RbConfig.ruby, "-e", script, entrypoint)
-    assert status.success?, output
-    assert_equal "true:constant:#{Expect::VERSION}\n", output
-  end
 end