expect-pty 0.3.1 → 0.3.3

data/lib/expect.rb

@@ -3,7 +3,6 @@
 require "pty"
 require "io/console"
 require "io/wait"
-require "shellwords"
 require "stringio"
 require "forwardable"
 require_relative "expect/version"
@@ -21,6 +20,8 @@ class Expect
   CONTINUE = :continue
   CONTINUE_WITHOUT_RESET = :continue_without_reset
   READ_SIZE = 16_384
+  CONFIGURATION_MUTEX = Mutex.new
+  private_constant :CONFIGURATION_MUTEX
 
   class SpawnError < StandardError; end
 
@@ -40,25 +41,39 @@ class Expect
       return @configuration if defined?(@configuration)
       return superclass.configuration unless self == Expect
 
-      @configuration = Configuration.new.freeze
+      CONFIGURATION_MUTEX.synchronize { @configuration ||= Configuration.new.freeze }
     end
 
     # 基于旧快照构造可修改副本，全部赋值与配置块成功后才发布，异常时保留原配置。
     def configure(**)
-      updated = Configuration.new(**configuration.to_h, **)
-      yield updated if block_given?
-      @configuration = updated.freeze
+      raise ThreadError, "nested configure is not supported" if CONFIGURATION_MUTEX.owned?
+
+      # 初始化默认快照后，将整个读改写过程串行化，避免并发配置丢失更新。
+      configuration
+      CONFIGURATION_MUTEX.synchronize do
+        updated = Configuration.new(**configuration.to_h, **)
+        yield updated if block_given?
+        @configuration = updated.freeze
+      end
     end
 
     # 创建并启动会话；有块时返回块结果并确保关闭，无块时由调用方负责生命周期。
     def spawn(*command, env: {}, chdir: nil, **)
       session = new(**)
       session.spawn(*command, env: env, chdir: chdir)
+      spawned = true
       return session unless block_given?
 
       yield session
+    rescue Exception # rubocop:disable Lint/RescueException -- 记录本次作用域的失败，清理后原样传播，包括非 StandardError 异常。
+      failed = true
+      raise
     ensure
-      session&.close if block_given? || (session && !session.pid)
+      if session && (block_given? || !spawned)
+        session.__send__(:cleanup_preserving_failure, failed) do
+          session.close(graceful: spawned && session.graceful_close?)
+        end
+      end
     end
 
     # 适配已有 IO；own: true 接管关闭责任，初始化失败也释放接管的读写端。
@@ -69,11 +84,14 @@ class Expect
       return session unless block_given?
 
       yield session
+    rescue Exception # rubocop:disable Lint/RescueException -- 初始化和块异常均须保留，清理失败不能替换原始原因。
+      failed = true
+      raise
     ensure
-      if initialized
-        session.close if block_given?
-      elsif own
-        [io, writer].uniq.each { |handle| handle.close if handle.is_a?(IO) && !handle.closed? }
+      if session && (block_given? || !initialized)
+        session.__send__(:cleanup_preserving_failure, failed) do
+          session.close(graceful: initialized && session.graceful_close?)
+        end
       end
     end
 
@@ -165,14 +183,15 @@ class Expect
     @tty_name = slave.path
     spawn(*command, env: env, chdir: chdir) unless command.empty?
     initialized = true
+  rescue Exception # rubocop:disable Lint/RescueException -- 构造异常时也要关闭已创建的资源并回收已启动的子进程。
+    failed = true
+    raise
   ensure
-    unless initialized
-      master&.close unless master&.closed?
-      slave&.close unless slave&.closed?
-    end
+    cleanup_preserving_failure(failed) { close(graceful: false) } if @resources && !initialized
   end
 
   # 在新控制终端中执行命令并同步确认 exec 结果；同一会话只能启动一次。
+  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- PTY 子进程启动与失败回传共用一次生命周期。
   def spawn(*command, env: {}, chdir: nil)
     raise SpawnError, "cannot reuse a spawned session" if @command
     raise SpawnError, "only a new PTY session can spawn" unless @slave && !@slave.closed? && !closed?
@@ -223,6 +242,7 @@ class Expect
     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
@@ -297,6 +317,7 @@ class Expect
   end
 
   # 按 Ruby to_s 规则原样写入所有字节，返回字节数；背压等待受 write_timeout 限制。
+  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 写入、背压排空和同一期限必须同步推进。
   def write(*objects)
     raise IOError, "closed Expect session" if closed? || writer.closed?
 
@@ -339,6 +360,7 @@ class Expect
     end
     data.bytesize
   end
+  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
   # 链式写入单个对象，返回当前会话。
   def <<(object)
@@ -364,88 +386,12 @@ class Expect
       object.to_s.each_char do |character|
         sleep(pause) if pause.positive?
         count += write(character)
-        read_available if !eof? && to_io.wait_readable(0.01)
+        read_available if !eof? && to_io.wait_readable(0)
       end
     end
     count
   end
 
-  # 读取当前日志目标，可能为库打开的文件、借用的 IO、回调或 nil。
-  attr_reader :log_output
-
-  # 替换借用的日志目标或停止日志；先校验新目标，失败时保留旧目标。
-  def log_output=(target)
-    unless target.nil? || target.respond_to?(:write) || target.respond_to?(:call)
-      raise ArgumentError, "log output must support write or call, or be nil"
-    end
-
-    replace_log(target)
-  end
-
-  # 打开追加/覆盖日志文件，或注册接收字节的日志块；同一次只能指定一种目标。
-  def log_to(target = nil, mode: "a", &block)
-    raise ArgumentError, "provide a log target or a block, not both" if block && target
-
-    target = block if block
-    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)
-
-      # 库打开的文件由 SessionResources 持有，替换日志或关闭会话时释放；外部 IO 只借用。
-      replace_log(File.open(target, "#{mode}b", 0o600), owned: true)
-    else
-      raise ArgumentError, "provide a log target or a block" unless target
-
-      self.log_output = target
-    end
-  end
-
-  # 向当前日志目标补写内容，支持 IO 和回调，不发送给子进程或监听器。
-  def write_log(*objects)
-    target = log_output
-    return unless target
-
-    data = objects.map { |object| object.to_s.b }.join
-    target.respond_to?(:call) ? target.call(data) : emit(target, data)
-  end
-
-  # 返回监听器列表副本，避免外部原地修改转发关系。
-  def listeners = @listeners.dup
-
-  # 校验所有监听器均可写后一次性替换列表，外部数组后续修改不会影响会话。
-  def listeners=(outputs)
-    outputs = Array(outputs)
-    raise ArgumentError, "listeners must support write" unless outputs.all? { |output| output.respond_to?(:write) }
-
-    @listeners = outputs.dup
-  end
-
-  # 查询可恢复的终端模式字符串，或通过系统 stty 设置模式；参数按数组传递，不经 shell。
-  def stty(*modes)
-    return "" unless tty?
-
-    modes = modes.flat_map { |mode| Shellwords.split(mode.to_s) }
-    modes = ["-g"] if modes.empty?
-    reader, sink = IO.pipe
-    child = Process.spawn("stty", *modes, in: to_io, out: sink, err: sink)
-    sink.close
-    output = reader.read
-    _, status = Process.waitpid2(child)
-    raise IOError, "stty failed: #{output.strip}" unless status.success?
-
-    output.strip
-  ensure
-    reader&.close unless reader&.closed?
-    sink&.close unless sink&.closed?
-  end
-
-  # 读取终端的 [行数, 列数]。
-  def winsize = to_io.winsize
-
-  # 更新终端尺寸，由内核通知前台进程。
-  def winsize=(size)
-    to_io.winsize = size
-  end
-
   # 轮询回收状态直到进程退出或期限到达；返回 Process::Status 或 nil，超时不丢弃 PID。
   def wait(timeout: nil)
     period = Expect.duration(timeout)
@@ -489,43 +435,75 @@ class Expect
   def close(graceful: graceful_close?)
     soft_close if graceful
     nil
+  rescue Exception # rubocop:disable Lint/RescueException -- 软关闭的原始异常在硬关闭兜底后继续传播。
+    failed = true
+    raise
   ensure
-    hard_close
+    cleanup_preserving_failure(failed) { hard_close }
   end
 
   private
 
+  # 仅在本次生命周期已有异常时抑制常规清理错误；调用者 rescue 中的旧异常不算本次失败。
+  def cleanup_preserving_failure(failed)
+    yield
+  rescue IOError, SystemCallError
+    raise unless failed
+  end
+
   # 共用的进程关闭流程；force 控制是否允许 KILL，只有资源创建者能够操作直属子进程。
   def finish_close(timeout:, term_timeout:, force:)
+    failure = nil
+    # 预期的清理错误延后传播，保证其余所属资源和直属子进程仍能完成清理。
+    cleanup = lambda do |&step|
+      step.call
+    rescue IOError, SystemCallError => error
+      failure ||= error
+      nil
+    end
     # IO 关闭与进程退出独立记录：软关闭可能已经 closed?，但仍保留活跃 PID。
-    @resources.close_handles
+    cleanup.call { @resources.close_handles }
     @closed = true
-    @interact_inputs&.each_value { |input| input.close(graceful: false) }
-    @interact_inputs&.clear
+    @interact_inputs&.delete_if do |_io, input|
+      cleanup.call do
+        input.close(graceful: false)
+        true
+      end
+    end
     @interact_output = nil
     @relay_outputs&.clear
     @relay_history&.clear
     @relay_callback = nil
+    status = finish_child_close(timeout: timeout, term_timeout: term_timeout, force: force)
+    completed = true
+    status
+  ensure
+    cleanup.call { self.log_output = nil }
+    # 用本次流程的完成状态判断异常传播，不能误把调用者 rescue 中的异常当成当前错误。
+    raise failure if failure && completed
+  end
+
+  # 句柄清理失败不改变进程策略；未回收 PID 保留给重复关闭或终结器继续处理。
+  def finish_child_close(timeout:, term_timeout:, force:)
     return process_status unless @resources.owner == Process.pid && pid
     return process_status if wait(timeout: timeout)
 
     signal_child("TERM")
     return process_status if wait(timeout: term_timeout)
 
-    if force
-      signal_child("KILL")
-      wait(timeout: 1)
-    end
-  ensure
-    self.log_output = nil
+    return unless force
+
+    signal_child("KILL")
+    wait(timeout: 1)
   end
 
   # 统一初始化 PTY 与已有 IO 会话，复制配置并注册不直接捕获会话的资源终结器。
   def initialize_session(reader, writer:, slave: nil, own: false, **)
+    # 先登记所有权，后续校验失败也使用同一个资源对象逐个清理所属 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?
     raise ArgumentError, "writer must be a real IO" unless writer.is_a?(IO) && !writer.closed?
 
-    @resources = SessionResources.new(reader, writer: writer, slave: slave, own: own)
     @pty = reader.tty?
     @slave = slave
     @configuration = Configuration.new(**self.class.configuration.to_h, **)
@@ -568,13 +546,14 @@ class Expect
   end
 
   # 先将读取字节交给匹配或转接缓冲，再记录日志；日志失败也能恢复输入。
-  def read_available(propagate: true, buffer: @buffer)
+  def read_available(propagate: true, buffer: @buffer, trim: true)
     return nil if eof?
 
     # 写入背压也会读取；转接期间统一交给转义处理器，不能直接转发或另存匹配缓冲。
     if @interaction_buffer
       buffer = @interaction_buffer
       propagate = false
+      trim = false
     end
 
     begin
@@ -597,7 +576,7 @@ class Expect
     end
     data = data.b
     buffer << data
-    trim_buffer if buffer.equal?(@buffer)
+    trim_buffer if trim
     trace("received #{data.inspect}", level: 2) if debug_level >= 2
     trace("buffer #{@buffer.inspect}", level: 3) if debug_level >= 3
     # 仅在真实读取时记录日志，后续匹配或人工转接重用缓冲时不会重复记录。
@@ -612,47 +591,6 @@ class Expect
     @buffer = @buffer.byteslice(-limit, limit) if limit&.positive? && @buffer.bytesize > limit
   end
 
-  # 按各自开关将接收字节转发到 stdout 和监听器，不重复写日志。
-  def propagate(data)
-    emit($stdout, data) if log_stdout?
-    @listeners.each { |listener| emit(listener, data) } if log_listeners?
-  end
-
-  # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
-  def emit(target, 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
-
-  # 按诊断级别向 stderr 输出会话标识和消息。
-  def trace(message, level: 1)
-    warn("#{inspect}: #{message}") if debug_level >= level
-  end
-
-  # 交接日志目标和所有权，只关闭库拥有的旧文件；失败时释放新打开的文件。
-  def replace_log(target, owned: false)
-    previous = log_output
-    # 重复赋值同一目标时保留原所有权，防止将库打开的文件误变成借用资源。
-    return target if previous.equal?(target)
-
-    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?
-    raise
-  end
-
   # 仅由资源创建者向仍未回收的子进程发送信号；若进程刚好退出，则尝试回收。
   def signal_child(signal)
     return unless alive? && @resources.owner == Process.pid
@@ -663,4 +601,6 @@ class Expect
   end
 end
 
+require_relative "expect/logging"
+require_relative "expect/terminal"
 require_relative "expect/interaction"

data/script/ci

@@ -6,6 +6,11 @@ cd "$(dirname "${BASH_SOURCE[0]}")/.."
 bundle exec rake
 bundle exec ruby examples/dialogue.rb
 
+# 只检查小规模工作负载的正确性，不为共享 CI 机器设置性能阈值。
+for benchmark in matching relay send_slow; do
+  bundle exec ruby "benchmark/${benchmark}.rb" --smoke
+done
+
 mkdir -p tmp/ci
 gem_version="$(ruby -Ilib -rexpect/version -e 'print Expect::VERSION')"
 gem_file="tmp/ci/expect-pty-${gem_version}.gem"

data/script/release.rb

@@ -83,11 +83,16 @@ class Release
 
   private
 
-  def capture(*arguments)
-    output, error, status = Open3.capture3(*arguments)
+  def capture(*)
+    capture_bytes(*).strip
+  end
+
+  # Git blob 是任意字节，不能沿用命令文本的 strip，尾部换行和 NUL 也属于发布内容。
+  def capture_bytes(*arguments)
+    output, error, status = Open3.capture3(*arguments, binmode: true)
     raise "#{arguments.first} failed: #{error.strip}" unless status.success?
 
-    output.strip
+    output
   end
 
   def command(*arguments)
@@ -124,7 +129,7 @@ class Release
   def verify_package
     package = Gem::Package.new(@artifact)
     expected = Gem::Specification.load(File.expand_path("expect-pty.gemspec"))
-    fields = %i[name version platform summary description authors licenses required_ruby_version
+    fields = %i[name version platform summary description authors licenses homepage required_ruby_version
                 required_rubygems_version require_paths metadata dependencies extensions executables bindir
                 post_install_message]
     unless fields.all? { |field| package.spec.public_send(field) == expected.public_send(field) }
@@ -132,6 +137,7 @@ class Release
     end
     raise "Artifact file list differs from the source" unless package.contents.sort == expected.files.sort
 
+    committed = committed_files if @commit
     # 直接检查归档中的权限，避免解包时本机 umask 改写执行位。
     File.open(@artifact, "rb") do |io|
       Gem::Package::TarReader.new(io) do |archive|
@@ -139,7 +145,10 @@ class Release
         package.open_tar_gz(data) do |tar|
           tar.each do |entry|
             file = entry.full_name
-            raise "Artifact differs from source: #{file}" unless entry.file? && entry.read == File.binread(file)
+            bytes = entry.read
+            raise "Artifact differs from source: #{file}" unless entry.file? && bytes == File.binread(file)
+
+            verify_committed_file(file, bytes, entry.header.mode, committed) if committed
             next if entry.header.mode & 0o111 == File.stat(file).mode & 0o111
 
             raise "Artifact executable permissions differ: #{file}"
@@ -149,6 +158,29 @@ class Release
     end
   end
 
+  # 工作区干净不代表所有打包文件都来自提交：ignore、assume-unchanged 和 filemode 均可隐藏差异。
+  # 只在正式发布时核对提交树；dry-run 仍允许检验尚未提交的开发源码。
+  def committed_files
+    capture_bytes("git", "ls-tree", "-rz", "--full-tree", @commit).split("\0").to_h do |record|
+      metadata, file = record.split("\t", 2)
+      mode, type, object = metadata.split
+      [file, [mode.to_i(8), type, object]]
+    end
+  end
+
+  def verify_committed_file(file, bytes, mode, committed)
+    committed_mode, type, object = committed[file.b]
+    unless type == "blob" && committed_mode & 0o170000 == 0o100000
+      raise "Artifact file is not in release commit: #{file}"
+    end
+    unless bytes == capture_bytes("git", "cat-file", "blob", object)
+      raise "Artifact differs from release commit: #{file}"
+    end
+    return if mode & 0o111 == committed_mode & 0o111
+
+    raise "Artifact executable permissions differ from release commit: #{file}"
+  end
+
   def get(path)
     uri = URI("#{GEM_HOST}#{path}")
     Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|