net-connector 0.6.0 → 0.7.0

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

@@ -25,13 +25,10 @@ module Net
 
       attr_reader :configuration, :command_timeout
 
-      # 将连接状态查询委托给当前设备会话。
       def_delegators :@session, :connected?, :privileged?, :state
-      # 将设备地址、账号和日志路径委托给连接配置。
       def_delegators :@configuration, :host, :username, :log_file
 
       class << self
-        # 读取或声明连接器的厂商标识。
         def vendor(key = nil)
           return @vendor = key if key
 
@@ -98,7 +95,6 @@ module Net
       # 返回当前连接器使用的不可变设备档案，便于检查厂商声明。
       def profile = self.class.profile || Profile.default
 
-      # 读取或声明连接器的厂商标识。
       def vendor = self.class.vendor
 
       # 只查询实现能力，不连接设备；不代表现场权限或固件验证成功。
@@ -141,7 +137,7 @@ module Net
       end
 
       # 多步骤业务操作独占当前会话，内部脚本仍禁止回调重入。
-      def with_operation(name, &block) = @session.with_operation(name, &block)
+      def with_operation(name, &) = @session.with_operation(name, &)
 
       # 业务层可扩展脚本准备、响应校验和最终结果，所有钩子均在会话锁内执行。
       def execute_operation(script, name:, prompt: nil, after_command: nil, privilege: true, &finalize)
@@ -168,48 +164,36 @@ module Net
         @session.interact(input: input, output: output, escape: escape, timeout: timeout)
       end
 
-      # 返回不包含凭据的连接状态摘要。
       def inspect = "#<#{self.class} host=#{host.inspect} state=#{state}>"
 
       protected
 
-      # 匹配设备分页提示，供对话层自动发送翻页响应。
       def pager_pattern = profile.pager_pattern
 
-      # 返回分页提示对应的响应字节。
       def pager_response = profile.pager_response
 
-      # 匹配密码输入提示。
       def password_prompt = profile.password_prompt
 
-      # 匹配用户名输入提示。
       def username_prompt = profile.username_prompt
 
-      # 返回认证失败的设备输出模式。
       def authentication_error_patterns = profile.authentication_error_patterns
 
-      # 返回命令失败的设备输出模式。
       def command_error_patterns = profile.command_error_patterns
 
       # 返回命令期间需要自动应答的确认对话。
-      def confirmation_dialogues = profile.confirmation_interactions
+      def confirmation_interactions = profile.confirmation_interactions
 
       # 返回登录期间需要自动应答的附加对话。
-      def login_dialogues = profile.login_interactions
+      def login_interactions = profile.login_interactions
 
-      # 返回旧版 SSH 恢复使用的协商参数。
       def legacy_ssh_arguments = profile.legacy_ssh_arguments
 
-      # 返回进入特权模式的命令；nil 表示不支持。
       def enable_command = profile.privilege_command
 
-      # 匹配特权模式提示符。
       def enable_prompt = profile.privilege_prompt
 
-      # 返回默认单条命令超时秒数。
       def default_command_timeout = profile.command_timeout
 
-      # 返回可选终端大小。
       def terminal_size = profile.terminal_size
 
       # 返回登录完成提示；厂商必须实现。
@@ -252,9 +236,9 @@ module Net
           login_prompt: login_prompt, command_prompt: command_prompt,
           password_prompt: password_prompt, username_prompt: username_prompt, enable_prompt: enable_prompt,
           authentication_errors: authentication_error_patterns, command_errors: command_error_patterns,
-          login_interactions: login_dialogues,
+          login_interactions: login_interactions,
           command_interactions: [Interaction.new(pager_pattern, pager_response, capture: false),
-                                 *confirmation_dialogues]
+                                 *confirmation_interactions]
         )
       end
 
@@ -263,34 +247,42 @@ module Net
                          finalize: nil, &on_step)
         return Result.new if script.empty?
 
-        finish_step = lambda do |command, response, context|
-          self.after_command(command, response, context)
-          after_command&.call(command, response, context)
-        end
-        execution = Execution.new(session: @session, timeout: command_timeout,
-                                  prepare: method(:prepare_command), after_command: finish_step, prompt: prompt)
-        execution.context[:operation] = operation if operation
-        execution.context[:privilege] = privilege
+        execution = build_execution(operation: operation, prompt: prompt, after_command: after_command, privilege: privilege)
         output_sensitive = script.any?(&:output_sensitive?)
         @session.perform(:script) do
           @session.log_script(operation: operation, steps: execution.steps) do
             @session.with_sensitive_output(output_sensitive) { before_batch(execution) }
             result = execution.execute_script(script, &on_step)
-            private_result = output_sensitive || script.any?(&:sensitive?) || execution.sensitive?
-            @session.with_sensitive_output(private_result) do
-              result = finalize ? finalize.call(result) : result
-              # 回调也可直接返回失败；与抛错共用脱敏边界，保留已完成步骤及业务配置。
-              if result.is_a?(Result) && result.failure?
-                result = Result.new(steps: result.steps, config: result.config,
-                                    error: @session.normalize_error(result.error, phase: :script))
-              end
-              result
+            sensitive_result = output_sensitive || script.any?(&:sensitive?) || execution.sensitive?
+            @session.with_sensitive_output(sensitive_result) do
+              finalize_script_result(result, finalize)
             end
           end
         end
       rescue Error => error
         Result.new(steps: execution ? execution.steps : [], error: error)
       end
+
+      def build_execution(operation:, prompt:, after_command:, privilege:)
+        finish_step = lambda do |command, response, context|
+          self.after_command(command, response, context)
+          after_command&.call(command, response, context)
+        end
+        execution = Execution.new(session: @session, timeout: command_timeout,
+                                  prepare: method(:prepare_command), after_command: finish_step, prompt: prompt)
+        execution.context[:operation] = operation if operation
+        execution.context[:privilege] = privilege
+        execution
+      end
+
+      # 回调也可直接返回失败；与抛错共用脱敏边界，保留已完成步骤及业务配置。
+      def finalize_script_result(result, finalize)
+        result = finalize ? finalize.call(result) : result
+        return result unless result.is_a?(Result) && result.failure?
+
+        Result.new(steps: result.steps, config: result.config,
+                   error: @session.normalize_error(result.error, phase: :script))
+      end
     end
   end
 end

data/lib/net/connector/device/profile/builder.rb

@@ -12,7 +12,7 @@ module Net
 
         # 声明运行配置和保存配置命令。
         def commands(&definition)
-          check_block!(:commands, definition)
+          validate_block!(:commands, definition)
           commands = Commands.new(
             @values[:config_commands], @values[:save_commands]
           )
@@ -24,28 +24,28 @@ module Net
 
         # 声明登录、命令、凭据和提权提示符。
         def prompts(&definition)
-          check_block!(:prompts, definition)
+          validate_block!(:prompts, definition)
           Prompts.new(@values).instance_eval(&definition)
           self
         end
 
         # 声明分页模式及自动翻页响应。
         def pager(&definition)
-          check_block!(:pager, definition)
+          validate_block!(:pager, definition)
           Pager.new(@values).instance_eval(&definition)
           self
         end
 
         # 声明认证失败和命令失败的输出模式。
         def errors(&definition)
-          check_block!(:errors, definition)
+          validate_block!(:errors, definition)
           Errors.new(@values).instance_eval(&definition)
           self
         end
 
         # 声明登录挑战和命令确认交互。
         def interactions(&definition)
-          check_block!(:interactions, definition)
+          validate_block!(:interactions, definition)
           interactions = Interactions.new(@values)
           interactions.instance_eval(&definition)
           @values[:login_interactions] = interactions.login_interactions
@@ -55,14 +55,14 @@ module Net
 
         # 声明进入特权模式所需的命令和提示符。
         def privilege(&definition)
-          check_block!(:privilege, definition)
+          validate_block!(:privilege, definition)
           Privilege.new(@values).instance_eval(&definition)
           self
         end
 
         # 声明旧版 SSH 协商参数。
         def ssh(&definition)
-          check_block!(:ssh, definition)
+          validate_block!(:ssh, definition)
           Ssh.new(@values).instance_eval(&definition)
           self
         end
@@ -103,7 +103,7 @@ module Net
         private
 
         # 块式声明入口必须有明确的子 DSL，避免静默忽略配置。
-        def check_block!(name, definition)
+        def validate_block!(name, definition)
           raise ArgumentError, "#{name} requires a block" unless definition
         end
 

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

@@ -63,7 +63,7 @@ module Net
         @legacy_ssh_arguments = strings(legacy_ssh_arguments, :legacy_ssh_arguments)
         @privilege_command = optional_text(privilege_command, :privilege_command)
         @command_timeout = duration(command_timeout, :command_timeout)
-        @terminal_size = validate_terminal_size(terminal_size)
+        @terminal_size = validate_terminal_size!(terminal_size)
         @running_config_strategy = strategy_class(running_config_strategy, :running_config_strategy,
                                                   %i[clean result_step prompt_text validate_response!])
         @tftp_strategy = strategy_class(tftp_strategy, :tftp_strategy,
@@ -211,7 +211,7 @@ module Net
       end
 
       # 校验终端宽高并冻结数组。
-      def validate_terminal_size(value)
+      def validate_terminal_size!(value)
         return if value.nil?
         unless value.is_a?(Array) && value.size == 2 && value.all? { |dimension| dimension.is_a?(Integer) && dimension.positive? }
           raise ArgumentError, "terminal_size must contain two positive Integers"

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

@@ -81,7 +81,7 @@ module Net
         raise build_incomplete_error("configuration collection has no completed configuration step") unless step
 
         content = @device.clean_config(step.output)
-        unless content.is_a?(String) && !content.strip.empty? && content?(step)
+        unless content.is_a?(String) && !content.strip.empty? && config_body?(step)
           raise build_incomplete_error("configuration collection returned empty content")
         end
         Result.new(steps: result.steps, config: content)
@@ -99,7 +99,7 @@ module Net
       end
 
       # 排除命令回显和提示符，确认响应确实包含配置正文。
-      def content?(step)
+      def config_body?(step)
         body = TerminalRenderer.render(step.output.delete_suffix(step.prompt.to_s)).strip
         lines = body.lines
         lines.shift if lines.first&.strip == step.command.text

data/lib/net/connector/device/tftp/receipt.rb

@@ -7,7 +7,8 @@ module Net
   module Connector
     # 一次设备上报上传的不可变回执；path 是实际目标，未知时保持 nil。
     TftpReceipt = Data.define(:server, :path, :completed_at, :configuration_kind, :source_file,
-                             :format, :requested_path, :verification, :server_sha256)
+                             :format, :requested_path, :verification, :server_sha256, :server_bytes, :local_path,
+                             :archive_path)
 
     class TftpReceipt
       KINDS = %i[running startup saved_file native_archive unknown].freeze
@@ -15,7 +16,8 @@ module Net
       private_constant :KINDS, :FORMATS
 
       def initialize(server:, path:, completed_at:, configuration_kind: :unknown, source_file: nil,
-                     format: :unknown, requested_path: nil, verification: :device_reported, server_sha256: nil)
+                     format: :unknown, requested_path: nil, verification: :device_reported, server_sha256: nil,
+                     server_bytes: nil, local_path: nil, archive_path: nil)
         raise ArgumentError, "completed_at must be a Time" unless completed_at.is_a?(Time)
 
         TftpTarget.new(host: server, path: path.nil? ? "unconfirmed" : path)
@@ -29,10 +31,17 @@ module Net
             server_sha256.match?(/\A[0-9a-f]{64}\z/))
         raise ArgumentError, "invalid TFTP verification evidence" unless valid_verification
 
+        if (!server_bytes.nil? && (!server_bytes.is_a?(Integer) || !server_bytes.positive?)) ||
+          (!local_path.nil? && (!local_path.is_a?(String) || local_path.empty?)) ||
+          (!archive_path.nil? && (!archive_path.is_a?(String) || archive_path.empty?)) ||
+          (verification != :server_verified && (server_bytes || local_path || archive_path))
+          raise ArgumentError, "invalid server file metadata"
+        end
         super(server: server.dup.freeze, path: path&.dup&.freeze, completed_at: completed_at.dup.freeze,
               configuration_kind: configuration_kind, source_file: source_file&.dup&.freeze, format: format,
               requested_path: requested_path&.dup&.freeze, verification: verification,
-              server_sha256: server_sha256&.dup&.freeze)
+              server_sha256: server_sha256&.dup&.freeze, server_bytes: server_bytes, local_path: local_path&.dup&.freeze,
+              archive_path: archive_path&.dup&.freeze)
       end
 
       # Ruby 3.2 的 Data#with 不调用 initialize；所有更新都重新校验并冻结字段。

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

@@ -89,13 +89,13 @@ module Net
           raise DeviceError.new("device reported TFTP backup failure",
                                 code: :transfer_failed, host: @device.host, phase: :tftp_backup)
         end
-        unless strategy.device_reported_complete?(result)
-          result.value! if result.failure?
-          @device.log_event("tftp_backup", level: :error, status: "transfer_unconfirmed", phase: :tftp_backup,
-                                code: :transfer_unconfirmed, server: target.host)
-          raise DeviceError.new("device did not confirm TFTP backup completion",
-                                code: :transfer_unconfirmed, host: @device.host, phase: :tftp_backup)
-        end
+        return if strategy.device_reported_complete?(result)
+
+        result.value! if result.failure?
+        @device.log_event("tftp_backup", level: :error, status: "transfer_unconfirmed", phase: :tftp_backup,
+                              code: :transfer_unconfirmed, server: target.host)
+        raise DeviceError.new("device did not confirm TFTP backup completion",
+                              code: :transfer_unconfirmed, host: @device.host, phase: :tftp_backup)
       end
 
       # 识别设备回显中的传输失败信息。

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

@@ -180,10 +180,10 @@ module Net
                                   code: :verification_plan_changed, host: @device.host, phase: :verify)
           end
         end
-        unless changes.all? { |change| updated[@strategy.interface_key(change.interface)] == change.new_description }
-          raise DeviceError.new("interface descriptions were not confirmed by readback",
-                                code: :description_unconfirmed, host: @device.host, phase: :verify)
-        end
+        return if changes.all? { |change| updated[@strategy.interface_key(change.interface)] == change.new_description }
+
+        raise DeviceError.new("interface descriptions were not confirmed by readback",
+                              code: :description_unconfirmed, host: @device.host, phase: :verify)
       end
 
       # 重验失败仍在写入前直接抛异常，保持 stale_plan 的既有契约。

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

@@ -70,11 +70,11 @@ module Net
       def self.parse(text, name: nil)
         raise ArgumentError, "script must be a String" unless text.is_a?(String)
 
-        commands = text.each_line.with_index(1).filter_map do |line, number|
+        commands = text.each_line.with_index(1).filter_map do |line, line_number|
           line = line.chomp
           next if line.strip.empty? || line.lstrip.start_with?("#")
 
-          Command.new(line, source: name, line: number)
+          Command.new(line, source: name, line: line_number)
         end
         new(commands, name: name)
       end

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

@@ -9,13 +9,13 @@ module Net
     class Configuration
       attr_reader :host, :username, :password, :enable_password, :protocol, :port, :login_timeout,
                   :command_timeout, :write_timeout, :max_output_bytes, :max_script_output_bytes, :log_file, :log_format, :log_level,
-                  :known_hosts, :host_key_policy, :challenges, :logger
+                  :known_hosts, :host_key_policy, :challenges, :logger, :on_event
 
       # 校验端点、凭据、超时、日志、主机密钥和挑战配置，然后冻结设置。
       def initialize(host: nil, username: nil, password: nil, enable_password: nil, protocol: :ssh, port: nil,
                      login_timeout: 10, command_timeout: nil, write_timeout: 10,
                      max_output_bytes: 32 * 1024 * 1024, max_script_output_bytes: nil, log_file: nil, logger: nil,
-                     log_format: :text, log_level: :info,
+                     log_format: :text, log_level: :info, on_event: nil,
                      known_hosts: nil, host_key_policy: :strict, telnet_fallback: false, legacy_ssh: false,
                      challenges: [])
         @host = frozen_string(host)
@@ -45,6 +45,9 @@ module Net
         raise ArgumentError, "logger cannot be combined with raw logging" if logger && @log_format == :raw
 
         @logger = logger
+        raise ArgumentError, "on_event must respond to call" if on_event && !on_event.respond_to?(:call)
+
+        @on_event = on_event
         @log_level = enum_value(log_level, %i[debug info warn error], :log_level)
         @known_hosts = absolute_path(known_hosts)
         @host_key_policy = enum_value(host_key_policy, %i[strict accept_new replace], :host_key_policy)

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

@@ -15,7 +15,7 @@ module Net
         @command_timeout = timeout
         @prepare_command = prepare
         @after_command = after_command
-        @prompt = prompt
+        @prompt_resolver = prompt
         @context = {}
         @steps = []
         @output_bytes = 0
@@ -28,10 +28,10 @@ module Net
 
       # 依次准备、执行和记录脚本命令；失败时保留已完成步骤并统一抛错。
       def execute_script(script)
-        script.each do |original|
-          @session.with_command_redaction(original) do
-            @current_command = original
-            command = @prepare_command.call(original, self)
+        script.each do |original_command|
+          @session.with_command_redaction(original_command) do
+            @current_command = original_command
+            command = @prepare_command.call(original_command, self)
             next unless command
 
             @current_command = command
@@ -45,31 +45,31 @@ module Net
             # 设备已经完成命令；后处理失败也不能从部分结果中抹去其副作用。
             @after_command.call(command, response, self)
             yield step if block_given?
-            check_output_budget!(@last_query_command, completed: true)
+            validate_response_budget!(@last_executed_command)
           rescue => error
             raise @session.normalize_error(error, phase: :script, command: @current_command), cause: nil
           end
         end
-        check_output_budget!(@last_query_command, completed: true)
+        validate_response_budget!(@last_executed_command)
         Result.new(steps: steps)
       end
 
       # 厂商后续查询复用同一信道和错误处理，不开启新的批处理。
       def execute_command(command)
         command = Command.new(command) unless command.is_a?(Command)
-        check_output_budget!(command, completed: false)
-        prompt = @prompt&.call(command)
+        validate_send_budget!(command)
+        prompt = @prompt_resolver&.call(command)
         # 提示符回调也可能追加查询，实际发送前重新检查它消耗的预算。
-        check_output_budget!(command, completed: false) if @prompt
+        validate_send_budget!(command) if @prompt_resolver
         response = @session.execute_command(command, timeout: @command_timeout, prompt: prompt) do
           # 必须在 Session 恢复命令词表前读取；最终处理只能继承敏感性，不长期保留秘密。
           @sensitive ||= @session.redactor.sensitive?
         end
-        @last_query_command = command
+        @last_executed_command = command
         @output_bytes += response.raw.bytesize
         # 主命令先记录完整步骤，再检查超额；追加查询同样计入预算，但不改变原 steps 结构。
         yield response if block_given?
-        check_output_budget!(command, completed: true)
+        validate_response_budget!(command)
         response
       end
 
@@ -86,9 +86,20 @@ module Net
       private
 
       # 单响应上限仍约束正在读取的命令；累计预算阻止继续发送，不承诺设备尚未执行。
-      def check_output_budget!(command, completed:)
-        return unless @output_limit && (completed ? @output_bytes > @output_limit : @output_bytes >= @output_limit)
+      def validate_send_budget!(command)
+        return unless @output_limit && @output_bytes >= @output_limit
 
+        raise_output_limit!(command)
+      end
+
+      # 恰好达到预算的已完成响应仍然有效；下一次发送由发送前检查阻止。
+      def validate_response_budget!(command)
+        return unless @output_limit && @output_bytes > @output_limit
+
+        raise_output_limit!(command)
+      end
+
+      def raise_output_limit!(command)
         raise @session.build_error(ScriptOutputLimitExceeded,
                                    "script output reached max_script_output_bytes; commands already sent may have executed",
                                    phase: :script, command: command), cause: nil

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+require "open3"
+require_relative "errors"
+
+module Net
+  module Connector
+    # SSH 只写会话副本；认证后在跨进程锁内合并，网络等待不占用共享文件锁。
+    class KnownHosts
+      attr_reader :path
+
+      def initialize(configuration, replace: false)
+        destination = configuration.known_hosts || File.join(Dir.home, ".ssh", "known_hosts")
+        FileUtils.mkdir_p(File.dirname(destination), mode: 0o700)
+        @destination = File.join(File.realpath(File.dirname(destination)), File.basename(destination))
+        @host = configuration.host
+        @host = "[#{@host}]:#{configuration.port}" if configuration.port && configuration.port != 22
+        @replace = replace
+        @original = read_shared
+        @file = Tempfile.new([".nc-known-hosts-", ""], File.dirname(@destination))
+        @path = @file.path
+        @file.write(@original)
+        @file.flush
+        remove_host(@path) if @replace
+      rescue Exception # rubocop:disable Lint/RescueException -- Remove the private snapshot on interruption.
+        close
+        raise
+      end
+
+      def commit
+        additions = File.binread(path).lines - @original.lines
+        return if additions.empty?
+
+        with_lock do
+          current = read_shared
+          Tempfile.create([".nc-known-hosts-merge-", ""], File.dirname(@destination)) do |file|
+            file.write(current)
+            file.flush
+            reject_changed_key!(file.path) unless @replace
+            remove_host(file.path) if @replace
+            contents = File.binread(file.path)
+            entries = contents.lines
+            additions.each { |line| entries << line unless entries.include?(line) }
+            File.open(file.path, "wb", 0o600) do |replacement|
+              replacement.write(entries.map { |line| line.end_with?("\n") ? line : line + "\n" }.join)
+              replacement.flush
+              replacement.fsync
+            end
+            File.rename(file.path, @destination)
+          ensure
+            File.unlink(file.path + ".old") if file && File.exist?(file.path + ".old")
+          end
+        end
+      end
+
+      def close
+        File.unlink(@path + ".old") if @path && File.exist?(@path + ".old")
+        @file&.close!
+        @file = nil
+      end
+
+      private
+
+      def read_shared
+        File.open(@destination, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
+          raise IOError, "known_hosts must be a regular file" unless file.stat.file?
+
+          file.read
+        end
+      rescue Errno::ENOENT
+        ""
+      end
+
+      def reject_changed_key!(current_path)
+        current = host_keys(current_path)
+        staged = host_keys(path)
+        return if current.empty? || (staged - current).empty?
+
+        raise ConnectionError.new("host key changed during concurrent registration", code: :host_key_changed)
+      end
+
+      def host_keys(path)
+        output, status = Open3.capture2e("ssh-keygen", "-f", path, "-F", @host)
+        raise IOError, "reading device host key failed" unless [0, 1].include?(status.exitstatus)
+
+        output.lines.reject { |line| line.start_with?("#") }.map { |line| line.split[1, 2] }.uniq
+      end
+
+      def remove_host(path)
+        _output, status = Open3.capture2e("ssh-keygen", "-f", path, "-R", @host)
+        raise IOError, "removing device host key failed" unless status.success?
+      end
+
+      def with_lock
+        lock_path = @destination + ".nc-lock"
+        File.open(lock_path, File::RDWR | File::CREAT | File::NOFOLLOW | File::NONBLOCK, 0o600) do |file|
+          stat = file.stat
+          unless stat.file? && stat.uid == Process.euid && stat.nlink == 1 && (stat.mode & 0o7777) == 0o600
+            raise IOError, "known_hosts lock must be an owned private regular file"
+          end
+          file.flock(File::LOCK_EX)
+          current = File.lstat(lock_path)
+          raise IOError, "known_hosts lock changed" unless current.dev == stat.dev && current.ino == stat.ino
+
+          yield
+        end
+      end
+    end
+  end
+end

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