net-connector 0.10.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6ba09a377ed95488c9ecd62788732557564339638dec3ae596bbce0226369fa
-  data.tar.gz: '0876aa9703bdbb2e46db010fcf263a2e1f1e7549e0f63d1bcf60f8529193e3ed'
+  metadata.gz: 9891d74f563f6d1383bf3a5a41e1eeb51e607b1395ec4794a42ed45027ce3c34
+  data.tar.gz: 950f56fcf3428c4a9a33c2176768f5cab3bdb4f19e649dd6f8e89547810dcea7
 SHA512:
-  metadata.gz: 6636cacf21a401c68a6b6dd596e3c4ab11eb153879e6e6e9f74339cf72bea7f8e71e6937745300fc9e513c7b4521b1eecdb249a1cf3abe7b6c3a15fc253b34a4
-  data.tar.gz: f97ff17b82418d78a1c959f420d4c17a53efc7ce4101694719e394e7d50d42f1ae2e86167a3b470850e598eba9becc42cb6364133fe2e6888eca426342534129
+  metadata.gz: a785501bd50b61f542b9222ae24597025a20d3aa1d10fd2a042d20a7653f5fbe8ec2f6ccaf3ab6ea34db0cd11553fb918a836c34fd21dda9b4cb8b0dec83ed81
+  data.tar.gz: 5e1ef923eb2d603595d6225ed7cb6f08c36dbfc12c760d5b9aa69c94bbf812ef7a288586a48ff1b75947fc4886eb7dfbf830a5038bda2bfd6a43205aca18848e

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 更新记录
 
+## 0.10.1 - 2026-10-11
+
+- 设备 `open`、PTY、SSH 信任快照、日志与本地文件统一保护资源交接和关闭边界；异步取消在资源登记或回收后交付，业务等待仍可取消，收尾故障不覆盖首个操作错误。
+- 修复线程回收同时发生二次取消时的循环异常原因，保留原始失败。
+- 配置正文检查提前结束扫描，减少大配置的对象分配和字符串复制，保持原有命令回显与空配置判定。
+
 ## 0.10.0 - 2026-10-11
 
 - 新增 `sync_interface_descriptions`：一次调用、每台设备一个连接，完成邻居发现、描述修改、读回与保存；无变化时不写入或保存，后端仍支持定制格式和分阶段审批。

data/docs/architecture.md

@@ -299,6 +299,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/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/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/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/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.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.1
 platform: ruby
 authors:
 - net-connector contributors