net-connector 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f994834e561576d4fafde11f003653a865dd4d35da5a5fd8a7a4c2a016cc2d5
-  data.tar.gz: f7585fe57b094fd687b2de70e34b6b41eb0e46c220d5fc9bfe4357a25c31f6f9
+  metadata.gz: 3ff14cb75482326d5580fefe4341ab39d727c1bc0d35daa90ebf34f534dbf1d1
+  data.tar.gz: eb6da5eca7eed4764f9dfa12e67708625d32cb597f206a2af1711047bcd1582c
 SHA512:
-  metadata.gz: c862e76e800b3ef6174e8aeadaedd4724dafbd08858954874e6955c0c71a4f21c1f9fd124dfe60e59e5389380330193740cbed6e2c0369ee6f9eaddd0b0d56ce
-  data.tar.gz: 6d62272a65c854987a1d9d73e1cb6aeba177743df828e37ec20595b31e9c42ada27dd787989a9cf1ecc17a3ae7fa1fe46f3c6db992e736ffcb2337c42b081feb
+  metadata.gz: 57c9e407fab11396ce830e35a54eddf0f5266864e76840407c7df691fa0ddf4e3f894c0e708a62f79c4e8ee2ba2236c04d3c503206e64d4d0892a1d17b74eb16
+  data.tar.gz: bfeb19f27232509e79a96b1156342365ece7ecec96a66bd56207da48dcaf3db334940aab8d8966fb0028403aa50762b7d989da3618b892b952aa49bc43293825

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 更新记录
 
+## 0.11.0 - 2026-10-17
+
+- 固定协议行分隔符，不再依赖宿主的 `$/`：并发 SSH 主机密钥冲突仍会拒绝，脚本、PAN-OS 配置、TFTP/保存证据及日志按设备行解析；标准输入凭据和隐藏密码只消费当前一行。
+- 传输事件在构造时保存不可变的二进制快照，自定义传输复用缓冲区不再覆盖已接收分片或超时证据；PTY 将字节规范化集中到事件边界，避免重复转换。自定义传输应为每次读取创建新事件，不能再修改已构造事件的字段。
+- 结果汇总在拼接前统一为原始字节，混合 UTF-8、二进制及其他编码的已完成步骤不再触发编码冲突；单条结果省去中间数组与拼接，返回值仍是独立、可修改的二进制字符串。
+- 命令回执在构造时校验命令、输出、提示及有限非负耗时，避免非法对象进入已完成步骤后才在汇总或诊断时失败。
+- 自定义对话提前校验错误匹配与交互列表，复制并冻结自身规则，不再冻结调用方数组；无效规则在会话开始前报告。
+- 字节、诊断、SSH 信任文件及终端进度拼接使用显式空分隔符，避免宿主设置 Ruby 的 `$,` 后将额外字符插入响应、错误证据或文件。
+
+## 0.10.3 - 2026-10-16
+
+- 保护会话锁取得、登记和释放的异步取消边界，完整操作、单次执行和关闭共用持锁作用域；业务等待仍可取消，非局部退出仍释放锁。
+- 工作线程提前退出或被终止时，线程池报告未完成任务并回收其余线程，避免返回貌似成功的空结果；跨作用域重新交付异常保留原始原因链，不附加调用方已处理的无关异常。
+- 修复 UTF-8 命令诊断混用字符与字节偏移导致截断或异常的问题，保留二进制输出及终端重绘前的错误证据。
+- 固定策略快照的相对路径基准，后续目录变化和策略覆盖不再改变同批目录与信任文件；活设置及设备凭据仍动态读取。
+- 拒绝规范化后指向不同连接器的地址或厂商覆盖，以及规范化为空的必需厂商标签；IP 地址校验异常不再携带原始输入。
+- 终端逐行输出改用 Ruby 原生行尾裁剪，减少正则扫描和临时对象，保留控制序列、UTF-8 校验及行长度限额。
+
 ## 0.10.2 - 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/netdisco.md

@@ -181,8 +181,12 @@ HTTP counts actual chunks and closes on excess. Injected `requester:` callbacks
 
 `Settings#snapshot(mode:)` freezes public policy before side effects. CLI planning and execution share it; later calls can read new settings. Credentials remain dynamic per task. `Settings.new.for_run(mode: :backup)` shares policy across API calls; non-sensitive overrides preserve an existing snapshot. A custom `credentials:` resolver can supply per-device connection options, taking precedence over defaults. Injected clients remain caller-owned.
 
+Snapshot backup, cache, log, TFTP verification, SSH known-hosts and explicit PostgreSQL CA certificate paths resolve against the working directory captured when the snapshot is created, including default paths and later relative overrides. Paths beginning with `~/` and the path `~` use the home directory captured by that snapshot. PostgreSQL CA paths retain libpq's literal path semantics without tilde expansion; `sslrootcert: system` keeps its system trust-store meaning, while `./system` names a file. Live settings continue to resolve paths against the current working directory and home directory.
+
 Explicit host mappings, device rules, and vendor overrides take precedence over automatic detection. Comware plus a branded H3C model can correct stale vendor labels; H3C WX/AC models select the wireless connector.
 
+Host and vendor overrides reject normalized aliases that select different connectors; aliases selecting the same connector can coexist. Required vendor labels must remain nonempty after normalization. Invalid rules fail before device connections begin.
+
 ## TFTP history and verification
 
 Direct upload receipts only establish `device_reported`. Fleet can verify a local/mounted TFTP directory via `verification_root:`; the CLI accepts `--tftp-root DIR` or YAML `tftp.verification_root`. A verified receipt requires a current, nonempty regular file matching the actual receipt path, with SHA-256 evidence. Missing evidence prevents `verified` success. A mismatched receipt path is retained as device evidence, but cannot be verified or archived without a baseline for that locked target.

data/docs/netdisco.zh-CN.md

@@ -179,6 +179,10 @@ ssh:
 
 每台任务开始时仍读取设备凭据，`Settings.from_file` 也保留轮换能力。纯策略快照不保存密码、API key 或凭据解析器。需要让多次 API 调用共用策略时，可传 `Settings.new.for_run(mode: :backup)`。自定义 `credentials:` 解析器仍可逐设备返回连接设置，它显式给出的选项优先于批次默认值，由调用方负责一致性；注入的 `client:` 生命周期也由调用方管理。传入 `plan:` 的执行不会重新拉取或筛选已批准清单。`fleet.devices` 可在不连接设备时检查映射。
 
+快照中的备份、缓存、日志、TFTP 核验目录、SSH known-hosts 路径及显式 PostgreSQL CA 证书路径，以创建快照时的工作目录为基准，默认路径和后续相对路径覆盖也沿用这一基准。`~/` 开头的路径及 `~` 使用快照创建时的主目录。PostgreSQL CA 路径保留 libpq 的字面路径语义，不展开波浪号；`sslrootcert: system` 仍表示系统信任库，`./system` 则表示文件。未固定的活设置仍按调用时的当前工作目录和主目录解析路径。
+
+地址和厂商覆盖规则规范化后，同一键不能指向不同连接器；指向同一连接器的别名可以并存。必需的厂商标签规范化后也不能为空。非法规则在连接设备前拒绝。
+
 ## 批量示例与进度
 
 `examples/backup.rb` 和 `examples/backup_tftp.rb` 默认全量备份符合筛选条件的设备，并在终端原地刷新两行进度（登录、采集、排队、成功和未完成数，以及耗时、平均吞吐、预计剩余时间）；失败单独输出，结束后显示汇总和报告路径。重定向时每 25 台输出一次进度，避免刷屏。`--verbose` 显示逐条登录和命令事件，`--json` 才在 STDOUT 输出 JSON；完整计划和结果始终保存在批次目录。`--no-progress` 关闭人类进度。百分比表示任务完成比例，不是成功率。

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/background_task.rb

@@ -32,7 +32,7 @@ module Net
           end
           # break 和非局部 return 也会展开作用域；异常交付必须在 ensure 内，不能绕过。
           failure ||= completion.pop unless completion.empty?
-          raise failure if failure
+          raise failure, cause: failure.cause if failure
         end
         value
       end

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

@@ -67,7 +67,7 @@ module Net
           device.connect
           yield device
         end
-        raise failure if failure
+        raise failure, cause: failure.cause if failure
 
         value
       end

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/device_session.rb

@@ -33,7 +33,7 @@ module Net
             failure ||= error
           end
           # break 和非局部 return 跳过尾部返回值；收尾故障必须在展开作用域时交付。
-          raise failure if failure && (!completed || !failure.is_a?(StandardError))
+          raise failure, cause: failure.cause if failure && (!completed || !failure.is_a?(StandardError))
         end
 
         [value, failure]

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
@@ -95,8 +113,8 @@ module Net
 
         start = match.begin(0).positive? ? output.rindex(/[\r\n]/, match.begin(0) - 1) : nil
         start = start ? start + 1 : 0
-        finish = output.index(/[\r\n]/, match.end(0)) || output.bytesize
-        output.byteslice(start, finish - start).strip
+        finish = output.index(/[\r\n]/, match.end(0)) || output.length
+        output[start...finish].strip
       end
     end
 

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/session.rb

@@ -67,25 +67,13 @@ module Net
         if @operation_owner == [Thread.current, Fiber.current] && !@performing
           return perform_locked(phase, &)
         end
-        unless @lock.try_lock
-          raise build_error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
-        end
-
-        begin
-          perform_locked(phase, &)
-        ensure
-          @lock.unlock
-        end
+        with_session_lock(phase) { perform_locked(phase, &) }
       end
 
       # 业务操作在多次脚本之间持有租约；只有同一线程和 Fiber 可顺序使用。
       def with_operation(phase)
-        unless @lock.try_lock
-          raise build_error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
-        end
-        @operation_owner = [Thread.current, Fiber.current]
-        result = nil
-        begin
+        with_session_lock(phase, operation: true) do
+          result = nil
           @log.with_operation_context(phase) { result = yield }
         rescue Error => error
           raise unless result.is_a?(Result)
@@ -93,9 +81,6 @@ module Net
           # 日志收尾失败不能抹去已完成的设备步骤，也不能覆盖原业务错误。
           Result.new(steps: result.steps, config: result.config,
                      error: result.error || normalize_error(error, phase: phase))
-        ensure
-          @operation_owner = nil
-          @lock.unlock
         end
       end
 
@@ -108,15 +93,7 @@ module Net
 
       # 独占关闭会话；已有操作占用时返回会话繁忙错误。
       def close
-        unless @lock.try_lock
-          raise build_error(SessionBusy, "cannot close a session owned by another operation", phase: :close), cause: nil
-        end
-
-        begin
-          close_resources
-        ensure
-          @lock.unlock
-        end
+        with_session_lock(:close, busy_message: "cannot close a session owned by another operation") { close_resources }
       end
 
       # 执行特权认证，并更新提示符及特权状态。
@@ -234,11 +211,44 @@ module Net
 
       private
 
+      # 锁取得与所有权登记不可拆开；只在交接及释放窗口延迟取消，业务等待仍可中断。
+      def with_session_lock(phase, operation: false, busy_message: "session already belongs to another operation")
+        acquired = false
+        failure = nil
+        begin
+          Thread.handle_interrupt(Exception => :never) do
+            acquired = @lock.try_lock
+            @operation_owner = [Thread.current, Fiber.current] if acquired && operation
+          end
+          unless acquired
+            raise build_error(SessionBusy, busy_message, phase: phase), cause: nil
+          end
+
+          yield
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 解锁期间的二次取消不能覆盖原业务故障。
+          failure = error
+          raise
+        ensure
+          if acquired
+            begin
+              Thread.handle_interrupt(Exception => :never) do
+                @operation_owner = nil if operation
+                @lock.unlock
+              end
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 完成释放后再交付取消，并避免原故障形成 cause 环。
+              error = failure || error
+              raise error, cause: error.cause
+            end
+          end
+        end
+      end
+
       # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
       def perform_locked(phase)
-        @performing = true
         completed = false
+        failure = nil
         begin
+          @performing = true
           unless connected?
             close_resources unless state == :closed
             connect_session
@@ -251,15 +261,34 @@ module Net
           failure = normalize_error(error, phase: phase)
           close_preserving_failure
           raise failure, cause: nil
-        rescue Exception # rubocop:disable Lint/RescueException -- 中断先释放传输资源，再继续向外传播。
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 中断先释放传输资源，再继续向外传播。
+          failure = error
           close_preserving_failure
           raise
         ensure
+          finish_perform(completed, failure)
+        end
+      end
+
+      # 资源查询和关闭仍可取消；不论它们如何退出，都先清除执行标记再交付首个故障。
+      def finish_perform(completed, failure)
+        begin
           # throw/catch 也会离开此块；对话未完成时必须关闭连接，不能把
           # 半途的设备提示符误当成下一条命令的响应。
           close_preserving_failure unless completed || !connected?
-          @state = :ready if connected?
-          @performing = false
+          connected = connected?
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 收尾取消不能覆盖已记录的操作故障。
+          failure ||= error
+        ensure
+          begin
+            Thread.handle_interrupt(Exception => :never) do
+              @state = :ready if connected
+              @performing = false
+            end
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 状态登记完成后才交付二次取消。
+            failure ||= error
+          end
+          raise failure, cause: failure.cause if failure
         end
       end
 

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

@@ -164,7 +164,8 @@ module Net
 
       # 删除行尾空白，写出当前行并重置光标。
       def emit_line(newline:)
-        @target.write(utf8_safe(@line.sub(/[ \t]+\z/n, "")))
+        # 其他 ASCII 空白控制字节已由 consume_control 消费，缓冲区只需裁剪空格和制表符。
+        @target.write(utf8_safe(@line.rstrip))
         @target.write("\n") if newline
         @line.clear
         @cursor = 0
@@ -176,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/execution_pool.rb

@@ -52,6 +52,7 @@ module Net
             Thread.handle_interrupt(Exception => :never) do
               threads << Thread.new do
                 failure = nil
+                exhausted = false
                 begin
                   # 全部线程成功建立后才允许设备操作，创建失败不能留下已发送的变更。
                   Thread.handle_interrupt(Exception => :immediate) do
@@ -60,10 +61,13 @@ module Net
                       index, item = task
                       results[index] = yield item
                     end
+                    exhausted = true
                   end
                 rescue Exception => error # rubocop:disable Lint/RescueException -- 将中断同步交给调用线程，避免全局 abort_on_exception 波及其他线程。
                   failure = error
                 ensure
+                  # Thread.exit/kill 不经过 rescue；不能把尚未完成的任务伪装成合法 nil 结果。
+                  failure ||= RuntimeError.new("execution worker stopped before completing its tasks") unless exhausted
                   finished << [Thread.current, failure]
                 end
               end
@@ -73,7 +77,7 @@ module Net
           count.times do
             thread, failure = finished.pop
             thread.join
-            raise failure if failure
+            raise failure, cause: failure.cause if failure
           end
           completed = true
         rescue Exception => error # rubocop:disable Lint/RescueException -- 记录取消或原任务故障，收尾中再次取消不能覆盖它。
@@ -102,7 +106,8 @@ module Net
         end
       rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复交付时保留原故障，二次取消不改变批次失败原因。
         # 二次取消可能已以原故障为 cause；不能反向关联形成异常原因环。
-        raise primary_failure || error, cause: nil
+        error = primary_failure || error
+        raise error, cause: error.cause
       end
     end
   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/netdisco/rules.rb

@@ -39,15 +39,20 @@ module Net
           unless vendor_overrides.is_a?(Hash)
             raise ArgumentError, "vendor_overrides must be a Hash"
           end
-          vendor_overrides.to_h do |label, vendor|
+          vendor_overrides.each_with_object({}) do |(label, vendor), mapping|
             unless label.is_a?(String) && vendor.is_a?(String) && !label.empty?
               raise ArgumentError, "vendor_overrides must map labels to connector names"
             end
             key = normalize(label)
+            raise ArgumentError, "vendor_overrides labels must remain nonempty after normalization" if key.empty?
+
             value = vendor.to_sym
             raise ArgumentError, "vendor_overrides contains an unsupported connector" unless Net::Connector.vendors.include?(value)
+            if mapping.key?(key) && mapping[key] != value
+              raise ArgumentError, "vendor_overrides contains conflicting normalized labels"
+            end
 
-            [key, value]
+            mapping[key] = value
           end.freeze
         end
 
@@ -55,19 +60,22 @@ module Net
         def host_mapping(host_overrides)
           raise ArgumentError, "host_overrides must be a Hash" unless host_overrides.is_a?(Hash)
 
-          host_overrides.to_h do |host, vendor|
+          host_overrides.each_with_object({}) do |(host, vendor), mapping|
             unless host.is_a?(String) && !host.include?("/") && vendor.is_a?(String)
               raise ArgumentError, "host_overrides must map IP addresses to connector names"
             end
             begin
               address = IPAddr.new(host).to_s
             rescue IPAddr::Error
-              raise ArgumentError, "host_overrides contains an invalid IP address"
+              raise ArgumentError, "host_overrides contains an invalid IP address", cause: nil
             end
             connector = vendor.to_sym
             raise ArgumentError, "host_overrides contains an unsupported connector" unless Net::Connector.vendors.include?(connector)
+            if mapping.key?(address) && mapping[address] != connector
+              raise ArgumentError, "host_overrides contains conflicting normalized IP addresses"
+            end
 
-            [address, connector]
+            mapping[address] = connector
           end.freeze
         end
 
@@ -84,8 +92,10 @@ module Net
             end
             connector = rule.fetch("connector").to_sym
             raise ArgumentError, "mapping contains an unsupported connector" unless Net::Connector.vendors.include?(connector)
+            vendor = normalize(rule.fetch("vendor"))
+            raise ArgumentError, "mapping vendor must remain nonempty after normalization" if vendor.empty?
 
-            { vendor: normalize(rule.fetch("vendor")), os: rule["os"] && normalize(rule["os"]),
+            { vendor: vendor, os: rule["os"] && normalize(rule["os"]),
               model_prefix: rule["model_prefix"] && normalize(rule["model_prefix"]), connector: connector }.freeze
           end.freeze
         end
@@ -153,7 +163,7 @@ module Net
 
             [IPAddr.new(value).to_s.freeze, true]
           rescue IPAddr::Error
-            raise ArgumentError, "host list entries must be IP addresses"
+            raise ArgumentError, "host list entries must be IP addresses", cause: nil
           end.freeze
         end
 

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

@@ -37,9 +37,11 @@ module Net
         end
 
         # 分开保存默认策略、显式覆盖与凭据来源；fixed 实例只承载已复制的公开快照。
-        def initialize(env: ENV, defaults: {}, overrides: {}, policy: nil, fixed: false)
+        def initialize(env: ENV, defaults: {}, overrides: {}, policy: nil, fixed: false, path_context: nil)
           @env, @defaults, @overrides = env, defaults, overrides
           @policy, @fixed = policy, fixed
+          # 路径上下文只在内部固定策略之间传递，不属于用户配置或凭据来源。
+          @path_context = (path_context || [Dir.pwd, Dir.home]).map { |path| path.dup.freeze }.freeze if fixed
         end
 
         # 调用入口补充运行目录等非敏感覆盖，凭据仍从同一来源读取。
@@ -47,7 +49,7 @@ module Net
           if @fixed
             public_values = @env.merge(@overrides).merge(values).slice(*non_secret_keys)
                                 .transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
-            return self.class.new(env: public_values, fixed: true).freeze
+            return self.class.new(env: public_values, fixed: true, path_context: @path_context).freeze
           end
 
           policy = @policy.with_overrides(values) if @policy
@@ -150,7 +152,7 @@ module Net
           unless directory.is_a?(String) && !directory.empty? && !directory.include?("\0")
             raise ArgumentError, "netdisco.cache_directory must be a nonempty path without NUL"
           end
-          { directory: File.expand_path(directory), ttl: number("ND_CACHE_TTL", InventoryCache::DEFAULT_TTL),
+          { directory: absolute_path(directory), ttl: number("ND_CACHE_TTL", InventoryCache::DEFAULT_TTL),
             enabled: boolean("ND_CACHE_ENABLED", true) }.freeze
         end
 
@@ -169,7 +171,7 @@ module Net
           path = raw("NC_BACKUP_DIRECTORY", DEFAULT_BACKUP_DIRECTORY)
           raise ArgumentError, "NC_BACKUP_DIRECTORY must be nonempty" unless present?(path)
 
-          File.expand_path(path)
+          absolute_path(path)
         end
 
         # 与 Worker 共用并发上限，非法值在任务与目录创建前失败。
@@ -226,11 +228,13 @@ module Net
         # 本机核验根目录属于策略快照，解析路径不证明文件已经上传。
         def tftp_root
           path = value("NC_TFTP_ROOT")
-          File.expand_path(path) if path
+          absolute_path(path) if path
         end
 
         # 端口、TLS 与连接超时进入固定策略；主机、数据库名和登录凭据仍从环境读取。
         def database_options
+          return @policy.database_options if @policy
+
           options = {}
           %i[port connect_timeout].each do |name|
             key = "ND_DB_#{name.to_s.upcase}"
@@ -242,14 +246,20 @@ module Net
             item = value("ND_DB_#{name.to_s.upcase}")
             options[name] = item if item
           end
-          DatabaseClient.connection_policy(**options)
+          options = DatabaseClient.connection_policy(**options)
+          # libpq 的 system 是系统信任库标记；其他显式路径按字面解析，不展开波浪号。
+          if @fixed && options[:sslrootcert] && options[:sslrootcert] != "system"
+            options = options.merge(sslrootcert: File.absolute_path(options[:sslrootcert], @path_context.first).freeze).freeze
+          end
+          options
         end
 
         # 经 Configuration 复用连接校验；厂商协议覆盖通用协议，不包含设备凭据。
         def connection_options(vendor = nil)
+          known_hosts = value("NC_KNOWN_HOSTS")
           configuration = Configuration.new(
             protocol: vendor_protocols[vendor.to_s] || value("NC_PROTOCOL") || "ssh",
-            log_level: value("NC_LOG_LEVEL") || "info", known_hosts: value("NC_KNOWN_HOSTS"),
+            log_level: value("NC_LOG_LEVEL") || "info", known_hosts: known_hosts && absolute_path(known_hosts),
             host_key_policy: value("NC_HOST_KEY_POLICY") || "strict",
             max_script_output_bytes: optional_integer("NC_MAX_SCRIPT_OUTPUT_BYTES")
           )
@@ -281,7 +291,7 @@ module Net
         # 会话日志目录属于公开策略；调用方和批次入口负责实际创建。
         def log_directory
           path = value("NC_LOG_DIRECTORY")
-          File.expand_path(path) if path
+          absolute_path(path) if path
         end
 
         # 生成已验证的无凭据配置摘要，不展开原环境或 resolver。
@@ -326,6 +336,20 @@ module Net
           @defaults.fetch(key, default)
         end
 
+        # 固定策略及其覆盖共用快照的工作目录和主目录；活设置仍按调用时的环境解析。
+        def absolute_path(path)
+          return @policy.absolute_path(path) if @policy
+          return File.expand_path(path) unless @fixed
+
+          if path == "~" || path.start_with?("~/")
+            home = @path_context.last
+            raise ArgumentError, "non-absolute home" unless home.start_with?(File::SEPARATOR)
+
+            path = home + path.delete_prefix("~")
+          end
+          File.expand_path(path, @path_context.first)
+        end
+
         private
 
         # 身份指纹只用于隔离缓存；凭据、SQL 和参数均不写入缓存文件或摘要。

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.2"
+    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.2
+  version: 0.11.0
 platform: ruby
 authors:
 - net-connector contributors