net-connector 0.10.1 → 0.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9891d74f563f6d1383bf3a5a41e1eeb51e607b1395ec4794a42ed45027ce3c34
-  data.tar.gz: 950f56fcf3428c4a9a33c2176768f5cab3bdb4f19e649dd6f8e89547810dcea7
+  metadata.gz: 641ad063dfd167ac9a8c45508bda6e759ebbfd0ec4cf62b86d3ca301ef165b8f
+  data.tar.gz: 588bc23e9ee7154a45baa07ebbcf0688c32926acc035bf881fa01a64cb999ec3
 SHA512:
-  metadata.gz: a785501bd50b61f542b9222ae24597025a20d3aa1d10fd2a042d20a7653f5fbe8ec2f6ccaf3ab6ea34db0cd11553fb918a836c34fd21dda9b4cb8b0dec83ed81
-  data.tar.gz: 5e1ef923eb2d603595d6225ed7cb6f08c36dbfc12c760d5b9aa69c94bbf812ef7a288586a48ff1b75947fc4886eb7dfbf830a5038bda2bfd6a43205aca18848e
+  metadata.gz: b5a701fc703b5015609082220e370fcc1837110c511be0b6094abaf37d3a88b2cb1206f807c9ce9c5733fdc7e7c49a1bba33a4788ff08d3f0207d855569bc249
+  data.tar.gz: 95c55b593e14974041b216da1160df02ba0770c0ddb8b71a2a2bd0d103245f93ac84555ac7ce0238b63d678be252f6592b0f839842dbc39bc78782a2a17d7452

data/CHANGELOG.md

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

data/docs/architecture.md

@@ -73,6 +73,8 @@ Fleet 在规范目标校验、凭据解析及连接器构造之前加同一把
 
 提交后的 `BackupPersistenceError` 只携带原 `Backup` 元数据和受控写入回执，Fleet 保留产物并使用已有 saved_with_error 分类。只接受库定义的具体完成错误及匹配产物类型，第三方异常的 backup 属性或自定义 WriteError 子类不作为完成证据。报告保留已提交位置，导出错误说明 committed；设备命令不会自动重放。
 
+直接备份在路径锁退出前保存完成元数据，锁关闭的普通故障转换为 `BackupFinalizeError`，其中 `backup` 保留结果，`underlying_type` 经过类型白名单。该错误只确认备份操作已完成，不制造文件同步回执；未变文件的历史持久性仍未补验。Fleet 的外层路径锁及 TFTP 归档锁同样保存最新结果，退出故障转为 saved_with_error 或 reported_with_error，已有设备诊断优先，中断继续传播。
+
 TFTP 归档分别保留本地批次副本与服务器归档副本的提交位置；写入器的原生回执必须与本次目标路径一致。目录同步或收尾失败仍保留已提交路径，成功上传转为 `reported_with_error`，诊断记录归档失败及持久化阶段；设备任务此前已有错误时保留原诊断。报告失败后的 JSON 补写同样保留已提交位置，不覆盖首次报告故障，也不重新执行设备任务。
 
 TFTP 只确认设备报告的上传结果：策略去掉命令、应答和提示符回显后，检查明确的完成行；文件名或表示“即将上传”的进度文字不算成功。原始输出或终端渲染文本中的失败证据优先于成功文字。

data/docs/netdisco.md

@@ -57,6 +57,8 @@ The directory must belong to the current user with mode `0700`; cache and lock f
 
 Expired inventory refreshes automatically. A remote inventory failure falls back to validated history without changing its original timestamp. Configuration errors, missing credentials, interruption and unsafe files remain errors. Failed cache writes preserve newly fetched inventory. `fleet.inventory_status` reports `:fresh_cache`, `:refreshed`, `:stale_cache` or `:uncached`, the original `fetched_at`, and safe failure metadata; the CLI warns on history fallback or cache write failure.
 
+An empty or malformed cache file is a cache miss and triggers a remote query. It cannot supply fallback history if that query fails.
+
 Use `net-backup --refresh-inventory`, `fleet.devices(force_refresh: true)`, or `fleet.plan_backup(force_refresh: true)` to bypass freshness. TFTP planning accepts the same keyword. A forced refresh also falls back to valid history if the remote request fails. `cache_enabled: false` disables caching. Injected clients stay uncached unless explicitly wrapped in `Netdisco::InventoryCache`; shared wrapper status describes the latest call, so synchronize concurrent access to the same instance. Cache locks bound waiting and coalesce ordinary expired-cache refreshes across processes; independently requested forced refreshes still query the source.
 
 ## CLI planning and execution
@@ -179,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.
@@ -189,6 +195,8 @@ Verification holds a target lock across the pre-upload file-state/time baseline,
 
 Batch examples enable history preservation. With an accessible server directory, uploads use hostname/IP names and are retained in both `<batch>/tftp/` and server `archive/<batch>/`; pre-existing same-name files are archived under `previous/` before upload. File-state and filesystem-time baselines are captured under the upload lock. Verification or archival failure preserves available receipts and committed paths without reporting success.
 
+Path-lock cleanup failures after a completed local backup or TFTP archive retain the saved paths as `:saved_with_error` or `:reported_with_error`. An earlier device error remains the primary diagnostic; callbacks receive the retained outcome and commands are not replayed.
+
 Without a server directory, batch examples add a batch identifier to names, retain `device_reported`, and cannot save local configuration copies. PAN-OS uses the fixed `running-config.xml` name, so the history-preserving example refuses its upload without local server access. Plans still prevent same-batch filename collisions.
 
 Reports distinguish `verification`, `server_file_verified`, `local_file`, `server_archive_file`, `bytes`, and `sha256`. TFTP has no configuration `change` notification.

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` 关闭人类进度。百分比表示任务完成比例，不是成功率。
@@ -250,6 +254,8 @@ TFTP 的 `verification` 汇总与设备条目的 `server_file_verified` 区分
 
 提供 `verification_root:` 时，即使不保留历史，TFTP 核验也在目标锁内采集上传前文件状态与文件系统时间、执行上传并检查指纹。未变化的旧文件不能凭未来时间戳获得服务器核验；服务器目录须可写以建立锁和时间探针。结果回调与最终报告采用核验后的结果，文件证据不覆盖设备操作或关闭故障。回执路径与锁定目标不一致时保留设备证据，但缺少该路径的上传前基线，不核验或归档旧文件。
 
+本地备份或 TFTP 归档完成后若路径锁收尾失败，结果以 `:saved_with_error` 或 `:reported_with_error` 保留已保存路径。已有设备错误仍作为首个诊断，回调收到保留回执的结果，命令不自动重放。
+
 ## 清单缓存
 
 HTTP 和 PostgreSQL 默认启用本地清单缓存，有效期三天（259200 秒），目录为当前工作目录下的 `.cache/net-connector/inventory`。YAML `netdisco.cache_directory`、`cache_ttl` 和 `cache_enabled` 分别控制目录、秒数和是否启用；TTL 须为有限正数，设置 `cache_enabled: false` 关闭缓存。
@@ -260,6 +266,8 @@ HTTP 和 PostgreSQL 默认启用本地清单缓存，有效期三天（259200
 
 过期后自动刷新；远端请求失败时回退已验证历史，不更新原获取时间。配置错误、缺少凭据、中断和不安全文件不会被回退掩盖。缓存写入失败仍交付刚取得的新清单。`fleet.inventory_status` 提供 `:fresh_cache`、`:refreshed`、`:stale_cache`、`:uncached`、原始 `fetched_at` 和安全故障字段，CLI 对历史回退和缓存写入失败单独提示。
 
+空文件或格式损坏的缓存按未命中处理，重新查询远端；查询失败时，这类文件不能作为回退历史。
+
 强刷使用 `net-backup --refresh-inventory`、`fleet.devices(force_refresh: true)`、`fleet.plan_backup(force_refresh: true)`；TFTP 规划也支持此参数。强刷失败同样回退已验证历史。直接注入客户端时不自动缓存，可显式包裹 `Netdisco::InventoryCache`。一个包装器的状态描述最近调用，并发共享实例须由调用方同步。有界跨进程锁合并普通过期刷新，独立强刷请求各自访问远端。
 
 ## 配置批次与接口修正

data/docs/usage.md

@@ -39,6 +39,8 @@ Create and protect the parent directory first. `open` closes the session on retu
 
 Writes use mode `0600`, file synchronization, atomic replacement, and parent-directory synchronization. A collection failure leaves the old file intact. Failure after replacement raises `BackupPersistenceError`; `error.backup` retains metadata and `error.receipt` distinguishes `:committed` from `:durable`. Unsupported directory synchronization is reported as `:backup_durability_unsupported`. Do not repeat the device operation to recover file finalization.
 
+If path-lock cleanup fails after backup completes, `BackupFinalizeError` retains `error.backup` and a safe `error.underlying_type`. Its code is `:backup_finalize_failed`; it does not claim a new durability check for an unchanged file. Interruptions still propagate.
+
 Private `.net-connector-<digest>.lock` files remain in the directory. All writers must follow the same locking protocol; ancestor directories remain the caller's responsibility.
 
 For an in-memory configuration, use `device.running_config.value!`. The `Result` retains completed steps on failure. Collection suppresses configuration content in logs and error diagnostics, including debug/raw and application loggers; returned output and backup files remain sensitive.

data/docs/usage.zh-CN.md

@@ -43,6 +43,8 @@ end
 
 写入使用 `0600` 临时文件、文件同步、原子替换及父目录同步。替换后同步或收尾失败会抛出 `BackupPersistenceError`，`error.backup` 保留已写文件的元数据，`error.receipt` 区分 `:committed`（持久性未确认）和 `:durable`（同步已完成）。目录同步不受支持对应 `:backup_durability_unsupported`，不会静默报告持久化成功，也不会自动重做设备采集。
 
+备份完成后若路径锁收尾失败，`BackupFinalizeError` 保留 `error.backup` 和安全的 `error.underlying_type`，错误码为 `:backup_finalize_failed`；内容未变时不会声称重新验证过文件持久性，中断仍向调用方传播。
+
 调用方应创建并保护备份目录，运行配置可能含有设备凭据。同目录下的 `.net-connector-<摘要>.lock` 是私有的长期锁文件，正常释放不删除它。所有写入者须使用本库的锁协议；`NOFOLLOW` 不保护被外部替换的祖先目录。锁名保守合并大小写及 Unicode 等价写法，实际备份文件名不变；在区分大小写的文件系统上，这些名称也会串行。
 
 ## 设备发起的 TFTP 备份

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

@@ -39,6 +39,19 @@ module Net
       end
     end
 
+    # 备份已完成后的路径锁收尾错误；不把未变文件冒充本次完成 fsync 的写入回执。
+    class BackupFinalizeError < Error
+      attr_reader :backup, :underlying_type
+
+      def initialize(backup:, underlying:, host: nil)
+        raise ArgumentError, "backup must be a completed Backup" unless backup.instance_of?(Backup)
+
+        @backup = backup
+        @underlying_type = ErrorMetadata.type(underlying.class.name) || "StandardError"
+        super("backup completed; path lock finalization failed", code: :backup_finalize_failed, host: host, phase: :backup)
+      end
+    end
+
     # 先取得路径锁再采集和原子写入；提交后的收尾错误仍保留备份元数据。
     class LocalBackup
       # 设备入口与功能实现共置，Base 只组合能力，不重复业务流程。
@@ -56,8 +69,13 @@ module Net
 
       # 采集配置、识别变更并原子写入私有文件。
       def call(path:, lock_timeout: 0)
+        backup = nil
         host = @device.host if @device.respond_to?(:host)
-        Storage::BackupLock.synchronize(path, timeout: lock_timeout, host: host) { |lock| collect_and_write(lock.path) }
+        Storage::BackupLock.synchronize(path, timeout: lock_timeout, host: host) { |lock| backup = collect_and_write(lock.path) }
+      rescue StandardError => error
+        raise unless backup
+
+        raise BackupFinalizeError.new(backup: backup, underlying: error, host: host), cause: nil
       end
 
       private

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

@@ -7,7 +7,7 @@ module Net
       CONNECTOR_TYPES = %w[Error ConnectionError AuthenticationError LoginTimeout CommandTimeout WriteTimeout
                            PromptError ConnectionClosed TransportError DeviceError ScriptError InternalError
                            OutputLimitExceeded ScriptOutputLimitExceeded SessionBusy UnsupportedOperation LogError ParsingError BackupBusy
-                           BackupPersistenceError TftpCompletionError].freeze
+                           BackupPersistenceError BackupFinalizeError TftpCompletionError].freeze
       TYPES = (CONNECTOR_TYPES.map { |name| "Net::Connector::#{name}" } +
         %w[StandardError RuntimeError ArgumentError TypeError IOError EOFError SystemCallError ThreadError
            RangeError KeyError IndexError NoMethodError NameError FrozenError NotImplementedError

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

@@ -52,6 +52,8 @@ module Net
           if error.instance_of?(BackupPersistenceError) && backup.instance_of?(Backup) && error.backup.equal?(backup)
             { artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,
               underlying_type: error.underlying_type }
+          elsif error.instance_of?(BackupFinalizeError) && backup.instance_of?(Backup) && error.backup.equal?(backup)
+            { artifact_phase: :finalize, underlying_type: error.underlying_type }
           elsif error.instance_of?(TftpCompletionError) && backup.instance_of?(TftpReceipt) && error.receipt.equal?(backup)
             { artifact_state: :reported_uploaded, artifact_phase: error.code == :transfer_finalize_failed ? :finalize : :path,
               verification: :device_reported, underlying_type: error.underlying_type }

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

@@ -246,14 +246,20 @@ module Net
 
         # 执行单台设备的本地配置采集。
         def backup_device(device, directory, log_directory, settings_snapshot, filename_style: :ip)
+          outcome = nil
           destination = File.join(directory, device.backup_filename(style: filename_style))
           Storage::BackupLock.synchronize(destination, host: device.host) do |path_lock|
             Storage::SafeFile.open(destination, missing: true) { |_file, _stat| nil }
-            run_device(device, log_directory, settings_snapshot, success_status: :backed_up,
-                       partial_status: :saved_with_error, backup_class: Backup) do |connector|
+            outcome = run_device(device, log_directory, settings_snapshot, success_status: :backed_up,
+                                 partial_status: :saved_with_error, backup_class: Backup) do |connector|
               path_lock.with_delegated_lock { connector.backup(path: destination) }
             end
           end
+        rescue StandardError => error
+          raise unless outcome
+          return outcome unless outcome.success?
+
+          build_outcome(device, :saved_with_error, backup: outcome.backup, error: error)
         end
 
         # 隔离单台设备的凭据、连接、操作和关闭异常。
@@ -290,7 +296,8 @@ module Net
             result
           end
           if failure && backup.nil?
-            if backup_class == Backup && failure.instance_of?(BackupPersistenceError) && failure.backup.instance_of?(Backup)
+            if backup_class == Backup && [BackupPersistenceError, BackupFinalizeError].any? { |type| failure.instance_of?(type) } &&
+               failure.backup.instance_of?(Backup)
               backup = failure.backup
             elsif backup_class == TftpReceipt && failure.instance_of?(TftpCompletionError) && failure.receipt.instance_of?(TftpReceipt)
               backup = failure.receipt

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

@@ -111,7 +111,7 @@ module Net
             return nil if stat.size > @max_inventory_bytes
 
             body = file.read(@max_inventory_bytes + 1)
-            return nil if body.bytesize > @max_inventory_bytes
+            return nil if body.nil? || body.bytesize > @max_inventory_bytes
 
             entry = JSON.parse(body)
             unless entry.is_a?(Hash) && entry.keys.sort == %w[fetched_at identity rows schema] &&
@@ -161,15 +161,21 @@ module Net
 
           bytes = 0
           rows.map do |row|
-            unless row.is_a?(Hash) && row["ip"].is_a?(String) && !row["ip"].strip.empty? &&
-                   Client::FIELDS.all? { |field| row[field].nil? || row[field].is_a?(String) }
+            unless row.is_a?(Hash) && row["ip"].is_a?(String) && !row["ip"].strip.empty?
               raise InvalidCache
             end
-            selected = row.slice(*Client::FIELDS)
-            bytes += selected.sum { |key, value| key.bytesize + (value&.bytesize || 0) }
-            raise InvalidCache if bytes > @max_inventory_bytes
+            # 一次遍历完成白名单、限额与复制，避免中间 Hash 和逐字段求和产生的数组。
+            Client::FIELDS.each_with_object({}) do |field, selected|
+              next unless row.key?(field)
 
-            selected.transform_values { |value| value&.dup&.freeze }.freeze
+              value = row[field]
+              raise InvalidCache unless value.nil? || value.is_a?(String)
+
+              bytes += field.bytesize + (value&.bytesize || 0)
+              raise InvalidCache if bytes > @max_inventory_bytes
+
+              selected[field] = value&.dup&.freeze
+            end.freeze
           end.freeze
         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/netdisco/tftp_archive.rb

@@ -55,6 +55,7 @@ module Net
 
         # 上传与归档在同一目标锁内完成，后续失败仍保留可确认的上传回执和提交路径。
         def upload_and_archive(device, started_at:)
+          outcome = nil
           raise Unavailable.new(host: device.host) if device.vendor == :palo_alto && !@server_root
 
           remote_filename = upload_filename(device)
@@ -66,14 +67,22 @@ module Net
             upload_started_at = server_timestamp
             outcome = yield remote_filename
             receipt = outcome.backup
-            return outcome unless receipt.is_a?(TftpReceipt) && receipt.path
+            next outcome unless receipt.is_a?(TftpReceipt) && receipt.path
 
             verified = @verifier.verify_outcome(outcome.with(started_at: started_at), started_at: upload_started_at,
                                                 previous: previous, expected_path: remote_filename)
-            return outcome.success? ? archive_failure(outcome) : outcome unless verified.backup.verification == :server_verified
+            unless verified.backup.verification == :server_verified
+              outcome = outcome.success? ? archive_failure(outcome) : outcome
+              next outcome
+            end
 
-            archive_uploaded_file(verified)
+            outcome = archive_uploaded_file(verified)
           end
+        rescue StandardError => error
+          raise unless outcome
+
+          # 目标锁的关闭发生在块返回之后；保存最新回执，不能丢失已完成的归档路径。
+          outcome.success? ? archive_failure(outcome, persistence_error: error) : outcome
         end
 
         private

data/lib/net/connector/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.10.3
 platform: ruby
 authors:
 - net-connector contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-11 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expect-pty