expect-pty 0.3.3 → 0.4.0

data/lib/expect.rb

@@ -99,8 +99,8 @@ class Expect
     def expect(...) = expect_result(...).number
 
     # 多会话等待的完整结果入口；from: 提供默认来源，块内可分别指定每个模式的来源。
-    def expect_result(*patterns, from: [], timeout: configuration.timeout, &)
-      run_expect(from, patterns, timeout, &)
+    def expect_result(*patterns, from: [], timeout: configuration.timeout, deadline: nil, &)
+      run_expect(from, patterns, timeout, deadline: deadline, &)
     end
 
     # 返回继续等待的控制符，reset_timeout 决定是否重新计算匹配期限。
@@ -149,15 +149,17 @@ class Expect
     private
 
     # 先完成模式声明再启动引擎；无参数块支持简洁 DSL，有参数块保留调用方 self。
-    def run_expect(sessions, patterns, timeout, &block)
+    def run_expect(sessions, patterns, timeout, deadline: nil, &block)
       timeout = duration(timeout)
+      deadline = Float(deadline) unless deadline.nil?
+      raise ArgumentError, "deadline must be finite" if deadline && !deadline.finite?
       raise ArgumentError, "provide patterns or a pattern block, not both" if block_given? && !patterns.empty?
 
       pattern_list = PatternList.new(sessions, patterns)
       if block
         block.parameters.empty? ? pattern_list.instance_exec(&block) : block.call(pattern_list)
       end
-      Matcher.new(pattern_list.validate!, timeout).run
+      Matcher.new(pattern_list.validate!, timeout, deadline: deadline).run
     end
   end
 
@@ -167,7 +169,7 @@ class Expect
   def_delegators :@configuration, *Configuration::ATTRIBUTES, *Configuration::PREDICATES
   def_delegators :@configuration, *(Configuration::ATTRIBUTES - [:buffer_limit]).map { |name| :"#{name}=" }
 
-  attr_reader :command, :last_result, :slave, :tty_name
+  attr_reader :command, :last_result, :slave, :tty_name, :buffer_discarded_bytes
 
   # 校验并更新缓冲上限后，立即裁剪已接收的内容；校验失败不改变旧缓冲。
   def buffer_limit=(value)
@@ -236,20 +238,21 @@ class Expect
       hard_close
       raise SpawnError, failure
     end
-    trace("spawned pid=#{child}")
+    trace("spawned pid=#{child}", event: :spawned)
     self
   ensure
     from_child&.close unless from_child&.closed?
     to_parent&.close unless to_parent&.closed?
   end
+
   # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
   # 在当前会话等待文本或事件，返回模式序号或 nil。
   def expect(...) = expect_result(...).number
 
   # 使用会话默认超时构造一次等待，返回含匹配内容、来源和错误的 Result。
-  def expect_result(*patterns, timeout: self.timeout, &)
-    self.class.__send__(:run_expect, [self], patterns, timeout, &)
+  def expect_result(*patterns, timeout: self.timeout, deadline: nil, &)
+    self.class.__send__(:run_expect, [self], patterns, timeout, deadline: deadline, &)
   end
 
   # 供实例回调返回继续控制符，语义与 Expect.continue 相同。
@@ -306,6 +309,7 @@ class Expect
     raise ArgumentError, "buffer must be a String" unless value.is_a?(String)
 
     @buffer = value.b
+    @buffer_generation += 1
     trim_buffer
   end
 
@@ -313,6 +317,7 @@ class Expect
   def clear_buffer
     previous = @buffer
     @buffer = "".b
+    @buffer_generation += 1
     previous
   end
 
@@ -322,7 +327,7 @@ 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) if debug_level >= 2
+    trace_data(:sending, data, level: 2) if debug_level >= 2
     deadline = write_timeout && (Expect.monotonic + write_timeout)
     offset = 0
     while offset < data.bytesize
@@ -360,6 +365,7 @@ class Expect
     end
     data.bytesize
   end
+
   # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
   # 链式写入单个对象，返回当前会话。
@@ -478,7 +484,11 @@ class Expect
     completed = true
     status
   ensure
-    cleanup.call { self.log_output = nil }
+    begin
+      cleanup.call { flush_diagnostics }
+    ensure
+      cleanup.call { self.log_output = nil }
+    end
     # 用本次流程的完成状态判断异常传播，不能误把调用者 rescue 中的异常当成当前错误。
     raise failure if failure && completed
   end
@@ -498,7 +508,7 @@ class Expect
   end
 
   # 统一初始化 PTY 与已有 IO 会话，复制配置并注册不直接捕获会话的资源终结器。
-  def initialize_session(reader, writer:, slave: nil, own: false, **)
+  def initialize_session(reader, writer:, slave: nil, own: false, diagnostic_output: nil, **)
     # 先登记所有权，后续校验失败也使用同一个资源对象逐个清理所属 IO。
     @resources = SessionResources.new(reader, writer: writer, slave: slave, own: own)
     raise ArgumentError, "reader must be a real IO" unless reader.is_a?(IO) && !reader.closed?
@@ -508,10 +518,13 @@ class Expect
     @slave = slave
     @configuration = Configuration.new(**self.class.configuration.to_h, **)
     @buffer = "".b
+    @buffer_generation = 0
+    @buffer_discarded_bytes = 0
     @listeners = []
     @sequences = {}
     @relay_outputs = []
     @closed = @eof = false
+    self.diagnostic_output = diagnostic_output
     ObjectSpace.define_finalizer(self, SessionResources.finalizer(@resources))
   end
 
@@ -527,9 +540,14 @@ class Expect
     @last_result = Result.new(number: pattern.number, before: @buffer.byteslice(0, offset),
                               match: @buffer.byteslice(offset, length), after: @buffer.byteslice((offset + length)..),
                               session: self, captures: captures)
-    @buffer = @last_result.after.dup unless preserve_buffer?
+    unless preserve_buffer?
+      @buffer = @last_result.after.dup
+      @buffer_generation += 1
+    end
+    # 诊断回调可能嵌套等待；恢复本次结果后再交给正式模式回调，不能返回内层等待的结果。
+    result = @last_result
     trace("matched pattern #{pattern.number}")
-    @last_result
+    @last_result = result
   end
 
   # 记录超时、EOF 或原始 IO 异常，保留当前缓冲快照并清除旧匹配及捕获组。
@@ -562,33 +580,41 @@ class Expect
       # 某些系统用 PTY 的 EIO 表示对端关闭；普通 IO 的同类错误仍按异常处理。
       raise unless @pty
 
-      @eof = true
-      return nil
+      return finish_read
     rescue EOFError
-      @eof = true
-      return nil
+      return finish_read
     end
     return nil if data == :wait_readable
 
-    if data.nil?
-      @eof = true
-      return nil
-    end
+    return finish_read if data.nil?
+
     data = data.b
     buffer << data
     trim_buffer if trim
-    trace("received #{data.inspect}", level: 2) if debug_level >= 2
-    trace("buffer #{@buffer.inspect}", level: 3) if debug_level >= 3
+    trace_data(:received, data, level: 2) if debug_level >= 2
+    trace_data(:buffer, @buffer, level: 3) if debug_level >= 3
     # 仅在真实读取时记录日志，后续匹配或人工转接重用缓冲时不会重复记录。
     write_log(data)
     propagate(data) if propagate
     data
   end
 
+  def finish_read
+    @eof = true
+    flush_log
+    flush_diagnostics(:received)
+    nil
+  end
+
   # 缓冲超过上限时只保留最新尾部字节，不对编码做隐式修改。
   def trim_buffer
     limit = buffer_limit
-    @buffer = @buffer.byteslice(-limit, limit) if limit&.positive? && @buffer.bytesize > limit
+    return unless limit && @buffer.bytesize > limit
+
+    # 只累计匹配窗口裁剪，消费、清空及转接交接不算丢弃；关闭后仍可读取累计值。
+    @buffer_discarded_bytes += @buffer.bytesize - limit
+    @buffer = @buffer.byteslice(-limit, limit)
+    @buffer_generation += 1
   end
 
   # 仅由资源创建者向仍未回收的子进程发送信号；若进程刚好退出，则尝试回收。

data/script/ci

@@ -7,7 +7,7 @@ bundle exec rake
 bundle exec ruby examples/dialogue.rb
 
 # 只检查小规模工作负载的正确性，不为共享 CI 机器设置性能阈值。
-for benchmark in matching relay send_slow; do
+for benchmark in matching relay send_slow scaling; do
   bundle exec ruby "benchmark/${benchmark}.rb" --smoke
 done
 
@@ -45,7 +45,7 @@ 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) }
+unexpected = %w[minitest rake rubocop parallel logger].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)
@@ -68,7 +68,34 @@ Expect.spawn(RbConfig.ruby, "--disable-gems", "-e", child, raw_pty: true, log_st
   abort "installed gem child did not exit successfully" unless status&.success?
 end
 
-puts "Installed #{spec.full_name}: #{ARGV.fetch(0)} PTY and runtime dependencies passed"
+# 使用已安装包验证内部过滤器随包分发，且结构化诊断无需加载可选的 Logger。
+reader, producer = IO.pipe
+events = []
+transcript = StringIO.new
+begin
+  Expect.open(reader, own: true, buffer_limit: 5, debug_level: 2,
+              diagnostic_output: ->(event) { events << event }) do |session|
+    session.redact("secret")
+    session.log_to(transcript)
+    session.buffer = "ready"
+    expired = session.expect_result("ready", deadline: Expect.monotonic)
+    abort "expired deadline consumed buffered text" unless expired.timeout? && session.buffer == "ready"
+    abort "zero timeout lost buffered text" unless session.expect("ready", timeout: 0) == 1
+    producer.write("secret!")
+    producer.close
+    result = session.expect_result(:eof, deadline: Expect.monotonic + 5)
+    abort "installed gem did not preserve capped input" unless result.eof? && result.before == "cret!"
+    abort "incorrect installed buffer accounting" unless session.buffer_discarded_bytes == 2
+    abort "installed redaction failed" unless transcript.string == "[FILTERED]!"
+    abort "diagnostics leaked secret" if events.any? { |event| event[:message].include?("secret") }
+    abort "filtered diagnostic missing" unless events.any? { |event| event[:message].include?("[FILTERED]") }
+  end
+ensure
+  reader.close unless reader.closed?
+  producer.close unless producer.closed?
+end
+
+puts "Installed #{spec.full_name}: #{ARGV.fetch(0)} PTY, core contracts and runtime dependencies passed"
 RUBY
   ruby smoke.rb plain
 

data/test/buffer_accounting_test.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class BufferAccountingTest < ExpectTest
+  def test_limit_discards_are_cumulative_and_distinct_from_consumption
+    session, = pipe_session(buffer_limit: 4)
+    assert_equal 0, session.buffer_discarded_bytes
+    session.buffer = "abcdef"
+    assert_equal "cdef", session.buffer
+    assert_equal 2, session.buffer_discarded_bytes
+    session.buffer_limit = 2
+    assert_equal "ef", session.buffer
+    assert_equal 4, session.buffer_discarded_bytes
+    assert_equal 1, session.expect("e", timeout: 0)
+    assert_equal "f", session.clear_buffer
+    session.close
+    assert_equal 4, session.buffer_discarded_bytes
+    refute_respond_to session, :buffer_discarded_bytes=
+  end
+
+  def test_invalid_limit_and_buffer_leave_accounting_unchanged
+    session, = pipe_session(buffer_limit: 4)
+    session.buffer = "abcdef"
+    assert_raises(ArgumentError) { session.buffer_limit = 0 }
+    assert_raises(ArgumentError) { session.buffer = nil }
+    assert_equal "cdef", session.buffer
+    assert_equal 2, session.buffer_discarded_bytes
+    session.buffer_limit = nil
+    session.buffer = "unlimited"
+    assert_equal 2, session.buffer_discarded_bytes
+  end
+
+  def test_continuous_output_keeps_a_bounded_window_and_complete_log
+    session, writer = pipe_session(buffer_limit: 64)
+    logged = 0
+    session.log_to { |data| logged += data.bytesize }
+    32.times do
+      writer.write("x" * 4096)
+      assert_nil session.expect("missing", timeout: 0)
+      assert_equal 64, session.buffer.bytesize
+    end
+    assert_equal 131_072, logged
+    assert_equal logged - 64, session.buffer_discarded_bytes
+  end
+
+  def test_preserved_match_does_not_count_as_discard
+    session, = pipe_session(buffer_limit: 4, preserve_buffer: true)
+    session.buffer = "abcdef"
+    2.times { assert_equal 1, session.expect("ef", timeout: 0) }
+    assert_equal "cdef", session.buffer
+    assert_equal 2, session.buffer_discarded_bytes
+  end
+
+  def test_relay_tail_is_only_counted_when_matching_applies_the_limit
+    session, writer = pipe_session(buffer_limit: 2)
+    output = StringIO.new
+    session.listeners = [output]
+    session.on_sequence("STOP")
+    writer.write("prefixSTOPtail")
+    assert_same session, Expect.interconnect(session, timeout: 1)
+    assert_equal "prefix", output.string
+    assert_equal "tail", session.buffer
+    assert_equal 0, session.buffer_discarded_bytes
+    assert_equal 1, session.expect("il", timeout: 0)
+    assert_equal 2, session.buffer_discarded_bytes
+    session.expect(timeout: 0)
+    assert_equal 2, session.buffer_discarded_bytes
+  end
+
+  def test_logging_failure_preserves_the_retained_input_and_discard_count
+    session, writer = pipe_session(buffer_limit: 4)
+    failure = IOError.new("log failed")
+    session.log_to { raise failure }
+    writer.write("abcdef")
+    assert_same failure, session.expect_result("ef", timeout: 1).error
+    assert_equal "cdef", session.buffer
+    assert_equal 2, session.buffer_discarded_bytes
+    session.log_output = nil
+    assert_equal 1, session.expect("ef", timeout: 0)
+    assert_equal 2, session.buffer_discarded_bytes
+  end
+end

data/test/deadline_test.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class DeadlineTest < ExpectTest
+  def test_absolute_deadline_caps_timeout_resets_from_incoming_data
+    session, writer = pipe_session(reset_timeout_on_read: true)
+    with_clock([[4, writer, "."], [8, writer, "."], [12, writer, "done"]]) do |clock|
+      result = session.expect_result("done", timeout: 5, deadline: 10)
+      assert result.timeout?
+      assert_equal 10, clock[0]
+      assert_equal "..", session.buffer
+    end
+  end
+
+  def test_class_api_and_nil_timeout_use_the_absolute_deadline
+    session, writer = pipe_session
+    with_clock([[4, writer, "ready"]]) do |clock|
+      assert_equal 1, Expect.expect("ready", from: session, timeout: nil, deadline: 5)
+      result = Expect.expect_result("missing", from: session, timeout: nil, deadline: 5)
+      assert result.timeout?
+      assert_equal 5, clock[0]
+    end
+  end
+
+  def test_shorter_relative_timeout_still_wins
+    session, = pipe_session
+    with_clock do |clock|
+      assert session.expect_result("missing", timeout: 2, deadline: 10).timeout?
+      assert_equal 2, clock[0]
+    end
+  end
+
+  def test_continuing_match_cannot_extend_the_hard_deadline
+    session, = pipe_session
+    session.buffer = "first second"
+    with_clock do |clock|
+      result = session.expect_result(timeout: 10, deadline: 5) do
+        on("first") do
+          clock[0] = 6
+          Expect.continue
+        end
+        on("second") { flunk "must not consume text after the deadline" }
+      end
+      assert result.timeout?
+      assert_equal " second", session.buffer
+    end
+  end
+
+  def test_timeout_callback_cannot_restart_an_expired_hard_deadline
+    session, = pipe_session
+    calls = 0
+    with_clock do |clock|
+      result = session.expect_result(timeout: 3, deadline: 5) do
+        timeout do
+          calls += 1
+          Expect.continue
+        end
+      end
+      assert result.timeout?
+      assert_equal 2, calls
+      assert_equal 5, clock[0]
+    end
+  end
+
+  def test_expired_deadline_does_not_scan_or_read_and_preserves_input
+    session, writer = pipe_session
+    session.buffer = "buffered"
+    writer.write("unread")
+    with_clock do |clock|
+      clock[0] = 5
+      assert session.expect_result("buffered", timeout: 0, deadline: 5).timeout?
+      assert_equal "buffered", session.buffer
+      assert_equal "unread", session.to_io.read_nonblock(6)
+    end
+  end
+
+  def test_zero_relative_timeout_still_polls_with_a_future_hard_deadline
+    session, writer = pipe_session
+    writer.write("ready")
+    assert_equal 1, session.expect("ready", timeout: 0, deadline: Expect.monotonic + 1)
+  end
+
+  def test_repeated_interruptions_cannot_extend_a_deadline
+    session, = pipe_session
+    clock = [0]
+    Expect.stub(:monotonic, -> { clock[0] }) do
+      IO.stub(:select, lambda { |*|
+        clock[0] += 1
+        raise Errno::EINTR
+      }) do
+        assert session.expect_result("missing", deadline: 3).timeout?
+      end
+      assert_equal 3, clock[0]
+    end
+  end
+
+  def test_known_eof_events_are_delivered_before_timeout_of_live_sources
+    ended, = pipe_session
+    live, = pipe_session
+    ended.close
+    live.buffer = "ready"
+    seen = []
+    with_clock do
+      result = Expect.expect_result(from: [ended, live], deadline: 0) do
+        on("ready") { flunk "deadline already expired" }
+        eof(from: ended) do
+          seen << :eof
+          Expect.continue
+        end
+        timeout { |sessions| seen << sessions }
+      end
+      assert result.timeout?
+      assert_same live, result.session
+      assert_equal [:eof, [live]], seen
+      assert_equal "ready", live.buffer
+    end
+  end
+
+  def test_all_known_eof_returns_eof_even_at_the_hard_deadline
+    first, = pipe_session
+    second, = pipe_session
+    [first, second].each(&:close)
+    seen = []
+    with_clock do
+      result = Expect.expect_result(from: [first, second], deadline: 0) do
+        eof do |session|
+          seen << session
+          Expect.continue
+        end
+        timeout { flunk "all sources ended" }
+      end
+      assert result.eof?
+      assert_equal [first, second], seen
+    end
+  end
+
+  def test_deadline_reached_during_regexp_does_not_consume_the_match
+    session, = pipe_session
+    session.buffer = "ready"
+    pattern = Regexp.new("ready")
+    match = pattern.method(:match)
+    with_clock do |clock|
+      pattern.stub(:match, lambda { |text|
+        clock[0] = 5
+        match.call(text)
+      }) do
+        assert session.expect_result(pattern, deadline: 5).timeout?
+      end
+      assert_equal "ready", session.buffer
+    end
+  end
+
+  def test_preserved_timeout_at_hard_deadline_still_dispatches_all_known_eof
+    first, = pipe_session
+    second, = pipe_session
+    [first, second].each(&:close)
+    first.buffer = "ready"
+    seen = []
+    with_clock do |clock|
+      result = Expect.expect_result(from: [first, second], deadline: 5) do
+        on("ready") do
+          clock[0] = 5
+          Expect.continue(reset_timeout: false)
+        end
+        eof do |session|
+          seen << session
+          Expect.continue(reset_timeout: false)
+        end
+        timeout { seen << :timeout }
+      end
+      assert result.eof?
+      assert_equal [first, second], seen
+    end
+  end
+
+  def test_preserved_timeout_at_hard_deadline_only_times_out_live_sources
+    ended, = pipe_session
+    live, = pipe_session
+    ended.close
+    ended.buffer = "ready"
+    seen = []
+    with_clock do |clock|
+      result = Expect.expect_result(from: [ended, live], deadline: 5) do
+        on("ready") do
+          clock[0] = 5
+          Expect.continue(reset_timeout: false)
+        end
+        eof(from: ended) do
+          seen << :eof
+          Expect.continue(reset_timeout: false)
+        end
+        timeout { |sessions| seen << sessions }
+      end
+      assert result.timeout?
+      assert_same live, result.session
+      assert_equal [:eof, [live]], seen
+    end
+  end
+
+  def test_invalid_deadlines_are_rejected_before_the_definition_or_io
+    session, writer = pipe_session
+    writer.write("ready")
+    [Float::INFINITY, -Float::INFINITY, Float::NAN, "invalid"].each do |deadline|
+      assert_raises(ArgumentError) do
+        session.expect_result(deadline: deadline) { flunk "invalid deadline must reject before registration" }
+      end
+    end
+    assert_equal "ready", session.to_io.read_nonblock(5)
+  end
+
+  private
+
+  # 虚拟时间只控制等待，数据仍经真实管道；精确断言上限，不依赖线程调度和 sleep。
+  def with_clock(events = [])
+    clock = [0.0]
+    pending = events.dup
+    poll = IO.method(:select)
+    select = lambda do |readers, writers, errors, timeout|
+      due = timeout && (clock[0] + timeout)
+      if pending.any? && (!due || pending.first[0] <= due)
+        at, writer, data = pending.shift
+        clock[0] = at
+        writer.write(data)
+        poll.call(readers, writers, errors, 0)
+      else
+        raise "unbounded wait without input" unless due
+
+        clock[0] = due
+        nil
+      end
+    end
+    Expect.stub(:monotonic, -> { clock[0] }) do
+      IO.stub(:select, select) { yield clock }
+    end
+  end
+end