net-connector 0.10.2 → 0.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f994834e561576d4fafde11f003653a865dd4d35da5a5fd8a7a4c2a016cc2d5
-  data.tar.gz: f7585fe57b094fd687b2de70e34b6b41eb0e46c220d5fc9bfe4357a25c31f6f9
+  metadata.gz: 641ad063dfd167ac9a8c45508bda6e759ebbfd0ec4cf62b86d3ca301ef165b8f
+  data.tar.gz: 588bc23e9ee7154a45baa07ebbcf0688c32926acc035bf881fa01a64cb999ec3
 SHA512:
-  metadata.gz: c862e76e800b3ef6174e8aeadaedd4724dafbd08858954874e6955c0c71a4f21c1f9fd124dfe60e59e5389380330193740cbed6e2c0369ee6f9eaddd0b0d56ce
-  data.tar.gz: 6d62272a65c854987a1d9d73e1cb6aeba177743df828e37ec20595b31e9c42ada27dd787989a9cf1ecc17a3ae7fa1fe46f3c6db992e736ffcb2337c42b081feb
+  metadata.gz: b5a701fc703b5015609082220e370fcc1837110c511be0b6094abaf37d3a88b2cb1206f807c9ce9c5733fdc7e7c49a1bba33a4788ff08d3f0207d855569bc249
+  data.tar.gz: 95c55b593e14974041b216da1160df02ba0770c0ddb8b71a2a2bd0d103245f93ac84555ac7ce0238b63d678be252f6592b0f839842dbc39bc78782a2a17d7452

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 更新记录
 
+## 0.10.3 - 2026-10-16
+
+- 保护会话锁取得、登记和释放的异步取消边界，完整操作、单次执行和关闭共用持锁作用域；业务等待仍可取消，非局部退出仍释放锁。
+- 工作线程提前退出或被终止时，线程池报告未完成任务并回收其余线程，避免返回貌似成功的空结果；跨作用域重新交付异常保留原始原因链，不附加调用方已处理的无关异常。
+- 修复 UTF-8 命令诊断混用字符与字节偏移导致截断或异常的问题，保留二进制输出及终端重绘前的错误证据。
+- 固定策略快照的相对路径基准，后续目录变化和策略覆盖不再改变同批目录与信任文件；活设置及设备凭据仍动态读取。
+- 拒绝规范化后指向不同连接器的地址或厂商覆盖，以及规范化为空的必需厂商标签；IP 地址校验异常不再携带原始输入。
+- 终端逐行输出改用 Ruby 原生行尾裁剪，减少正则扫描和临时对象，保留控制序列、UTF-8 校验及行长度限额。
+
 ## 0.10.2 - 2026-10-16
 
 - 修复空清单缓存文件阻断查询的问题，空文件按缓存未命中处理，远端查询失败仍正常报告。

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/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_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/dialogue.rb

@@ -95,8 +95,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/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

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

@@ -3,6 +3,6 @@
 module Net
   module Connector
     # gemspec、CLI 与发布工具共用此版本，运行时读取不触发设备依赖加载。
-    VERSION = "0.10.2"
+    VERSION = "0.10.3"
   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.10.3
 platform: ruby
 authors:
 - net-connector contributors