net-connector 0.4.1 → 0.4.2

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

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "expect/redactor"
+
 module Net
   module Connector
-    # 操作错误携带已脱敏上下文；原始配置只存在于明确的结果或日志中。
+    # 操作错误携带已脱敏上下文；敏感配置正文只存在于明确返回的业务结果中。
     class Error < StandardError
       attr_reader :code, :host, :phase, :command, :output, :source, :line, :underlying
 
@@ -48,6 +50,8 @@ module Net
 
     class OutputLimitExceeded < Error; end
 
+    class ScriptOutputLimitExceeded < OutputLimitExceeded; end
+
     class SessionBusy < Error; end
 
     class UnsupportedOperation < Error; end
@@ -72,10 +76,16 @@ module Net
       def inspect = "#<#{self.class} type=#{type}>"
     end
 
-    # 每个会话独立保存脱敏词，包括配置凭据和动态认证响应。
+    # 管理连接器的秘密作用域和输出敏感性；字节过滤统一委托给 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
@@ -83,9 +93,10 @@ module Net
       # 重置动态词表，同时保留配置中的固定凭据。
       def reset
         @secrets = []
-        @pattern = nil
+        @patterns = nil
         @scoped = false
         @sensitive = false
+        @output_sensitive = false
         @configured.each { |secret| remember(secret) }
       end
 
@@ -94,18 +105,20 @@ module Net
         return yield if reuse && @scoped
 
         previous = @secrets
-        previous_pattern = @pattern
+        previous_patterns = @patterns
         previous_scoped = @scoped
         previous_sensitive = @sensitive
+        previous_output_sensitive = @output_sensitive
         @secrets = previous.dup
         @scoped = true
         begin
           yield
         ensure
           @secrets = previous
-          @pattern = previous_pattern
+          @patterns = previous_patterns
           @scoped = previous_scoped
           @sensitive = previous_sensitive
+          @output_sensitive = previous_output_sensitive
         end
       end
 
@@ -115,7 +128,16 @@ module Net
       # 判断当前脱敏范围是否包含敏感交互。
       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?
 
@@ -123,63 +145,26 @@ module Net
         return if @secrets.include?(bytes)
 
         @secrets << bytes.freeze
-        @secrets.sort_by! { |value| -value.bytesize }
-        @pattern = nil
-      end
-
-      # 保留可能跨下一分片的尾部；完整匹配始终作为整体脱敏。
-      def stream_chunk(bytes, final: false)
-        return [call(bytes), "".b] if final || @secrets.empty?
-
-        retained = [@secrets.first.bytesize, "[REDACTED]".bytesize].max - 1
-        boundary = [bytes.bytesize - retained, 0].max
-        matches(bytes).each do |start, finish|
-          if start < boundary && finish > boundary
-            boundary = start
-            break
-          end
-        end
-        [call(bytes.byteslice(0, boundary)), bytes.byteslice(boundary..)]
+        @patterns = nil
       end
 
-      # 单次扫描替换所有敏感词，并保留已有脱敏标记。
+      # 一次性诊断不共享流状态；原标记作为不透明区间，避免再次展开它。
       def call(text)
-        text = text.to_s.b
-        return text if @secrets.empty?
-
-        output = +"".b
-        offset = 0
-        matches(text).each do |start, finish|
-          output << text.byteslice(offset, start - offset) << "[REDACTED]"
-          offset = finish
-        end
-        output << text.byteslice(offset..)
+        Expect::Redactor.redact(text.to_s.b, patterns, replacement: MASK)
       end
 
-      # 返回脱敏器类型摘要。
-      def inspect = "#<#{self.class}>"
-
-      private
-
-      # 前瞻保留重叠匹配；跨标记边界的真实秘密不能被已有标记遮蔽。
-      def pattern
-        @pattern ||= /(?=(#{Regexp.union((@secrets + ["[REDACTED]"]).uniq.sort_by { |secret| -secret.bytesize })}))/n
+      # 每个日志目标独占过滤流，跨分片尾部和重叠掩码由依赖库维护。
+      def stream
+        Expect::Redactor.new(patterns, replacement: MASK)
       end
 
-      # 合并重叠的秘密匹配区间，防止替换顺序露出部分凭据。
-      def matches(text)
-        ranges = []
-        text.to_enum(:scan, pattern).each do
-          match = Regexp.last_match
-          start, finish = match.begin(1), match.end(1)
-          if ranges.last && start < ranges.last.last
-            ranges.last[1] = [ranges.last.last, finish].max
-          else
-            ranges << [start, finish]
-          end
-        end
-        ranges
+      # 临时范围恢复时，日志流可以同步恢复注册词表，不缓存配置正文。
+      def patterns
+        @patterns ||= (@secrets.empty? ? [] : (@secrets + [MASK]).uniq).freeze
       end
+
+      # 返回脱敏器类型摘要。
+      def inspect = "#<#{self.class}>"
     end
   end
 end

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

@@ -18,6 +18,8 @@ module Net
         @prompt = prompt
         @context = {}
         @steps = []
+        @output_bytes = 0
+        @output_limit = session.configuration.max_script_output_bytes
       end
 
       # 依次准备、执行和记录脚本命令；失败时保留已完成步骤并统一抛错。
@@ -30,24 +32,38 @@ module Net
 
             @current_command = command
             started = Expect.monotonic
-            response = query(command)
-            step = CommandResult.new(command: command, output: response.output, prompt: response.prompt,
-                                     duration: Expect.monotonic - started)
-            steps << step
+            step = nil
+            response = query(command) do |received|
+              step = CommandResult.new(command: command, output: received.output, prompt: received.prompt,
+                                       duration: Expect.monotonic - started)
+              steps << step
+            end
             # 设备已经完成命令；后处理失败也不能从部分结果中抹去其副作用。
             @after_command.call(command, response, self)
             yield step if block_given?
+            check_output_budget!(@last_query_command, completed: true)
           rescue => error
             raise @session.normalize_error(error, phase: :script, command: @current_command), cause: nil
           end
         end
+        check_output_budget!(@last_query_command, completed: true)
         Result.new(steps: steps)
       end
 
       # 厂商后续查询复用同一信道和错误处理，不开启新的批处理。
       def query(command)
         command = Command.new(command) unless command.is_a?(Command)
-        @session.exchange(command, timeout: @command_timeout, prompt: @prompt&.call(command))
+        check_output_budget!(command, completed: false)
+        prompt = @prompt&.call(command)
+        # 提示符回调也可能追加查询，实际发送前重新检查它消耗的预算。
+        check_output_budget!(command, completed: false) if @prompt
+        response = @session.exchange(command, timeout: @command_timeout, prompt: prompt)
+        @last_query_command = command
+        @output_bytes += response.raw.bytesize
+        # 主命令先记录完整步骤，再检查超额；追加查询同样计入预算，但不改变原 steps 结构。
+        yield response if block_given?
+        check_output_budget!(command, completed: true)
+        response
       end
 
       # 只有当前会话未特权时才执行特权认证。
@@ -59,6 +75,17 @@ module Net
       def failure(message)
         @session.error(ScriptError, message, phase: :script, command: @current_command)
       end
+
+      private
+
+      # 单响应上限仍约束正在读取的命令；累计预算阻止继续发送，不承诺设备尚未执行。
+      def check_output_budget!(command, completed:)
+        return unless @output_limit && (completed ? @output_bytes > @output_limit : @output_bytes >= @output_limit)
+
+        raise @session.error(ScriptOutputLimitExceeded,
+                             "script output reached max_script_output_bytes; commands already sent may have executed",
+                             phase: :script, command: command), cause: nil
+      end
     end
   end
 end

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

@@ -89,7 +89,7 @@ module Net
 
       # 应用注入的日志器没有终端写入器，改由日志器记录完整回显。
       def response_output(bytes)
-        return unless detailed? && !@writer
+        return unless detailed? && !@writer && !@redactor.output_sensitive?
 
         @redactor.call(TerminalRenderer.render(@redactor.call(bytes))).each_line do |line|
           @logger.debug("#{@tag}  #{line.chomp}") if ::Logger::DEBUG >= @event_level
@@ -169,18 +169,17 @@ module Net
 
       # 文件写入边界保留短尾部，避免分片或终端控制符拼出明文凭据。
       class RedactingWriter
-        # 保存目标流、脱敏器和等待下一分片的尾部。
+        # 保存目标与作用域；每个日志目标独占 expect-pty 的过滤流。
         def initialize(target, redactor)
           @target = target
           @redactor = redactor
-          @pending = "".b
+          @filter = redactor.stream
         end
 
         # 写入已确认安全的前缀，暂存可能与下一分片组成秘密的尾部。
         def write(bytes)
-          @pending << bytes.b
-          safe, @pending = @redactor.stream_chunk(@pending)
-          @target.write(safe)
+          @filter.patterns = @redactor.patterns
+          @target.write(@filter.append(bytes.b))
           bytes.bytesize
         end
 
@@ -189,11 +188,13 @@ module Net
 
         # 在日志结束时脱敏并写出剩余尾部。
         def finish
-          safe, @pending = @redactor.stream_chunk(@pending, final: true)
-          @target.write(safe)
+          @filter.patterns = @redactor.patterns
+          # 保留旧日志的完整词匹配契约；配置正文由 Session 的敏感范围直接隔离。
+          @target.write(@filter.finish(partial: false))
           flush
         end
       end
+
       private_constant :RedactingWriter
 
       # 以私有权限打开设备日志文件。
@@ -224,7 +225,8 @@ module Net
 
       # 将日志异常包装成统一错误并保留脱敏原因。
       def failure(message, error)
-        LogError.new(message, phase: :logging, underlying: UnderlyingError.new(error, @redactor))
+        LogError.new(message, phase: :logging,
+                     underlying: UnderlyingError.new(error, @redactor, sensitive: @redactor.sensitive?))
       end
     end
   end

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

@@ -10,6 +10,8 @@ module Net
   module Connector
     # 连接状态、传输层和日志的唯一所有者；同一时刻只允许一个操作占用会话。
     class Session
+      MAX_ERROR_OUTPUT_BYTES = 4096
+
       attr_reader :configuration, :transport, :reader, :redactor, :state, :prompt
 
       # 创建认证、响应读取、脱敏和日志对象，并把会话置于关闭状态。
@@ -75,6 +77,13 @@ module Net
         end
       end
 
+      # 文件业务必须先取得路径锁，再调用会话；不能持有会话租约去等待另一个备份者。
+      def assert_path_lock_order!(phase)
+        return unless @lock.locked?
+
+        raise error(SessionBusy, "backup path ownership must be acquired before a session operation", phase: phase), cause: nil
+      end
+
       # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
       def perform_locked(phase)
         @performing = true
@@ -140,6 +149,19 @@ module Net
         end
       end
 
+      # 批次准备和最终清理也可能读取配置；在作用域退出前归一化其异常，
+      # 防止清理钩子的消息或回溯将已完成步骤中的正文带回诊断通道。
+      def output_scope(enabled)
+        return yield unless enabled
+
+        redactor.scope do
+          redactor.output_sensitive!
+          yield
+        rescue => error
+          raise normalize_error(error, phase: :script), cause: nil
+        end
+      end
+
       # 复用完整命令的脱敏范围；厂商后续查询产生的秘密保留到外层回调结束。
       def exchange(command, timeout:, prompt: nil)
         redactor.scope(reuse: true) do
@@ -147,9 +169,10 @@ module Net
           started = Expect.monotonic
           @log.event("command_start", text: command.sensitive? ? "[REDACTED]" : command.text)
           sensitive_dialogue = [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
-          @log.event("device_output", level: :debug) if @log.detailed? && !command.sensitive? && !sensitive_dialogue
+          private_output = command.sensitive? || redactor.output_sensitive? || sensitive_dialogue
+          @log.event("device_output", level: :debug) if @log.detailed? && !private_output
           response = exchange_command(command, timeout: timeout, prompt: prompt)
-          @log.response_output(response.raw) unless command.sensitive? || sensitive_dialogue
+          @log.response_output(response.raw) unless private_output
           @log.event("command_complete", status: "response_received")
           @log.event("command_detail", level: :debug,
                      duration_ms: ((Expect.monotonic - started) * 1000).round,
@@ -165,6 +188,7 @@ module Net
 
       # 在用户钩子运行前标记敏感上下文，动态交互尚未返回时也能保护其异常。
       def protect_command(command)
+        redactor.output_sensitive! if command.output_sensitive?
         if command.sensitive? || [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
           redactor.sensitive!
         end
@@ -189,7 +213,7 @@ module Net
 
           response
         end
-        if command.sensitive? || interactions.any?(&:sensitive?)
+        if command.sensitive? || redactor.output_sensitive? || interactions.any?(&:sensitive?)
           @log.pause(&operation)
         else
           operation.call
@@ -220,20 +244,20 @@ module Net
 
       # 创建带脱敏上下文、阶段、命令和输出尾部的领域错误。
       def error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
-        sensitive = redactor.sensitive? || command&.sensitive?
+        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: output.byteslice(-4096, 4096) || output,
+                  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?
+          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]"
@@ -245,7 +269,7 @@ module Net
             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: output.byteslice(-4096, 4096) || output,
+            output: truncate_output(output),
             underlying: exception.underlying && UnderlyingError.new(exception.underlying, redactor, sensitive: sensitive)
           )
         end
@@ -265,6 +289,13 @@ module Net
 
       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}>"
 

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

@@ -8,20 +8,21 @@ module Net
     # 把终端编辑控制符渲染成可读、兼容 UTF-8 和二进制的逐行日志。
     class TerminalRenderer
       # 将字节流完整渲染为字符串，供测试和一次性转换使用。
-      def self.render(input)
+      def self.render(input, strict_utf8: false)
         output = StringIO.new("".b)
-        renderer = new(output)
+        renderer = new(output, strict_utf8: strict_utf8)
         renderer.write(input)
         renderer.finish
         output.string
       end
 
       # 初始化当前行、光标和转义序列状态。
-      def initialize(target, max_line_bytes: 32 * 1024 * 1024)
+      def initialize(target, max_line_bytes: 32 * 1024 * 1024, strict_utf8: false)
         raise ArgumentError, "target must respond to write" unless target.respond_to?(:write)
         unless max_line_bytes.is_a?(Integer) && max_line_bytes.positive?
           raise ArgumentError, "max_line_bytes must be positive"
         end
+        raise ArgumentError, "strict_utf8 must be true or false" unless [true, false].include?(strict_utf8)
 
         @target = target
         @line = "".b
@@ -29,6 +30,7 @@ module Net
         @escape_state = nil
         @csi_parameters = "".b
         @max_line_bytes = max_line_bytes
+        @strict_utf8 = strict_utf8
       end
 
       # 逐字节消费终端输出，并返回输入字节数。
@@ -146,10 +148,11 @@ module Net
         @cursor = 0
       end
 
-      # 尽量保持有效 UTF-8；非法字节转义为可读的十六进制文本。
+      # 日志把非法字节转义；解析必须拒绝终端编辑产生的损坏字节，不能制造可写业务证据。
       def utf8_safe(line)
         text = line.dup.force_encoding(Encoding::UTF_8)
         return text.b if text.valid_encoding?
+        raise Encoding::InvalidByteSequenceError, "terminal editing produced invalid UTF-8" if @strict_utf8
 
         text.scrub { |invalid| invalid.bytes.map { |byte| format("\\x%02X", byte) }.join }.b
       end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "time"
+require_relative "diagnostic"
 
 module Net
   module Connector
@@ -8,9 +9,29 @@ module Net
       # 单台设备的最终结果，保留状态、配置产物和错误类型。
       Outcome = Data.define(:device, :status, :backup, :error_code, :error_type,
                             :started_at, :finished_at) do
+        attr_reader :diagnostic
+
         # 创建结果，允许计划阶段尚无执行时间。
-        def initialize(device:, status:, backup:, error_code:, error_type:, started_at: nil, finished_at: nil)
-          super
+        def initialize(device:, status:, backup:, error_code:, error_type:, started_at: nil, finished_at: nil,
+                       duration_ms: nil, diagnostic: nil)
+          unless duration_ms.nil? || (duration_ms.is_a?(Numeric) && duration_ms.real? && duration_ms.finite? && duration_ms >= 0)
+            raise ArgumentError, "duration_ms must be nonnegative and finite"
+          end
+          raise ArgumentError, "diagnostic must be a Diagnostic" unless diagnostic.nil? || diagnostic.instance_of?(Diagnostic)
+
+          @duration_ms, @diagnostic = duration_ms, diagnostic
+          super(device: device, status: status, backup: backup, error_code: error_code, error_type: error_type,
+                started_at: started_at, finished_at: finished_at)
+        end
+
+        # Data 成员保持不变；Worker 加上时间、旧文件迁移调整产物时仍保留内部元数据。
+        def with(**attributes)
+          return self if attributes.empty?
+
+          metadata = { duration_ms: @duration_ms, diagnostic: diagnostic }
+          metadata[:duration_ms] = nil if attributes.key?(:started_at) || attributes.key?(:finished_at)
+          metadata[:diagnostic] = nil if attributes.key?(:error_code) || attributes.key?(:error_type)
+          self.class.new(**to_h, **metadata.merge(attributes))
         end
 
         # 判断设备是否完成配置保存或上报上传成功。
@@ -24,7 +45,9 @@ module Net
 
         # 计算设备任务的耗时，计划阶段没有时间时返回空值。
         def duration_ms
-          ((finished_at - started_at) * 1000).round if started_at && finished_at
+          return @duration_ms unless @duration_ms.nil?
+
+          [((finished_at - started_at) * 1000).round, 0].max if started_at && finished_at
         end
       end
 
@@ -40,6 +63,9 @@ module Net
         # 空清单与已尝试但未全部成功的批次分别标记。
         def status = outcomes.empty? ? :no_devices : (success? ? :succeeded : :incomplete)
 
+        # 单独请求 v2 包装，不改变旧 Data 的成员、解构或默认 summary。
+        def report(policy: :strict) = Report.new(self, policy: policy)
+
         # 生成可写入报告及供命令行展示的结构化摘要。
         def summary
           {
@@ -66,6 +92,8 @@ module Net
           }
         end
       end
+
+      autoload :Report, File.expand_path("report", __dir__)
     end
   end
 end