net-connector 0.7.3 → 0.9.0

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

@@ -39,7 +39,7 @@ module Net
           open_transcript if @io && @configuration.log_level == :debug
         end
       rescue => error
-        close_preserving_error
+        close_preserving_failure
         raise build_error("unable to open session log", error), cause: nil
       end
 
@@ -49,9 +49,14 @@ module Net
         finish_output
         @context = @context.merge(fields).freeze
         yield
+      rescue Exception # rubocop:disable Lint/RescueException -- 保留从当前作用域向外传播的故障，包括中断。
+        failed = true
+        raise
       ensure
         begin
           finish_output
+        rescue Exception # rubocop:disable Lint/RescueException -- 收尾故障或中断不能覆盖当前作用域的原始失败。
+          raise unless failed
         ensure
           @context = previous
         end
@@ -98,6 +103,9 @@ module Net
                   code: ErrorMetadata.code(failure.code),
                   phase: ErrorMetadata.phase(failure.phase) || ErrorMetadata.phase(phase),
                   message: failure.message)
+      rescue Error
+        # 原始失败已由调用者保留；诊断通道故障不能替换登录、命令或业务错误。
+        nil
       end
 
       # 用户钩子可能把未登记的配置片段放进事件名、字段名或值；敏感范围统一隐藏。
@@ -163,8 +171,16 @@ module Net
         finish_output
         @transport.log_output = nil if @transport
         yield
+      rescue Exception # rubocop:disable Lint/RescueException -- 恢复日志接线，不覆盖当前作用域的故障或中断。
+        failed = true
+        raise
       ensure
-        @transport.log_output = self if @transport && @writer && @attached
+        begin
+          @transport.log_output = self if @transport && @writer && @attached
+        rescue Exception # rubocop:disable Lint/RescueException -- 接线恢复故障或中断不能覆盖原始操作异常。
+          # 恢复接线仍须尝试，但不能盖掉设备失败或用户中断。
+          raise unless failed
+        end
       end
 
       # 断开回显记录并关闭日志资源。
@@ -172,9 +188,14 @@ module Net
         begin
           @transport.log_output = nil if @transport
           finish_output
+        rescue Exception # rubocop:disable Lint/RescueException -- 脱离日志或刷新失败后仍须关闭文件并清除状态。
+          failed = true
+          raise
         ensure
           begin
             @io&.close
+          rescue Exception # rubocop:disable Lint/RescueException -- 文件关闭不能覆盖首个日志收尾故障或中断。
+            raise unless failed
           ensure
             @writer = @output = @transcript = @logger = @io = @transport = @session_id = nil
             @attached = false
@@ -233,10 +254,10 @@ module Net
           file.binmode
           file.write("\n") if file.size.positive? && @configuration.log_format == :text
           file
-        rescue Exception # rubocop:disable Lint/RescueException -- Release partially configured files on interrupts too.
+        rescue Exception # rubocop:disable Lint/RescueException -- 中断时也释放尚未完成设置的文件。
           begin
             file.close
-          rescue
+          rescue Exception # rubocop:disable Lint/RescueException -- 保留文件设置的原始故障或中断。
             # 保留设置失败的原始原因。
           end
           raise
@@ -244,9 +265,9 @@ module Net
       end
 
       # 在日志打开失败后尽力释放资源。
-      def close_preserving_error
+      def close_preserving_failure
         close
-      rescue
+      rescue Exception # rubocop:disable Lint/RescueException -- 清理故障或中断不能覆盖日志打开失败。
         nil
       end
 

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

@@ -48,7 +48,7 @@ module Net
         @rules.freeze
       end
 
-      # 依次尝试恢复规则，并只返回第一个新传输对象。
+      # 依次尝试恢复规则，只采用首个可用传输；密钥替换可以复用原对象。
       def recover(error, transport)
         @rules.lazy.filter_map { |rule| rule.recover(error, transport) }.first
       end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "expect/redactor"
+
+module Net
+  module Connector
+    # 管理连接器的秘密作用域和输出敏感性；字节过滤统一委托给 expect-pty。
+    class Redactor
+      MASK = "[REDACTED]".b.freeze
+
+      # 保存初始凭据，并建立第一版脱敏词表。
+      def initialize(*secrets)
+        unless Expect.constants(false).include?(:Redactor) && Expect::Redactor.respond_to?(:redact)
+          raise LoadError, "net-connector requires expect-pty with the public Expect::Redactor API"
+        end
+
+        @configured = secrets.compact.map(&:b).map(&:freeze).freeze
+        reset
+      end
+
+      # 重置动态词表，同时保留配置中的固定凭据。
+      def reset
+        @secrets = []
+        @patterns = nil
+        @scoped = false
+        @sensitive = false
+        @output_sensitive = false
+        @configured.each { |secret| remember(secret) }
+      end
+
+      # 临时命令响应在错误归一化期间保留，离开作用域后不进入长期会话。
+      def with_scope(reuse: false)
+        return yield if reuse && @scoped
+
+        previous = @secrets
+        previous_patterns = @patterns
+        previous_scoped = @scoped
+        previous_sensitive = @sensitive
+        previous_output_sensitive = @output_sensitive
+        @secrets = previous.dup
+        @scoped = true
+        begin
+          yield
+        ensure
+          @secrets = previous
+          @patterns = previous_patterns
+          @scoped = previous_scoped
+          @sensitive = previous_sensitive
+          @output_sensitive = previous_output_sensitive
+        end
+      end
+
+      # 敏感命令和交互的异常可能只引用秘密的一部分，不能只依赖完整词匹配。
+      def sensitive! = @sensitive = true
+
+      # 判断当前脱敏范围是否包含敏感交互。
+      def sensitive? = @sensitive
+
+      # 输出敏感时不把正文加入词表；只在当前范围内屏蔽日志和任意错误正文。
+      def output_sensitive!
+        @output_sensitive = true
+        sensitive!
+      end
+
+      # 后续查询继承输出边界，即使查询命令本身没有敏感标记。
+      def output_sensitive? = @output_sensitive
+
+      # 只维护当前作用域的注册词；匹配次序和重叠区间交给共享过滤器。
+      def remember(secret)
+        return if secret.nil? || secret.empty?
+
+        bytes = secret.b
+        return if @secrets.include?(bytes)
+
+        @secrets << bytes.freeze
+        @patterns = nil
+      end
+
+      # 一次性诊断不共享流状态；原标记作为不透明区间，避免再次展开它。
+      def call(text)
+        Expect::Redactor.redact(text.to_s.b, patterns, replacement: MASK)
+      end
+
+      # 每个日志目标独占过滤流，跨分片尾部和重叠掩码由依赖库维护。
+      def stream
+        Expect::Redactor.new(patterns, replacement: MASK)
+      end
+
+      # 临时范围恢复时，日志流可以同步恢复注册词表，不缓存配置正文。
+      def patterns
+        @patterns ||= (@secrets.empty? ? [] : (@secrets + [MASK]).uniq).freeze
+      end
+
+      # 返回脱敏器类型摘要。
+      def inspect = "#<#{self.class}>"
+    end
+  end
+end

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "expect/pty"
+require_relative "dialogue"
+
+module Net
+  module Connector
+    # 在传输层上执行有界对话；收到字节或分页标记不会重置截止时间。
+    class ResponseReader
+      # 保存会话引用，以便读取器使用传输、配置和脱敏上下文。
+      def initialize(session)
+        @session = session
+      end
+
+      # 读取到结束提示、失败模式或超时，并处理交互响应和输出上限。
+      def read(prompt:, interactions:, phase:, timeout: nil, deadline: nil, command: nil, failures: {})
+        deadline ||= Expect.monotonic + timeout
+        patterns = [*failures.keys, *interactions.map(&:pattern), prompt]
+        raw = []
+        output = []
+        counts = Hash.new(0)
+        bytes = 0
+        loop do
+          event = read_event(patterns, deadline)
+          raw << event.before unless event.before.empty?
+          output << event.before unless event.before.empty?
+          bytes += event.before.bytesize + event.match.bytesize
+          validate_event!(event, bytes, raw, phase, command)
+
+          if event.index == patterns.size
+            raw << event.match
+            output << event.match
+          elsif event.index == patterns.size - 1
+            return finish_response(event.match, raw, output, phase, command)
+          elsif event.index < failures.size
+            raise build_connection_error(failures.values.fetch(event.index), phase, command), cause: nil
+          else
+            reply = interactions.fetch(event.index - failures.size)
+            raw << event.match
+            output << event.match if reply.capture?
+            respond(reply, event.match, counts, deadline, phase, command)
+          end
+          next if Expect.monotonic < deadline
+
+          raise build_read_error(nil, phase, command, raw.join), cause: nil
+        end
+      end
+
+      private
+
+      # 分页和流式输出只消耗剩余时间，不为下一次读取重新计时。
+      def read_event(patterns, deadline)
+        @session.transport.read(patterns, timeout: [deadline - Expect.monotonic, 0].max)
+      end
+
+      # 连接失败模式携带稳定错误码，供连接级恢复规则选择处理方式。
+      def build_connection_error(failure, phase, command)
+        klass, code = failure
+        @session.build_error(klass, "device connection failed (#{code})", phase: phase, code: code, command: command)
+      end
+
+      # 先限制原始字节数，再处理传输失败，避免错误输出绕过总量限制。
+      def validate_event!(event, bytes, raw, phase, command)
+        if bytes > @session.configuration.max_output_bytes
+          raise @session.build_error(OutputLimitExceeded, "device output exceeded max_output_bytes",
+                                     phase: phase, command: command, output: (raw + [event.match]).join), cause: nil
+        end
+        raise build_read_error(event, phase, command, raw.join), cause: nil unless event.matched?
+      end
+
+      # 完整提示符必须消费字节；交互标记可从业务输出排除，但原始响应始终保留。
+      def finish_response(prompt, raw, output, phase, command)
+        if prompt.empty?
+          raise @session.build_error(PromptError, "prompt pattern did not consume any output",
+                                     phase: phase, command: command, output: raw.join), cause: nil
+        end
+
+        raw << prompt
+        output << prompt
+        raw_text = raw.join
+        Response.new(raw: raw_text, output: (output == raw) ? raw_text : output.join, prompt: prompt)
+      end
+
+      # 重复提示和缺失应答必须在写入前失败；所有应答共用读取操作的截止时间。
+      def respond(reply, prompt, counts, deadline, phase, command)
+        counts[reply] += 1
+        if prompt.empty? || (reply.limit && counts[reply] > reply.limit)
+          raise build_interaction_error("response rejected or repeated", phase, command), cause: nil
+        end
+
+        value = interaction_response(reply, prompt, phase, command)
+        raise build_interaction_error("response unavailable", phase, command), cause: nil unless value.is_a?(String)
+
+        @session.redactor.remember(value.chomp) if reply.sensitive?
+        @session.write(value, deadline: deadline, phase: phase, command: command)
+      end
+
+      # 动态口令尚未返回时无法加入词表，须在敏感范围内先归一化回调异常。
+      # 成功后由调用方登记响应，临时敏感标记不会影响后续普通命令的诊断。
+      def interaction_response(reply, prompt, phase, command)
+        return reply.response(prompt) unless reply.sensitive?
+
+        @session.redactor.with_scope(reuse: true) do
+          @session.redactor.sensitive!
+          reply.response(prompt)
+        rescue => error
+          raise @session.normalize_error(error, phase: phase, command: command), cause: nil
+        end
+      end
+
+      # 将交互拒绝或响应缺失转换为认证或脚本错误。
+      def build_interaction_error(message, phase, command)
+        authenticating = %i[login enable].include?(phase)
+        klass = authenticating ? AuthenticationError : ScriptError
+        label = authenticating ? "authentication" : "command interaction"
+        @session.build_error(klass, "#{label} #{message}", phase: phase, command: command)
+      end
+
+      # 根据 EOF、提示符、阶段和底层异常选择具体读取错误类型。
+      def build_read_error(event, phase, command, output)
+        if event&.error.is_a?(Exception)
+          return @session.build_error(TransportError, "transport read failed", phase: phase, command: command,
+                                      underlying: event.error, output: output)
+        end
+        klass = if event&.error == :eof
+                  ConnectionClosed
+                elsif command&.prompt
+                  PromptError
+                elsif %i[login enable].include?(phase)
+                  LoginTimeout
+                else
+                  CommandTimeout
+                end
+        @session.build_error(klass, "device response #{event&.error || :timeout}", phase: phase,
+                             command: command, output: output)
+      end
+    end
+  end
+end

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

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-require "English"
 require_relative "authentication"
 require_relative "log"
+require_relative "redactor"
+require_relative "response_reader"
 require_relative "recovery"
 require_relative "transport"
 
@@ -45,12 +46,14 @@ module Net
           started = Expect.monotonic
           @log.log_event("operation_start", level: :debug, phase: :script)
           result = yield
-          log_operation_completion(started, result.is_a?(Result) ? result.error : nil, steps: steps.size)
-          result
         rescue => error
           failure = normalize_error(error, phase: :script)
           log_operation_completion(started, failure, steps: steps.size)
           raise failure, cause: nil
+        else
+          # 完成事件只发送一次；观察者失败由外层保留业务结果，不再次调用同一观察者。
+          log_operation_completion(started, result.is_a?(Result) ? result.error : nil, steps: steps.size)
+          result
         end
       end
 
@@ -178,8 +181,11 @@ module Net
           @state = :interacting
           begin
             transport.interact(**options)
+          rescue Exception # rubocop:disable Lint/RescueException -- 交互失败或中断后仍关闭会话，保留本次原始异常。
+            failed = true
+            raise
           ensure
-            $ERROR_INFO ? close_preserving_failure : close_resources
+            failed ? close_preserving_failure : close_resources
           end
         end
       end
@@ -245,7 +251,7 @@ module Net
           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.
+        rescue Exception # rubocop:disable Lint/RescueException -- 中断先释放传输资源，再继续向外传播。
           close_preserving_failure
           raise
         ensure
@@ -380,8 +386,15 @@ module Net
         @prompt = nil
         begin
           transport.close
+        rescue Exception # rubocop:disable Lint/RescueException -- 传输关闭失败或中断后仍须尝试关闭日志。
+          failed = true
+          raise
         ensure
-          @log.close
+          begin
+            @log.close
+          rescue Exception # rubocop:disable Lint/RescueException -- 日志收尾不能覆盖传输关闭的首个失败。
+            raise unless failed
+          end
         end
         nil
       rescue => error
@@ -391,7 +404,7 @@ module Net
       # 尝试清理资源但不覆盖原始操作异常。
       def close_preserving_failure
         close_resources
-      rescue
+      rescue Exception # rubocop:disable Lint/RescueException -- 原操作失败时，清理故障或中断均不得覆盖它。
         # 所有清理路径完成后，原始操作异常仍然是权威结果。
         nil
       end

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

@@ -65,12 +65,8 @@ module Net
             @channel.spawn(*argv)
           end
           self
-        rescue Exception # rubocop:disable Lint/RescueException -- A half-open PTY must be released on interrupts.
-          begin
-            close
-          rescue
-            # 尝试释放半打开信道后，仍然抛出原始失败。
-          end
+        rescue Exception # rubocop:disable Lint/RescueException -- 中断时也必须释放尚未完成初始化的 PTY。
+          close_preserving_failure
           raise
         end
 
@@ -120,6 +116,13 @@ module Net
 
         private
 
+        # 已有操作异常时仍尝试清理；次级故障或中断不能覆盖原始失败。
+        def close_preserving_failure
+          close
+        rescue Exception # rubocop:disable Lint/RescueException -- 清理后继续传播原始操作异常。
+          nil
+        end
+
         # 检查缓冲上限并把设备输出写入当前日志目标。
         def write_log_output(bytes)
           if @channel.buffer.bytesize > configuration.max_output_bytes
@@ -148,8 +151,8 @@ module Net
             @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
+        rescue Exception # rubocop:disable Lint/RescueException -- 启动失败或中断时释放临时信任文件。
+          close_preserving_failure
           raise
         end
 
@@ -159,10 +162,18 @@ module Net
         end
 
         def close
+          known_hosts = @known_hosts
+          @known_hosts = nil
           super
+        rescue Exception # rubocop:disable Lint/RescueException -- 全部资源均须尝试关闭，保留首个失败或中断。
+          failed = true
+          raise
         ensure
-          @known_hosts&.close
-          @known_hosts = nil
+          begin
+            known_hosts&.close
+          rescue Exception # rubocop:disable Lint/RescueException -- 信任文件收尾不能覆盖传输关闭的原始异常。
+            raise unless failed
+          end
         end
 
         # 返回 SSH 协议标识。

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

@@ -2,25 +2,33 @@
 
 require "json"
 require "socket"
+require_relative "cli/options"
+require_relative "connection"
+require_relative "fleet"
+require_relative "progress"
+require_relative "report/files"
+require_relative "../storage/batch_directory"
 
 module Net
   module Connector
     module Netdisco
       # 人类批次入口：固定配置、预览、执行、保存报告，最后决定输出与退出码。
       class BackupRun
+        # 保存批次模式与调用方 IO，构造阶段不读取清单、不创建目录。
         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])
+          progress = Progress.new(io: @error, enabled: !options[:no_progress], 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
@@ -38,8 +46,9 @@ module Net
 
           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 = record_progress_error(report, progress)
           report = Report::Files.write(report, directory: batch_directory, plan: plan, concurrency: settings.concurrency)
-          finish(report, progress, options, batch_directory)
+          finish(report, progress, options, batch_directory, plan, settings.concurrency)
         rescue ArgumentError, Client::Error => exception
           @error.puts "备份参数或清单错误：#{exception.message}"
           2
@@ -50,8 +59,9 @@ module Net
 
         private
 
+        # 预检完成后才创建批次目录；补充日志路径时保持原策略快照与动态凭据来源。
         def prepare(options)
-          settings = CLI::Options.settings(options, env: @env)
+          settings = CLI::Options.settings(options, env: @env).for_run(mode: @mode)
           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
@@ -62,10 +72,10 @@ module Net
           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,
@@ -82,6 +92,7 @@ module Net
           end
         end
 
+        # 将任务结果追加到私有事件流并更新进度；异常由工作线程保留为回调诊断。
         def result_callback(progress, events)
           lock = Mutex.new
           lambda do |outcome|
@@ -95,10 +106,17 @@ module Net
           end
         end
 
-        def finish(report, progress, options, batch_directory)
+        # 报告先保存，再显示完成信息；终端收尾失败只补写诊断，不重放任务。
+        def finish(report, progress, options, batch_directory, plan, concurrency)
           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"))
+          summary_path = File.join(batch_directory, "summary.txt")
+          progress.location(summary_path, label: "文本报告") if File.file?(summary_path)
+          updated = record_progress_error(report, progress)
+          unless updated.equal?(report)
+            # 末尾显示也可能首次失败，只补写诊断，不重复设备任务或事件。
+            report = Report::Files.write(updated, directory: batch_directory, plan: plan, concurrency: concurrency)
+          end
           if options[:json]
             @output.puts JSON.generate(directory: batch_directory, counts: report.counts,
                                        tasks_succeeded: report.policy_success?, success: report.policy_success?,
@@ -108,15 +126,24 @@ module Net
           report.policy_success? ? 0 : 1
         end
 
+        # 输出故障只记录一次，保留已有批次结果和回调错误。
+        def record_progress_error(report, progress)
+          return report unless progress.output_error && !report.callback_errors.include?(progress.output_error)
+
+          report.with(callback_errors: [*report.callback_errors, progress.output_error].freeze)
+        end
+
+        # 优先使用显式核验根目录；仅服务器是本机地址时探测本机惯用 TFTP 目录。
         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"]
+          server = settings.tftp_server || (raise ArgumentError, "YAML tftp.server is required")
+          return options[:tftp_root] || settings.tftp_root if options[:tftp_root] || settings.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),