expect-pty 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bffb0687dc259c0b1e2abc3920def8a496c67b0853dda43b0f7da98d0273b8b6
-  data.tar.gz: bd56c190bd1bb312902e2679a03c91d620bff4498551402344a46f979df1d9dd
+  metadata.gz: 5f3f00d375bb8a90ef67974bbd7649b031554e15f9d463cf28f1388d5d3e5dc1
+  data.tar.gz: 9c9a556719b8c79c43553bc344fa679737abb2330f8ecdec72beabfedb3842d7
 SHA512:
-  metadata.gz: e018796d8f8b2e9b2efdf515bce9ef4b57fd0e5d63e2be511e97231990b0525d98f9814c9aa23a480ae9e0956b28048e70de6187ebb535e91016f5bcb21cee61
-  data.tar.gz: 8633ebbdbee3858cb7a0756160b15357fdbc7eaf3df46ce2d8ac76f0a57eb74c3b35271c05661fd07de1c9d2f011a1e4fc0f839e4279368a7ac15a70b3deaa9e
+  metadata.gz: 53fa1a25e62c9c16c2ecbafc3efa38ba4acd2c805afa6b1547e4b83cb95c98484bbd27f612a83397a9eb9a0715af857b7f9f4d698f52bdcaa4b7dcbd3a55a42e
+  data.tar.gz: 226b72621b685c9fce34097838e0c10a81f616b3ba26a62a90eb6f09c9e3a6e0a3cd5cac331ba79c9a81caf134707821622a3e1ebe85842aff01da79b1d1d554

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.5.0 - 2026-09-27
+
+- **独立脱敏**：新增无需创建会话的 `Expect::Redactor`，支持完整文本和分块字节流过滤，以及自定义替换标记。
+- **过滤规则**：支持空模式列表和复制校验后的规则更新，完整文本仅匹配完整秘密，流结束时默认隐藏未完成的秘密前缀，现有会话脱敏行为保持不变。
+
 ## 0.4.0 - 2026-09-27
 
 - **缓冲与生命周期**：新增只读 `buffer_discarded_bytes`，区分上限裁剪与正常消费；补齐外部回收进程、借用 IO、重复关闭和失败重试的契约回归。

data/README.md

@@ -16,7 +16,7 @@ RubyGems/Bundler 解析。推荐入口 **`require "expect/pty"`**；本项目提
 项目和仓库名为 `expect-ruby`，Gem 名为 `expect-pty`。在应用的 Gemfile 中添加以下内容，然后运行 `bundle install`：
 
 ```ruby
-gem "expect-pty", "~> 0.4.0", require: "expect/pty"
+gem "expect-pty", "~> 0.5.0", require: "expect/pty"
 ```
 
 也可直接执行 `gem install expect-pty`。需要跟随开发分支时，可从 GitHub 安装：
@@ -29,8 +29,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.4.0.gem
-gem install ./tmp/expect-pty-0.4.0.gem
+gem build expect-pty.gemspec --output tmp/expect-pty-0.5.0.gem
+gem install ./tmp/expect-pty-0.5.0.gem
 ```
 
 ```ruby
@@ -290,6 +290,23 @@ session.log_to("session.log")
 3 的缓冲快照只显示 `[FILTERED]`，避免部分消费或裁剪后剩下的秘密片段绕过过滤。日志回调的分块边界因此可能变化。GC
 兜底不会调用用户日志回调，需显式关闭会话以交付过滤器尾部。
 
+应用需要过滤自己的日志或错误文本时，可以直接使用独立的字节过滤器，无需打开 PTY 或创建会话：
+
+```ruby
+require "expect/redactor"
+
+safe_message = Expect::Redactor.redact(message, [password], replacement: "[REDACTED]")
+filter = Expect::Redactor.new([password], replacement: "[REDACTED]")
+output.write(filter.append(chunk)) # 每个输出流使用独立实例
+output.write(filter.finish)
+```
+
+`patterns=` 用由非空字符串组成的数组替换后续规则，空数组表示不注册秘密；输入数组、字符串和替换标记都会复制，
+无效更新不改变已有规则或暂存数据。已输出的内容不能撤回，更新后也会保留先前标记为隐藏的尾部区间。
+`redact` 处理完整文本，只匹配完整秘密；`finish` 默认还隐藏未完成的秘密前缀。已确定输入完整的调用方可用
+`finish(partial: false)`。连续或重叠的隐藏区间合并成一个替换标记。过滤不自动识别终端控制符或编码，过滤器本身不持有 IO，
+也不负责会话作用域或异常对象的安全字段选择。该公共接口从 0.5.0 开始提供。
+
 ```ruby
 session.interact(input: $stdin, escape: "\x1d", output: $stdout) # Ctrl-]
 

data/docs/INTERNAL_CONTRACTS.md

@@ -15,9 +15,9 @@
 | `terminal.rb`                                   | `stty` 和窗口尺寸的会话终端接口                    |
 | `interaction.rb`、`relay.rb`、`relay_writer.rb` | 人工接管、转义处理、共同调度和各目标发送游标       |
 
-`redactor.rb` 为日志和各方向诊断提供内部字节流过滤器，不持有 IO，也不接管协议缓冲。
+`redactor.rb` 提供公共 `Expect::Redactor` 字节过滤接口，供会话日志、各方向诊断及上层库共用，不持有 IO，也不接管协议缓冲。
 
-这些能力文件延续 `interaction.rb` 的类重开方式，公共入口仍是 `expect/pty`。按职责组织方法，不引入新的继承层级，也不复制会话状态。
+会话能力文件延续 `interaction.rb` 的类重开方式，入口为 `expect/pty`；独立过滤器可通过 `expect/redactor` 加载。按职责组织方法，不引入新的继承层级，也不复制会话状态。
 
 跨对象调用使用 `__send__` 访问受保护或私有方法。变更以下入口时，应同时检查调用方与失败恢复路径：
 
@@ -77,7 +77,11 @@ exec 成功后诊断输出失败，也要立即回收未交付给调用方的子
 
 `logging.rb` 分开处理接收日志、诊断和协议转发。`diagnostic_output` 借用 Logger、可写对象或回调，不进入资源账本；默认沿用 stderr。回调接收冻结的事件 Hash 和 message 字符串，不含会话对象。诊断失败与其他同步 IO 错误同样保留已读取的原始输入。
 
-`redactor.rb` 是内部的字节流过滤器。会话复制并追加注册秘密，每个接收日志流以及发送、接收诊断方向各自持有过滤器。暂存最长秘密长度减一的尾部，重叠秘密合并为隐藏区间，过滤发生在 `inspect` 转义之前。缓冲快照可能只剩秘密中间字节，启用脱敏时整体隐藏，不重复展示其内容。
+`redactor.rb` 是无 IO 的公共字节过滤器。会话复制并追加注册秘密，每个接收日志流以及发送、接收诊断方向各自持有过滤器。暂存最长秘密长度减一的尾部，重叠秘密合并为隐藏区间，过滤发生在 `inspect` 转义之前。缓冲快照可能只剩秘密中间字节，启用脱敏时整体隐藏，不重复展示其内容。
+
+公共构造器及 `patterns=` 会校验并复制秘密；空模式列表直接交付字节，更新规则不清除已经建立的掩码。
+默认替换标记为 `[FILTERED]`，上层库可显式指定自己的标记。类方法 `redact` 使用独立流并以 `finish(partial: false)` 结束完整文本；
+`append`/`finish` 的默认流策略仍隐藏末尾疑似秘密前缀。作用域所有权、终端渲染和异常字段选择由调用方负责。
 
 EOF 结束接收流，日志或诊断目标替换先冲刷旧流，显式关闭结束所有方向；尾部疑似秘密前缀保守隐藏。GC 只清理所属资源，不执行用户回调或过滤尾部输出。调用方需显式关闭以交付尾部；借用日志和诊断目标不关闭，库打开的日志文件仍由 SessionResources 管理。
 
@@ -99,6 +103,7 @@ EOF 结束接收流，日志或诊断目标替换先冲刷旧流，显式关闭
 | 外部回收、借用 IO、关闭失败重试、原生错误分类 | lifecycle_contract_test |
 | 绝对期限、接收和回调重置、过期文本、EOF、EINTR、零轮询 | deadline_test |
 | Logger/IO/回调、分片与重叠秘密、二进制、流尾部、关闭失败、覆盖与重入 | diagnostics_test |
+| 公共过滤器独立加载、完整文本与分块、空规则、规则更新、输入复制和安全摘要 | redactor_test |
 | 字面跨读取命中、声明优先级、缓存失效、操作序列与全量扫描对照 | literal_scan_test |
 
 ## 既有回归入口

data/docs/VERIFICATION.md

@@ -1,5 +1,13 @@
 # 验证记录
 
+## 0.5.0 公共字节过滤器发布前复核（2026-09-27）
+
+基线为已发布的 `5a219f7`（0.4.0）。本轮公开 `Expect::Redactor`，新增 11 项回归，覆盖独立加载不引入 PTY、完整文本与流尾部策略、跨分片与重叠秘密、自定义替换标记、空规则、输入复制、无效更新原子性及安全摘要；现有会话日志与诊断继续复用该过滤器。
+
+从基线建立独立检出，仅带入本轮改动。macOS arm64、Ruby 4.0.6、Bundler 4.0.17 下执行 `ruby script/release.rb --dry-run`，330 项测试、1,894 条断言全部通过，无失败、错误或跳过；RuboCop 检查 59 个文件无违规。四组基准 smoke、Gem 构建、普通 RubyGems 与最小 Bundler 应用的隔离安装均通过，安装后实际调用公共完整文本和分块过滤接口。
+
+此处记录本地发布预演；远端 Linux/macOS 与 Ruby 3.2/3.3/3.4/4.0 矩阵、标签及下载包校验，以 0.5.0 发布提交对应的 GitHub Actions 与 Release 为准。
+
 ## 0.4.0 发布前复核（2026-09-27）
 
 发布前新增七项回归：总期限在文本回调后到达时，已知 EOF 先于剩余活跃来源的超时派发；覆盖日志路径前交付旧尾部，冲刷失败不能提前截断新文件；嵌套诊断等待保留外层匹配结果；日志回调轮换目标时正确交接所有权；诊断回调新建或再次写入另一方向时，尾部仍交给旧目标。各项均先复现失败，再验证修复，纯相对超时行为保持不变。

data/lib/expect/redactor.rb

@@ -3,10 +3,21 @@
 class Expect
   # 单个日志字节流的过滤器。保留最长秘密长度减一的尾部，跨 write/read 分片仍可识别。
   # 掩码与原字节一起留存；重叠命中的区间取并集，已经输出的掩码不重复生成。
-  # 上层负责传入已复制的非空二进制秘密，每个日志目标或诊断方向使用独立实例。
+  # 不依赖会话或 IO；每个日志目标或诊断方向使用独立实例。
   class Redactor
+    # 完整诊断文本只匹配完整秘密；流边界的疑似秘密前缀由 finish 的默认策略保护。
+    def self.redact(data, patterns, replacement: "[FILTERED]")
+      filter = new(patterns, replacement: replacement)
+      filter.append(data) + filter.finish(partial: false)
+    end
+
     # pending 保存尚不能安全输出的原字节，hidden 的对应字节用 0/1 表示是否需要遮盖。
-    def initialize(patterns)
+    def initialize(patterns, replacement: "[FILTERED]")
+      unless replacement.is_a?(String) && !replacement.empty?
+        raise ArgumentError, "replacement must be a nonempty String"
+      end
+
+      @replacement = replacement.b.freeze
       self.patterns = patterns
       @pending = "".b
       @hidden = "".b
@@ -15,21 +26,42 @@ class Expect
 
     # 更新后续匹配规则并保留已有尾部与掩码；不能追溯修改已经交付给日志目标的内容。
     def patterns=(patterns)
-      @patterns = patterns
-      @lookbehind = patterns.map(&:bytesize).max - 1
+      unless patterns.is_a?(Array) && patterns.all? { |pattern| pattern.is_a?(String) && !pattern.empty? }
+        raise ArgumentError, "patterns must be an Array of nonempty Strings"
+      end
+
+      @patterns = patterns.map { |pattern| pattern.b.freeze }.uniq.freeze
+      @lookbehind = [(@patterns.map(&:bytesize).max || 0) - 1, 0].max
     end
 
     # 追加一个原始字节块，返回已经可以确定的安全前缀；新秘密可能跨越此前保留的尾部。
     def append(data)
-      @pending << data
+      raise ArgumentError, "data must be a String" unless data.is_a?(String)
+
+      @pending << data.b
       @hidden << ("\0" * data.bytesize)
       mark_secrets
       release([@pending.bytesize - @lookbehind, 0].max)
     end
 
     # EOF、日志目标替换及关闭是流边界；尾部疑似秘密前缀也遮盖，不能因 flush 泄露片段。
-    def finish
+    def finish(partial: true)
+      raise ArgumentError, "partial must be true or false" unless [true, false].include?(partial)
+
       mark_secrets
+      mark_partial_secrets if partial
+      output = release(@pending.bytesize)
+      @masking = false
+      output
+    end
+
+    # 过滤器公开后仍不在诊断摘要中展开注册秘密或尚未交付的原始字节。
+    def inspect = "#<#{self.class}>"
+
+    private
+
+    # 流关闭时无法再等待后续字节，默认隐藏与秘密开头一致的未完成尾部。
+    def mark_partial_secrets
       @patterns.each do |pattern|
         [pattern.bytesize - 1, @pending.bytesize].min.downto(1) do |length|
           next unless @pending.end_with?(pattern.byteslice(0, length))
@@ -38,13 +70,8 @@ class Expect
           break
         end
       end
-      output = release(@pending.bytesize)
-      @masking = false
-      output
     end
 
-    private
-
     # 每次只将命中区域标为隐藏，不清除旧掩码；偏移逐字节推进以识别相互重叠的秘密。
     def mark_secrets
       @patterns.each do |pattern|
@@ -56,7 +83,7 @@ class Expect
     end
 
     # 按连续区间输出，避免逐字节构造字符串；只保存尚可能与下一块组成秘密的后缀。
-    # masking 跨 append 保留，使被分成多个块的同一隐藏区间只输出一次 [FILTERED]。
+    # masking 跨 append 保留，使被分成多个块的同一隐藏区间只输出一次替换标记。
     def release(length)
       output = "".b
       cursor = 0
@@ -64,7 +91,7 @@ class Expect
         hidden = @hidden.getbyte(cursor) == 1
         ending = [@hidden.index(hidden ? "\0" : "\1", cursor) || length, length].min
         if hidden
-          output << "[FILTERED]" unless @masking
+          output << @replacement unless @masking
         else
           output << @pending.byteslice(cursor, ending - cursor)
         end
@@ -76,6 +103,4 @@ class Expect
       output
     end
   end
-
-  private_constant :Redactor
 end

data/lib/expect/version.rb

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

data/script/ci

@@ -68,7 +68,11 @@ 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
 
-# 使用已安装包验证内部过滤器随包分发，且结构化诊断无需加载可选的 Logger。
+# 使用已安装包验证公共过滤器随包分发，且结构化诊断无需加载可选的 Logger。
+filter = Expect::Redactor.new(["secret"], replacement: "[REDACTED]")
+filtered = filter.append("sec") + filter.append("ret!") + filter.finish
+abort "installed public redactor failed" unless filtered == "[REDACTED]!"
+abort "installed complete-text redactor failed" unless Expect::Redactor.redact("sec", ["secret"]) == "sec"
 reader, producer = IO.pipe
 events = []
 transcript = StringIO.new

data/test/redactor_test.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "open3"
+require "rbconfig"
+require_relative "../lib/expect/redactor"
+
+class RedactorTest < Minitest::Test
+  def test_standalone_require_does_not_load_pty_or_allocate_a_session
+    program = <<~RUBY
+      require "expect/redactor"
+      abort "PTY loaded" if defined?(PTY)
+      abort "unexpected result" unless Expect::Redactor.redact("secret!", ["secret"]) == "[FILTERED]!"
+    RUBY
+    output, status = Open3.capture2e(RbConfig.ruby, "--disable-gems", "-I", File.expand_path("../lib", __dir__),
+                                     "-e", program)
+    assert status.success?, output
+  end
+
+  def test_empty_patterns_pass_binary_input_without_buffering
+    filter = Expect::Redactor.new([])
+    assert_equal "\xff\0raw".b, filter.append("\xff\0raw".b)
+    assert_empty filter.finish
+    assert_equal "plain", Expect::Redactor.redact("plain", [])
+  end
+
+  def test_one_shot_redaction_does_not_treat_an_ordinary_suffix_as_a_secret_prefix
+    assert_equal "pass", Expect::Redactor.redact("pass", ["password"])
+    assert_equal "[REDACTED]!", Expect::Redactor.redact("password!", ["password"], replacement: "[REDACTED]")
+  end
+
+  def test_stream_finish_masks_partial_secrets_by_default
+    filter = Expect::Redactor.new(["password"])
+    assert_equal "prefix [FILTERED]", filter.append("prefix pass") + filter.finish
+    assert_empty filter.finish
+    assert_equal "[FILTERED]!", filter.append("password!") + filter.finish
+  end
+
+  def test_exact_finish_is_explicit_and_validated
+    filter = Expect::Redactor.new(["password"])
+    filter.append("pass")
+    assert_raises(ArgumentError) { filter.finish(partial: nil) }
+    assert_equal "pass", filter.finish(partial: false)
+  end
+
+  def test_custom_marker_and_overlapping_patterns_at_every_boundary
+    patterns = ["alpha[REDACTED]omega", "[REDACTED]", "REDACTED", "[", "abc", "cde"]
+    input = "alpha[REDACTED]omega | [REDACTED] | abcde!"
+    expected = "[REDACTED] | [REDACTED] | [REDACTED]!"
+    (0..input.bytesize).each do |split|
+      filter = Expect::Redactor.new(patterns, replacement: "[REDACTED]")
+      actual = filter.append(input.byteslice(0, split)) + filter.append(input.byteslice(split..)) + filter.finish
+      assert_equal expected, actual, "split #{split}"
+    end
+    filter = Expect::Redactor.new(patterns, replacement: "[REDACTED]")
+    actual = input.bytes.map { |byte| filter.append(byte.chr) }.join + filter.finish
+    assert_equal expected, actual
+    assert_equal expected, Expect::Redactor.redact(input, patterns, replacement: "[REDACTED]")
+  end
+
+  def test_patterns_and_replacement_are_copied
+    secret = +"secret"
+    patterns = [secret]
+    replacement = +"hidden"
+    filter = Expect::Redactor.new(patterns, replacement: replacement)
+    secret.replace("public")
+    patterns.clear
+    replacement.clear
+    assert_equal "hidden!", filter.append("secret!") + filter.finish
+  end
+
+  def test_invalid_pattern_update_is_atomic_and_preserves_pending_data
+    filter = Expect::Redactor.new(["secret"])
+    filter.append("sec")
+    [nil, "secret", [""], ["valid", 1]].each do |patterns|
+      assert_raises(ArgumentError) { filter.patterns = patterns }
+    end
+    assert_equal "[FILTERED]!", filter.append("ret!") + filter.finish
+  end
+
+  def test_pattern_update_keeps_hidden_spans_and_matches_new_secret_across_chunks
+    filter = Expect::Redactor.new(%w[abc long-pattern])
+    filter.append("abcsec")
+    filter.patterns = ["secret"]
+    assert_equal "[FILTERED]!", filter.append("ret!") + filter.finish
+    filter.patterns = []
+    assert_equal "secret", filter.append("secret")
+    assert_empty filter.finish
+  end
+
+  def test_invalid_input_and_replacement_do_not_mutate_stream
+    [nil, "", 3].each do |replacement|
+      assert_raises(ArgumentError) { Expect::Redactor.new([], replacement: replacement) }
+    end
+    filter = Expect::Redactor.new(["secret"])
+    filter.append("sec")
+    assert_raises(ArgumentError) { filter.append(nil) }
+    assert_equal "[FILTERED]!", filter.append("ret!") + filter.finish
+  end
+
+  def test_inspect_does_not_expose_registered_or_pending_bytes
+    filter = Expect::Redactor.new(["private-pattern"])
+    filter.append("raw-pending")
+    assert_equal "#<Expect::Redactor>", filter.inspect
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: expect-pty
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - expect-pty contributors
@@ -169,6 +169,7 @@ files:
 - test/multi_session_test.rb
 - test/pattern_offset_test.rb
 - test/process_test.rb
+- test/redactor_test.rb
 - test/relay_recovery_test.rb
 - test/release_test.rb
 - test/ruby_api_test.rb