expect-pty 0.5.3 → 0.7.1

data/lib/expect/pattern_list.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 将 Ruby 模式和块回调整理为有序会话组；注册阶段不读取 IO、不执行匹配回调。
   # 分组结构直接决定 Matcher 的“声明组 → 会话 → 模式”优先级，不能按匹配位置重排。
   class PatternList
+    # 供匹配器读取的已编译分组和超时规则。
+    # @api private
     attr_reader :groups, :timeout_pattern
 
     # 建立默认来源，并将位置参数中的文本、正则、:eof、:timeout 转成统一模式。
@@ -26,7 +28,7 @@ class Expect
     def on(value, from: @default_sessions, &block)
       raise ArgumentError, "pattern must be a String or Regexp" unless value.is_a?(String) || value.is_a?(Regexp)
 
-      add(value.is_a?(String) ? value.b.freeze : value, from, block)
+      add(value, from, block)
     end
 
     # 为指定来源注册 EOF 回调；实例 DSL 默认使用当前会话。
@@ -37,6 +39,8 @@ class Expect
     # 注册一次等待的唯一超时回调，重复定义直接报错，避免悄悄覆盖业务处理。
     # 超时是整次等待的事件，回调收到全部活跃会话，不归属于某一个来源组。
     def timeout(&block)
+      raise FrozenError, "patterns are finalized" if frozen?
+
       raise ArgumentError, "timeout callback already registered" if @timeout_pattern
 
       @timeout_pattern = build(:timeout, block)
@@ -45,22 +49,42 @@ class Expect
 
     # 汇总并去重读取源，同一会话出现在多个模式组时仍只读取一次。
     # 这里只去重会话对象；不同会话包装同一 IO 时的读取归属由 Matcher 决定。
-    def sessions = groups.flat_map(&:first).uniq
+    # @api private
+    def sessions
+      groups.flat_map(&:first).each_with_object({}.compare_by_identity) do |session, unique|
+        unique[session] = true
+      end.keys
+    end
 
     # 收集指定会话的所有 EOF 处理器，保留原注册顺序。
+    # @api private
     def eof_patterns_for(session)
       groups.flat_map do |sessions, patterns|
-        sessions.include?(session) ? patterns.select(&:eof?) : []
+        sessions.any? { |candidate| candidate.equal?(session) } ? patterns.select(&:eof?) : []
       end
     end
 
     # 启动引擎前确保存在读取源；类级等待必须通过 from: 明确来源。
+    # @api private
     def validate!
       raise ArgumentError, "at least one session is required" if groups.empty?
 
       self
     end
 
+    # 固定本次等待的规则；只冻结声明容器，不冻结借用的会话与回调。
+    # @api private
+    def finalize!
+      validate!
+      groups.each do |sessions, patterns|
+        sessions.freeze
+        patterns.freeze
+      end
+      groups.each(&:freeze).freeze
+      @default_sessions.freeze
+      freeze
+    end
+
     private
 
     # 校验并复制来源列表，将模式加入相邻的相同来源组或新建组。
@@ -69,7 +93,7 @@ class Expect
       validate_sessions!(sessions)
       pattern = build(value, callback)
       # 仅合并相邻的相同来源，保持声明顺序；跨组复用会话由引擎去重读取。
-      if groups.last&.first == sessions
+      if same_sessions?(groups.last&.first, sessions)
         groups.last.last << pattern
       else
         groups << [sessions, [pattern]]
@@ -77,17 +101,23 @@ class Expect
       self
     end
 
+    # 会话的业务相等性不能合并不同读取源；来源对象及排列都必须相同。
+    def same_sessions?(previous, sessions)
+      !previous.nil? && previous.size == sessions.size &&
+        previous.each_with_index.all? { |session, index| session.equal?(sessions[index]) }
+    end
+
     # 按注册顺序分配从 1 开始的序号，文本模式与事件共用编号。
     def build(value, callback)
       @number += 1
-      Pattern.new(number: @number, value: value, callback: callback)
+      Pattern.new(number: @number, value:, callback:)
     end
 
-    # 拒绝空来源和非 Expect 对象，在任何 IO 读取之前暴露调用错误。
+    # 拒绝空来源和非 Session 对象，在任何 IO 读取之前暴露调用错误。
     def validate_sessions!(sessions)
-      return if !sessions.empty? && sessions.all?(Expect)
+      return if !sessions.empty? && sessions.all?(Session)
 
-      raise ArgumentError, "patterns require Expect sessions; specify from: for class-level waits"
+      raise ArgumentError, "patterns require Session objects; specify from: for class-level waits"
     end
   end
 end

data/lib/expect/redactor.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 单个日志字节流的过滤器。保留最长秘密长度减一的尾部，跨 write/read 分片仍可识别。
   # 掩码与原字节一起留存；重叠命中的区间取并集，已经输出的掩码不重复生成。
   # 不依赖会话或 IO；每个日志目标或诊断方向使用独立实例。
   class Redactor
     # 完整诊断文本只匹配完整秘密；流边界的疑似秘密前缀由 finish 的默认策略保护。
     def self.redact(data, patterns, replacement: "[FILTERED]")
-      filter = new(patterns, replacement: replacement)
+      filter = new(patterns, replacement:)
       filter.append(data) + filter.finish(partial: false)
     end
 
@@ -62,11 +62,18 @@ class Expect
 
     # 流关闭时无法再等待后续字节，默认隐藏与秘密开头一致的未完成尾部。
     def mark_partial_secrets
+      tail = @pending.byteslice(-1, 1)
+      return unless tail
+
       @patterns.each do |pattern|
-        [pattern.bytesize - 1, @pending.bytesize].min.downto(1) do |length|
-          next unless @pending.end_with?(pattern.byteslice(0, length))
+        length = [pattern.bytesize - 1, @pending.bytesize].min
+        # 前缀必须以当前尾字节结束；只收紧最高候选长度，密集候选仍沿用简单倒序扫描。
+        next unless length.positive? && (offset = pattern.rindex(tail, length - 1))
+
+        (offset + 1).downto(1) do |candidate|
+          next unless @pending.end_with?(pattern.byteslice(0, candidate))
 
-          @hidden[-length, length] = "\1" * length
+          @hidden[-candidate, candidate] = "\1" * candidate
           break
         end
       end

data/lib/expect/relay.rb

@@ -1,170 +1,195 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 一次转接的共同读写循环；发送游标留在源会话中，调用结束后仍可继续。
   # 本对象只暂借未处理输入；读缓冲、发送进度与转义回调分开保存，避免重入时重复交付。
+  # @api private
   class Relay
+    # 只串行化来源归属交接；Session 的其他操作仍须由调用方避免并发修改。
     OWNERSHIP_MUTEX = Mutex.new
     private_constant :OWNERSHIP_MUTEX
 
     # 这里只校验参数；run 取得所有来源后才转移缓冲，不关闭或接管任何外部 IO。
     def initialize(sessions, timeout)
-      @sessions = sessions.uniq
+      @sessions = sessions.uniq(&:object_id)
       @active = @sessions.dup
       period = Expect.duration(timeout)
       @deadline = period && (Expect.monotonic + period)
       @token = Object.new
-      @buffers = {}
-      @previous = {}
+      @buffers = {}.compare_by_identity
+      @previous = {}.compare_by_identity
     end
 
     # 每轮先处理转义和已排队输出，再共同选择读写；停止返回来源会话，总期限到达返回 nil。
     # 真实 IO 的写入由非阻塞游标推进，用户日志和回调仍同步执行，须由调用方保证及时返回。
-    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 共享读写循环统一维护来源和目标期限。
     def run
       prepare_sources
-      outputs.each(&:restart_timeout)
+      pending_writes.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
+        stopped, idle, queued = dispatch_sources
+        return stopped if stopped
 
-          result = Expect.__send__(:relay_buffer, session, @buffers, final: session.eof?) do |data|
-            session.__send__(:queue_output, data)
-          end
-          return session unless result
+        return nil if @active.empty?
 
-          if result == :pending
-            queued = true
-            next
-          end
+        return finish_timeout(idle) if polled && expired?
+
+        progress = advance_outputs || queued
+
+        polled = true
+        return finish_timeout(idle) if select_and_read(progress) == :timeout
+      end
+    ensure
+      restore_sources
+    end
 
-          idle << session
-          next unless session.eof?
+    private
 
-          callback = session.__send__(:sequences)[:eof]
-          return session unless callback&.call
+    # 先交付转义前缀再派发回调；EOF 只在待发送数据处理完后生效。
+    def dispatch_sources
+      idle = []
+      queued = false
+      @active.dup.each do |session|
+        next if session.pending_output?
 
-          @active.delete(session)
+        if (callback = session.relay_callback)
+          session.relay_callback = nil
+          return [session, idle, queued] unless callback.call
         end
-        return nil if @active.empty?
 
-        return finish_timeout(idle) if polled && expired?
+        result = Interaction.queue_input(session, @buffers.fetch(session), final: session.eof?)
+        return [session, idle, queued] if result == :stopped
 
-        progress = advance_outputs || queued
+        if result == :queued
+          queued = true
+          next
+        end
+
+        idle << session
+        next unless session.eof?
+
+        callback = session.sequences[:eof]
+        return [session, idle, queued] unless callback&.call
+
+        @active.delete_if { |active| active.equal?(session) }
+      end
+      [nil, idle, queued]
+    end
+
+    # 共同等待来源与目标，每轮读每个就绪来源一次；EINTR 返回原期限循环。
+    def select_and_read(progress)
+      pending = pending_writes
+      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
+        ready = IO.select(readers.map(&:to_io), pending.filter_map(&:io).uniq(&:object_id), nil, remaining)
+        if ready
+          read_ready(readers, ready.first)
+        elsif !progress
+          return :timeout if expired?
+
+          pending.each(&:check_timeout!)
+        end
+      rescue Errno::EINTR
+        nil
+      end
+      nil
+    end
+
+    # 同源转接期间读取到借用缓冲；目标会话的背压读取沿用自身状态。
+    def read_ready(readers, readable)
+      return if readable.empty?
+
+      if readable.size > 1
+        ready = {}.compare_by_identity
+        readable.each { |io| ready[io] = true }
+      end
+      readers.each do |session|
+        next unless ready ? ready.key?(session.to_io) : readable.first.equal?(session.to_io)
 
-        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), trim: false)
-                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!)
+          if @buffers.key?(session)
+            session.read_available(propagate: false, buffer: @buffers.fetch(session), trim: false)
+          else
+            session.read_available(propagate: false)
           end
         rescue Errno::EINTR
           next
         end
       end
-    ensure
-      restore_sources
     end
 
-    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-
-    private
-
     # 锁仅保护标记检查/登记，不跨 IO 或用户回调；任一来源被占用时整组拒绝，不动缓冲和期限。
     def prepare_sources
       OWNERSHIP_MUTEX.synchronize do
-        if @sessions.any? { |session| session.__send__(:relay_owner) }
-          raise ReentrancyError, "source session already has an active relay"
-        end
+        raise ReentrancyError, "source session already has an active relay" if @sessions.any?(&:relay_owner)
 
-        @sessions.each { |session| session.__send__(:relay_owner=, @token) }
+        @sessions.each { |session| session.relay_owner = @token }
       end
       @sessions.each do |session|
-        @previous[session] = session.__send__(:interaction_buffer)
+        @previous[session] = session.interaction_buffer
         @buffers[session] = session.clear_buffer
-        session.__send__(:interaction_buffer=, @buffers.fetch(session))
+        session.interaction_buffer = @buffers.fetch(session)
       end
     end
 
     # 未处理输入还给会话，已排队字节仍归游标；构造中断也只恢复已转移的缓冲及自己的标记。
     def restore_sources
-      @previous.each { |session, buffer| session.__send__(:interaction_buffer=, buffer) }
-      @buffers.each { |session, buffer| session.__send__(:restore_relay_buffer, buffer) }
+      @previous.each { |session, buffer| session.interaction_buffer = buffer }
+      @buffers.each { |session, buffer| session.restore_relay_buffer(buffer) }
     ensure
       OWNERSHIP_MUTEX.synchronize do
         @sessions.each do |session|
-          session.__send__(:relay_owner=, nil) if session.__send__(:relay_owner).equal?(@token)
+          session.relay_owner = nil if session.relay_owner.equal?(@token)
         end
       end
     end
 
     # 只收集尚未完成的目标，供共同 select 以及最早写入期限计算使用。
-    def outputs = @sessions.flat_map { |session| session.__send__(:relay_outputs) }.reject(&:done?)
+    def pending_writes = @sessions.flat_map(&:pending_writes).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 = session.pending_writes
+        pending.each { |output| progress = output.advance(check_timeout:) || progress }
         pending.reject!(&:done?)
       end
       progress
     end
 
     # 转接总期限不因持续输入或某个目标的写入进展而重置。
-    def expired? = @deadline && Expect.monotonic >= @deadline
+    def expired? = !@deadline.nil? && 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?)
+      targets = pending.filter_map do |output|
+        output.target if output.target.is_a?(Session)
+      end
+      sources = @active.reject do |session|
+        session.pending_output? && targets.none? { |target| target.equal?(session) }
+      end
+      (sources + targets).uniq { |session| session.to_io.object_id }.reject(&:eof?)
     end
 
     # 总期限结束时将可交付尾部转为发送游标，至多尝试一轮交付；余量由源会话保存。
     # 目标的写期限更早到达时保留 WriteTimeout 语义，不能被转接的普通超时掩盖。
     def finish_timeout(idle)
       # 调度延迟可能让两种期限均已到达，仍按先到的期限决定结果。
-      outputs.each { |output| output.check_timeout! if output.deadline && output.deadline < @deadline }
+      pending_writes.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)
+        session.queue_output(buffer.dup)
+        Interaction.remember_output(session, buffer)
         buffer.clear
       end
       # 到期后只尝试一次非阻塞写入，剩余游标留给下一次 interconnect。

data/lib/expect/relay_writer.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 向单个转接目标写入数据，维护发送进度与期限；恢复时不重放已成功写出的前缀。
   # 只借用目标，不 dup 描述符，也不负责读取；所有就绪等待统一交给 Relay 调度。
+  # @api private
   class RelayWriter
+    # target 始终借用；deadline 是本轮背压预算，不表示整块数据已交付。
     attr_reader :target, :deadline
 
     # data 在本游标存活期间由上层保持不变，offset 始终以实际交付的字节数计量。
@@ -18,13 +20,13 @@ class Expect
     # 初次排队或重新进入 interconnect 时开始新的写入预算；普通短写不会刷新期限。
     # 只有 Expect 目标提供 write_timeout，原生 IO 和自定义目标只受转接总期限约束。
     def restart_timeout
-      period = target.write_timeout if target.is_a?(Expect)
+      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?(Expect)
+      return target.writer if target.is_a?(Session)
 
       target if target.is_a?(IO)
     end
@@ -36,12 +38,12 @@ class Expect
     # 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?(Expect) && target.closed?
+      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 count == :wait_writable
+        if io && count == :wait_writable
           check_timeout! if check_timeout
           return false
         end

data/lib/expect/result.rb

@@ -1,18 +1,42 @@
 # frozen_string_literal: true
 
-class Expect
-  # 保存一次等待的结果，保留 Struct 原生数组、Hash 转换和模式解构能力。
-  # number 仅在文本匹配时存在；error 为 :timeout、:eof 或原始 IO 异常，文本字段均为字节串。
-  # before/match/after 是产生结果时的快照，后续读取不追加到旧结果；captures 保留未参与捕获的 nil。
-  # 结果对象仍采用普通可变 Struct 语义；session 只引用来源，不取得 IO 或子进程所有权。
-  Result = Struct.new(:number, :error, :match, :before, :after, :session, :captures, keyword_init: true) do
-    # 是否命中文本模式；事件不会返回模式序号。
+module Expect
+  # 一次等待的不可变快照；session 与 error 只引用来源和原始异常，不取得其所有权。
+  # 文本和捕获值单独复制冻结，后续读取或调用者修改输入不会改变结果。
+  # @!method self.new(**fields)
+  #   按字段关键字或成员顺序的位置参数构造不可变结果。
+  # @!method self.[](**fields)
+  #   使用与 new 相同的参数构造不可变结果。
+  # @!method self.members
+  #   返回按声明顺序排列的字段名。
+  # @!method self.inspect
+  #   返回结果类的说明。
+  # @!method members
+  #   返回按声明顺序排列的字段名。
+  # @!method with(**fields)
+  #   复制结果并替换指定字段，新文本仍独立冻结。
+  # @!method to_h
+  #   返回字段 Hash；有块时按 Ruby Data 协议转换键值对。
+  # @!method deconstruct
+  #   按成员声明顺序返回字段数组。
+  # @!method deconstruct_keys(keys)
+  #   按指定键解构结果，nil 表示全部字段。
+  Result = Data.define(:number, :error, :match, :before, :after, :session, :captures) do
+    # 构造独立不可变快照，复制字符串和捕获数组。
+    # @param captures [Array<String, nil>] 按声明顺序保存捕获组，未参与的组保留 nil。
+    def initialize(number: nil, error: nil, match: nil, before: nil, after: nil, session: nil, captures: [])
+      super(number:, error:, session:, match: match&.dup&.freeze,
+            before: before&.dup&.freeze, after: after&.dup&.freeze,
+            captures: captures.map { |value| value&.dup&.freeze }.freeze)
+    end
+
+    # 是否命中文本；EOF 和超时没有模式序号。
     def matched? = !number.nil?
 
-    # 是否因本次等待期限到达而返回。
+    # 是否因等待期限到达而返回。
     def timeout? = error == :timeout
 
-    # 是否读取源已经结束；子进程是否退出仍应查询会话的 process_status。
+    # 是否读取源已经结束，子进程状态由会话单独查询。
     def eof? = error == :eof
   end
 end