net-connector 0.10.0 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6ba09a377ed95488c9ecd62788732557564339638dec3ae596bbce0226369fa
-  data.tar.gz: '0876aa9703bdbb2e46db010fcf263a2e1f1e7549e0f63d1bcf60f8529193e3ed'
+  metadata.gz: 7f994834e561576d4fafde11f003653a865dd4d35da5a5fd8a7a4c2a016cc2d5
+  data.tar.gz: f7585fe57b094fd687b2de70e34b6b41eb0e46c220d5fc9bfe4357a25c31f6f9
 SHA512:
-  metadata.gz: 6636cacf21a401c68a6b6dd596e3c4ab11eb153879e6e6e9f74339cf72bea7f8e71e6937745300fc9e513c7b4521b1eecdb249a1cf3abe7b6c3a15fc253b34a4
-  data.tar.gz: f97ff17b82418d78a1c959f420d4c17a53efc7ce4101694719e394e7d50d42f1ae2e86167a3b470850e598eba9becc42cb6364133fe2e6888eca426342534129
+  metadata.gz: c862e76e800b3ef6174e8aeadaedd4724dafbd08858954874e6955c0c71a4f21c1f9fd124dfe60e59e5389380330193740cbed6e2c0369ee6f9eaddd0b0d56ce
+  data.tar.gz: 6d62272a65c854987a1d9d73e1cb6aeba177743df828e37ec20595b31e9c42ada27dd787989a9cf1ecc17a3ae7fa1fe46f3c6db992e736ffcb2337c42b081feb

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 更新记录
 
+## 0.10.2 - 2026-10-16
+
+- 修复空清单缓存文件阻断查询的问题，空文件按缓存未命中处理，远端查询失败仍正常报告。
+- 减少大清单缓存读取和刷新时的临时对象分配，保留字段白名单、限额和不可变快照。
+- 修复本地备份及 TFTP 归档完成后锁关闭失败导致回执丢失的问题，报告保留已保存路径和原有设备错误，直接备份通过 `BackupFinalizeError#backup` 提供完成元数据。
+
+## 0.10.1 - 2026-10-11
+
+- 设备 `open`、PTY、SSH 信任快照、日志与本地文件统一保护资源交接和关闭边界；异步取消在资源登记或回收后交付，业务等待仍可取消，收尾故障不覆盖首个操作错误。
+- 修复线程回收同时发生二次取消时的循环异常原因，保留原始失败。
+- 配置正文检查提前结束扫描，减少大配置的对象分配和字符串复制，保持原有命令回显与空配置判定。
+
 ## 0.10.0 - 2026-10-11
 
 - 新增 `sync_interface_descriptions`：一次调用、每台设备一个连接，完成邻居发现、描述修改、读回与保存；无变化时不写入或保存，后端仍支持定制格式和分阶段审批。

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 只确认设备报告的上传结果：策略去掉命令、应答和提示符回显后，检查明确的完成行；文件名或表示“即将上传”的进度文字不算成功。原始输出或终端渲染文本中的失败证据优先于成功文字。
@@ -299,6 +301,8 @@ TFTP 策略必须实现 `validate_options!(target, source_file:, vrf:)`、`recei
 
 ## 加载入口与厂商策略
 
+公开设备 `open` 与批量任务共用 `DeviceSession` 的关闭边界。PTY、SSH 信任快照、日志及本地文件在取得资源与登记所有权之间延后异步取消，关闭时保护回收过程；设备命令、文件读取和锁竞争仍可取消。清理保留首个故障，二次取消不能替换主错误或形成循环异常原因。
+
 `require "net/connector"` 加载设备 API 和引擎，厂商由 `vendor_class` 按需加载。TextFSM 能力模块可预先组合，但外部 `textfsm` gem 只在实际解析时加载。仅需会话引擎时使用 `require "net/connector/engine/core"`；离线文件操作使用 `net/connector/storage`，不加载厂商。
 
 `engine/dialogue` 只定义 Interaction、Dialogue 与 Response；读取循环位于 `engine/response_reader`。`engine/errors` 不加载脱敏运行时，`engine/redactor` 负责秘密作用域。Session 明确加载并持有读取器与脱敏器。

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
@@ -189,6 +191,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

@@ -250,6 +250,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 +262,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/device/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "forwardable"
+require_relative "../device_session"
 require_relative "../engine/core"
 require_relative "profile"
 require_relative "running_config"
@@ -62,20 +63,13 @@ module Net
       def self.open(**)
         raise ArgumentError, "open requires a block" unless block_given?
 
-        device = new(**)
-        begin
+        value, failure = DeviceSession.call(factory: -> { new(**) }) do |device|
           device.connect
           yield device
-        rescue Exception # rubocop:disable Lint/RescueException -- 本次连接或块失败时仍关闭设备，并保留原始故障或中断。
-          failed = true
-          raise
-        ensure
-          begin
-            device.close
-          rescue Exception # rubocop:disable Lint/RescueException -- 只保留本次作用域的原始异常，不受外层已处理异常影响。
-            raise unless failed
-          end
         end
+        raise failure 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/running_config.rb

@@ -103,9 +103,11 @@ module Net
       # 排除命令回显和提示符，确认响应确实包含配置正文。
       def config_body?(step)
         body = TerminalRenderer.render(step.output.delete_suffix(step.prompt.to_s)).strip
-        lines = body.lines
-        lines.shift if lines.first&.strip == step.command.text
-        !lines.join.strip.empty?
+        # 只需确认首个正文行；不为大配置创建全部行对象或重新拼接整份响应。
+        body.each_line.with_index.any? do |line, index|
+          text = line.strip
+          !text.empty? && !(index.zero? && text == step.command.text)
+        end
       end
 
       # 将缺少配置的情况统一映射为可识别的设备错误码。

data/lib/net/connector/device_session.rb

@@ -14,11 +14,16 @@ module Net
         begin
           # 构造器在阻塞等待中仍可取消；非阻塞的返回交接须先登记所有权再交付取消。
           # 工厂尚未返回时的部分资源由工厂清理，成功返回后统一由本作用域关闭。
-          Thread.handle_interrupt(Exception => :on_blocking) { connector = factory.call }
+          Thread.handle_interrupt(Exception => :on_blocking) do
+            connector = factory.call
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 工厂同步故障先于退出屏蔽范围时交付的取消。
+            failure = error
+            raise
+          end
           value = yield connector
           completed = true
         rescue Exception => error # rubocop:disable Lint/RescueException -- 收尾后保留最先发生的中断，普通故障单独交付业务层。
-          failure = error
+          failure ||= error
           completed = true
         ensure
           begin

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

@@ -20,7 +20,7 @@ module Net
         @host = "[#{@host}]:#{configuration.port}" if configuration.port && configuration.port != 22
         @replace = replace
         @original = read_shared
-        @file = Tempfile.new([".nc-known-hosts-", ""], File.dirname(@destination))
+        create_snapshot
         @path = @file.path
         @file.write(@original)
         @file.flush
@@ -57,6 +57,36 @@ module Net
       end
 
       def close
+        failure = nil
+        # 清除引用至删除快照期间延后异步取消，不能留下失去所有者的临时文件。
+        Thread.handle_interrupt(Exception => :never) do
+          close_snapshot
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 保存同步清理故障，退出屏蔽范围后继续传播。
+          failure = error
+          raise
+        end
+      rescue Exception => error # rubocop:disable Lint/RescueException -- 延迟取消不能覆盖清理过程中已经发生的故障。
+        raise failure || error, cause: nil
+      end
+
+      private
+
+      # 临时文件返回后先登记所有权，阻塞构造期间仍允许取消。
+      def create_snapshot
+        failure = nil
+        begin
+          Thread.handle_interrupt(Exception => :on_blocking) do
+            @file = Tempfile.new([".nc-known-hosts-", ""], File.dirname(@destination))
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 构造故障先于退出屏蔽范围时递送的二次取消。
+            failure = error
+          end
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 成功交接后取消仍传播，但不覆盖已登记的构造故障。
+          failure ||= error
+        end
+        raise failure, cause: nil if failure
+      end
+
+      def close_snapshot
         file = @file
         @file = nil
         File.unlink(@path + ".old") if @path && File.exist?(@path + ".old")
@@ -71,8 +101,6 @@ module Net
         end
       end
 
-      private
-
       # 初始化失败时保留原始异常，同时尽力清理已经创建的临时文件。
       def close_preserving_failure
         close

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

@@ -31,15 +31,17 @@ module Net
         @transport = transport
         @session_id = SecureRandom.hex(8).freeze
         @command_sequence = 0
-        @io = open_file(@configuration.log_file) if @configuration.log_file
+        open_file(@configuration.log_file) if @configuration.log_file
         if @configuration.log_format == :raw
           @writer = @output = RedactingWriter.new(@io, @redactor) if @io
         elsif @io || @configuration.logger
           @logger = @configuration.logger || ::Logger.new(@io, formatter: Formatter.new)
           open_transcript if @io && @configuration.log_level == :debug
         end
-      rescue => error
+      rescue Exception => error # rubocop:disable Lint/RescueException -- 文件已登记后的中断也必须释放资源，仍原样交付中断。
         close_preserving_failure
+        raise unless error.is_a?(StandardError)
+
         raise build_error("unable to open session log", error), cause: nil
       end
 
@@ -192,10 +194,16 @@ module Net
           failed = true
           raise
         ensure
+          close_failure = nil
           begin
-            @io&.close
-          rescue Exception # rubocop:disable Lint/RescueException -- 文件关闭不能覆盖首个日志收尾故障或中断。
-            raise unless failed
+            Thread.handle_interrupt(Exception => :never) do
+              @io&.close
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 文件关闭先发生的故障优先于待处理中断。
+              close_failure = error
+              raise
+            end
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 文件关闭不能覆盖首个日志收尾故障或中断。
+            raise close_failure || error, cause: nil unless failed
           ensure
             @writer = @output = @transcript = @logger = @io = @transport = @session_id = nil
             @attached = false
@@ -244,29 +252,28 @@ module Net
 
       # 以私有权限打开设备日志文件。
       def open_file(path)
+        failure = nil
         FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
-        file = File.open(path, File::WRONLY | File::CREAT | File::APPEND | File::NOFOLLOW | File::NONBLOCK, 0o600)
-        begin
-          # FIFO 的打开不受登录截止时间约束；验证同一个 FD 后才能修改权限或写入。
-          raise ArgumentError, "session log must be a regular file" unless file.stat.file?
-
-          file.chmod(0o600)
-          file.binmode
-          file.write("\n") if file.size.positive? && @configuration.log_format == :text
-          file
-        rescue Exception # rubocop:disable Lint/RescueException -- 中断时也释放尚未完成设置的文件。
-          begin
-            file.close
-          rescue Exception # rubocop:disable Lint/RescueException -- 保留文件设置的原始故障或中断。
-            # 保留设置失败的原始原因。
-          end
+        # 返回文件后先登记唯一所有者；后续设置失败由 open 统一释放，不重复交接资源。
+        Thread.handle_interrupt(Exception => :never) do
+          @io = File.open(path, File::WRONLY | File::CREAT | File::APPEND | File::NOFOLLOW | File::NONBLOCK, 0o600)
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 非阻塞打开的主故障不能被待处理中断替换。
+          failure = error
           raise
         end
+        # FIFO 的打开不受登录截止时间约束；验证同一个 FD 后才能修改权限或写入。
+        raise ArgumentError, "session log must be a regular file" unless @io.stat.file?
+
+        @io.chmod(0o600)
+        @io.binmode
+        @io.write("\n") if @io.size.positive? && @configuration.log_format == :text
+      rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复取消交付时仍保留打开阶段的首个故障。
+        raise failure || error, cause: nil
       end
 
       # 在日志打开失败后尽力释放资源。
       def close_preserving_failure
-        close
+        Thread.handle_interrupt(Exception => :never) { close }
       rescue Exception # rubocop:disable Lint/RescueException -- 清理故障或中断不能覆盖日志打开失败。
         nil
       end

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

@@ -37,18 +37,23 @@ module Net
 
         # 打开伪终端、设置终端大小并启动设备进程。
         def open
+          failure = nil
           configuration.validate_endpoint!
-          @channel = if @channel_factory
-                       @channel_factory.call
-                     else
-                       if defined?(Expect::Session)
+          # 构造期间的阻塞仍可取消；返回交接先登记信道，再交付异步中断。
+          Thread.handle_interrupt(Exception => :on_blocking) do
+            @channel = if @channel_factory
+                         @channel_factory.call
+                       elsif defined?(Expect::Session)
                          Expect::Session.new(buffer_limit: nil, write_timeout: configuration.write_timeout)
                        else
                          Expect.new(raw_pty: true, reset_timeout_on_read: false, buffer_limit: nil,
-                                  preserve_buffer: false, log_stdout: false, log_listeners: false,
-                                  debug_level: 0, write_timeout: configuration.write_timeout)
+                                    preserve_buffer: false, log_stdout: false, log_listeners: false,
+                                    debug_level: 0, write_timeout: configuration.write_timeout)
                        end
-                     end
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 退出屏蔽范围交付取消之前，先保存构造器的同步故障。
+            failure = error
+            raise
+          end
           # Profile 使用宽、高；PTY 使用行数、列数。
           @channel.slave.winsize = @terminal_size.reverse if @terminal_size
           if @channel.respond_to?(:transcript=)
@@ -65,9 +70,9 @@ module Net
             @channel.spawn(*argv)
           end
           self
-        rescue Exception # rubocop:disable Lint/RescueException -- 中断时也必须释放尚未完成初始化的 PTY。
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 中断时也必须释放尚未完成初始化的 PTY。
           close_preserving_failure
-          raise
+          raise failure || error, cause: nil
         end
 
         # 从信道读取下一事件，并把字符串字段转换为字节字符串。
@@ -107,10 +112,19 @@ module Net
 
         # 清除信道和日志目标，并强制关闭底层进程。
         def close
-          channel = @channel
-          @channel = nil
-          @log_target = nil
-          channel&.hard_close
+          failure = nil
+          # 从字段移交到关闭完成期间不能取消，避免丢失尚未回收的进程。
+          Thread.handle_interrupt(Exception => :never) do
+            channel = @channel
+            @channel = nil
+            @log_target = nil
+            channel&.hard_close
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 延迟取消不能覆盖底层关闭的首个故障。
+            failure = error
+            raise
+          end
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复取消交付时仍保留最先观察到的故障。
+          raise failure || error, cause: nil
         end
 
         # 把人工交互结果转换为设备 EOF、超时或输入状态。
@@ -156,14 +170,21 @@ module Net
         end
 
         def open
+          failure = nil
           configuration.validate_endpoint!
           unless configuration.host_key_policy == :strict
-            @known_hosts = KnownHosts.new(configuration, replace: @replace_host_key)
+            # 临时信任文件的返回交接与信道遵守同一所有权边界。
+            Thread.handle_interrupt(Exception => :on_blocking) do
+              @known_hosts = KnownHosts.new(configuration, replace: @replace_host_key)
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 构造器先失败时，延迟取消不得覆盖其原始异常。
+              failure = error
+              raise
+            end
           end
           super
-        rescue Exception # rubocop:disable Lint/RescueException -- 启动失败或中断时释放临时信任文件。
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 启动失败或中断时释放临时信任文件。
           close_preserving_failure
-          raise
+          raise failure || error, cause: nil
         end
 
         def authenticated
@@ -172,18 +193,29 @@ module Net
         end
 
         def close
-          known_hosts = @known_hosts
-          @known_hosts = nil
-          super
-        rescue Exception # rubocop:disable Lint/RescueException -- 全部资源均须尝试关闭，保留首个失败或中断。
-          failed = true
-          raise
-        ensure
-          begin
-            known_hosts&.close
-          rescue Exception # rubocop:disable Lint/RescueException -- 信任文件收尾不能覆盖传输关闭的原始异常。
-            raise unless failed
+          failure = nil
+          # 一次取消须等待信道和信任快照均完成回收；同步故障仍保留首个。
+          Thread.handle_interrupt(Exception => :never) do
+            known_hosts = @known_hosts
+            @known_hosts = nil
+            begin
+              super
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 全部资源均须尝试关闭，保留首个失败或中断。
+              failure = error
+              raise
+            ensure
+              begin
+                known_hosts&.close
+              rescue Exception => error # rubocop:disable Lint/RescueException -- 信任文件收尾不能覆盖传输关闭的原始异常。
+                unless failure
+                  failure = error
+                  raise
+                end
+              end
+            end
           end
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复取消交付也不能盖掉已经发生的关闭故障。
+          raise failure || error, cause: nil
         end
 
         # 返回 SSH 协议标识。

data/lib/net/connector/execution_pool.rb

@@ -101,7 +101,8 @@ module Net
           end
         end
       rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复交付时保留原故障，二次取消不改变批次失败原因。
-        raise primary_failure || error
+        # 二次取消可能已以原故障为 cause；不能反向关联形成异常原因环。
+        raise primary_failure || error, cause: nil
       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/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/storage/backup_lock.rb

@@ -46,17 +46,43 @@ module Net
             return yield self
           end
 
-          file = nil
+          file = acquisition_error = nil
           begin
-            file = open_lock
+            # 文件取得与所有权登记不可拆开；竞争锁和业务块仍立即响应中断。
+            Thread.handle_interrupt(Exception => :never) do
+              begin
+                file = open_lock
+              rescue Exception => error # rubocop:disable Lint/RescueException -- 取得失败先于边界退出时递送的中断。
+                acquisition_error = error
+              end
+            end
+            raise acquisition_error, cause: nil if acquisition_error
+
             verify_lock!(file)
             acquire(file)
             verify_lock!(file)
             @owner = [Process.pid, Fiber.current]
             yield self
+          rescue Exception # rubocop:disable Lint/RescueException -- 解锁收尾保留首个操作故障或中断。
+            failed = true
+            raise acquisition_error, cause: nil if acquisition_error
+
+            raise
           ensure
             @owner = nil
-            file&.close
+            cleanup_error = nil
+            begin
+              Thread.handle_interrupt(Exception => :never) do
+                begin
+                  file&.close
+                rescue Exception => error # rubocop:disable Lint/RescueException -- 在递送待处理中断前登记关闭故障。
+                  cleanup_error = error
+                end
+              end
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 待处理中断不能覆盖已登记的关闭故障。
+              cleanup_error ||= error
+            end
+            raise cleanup_error, cause: nil if cleanup_error && !failed
           end
         end
 

data/lib/net/connector/storage/safe_file.rb

@@ -10,17 +10,43 @@ module Net
         Fingerprint = Data.define(:path, :sha256, :mode, :dev, :ino)
 
         def self.open(path, missing: false, replace_symlink: false)
-          file = open_handle(path, missing: missing, replace_symlink: replace_symlink)
-          return nil unless file
-
+          file = acquisition_error = nil
           begin
+            # 取得描述符与登记所有权共用短暂边界；读取和业务块仍可中断。
+            Thread.handle_interrupt(Exception => :never) do
+              begin
+                file = open_handle(path, missing: missing, replace_symlink: replace_symlink)
+              rescue Exception => error # rubocop:disable Lint/RescueException -- 取得失败先于边界退出时递送的中断。
+                acquisition_error = error
+              end
+            end
+            raise acquisition_error, cause: nil if acquisition_error
+            return nil unless file
+
             stat = file.stat
             raise ArgumentError, "saved configuration is not a regular file" unless stat.file?
 
             file.binmode
             yield file, stat
+          rescue Exception # rubocop:disable Lint/RescueException -- 收尾不能覆盖读取故障或用户中断。
+            failed = true
+            raise acquisition_error, cause: nil if acquisition_error
+
+            raise
           ensure
-            file.close
+            cleanup_error = nil
+            begin
+              Thread.handle_interrupt(Exception => :never) do
+                begin
+                  file&.close
+                rescue Exception => error # rubocop:disable Lint/RescueException -- 在递送待处理中断前登记关闭故障。
+                  cleanup_error = error
+                end
+              end
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 待处理中断不能覆盖已登记的关闭故障。
+              cleanup_error ||= error
+            end
+            raise cleanup_error, cause: nil if cleanup_error && !failed
           end
         end
 

data/lib/net/connector/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.2
 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