netstack 0.1.1 → 0.2.0

data/lib/netstack/connector/error.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    # 操作错误携带已脱敏上下文；敏感配置正文只存在于明确返回的业务结果中。
+    class Error < StandardError
+      attr_reader :code, :host, :phase, :command, :output, :source, :line, :underlying
+
+      # 保存错误阶段、命令和输出尾部，并为缺省错误类生成稳定错误码。
+      def initialize(message, code: nil, host: nil, phase: nil, command: nil, output: "".b,
+                     source: nil, line: nil, underlying: nil)
+        super(message)
+        @code = code || self.class.name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+        @host = host
+        @phase = phase
+        @command = command
+        @output = output.freeze
+        @source = source
+        @line = line
+        @underlying = underlying
+      end
+
+      # 内置错误保留业务回执，但不复制可能含秘密的原生 cause 和调用栈。
+      # 自定义子类重新构造，避免其 message 等方法继续读取未脱敏的私有字段。
+      def with_diagnostics(message:, **context)
+        context = { code: code, host: host, phase: phase, command: command, output: output,
+                    source: source, line: line, underlying: underlying }.merge(context)
+        return self.class.new(message, **context) unless ErrorMetadata.known_type?(self.class.name)
+
+        copy = self.class.allocate
+        instance_variables.each { |name| copy.instance_variable_set(name, instance_variable_get(name)) }
+        Error.instance_method(:initialize).bind_call(copy, message, **context)
+        copy
+      end
+
+      # 返回不展开命令和输出的错误摘要。
+      def inspect = "#<#{self.class} code=#{ErrorMetadata.code(code).inspect} phase=#{ErrorMetadata.phase(phase).inspect}>"
+    end
+  end
+end

data/lib/netstack/connector/error_metadata.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    # 日志与报告共用固定诊断词表；未知元数据可能来自配置正文，不能作为自由文本输出。
+    module ErrorMetadata
+      CONNECTOR_TYPES = %w[Error ConnectionError AuthenticationError LoginTimeout CommandTimeout WriteTimeout
+                           PromptError ConnectionClosed TransportError DeviceError ScriptError InternalError
+                           OutputLimitExceeded ScriptOutputLimitExceeded SessionBusy UnsupportedOperation LogError ParsingError BackupBusy
+                           BackupPersistenceError TftpCompletionError].freeze
+      TYPES = (CONNECTOR_TYPES.map { |name| "Netstack::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
+           Netstack::Connector::Storage::PrivateFile::WriteError
+           Netstack::Connector::Storage::PrivateFile::PersistenceError
+           Netstack::Connector::Storage::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 save interact tftp_backup report callback].freeze
+      private_constant :CONNECTOR_TYPES, :TYPES, :CODES, :PHASES
+
+      module_function
+
+      def code(value) = CODES.include?(value) ? value : nil
+
+      def default_code(name)
+        return :error unless known_type?(name)
+
+        code(name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym) || :error
+      end
+
+      def phase(value) = PHASES.include?(value) ? value : nil
+
+      def known_type?(name) = name.instance_of?(String) && TYPES.include?(name)
+
+      def type(name)
+        return if name.nil?
+
+        known_type?(name) ? name.dup.freeze : "StandardError"
+      end
+    end
+  end
+end

data/lib/netstack/connector/event.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "open3"
+require "expect/pty"
+
+module Netstack
+  module Connector
+    # 传输事件使用从零开始的模式索引；最后一个额外索引表示流式数据。
+    Event = Struct.new(:index, :before, :match, :error) do
+      # 规范化事件的默认字节字段，便于读取器统一处理。
+      def initialize(index: nil, before: "".b, match: "".b, error: nil)
+        super
+      end
+
+      # 判断读取是否命中了模式而不是传输错误。
+      def matched? = error.nil?
+
+      # 返回事件索引和错误类型摘要。
+      def inspect = "#<#{self.class} index=#{index.inspect} error=#{error&.class}>"
+    end
+  end
+end

data/lib/netstack/connector/execution.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    # 单个脚本的局部状态；执行对象不拥有设备或传输层生命周期。
+    class Execution
+      attr_reader :context, :steps
+
+      # 保存命令准备和后处理钩子，并初始化批次上下文及已完成步骤。
+      def initialize(session:, timeout:, prepare:, after_command:, prompt: nil)
+        @session = session
+        @command_timeout = timeout
+        @prepare_command = prepare
+        @after_command = after_command
+        @prompt_resolver = prompt
+        @context = {}
+        @steps = []
+        @output_bytes = 0
+        @output_limit = session.configuration.max_script_output_bytes
+        @sensitive = false
+      end
+
+      # 汇总实际执行的命令及交互，包括批次准备和厂商追加查询。
+      def sensitive? = @sensitive
+
+      # 依次准备、执行和记录脚本命令；失败时保留已完成步骤并统一抛错。
+      def execute_script(script)
+        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
+            started = Expect.monotonic
+            step = nil
+            response = execute_command(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?
+            validate_response_budget!(@last_executed_command)
+          rescue => error
+            raise @session.normalize_error(error, phase: :script, command: @current_command), cause: nil
+          end
+        end
+        validate_response_budget!(@last_executed_command)
+        Result.new(steps: steps)
+      end
+
+      # 厂商后续查询复用同一信道和错误处理，不开启新的批处理。
+      def execute_command(command)
+        command = Command.new(command) unless command.is_a?(Command)
+        validate_send_budget!(command)
+        prompt = @prompt_resolver&.call(command)
+        # 提示符回调也可能追加查询，实际发送前重新检查它消耗的预算。
+        validate_send_budget!(command) if @prompt_resolver
+        response = @session.execute_command(command, timeout: @command_timeout, prompt: prompt) do |received|
+          # 必须在 Session 恢复命令词表前读取；最终处理只能继承敏感性，不长期保留秘密。
+          @sensitive ||= @session.redactor.sensitive?
+          if received
+            @last_executed_command = command
+            @output_bytes += received.raw.bytesize
+            # 日志收尾失败也保留完整响应和预算；追加查询不改变原 steps 结构。
+            yield received if block_given?
+          end
+        end
+        validate_response_budget!(command)
+        response
+      end
+
+      # 只有当前会话未特权时才执行特权认证。
+      def enable(command, prompt)
+        @session.enable(command, prompt) unless @session.privileged?
+      end
+
+      # 根据当前命令建立脚本阶段错误。
+      def build_error(message)
+        @session.build_error(ScriptError, message, phase: :script, command: @current_command)
+      end
+
+      private
+
+      # 单响应上限仍约束正在读取的命令；累计预算阻止继续发送，不承诺设备尚未执行。
+      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
+      end
+    end
+  end
+end

data/lib/netstack/connector/interaction.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/pty"
+
+module Netstack
+  module Connector
+    # 一组提示与响应规则；可调用响应支持一次性密码等动态挑战。
+    class Interaction
+      attr_reader :pattern, :limit
+
+      # 校验提示模式、响应类型和次数限制，然后冻结规则定义。
+      def initialize(pattern, response, sensitive: false, limit: nil, capture: true)
+        unless pattern.is_a?(Regexp) && !pattern.match?("")
+          raise ArgumentError, "interaction pattern must be a nonempty Regexp"
+        end
+        unless response.is_a?(String) || response.respond_to?(:call)
+          raise ArgumentError, "response must be a String or callable"
+        end
+        valid_limit = limit.nil? || (limit.is_a?(Integer) && limit.positive?)
+        unless valid_limit
+          raise ArgumentError, "limit must be positive or nil"
+        end
+        unless [true, false].include?(sensitive) && [true, false].include?(capture)
+          raise ArgumentError, "sensitive and capture must be true or false"
+        end
+
+        @pattern = pattern
+        @response = response.is_a?(String) ? response.dup.freeze : response
+        @sensitive = sensitive
+        @limit = limit
+        @capture = capture
+        freeze
+      end
+
+      # 根据当前提示计算响应文本或调用动态响应函数。
+      def response(prompt) = @response.respond_to?(:call) ? @response.call(prompt) : @response
+
+      # 判断响应是否需要从日志和错误上下文中脱敏。
+      def sensitive? = @sensitive
+
+      # 判断提示文本是否应保留在响应输出中。
+      def capture? = @capture
+
+      # 返回不包含响应内容的规则摘要。
+      def inspect = "#<#{self.class} sensitive=#{sensitive?}>"
+
+      # 将普通交互转换为一次性的敏感挑战。
+      def challenge
+        self.class.new(pattern, @response, sensitive: true, limit: limit || 1, capture: false)
+      end
+    end
+  end
+end

data/lib/netstack/connector/internal_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class InternalError < Error; end
+  end
+end

data/lib/netstack/connector/known_hosts.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "fileutils"
+require "tempfile"
+require "open3"
+
+module Netstack
+  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
+        @lock_timeout = configuration.login_timeout
+        @original = read_shared
+        # OpenSSH 以追加模式登记新密钥；私有副本必须在完整行后开始，且差量基线保持一致。
+        @original << "\n" unless @original.empty? || @original.end_with?("\n")
+        @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
+          acquire_lock(file)
+          current = File.lstat(lock_path)
+          raise IOError, "known_hosts lock changed" unless current.dev == stat.dev && current.ino == stat.ino
+
+          yield
+        end
+      end
+
+      def acquire_lock(file)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @lock_timeout
+        until file.flock(File::LOCK_EX | File::LOCK_NB)
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if remaining <= 0
+            raise LoginTimeout.new("known_hosts lock acquisition timed out", phase: :login), cause: nil
+          end
+
+          sleep([remaining, 0.05].min)
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/local_backup.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "digest"
+
+module Netstack
+  module Connector
+    class LocalBackup
+      # 设备入口与功能实现共置，Device 只组合能力，不重复业务流程。
+      module Capability
+        # 采集配置并以原子方式保存为私有文件。
+        # 采集失败时保留已有备份文件。
+        def backup(path:, lock_timeout: 0)
+          @session.assert_path_lock_order!(:backup)
+          LocalBackup.new(self).call(path: path, lock_timeout: lock_timeout)
+        end
+      end
+
+      # 保存执行配置采集的设备对象。
+      def initialize(device) = @device = device
+
+      # 采集配置、识别变更并原子写入私有文件。
+      def call(path:, lock_timeout: 0)
+        host = @device.host if @device.respond_to?(:host)
+        Storage::BackupLock.synchronize(path, timeout: lock_timeout, host: host) { |lock| collect_and_write(lock.path) }
+      end
+
+      private
+
+      def collect_and_write(destination)
+        contents = @device.running_config.value!
+        digest = Digest::SHA256.hexdigest(contents)
+        previous = Storage::SafeFile.fingerprint(destination, missing: true, replace_symlink: true)
+        previous_digest = previous&.sha256
+        change = if previous_digest.nil?
+                   :created
+                 elsif previous_digest == digest
+                   :unchanged
+                 else
+                   :changed
+                 end
+
+        backup = Backup.new(path: destination, bytes: contents.bytesize,
+                            sha256: digest, collected_at: Time.now.utc, change: change,
+                            previous_sha256: previous_digest)
+        if change != :unchanged || previous.mode != 0o600 || !Storage::SafeFile.same_entry?(destination, previous)
+          write_backup(backup, contents)
+        end
+        backup
+      end
+
+      def write_backup(backup, contents)
+        Storage::PrivateFile.write(backup.path, contents)
+      rescue Storage::PrivateFile::WriteError => error
+        raise unless Storage::PrivateFile.receipt_error?(error) && error.receipt.committed?
+
+        host = @device.host if @device.respond_to?(:host)
+        raise BackupPersistenceError.new(backup: backup, write_error: error, host: host), cause: nil
+      end
+    end
+  end
+end

data/lib/netstack/connector/log/event.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class Log
+      # 在敏感作用域结束前冻结安全副本；应用 formatter 可直接读取字段。
+      class Event
+        attr_reader :name, :fields
+
+        def initialize(name, fields, redactor:)
+          @name = safe_text(name.is_a?(String) || name.is_a?(Symbol) ? name.to_s : "custom", redactor).freeze
+          @fields = fields.each_with_object({}) do |(key, value), result|
+            next unless (key.is_a?(Symbol) || key.is_a?(String)) && key.to_s.match?(/\A[a-z][a-z0-9_]{0,63}\z/)
+            next unless redactor.call(key.to_s) == key.to_s
+            next if key.to_s == "event"
+
+            result[key.to_sym] = safe_value(value, redactor)
+          end.freeze
+          freeze
+        end
+
+        # 与文本呈现共用同一安全记录，调用方不能借 formatter 取得原始秘密。
+        def to_h = { event: name, **fields }.freeze
+
+        def to_s
+          details = to_h.reject { |key, _| key == :host }.map { |key, value| "#{key}=#{token(value)}" }.join(" ")
+          "[host=#{token(fields[:host])}] #{Messages.format(name, fields)} | #{details}"
+        end
+
+        # Ruby Logger 的默认 formatter 对非 String 消息调用 inspect。
+        alias inspect to_s
+
+        private
+
+        def safe_value(value, redactor)
+          case value
+          when String, Symbol
+            safe_text(value.to_s, redactor).freeze
+          when Float
+            value.finite? && redactor.call(value.to_s) == value.to_s ? value : "[REDACTED]"
+          when Integer, TrueClass, FalseClass, NilClass
+            redactor.call(value.to_s) == value.to_s ? value : "[REDACTED]"
+          else
+            # 不调用任意对象的 inspect/to_s，避免展开异常、配置对象或容器中的秘密。
+            "[REDACTED]"
+          end
+        end
+
+        def safe_text(text, redactor)
+          rendered = TerminalRenderer.render(redactor.call(text))
+          redactor.call(rendered).force_encoding(Encoding::UTF_8).scrub.gsub(/[[:cntrl:]]+/, " ").strip
+        end
+
+        def token(value)
+          return "nil" if value.nil?
+
+          text = value.to_s
+          text.match?(/\A[A-Za-z0-9_.:\/-]+\z/) ? text : text.inspect
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/log/formatter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "logger"
+
+module Netstack
+  module Connector
+    class Log
+      # 只安装在连接器自有的 Logger 上；注入的日志器保留应用自己的格式。
+      class Formatter < ::Logger::Formatter
+        def call(severity, time, _program, message)
+          "[#{time.getlocal.strftime("%Y-%m-%d %H:%M:%S.%L %:z")}] #{severity} #{message}\n"
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/log/messages.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class Log
+      # 独立于日志目标的人类可读事件文案。
+      module Messages
+        module_function
+
+        # 将结构化会话事件转换为便于人工阅读的中文日志。
+        def format(name, fields)
+          case name
+          when "connect"
+            "开始连接 #{fields[:host]}（#{fields[:protocol].to_s.upcase}，账号 #{fields[:username]}）"
+          when "connect_failed"
+            "连接失败：#{fields[:message]}（#{fields[:error]}）"
+          when "login_start"
+            "等待设备登录提示"
+          when "login_output"
+            "登录过程回显（已脱敏）："
+          when "login_complete"
+            fields[:status] == "ok" ? "登录成功，设备提示符：#{fields[:prompt]}" :
+              "登录失败：#{fields[:message]}（#{fields[:error]}）"
+          when "command_start"
+            "下发命令：#{fields[:text]}"
+          when "device_output"
+            "设备回显："
+          when "command_complete"
+            fields[:status] == "response_received" ? "命令回显结束，已收到设备提示符" :
+              "命令执行失败：#{fields[:message]}（#{fields[:error]}）"
+          when "operation_start"
+            "开始处理设备脚本"
+          when "operation_complete"
+            fields[:status] == "completed" ? "设备脚本处理完成" :
+              "设备脚本处理失败：#{fields[:message]}（#{fields[:error]}）"
+          when "tftp_backup"
+            case fields[:status]
+            when "reported_uploaded"
+              "TFTP 备份：设备报告上传成功，目标 #{fields[:server]}/#{fields[:path]}；服务器文件尚未核验"
+            when "transfer_failed"
+              "TFTP 备份失败：设备报告传输失败，服务器 #{fields[:server]}"
+            else
+              "TFTP 备份未确认：设备未报告上传成功，服务器 #{fields[:server]}"
+            end
+          else
+            name.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/log/redacting_writer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class Log
+      # 每个目标独占 expect-pty 的过滤流；此层只适配 IO，不实现匹配算法。
+      class RedactingWriter
+        def initialize(target, redactor)
+          @target = target
+          @redactor = redactor
+          @filter = redactor.stream
+        end
+
+        def write(bytes)
+          @filter.patterns = @redactor.patterns
+          @target.write(@filter.append(bytes.b))
+          bytes.bytesize
+        end
+
+        def flush = @target.flush
+
+        def finish
+          @filter.patterns = @redactor.patterns
+          # 配置正文由 Session 的敏感范围隔离；保留完整词匹配的收尾契约。
+          @target.write(@filter.finish(partial: false))
+          flush
+        end
+      end
+    end
+  end
+end