net-connector 0.9.0 → 0.10.0

data/lib/net/connector/device/topology.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "topology/strategy"
+require_relative "topology/stages"
 
 module Net
   module Connector
@@ -14,6 +15,11 @@ module Net
         # 读取运行配置中的接口描述或端口名称。
         def interface_descriptions = Topology.new(self).interface_descriptions
 
+        # 显式同步请求在同一会话中完成发现、修改、读回与保存，无须调用方传递计划。
+        def sync_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+          Topology.new(self).sync_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+        end
+
         # 以邻居和现有配置为证据，生成待确认的接口描述变更计划。
         def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
           Topology.new(self).plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
@@ -29,6 +35,50 @@ module Net
       Change = Data.define(:interface, :old_description, :new_description, :neighbor)
       Plan = Data.define(:host, :vendor, :evidence, :changes, :commands)
 
+      # 仅承载厂商档案的离线上下文，不能连接、查询或下发设备命令。
+      PlanningContext = Data.define(:host, :vendor, :profile) do
+        def config_commands = profile.config_commands
+      end
+      private_constant :PlanningContext
+
+      # 全批应用前拒绝可离线判定的能力或命令问题；现场证据仍由单设备操作重验。
+      def self.validate_plan!(plan, host:, vendor:)
+        unless plan.is_a?(Plan) && plan.host == host && plan.vendor == vendor
+          raise ArgumentError, "plan must match its target device"
+        end
+        if plan.changes.empty?
+          raise ArgumentError, "empty topology plan cannot contain commands" unless plan.commands.empty?
+
+          return plan
+        end
+        strategy = planning_strategy(host: host, vendor: vendor)
+        validate_change_support!(strategy, host: host, phase: :apply)
+        stages = Stages.build(strategy: strategy, host: host, changes: plan.changes)
+        unless stages.values.flat_map { |script| script.map(&:text) } == plan.commands
+          raise ArgumentError, "plan commands were modified or use an older execution sequence; regenerate the plan"
+        end
+        plan
+      end
+
+      # 批次规划在建立任一会话前检查整个目标集合的厂商写入能力。
+      def self.validate_vendor_support!(host:, vendor:, phase:)
+        validate_change_support!(planning_strategy(host: host, vendor: vendor), host: host, phase: phase)
+      end
+
+      def self.planning_strategy(host:, vendor:)
+        profile = Net::Connector.vendor_class(vendor).profile
+        (profile.topology_strategy || Strategy).new(PlanningContext.new(host: host, vendor: vendor, profile: profile))
+      end
+      private_class_method :planning_strategy
+
+      # 能力声明不需要会话；规划、批次预检和现场应用使用同一厂商规则。
+      def self.validate_change_support!(strategy, host:, phase:)
+        return if strategy.supports?(:interface_description_changes)
+
+        raise UnsupportedOperation.new("automatic interface description changes are unavailable; use a verified manual workflow",
+                                       code: strategy.change_error_code, host: host, phase: phase)
+      end
+
       # 保存设备及其独立的 TextFSM 解析入口。
       def initialize(device, template_dir: nil)
         require_relative "../textfsm"
@@ -92,6 +142,18 @@ module Net
 
       private :read_interface_descriptions
 
+      # 调用即表达修改意图；同一租约覆盖发现到保存，外部变更仍须重验。
+      def sync_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+        unless [abbreviate, lowercase].all? { |value| value == true || value == false }
+          raise ArgumentError, "description formatting options must be boolean"
+        end
+        validate_change_support!(:apply)
+        @device.with_operation(:apply) do
+          plan = plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+          plan.changes.empty? ? Result.new : apply_plan(plan)
+        end
+      end
+
       # 比对邻居和现有描述，生成包含确切命令的只读变更计划。
       def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
         validate_change_support!(:plan) if @strategy.supports?(:neighbors)
@@ -210,21 +272,7 @@ module Net
 
       # 审批列表保留真正执行的读回命令，使旧版“先保存后读回”计划无法静默复用。
       def stage_scripts(changes)
-        phases = %i[leave_configuration_commands verification_commands persistence_commands].map do |method|
-          @strategy.public_send(method)
-        end
-        unless phases.all? { |commands| commands.is_a?(Array) && !commands.empty? }
-          raise UnsupportedOperation.new("topology strategy must declare separate readback and persistence stages",
-                                         code: :description_stages_unsupported, host: @device.host, phase: :plan)
-        end
-        leave, verify, persist = phases
-        sequences = {
-          change: [@strategy.enter_configuration_command] + changes.flat_map { |change| change_commands(change) } + leave,
-          verify: verify, persist: persist
-        }
-        sequences.transform_values do |commands|
-          Script.new(commands.map { |command| @strategy.script_command(command) }, name: "interface descriptions")
-        end
+        Stages.build(strategy: @strategy, host: @device.host, changes: changes)
       end
 
       def execute_stage(script, steps)
@@ -242,10 +290,7 @@ module Net
 
       # 下发描述前确认厂商提供配置能力，避免把只读发现当成可写能力。
       def validate_change_support!(phase)
-        return if @strategy.supports?(:interface_description_changes)
-
-        raise UnsupportedOperation.new("automatic interface description changes are unavailable; use a verified manual workflow",
-                                       code: @strategy.change_error_code, host: @device.host, phase: phase)
+        self.class.validate_change_support!(@strategy, host: @device.host, phase: phase)
       end
 
       # 汇总邻居身份和当前描述，并要求每个目标接口都有配置证据。
@@ -267,11 +312,7 @@ module Net
         end.freeze
       end
 
-      # 设备标识来自解析证据，仍需在生成命令前验证其安全性。
-      def change_commands(change)
-        InterfaceDescription.validate_interface!(change.interface)
-        @strategy.change_commands(change)
-      end
+
     end
   end
 end

data/lib/net/connector/device_session.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    # 一个设备任务独占一个连接器；返回值与收尾故障分别保留，不能靠重试恢复写操作。
+    module DeviceSession
+      # 工厂负责构造，作用域负责关闭；中断仍向调用方传播且不会被第二个关闭故障覆盖。
+      def self.call(factory:)
+        raise ArgumentError, "factory must respond to call" unless factory.respond_to?(:call)
+        raise ArgumentError, "device session requires a block" unless block_given?
+
+        connector = value = failure = nil
+        completed = false
+        begin
+          # 构造器在阻塞等待中仍可取消；非阻塞的返回交接须先登记所有权再交付取消。
+          # 工厂尚未返回时的部分资源由工厂清理，成功返回后统一由本作用域关闭。
+          Thread.handle_interrupt(Exception => :on_blocking) { connector = factory.call }
+          value = yield connector
+          completed = true
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 收尾后保留最先发生的中断，普通故障单独交付业务层。
+          failure = error
+          completed = true
+        ensure
+          begin
+            # 二次异步取消须等待关闭完成，不能在收尾中再次丢失资源所有权。
+            Thread.handle_interrupt(Exception => :never) { connector&.close }
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 关闭故障不能覆盖原操作故障，包括 Interrupt。
+            failure ||= error
+          end
+          # break 和非局部 return 跳过尾部返回值；收尾故障必须在展开作用域时交付。
+          raise failure if failure && (!completed || !failure.is_a?(StandardError))
+        end
+
+        [value, failure]
+      end
+    end
+  end
+end

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

@@ -80,11 +80,21 @@ module Net
 
         # 临时设置写入超时，完成写入后恢复原设置。
         def write(bytes, timeout: configuration.write_timeout)
-          previous = @channel.write_timeout
-          @channel.write_timeout = timeout
-          @channel.write(bytes)
-        ensure
-          @channel.write_timeout = previous if @channel
+          channel = @channel
+          previous = channel.write_timeout
+          begin
+            channel.write_timeout = timeout
+            channel.write(bytes)
+          rescue Exception # rubocop:disable Lint/RescueException -- 恢复超时前保留写入的首个故障或中断。
+            failed = true
+            raise
+          ensure
+            begin
+              channel.write_timeout = previous
+            rescue Exception # rubocop:disable Lint/RescueException -- 收尾故障不能把中断转换成普通写入错误。
+              raise unless failed
+            end
+          end
         end
 
         # 判断信道尚未建立或已经关闭。

data/lib/net/connector/execution_pool.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    # 仅管理有限并发和线程所有权；业务层负责将普通任务故障转换为领域结果。
+    class ExecutionPool
+      DEFAULT_CONCURRENCY = 4
+      MAX_CONCURRENCY = 50
+
+      def self.validate_concurrency!(concurrency)
+        unless concurrency.is_a?(Integer) && (1..MAX_CONCURRENCY).cover?(concurrency)
+          raise ArgumentError, "concurrency must be an Integer in 1..#{MAX_CONCURRENCY}"
+        end
+
+        concurrency
+      end
+
+      # 环境只提供默认并发数；显式构造参数优先，非法值不创建线程。
+      def self.environment_concurrency(env: ENV)
+        value = env.fetch("NC_CONCURRENCY", DEFAULT_CONCURRENCY.to_s)
+        unless value.is_a?(String) && value.match?(/\A[0-9]+\z/)
+          raise ArgumentError, "NC_CONCURRENCY must be a positive integer"
+        end
+
+        validate_concurrency!(Integer(value, 10))
+      end
+
+      def initialize(concurrency: self.class.environment_concurrency)
+        @concurrency = self.class.validate_concurrency!(concurrency)
+      end
+
+      # 保序返回块的值；任何未处理异常均在调用线程抛出，停止并回收本次所有线程。
+      # 只复制任务数组，任务内容仍由业务层在下发前校验和固定，不自动重放块。
+      def map(items)
+        raise ArgumentError, "items must be an Array" unless items.is_a?(Array)
+        raise ArgumentError, "map requires a block" unless block_given?
+
+        items = items.dup
+        queue = Queue.new
+        items.each_with_index { |item, index| queue << [index, item] }
+        count = [items.size, @concurrency].min
+        count.times { queue << nil }
+        gate = Queue.new
+        finished = Queue.new
+        results = Array.new(items.size)
+        threads = []
+        completed = false
+        primary_failure = nil
+        begin
+          count.times do
+            # 仅延迟线程创建到登记的异步中断，避免尚未登记的工作线程失去所有者。
+            Thread.handle_interrupt(Exception => :never) do
+              threads << Thread.new do
+                failure = nil
+                begin
+                  # 全部线程成功建立后才允许设备操作，创建失败不能留下已发送的变更。
+                  Thread.handle_interrupt(Exception => :immediate) do
+                    gate.pop
+                    while (task = queue.pop)
+                      index, item = task
+                      results[index] = yield item
+                    end
+                  end
+                rescue Exception => error # rubocop:disable Lint/RescueException -- 将中断同步交给调用线程，避免全局 abort_on_exception 波及其他线程。
+                  failure = error
+                ensure
+                  finished << [Thread.current, failure]
+                end
+              end
+            end
+          end
+          count.times { gate << true }
+          count.times do
+            thread, failure = finished.pop
+            thread.join
+            raise failure if failure
+          end
+          completed = true
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 记录取消或原任务故障，收尾中再次取消不能覆盖它。
+          primary_failure = error
+          raise
+        ensure
+          stop_threads(threads, primary_failure) unless completed
+        end
+        results
+      end
+
+      private
+
+      # kill 运行任务自身的 ensure；次级关闭故障不能盖掉已观察到的原始异常。
+      def stop_threads(threads, primary_failure)
+        # 仅回收期间延迟异步取消；交付二次中断之前必须 kill 并 join 全部拥有线程。
+        Thread.handle_interrupt(Exception => :never) do
+          threads.each(&:kill)
+          threads.each do |thread|
+            begin
+              thread.join
+            rescue Exception # rubocop:disable Lint/RescueException -- 等待全部拥有线程收尾，保留调用方原始故障或中断。
+              nil
+            end
+          end
+        end
+      rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复交付时保留原故障，二次取消不改变批次失败原因。
+        raise primary_failure || error
+      end
+    end
+  end
+end

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

@@ -33,11 +33,13 @@ module Net
           fleet = Fleet.new(client: client, settings: settings, credentials: resolver, result_store: nil)
           progress.reading_inventory
           limit = settings.limit_per_vendor
+          refresh = options[:force_refresh] ? { force_refresh: true } : {}
           plan = if @mode == :backup
-                   fleet.plan_backup(limit_per_vendor: limit)
+                   fleet.plan_backup(limit_per_vendor: limit, **refresh)
                  else
-                   fleet.plan_tftp_backup(limit_per_vendor: limit, allow_fixed_name_reuse: !server_root.nil?)
+                   fleet.plan_tftp_backup(limit_per_vendor: limit, allow_fixed_name_reuse: !server_root.nil?, **refresh)
                  end
+          inventory_warning(fleet)
           progress.plan(plan, concurrency: settings.concurrency, limit_per_vendor: limit)
           preview = plan_summary(plan)
           @output.puts JSON.generate(plan: preview) if options[:json]
@@ -59,6 +61,16 @@ module Net
 
         private
 
+        # 清单离线回退和本地保存故障单独提示，不覆盖设备操作结果。
+        def inventory_warning(fleet)
+          if fleet.inventory_status && fleet.inventory_status[:source] == :stale_cache
+            @error.puts "清单刷新失败，使用历史缓存（#{fleet.inventory_status[:refresh_error_code]}）"
+          end
+          return unless fleet.inventory_status && fleet.inventory_status[:write_error_type]
+          @error.puts "清单缓存写入失败（#{fleet.inventory_status[:write_error_type]}）"
+
+        end
+
         # 预检完成后才创建批次目录；补充日志路径时保持原策略快照与动态凭据来源。
         def prepare(options)
           settings = CLI::Options.settings(options, env: @env).for_run(mode: @mode)

data/lib/net/connector/netdisco/cli/options.rb

@@ -47,6 +47,7 @@ module Net
 
           # 正式 CLI 与批次示例共用并发、抽样、核验和成功策略选项。
           def self.add_execution(opts, values)
+            opts.on("--refresh-inventory", "强制刷新清单；远端失败时回退已验证历史") { values[:force_refresh] = true }
             opts.on("-c", "--concurrency N", Integer, "并发设备数，1 至 50") do |count|
               raise OptionParser::InvalidArgument unless (1..Settings::MAX_CONCURRENCY).cover?(count)
 

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

@@ -27,8 +27,7 @@ module Net
           return 0 if options[:done]
 
           validate_options!(options)
-          mode = options[:export] ? :export : (options[:tftp] ? :tftp : :backup)
-          settings = settings_for(options).for_run(mode: mode)
+          settings = settings_for(options)
 
           if options[:show_config]
             @output.puts JSON.pretty_generate(settings.public_config)
@@ -44,6 +43,7 @@ module Net
 
           fleet = @fleet_factory.call(settings)
           plan = backup_plan(fleet, settings, options)
+          inventory_warning(fleet)
           if options[:plan]
             @output.puts JSON.pretty_generate(plan_summary(plan))
             return 0
@@ -71,9 +71,10 @@ module Net
 
         private
 
-        # 公开 CLI 参数覆盖 YAML 与 ND_URL；设备凭据按环境或显式 CLI 参数解析。
+        # CLI 覆盖支持的环境变量与 YAML；设备凭据按环境或显式 CLI 参数解析。
         def settings_for(options)
-          Options.settings(options, env: @env)
+          mode = options[:export] ? :export : (options[:tftp] ? :tftp : :backup)
+          Options.settings(options, env: @env).for_run(mode: mode)
         end
 
         # 导出已有配置不创建清单或设备连接。
@@ -86,10 +87,11 @@ module Net
         # 预览与执行共用计划和主机存在性检查。
         def backup_plan(fleet, settings, options)
           limit = options[:all] ? nil : options[:limit] || settings.limit_per_vendor(tftp: options[:tftp])
+          refresh = options[:force_refresh] ? { force_refresh: true } : {}
           plan = if options[:tftp]
-                   fleet.plan_tftp_backup(limit_per_vendor: limit)
+                   fleet.plan_tftp_backup(limit_per_vendor: limit, **refresh)
                  else
-                   fleet.plan_backup(limit_per_vendor: limit)
+                   fleet.plan_backup(limit_per_vendor: limit, **refresh)
                  end
           if options[:host]
             host = IPAddr.new(options[:host]).to_s
@@ -98,6 +100,15 @@ module Net
           plan
         end
 
+        # 回退历史只描述清单来源，不把缓存命中误报为远端已恢复。
+        def inventory_warning(fleet)
+          status = fleet.inventory_status if fleet.respond_to?(:inventory_status)
+          if status && status[:source] == :stale_cache
+            @error.puts "net-backup: 清单刷新失败，使用历史缓存（#{status[:refresh_error_code]}）"
+          end
+          @error.puts "net-backup: 清单缓存写入失败（#{status[:write_error_type]}）" if status && status[:write_error_type]
+        end
+
         # 仅执行已经校验的计划，保留本地与 TFTP 两种结果语义。
         def backup(fleet, plan, settings, options)
           reporting = options.slice(:success_policy)
@@ -158,7 +169,7 @@ module Net
             raise ArgumentError, "--export 不能与清单查询选项同时使用"
           end
           if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:environment].key?("NC_CONCURRENCY") || options[:host] ||
-            options[:success_policy] || options[:tftp_root] || options[:max_script_output_bytes])
+            options[:success_policy] || options[:tftp_root] || options[:max_script_output_bytes] || options[:force_refresh])
             raise ArgumentError, "--export 不能与备份选项同时使用"
           end
         end

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

@@ -6,6 +6,7 @@ require "openssl"
 require "timeout"
 require "uri"
 require_relative "inventory_budget"
+require_relative "../background_task"
 
 module Net
   module Connector
@@ -196,11 +197,11 @@ module Net
 
         # 异步超时展开栈时，Net::HTTP 的 chunked ensure 可能再次等待读取。
         # 只关闭本次自有连接来解除这类阻塞；结束时唤醒并 join 观察线程，不遗留后台任务。
-        def with_http_deadline(http, budget)
+        def with_http_deadline(http, budget, &)
           mutex = Mutex.new
           changed = ConditionVariable.new
           finished = false
-          timer = Thread.new do
+          task = lambda do
             begin
               mutex.synchronize { changed.wait(mutex, budget.remaining) until finished }
             rescue InventoryTimeout
@@ -212,10 +213,8 @@ module Net
               end
             end
           end
-          yield
-        ensure
-          mutex&.synchronize { finished = true; changed.broadcast }
-          timer&.join
+          stop = -> { mutex.synchronize { finished = true; changed.broadcast } }
+          BackgroundTask.run(task: task, stop: stop, &)
         end
 
         def read_response(http, request, budget)

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

@@ -6,10 +6,13 @@ require "yaml"
 module Net
   module Connector
     module Netdisco
-      # 无凭据 YAML 配置；仅 ND_URL 允许从进程环境覆盖，其他策略由 CLI 覆盖。
+      # 无凭据 YAML 配置；ND_URL、ND_CACHE_TTL、NC_CONCURRENCY 允许环境覆盖，其余策略由 CLI 覆盖。
       class ConfigFile
         FIELDS = {
-          "netdisco" => { "source" => ["ND_SOURCE", :string],
+          "netdisco" => { "cache_directory" => ["ND_CACHE_DIRECTORY", :string],
+                          "cache_ttl" => ["ND_CACHE_TTL", :number],
+                          "cache_enabled" => ["ND_CACHE_ENABLED", :boolean],
+                          "source" => ["ND_SOURCE", :string],
                           "query" => ["ND_QUERY", :string],
                           "query_params" => ["ND_QUERY_PARAMS", :json_array],
                           "url" => ["ND_URL", :string],

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

@@ -76,38 +76,34 @@ module Net
           budget = InventoryBudget.new(@options, clock: method(:monotonic))
           connection = nil
           connected = false
+          failed = false
           begin
             Timeout.timeout(budget.remaining, Client::InventoryTimeout) do
-              # 先取得连接句柄再交付超时，确保异常到达时 ensure 能显式关闭连接。
-              Thread.handle_interrupt(Client::InventoryTimeout => :never) do
+              # 只在取得句柄并登记所有权期间延后异步异常，离开后仍立即传播原中断。
+              Thread.handle_interrupt(Exception => :never) do
                 connection = PG::Connection.connect_start(@connection_options)
               end
               # PostgreSQL NOTICE 可能包含 SQL 或数据，不交给 libpq 默认的 stderr 输出器。
               connection.set_notice_processor { |_notice| nil }
               wait_for_connection(connection, budget)
               connected = true
-              # 使用 pg 可中断的 Ruby 等待接口；底层 socket 仍以非阻塞方式工作。
-              connection.setnonblocking(false)
-              connection.set_client_encoding("UTF8")
-              connection.exec("BEGIN READ ONLY").clear
-              set_statement_timeout(connection, budget)
-              # 即使没有参数也走扩展查询协议，由 PostgreSQL 拒绝多语句和非查询命令。
-              connection.exec_params("DECLARE net_connector_inventory NO SCROLL CURSOR FOR\n#{@options.fetch(:query)}",
-                                     @options.fetch(:query_params)).clear
-              rows = inventory(connection, budget)
-              connection.exec("ROLLBACK").clear
-              budget.remaining
-              rows
+              query_inventory(connection, budget)
             end
           rescue Client::Error => error
+            failed = true
             raise error, cause: nil
           rescue PG::QueryCanceled
+            failed = true
             raise Client::InventoryTimeout, cause: nil
           rescue PG::Error, IOError, SystemCallError
+            failed = true
             code = connected ? :query_failed : :connection_failed
             raise Client::Error.new("Netdisco database #{code.to_s.tr("_", " ")}", code: code), cause: nil
+          rescue Exception # rubocop:disable Lint/RescueException -- 清理继续保留未知异常和用户中断。
+            failed = true
+            raise
           ensure
-            connection&.finish
+            close_connection(connection, failed: failed)
           end
         end
 
@@ -115,6 +111,28 @@ module Net
 
         private
 
+        # 连接始终尝试关闭；收尾故障不能覆盖查询失败或中断，完成后的关闭失败仍须传播。
+        def close_connection(connection, failed:)
+          connection&.finish
+        rescue Exception # rubocop:disable Lint/RescueException -- 保留先发生的查询失败和用户中断。
+          raise unless failed
+        end
+
+        # 使用 pg 可中断的等待与扩展查询协议，只读游标共享本次清单的总预算。
+        def query_inventory(connection, budget)
+          connection.setnonblocking(false)
+          connection.set_client_encoding("UTF8")
+          connection.exec("BEGIN READ ONLY").clear
+          set_statement_timeout(connection, budget)
+          # 即使没有参数也走扩展查询协议，由 PostgreSQL 拒绝多语句和非查询命令。
+          connection.exec_params("DECLARE net_connector_inventory NO SCROLL CURSOR FOR\n#{@options.fetch(:query)}",
+                                 @options.fetch(:query_params)).clear
+          rows = inventory(connection, budget)
+          connection.exec("ROLLBACK").clear
+          budget.remaining
+          rows
+        end
+
         def wait_for_connection(connection, budget)
           deadline = monotonic + @connection_options.fetch(:connect_timeout, budget.remaining).to_f
           loop do