net-connector 0.10.1 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9891d74f563f6d1383bf3a5a41e1eeb51e607b1395ec4794a42ed45027ce3c34
-  data.tar.gz: 950f56fcf3428c4a9a33c2176768f5cab3bdb4f19e649dd6f8e89547810dcea7
+  metadata.gz: 7f994834e561576d4fafde11f003653a865dd4d35da5a5fd8a7a4c2a016cc2d5
+  data.tar.gz: f7585fe57b094fd687b2de70e34b6b41eb0e46c220d5fc9bfe4357a25c31f6f9
 SHA512:
-  metadata.gz: a785501bd50b61f542b9222ae24597025a20d3aa1d10fd2a042d20a7653f5fbe8ec2f6ccaf3ab6ea34db0cd11553fb918a836c34fd21dda9b4cb8b0dec83ed81
-  data.tar.gz: 5e1ef923eb2d603595d6225ed7cb6f08c36dbfc12c760d5b9aa69c94bbf812ef7a288586a48ff1b75947fc4886eb7dfbf830a5038bda2bfd6a43205aca18848e
+  metadata.gz: c862e76e800b3ef6174e8aeadaedd4724dafbd08858954874e6955c0c71a4f21c1f9fd124dfe60e59e5389380330193740cbed6e2c0369ee6f9eaddd0b0d56ce
+  data.tar.gz: 6d62272a65c854987a1d9d73e1cb6aeba177743df828e37ec20595b31e9c42ada27dd787989a9cf1ecc17a3ae7fa1fe46f3c6db992e736ffcb2337c42b081feb

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 更新记录
 
+## 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
@@ -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/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/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/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/version.rb

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