net-connector 0.4.2 → 0.5.0

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

@@ -40,7 +40,22 @@ module Net
       def mark_privileged! = @privileged = true
 
       # 记录脚本之外的业务结果，例如设备报告的 TFTP 上传状态。
-      def log_event(name, **fields) = @log.event(name, **fields)
+      def log_event(name, **fields) = @log.log_custom_event(name, **fields)
+
+      # 业务名称贯穿脚本及其钩子，底层命令另外分配独立序号。
+      def log_script(operation:, steps:)
+        @log.with_operation_context(operation) do
+          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
+        end
+      end
 
       # 在会话锁内建立连接。
       def connect
@@ -53,7 +68,7 @@ module Net
           return perform_locked(phase) { yield }
         end
         unless @lock.try_lock
-          raise error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
+          raise build_error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
         end
 
         begin
@@ -66,11 +81,18 @@ module Net
       # 业务操作在多次脚本之间持有租约；只有同一线程和 Fiber 可顺序使用。
       def with_operation(phase)
         unless @lock.try_lock
-          raise error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
+          raise build_error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
         end
         @operation_owner = [Thread.current, Fiber.current]
+        result = nil
         begin
-          yield
+          @log.with_operation_context(phase) { result = yield }
+        rescue Error => error
+          raise unless result.is_a?(Result)
+
+          # 日志收尾失败不能抹去已完成的设备步骤，也不能覆盖原业务错误。
+          Result.new(steps: result.steps, config: result.config,
+                     error: result.error || normalize_error(error, phase: phase))
         ensure
           @operation_owner = nil
           @lock.unlock
@@ -81,7 +103,7 @@ module Net
       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
+        raise build_error(SessionBusy, "backup path ownership must be acquired before a session operation", phase: phase), cause: nil
       end
 
       # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
@@ -118,7 +140,7 @@ module Net
       # 独占关闭会话；已有操作占用时返回会话繁忙错误。
       def close
         unless @lock.try_lock
-          raise error(SessionBusy, "cannot close a session owned by another operation", phase: :close), cause: nil
+          raise build_error(SessionBusy, "cannot close a session owned by another operation", phase: :close), cause: nil
         end
 
         begin
@@ -131,7 +153,7 @@ module Net
       # 执行特权认证，并更新提示符及特权状态。
       def enable(command, prompt)
         unless command
-          raise error(UnsupportedOperation, "privilege authentication is not supported", phase: :enable), cause: nil
+          raise build_error(UnsupportedOperation, "privilege authentication is not supported", phase: :enable), cause: nil
         end
 
         @privileged = false
@@ -142,8 +164,8 @@ module Net
       end
 
       # 命令准备、交换、后处理及回调共用一份临时词表，退出时一并清除。
-      def command_scope(command)
-        redactor.scope do
+      def with_command_redaction(command)
+        redactor.with_scope do
           protect_command(command)
           yield
         end
@@ -151,10 +173,10 @@ module Net
 
       # 批次准备和最终清理也可能读取配置；在作用域退出前归一化其异常，
       # 防止清理钩子的消息或回溯将已完成步骤中的正文带回诊断通道。
-      def output_scope(enabled)
+      def with_sensitive_output(enabled)
         return yield unless enabled
 
-        redactor.scope do
+        redactor.with_scope do
           redactor.output_sensitive!
           yield
         rescue => error
@@ -163,29 +185,47 @@ module Net
       end
 
       # 复用完整命令的脱敏范围；厂商后续查询产生的秘密保留到外层回调结束。
-      def exchange(command, timeout:, prompt: nil)
-        redactor.scope(reuse: true) do
+      def execute_command(command, timeout:, prompt: nil)
+        redactor.with_scope(reuse: true) do
           protect_command(command)
-          started = Expect.monotonic
-          @log.event("command_start", text: command.sensitive? ? "[REDACTED]" : command.text)
-          sensitive_dialogue = [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
-          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 private_output
-          @log.event("command_complete", status: "response_received")
-          @log.event("command_detail", level: :debug,
-                     duration_ms: ((Expect.monotonic - started) * 1000).round,
-                     response_bytes: response.raw.bytesize)
-          response
-        rescue => error
-          failure = normalize_error(error, phase: :command, command: command)
-          @log.event("command_complete", level: :error, status: "failed",
-                     error: failure.class.name, message: failure.message)
-          raise failure, cause: nil
+          @log.with_command_context(command) { execute_command_with_logging(command, timeout: timeout, prompt: prompt) }
+        ensure
+          # 失败的敏感探测也可能被钩子捕获后继续；离开作用域前始终通知执行器。
+          yield if block_given?
         end
       end
 
+      def execute_command_with_logging(command, timeout:, prompt:)
+        started = Expect.monotonic
+        @log.log_event("command_start")
+        sensitive_dialogue = [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
+        private_output = command.sensitive? || redactor.output_sensitive? || sensitive_dialogue
+        @log.log_event("device_output", level: :debug) if @log.debug? && !private_output
+        response = exchange_command(command, timeout: timeout, prompt: prompt)
+        @log.log_response_output(response.raw) unless private_output
+        details = { duration_ms: elapsed_ms(started), response_bytes: response.raw.bytesize }
+        @log.log_event("command_complete", status: "response_received", **details)
+        response
+      rescue => error
+        failure = normalize_error(error, phase: :command, command: command)
+        @log.log_failure("command_complete", failure, status: "failed", duration_ms: elapsed_ms(started), phase: :command)
+        raise failure, cause: nil
+      end
+
+      def elapsed_ms(started) = ((Expect.monotonic - started) * 1000).round
+
+      def log_operation_completion(started, failure, steps: nil)
+        fields = { status: failure ? "failed" : "completed", duration_ms: elapsed_ms(started), steps: steps,
+                   phase: :script }
+        if failure
+          @log.log_failure("operation_complete", failure, **fields, failed_command: failure.command)
+        else
+          @log.log_event("operation_complete", **fields)
+        end
+      end
+
+      private :execute_command_with_logging, :elapsed_ms, :log_operation_completion
+
       # 在用户钩子运行前标记敏感上下文，动态交互尚未返回时也能保护其异常。
       def protect_command(command)
         redactor.output_sensitive! if command.output_sensitive?
@@ -208,7 +248,7 @@ module Net
                                  deadline: deadline, phase: :command, command: command)
           @prompt = response.prompt
           if (diagnostic = @dialogue.diagnostic(response.raw))
-            raise error(DeviceError, diagnostic, phase: :command, command: command, output: response.raw), cause: nil
+            raise build_error(DeviceError, diagnostic, phase: :command, command: command, output: response.raw), cause: nil
           end
 
           response
@@ -243,7 +283,7 @@ module Net
       end
 
       # 创建带脱敏上下文、阶段、命令和输出尾部的领域错误。
-      def error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
+      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)
@@ -264,8 +304,8 @@ module Net
           end
           message = safe_error_text(exception.message, sensitive: sensitive)
           output = safe_error_text(exception.output, sensitive: sensitive)
-          return exception.class.new(
-            message, code: exception.code,
+          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,
@@ -279,7 +319,7 @@ module Net
                 when IOError, SystemCallError, Expect::SpawnError then TransportError
                 else InternalError
                 end
-        error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
+        build_error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
       end
 
       # 敏感上下文的任意异常和设备输出可能只包含局部秘密，保留类型和错误码诊断。
@@ -306,27 +346,28 @@ module Net
         attempted_recovery = false
         begin
           @state = :connecting
+          started = Expect.monotonic
           redactor.reset
           @log.open(transport)
-          @log.event("connect", host: configuration.host, username: configuration.username,
-                     protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
+          @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.event("login_start", level: :debug)
+          @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.authentication_output(response.raw)
-          @log.event("login_complete", status: "ok", prompt: response.prompt)
+          @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
         rescue => error
           phase = (@state == :connecting) ? :connect : :login
           failure = normalize_error(error, phase: phase)
-          @log.event(phase == :connect ? "connect_failed" : "login_complete", level: :error,
-                     status: "failed", error: failure.class.name, message: failure.message, phase: phase)
+          @log.log_failure(phase == :connect ? "connect_failed" : "login_complete", failure,
+                           status: "failed", phase: phase, duration_ms: elapsed_ms(started))
           close_preserving_failure
           replacement = attempted_recovery ? nil : @recovery.recover(failure, transport)
           if replacement

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "terminal_renderer"
+require_relative "errors"
+
+module Net
+  module Connector
+    # 设备/文件提供的是字节，不受 Ruby 源文件编码控制。解析边界只接受 UTF-8，
+    # 不猜测编码、不改写原文，也不让终端编辑把非法字节抹掉后变成可信证据。
+    module TerminalText
+      def self.utf8(bytes, host: nil)
+        raise ArgumentError, "text must be a String" unless bytes.is_a?(String)
+
+        text = bytes.b.force_encoding(Encoding::UTF_8)
+        invalid_encoding!(host) unless text.valid_encoding?
+        text
+      end
+
+      def self.render(bytes, host: nil)
+        TerminalRenderer.render(utf8(bytes, host: host), strict_utf8: true).force_encoding(Encoding::UTF_8)
+      rescue Encoding::InvalidByteSequenceError
+        invalid_encoding!(host)
+      end
+
+      def self.invalid_encoding!(host)
+        raise ParsingError.new("device output is not valid UTF-8", code: :invalid_output_encoding,
+                               host: host, phase: :parse), cause: nil
+      end
+
+      private_class_method :invalid_encoding!
+    end
+  end
+end

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

@@ -46,7 +46,7 @@ module Net
                      end
           # Profile 使用宽、高；PTY 使用行数、列数。
           @channel.slave.winsize = @terminal_size.reverse if @terminal_size
-          @channel.log_output = method(:record)
+          @channel.log_output = method(:write_log_output)
           @channel.spawn(*argv)
           self
         rescue Exception # rubocop:disable Lint/RescueException -- A half-open PTY must be released on interrupts.
@@ -104,7 +104,7 @@ module Net
         private
 
         # 检查缓冲上限并把设备输出写入当前日志目标。
-        def record(bytes)
+        def write_log_output(bytes)
           if @channel.buffer.bytesize > configuration.max_output_bytes
             raise OutputLimitExceeded.new("transport buffer exceeded max_output_bytes",
                                           phase: :read, output: @channel.buffer.dup), cause: nil

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

@@ -8,9 +8,7 @@ module Net
     module Netdisco
       # 单台设备的最终结果，保留状态、配置产物和错误类型。
       Outcome = Data.define(:device, :status, :backup, :error_code, :error_type,
-                            :started_at, :finished_at) do
-        attr_reader :diagnostic
-
+                            :started_at, :finished_at, :duration_ms, :diagnostic) do
         # 创建结果，允许计划阶段尚无执行时间。
         def initialize(device:, status:, backup:, error_code:, error_type:, started_at: nil, finished_at: nil,
                        duration_ms: nil, diagnostic: nil)
@@ -19,19 +17,18 @@ module Net
           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)
+                started_at: started_at, finished_at: finished_at, duration_ms: duration_ms, diagnostic: diagnostic)
         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))
+          values = to_h
+          values[:duration_ms] = nil if attributes.key?(:started_at) || attributes.key?(:finished_at)
+          values[:diagnostic] = nil if attributes.key?(:error_code) || attributes.key?(:error_type)
+          self.class.new(**values.merge(attributes))
         end
 
         # 判断设备是否完成配置保存或上报上传成功。
@@ -42,13 +39,6 @@ module Net
 
         # 判断设备是否因为清单或采样规则未执行。
         def skipped? = !success? && !partial? && status != :failed
-
-        # 计算设备任务的耗时，计划阶段没有时间时返回空值。
-        def duration_ms
-          return @duration_ms unless @duration_ms.nil?
-
-          [((finished_at - started_at) * 1000).round, 0].max if started_at && finished_at
-        end
       end
 
       # 汇总一次批量任务的设备结果、回调故障和报告写入状态。
@@ -63,34 +53,8 @@ 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
-          {
-            mode: mode, status: status, started_at: started_at.iso8601, finished_at: finished_at.iso8601,
-            total: outcomes.size,
-            succeeded: outcomes.count(&:success?),
-            partial: outcomes.count(&:partial?),
-            failed: outcomes.count { |item| item.status == :failed },
-            skipped: outcomes.count(&:skipped?),
-            counts: counts,
-            callback_errors: callback_errors,
-            devices: outcomes.map do |item|
-              { host: item.device.host || item.device.source_ip, name: item.device.name,
-                vendor: item.device.vendor,
-                status: item.status, path: item.backup&.path,
-                bytes: item.backup.is_a?(Backup) ? item.backup.bytes : nil,
-                sha256: item.backup.is_a?(Backup) ? item.backup.sha256 : nil,
-                change: item.backup.is_a?(Backup) ? item.backup.change : nil,
-                previous_sha256: item.backup.is_a?(Backup) ? item.backup.previous_sha256 : nil,
-                started_at: item.started_at&.iso8601, finished_at: item.finished_at&.iso8601,
-                duration_ms: item.duration_ms,
-                error_code: item.error_code, error_type: item.error_type }
-            end
-          }
-        end
+        # 显式从原始执行结果构造报告。
+        def build_report(policy: :strict) = Report.new(self, policy: policy)
       end
 
       autoload :Report, File.expand_path("report", __dir__)

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

@@ -48,11 +48,10 @@ module Net
 
           batch = backup(fleet, plan, settings, options)
           summary = batch.summary
-          summary = summary.merge(report_location: batch.report_location, report_error: batch.report_error) unless batch.instance_of?(Report)
           @output.puts JSON.pretty_generate(summary)
-          (batch.instance_of?(Report) ? batch.policy_success? : batch.success?) ? 0 : 1
-        rescue Operations::PrivateFile::WriteError => exception
-          message = Operations::PrivateFile.receipt_error?(exception) ? exception.message : exception.class.name
+          batch.policy_success? ? 0 : 1
+        rescue Storage::PrivateFile::WriteError => exception
+          message = Storage::PrivateFile.receipt_error?(exception) ? exception.message : exception.class.name
           @error.puts "net-connector-backup: #{message}"
           2
         rescue OptionParser::ParseError, ArgumentError, KeyError, Errno::ENOENT,
@@ -81,7 +80,7 @@ module Net
 
         # 导出已有配置不创建清单或设备连接。
         def export_config(settings, options)
-          path = Operations::SavedConfig.new(directory: settings.backup_directory)
+          path = Storage::SavedConfig.new(directory: settings.backup_directory)
                                         .export(host: options[:export], output: options[:output], io: @output)
           @output.puts JSON.generate(host: options[:export], output: path) if path
         end
@@ -103,7 +102,7 @@ module Net
 
         # 仅执行已经校验的计划，保留本地与 TFTP 两种结果语义。
         def backup(fleet, plan, settings, options)
-          reporting = options.slice(:success_policy, :report_schema)
+          reporting = options.slice(:success_policy)
           if options[:tftp]
             fleet.tftp_backup_all(plan: plan, server: settings.tftp_server,
                                   concurrency: settings.concurrency,
@@ -135,7 +134,6 @@ module Net
             end
             args.on("--all", "选择全部就绪设备") { options[:all] = true }
             args.on("--success-policy POLICY", %w[strict selected], "成功判定：strict（默认）或 selected") { |value| options[:success_policy] = value.to_sym }
-            args.on("--report-schema N", Integer, "报告版本：1（默认）或 2；selected 使用 2") { |value| options[:report_schema] = value }
             args.on("-v", "--version", "显示版本") do
               @output.puts Net::Connector::VERSION
               options[:done] = true
@@ -153,7 +151,7 @@ module Net
 
         # 拒绝互斥或缺少依赖的命令行选项。
         def validate_options!(options)
-          Report.options(policy: options.fetch(:success_policy, :strict), schema: options[:report_schema])
+          Report.validate_policy!(options.fetch(:success_policy, :strict))
           Planner.validate_limit!(options[:limit])
           Worker.new(concurrency: options[:concurrency]) if options[:concurrency]
           modes = [:show_config, :plan, :export].count { |key| options[key] }
@@ -161,7 +159,7 @@ module Net
           raise ArgumentError, "--output 需要同时指定 --export" if options[:output] && !options[:export]
           raise ArgumentError, "--all 不能与 --limit-per-vendor 同时使用" if options[:all] && options[:limit]
           if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:concurrency] || options[:host] ||
-                                  options[:success_policy] || options[:report_schema] || options[:max_script_output_bytes])
+                                  options[:success_policy] || options[:max_script_output_bytes])
             raise ArgumentError, "--export 不能与备份选项同时使用"
           end
         end

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

@@ -109,10 +109,10 @@ module Net
           end
           raise Error.new("Netdisco inventory exceeded max_pages", code: :max_pages), cause: nil
         rescue QueryRequired
-          legacy_devices(token, budget)
+          query_required_devices(token, budget)
         end
 
-        def legacy_devices(token, budget)
+        def query_required_devices(token, budget)
           uri = endpoint("api/v1/search/device")
           uri.query = URI.encode_www_form(q: "%", seeallcolumns: true)
           rows = request_json(uri, authorized_get(uri, token), budget, allow_empty: true)

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "ipaddr"
-require_relative "../operations/saved_config"
+require_relative "../storage/saved_config"
 
 module Net
   module Connector
@@ -44,7 +44,7 @@ module Net
         def ready? = issue.nil?
 
         # 生成不随名称或厂商信息改变的本地文本文件名。
-        def backup_filename = Operations::SavedConfig.filename(host)
+        def backup_filename = Storage::SavedConfig.filename(host)
 
         # 生成设备 CLI 可用的 ASCII 远端文件名。
         def tftp_filename
@@ -53,13 +53,12 @@ module Net
                       .gsub(/\A[._-]+|[._-]+\z/, "")
           label = vendor&.to_s || "device" if label.empty?
           strategy = Net::Connector.vendor_class(vendor).profile.tftp_strategy if vendor
-          # 旧版自定义策略只需实现实例接口，缺少命名接口时沿用通用 cfg 名称。
-          strategy = Operations::Tftp::Strategy unless strategy.respond_to?(:filename)
+          raise UnsupportedOperation, "device has no TFTP strategy" unless strategy
           TftpTarget.validate_path!(strategy.filename(host, label: label))
         end
 
         # 按厂商及设备地址实例化连接器。
-        def connector(**settings)
+        def build_connector(**settings)
           raise ArgumentError, "device is not ready: #{issue}" unless ready?
           raise ArgumentError, "host cannot be overridden" if settings.key?(:host)
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../engine/error_metadata"
+
 module Net
   module Connector
     module Netdisco
@@ -8,59 +10,27 @@ module Net
                                :artifact_state, :artifact_phase, :verification)
 
       class Diagnostic
-        CONNECTOR_TYPES = %w[Error ConnectionError AuthenticationError LoginTimeout CommandTimeout WriteTimeout
-                             PromptError ConnectionClosed TransportError DeviceError ScriptError InternalError
-                             OutputLimitExceeded ScriptOutputLimitExceeded SessionBusy UnsupportedOperation LogError ParsingError BackupBusy
-                             BackupPersistenceError TftpCompletionError SavedConfigChanged].freeze
-        TYPES = (CONNECTOR_TYPES.map { |name| "Net::Connector::#{name}" } +
-          %w[StandardError RuntimeError ArgumentError TypeError IOError EOFError SystemCallError ThreadError
-             RangeError KeyError IndexError NoMethodError NameError FrozenError NotImplementedError
-             Timeout::Error IO::TimeoutError Errno::EIO Errno::EACCES Errno::EPERM Errno::ENOSPC Errno::EROFS
-             Errno::ENOENT Errno::ENOTDIR Errno::EISDIR Errno::ELOOP Errno::EINVAL Errno::ENOSYS
-             Errno::ENOTSUP Errno::EOPNOTSUPP Errno::ETIMEDOUT Errno::ECONNREFUSED Errno::ECONNRESET
-             Net::Connector::Operations::PrivateFile::WriteError
-             Net::Connector::Operations::PrivateFile::PersistenceError
-             Net::Connector::Operations::PrivateFile::DirectorySyncUnsupported]).freeze
-        CODES = (CONNECTOR_TYPES.map { |name| name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym } +
-          %i[authentication_failed connection_failed connection_refused no_route connection_reset
-             connection_timeout host_key_changed host_key_untrusted rsa_too_small unsupported_cipher
-             ambiguous_description ambiguous_neighbor confirmation_required description_stages_unsupported
-             description_unconfirmed description_unsupported incomplete_configuration interface_missing
-             neighbor_discovery_unsupported parse_failed invalid_output_encoding persistence_unconfirmed stale_plan startup_config_missing
-             template_invalid template_missing template_unreadable transfer_failed transfer_finalize_failed
-             transfer_path_mismatch transfer_path_unconfirmed transfer_unconfirmed uncommitted_configuration
-             unrecognized_output unsupported_configuration_format verification_plan_changed candidate_isolation_unavailable
-             backup_durability_unsupported backup_finalize_failed backup_persistence_unconfirmed
-             file_finalize_failed file_persistence_unconfirmed file_write_failed directory_sync_unsupported]).freeze
-        PHASES = %i[connect login enable command script read write close logging backup collect discover parse
-                    plan apply verify persist tftp_backup report callback].freeze
         ARTIFACT_STATES = %i[not_committed committed durable reported_uploaded].freeze
         ARTIFACT_PHASES = %i[resolve_parent temporary_file write file_sync rename directory_open directory_sync
                             cleanup complete path finalize].freeze
-        private_constant :CONNECTOR_TYPES, :TYPES, :CODES, :PHASES, :ARTIFACT_STATES, :ARTIFACT_PHASES
+        private_constant :ARTIFACT_STATES, :ARTIFACT_PHASES
 
         # 包括手工构造的结果在内，v2 都不能携带自由文本诊断值。
         def initialize(error_code: nil, error_type: nil, phase: nil, underlying_type: nil,
                        artifact_state: nil, artifact_phase: nil, verification: nil)
-          super(error_code: CODES.include?(error_code) ? error_code : nil,
-                error_type: self.class.type(error_type), phase: PHASES.include?(phase) ? phase : nil,
-                underlying_type: self.class.type(underlying_type),
+          super(error_code: ErrorMetadata.code(error_code),
+                error_type: ErrorMetadata.type(error_type), phase: ErrorMetadata.phase(phase),
+                underlying_type: ErrorMetadata.type(underlying_type),
                 artifact_state: ARTIFACT_STATES.include?(artifact_state) ? artifact_state : nil,
                 artifact_phase: ARTIFACT_PHASES.include?(artifact_phase) ? artifact_phase : nil,
                 verification: verification == :device_reported ? verification : nil)
         end
 
-        def self.type(name)
-          return if name.nil?
-
-          name.instance_of?(String) && TYPES.include?(name) ? name.dup.freeze : "StandardError"
-        end
-
         # 读取已知错误的白名单属性后立即丢弃异常引用，不把回调对象保留进批次。
         def self.from(error, backup: nil, phase: nil)
           return unless error
 
-          fields = { error_type: type(error.class.name) || "StandardError", phase: phase }
+          fields = { error_type: ErrorMetadata.type(error.class.name) || "StandardError", phase: phase }
           if error.is_a?(Net::Connector::Error)
             fields.merge!(error_code: error.code, phase: phase || error.phase)
             fields[:underlying_type] = error.underlying.type if error.underlying.instance_of?(UnderlyingError)
@@ -74,10 +44,10 @@ module Net
           if error.instance_of?(BackupPersistenceError) && backup.instance_of?(Backup) && error.backup.equal?(backup)
             { artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,
               underlying_type: error.underlying_type }
-          elsif error.instance_of?(TftpCompletionError) && backup.instance_of?(TftpBackup) && error.transfer.equal?(backup)
+          elsif error.instance_of?(TftpCompletionError) && backup.instance_of?(TftpReceipt) && error.receipt.equal?(backup)
             { artifact_state: :reported_uploaded, artifact_phase: error.code == :transfer_finalize_failed ? :finalize : :path,
               verification: :device_reported, underlying_type: error.underlying_type }
-          elsif phase == :report && Operations::PrivateFile.receipt_error?(error)
+          elsif phase == :report && Storage::PrivateFile.receipt_error?(error)
             { error_code: error.code, artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,
               underlying_type: error.underlying_type }
           else