expect-pty 0.2.0 → 0.3.1

data/lib/expect/interaction.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require_relative "relay_writer"
+require_relative "relay"
+
+# 为会话补充人工接管和多路 IO 转接；核心会话定义位于 lib/expect.rb。
+class Expect
+  REGEXP_ESCAPE_HISTORY_LIMIT = 65_536
+  private_constant :REGEXP_ESCAPE_HISTORY_LIMIT
+
+  # Presents remote text on a raw local terminal without changing existing CRLF sequences.
+  class InteractOutput
+    def initialize(target)
+      @target = target
+      @previous_carriage_return = false
+    end
+
+    attr_reader :target
+
+    def render(data)
+      bytes = data.to_s.b
+      rendered = bytes.gsub(/(?<!\r)\n/n, "\r\n")
+      rendered = rendered.byteslice(1..) if @previous_carriage_return && bytes.start_with?("\n")
+      @previous_carriage_return = bytes.end_with?("\r")
+      rendered
+    end
+
+    def write(data)
+      @target.write(render(data))
+    end
+  end
+
+  private_constant :InteractOutput
+
+  # 注册字面、正则转义或 :eof 事件；回调用闭包保存上下文，nil/false 停止，其余值继续。
+  def on_sequence(sequence, &block)
+    key = case sequence
+          when :eof, Regexp then sequence
+          when String then sequence.b.freeze
+          else raise ArgumentError, "sequence must be a String, Regexp or :eof"
+          end
+    raise ArgumentError, "escape sequence must not be empty" if key == ""
+
+    @sequences[key] = block
+    self
+  end
+
+  # 临时将输入、会话和输出相连，实现人工接管；结束时恢复双方监听器、日志开关和转义设置。
+  def interact(input: $stdin, escape: nil, output: nil, timeout: nil)
+    source = interact_source(input)
+    output ||= input.equal?($stdin) ? $stdout : input
+    saved_self = [listeners, log_stdout, log_listeners]
+    saved_source = [source.listeners, source.log_stdout, source.log_listeners, source.sequences.dup]
+    terminal_state = prepare_interact_terminal(source)
+    display = interact_display(source, output, terminal_state)
+    # 临时建立“用户输入 -> 子进程 -> 显示输出”的双向连接，原监听关系在 ensure 中恢复。
+    self.listeners = [display]
+    self.log_stdout = false
+    self.log_listeners = true
+    source.listeners = [self]
+    source.log_stdout = false
+    source.log_listeners = true
+    source.on_sequence(escape) if escape
+    Expect.interconnect(self, source, timeout: timeout)
+  ensure
+    begin
+      if saved_self
+        self.listeners, self.log_stdout, self.log_listeners = saved_self
+        source.listeners, source.log_stdout, source.log_listeners, source.sequences = saved_source
+      end
+    ensure
+      restore_interact_terminal(terminal_state)
+    end
+  end
+
+  # 按各会话 listeners 建立转发图，处理转义、EOF 和总期限，返回引发停止的会话或 nil。
+  def self.interconnect(*sessions, timeout: nil)
+    raise ArgumentError, "interconnect requires Expect sessions" if sessions.empty? || sessions.any? do |session|
+      !session.is_a?(Expect)
+    end
+
+    Relay.new(sessions, timeout).run
+  end
+
+  # 超时或异常后仍有未交付的数据；重新 interconnect 同一源会话可继续发送。
+  def pending_output? = @relay_outputs.any? { |output| !output.done? }
+
+  # 转发一个会话的待处理缓冲并剔除转义；返回 false 表示应结束整个转接。
+  # 字面序列暂存潜在前缀，正则序列结合历史匹配；final 为真时不再等待后续字节。
+  def self.relay_buffer(session, buffers, final: false)
+    buffer = buffers.fetch(session)
+    loop do
+      sequences = session.__send__(:sequences).except(:eof)
+      history = session.__send__(:relay_history)
+      matches = sequences.filter_map do |key, handler|
+        if key.is_a?(Regexp)
+          position = Pattern.new(value: key).locate(history + buffer, final: final)
+          if position
+            offset, length, = position
+            raise ArgumentError, "escape regexp must consume at least one byte" if length.zero?
+
+            # 历史前缀已实时转发，不能撤回；负偏移表示本次只需消费转义尚未转发的部分。
+            [offset - history.bytesize, length, handler]
+          end
+        else
+          position = buffer.index(key)
+          [position, key.bytesize, handler] if position
+        end
+      end
+      if (found = matches.min_by(&:first))
+        position, length, callback = found
+        if position.positive?
+          if block_given?
+            yield buffer.byteslice(0, position)
+            buffer.replace(buffer.byteslice((position + length)..))
+            history.clear
+            # 已确定的转义不能在等待写入后重新匹配；尾部可能在等待期间继续增长。
+            session.__send__(:relay_callback=, [callback])
+            return :pending
+          end
+          session.__send__(:propagate, buffer.byteslice(0, position))
+        end
+        buffer.replace(buffer.byteslice([position + length, 0].max..))
+        # 转义消费后清除历史，防止继续回调再次匹配同一个转义。
+        history.clear
+        return false unless callback&.call
+
+        next
+      end
+
+      # 暂存可能构成字面转义的最长后缀，保证 STOP 分两次读取时 ST 不会提前发给子进程。
+      held = 0
+      unless final
+        sequences.each_key do |key|
+          next if key.is_a?(Regexp)
+
+          [key.bytesize - 1, buffer.bytesize].min.downto(1) do |length|
+            if buffer.end_with?(key.byteslice(0, length))
+              held = [held, length].max
+              break
+            end
+          end
+        end
+      end
+      count = buffer.bytesize - held
+      count = [count, READ_SIZE].min if block_given?
+      if count.positive?
+        data = buffer.byteslice(0, count)
+        block_given? ? yield(data) : session.__send__(:propagate, data)
+      end
+      if sequences.keys.any?(Regexp)
+        history << buffer.byteslice(0, count)
+        limit = session.buffer_limit || REGEXP_ESCAPE_HISTORY_LIMIT
+        if history.bytesize > limit
+          history.replace(history.byteslice(-limit, limit))
+          if sequences.keys.any? { |key| key.is_a?(Regexp) && key.fixed_encoding? && key.encoding == Encoding::UTF_8 }
+            # 窗口可能从 UTF-8 续字节开始；丢弃不完整的首字符后再交给固定编码正则。
+            history.slice!(0) while (byte = history.getbyte(0)) && (0x80..0xBF).cover?(byte)
+          end
+        end
+      end
+      buffer.slice!(0, count)
+      return block_given? && count.positive? ? :pending : true
+    end
+  end
+
+  private_class_method :relay_buffer
+
+  def interact_source(input)
+    return input if input.is_a?(Expect)
+
+    @interact_inputs ||= {}.compare_by_identity
+    @interact_inputs.delete_if { |io, session| io.closed? || session.closed? }
+    @interact_inputs[input] ||= Expect.open(input)
+  end
+
+  def queue_output(data)
+    targets = []
+    targets << $stdout if log_stdout?
+    targets.concat(@listeners) if log_listeners?
+    @relay_outputs = targets.map do |target|
+      if target.is_a?(InteractOutput)
+        RelayWriter.new(target.target, target.render(data))
+      else
+        RelayWriter.new(target, data)
+      end
+    end
+  end
+
+  private :interact_source, :queue_output
+
+  # Only interact knows which stream is the local keyboard. Generic interconnect leaves terminals alone.
+  def prepare_interact_terminal(source)
+    return unless source.raw_terminal? && source.tty?
+
+    io = source.to_io
+    state = [io, io.console_mode]
+    io.raw!
+    state
+  rescue Exception # rubocop:disable Lint/RescueException -- Restore a partially changed terminal on interrupts.
+    restore_interact_terminal(state)
+    raise
+  end
+
+  def restore_interact_terminal(state)
+    return unless state
+
+    io, mode = state
+    io.console_mode = mode unless io.closed?
+  end
+
+  def interact_display(source, output, terminal_state)
+    @interact_output = nil unless terminal_state && @interact_output&.target.equal?(output)
+    return output unless terminal_state
+
+    target = output.respond_to?(:to_io) ? output.to_io : output
+    return output unless target.respond_to?(:tty?) && target.tty?
+    return output unless source.to_io.stat.rdev == target.stat.rdev
+
+    # 同一输出的 CRLF 可能跨越两次接管；只缓存最近目标，避免长期持有旧终端。
+    @interact_output ||= InteractOutput.new(output)
+  rescue IOError, SystemCallError
+    output
+  end
+
+  private :prepare_interact_terminal, :restore_interact_terminal, :interact_display
+
+  protected
+
+  # 仅供转接内部保存和恢复注册表，避免公开可变 Hash 绕过 on_sequence 的校验。
+  attr_accessor :sequences
+  # 让同步写入的背压读取遵守当前转接的数据所有权，退出后恢复普通匹配缓冲。
+  attr_accessor :interaction_buffer
+  attr_reader :relay_outputs
+  attr_accessor :relay_callback
+
+  # 历史属于产生它的转义规则；同规则重入继续匹配，换规则不能重放已转发输入。
+  def relay_history
+    sequences = @sequences.except(:eof)
+    @relay_history = "".b unless @relay_history_sequences == sequences
+    @relay_history_sequences = sequences
+    @relay_history
+  end
+
+  # 转接尚未处理的输入不能被匹配窗口上限裁掉；下次 expect 会重新应用该上限。
+  def restore_relay_buffer(buffer)
+    @buffer = buffer + @buffer
+  end
+end

data/lib/expect/{engine.rb → matcher.rb}

@@ -2,7 +2,7 @@
 
 class Expect
   # 驱动一次单会话或多会话匹配，管理模式优先级、EOF 和共享期限，不接管 IO 所有权。
-  class Engine
+  class Matcher
     # 固定本次参与的会话及初始期限；已处理 EOF 的会话仅从本次等待中移除。
     def initialize(patterns, timeout)
       @patterns = patterns
@@ -10,12 +10,24 @@ class Expect
       @timeout = Expect.duration(timeout)
       @deadline = next_deadline
       @handled_eof = []
+      @stalled_matches = {}
       @polled = false
     end
 
     # 运行匹配状态机；内部 :retry 表示继续循环，最终返回一个 Result。
     def run
-      @sessions.each { |session| session.__send__(:reset_result) }
+      @relay_buffers = {}
+      @sessions.each do |session|
+        buffer = session.__send__(:interaction_buffer)
+        if buffer
+          # 转义回调中的显式匹配临时接管读取，先消费转接已经预读的尾部。
+          @relay_buffers[session] = buffer
+          session.__send__(:interaction_buffer=, nil)
+          session.__send__(:restore_relay_buffer, buffer)
+          buffer.clear
+        end
+        session.__send__(:reset_result)
+      end
       loop do
         # 先消费已缓冲的匹配，再处理 EOF，最后读取；避免进程退出时丢失最后一个匹配。
         result = if (matched = find_match)
@@ -27,6 +39,11 @@ class Expect
                  end
         return result unless result == :retry
       end
+    ensure
+      @relay_buffers.each do |session, buffer|
+        buffer.replace(session.clear_buffer)
+        session.__send__(:interaction_buffer=, buffer)
+      end
     end
 
     private
@@ -38,8 +55,15 @@ class Expect
           next if @handled_eof.include?(session)
 
           buffer = session.buffer
+          stalled = @stalled_matches[session]
+          if stalled && stalled[:buffer] != buffer
+            @stalled_matches.delete(session)
+            stalled = nil
+          end
           patterns.each do |pattern|
-            position = pattern.locate(buffer)
+            next if stalled && stalled[:patterns].include?(pattern)
+
+            position = pattern.locate(buffer, final: session.eof?)
             return [session, pattern, position] if position
           end
         end
@@ -49,12 +73,17 @@ class Expect
 
     # 先记录并消费匹配，再执行回调；回调可选择结束、重置期限或保留期限继续。
     def handle_match(session, pattern, position)
+      previous_buffer = session.buffer
       result = session.__send__(:record_match, pattern, position)
       action = pattern.call(session)
       return result unless continuing?(action)
 
+      # 回调未改变缓冲时暂停当前模式，等待缓冲变化后再匹配，避免原地空转。
+      if session.buffer == previous_buffer
+        stalled = (@stalled_matches[session] ||= { buffer: previous_buffer, patterns: [] })
+        stalled[:patterns] << pattern
+      end
       @deadline = next_deadline if action == CONTINUE
-      # 零宽匹配可能不消费字节，必须在继续回调后检查期限，避免只匹配缓冲而永久空转。
       return handle_timeout if action == CONTINUE_WITHOUT_RESET && expired?
 
       :retry
@@ -100,12 +129,14 @@ class Expect
       readable.each do |io|
         session = sessions.find { |candidate| candidate.to_io.equal?(io) }
         begin
-          data = session.__send__(:read_available)
+          # 转接回调消费匹配内容，余下字节交回 Relay，不能在这里提前转发两次。
+          data = session.__send__(:read_available, propagate: !@relay_buffers.key?(session))
         rescue Errno::EINTR
           next
         rescue IOError, SystemCallError => error
           return session.__send__(:record_error, error)
         end
+        @stalled_matches.delete(session) if data
         @deadline = next_deadline if data && session.reset_timeout_on_read?
       end
       :retry
@@ -113,12 +144,16 @@ class Expect
 
     # 返回本次仍需监听的会话，供读取选择和超时回调使用。
     def active_sessions = @sessions.reject { |session| @handled_eof.include?(session) }
+
     # 只有约定的继续符号会驱动下一轮，普通回调返回值不会改变等待流程。
     def continuing?(action) = [CONTINUE, CONTINUE_WITHOUT_RESET].include?(action)
+
     # 使用单调时钟计算期限；nil 一直表示无限等待，不受系统时间调整影响。
     def next_deadline = @timeout && (Expect.monotonic + @timeout)
+
     # 计算传给 select 的非负等待秒数，避免计时跨过边界时产生负数。
     def remaining = @deadline && [@deadline - Expect.monotonic, 0].max
+
     # 判断有限期限是否已到达；无限等待不会触发超时。
     def expired? = @deadline && Expect.monotonic >= @deadline
 

data/lib/expect/pattern.rb

@@ -12,7 +12,7 @@ class Expect
     def eof? = value == :eof
 
     # 在缓冲中定位字符串或正则，返回 [字节偏移, 字节长度, 捕获组]；事件或未匹配返回 nil。
-    def locate(buffer)
+    def locate(buffer, final: false)
       case value
       when String
         offset = buffer.index(value)
@@ -21,8 +21,9 @@ class Expect
         text = buffer.dup
         text.force_encoding(value.encoding) if value.fixed_encoding?
         unless text.valid_encoding?
-          # 一次读取可能截断 UTF-8 字符。仅对完整前缀做本轮匹配，原缓冲保留残片等待后续字节。
-          text = complete_prefix(text)
+          # 不完整的尾字符可能改变锚点或前瞻结果，必须等字符收齐后再匹配。
+          validate_incomplete_suffix!(text, final: final)
+          return nil
         end
         found = value.match(text)
         return unless found
@@ -37,24 +38,15 @@ class Expect
     private
 
     # 仅容忍末尾尚未收全的 UTF-8 字符，其他非法编码直接报错，不静默替换接收字节。
-    def complete_prefix(text)
-      if text.encoding == Encoding::UTF_8
-        # UTF-8 字符最多四字节，不完整后缀最多三字节。逐一验证头字节、续字节及剩余前缀。
-        1.upto([3, text.bytesize].min) do |length|
-          prefix = text.byteslice(0, text.bytesize - length)
-          suffix = text.byteslice(text.bytesize - length, length).b
-          lead = suffix.getbyte(0)
-          expected = case lead
-                     when 0xC2..0xDF then 2
-                     when 0xE0..0xEF then 3
-                     when 0xF0..0xF4 then 4
-                     end
-          if expected && length < expected && suffix.bytes.drop(1).all? do |byte|
-            (0x80..0xBF).cover?(byte)
-          end && prefix.valid_encoding?
-            return prefix
-          end
+    def validate_incomplete_suffix!(text, final:)
+      if !final && text.encoding == Encoding::UTF_8
+        incomplete = begin
+          text.encode(Encoding::UTF_16LE)
+          false
+        rescue Encoding::InvalidByteSequenceError => error
+          error.incomplete_input?
         end
+        return if incomplete
       end
       raise EncodingError, "received invalid #{text.encoding} data; use a binary regexp (/.../n) for binary streams"
     end

data/lib/expect/relay.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+class Expect
+  # 一次转接的共同读写循环；发送游标留在源会话中，调用结束后仍可继续。
+  class Relay
+    def initialize(sessions, timeout)
+      @sessions = sessions.uniq
+      @active = @sessions.dup
+      period = Expect.duration(timeout)
+      @deadline = period && (Expect.monotonic + period)
+      @buffers = @sessions.to_h { |session| [session, session.clear_buffer] }
+      @previous = @sessions.to_h { |session| [session, session.__send__(:interaction_buffer)] }
+    end
+
+    def run
+      @sessions.each { |session| session.__send__(:interaction_buffer=, @buffers.fetch(session)) }
+      outputs.each(&:restart_timeout)
+      polled = false
+      loop do
+        idle = []
+        queued = false
+        @active.dup.each do |session|
+          next if session.pending_output?
+
+          if (callback = session.__send__(:relay_callback))
+            session.__send__(:relay_callback=, nil)
+            return session unless callback.first&.call
+          end
+
+          result = Expect.__send__(:relay_buffer, session, @buffers, final: session.eof?) do |data|
+            session.__send__(:queue_output, data)
+          end
+          return session unless result
+
+          if result == :pending
+            queued = true
+            next
+          end
+
+          idle << session
+          next unless session.eof?
+
+          callback = session.__send__(:sequences)[:eof]
+          return session unless callback&.call
+
+          @active.delete(session)
+        end
+        return nil if @active.empty?
+
+        return finish_timeout(idle) if polled && expired?
+
+        progress = advance_outputs || queued
+
+        pending = outputs
+        readers = read_sources(pending)
+        deadlines = [@deadline, *pending.map(&:deadline)].compact
+        remaining = deadlines.empty? ? nil : [deadlines.min - Expect.monotonic, 0].max
+        # 有进展时轮询输入再继续发送，避免大块输出饿死其他来源。
+        remaining = 0 if progress
+        begin
+          polled = true
+          ready = IO.select(readers.map(&:to_io), pending.filter_map(&:io).uniq, nil, remaining)
+          if ready
+            readers.each do |session|
+              next unless ready[0].include?(session.to_io)
+
+              begin
+                if @buffers.key?(session)
+                  session.__send__(:read_available, propagate: false, buffer: @buffers.fetch(session))
+                else
+                  session.__send__(:read_available, propagate: false)
+                end
+              rescue Errno::EINTR
+                next
+              end
+            end
+          elsif !progress
+            return finish_timeout(idle) if expired?
+
+            pending.each(&:check_timeout!)
+          end
+        rescue Errno::EINTR
+          next
+        end
+      end
+    ensure
+      @previous.each { |session, buffer| session.__send__(:interaction_buffer=, buffer) }
+      @buffers.each { |session, buffer| session.__send__(:restore_relay_buffer, buffer) }
+    end
+
+    private
+
+    def outputs = @sessions.flat_map { |session| session.__send__(:relay_outputs) }.reject(&:done?)
+
+    def advance_outputs(check_timeout: true)
+      progress = false
+      @sessions.each do |session|
+        pending = session.__send__(:relay_outputs)
+        pending.each { |output| progress = output.advance(check_timeout: check_timeout) || progress }
+        pending.reject!(&:done?)
+      end
+      progress
+    end
+
+    def expired? = @deadline && Expect.monotonic >= @deadline
+
+    def read_sources(pending)
+      # 输出目标可能也在等待我们读取；这些来源即使有待发送数据也必须继续排空。
+      targets = pending.map(&:target).grep(Expect)
+      sources = @active.reject { |session| session.pending_output? && !targets.include?(session) }
+      (sources + targets).uniq(&:to_io).reject(&:eof?)
+    end
+
+    def finish_timeout(idle)
+      # 调度延迟可能让两种期限均已到达，仍按先到的期限决定结果。
+      outputs.each { |output| output.check_timeout! if output.deadline && output.deadline < @deadline }
+      idle.each do |session|
+        next if session.pending_output?
+
+        buffer = @buffers.fetch(session)
+        next if buffer.empty?
+
+        session.__send__(:queue_output, buffer.dup)
+        buffer.clear
+      end
+      # 到期后只尝试一次非阻塞写入，剩余游标留给下一次 interconnect。
+      advance_outputs(check_timeout: false)
+      nil
+    end
+  end
+
+  private_constant :Relay
+end

data/lib/expect/relay_writer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+class Expect
+  # 向单个转接目标写入数据，维护发送进度与期限；恢复时不重放已成功写出的前缀。
+  class RelayWriter
+    attr_reader :target, :deadline
+
+    def initialize(target, data)
+      @target = target
+      @data = data
+      @offset = 0
+      @flushed = false
+      restart_timeout
+    end
+
+    def restart_timeout
+      period = target.write_timeout if target.is_a?(Expect)
+      @deadline = period && (Expect.monotonic + period)
+    end
+
+    def io
+      return target.writer if target.is_a?(Expect)
+
+      target if target.is_a?(IO)
+    end
+
+    def done? = @offset == @data.bytesize && @flushed
+
+    # 每轮每目标至多一次写入；真实 IO 永不在此等待，交给 Relay 的共同 select。
+    def advance(check_timeout: true)
+      return false if done?
+      raise IOError, "closed Expect session" if target.is_a?(Expect) && target.closed?
+
+      if @offset < @data.bytesize
+        bytes = @data.byteslice(@offset, READ_SIZE)
+        count = io ? io.write_nonblock(bytes, exception: false) : target.write(bytes)
+        if 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
+      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
+
+    def check_timeout!
+      return unless deadline && Expect.monotonic >= deadline
+
+      raise WriteTimeout.new("relay target write timed out", bytes_written: @offset)
+    end
+  end
+
+  private_constant :RelayWriter
+end

data/lib/expect/result.rb

@@ -6,8 +6,10 @@ class Expect
   Result = Struct.new(:number, :error, :match, :before, :after, :session, :captures, keyword_init: true) do
     # 是否命中文本模式；事件不会返回模式序号。
     def matched? = !number.nil?
+
     # 是否因本次等待期限到达而返回。
     def timeout? = error == :timeout
+
     # 是否读取源已经结束；子进程是否退出仍应查询会话的 process_status。
     def eof? = error == :eof
   end

data/lib/expect/{resources.rb → session_resources.rb}

@@ -2,8 +2,8 @@
 
 class Expect
   # 独立保存句柄、PID 和日志所有权，让终结器无需直接捕获会话即可清理遗弃资源。
-  class Resources
-    attr_accessor :pid, :status, :log, :own_log
+  class SessionResources
+    attr_accessor :pid, :status, :owned_log
     attr_reader :reader, :writer, :slave, :owner, :own
 
     # 记录创建资源的进程；fork 后的副本不能向父进程拥有的子进程发信号。
@@ -43,7 +43,7 @@ class Expect
       return unless owner == Process.pid
 
       close_handles
-      log.close if own_log && log && !log.closed?
+      owned_log.close if owned_log && !owned_log.closed?
       reap
       return unless pid
 

data/lib/expect/version.rb

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