net-connector 0.10.3 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 641ad063dfd167ac9a8c45508bda6e759ebbfd0ec4cf62b86d3ca301ef165b8f
-  data.tar.gz: 588bc23e9ee7154a45baa07ebbcf0688c32926acc035bf881fa01a64cb999ec3
+  metadata.gz: 3ff14cb75482326d5580fefe4341ab39d727c1bc0d35daa90ebf34f534dbf1d1
+  data.tar.gz: eb6da5eca7eed4764f9dfa12e67708625d32cb597f206a2af1711047bcd1582c
 SHA512:
-  metadata.gz: b5a701fc703b5015609082220e370fcc1837110c511be0b6094abaf37d3a88b2cb1206f807c9ce9c5733fdc7e7c49a1bba33a4788ff08d3f0207d855569bc249
-  data.tar.gz: 95c55b593e14974041b216da1160df02ba0770c0ddb8b71a2a2bd0d103245f93ac84555ac7ce0238b63d678be252f6592b0f839842dbc39bc78782a2a17d7452
+  metadata.gz: 57c9e407fab11396ce830e35a54eddf0f5266864e76840407c7df691fa0ddf4e3f894c0e708a62f79c4e8ee2ba2236c04d3c503206e64d4d0892a1d17b74eb16
+  data.tar.gz: bfeb19f27232509e79a96b1156342365ece7ecec96a66bd56207da48dcaf3db334940aab8d8966fb0028403aa50762b7d989da3618b892b952aa49bc43293825

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 更新记录
 
+## 0.11.0 - 2026-10-17
+
+- 固定协议行分隔符，不再依赖宿主的 `$/`：并发 SSH 主机密钥冲突仍会拒绝，脚本、PAN-OS 配置、TFTP/保存证据及日志按设备行解析；标准输入凭据和隐藏密码只消费当前一行。
+- 传输事件在构造时保存不可变的二进制快照，自定义传输复用缓冲区不再覆盖已接收分片或超时证据；PTY 将字节规范化集中到事件边界，避免重复转换。自定义传输应为每次读取创建新事件，不能再修改已构造事件的字段。
+- 结果汇总在拼接前统一为原始字节，混合 UTF-8、二进制及其他编码的已完成步骤不再触发编码冲突；单条结果省去中间数组与拼接，返回值仍是独立、可修改的二进制字符串。
+- 命令回执在构造时校验命令、输出、提示及有限非负耗时，避免非法对象进入已完成步骤后才在汇总或诊断时失败。
+- 自定义对话提前校验错误匹配与交互列表，复制并冻结自身规则，不再冻结调用方数组；无效规则在会话开始前报告。
+- 字节、诊断、SSH 信任文件及终端进度拼接使用显式空分隔符，避免宿主设置 Ruby 的 `$,` 后将额外字符插入响应、错误证据或文件。
+
 ## 0.10.3 - 2026-10-16
 
 - 保护会话锁取得、登记和释放的异步取消边界，完整操作、单次执行和关闭共用持锁作用域；业务等待仍可取消，非局部退出仍释放锁。

data/docs/architecture.md

@@ -139,6 +139,8 @@ Diagnostic 只保存固定词表中的码、类型、阶段和受控产物状态
 
 ## 迁移与尚未启用的能力
 
+自定义字节传输每次 `read` 返回新的 `Net::Connector::Event`。事件及其 `before`、`match` 字节串不可变；构造时复制可变输入并统一为二进制，调用方可继续复用源缓冲区。已有事件不能再通过 Struct 的字段赋值器修改，错误对象的身份保留。设备协议、脚本、SSH 信任文件和标准输入凭据使用显式换行符，不继承宿主的 `$/` 或 `$,` 设置。
+
 | 变化 | 调用方需要保留的约定 |
 | --- | --- |
 | 配置采集默认输出敏感 | 所有日志模式及错误正文隐藏配置；Result.config/steps 和备份仍保留原数据。自定义敏感业务需声明 output_sensitive，不以注册登录密码代替正文保护 |

data/docs/usage.md

@@ -122,6 +122,8 @@ warn "#{result.error.code}: #{result.steps.size} completed commands" if result.f
 
 `execute_command` runs one command; `execute_script` accepts a `Script` or command array. `Script.load(path)` reads a file. Commands are validated before I/O; completed steps survive later failures. `save_config` explicitly sends save commands; ordinary scripts do not save automatically.
 
+`result.output` concatenates completed steps as raw bytes without transcoding. Each call returns a mutable binary string; changing it does not change the frozen step outputs. Use `result.config` for the cleaned configuration, or `result.value!` to raise on failure before reading the successful value.
+
 Set `max_script_output_bytes:` to bound cumulative raw responses, including additional queries. Default is `nil`. Exceeding it returns `ScriptOutputLimitExceeded` (`:script_output_limit_exceeded`) and stops subsequent commands; the current command may already have executed. `max_output_bytes` separately limits each response. Neither setting is a process-memory limit.
 
 Per-command prompts use `interactions: [Net::Connector::Interaction.new(/Token:\z/, ->(_) { "value\n" }, sensitive: true)]`. Mark commands containing secrets `sensitive: true`. For safe command text with sensitive output, use `output_sensitive: true`; `running_config` enables this automatically.

data/docs/usage.zh-CN.md

@@ -169,6 +169,8 @@ end
 
 `execute_command` 执行一条命令；`execute_script` 接收 `Script` 或命令数组；`Script.load(path)` 读取脚本文件。所有命令在设备 I/O 前校验，后续步骤失败时仍保留已完成结果，库不会自动重放命令。`save_config` 显式执行厂商保存命令，普通脚本不会自动保存。
 
+`result.output` 按顺序拼接已完成步骤的原始字节，不执行字符编码转换。每次调用返回可修改的二进制字符串，修改它不会改变已冻结的步骤输出。清理后的配置使用 `result.config`；需要失败时先抛出错误，再读取成功值时使用 `result.value!`。
+
 创建连接器时可设置 `max_script_output_bytes: 8 * 1024 * 1024`，限制每个脚本及其追加查询累计收到的原始响应字节；默认 `nil` 保持原有完整输出行为。达到上限后不再发送下一命令，当前响应超过上限时保留刚完成的步骤并返回 `ScriptOutputLimitExceeded`（`code: :script_output_limit_exceeded`）。命令可能已经执行，不会自动重试。原有 `max_output_bytes` 继续限制单次读取响应；累计预算不是进程内存上限，详细计数规则见架构文档。
 
 厂商档案处理分页和常见确认提示。特定命令可给 `execute_command` 传入 `interactions: [Net::Connector::Interaction.new(/Token:\z/, ->(_) { "value\n" }, sensitive: true)]`。敏感命令及交互会暂停回显日志并在错误中脱敏；若普通命令文本包含秘密，必须显式标记 `sensitive: true`。

data/lib/net/connector/device/running_config/strategy.rb

@@ -18,7 +18,7 @@ module Net
 
         # 普通采集命令保持视图不变；需要切换视图的采集策略显式调整。
         def prompt_text(_command)
-          TerminalRenderer.render(@device.current_prompt.to_s).lines.last.to_s.strip
+          TerminalRenderer.render(@device.current_prompt.to_s).lines("\n").last.to_s.strip
         end
 
         # 公共策略不增加逐命令响应检查。

data/lib/net/connector/device/running_config.rb

@@ -104,7 +104,7 @@ module Net
       def config_body?(step)
         body = TerminalRenderer.render(step.output.delete_suffix(step.prompt.to_s)).strip
         # 只需确认首个正文行；不为大配置创建全部行对象或重新拼接整份响应。
-        body.each_line.with_index.any? do |line, index|
+        body.each_line("\n").with_index.any? do |line, index|
           text = line.strip
           !text.empty? && !(index.zero? && text == step.command.text)
         end

data/lib/net/connector/device/tftp/strategy.rb

@@ -59,10 +59,10 @@ module Net
         # 移除精确命令、静态响应和提示符，保留回车重绘前后的设备消息。
         def evidence_lines(step, output)
           prompt = TerminalRenderer.render(step.prompt.to_s).strip
-          responses = step.command.interactions.filter_map { |reply| reply.static_response&.chomp }
+          responses = step.command.interactions.filter_map { |reply| reply.static_response&.chomp("\n") }
           echoes = [step.command.text, "#{prompt}#{step.command.text}", *responses]
           # 原文中的每次回车分开核对，避免重绘回显误报，也保留被覆盖的诊断。
-          output.each_line.flat_map { |line| line.split(/\r(?!\n)/) }.map do |line|
+          output.each_line("\n").flat_map { |line| line.split(/\r(?!\n)/) }.map do |line|
             # 样式不改变字符历史；光标移动和擦除不能拿来删掉原始失败消息。
             line.gsub(/\e\[[0-9;:]*m/, "").strip
           end.reject { |line| line.empty? || line == prompt || echoes.include?(line) }

data/lib/net/connector/device/topology/immediate_strategy.rb

@@ -29,7 +29,7 @@ module Net
             failure = /\b(?:error|failed|failure|denied|cannot|unable|unsuccessful|aborted)\b/i
             next false if history.match?(failure) || TerminalRenderer.render(history).match?(failure) || rendered.match?(failure)
 
-            rendered.lines.any? { |line| line.strip.match?(persistence_pattern) }
+            rendered.lines("\n").any? { |line| line.strip.match?(persistence_pattern) }
           end
         end
 

data/lib/net/connector/engine/command.rb

@@ -70,8 +70,8 @@ module Net
       def self.parse(text, name: nil)
         raise ArgumentError, "script must be a String" unless text.is_a?(String)
 
-        commands = text.each_line.with_index(1).filter_map do |line, line_number|
-          line = line.chomp
+        commands = text.each_line("\n").with_index(1).filter_map do |line, line_number|
+          line = line.chomp("\n")
           next if line.strip.empty? || line.lstrip.start_with?("#")
 
           Command.new(line, source: name, line: line_number)

data/lib/net/connector/engine/dialogue.rb

@@ -70,10 +70,10 @@ module Net
         [login_prompt, command_prompt, password_prompt, username_prompt, enable_prompt].each do |pattern|
           raise ArgumentError, "prompt must be a nonempty Regexp" unless pattern.is_a?(Regexp) && !pattern.match?("")
         end
-        @authentication_errors = authentication_errors.freeze
-        @command_errors = command_errors.freeze
-        @login_interactions = login_interactions.freeze
-        @command_interactions = command_interactions.freeze
+        @authentication_errors = patterns(authentication_errors, :authentication_errors)
+        @command_errors = patterns(command_errors, :command_errors)
+        @login_interactions = interactions(login_interactions, :login_interactions)
+        @command_interactions = interactions(command_interactions, :command_interactions)
         freeze
       end
 
@@ -88,6 +88,24 @@ module Net
 
       private
 
+      # 自定义对话遵循与 Profile 相同的非空匹配规则，不冻结调用方数组。
+      def patterns(values, name)
+        unless values.is_a?(Array) && values.all? { |value| value.is_a?(Regexp) && !value.match?("") }
+          raise ArgumentError, "#{name} must be an Array of nonempty Regexp objects"
+        end
+
+        values.map { |value| value.frozen? ? value : value.dup.freeze }.freeze
+      end
+
+      # 交互对象自身不可变，只复制所属列表。
+      def interactions(values, name)
+        unless values.is_a?(Array) && values.all?(Interaction)
+          raise ArgumentError, "#{name} must be an Array of Interaction objects"
+        end
+
+        values.dup.freeze
+      end
+
       # 只截取命中错误模式的当前行，避免把整段设备配置写进诊断信息。
       def diagnostic_line(output)
         match = command_errors.lazy.filter_map { |pattern| pattern.match(output) }.first

data/lib/net/connector/engine/known_hosts.rb

@@ -31,7 +31,7 @@ module Net
       end
 
       def commit
-        additions = File.binread(path).lines - @original.lines
+        additions = File.binread(path).lines("\n") - @original.lines("\n")
         return if additions.empty?
 
         with_lock do
@@ -42,10 +42,10 @@ module Net
             reject_changed_key!(file.path) unless @replace
             remove_host(file.path) if @replace
             contents = File.binread(file.path)
-            entries = contents.lines
+            entries = contents.lines("\n")
             additions.each { |line| entries << line unless entries.include?(line) }
             File.open(file.path, "wb", 0o600) do |replacement|
-              replacement.write(entries.map { |line| line.end_with?("\n") ? line : line + "\n" }.join)
+              replacement.write(entries.map { |line| line.end_with?("\n") ? line : line + "\n" }.join(""))
               replacement.flush
               replacement.fsync
             end
@@ -130,7 +130,7 @@ module Net
         output, status = Open3.capture2e("ssh-keygen", "-f", path, "-F", @host)
         raise IOError, "reading device host key failed" unless [0, 1].include?(status.exitstatus)
 
-        output.lines.reject { |line| line.start_with?("#") }.map { |line| line.split[1, 2] }.uniq
+        output.lines("\n").reject { |line| line.start_with?("#") }.map { |line| line.split[1, 2] }.uniq
       end
 
       def remove_host(path)

data/lib/net/connector/engine/log/stream.rb

@@ -37,7 +37,7 @@ module Net
         def write(bytes)
           @buffer << bytes
           while (ending = @buffer.index("\n"))
-            @on_line.call(@buffer.slice!(0, ending + 1).chomp)
+            @on_line.call(@buffer.slice!(0, ending + 1).chomp("\n"))
           end
           bytes.bytesize
         end

data/lib/net/connector/engine/log.rb

@@ -138,8 +138,8 @@ module Net
       def log_response_output(bytes)
         return unless debug? && !@writer && !@redactor.output_sensitive?
 
-        @redactor.call(TerminalRenderer.render(@redactor.call(bytes))).each_line do |line|
-          write_event("device_output", level: :debug, output: line.chomp)
+        @redactor.call(TerminalRenderer.render(@redactor.call(bytes))).each_line("\n") do |line|
+          write_event("device_output", level: :debug, output: line.chomp("\n"))
         end
       rescue Error
         raise

data/lib/net/connector/engine/response_reader.rb

@@ -42,7 +42,7 @@ module Net
           end
           next if Expect.monotonic < deadline
 
-          raise build_read_error(nil, phase, command, raw.join), cause: nil
+          raise build_read_error(nil, phase, command, raw.join("")), cause: nil
         end
       end
 
@@ -63,22 +63,22 @@ module Net
       def validate_event!(event, bytes, raw, phase, command)
         if bytes > @session.configuration.max_output_bytes
           raise @session.build_error(OutputLimitExceeded, "device output exceeded max_output_bytes",
-                                     phase: phase, command: command, output: (raw + [event.match]).join), cause: nil
+                                     phase: phase, command: command, output: (raw + [event.match]).join("")), cause: nil
         end
-        raise build_read_error(event, phase, command, raw.join), cause: nil unless event.matched?
+        raise build_read_error(event, phase, command, raw.join("")), cause: nil unless event.matched?
       end
 
       # 完整提示符必须消费字节；交互标记可从业务输出排除，但原始响应始终保留。
       def finish_response(prompt, raw, output, phase, command)
         if prompt.empty?
           raise @session.build_error(PromptError, "prompt pattern did not consume any output",
-                                     phase: phase, command: command, output: raw.join), cause: nil
+                                     phase: phase, command: command, output: raw.join("")), cause: nil
         end
 
         raw << prompt
         output << prompt
-        raw_text = raw.join
-        Response.new(raw: raw_text, output: (output == raw) ? raw_text : output.join, prompt: prompt)
+        raw_text = raw.join("")
+        Response.new(raw: raw_text, output: (output == raw) ? raw_text : output.join(""), prompt: prompt)
       end
 
       # 重复提示和缺失应答必须在写入前失败；所有应答共用读取操作的截止时间。
@@ -91,7 +91,7 @@ module Net
         value = interaction_response(reply, prompt, phase, command)
         raise build_interaction_error("response unavailable", phase, command), cause: nil unless value.is_a?(String)
 
-        @session.redactor.remember(value.chomp) if reply.sensitive?
+        @session.redactor.remember(value.chomp("\n")) if reply.sensitive?
         @session.write(value, deadline: deadline, phase: phase, command: command)
       end
 

data/lib/net/connector/engine/result.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "command"
 
 module Net
   module Connector
@@ -10,6 +11,13 @@ module Net
 
       # 保存命令输出、提示符和耗时，并冻结结果。
       def initialize(command:, output:, prompt:, duration:)
+        raise ArgumentError, "command must be a Command" unless command.is_a?(Command)
+        raise ArgumentError, "output must be a String" unless output.is_a?(String)
+        raise ArgumentError, "prompt must be a String or nil" unless prompt.nil? || prompt.is_a?(String)
+        unless duration.is_a?(Numeric) && duration.real? && duration.finite? && duration >= 0
+          raise ArgumentError, "duration must be a finite nonnegative real number"
+        end
+
         @command = command
         @output = output.frozen? ? output : output.dup.freeze
         @prompt = prompt&.dup&.freeze
@@ -51,7 +59,14 @@ module Net
       def each(&) = steps.each(&)
 
       # 拼接所有已完成步骤的输出字节。
-      def output = steps.map(&:output).join.b
+      def output
+        return steps.first.output.b if steps.size == 1
+
+        # 拼接前统一编码；仅在拼接后调用 b 无法避免不同编码之间的冲突。
+        steps.map do |step|
+          step.output.encoding == Encoding::BINARY ? step.output : step.output.b
+        end.join("").force_encoding(Encoding::BINARY)
+      end
 
       # 成功时返回配置或输出，失败时重新抛出领域错误。
       def value!

data/lib/net/connector/engine/terminal_renderer.rb

@@ -177,7 +177,7 @@ module Net
         return text.b if text.valid_encoding?
         raise Encoding::InvalidByteSequenceError, "terminal editing produced invalid UTF-8" if @strict_utf8
 
-        text.scrub { |invalid| invalid.bytes.map { |byte| format("\\x%02X", byte) }.join }.b
+        text.scrub { |invalid| invalid.bytes.map { |byte| format("\\x%02X", byte) }.join("") }.b
       end
     end
   end

data/lib/net/connector/engine/transport.rb

@@ -8,9 +8,16 @@ module Net
   module Connector
     # 传输事件使用从零开始的模式索引；最后一个额外索引表示流式数据。
     Event = Struct.new(:index, :before, :match, :error) do
-      # 规范化事件的默认字节字段，便于读取器统一处理。
+      # 固定每次读取的字节快照，传输复用缓冲区时不能改写先前分片。
       def initialize(index: nil, before: "".b, match: "".b, error: nil)
-        super
+        unless before.is_a?(String) && match.is_a?(String)
+          raise ArgumentError, "before and match must be Strings"
+        end
+
+        before = before.b.freeze unless before.frozen? && before.encoding == Encoding::BINARY
+        match = match.b.freeze unless match.frozen? && match.encoding == Encoding::BINARY
+        super(index, before, match, error)
+        freeze
       end
 
       # 判断读取是否命中了模式而不是传输错误。
@@ -79,8 +86,8 @@ module Net
         def read(patterns, timeout:)
           reader = @channel.respond_to?(:expect_result) ? :expect_result : :expect
           result = @channel.public_send(reader, *patterns, STREAM, timeout: timeout)
-          Event.new(index: result.number && (result.number - 1), before: result.before.to_s.b,
-                    match: result.match.to_s.b, error: result.error)
+          Event.new(index: result.number && (result.number - 1), before: result.before.to_s,
+                    match: result.match.to_s, error: result.error)
         end
 
         # 临时设置写入超时，完成写入后恢复原设置。

data/lib/net/connector/netdisco/backup_run.rb

@@ -44,7 +44,7 @@ module Net
           preview = plan_summary(plan)
           @output.puts JSON.generate(plan: preview) if options[:json]
           @output.flush
-          return 1 if options[:stdin_credentials] && @input.gets&.strip != "RUN"
+          return 1 if options[:stdin_credentials] && @input.gets("\n")&.strip != "RUN"
 
           Storage::PrivateFile.write(File.join(batch_directory, "plan.json"), JSON.pretty_generate(preview))
           report = execute(fleet, settings, plan, batch_directory, progress, success_policy, server_root)

data/lib/net/connector/netdisco/cli/options.rb

@@ -138,7 +138,7 @@ module Net
             require "io/console"
             output.print "#{label}："
             output.flush
-            password = input.noecho(&:gets)&.chomp
+            password = input.noecho { |terminal| terminal.gets("\n") }&.chomp("\n")
             output.puts
             raise ArgumentError, "密码不能为空" if password.nil? || password.empty?
 

data/lib/net/connector/netdisco/connection.rb

@@ -14,7 +14,7 @@ module Net
           end
 
           begin
-            values = JSON.parse(input.gets || "")
+            values = JSON.parse(input.gets("\n") || "")
           rescue JSON::ParserError
             raise ArgumentError, "凭据 JSON 无效", cause: nil
           end

data/lib/net/connector/netdisco/progress.rb

@@ -241,7 +241,7 @@ module Net
           text.each_char.take_while do |character|
             width += character.ord > 255 ? 2 : 1
             width < columns
-          end.join
+          end.join("")
         rescue IOError, SystemCallError
           line
         end

data/lib/net/connector/vendor/h3c/topology.rb

@@ -61,7 +61,7 @@ module Net
 
         # 过滤表头、分隔线和设备提示符，保留待解析的邻居行。
         def neighbor_lines(output)
-          output.lines.drop_while { |line| !line.match?(TABLE_HEADER) }.map(&:strip).reject do |line|
+          output.lines("\n").drop_while { |line| !line.match?(TABLE_HEADER) }.map(&:strip).reject do |line|
             line.empty? || line.match?(TABLE_HEADER) || line.match?(/\A[-=+ ]+\z/) ||
               line.match?(/\A(?:<[^>]+>|\[[^\]]+\])\z/)
           end

data/lib/net/connector/vendor/hillstone/topology.rb

@@ -52,7 +52,7 @@ module Net
 
         # 去掉命令、表头、总数和提示符，只保留邻居数据行。
         def neighbor_lines(output)
-          output.lines.map(&:strip).reject do |line|
+          output.lines("\n").map(&:strip).reject do |line|
             line.empty? || line == neighbor_command || line.match?(/\ASystem Name\s+Local Interface\b/i) ||
               line.match?(/\ATotal lldp neighbor number:\s*\d+\.?\z/i) ||
               line.match?(/\A[-=+ ]+\z/) || line.match?(/\A\S+(?:#|\([MBF]\))\z/)

data/lib/net/connector/vendor/palo_alto/running_config.rb

@@ -50,7 +50,7 @@ module Net
 
           pending = +""
           quote = nil
-          text.each_line do |line|
+          text.each_line("\n") do |line|
             next if pending.empty? && line.strip.empty?
             return false if pending.empty? && !line.start_with?("set ")
 

data/lib/net/connector/vendor/palo_alto/topology.rb

@@ -67,7 +67,7 @@ module Net
         # 邻居字段区只有空行和提示符时，才视为明确的空块。
         def empty_neighbor_block?(block)
           tail = block.split(/^\s*Neighbor information:\s*$/i, 2)
-          tail.size == 2 && tail.last.lines.all? { |line| line.strip.empty? || line.match?(/^\S+[>#]\s*$/) }
+          tail.size == 2 && tail.last.lines("\n").all? { |line| line.strip.empty? || line.match?(/^\S+[>#]\s*$/) }
         end
       end
     end

data/lib/net/connector/version.rb

@@ -3,6 +3,6 @@
 module Net
   module Connector
     # gemspec、CLI 与发布工具共用此版本，运行时读取不触发设备依赖加载。
-    VERSION = "0.10.3"
+    VERSION = "0.11.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.10.3
+  version: 0.11.0
 platform: ruby
 authors:
 - net-connector contributors