expect-pty 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67be724673aa5ba809cdba4e65b38f13edac9b1bca3be44f25981e5847d4eec7
-  data.tar.gz: 79837ec52929259e42f2dc7883ca4962fcf1cab5614c5d3a43f6f731892f01c5
+  metadata.gz: 0e21e96f8c4a79123cb7eb74606f0b0a8195c855290ba5ca97b43419917b1e36
+  data.tar.gz: 5f77fab495dd5d5b10e91e14a6957d3907c261cd9931dd73d1113827c1eabc74
 SHA512:
-  metadata.gz: c106240812e6ef1669ba2028f0a400eeeb03e26ad6bfbabb6832fb006171ff01fba37df047f0efd28d25d2320ad2a862772609bc954a9faa80361b0c8737e0b0
-  data.tar.gz: a09279ed617b6bc050edd1372f59321d2c6b3e89e01657a8b5d1bc576d79aa4d2c108673940df8a06c04a37af5aec2b1da658046e4b0abc0848e77751548c501
+  metadata.gz: b6334c31be027acef464d2d648dec242e43eff2367076a149c64a64a88edd27da2d51a65f3e85afcf2e8d15b2c41439c496b75731cc26db8e816d1fd3296076b
+  data.tar.gz: 1437a5c147513aa572b8b0430d8f25f0ed526ba6b14309f261f0ef30e1f0fa7e2b4850c4abd8a6a35f0988307f204870f31961c26db77245a6d35f986e34babe

data/.rubocop.yml

@@ -7,10 +7,47 @@ AllCops:
     - "tmp/**/*"
     - "vendor/**/*"
 
-# Protocol state machines and integration scenarios are reviewed by behavior,
-# rather than split merely to meet a line or branch count.
-Metrics:
-  Enabled: false
+# 宽松但有限的规模门槛覆盖生产代码；测试和基准的场景编排不按方法长度及 ABC 计数。
+# 需要更高分支复杂度的协议状态机仅在对应方法说明豁免原因。
+Metrics/AbcSize:
+  Max: 120
+  Exclude:
+    - "test/**/*"
+    - "benchmark/**/*"
+
+Metrics/BlockLength:
+  Max: 80
+
+Metrics/BlockNesting:
+  Max: 4
+  Exclude:
+    - "test/**/*"
+
+Metrics/ClassLength:
+  Max: 500
+
+Metrics/MethodLength:
+  Max: 80
+  Exclude:
+    - "test/**/*"
+    - "benchmark/**/*"
+
+Metrics/ModuleLength:
+  Max: 250
+
+Metrics/ParameterLists:
+  Max: 6
+  CountKeywordArgs: false
+
+Metrics/CyclomaticComplexity:
+  Max: 13
+  Exclude:
+    - "test/**/*"
+
+Metrics/PerceivedComplexity:
+  Max: 13
+  Exclude:
+    - "test/**/*"
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.3.3 - 2026-09-27
+
+- **生命周期**：构造及工厂启动失败时统一释放所属 IO 并回收子进程；块或软关闭的原始异常不再被后续 IO 清理错误覆盖，失败的单个句柄不会阻止其他资源收尾。
+- **匹配期限**：EOF 回调保留原期限继续时，不再于期限过后消费其他来源的文本匹配；已知 EOF 仍依次派发，所有来源结束时保持 EOF 结果。
+- **正则性能**：只在需要调整编码时复制输入缓冲，减少大缓冲区多模式扫描的耗时和分配，保持编码及字节偏移语义。
+- **终端错误**：系统缺少 `stty` 时提供明确的 IO 错误和安装提示，并保留原始异常。
+- **发布校验**：拒绝发布与目标 Git 提交的内容、执行权限或包元数据不一致的 Gem，提交前仍可通过 dry-run 验证候选包。
+
+## 0.3.2 - 2026-09-26
+
+- **匹配与转接**：正则直接使用字节偏移，重复来源在单轮扫描中共享缓冲快照；转义正则复用本轮组合文本，保留回调修改规则后的重新扫描语义。`send_slow` 只读取已经可读的回复。
+- **配置与清理**：并发 `Expect.configure` 串行发布，避免丢失更新；关闭句柄或日志失败时继续清理其他资源和直属子进程，并保留首个清理错误。转接读取显式保留未交付缓冲。
+- **维护与验证**：增加状态归属文档、性能基准及 smoke、分支复杂度检查、贡献指南和安全说明；补充匹配、转接、清理及并发配置回归测试。
+
 ## 0.3.1 - 2026-09-26
 
 - **安装依赖**：显式声明五个运行时标准库 gem，开发工具依赖单独管理，并补齐应用 Gemfile 中的 `require: "expect/pty"` 用法。

data/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# 参与贡献
+
+欢迎中文或英文 issue 和 PR。库的公共 API 名称和错误信息使用英文；库内的责任划分、复杂生命周期和协议解释使用中文，RuboCop 等工具指令保持原格式。文档以现有文件的语言为准，示例中的可编辑命令保持直接清晰。
+
+## 本地检查
+
+需要 Ruby 3.2+ 和 Linux/macOS。安装依赖后运行：
+
+```sh
+bundle install
+bundle exec rake           # RuboCop 和默认测试
+script/ci                  # 另含示例、Gem 构建及隔离安装验证
+```
+
+修改转接或匹配时，先运行对应的 `test/*_test.rb`，再运行 `bundle exec rake`。默认测试不需要 SSH；真实 SSH 集成测试的环境要求见 [测试说明](test/integration/README.md)。发布操作和历史验证分别见 [发布说明](docs/RELEASING.md) 与 [验证记录](docs/VERIFICATION.md)。
+
+RuboCop 对生产代码保留有限的长度、ABC、嵌套、参数数量和分支复杂度门槛。测试及基准的场景编排豁免方法长度与 ABC 计数；协议状态机的分支豁免只放在对应方法，并注明原因。阈值用于提示复核，职责拆分仍应保持状态归属和异常恢复逻辑完整。
+
+## 提交问题或改动
+
+问题报告请附 Ruby 版本、操作系统、最小复现代码、预期与实际结果，以及必要的异常信息；日志中请删去凭据和会话敏感内容。修复行为缺陷时，先加入能在旧实现复现问题的回归测试。涉及缓冲、转义、背压或进程清理的改动，请对照 [内部状态与数据归属](docs/INTERNAL_CONTRACTS.md)，说明超时、EOF 和失败后的恢复行为。
+
+PR 请说明行为变化、运行过的命令及结果。不要把本机生成的 `tmp/`、日志或凭据加入提交。

data/Gemfile

@@ -8,7 +8,8 @@ group :development, :test do
   # RuboCop 的依赖也必须支持最低 Ruby 版本。
   gem "parallel", "~> 1.27", require: false
   gem "rake", "~> 13.0", require: false
-  gem "rubocop", "~> 1.89", require: false
+  # 固定已审阅的规则集，避免不同 CI 环境自动启用新 cop 改变发布门槛。
+  gem "rubocop", "= 1.89.0", require: false
 
   # 测试、示例和发布工具直接使用的标准库 gem，不依赖其他开发工具间接引入。
   gem "digest", require: false

data/README.md

@@ -6,12 +6,14 @@
 
 要求 **Ruby 3.2+、POSIX 系统（Linux/macOS）**。运行时仅使用 Ruby 标准库，其中可独立安装的 gem 已在 gemspec 中声明，由 RubyGems/Bundler 解析。推荐入口 **`require "expect/pty"`**；本项目提供独立的 `Expect` 类，不修改标准库的 `IO#expect`。
 
+源码中的解释性注释主要使用中文；欢迎用中文或英文提交 issue 和 PR，参与方式见 [贡献指南](CONTRIBUTING.md)。
+
 ## 安装和运行
 
 项目和仓库名为 `expect-ruby`，Gem 名为 `expect-pty`。在应用的 Gemfile 中添加以下内容，然后运行 `bundle install`：
 
 ```ruby
-gem "expect-pty", "~> 0.3.1", require: "expect/pty"
+gem "expect-pty", "~> 0.3.3", require: "expect/pty"
 ```
 
 也可直接执行 `gem install expect-pty`。需要跟随开发分支时，可从 GitHub 安装：
@@ -24,8 +26,8 @@ gem "expect-pty", git: "https://github.com/gatework/expect-ruby.git", branch: "m
 
 ```sh
 mkdir -p tmp
-gem build expect-pty.gemspec --output tmp/expect-pty-0.3.1.gem
-gem install ./tmp/expect-pty-0.3.1.gem
+gem build expect-pty.gemspec --output tmp/expect-pty-0.3.3.gem
+gem install ./tmp/expect-pty-0.3.3.gem
 ```
 
 ```ruby
@@ -43,7 +45,7 @@ Expect.spawn("/bin/sh", "-i") do |shell|
 end
 ```
 
-块返回其执行结果，退出时关闭会话并回收子进程，异常和 `break` 也执行清理。无块形式需用 `ensure` 显式调用 `close`。`Expect.new` 可以先创建 PTY、设置 `slave.echo` / `slave.winsize`，然后调用实例的 `spawn`。
+块返回其执行结果，退出时关闭会话并回收子进程，异常和 `break` 也执行清理。构造或启动失败时同样释放已创建的资源；清理中的 IO 错误不会替换正在传播的原始异常。无块形式需用 `ensure` 显式调用 `close`。`Expect.new` 可以先创建 PTY、设置 `slave.echo` / `slave.winsize`，然后调用实例的 `spawn`。
 
 多个命令参数原样传给 Ruby `exec`；单个命令字符串使用 Ruby 的 shell 语义。不可信参数应使用独立参数形式。支持 `env: { "NAME" => "value" }` 和 `chdir: "/path"`。同一会话只能启动一次，启动失败抛出 `Expect::SpawnError`。
 
@@ -67,7 +69,9 @@ Expect.spawn("/bin/sh", "-i", timeout: 3) do |session|
 end
 ```
 
-`configure` 校验后发布冻结的配置对象；块异常不会发布部分修改。每个会话独立持有配置，优先使用构造参数；修改默认值不会改变已有会话，修改一个会话也不会影响其他会话。子类继承父类默认配置，可独立覆盖。
+`configure` 校验后发布冻结的配置对象；块异常不会发布部分修改。并发调用按顺序完成读改写，不会互相覆盖不同属性。配置块在锁内执行，应保持简短，不要在块内再次调用 `configure`（会抛出 `ThreadError`）或等待其他配置线程。每个会话独立持有配置，优先使用构造参数；修改默认值不会改变已有会话，修改一个会话也不会影响其他会话。子类继承父类默认配置，可独立覆盖。
+
+全局默认配置通常在应用启动时设置；每次会话的动态差异使用构造参数或会话属性，避免在高频路径反复获取共享配置锁。
 
 | 属性 | 默认值 | 行为 |
 | --- | --- | --- |
@@ -141,7 +145,7 @@ end
 
 回调通过闭包访问局部变量。无参数声明块在模式构建器中执行；希望保留调用方 `self` 时使用 `do |patterns|`，调用 `patterns.on(...)`。所有模式注册完成后才读取 IO；注册异常或 `break` 不消费输入。块和位置模式不能混用。`expect_result` 支持同样的声明方式。
 
-`continue` 继续等待并重新计时；`continue(reset_timeout: false)` 保留原期限，类和实例均可调用。无回调或返回其他值时结束本次匹配。超时回调只有返回重置计时的 `continue` 才再次等待。EOF 回调继续时移除该源并等待其余会话，全部 EOF 时立即返回。
+`continue` 继续等待并重新计时；`continue(reset_timeout: false)` 保留原期限，类和实例均可调用。回调返回后若保留的期限已过，不再扫描新的文本匹配，未消费的输入留给下一次等待。无回调或返回其他值时结束本次匹配。超时回调只有返回重置计时的 `continue` 才再次等待。EOF 回调继续时移除该源并等待其余会话；已知的 EOF 仍依次派发，全部 EOF 时直接返回，期限已过时仅对剩余活跃源触发超时。
 
 `eof` / `timeout` 声明会占用模式序号，但事件返回的 `number` 为 `nil`。一个等待只能注册一个超时回调；它接收**所有仍在监听的会话**。不需要回调时，可将 `:eof` / `:timeout` 作为位置事件参数。
 
@@ -187,8 +191,12 @@ ready = Expect.readable_sessions(first, second, timeout: 5)
 | `winsize` / `winsize=` | 读取/修改 `[rows, cols]`，由内核通知前台进程 |
 | `slave` / `tty_name` / `to_io` / `writer` / `fileno` / `tty?` | 底层 IO 和终端信息 |
 
+`send_slow` 在每次写入后只检查已经可读的回复，不附加固定等待；返回时不保证收齐最后一个字符引发的回复，完整对话请继续使用 `expect`。
+
 大块写入遇到背压时同时读取输出，避免双向传输互相阻塞。超过 `write_timeout` 抛出 `Expect::WriteTimeout`，`error.bytes_written` 给出本次 `write` 已被底层接受的字节数；这些字节不回滚，不要从头重发整个命令。写入、等待和背压读取中的 `EINTR` 均保留原期限重试。控制字符可直接发送，例如 `session.write("\x03")`，其信号作用取决于终端设置。`send`、`public_send`、`__send__` 保留 Ruby 反射语义。
 
+`stty` 需要系统命令位于 `PATH`；缺失时抛出带安装提示的 `IOError`，原始 `Errno::ENOENT` 保留在 `cause`。窗口尺寸和人工接管的终端恢复使用 Ruby `io/console`。
+
 ## 日志与人工交互
 
 ```ruby
@@ -206,6 +214,8 @@ session.log_listeners = false
 
 所有会话默认不输出到 stdout。日志仅记录实际读取的接收字节；写入不重复记录，终端回显可能作为接收内容返回。密码交互应关闭日志、调试，并确保被控程序不回显密码。
 
+普通 `expect` 按顺序同步写入日志、stdout 和 `listeners`，这些目标须及时消费数据；匹配的 `timeout` 不会中断阻塞中的输出。需要在慢目标背压时继续处理其他输入，应使用下面的 `interconnect` 非阻塞转接接口并设置期限。
+
 ```ruby
 session.interact(input: $stdin, escape: "\x1d", output: $stdout) # Ctrl-]
 
@@ -249,6 +259,13 @@ session.close(graceful: true) # 先软关闭，必要时继续硬关闭
 
 关闭只负责会话直接启动的子进程；垃圾回收提供非阻塞的强制清理兜底，不执行软关闭等待。优先使用块或 `ensure` 管理资源。
 
+## 安全注意事项
+
+- 将不可信命令和参数分别传给 `spawn`，例如 `Expect.spawn("ssh", host)`；单个命令字符串会使用 Ruby 的 shell 语义。`stty` 参数经拆分后作为独立参数传给进程，不拼接 shell 命令。
+- 会话日志可能记录密码回显、令牌和其他敏感字节。新日志文件以 `0600` 创建，已有文件保留原权限；请按需关闭 `log_to`、`log_stdout` 和调试输出，并管理日志留存。
+- `spawn` 在子进程中使用 `fork` 后的 Ruby 操作与 `exec`。高度多线程的宿主进程，尤其使用第三方 C 扩展时，可能受到 fork 时其他线程持锁的影响；尽量在启动其他线程前创建会话，并在自己的运行环境中验证。
+- 不可信正则可能耗费较长时间；使用带 `timeout:` 的 `Regexp` 实例，并为匹配缓冲设置合适的 `buffer_limit`。普通 `expect` 的 IO 期限不打断单次正则或同步回调。
+
 ## 示例和验证
 
 ```sh

data/benchmark/matching.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+runner = ExpectBenchmark::Runner.new("matching")
+reader, writer = IO.pipe
+session = Expect.open(reader, log_stdout: false)
+begin
+  sizes = runner.smoke ? [4096] : [4096, 65_536, 1_048_576]
+  sizes.product([1, 8, 32], %i[first last miss]).each do |size, count, hit|
+    session.buffer = "#{"x" * (size - 3)}END"
+    patterns = Array.new(count) { |index| /missing#{index}/ }
+    index = hit == :first ? 0 : count - 1
+    patterns[index] = /END/ unless hit == :miss
+    matcher = Expect::Matcher.new(Expect::PatternList.new([session], patterns), 0)
+    verify = lambda do |result|
+      valid = if hit == :miss
+                result.nil?
+              else
+                result && result[0].equal?(session) && result[1].number == index + 1 && result[2] == [size - 3, 3, []]
+              end
+      ExpectBenchmark.check(valid)
+    end
+    runner.measure("scan/#{size}/#{count}/#{hit}", bytes: size, inputs: { size: size, patterns: count, hit: hit },
+                                                   verify: verify) { matcher.__send__(:find_match) }
+  end
+  sizes.each do |size|
+    prefix = "中" * (size / 3)
+    session.buffer = "#{prefix}😀终tail"
+    matcher = Expect::Matcher.new(Expect::PatternList.new([session], [/😀(终)(x)?/]), 0)
+    verify = lambda do |result|
+      ExpectBenchmark.check(result && result[2] == [prefix.bytesize, 7, ["终".b, nil]])
+    end
+    runner.measure("utf8/#{size}", bytes: session.buffer.bytesize, inputs: { prefix_bytes: prefix.bytesize },
+                                   verify: verify) { matcher.__send__(:find_match) }
+  end
+ensure
+  session.close
+  reader.close
+  writer.close
+end
+
+[1, 8, 32].each do |count|
+  pipes = Array.new(count) { IO.pipe }
+  sessions = pipes.map { |input, _| Expect.open(input, log_stdout: false) }
+  begin
+    sessions.each { |source| source.buffer = "x" * 4096 }
+    list = Expect::PatternList.new
+    # 每轮交替反转来源组，确保同一会话真实出现在多个非相邻组。
+    8.times { |index| list.on(/missing/, from: index.even? ? sessions : sessions.reverse) }
+    # 单会话的相邻相同组会合并；保持普通单会话路径作为对照。
+    matcher = Expect::Matcher.new(list, 0)
+    runner.measure("groups/#{count}", bytes: 4096 * count, inputs: { sessions: count, groups: list.groups.size },
+                                      verify: lambda { |result|
+                                        ExpectBenchmark.check(result.nil?)
+                                      }) { matcher.__send__(:find_match) }
+    matcher.run
+    verify = lambda do |result|
+      ExpectBenchmark.check(result == :retry && sessions.all? { |source| source.buffer == "r" })
+    end
+    runner.measure("ready/#{count}", bytes: count, inputs: { sessions: count }, verify: verify) do
+      sessions.each(&:clear_buffer)
+      pipes.each { |pipe| pipe.last.write("r") }
+      ready = IO.select(pipes.map(&:first), nil, nil, 0).first
+      matcher.__send__(:read_ready, ready, sessions)
+    end
+  ensure
+    sessions.each(&:close)
+    pipes.flatten.each(&:close)
+  end
+end
+runner.finish

data/benchmark/relay.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+runner = ExpectBenchmark::Runner.new("relay")
+reader, writer = IO.pipe
+session = Expect.open(reader, log_stdout: false)
+begin
+  size = runner.smoke ? 4096 : 65_536
+  payload = "x" * size
+  %i[none literal regexps].each do |kind|
+    session.__send__(:sequences=, {})
+    session.on_sequence("STOP") if kind == :literal
+    16.times { |index| session.on_sequence(/missing#{index}/) } if kind == :regexps
+    output = StringIO.new("".b)
+    session.listeners = [output]
+    verify = ->(result) { ExpectBenchmark.check(result == true && output.string == payload) }
+    runner.measure("escape/#{kind}", bytes: size, inputs: { size: size, regexps: kind == :regexps ? 16 : 0 },
+                                     verify: verify) do
+      output.string = "".b
+      session.__send__(:relay_history).clear
+      Expect.__send__(:relay_buffer, session, { session => payload.b })
+    end
+  end
+
+  session.__send__(:sequences=, {})
+  writer.close
+  normal = StringIO.new("".b)
+  slow = StringIO.new("".b)
+  slow.define_singleton_method(:write) { |data| super(data.byteslice(0, 17)) }
+  session.listeners = [normal, slow]
+  verify = lambda do |result|
+    ExpectBenchmark.check(result.equal?(session) && normal.string == payload && slow.string == payload)
+    ExpectBenchmark.check(!session.pending_output? && session.buffer.empty?)
+  end
+  runner.measure("mixed_targets", bytes: size * 2, inputs: { size: size, short_write: 17 }, iterations: 5,
+                                  verify: verify) do
+    normal.string = "".b
+    slow.string = "".b
+    session.buffer = payload
+    Timeout.timeout(10) { Expect.interconnect(session, timeout: 5) }
+  end
+ensure
+  session.close
+  reader.close
+  writer.close unless writer.closed?
+end
+runner.finish

data/benchmark/send_slow.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+runner = ExpectBenchmark::Runner.new("send_slow")
+size = runner.smoke ? 8 : 128
+payload = "x" * size
+[false, true].product([0, 0.001]).each do |echo, delay|
+  verify = lambda do |result|
+    count, received, reply = result
+    ExpectBenchmark.check(count == size && received == payload && reply == (echo ? payload : nil))
+  end
+  runner.measure("send/#{echo ? "echo" : "silent"}/#{delay}", bytes: size,
+                                                              inputs: { size: size, echo: echo, delay: delay },
+                                                              iterations: 1, verify: verify) do
+    client, peer = Socket.pair(:UNIX, :STREAM, 0)
+    session = Expect.open(client, log_stdout: false)
+    consumer = Thread.new do
+      received = "".b
+      while received.bytesize < size
+        data = peer.readpartial(size)
+        received << data
+        peer.write(data) if echo
+      end
+      received
+    end
+    begin
+      Timeout.timeout(10) do
+        count = session.send_slow(payload, delay: delay)
+        reply = session.expect_result(payload, timeout: 2).match if echo
+        [count, consumer.value, reply]
+      end
+    ensure
+      consumer.kill.join
+      session.close
+      client.close
+      peer.close
+    end
+  end
+end
+runner.finish

data/benchmark/support.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "optparse"
+require "open3"
+require "digest"
+require "socket"
+require "timeout"
+
+# 标准库基准入口；每个工作负载先验证结果，采样后再核对，计时不包含断言。
+module ExpectBenchmark
+  # 保存环境、输入规模、耗时、分配与 GC 样本，便于比较不同源码目录。
+  class Runner
+    attr_reader :smoke, :library
+
+    def initialize(name)
+      @library = File.expand_path("../lib", __dir__)
+      @samples = 5
+      @iterations = nil
+      @smoke = false
+      @output = "tmp/benchmark/#{name}.json"
+      OptionParser.new do |options|
+        options.banner = "Usage: ruby benchmark/#{name}.rb [options]"
+        options.on("--smoke", "Small correctness workload") { @smoke = true }
+        options.on("--library PATH", "Compare another checkout's lib directory") do |path|
+          @library = File.expand_path(path)
+        end
+        options.on("--samples N", Integer) { |count| @samples = count }
+        options.on("--iterations N", Integer) { |count| @iterations = count }
+        options.on("--output PATH") { |path| @output = path }
+      end.parse!
+      unless @samples.positive? && (!@iterations || @iterations.positive?)
+        raise ArgumentError, "counts must be positive"
+      end
+
+      require File.join(@library, "expect")
+      @results = []
+    end
+
+    def measure(name, bytes:, inputs:, verify:, iterations: 100, &operation)
+      iterations = @iterations || (smoke ? 1 : iterations)
+      samples = smoke ? 1 : @samples
+      verify.call(operation.call) # 同时预热；错误输出永远不能成为更快的样本。
+      measurements = Array.new(samples) do
+        GC.start
+        before = GC.stat
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = nil
+        iterations.times { result = operation.call }
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        after = GC.stat
+        verify.call(result)
+        {
+          seconds: elapsed, allocated_objects: after[:total_allocated_objects] - before[:total_allocated_objects],
+          gc_count: after[:count] - before[:count], processed_bytes: bytes * iterations
+        }
+      end
+      @results << { name: name, inputs: inputs, iterations: iterations, samples: measurements }
+      puts "#{name}: #{format("%.6f", measurements.map { |row| row[:seconds] }.sort[samples / 2])}s"
+    end
+
+    def finish
+      root = File.dirname(library)
+      sha = git_output(root, "rev-parse", "HEAD")
+      dirty = git_output(root, "status", "--porcelain", "--untracked-files=all")
+      digest = Digest::SHA256.new
+      Dir[File.join(library, "**/*.rb")].each do |path|
+        digest << path.delete_prefix(library) << File.binread(path)
+      end
+      report = {
+        ruby: RUBY_DESCRIPTION, platform: RUBY_PLATFORM, revision: sha&.strip,
+        dirty: dirty.nil? ? nil : !dirty.empty?, library_sha256: digest.hexdigest, smoke: smoke, results: @results
+      }
+      FileUtils.mkdir_p(File.dirname(@output))
+      File.write(@output, "#{JSON.pretty_generate(report)}\n")
+      puts "Saved #{@output}"
+    end
+
+    private
+
+    # 安装包和源码归档可能没有 Git；未知状态记录为 nil，不误报为干净提交。
+    def git_output(root, *)
+      output, _, status = Open3.capture3("git", "-C", root, *)
+      output if status.success?
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+
+  def self.check(condition, message = "incorrect benchmark output")
+    raise message unless condition
+  end
+end

data/docs/COMPATIBILITY.md

@@ -24,7 +24,7 @@
 
 交互能力参考 [jacoby/expect.pm](https://github.com/jacoby/expect.pm)，源码基准为版本 1.38、提交 `2ea0e4ce20a896c95cb4c94e781f1b1f3145150d`。此项目独立实现，使用 MIT 许可，没有复制 Perl 实现代码；原项目作者及维护者为 Austin Schutz、Roland Giersig、Dave Jacoby，采用与 Perl 相同的许可。
 
-当前未发布版本采用 Ruby 原生接口。下表列出迁移关系，**旧方法、别名和参数语法已移除**；历史 0.1.1 安装包的接口见对应版本记录。
+从 0.2.0 起采用 Ruby 原生接口。下表列出迁移关系，**旧方法、别名和参数语法已移除**；历史 0.1.1 安装包的接口见对应版本记录。
 
 | 原接口或状态 | 当前 Ruby 接口 |
 | --- | --- |

data/docs/INTERNAL_CONTRACTS.md

@@ -0,0 +1,65 @@
+# 内部状态与数据归属
+
+这些状态供 Matcher、Relay 和会话生命周期协作使用，不是公共接口。
+
+## 模块职责
+
+| 模块 | 职责 |
+| --- | --- |
+| `expect.rb` | 会话入口、PTY 启动、缓冲、直接读写和关闭流程 |
+| `configuration.rb` | 配置校验与可复制的默认快照 |
+| `pattern.rb`、`pattern_list.rb`、`result.rb` | 字节定位、声明顺序及原生结果值 |
+| `matcher.rb` | 一次等待的匹配、事件派发和期限 |
+| `session_resources.rb` | IO、日志与直属子进程的所有权账本和 GC 兜底 |
+| `logging.rb` | 日志目标、监听器及同步输出；不持有第二份资源所有权 |
+| `terminal.rb` | `stty` 和窗口尺寸的会话终端接口 |
+| `interaction.rb`、`relay.rb`、`relay_writer.rb` | 人工接管、转义处理、共同调度和各目标发送游标 |
+
+这些能力文件延续 `interaction.rb` 的类重开方式，公共入口仍是 `expect/pty`。按职责组织方法，不引入新的继承层级，也不复制会话状态。
+
+跨对象调用使用 `__send__` 访问受保护或私有方法。变更以下入口时，应同时检查调用方与失败恢复路径：
+
+| 会话内部入口 | 使用方 | 不变量 |
+| --- | --- | --- |
+| `reset_result`、`record_match`、`record_eof`、`record_error` | Matcher | 先保存结果再执行回调；错误保留原始输入 |
+| `read_available` | Matcher、Relay、写入背压 | 转接缓冲交接时禁止直接传播和裁剪；普通匹配缓冲需要裁剪 |
+| `interaction_buffer`、`restore_relay_buffer` | Matcher、Relay | 嵌套匹配及转接退出时把未消费字节交还原所有者 |
+| `sequences`、`relay_history`、`relay_callback` | Relay、转义扫描 | 已识别转义只回调一次，已发送前缀不重放 |
+| `queue_output`、`relay_outputs`、`propagate` | Relay、转义扫描 | 每个目标独立保存短写进度；同步传播只用于普通匹配 |
+
+| 状态 | 所有者与修改入口 | 交接、超时与关闭 |
+| --- | --- | --- |
+| `@buffer` | 会话的未消费匹配输入；`read_available` 追加，`record_match` 消费，`clear_buffer` 移交 | Matcher 用公开 `buffer` 的副本扫描；一次扫描的重复来源复用副本，下轮重新获取。超时保留字节。关闭不清空它，便于检查尾部 |
+| `@interaction_buffer` | Relay 当前持有的待处理输入；转接背压读取也追加到这里 | 转义回调内的 Matcher 临时移回 `@buffer`；Matcher 的 ensure 将余下字节交回 Relay。Relay 的 ensure 恢复上层交互状态，并把未处理字节还给普通缓冲 |
+| `@relay_outputs` | 源会话持有的各目标发送游标；`queue_output` 创建，RelayWriter 推进 | 超时或写失败后保留原目标和已交付位置；重入续发，不重放成功前缀。关闭放弃剩余交付并清空队列，不关闭借用目标 |
+| `@relay_history` | 源会话的正则转义历史窗口；`relay_buffer` 更新 | 同一规则跨次转接保留，规则改变或转义消费后清空。窗口遵守 buffer_limit 或内部默认上限，固定 UTF-8 正则不保留开头的孤立续字节。关闭清空 |
+| `@relay_callback` | 已识别转义但尚未交付完前缀时，源会话暂存的回调 | 所有前缀目标交付完成后执行一次；超时保留，关闭释放。不能在等待写入后重新扫描这段已识别转义 |
+
+匹配优先级始终是“声明组 → 会话 → 模式”，不是文本位置；多个会话包装同一 IO 时，就绪处理使用对象身份选择首个声明会话。回调前后用于判断缓冲是否变化的快照仍独立保留，不能换成可变内部字符串。零长度或 preserve_buffer 的继续匹配必须遵守 stalled 保护。
+
+文本与 EOF 回调遵守相同的继续期限：`continue(reset_timeout: false)` 返回后先检查原期限，再开始下一轮文本匹配。EOF 继续已到期时仍依次派发已知 EOF，不读取新输入；超时仅通知仍活跃的来源，保留未消费缓冲。所有来源都已 EOF 时直接返回 EOF，不再制造一次超时事件。EOF 或超时回调重置期限后恢复普通匹配顺序。
+
+转义扫描只在一轮内复用 `history + buffer`，只含字面规则时不构造它。回调继续后重新读取规则、历史和缓冲；不能跨回调保存文本快照。字面转义的潜在前缀暂存，完整前缀交付后才执行转义回调。
+
+## 关闭与所有权
+
+SessionResources 保存创建者 PID、所属句柄、直属子进程和所属日志。借用 IO 不关闭，fork 后的非创建者不发送信号或回收父进程的孩子。soft_close 最多发送 TERM 并保留未退出 PID；hard_close 可在有限等待后发送 KILL。
+
+工厂和构造器在校验之前登记资源归属，失败时沿用同一清理流程；启动成功必须显式记录，不能用 PID 非空推断整个工厂调用已经成功。即使 exec 成功后诊断输出失败，也要立即回收未交付给调用方的子进程。
+
+显式关闭遇到 IOError/SystemCallError 时，继续尝试其他句柄、交互包装器、日志和子进程清理，最后传播首个清理错误；已经在传播的其他异常保留。失败资源继续持有，后续关闭可重试。GC 终结器独立尝试句柄、日志、非阻塞回收，常规清理错误不向外传播。终结器不能强引用会话本身。
+
+是否保留原始异常由当前构造、块或关闭作用域显式记录，不能直接读取调用者 rescue 中的 `$!`。`Interrupt` 和 `SystemExit` 同样先清理再传播；`break` / `throw` 不是异常，此时清理失败仍应抛出。
+
+## 回归入口
+
+| 不变量 | 测试 |
+| --- | --- |
+| 部分关闭失败、错误保留、借用 IO、非 owner、软硬关闭和 GC | cleanup_test、process_test、edge_case_test |
+| 字节偏移、二进制和 UTF-8 分片、零长度、可选捕获 | pattern_offset_test、matching_test、ruby_api_test、edge_case_test |
+| 一轮快照、同 IO 首来源、回调换规则、嵌套匹配 | scan_reuse_test、multi_session_test、interconnect_test |
+| 短写、转义拆包、超时恢复、不重放、回调前缀顺序 | relay_recovery_test、interconnect_test |
+| 无限/零/有限超时、继续重置/保留、EINTR、接收重置 | timeout_test（控制输入到达时间）、edge_case_test |
+| 总期限和目标写期限、连续中断不延长写超时 | relay_recovery_test |
+
+保留独立的 Matcher、Relay、write、wait 期限合同；仅为去重而统一事件循环会扩大上述状态交接的影响范围。

data/docs/PERFORMANCE.md

@@ -0,0 +1,60 @@
+# 性能基准
+
+从源码目录安装开发依赖后运行，基准本身仅使用标准库：
+
+```sh
+bundle exec ruby benchmark/matching.rb
+bundle exec ruby benchmark/relay.rb
+bundle exec ruby benchmark/send_slow.rb
+```
+
+默认预热一次、采样五次。结果分别写入 `tmp/benchmark/matching.json`、`relay.json`、`send_slow.json`，该目录不提交。每个场景先核对非空输入的预期结果，再计时；每轮计时后再次核对最后一次执行的结果。输出包括 Ruby、平台、源码提交、工作区是否修改、库源码 SHA-256、输入规模、迭代次数、处理字节数、墙钟耗时、分配对象数和 GC 次数。
+
+## 工作负载与边界
+
+| 脚本 | 范围 |
+| --- | --- |
+| matching | 4 KiB、64 KiB、1 MiB；1、8、32 个正则；首个命中、末个命中、全未命中；UTF-8 前缀和可选捕获；1、8、32 个会话、多组重复来源和同时就绪的真实管道 |
+| relay | 无转义、字面转义、16 个正则转义；正常目标与每次只接受 17 字节的目标共同接收相同数据 |
+| send_slow | 真实本地 socket；无回显、持续回显；零延迟和每字符 1ms 延迟 |
+
+`matching` 的扫描用内部 `find_match` 单独度量缓冲扫描，排除 PTY 启动和回调开销；就绪场景包含管道写入、选择和读取。`relay` 的前三项单独度量转义扫描，混合目标项运行完整转接循环。短写模拟目标吞吐受限，不等同于真实慢网络。`send_slow` 包含 socket、接收线程和完整回显校验的成本；无回显时计时止于接收方收齐数据。
+
+处理字节数表示每轮提供给场景的输入字节数（混合目标为两份交付量），不是正则引擎实际访问内存的次数。分配量是整个 Ruby 进程的计数，socket 场景包含接收线程的分配。基准不提供 CPU 或网络隔离；耗时波动不能直接归因于代码变化。
+
+## 同环境对照
+
+对照目录必须包含已知提交的完整源码。两个版本使用同一套基准脚本、同一 Ruby 和依赖，在机器空闲时交替运行，比较原始样本的中位数与分配量：
+
+```sh
+bundle exec ruby benchmark/matching.rb --library /path/to/baseline/lib --samples 5 --output tmp/benchmark/before.json
+bundle exec ruby benchmark/matching.rb --samples 5 --output tmp/benchmark/after.json
+```
+
+另外两份脚本支持相同参数。`--iterations N` 可增加单个样本工作量；比较双方必须使用相同参数。源码 SHA-256 用于区分同一提交上的未提交修改。修改工作负载后，应对两个版本重新取样。
+
+没有 Git 的源码归档或安装目录仍可运行；提交和工作区状态记为 `null`，保留源码 SHA-256。
+
+## 正则输入复用验证（2026-09-27）
+
+`Pattern#locate` 只在正则要求的编码与输入编码不同时复制输入；其他正则复用只读缓冲。Ruby 字符串可能共享底层存储，因此不能把减少一次 `dup` 直接解释为少复制整个缓冲的字节数；这里报告实际对象分配和墙钟样本。
+
+macOS arm64、Ruby 4.0.6、Bundler 4.0.17，使用同一套 `benchmark/matching.rb` 和依赖，对修改前后的 `lib` 分别运行 `--samples 5 --iterations 100`。下表为五次样本的中位数，每项均校验匹配结果。此前用 30 次迭代进行的首轮比较方向一致。
+
+| 场景 | 修改前耗时 | 修改后耗时 | 修改前分配 | 修改后分配 |
+| --- | --- | --- | --- | --- |
+| 4 KiB、32 个正则、全未命中 | 1.985 ms | 1.415 ms | 6,501 | 3,301 |
+| 64 KiB、32 个正则、全未命中 | 17.068 ms | 11.070 ms | 6,501 | 3,301 |
+| 1 MiB、32 个正则、全未命中 | 257.474 ms | 165.734 ms | 6,501 | 3,301 |
+| 1 MiB、32 个正则、最后命中 | 265.848 ms | 172.001 ms | 7,301 | 4,101 |
+| 1 MiB UTF-8 前缀、固定编码正则 | 78.348 ms | 74.721 ms | 1,201 | 1,201 |
+
+固定 UTF-8 正则仍需要编码副本，分配量不变；约 4.6% 的耗时差不能视为稳定收益。单正则大缓冲场景也基本不变。上述结果适用于本次机器与工作负载，不设为 CI 性能门槛。
+
+```sh
+bundle exec ruby benchmark/matching.rb --smoke
+bundle exec ruby benchmark/relay.rb --smoke
+bundle exec ruby benchmark/send_slow.rb --smoke
+```
+
+`script/ci` 运行这些小规模正确性检查，不设置墙钟性能阈值。热点优化必须有实际收益证据；减少对象分配不代表所有输入都会变快，也不能替代完整测试和安装验证。