net-connector 0.5.0 → 0.7.0

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

@@ -57,15 +57,15 @@ module Net
         end
       end
 
-      def with_operation_context(name, &block)
-        with_context(operation: name || @context[:operation] || :script, &block)
+      def with_operation_context(name, &)
+        with_context(operation: name || @context[:operation] || :script, &)
       end
 
-      def with_command_context(command, &block)
+      def with_command_context(command, &)
         @command_sequence += 1
         with_context(command_id: @command_sequence, phase: :command,
                      text: command.sensitive? ? "[REDACTED]" : command.text,
-                     source: command.source, line: command.line, &block)
+                     source: command.source, line: command.line, &)
       end
 
       # 将终端回显接入当前会话日志。
@@ -81,7 +81,7 @@ module Net
 
       # 按日志级别写入已脱敏的业务事件。
       def log_event(name, level: :info, **fields)
-        return unless @logger
+        return unless @logger || @configuration.on_event
 
         finish_output
         write_event(name, level: level, **fields)
@@ -190,7 +190,8 @@ module Net
 
       # 每次读取调用方的当前阈值，不缓存级别、不改写共享 Logger。
       def enabled?(level)
-        @logger && LEVELS.fetch(level) >= [@logger.level, LEVELS.fetch(@configuration.log_level)].max
+        LEVELS.fetch(level) >= LEVELS.fetch(@configuration.log_level) &&
+          (@configuration.on_event || (@logger && LEVELS.fetch(level) >= @logger.level))
       end
 
       def write_event(name, level:, **fields)
@@ -198,7 +199,9 @@ module Net
 
         values = @context.compact.merge(fields.reject { |key, _| CONTEXT_FIELDS.include?(key.to_s) })
         values = values.merge(host: @configuration.host, session_id: @session_id)
-        @logger.public_send(level, Event.new(name, values, redactor: @redactor))
+        event = Event.new(name, values, redactor: @redactor)
+        @logger.public_send(level, event) if @logger && LEVELS.fetch(level) >= @logger.level
+        @configuration.on_event&.call(event)
       end
 
       def open_transcript

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

@@ -30,13 +30,10 @@ module Net
         @lock = Mutex.new
       end
 
-      # 判断会话状态和传输层是否都表明连接仍然有效。
       def connected? = state != :closed && !transport.closed?
 
-      # 返回当前是否已经进入特权模式。
       def privileged? = @privileged
 
-      # 标记当前会话已进入特权模式。
       def mark_privileged! = @privileged = true
 
       # 记录脚本之外的业务结果，例如设备报告的 TFTP 上传状态。
@@ -63,16 +60,16 @@ module Net
       end
 
       # 锁覆盖完整操作而不是单次写入，保证批处理命令不会交错。
-      def perform(phase)
+      def perform(phase, &)
         if @operation_owner == [Thread.current, Fiber.current] && !@performing
-          return perform_locked(phase) { yield }
+          return perform_locked(phase, &)
         end
         unless @lock.try_lock
           raise build_error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
         end
 
         begin
-          perform_locked(phase) { yield }
+          perform_locked(phase, &)
         ensure
           @lock.unlock
         end
@@ -106,37 +103,6 @@ module Net
         raise build_error(SessionBusy, "backup path ownership must be acquired before a session operation", phase: phase), cause: nil
       end
 
-      # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
-      def perform_locked(phase)
-        @performing = true
-        completed = false
-        begin
-          unless connected?
-            close_resources unless state == :closed
-            connect_session
-          end
-          @state = (phase == :connect) ? :ready : :executing
-          result = yield
-          completed = true
-          result
-        rescue => error
-          failure = normalize_error(error, phase: phase)
-          close_preserving_failure
-          raise failure, cause: nil
-        rescue Exception # rubocop:disable Lint/RescueException -- Interrupts release the transport, then propagate.
-          close_preserving_failure
-          raise
-        ensure
-          # throw/catch 也会离开此块；对话未完成时必须关闭连接，不能把
-          # 半途的设备提示符误当成下一条命令的响应。
-          close_preserving_failure unless completed || !connected?
-          @state = :ready if connected?
-          @performing = false
-        end
-      end
-
-      private :perform_locked
-
       # 独占关闭会话；已有操作占用时返回会话繁忙错误。
       def close
         unless @lock.try_lock
@@ -195,6 +161,99 @@ module Net
         end
       end
 
+      # 按截止时间限制传输写入，并统一包装底层错误。
+      def write(bytes, deadline:, phase:, command: nil)
+        remaining = [deadline - Expect.monotonic, 0].max
+        transport.write(bytes, timeout: [remaining, configuration.write_timeout].min)
+      rescue => error
+        raise normalize_error(error, phase: phase, command: command), cause: nil
+      end
+
+      # 人工交互会结束当前连接，未完成的输入行不能在之后重放。
+      def interact(**options)
+        perform(:interact) do
+          @state = :interacting
+          begin
+            transport.interact(**options)
+          ensure
+            $ERROR_INFO ? close_preserving_failure : close_resources
+          end
+        end
+      end
+
+      # 创建带脱敏上下文、阶段、命令和输出尾部的领域错误。
+      def build_error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
+        sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
+        message = safe_error_text(message, sensitive: sensitive)
+        output = safe_error_text(output, sensitive: sensitive)
+        klass.new(message, host: configuration.host, phase: phase,
+                  command: command && (command.sensitive? ? "[REDACTED]" : redactor.call(command.text)),
+                  source: command&.source, line: command&.line,
+                  output: truncate_output(output),
+                  underlying: underlying && UnderlyingError.new(underlying, redactor, sensitive: sensitive), **context)
+      end
+
+      # 将底层异常映射为连接、传输、超时或内部错误，并保留安全上下文。
+      def normalize_error(exception, phase:, command: nil)
+        if exception.is_a?(Error)
+          sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
+          failed_command = exception.command || command&.text
+          if command&.sensitive? || (sensitive && exception.command && exception.command != command&.text)
+            failed_command = "[REDACTED]"
+          end
+          message = safe_error_text(exception.message, sensitive: sensitive)
+          output = safe_error_text(exception.output, sensitive: sensitive)
+          return exception.with_diagnostics(
+            message: message,
+            host: exception.host || configuration.host, phase: exception.phase || phase,
+            command: failed_command && redactor.call(failed_command),
+            source: exception.source || command&.source, line: exception.line || command&.line,
+            output: truncate_output(output),
+            underlying: exception.underlying && UnderlyingError.new(exception.underlying, redactor, sensitive: sensitive)
+          )
+        end
+
+        klass = case exception
+                when Expect::WriteTimeout then WriteTimeout
+                when IOError, SystemCallError, Expect::SpawnError then TransportError
+                else InternalError
+                end
+        build_error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
+      end
+
+      def inspect = "#<#{self.class} state=#{state} host=#{configuration.host.inspect}>"
+
+      private
+
+      # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
+      def perform_locked(phase)
+        @performing = true
+        completed = false
+        begin
+          unless connected?
+            close_resources unless state == :closed
+            connect_session
+          end
+          @state = (phase == :connect) ? :ready : :executing
+          result = yield
+          completed = true
+          result
+        rescue => error
+          failure = normalize_error(error, phase: phase)
+          close_preserving_failure
+          raise failure, cause: nil
+        rescue Exception # rubocop:disable Lint/RescueException -- Interrupts release the transport, then propagate.
+          close_preserving_failure
+          raise
+        ensure
+          # throw/catch 也会离开此块；对话未完成时必须关闭连接，不能把
+          # 半途的设备提示符误当成下一条命令的响应。
+          close_preserving_failure unless completed || !connected?
+          @state = :ready if connected?
+          @performing = false
+        end
+      end
+
       def execute_command_with_logging(command, timeout:, prompt:)
         started = Expect.monotonic
         @log.log_event("command_start")
@@ -224,8 +283,6 @@ module Net
         end
       end
 
-      private :execute_command_with_logging, :elapsed_ms, :log_operation_completion
-
       # 在用户钩子运行前标记敏感上下文，动态交互尚未返回时也能保护其异常。
       def protect_command(command)
         redactor.output_sensitive! if command.output_sensitive?
@@ -235,8 +292,6 @@ module Net
         redactor.remember(command.text) if command.sensitive?
       end
 
-      private :protect_command
-
       # 写入命令、读取对话、识别设备诊断，并返回响应对象。
       def exchange_command(command, timeout:, prompt: nil)
         deadline = Expect.monotonic + (command.timeout || timeout)
@@ -260,109 +315,23 @@ module Net
         end
       end
 
-      private :exchange_command
-
-      # 按截止时间限制传输写入，并统一包装底层错误。
-      def write(bytes, deadline:, phase:, command: nil)
-        remaining = [deadline - Expect.monotonic, 0].max
-        transport.write(bytes, timeout: [remaining, configuration.write_timeout].min)
-      rescue => error
-        raise normalize_error(error, phase: phase, command: command), cause: nil
-      end
-
-      # 人工交互会结束当前连接，未完成的输入行不能在之后重放。
-      def interact(**options)
-        perform(:interact) do
-          @state = :interacting
-          begin
-            transport.interact(**options)
-          ensure
-            $ERROR_INFO ? close_preserving_failure : close_resources
-          end
-        end
-      end
-
-      # 创建带脱敏上下文、阶段、命令和输出尾部的领域错误。
-      def build_error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
-        sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
-        message = safe_error_text(message, sensitive: sensitive)
-        output = safe_error_text(output, sensitive: sensitive)
-        klass.new(message, host: configuration.host, phase: phase,
-                  command: command && (command.sensitive? ? "[REDACTED]" : redactor.call(command.text)),
-                  source: command&.source, line: command&.line,
-                  output: truncate_output(output),
-                  underlying: underlying && UnderlyingError.new(underlying, redactor, sensitive: sensitive), **context)
-      end
-
-      # 将底层异常映射为连接、传输、超时或内部错误，并保留安全上下文。
-      def normalize_error(exception, phase:, command: nil)
-        if exception.is_a?(Error)
-          sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
-          failed_command = exception.command || command&.text
-          if command&.sensitive? || (sensitive && exception.command && exception.command != command&.text)
-            failed_command = "[REDACTED]"
-          end
-          message = safe_error_text(exception.message, sensitive: sensitive)
-          output = safe_error_text(exception.output, sensitive: sensitive)
-          return exception.with_diagnostics(
-            message: message,
-            host: exception.host || configuration.host, phase: exception.phase || phase,
-            command: failed_command && redactor.call(failed_command),
-            source: exception.source || command&.source, line: exception.line || command&.line,
-            output: truncate_output(output),
-            underlying: exception.underlying && UnderlyingError.new(exception.underlying, redactor, sensitive: sensitive)
-          )
-        end
-
-        klass = case exception
-                when Expect::WriteTimeout then WriteTimeout
-                when IOError, SystemCallError, Expect::SpawnError then TransportError
-                else InternalError
-                end
-        build_error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
-      end
-
       # 敏感上下文的任意异常和设备输出可能只包含局部秘密，保留类型和错误码诊断。
       def safe_error_text(text, sensitive:)
         sensitive && !text.to_s.empty? ? "[REDACTED]".b : redactor.call(text)
       end
 
-      private :safe_error_text
-
       # 必须先脱敏再截取尾部，避免截断凭据后逃过完整词匹配。
       def truncate_output(text)
         text.byteslice(-MAX_ERROR_OUTPUT_BYTES, MAX_ERROR_OUTPUT_BYTES) || text
       end
 
-      private :truncate_output
-
-      # 返回不包含凭据的会话状态摘要。
-      def inspect = "#<#{self.class} state=#{state} host=#{configuration.host.inspect}>"
-
-      private
-
       # 建立传输并登录；失败时最多执行一次连接级恢复，然后重试登录。
       def connect_session
         attempted_recovery = false
         begin
           @state = :connecting
           started = Expect.monotonic
-          redactor.reset
-          @log.open(transport)
-          @log.log_event("connect", host: configuration.host, username: configuration.username,
-                     phase: :connect, protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
-          transport.open
-          @state = :authenticating
-          @log.log_event("login_start", level: :debug, phase: :login)
-          response = @authentication.login
-          safe_response = Response.new(raw: redactor.call(response.raw), output: redactor.call(response.output),
-                                       prompt: response.prompt)
-          @prompt = response.prompt
-          @after_login.call(self, safe_response)
-          @log.log_authentication_output(response.raw)
-          @log.log_event("login_complete", status: "ok", prompt: response.prompt, phase: :login, duration_ms: elapsed_ms(started))
-          @log.attach
-          @state = :ready
+          login_once(started)
         rescue => error
           phase = (@state == :connecting) ? :connect : :login
           failure = normalize_error(error, phase: phase)
@@ -379,6 +348,26 @@ module Net
         end
       end
 
+      def login_once(started)
+        redactor.reset
+        @log.open(transport)
+        @log.log_event("connect", host: configuration.host, username: configuration.username,
+                       phase: :connect, protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
+        transport.open
+        @state = :authenticating
+        @log.log_event("login_start", level: :debug, phase: :login)
+        response = @authentication.login
+        transport.authenticated if transport.respond_to?(:authenticated)
+        safe_response = Response.new(raw: redactor.call(response.raw), output: redactor.call(response.output),
+                                     prompt: response.prompt)
+        @prompt = response.prompt
+        @after_login.call(self, safe_response)
+        @log.log_authentication_output(response.raw)
+        @log.log_event("login_complete", status: "ok", prompt: response.prompt, phase: :login, duration_ms: elapsed_ms(started))
+        @log.attach
+        @state = :ready
+      end
+
       # 清除会话状态并关闭传输和日志资源。
       def close_resources
         @state = :closed

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

@@ -2,6 +2,7 @@
 
 require "open3"
 require "expect/pty"
+require_relative "known_hosts"
 
 module Net
   module Connector
@@ -125,6 +126,29 @@ module Net
           @legacy_arguments = legacy_arguments.dup.freeze
         end
 
+        def open
+          configuration.validate_endpoint!
+          unless configuration.host_key_policy == :strict
+            @known_hosts = KnownHosts.new(configuration, replace: @replace_host_key)
+          end
+          super
+        rescue Exception # rubocop:disable Lint/RescueException -- Release a staged trust file on failed startup.
+          close
+          raise
+        end
+
+        def authenticated
+          @known_hosts&.commit
+          @replace_host_key = false
+        end
+
+        def close
+          super
+        ensure
+          @known_hosts&.close
+          @known_hosts = nil
+        end
+
         # 返回 SSH 协议标识。
         def protocol = :ssh
 
@@ -133,9 +157,10 @@ module Net
           configuration.validate_endpoint!
           checking = (configuration.host_key_policy == :strict) ? "yes" : "accept-new"
           arguments = ["ssh", *legacy_arguments, "-tt", "-o", "StrictHostKeyChecking=#{checking}",
-                       "-o", "NumberOfPasswordPrompts=1",
+                       "-o", "NumberOfPasswordPrompts=1", "-o", "UpdateHostKeys=no",
                        "-o", "ConnectTimeout=#{[configuration.login_timeout.ceil, 1].max}"]
-          arguments += ["-o", "UserKnownHostsFile=#{configuration.known_hosts}"] if configuration.known_hosts
+          known_hosts = @known_hosts&.path || configuration.known_hosts
+          arguments += ["-o", "UserKnownHostsFile=#{known_hosts}"] if known_hosts
           arguments += ["-p", configuration.port.to_s] if configuration.port
           arguments + ["-l", configuration.username, configuration.host]
         end
@@ -151,13 +176,13 @@ module Net
           Telnet.new(configuration, channel_factory: @channel_factory, terminal_size: @terminal_size)
         end
 
-        # 从指定 known_hosts 文件中删除当前设备的旧主机密钥。
+        # 恢复只标记下一次会话副本；共享信任文件在认证成功后才更新。
         def replace_host_key
-          host = configuration.host
-          host = "[#{host}]:#{configuration.port}" if configuration.port && configuration.port != 22
-          _output, status = Open3.capture2e("ssh-keygen", "-f", configuration.known_hosts, "-R", host)
-          raise IOError, "removing device host key failed" unless status.success?
+          raise IOError, "host key replacement is not enabled" unless configuration.host_key_policy == :replace
+
+          @replace_host_key = true
         end
+
       end
 
       # Telnet 只能显式启用；SSH 专用端口不能带入回退连接。

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+
+module Net
+  module Connector
+    module Netdisco
+      # 人类批次入口：固定配置、预览、执行、保存报告，最后决定输出与退出码。
+      class BackupRun
+        def initialize(mode: :backup, argv: ARGV, env: ENV, input: $stdin, output: $stdout, error: $stderr)
+          raise ArgumentError, "mode must be backup or tftp" unless %i[backup tftp].include?(mode)
+
+          @mode, @argv, @env, @input, @output, @error = mode, argv, env, input, output, error
+        end
+
+        def run
+          options = CLI::Options.parse(argv: @argv, input: @input, output: @output, error: @error)
+          return 0 if options[:help]
+
+          settings, success_policy, server_root, batch_directory = prepare(options)
+          client, credentials = Connection.build(settings, stdin_credentials: options[:stdin_credentials], input: @input)
+          progress = Progress.new(io: @error, enabled: @env.fetch("NC_PROGRESS", "1") != "0", verbose: options[:verbose])
+          resolver = ->(device) { credentials.call(device)&.merge(on_event: progress.method(:event)) }
+          fleet = Fleet.new(client: client, settings: settings, credentials: resolver, result_store: nil)
+          progress.reading_inventory
+          limit = settings.limit_per_vendor
+          plan = if @mode == :backup
+                   fleet.plan_backup(limit_per_vendor: limit)
+                 else
+                   fleet.plan_tftp_backup(limit_per_vendor: limit, allow_fixed_name_reuse: !server_root.nil?)
+                 end
+          progress.plan(plan, concurrency: settings.concurrency, limit_per_vendor: limit)
+          preview = plan_summary(plan)
+          @output.puts JSON.generate(plan: preview) if options[:json]
+          @output.flush
+          return 1 if options[:stdin_credentials] && @input.gets&.strip != "RUN"
+
+          Storage::PrivateFile.write(File.join(batch_directory, "plan.json"), JSON.pretty_generate(preview))
+          report = execute(fleet, settings, plan, batch_directory, progress, success_policy, server_root)
+          report = Report::Files.write(report, directory: batch_directory, plan: plan, concurrency: settings.concurrency)
+          finish(report, progress, options, batch_directory)
+        rescue ArgumentError, Client::Error => exception
+          @error.puts "备份参数或清单错误：#{exception.message}"
+          2
+        rescue StandardError => exception
+          @error.puts "备份未完成（#{exception.class}）"
+          2
+        end
+
+        private
+
+        def prepare(options)
+          settings = CLI::Options.settings(options, env: @env)
+          success_policy = options.fetch(:success_policy, :selected)
+          raise ArgumentError, "verified policy requires TFTP mode" if success_policy == :verified && @mode != :tftp
+          raise ArgumentError, "--tftp-root requires TFTP mode" if options[:tftp_root] && @mode != :tftp
+          server_root = tftp_root(settings, options) if @mode == :tftp
+          raise ArgumentError, "verified policy requires a local TFTP directory" if success_policy == :verified && !server_root
+          TftpVerification.new(root: server_root) if server_root
+          batch_directory = Storage::BatchDirectory.create(settings.backup_directory)
+          if @mode == :tftp && !settings.log_directory
+            settings = settings.with_overrides("NC_LOG_DIRECTORY" => File.join(batch_directory, "logs"))
+          end
+          settings = settings.for_run(mode: @mode)
+          [settings, success_policy, server_root, batch_directory]
+        end
+
+        def execute(fleet, settings, plan, batch_directory, progress, success_policy, server_root)
+          File.open(File.join(batch_directory, "events.jsonl"), File::WRONLY | File::CREAT | File::EXCL, 0o600) do |events|
+            options = { plan: plan, concurrency: settings.concurrency, success_policy: success_policy,
+                        on_start: progress.method(:start), on_result: result_callback(progress, events) }
+            progress.with_updates do
+              if @mode == :backup
+                fleet.backup_all(directory: batch_directory, filename_style: :hostname_ip, **options)
+              else
+                fleet.tftp_backup_all(server: settings.tftp_server, source_files: settings.tftp_source_files,
+                                      vrfs: settings.tftp_vrfs, report_directory: batch_directory,
+                                      verification_root: server_root, preserve_history: true, **options)
+              end
+            end
+          end
+        end
+
+        def result_callback(progress, events)
+          lock = Mutex.new
+          lambda do |outcome|
+            progress.result(outcome)
+            lock.synchronize do
+              events.puts JSON.generate(host: outcome.device.host, vendor: outcome.device.vendor,
+                                         status: outcome.status, error_code: outcome.diagnostic&.error_code,
+                                         error_type: outcome.diagnostic&.error_type, duration_ms: outcome.duration_ms)
+              events.flush
+            end
+          end
+        end
+
+        def finish(report, progress, options, batch_directory)
+          progress.finish(report)
+          progress.location(report.report_location) if report.report_location
+          @error.puts "文本报告：#{File.join(batch_directory, "summary.txt")}" if @env.fetch("NC_PROGRESS", "1") != "0" && File.file?(File.join(batch_directory, "summary.txt"))
+          if options[:json]
+            @output.puts JSON.generate(directory: batch_directory, counts: report.counts,
+                                       tasks_succeeded: report.policy_success?, success: report.policy_success?,
+                                       policy: report.policy, policy_success: report.policy_success?,
+                                       report_location: report.report_location, report_error: report.report_error)
+          end
+          report.policy_success? ? 0 : 1
+        end
+
+        def tftp_root(settings, options)
+          server = settings.tftp_server || (raise ArgumentError, "TFTP_HOST or YAML tftp.server is required")
+          return options[:tftp_root] || @env["TFTP_ROOT"] if options[:tftp_root] || @env["TFTP_ROOT"]
+          return unless Socket.ip_address_list.any? { |address| address.ip_address == server }
+
+          candidate = File.join(Dir.home, "Documents", "TFTP")
+          candidate if File.directory?(candidate)
+        end
+
+        def plan_summary(plan)
+          { total: plan.inventory.size, ready: plan.inventory.count(&:ready?),
+            vendors: plan.inventory.group_by { |device| device.vendor || :unmapped }.transform_values(&:size),
+            issues: plan.inventory.reject(&:ready?).group_by(&:issue).transform_values(&:size),
+            selected: plan.selected.map do |device|
+              filename = @mode == :backup ? device.backup_filename(style: :hostname_ip) : device.tftp_filename
+              { host: device.host, name: device.name, vendor: device.vendor, backup_filename: filename }
+            end }
+        end
+      end
+    end
+  end
+end

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

@@ -45,7 +45,7 @@ module Net
       Batch = Data.define(:mode, :outcomes, :started_at, :finished_at, :callback_errors,
                           :report_location, :report_error) do
         # 按设备最终状态统计数量。
-        def counts = outcomes.group_by(&:status).transform_values(&:size)
+        def counts = outcomes.map(&:status).tally
 
         # 仅在所有设备成功且回调、报告均正常时判定整批成功。
         def success? = !outcomes.empty? && outcomes.all?(&:success?) && callback_errors.empty? && report_error.nil?