net-connector 0.4.2 → 0.5.0

data/lib/net/connector/vendor/h3c/topology.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/topology/immediate_strategy"
+require_relative "../../device/topology/immediate_strategy"
 
 module Net
   module Connector
     module H3c
-      class Topology < Operations::Topology::ImmediateStrategy
+      class Topology < Topology::ImmediateStrategy
         TABLE_HEADER = /^\s*(?:System Name\s+Local Interface\b|(?:Local Interface|LocalIf)\s+)/i
         # H3C 提供 LLDP 邻居、配置描述读取和描述变更。
         def self.supports?(capability)
@@ -19,10 +19,10 @@ module Net
         def description_template = "h3c_interface_descriptions.textfsm"
 
         # 进入系统视图以修改接口描述。
-        def enter_configuration = "system-view"
+        def enter_configuration_command = "system-view"
 
         # 返回用户视图读回；保存交给后续独立阶段。
-        def leave_configuration = ["return"]
+        def leave_configuration_commands = ["return"]
 
         def persistence_pattern = /\ASaved the current configuration to mainboard device successfully\.\z/i
 
@@ -52,7 +52,7 @@ module Net
 
         # 在接口视图设置描述后用 quit 返回系统视图。
         def change_commands(change)
-          InterfaceDescription.commands(interface: change.interface, description: change.new_description, leave: "quit")
+          Net::Connector::Topology::InterfaceDescription.commands(interface: change.interface, description: change.new_description, leave: "quit")
         end
 
         private

data/lib/net/connector/vendor/h3c.rb

@@ -56,7 +56,7 @@ module Net
           return command unless /\A[ \t]*rule[ \t]+XXX[ \t]+append\b/i.match?(command.text)
 
           rule_id = execution.context[:rule_id]
-          raise execution.failure("new rule ID has not been acquired") unless rule_id
+          raise execution.build_error("new rule ID has not been acquired") unless rule_id
 
           command.with_text(command.text.sub(/XXX/i, rule_id))
         end
@@ -65,9 +65,9 @@ module Net
         def after_command(command, _response, execution)
           return unless /\A[ \t]*rule[ \t]+pass\b/i.match?(command.text)
 
-          response = execution.query("dis this")
+          response = execution.execute_command("dis this")
           rule_id = response.raw[/rule\s+(\d+)\s+pass[^\n]+\n\s*#/i, 1]
-          raise execution.failure("device did not return the new rule ID") unless rule_id
+          raise execution.build_error("device did not return the new rule ID") unless rule_id
 
           execution.context[:rule_id] = rule_id
         end

data/lib/net/connector/vendor/hillstone/tftp_backup.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/tftp/strategy"
+require_relative "../../device/tftp/strategy"
 
 module Net
   module Connector
     module Hillstone
-      class TftpBackup < Operations::Tftp::Strategy
+      class TftpBackup < Tftp::Strategy
         # 山石原生导出的配置文件使用 dat 扩展名。
         def self.file_extension = "dat"
 
@@ -31,7 +31,7 @@ module Net
         end
 
         # 检查设备回显是否确认 TFTP 传输完成。
-        def complete?(result)
+        def device_reported_complete?(result)
           !completion_line(result).nil?
         end
 

data/lib/net/connector/vendor/hillstone/topology.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/topology/immediate_strategy"
+require_relative "../../device/topology/immediate_strategy"
 
 module Net
   module Connector
     module Hillstone
-      class Topology < Operations::Topology::ImmediateStrategy
+      class Topology < Topology::ImmediateStrategy
         # 山石提供 LLDP 邻居、配置描述读取和描述变更。
         def self.supports?(capability)
           %i[neighbors interface_descriptions interface_description_changes].include?(capability)
@@ -18,10 +18,10 @@ module Net
         def description_template = "hillstone_interface_descriptions.textfsm"
 
         # 进入配置视图。
-        def enter_configuration = "configure"
+        def enter_configuration_command = "configure"
 
         # 退出配置视图后先读回，保存动作随后单独执行。
-        def leave_configuration = ["exit"]
+        def leave_configuration_commands = ["exit"]
 
         def persistence_pattern = /\ASaving configuration is finished\.?\z/i
 
@@ -43,7 +43,7 @@ module Net
 
         # 复用公共接口描述命令。
         def change_commands(change)
-          InterfaceDescription.commands(interface: change.interface, description: change.new_description)
+          Net::Connector::Topology::InterfaceDescription.commands(interface: change.interface, description: change.new_description)
         end
 
         private

data/lib/net/connector/vendor/huawei/tftp_backup.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/tftp/file_upload"
+require_relative "../../device/tftp/file_upload"
 
 module Net
   module Connector
     module Huawei
-      class TftpBackup < Operations::Tftp::FileUpload
+      class TftpBackup < Tftp::FileUpload
         # 缺少源文件也必须在首次设备 I/O 之前拒绝。
         def validate_options!(target, source_file:, vrf: nil)
           super
@@ -13,7 +13,7 @@ module Net
         end
 
         # 要求调用方提供合法的华为启动配置文件路径。
-        def source_file(value)
+        def resolve_source_file(value)
           raise ArgumentError, "Huawei TFTP backup requires source_file" unless value
 
           TftpTarget.validate_source_file!(value)

data/lib/net/connector/vendor/palo_alto/running_config.rb

@@ -23,7 +23,7 @@ module Net
         end
 
         # 采集前后都检查候选差异，拒绝把未提交配置误作运行配置。
-        def check_response(command, response, _execution)
+        def validate_response!(command, response, _execution)
           return unless command.text == "show config diff"
           return if body(response.output, command.text).empty?
 

data/lib/net/connector/vendor/palo_alto/tftp_backup.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/tftp/strategy"
+require_relative "../../device/tftp/strategy"
 
 module Net
   module Connector
     module PaloAlto
-      class TftpBackup < Operations::Tftp::Strategy
+      class TftpBackup < Tftp::Strategy
         FILENAME = "running-config.xml"
 
         # 返回 PAN-OS 固定使用的运行配置文件名。
@@ -33,7 +33,7 @@ module Net
         end
 
         # 检查设备回显是否确认 TFTP 传输完成。
-        def complete?(result)
+        def device_reported_complete?(result)
           completion_lines(result).any? do |line|
             line.match?(/\ASent\s+[1-9]\d*\s+bytes(?:\s+in\s+[\d.]+\s+(?:secs?|seconds?))?[.!]?\z/i)
           end

data/lib/net/connector/vendor/palo_alto/topology.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/topology/strategy"
+require_relative "../../device/topology/strategy"
 
 module Net
   module Connector
     module PaloAlto
-      class Topology < Operations::Topology::Strategy
+      class Topology < Topology::Strategy
         # 候选配置缺少经固件实验确认的所有权/commit 协议，暂只提供读取能力。
         def self.supports?(capability)
           %i[neighbors interface_descriptions].include?(capability)
@@ -20,10 +20,7 @@ module Net
         def description_template = "palo_alto_interface_descriptions.textfsm"
 
         # 进入候选配置视图。
-        def enter_configuration = "configure"
-
-        # 提交候选配置后退出配置视图。
-        def finish_commands = ["commit", "exit"]
+        def enter_configuration_command = "configure"
 
         # 只计入非空邻居块，跳过没有对端的本机接口。
         def expected_neighbor_count(output, _template)

data/lib/net/connector/vendor/radware/tftp_backup.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/tftp/strategy"
+require_relative "../../device/tftp/strategy"
 
 module Net
   module Connector
     module Radware
-      class TftpBackup < Operations::Tftp::Strategy
+      class TftpBackup < Tftp::Strategy
         # Radware 原生导出生成压缩配置归档。
         def self.file_extension = "tgz"
 
@@ -32,7 +32,7 @@ module Net
         end
 
         # 检查设备回显是否确认 TFTP 传输完成。
-        def complete?(result)
+        def device_reported_complete?(result)
           completion_lines(result).any? do |line|
             line.match?(/\A
               (?:Current\s+)?(?:configuration|config)\s+

data/lib/net/connector/vendor/radware/topology.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/topology/strategy"
+require_relative "../../device/topology/strategy"
 
 module Net
   module Connector
     module Radware
-      class Topology < Operations::Topology::Strategy
+      class Topology < Topology::Strategy
         # Alteon 只支持读取端口描述，不提供邻居发现或自动改写。
         def self.supports?(capability) = capability == :interface_descriptions
 

data/lib/net/connector/version.rb

@@ -2,6 +2,6 @@
 
 module Net
   module Connector
-    VERSION = "0.4.2"
+    VERSION = "0.5.0"
   end
 end

data/lib/net/connector.rb

@@ -16,18 +16,13 @@ module Net
       hillstone: "Hillstone"
     }.freeze
 
-    ALIASES = {
-      "cisco_n9k" => :cisco_nxos,
-      "paloalto" => :palo_alto
-    }.freeze
-
     # 返回当前支持的厂商标识集合。
     def self.vendors = VENDORS.keys
 
     # 根据厂商标识查找连接器类。
     def self.vendor_class(vendor)
       key = vendor.to_s.downcase.tr(" -", "__")
-      key = ALIASES.fetch(key, key.to_sym)
+      key = key.to_sym
       name = VENDORS.fetch(key) { raise ArgumentError, "unsupported vendor: #{vendor.inspect}" }
       require_relative "connector/vendor/#{key}"
       const_get(name, false).const_get(:Connector, false)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - net-connector contributors
@@ -411,28 +411,40 @@ files:
 - lib/net-connector.rb
 - lib/net/connector.rb
 - lib/net/connector/device/base.rb
-- lib/net/connector/device/interface_description.rb
-- lib/net/connector/device/interface_name.rb
+- lib/net/connector/device/local_backup.rb
 - lib/net/connector/device/profile.rb
 - lib/net/connector/device/profile/builder.rb
 - lib/net/connector/device/running_config.rb
 - lib/net/connector/device/running_config/strategy.rb
-- lib/net/connector/engine.rb
+- lib/net/connector/device/save_config.rb
+- lib/net/connector/device/tftp.rb
+- lib/net/connector/device/tftp/file_upload.rb
+- lib/net/connector/device/tftp/receipt.rb
+- lib/net/connector/device/tftp/strategy.rb
+- lib/net/connector/device/tftp/target.rb
+- lib/net/connector/device/topology.rb
+- lib/net/connector/device/topology/immediate_strategy.rb
+- lib/net/connector/device/topology/interface_description.rb
+- lib/net/connector/device/topology/interface_name.rb
+- lib/net/connector/device/topology/strategy.rb
 - lib/net/connector/engine/authentication.rb
-- lib/net/connector/engine/base.rb
 - lib/net/connector/engine/command.rb
 - lib/net/connector/engine/configuration.rb
 - lib/net/connector/engine/core.rb
 - lib/net/connector/engine/dialogue.rb
+- lib/net/connector/engine/error_metadata.rb
 - lib/net/connector/engine/errors.rb
 - lib/net/connector/engine/execution.rb
 - lib/net/connector/engine/log.rb
-- lib/net/connector/engine/log_messages.rb
-- lib/net/connector/engine/profile.rb
+- lib/net/connector/engine/log/event.rb
+- lib/net/connector/engine/log/formatter.rb
+- lib/net/connector/engine/log/messages.rb
+- lib/net/connector/engine/log/stream.rb
 - lib/net/connector/engine/recovery.rb
 - lib/net/connector/engine/result.rb
 - lib/net/connector/engine/session.rb
 - lib/net/connector/engine/terminal_renderer.rb
+- lib/net/connector/engine/terminal_text.rb
 - lib/net/connector/engine/transport.rb
 - lib/net/connector/netdisco.rb
 - lib/net/connector/netdisco/batch.rb
@@ -450,38 +462,11 @@ files:
 - lib/net/connector/netdisco/rules.rb
 - lib/net/connector/netdisco/settings.rb
 - lib/net/connector/netdisco/worker.rb
-- lib/net/connector/operations.rb
-- lib/net/connector/operations/backup_lock.rb
-- lib/net/connector/operations/local_backup.rb
-- lib/net/connector/operations/parse_output.rb
-- lib/net/connector/operations/private_file.rb
-- lib/net/connector/operations/running_config.rb
-- lib/net/connector/operations/running_config/cisco.rb
-- lib/net/connector/operations/running_config/hillstone.rb
-- lib/net/connector/operations/running_config/palo_alto.rb
-- lib/net/connector/operations/running_config/strategy.rb
-- lib/net/connector/operations/safe_file.rb
-- lib/net/connector/operations/saved_config.rb
-- lib/net/connector/operations/saved_config/legacy_index.rb
-- lib/net/connector/operations/tftp/cisco_ios.rb
-- lib/net/connector/operations/tftp/cisco_nxos.rb
-- lib/net/connector/operations/tftp/file_upload.rb
-- lib/net/connector/operations/tftp/h3c.rb
-- lib/net/connector/operations/tftp/hillstone.rb
-- lib/net/connector/operations/tftp/huawei.rb
-- lib/net/connector/operations/tftp/palo_alto.rb
-- lib/net/connector/operations/tftp/radware.rb
-- lib/net/connector/operations/tftp/strategy.rb
-- lib/net/connector/operations/tftp_backup.rb
-- lib/net/connector/operations/tftp_receipt.rb
-- lib/net/connector/operations/topology.rb
-- lib/net/connector/operations/topology/cisco.rb
-- lib/net/connector/operations/topology/h3c.rb
-- lib/net/connector/operations/topology/hillstone.rb
-- lib/net/connector/operations/topology/immediate_strategy.rb
-- lib/net/connector/operations/topology/palo_alto.rb
-- lib/net/connector/operations/topology/radware.rb
-- lib/net/connector/operations/topology/strategy.rb
+- lib/net/connector/storage.rb
+- lib/net/connector/storage/backup_lock.rb
+- lib/net/connector/storage/private_file.rb
+- lib/net/connector/storage/safe_file.rb
+- lib/net/connector/storage/saved_config.rb
 - lib/net/connector/templates/cisco_cdp_neighbors_detail.textfsm
 - lib/net/connector/templates/cisco_ios_running_config_interfaces.textfsm
 - lib/net/connector/templates/cisco_ios_show_ip_interface_brief.textfsm
@@ -494,6 +479,7 @@ files:
 - lib/net/connector/templates/palo_alto_interface_descriptions.textfsm
 - lib/net/connector/templates/palo_alto_lldp_neighbors.textfsm
 - lib/net/connector/templates/radware_port_names.textfsm
+- lib/net/connector/textfsm.rb
 - lib/net/connector/vendor/cisco_ios.rb
 - lib/net/connector/vendor/cisco_ios/running_config.rb
 - lib/net/connector/vendor/cisco_ios/tftp_backup.rb

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

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "interface_name"
-
-module Net
-  module Connector
-    # 描述文本与常见接口视图命令的纯构造方法，不连接或修改设备。
-    module InterfaceDescription
-      # 将邻居名称和接口拼成默认描述；只缩写邻居接口，保留原始大小写。
-      def self.format(neighbor, abbreviate: true, lowercase: false)
-        port = if abbreviate
-                 InterfaceName.short(neighbor.neighbor_interface, lowercase: lowercase)
-               else
-                 lowercase ? neighbor.neighbor_interface.downcase : neighbor.neighbor_interface
-               end
-        validate!("To #{neighbor.neighbor_name} #{port}")
-      end
-
-      # 生成进入接口、设置描述和退出视图的命令，不执行设备操作。
-      def self.commands(interface:, description:, leave: "exit")
-        validate_interface!(interface)
-        validate!(description)
-        raise ArgumentError, "interface exit must be exit or quit" unless %w[exit quit].include?(leave)
-
-        ["interface #{interface}", "description #{description}", leave]
-      end
-
-      # 共享的输入约束同样适用于 PAN-OS 的独立命令语法。
-      def self.validate!(value)
-        return value if value.is_a?(String) && value.bytesize.between?(1, 80) &&
-                        value.match?(/\A[\p{Alnum}_.: \/-]+\z/u)
-
-        raise ArgumentError, "description must be 1-80 bytes of plain interface text"
-      end
-
-      # 拒绝可能把描述命令拆成多条命令的不安全接口名。
-      def self.validate_interface!(value)
-        return value if value.is_a?(String) && value.match?(/\A[A-Za-z][A-Za-z0-9.\/-]*\z/)
-
-        raise ArgumentError, "neighbor interface name is unsafe"
-      end
-    end
-  end
-end

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

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-module Net
-  module Connector
-    # 接口身份匹配与描述展示共用名称规则；展示简称不能直接用作下发命令。
-    module InterfaceName
-      RULES = [
-        [/\A(?:xge|ten-gigabitethernet|tengigabitethernet|te)(?=\d)/i, "tengigabitethernet", "Te"],
-        [/\A(?:gigabitethernet|ge|gi)(?=\d)/i, "gigabitethernet", "Gi"],
-        [/\A(?:fastethernet|fa)(?=\d)/i, "fastethernet", "Fa"],
-        [/\A(?:ethernet|eth)(?=\d)/i, "ethernet", "Eth"],
-        [/\A(?:port-channel|po)(?=\d)/i, "port-channel", "Po"]
-      ].map(&:freeze).freeze
-
-      # 用于本机邻居表与配置的关联；保留已有证据键的拼写契约。
-      def self.key(name)
-        rule = RULES.find { |pattern, _key, _short| pattern.match?(name) }
-        rule ? name.sub(rule.first, rule[1]).downcase : name.downcase
-      end
-
-      # 仅缩短已识别的前缀，保留端口、子接口编号及未知命名。
-      # 默认延续输入的大写、小写或首字母大写形式；统一小写由调用方选择。
-      def self.short(name, lowercase: false)
-        rule = RULES.find { |pattern, _key, _short| pattern.match?(name) }
-        formatted = if rule
-                      name.sub(rule.first) do |prefix|
-                        abbreviation = rule.last
-                        if prefix == prefix.downcase
-                          abbreviation.downcase
-                        elsif prefix == prefix.upcase
-                          abbreviation.upcase
-                        elsif prefix.casecmp?(abbreviation)
-                          prefix
-                        else
-                          abbreviation
-                        end
-                      end
-                    else
-                      name.dup
-                    end
-        lowercase ? formatted.downcase : formatted
-      end
-
-      # 保留现有配置视图展开规则；厂商策略可覆盖不适用的名称。
-      def self.configuration(name)
-        name.sub(/\AXGE(?=\d)/i, "Ten-GigabitEthernet")
-            .sub(/\AGE(?=\d)/i, "GigabitEthernet")
-            .sub(/\AGi(?=\d)/i, "GigabitEthernet")
-            .sub(/\ATe(?=\d)/i, "TenGigabitEthernet")
-            .sub(/\AFa(?=\d)/i, "FastEthernet")
-            .sub(/\AEth(?=\d)/i, "Ethernet")
-            .sub(/\APo(?=\d)/i, "port-channel")
-      end
-    end
-  end
-end

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

@@ -1,4 +0,0 @@
-# frozen_string_literal: true
-
-# 旧加载路径保留为转发入口；设备定义位于 device/。
-require_relative "../device/base"

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

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Net
-  module Connector
-    # 独立于日志目标的人类可读事件文案。
-    module LogMessages
-      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 "command_detail"
-          "命令耗时 #{fields[:duration_ms]} 毫秒，收到 #{fields[:response_bytes]} 字节回显"
-        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

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

@@ -1,4 +0,0 @@
-# frozen_string_literal: true
-
-# 旧加载路径保留为转发入口；设备定义位于 device/。
-require_relative "../device/profile"

data/lib/net/connector/engine.rb

@@ -1,4 +0,0 @@
-# frozen_string_literal: true
-
-# 保留原设备门面入口；只需要会话执行层时加载 engine/core。
-require_relative "device/base"

data/lib/net/connector/operations/local_backup.rb

@@ -1,89 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-require_relative "private_file"
-require_relative "backup_lock"
-require_relative "safe_file"
-
-module Net
-  module Connector
-    Backup = Data.define(:path, :bytes, :sha256, :collected_at, :change, :previous_sha256) do
-      # 保存配置备份的路径、摘要和变更状态。
-      def initialize(path:, bytes:, sha256:, collected_at:, change: nil, previous_sha256: nil)
-        super
-      end
-
-      # 判断本次采集是否产生新的配置内容。
-      def changed? = [:created, :changed].include?(change)
-    end
-
-    # 只携带库自身的提交回执和配置元数据，不携带正文或原始文件系统异常。
-    class BackupPersistenceError < Error
-      attr_reader :backup, :receipt, :underlying_type
-
-      def initialize(backup:, write_error:, host: nil)
-        unless backup.instance_of?(Backup) && Operations::PrivateFile.receipt_error?(write_error) &&
-               write_error.receipt.committed? && write_error.receipt.path == backup.path
-          raise ArgumentError, "backup persistence error requires a matching committed backup receipt"
-        end
-
-        @backup, @receipt = backup, write_error.receipt
-        @underlying_type = write_error.underlying_type
-        code = if write_error.instance_of?(Operations::PrivateFile::DirectorySyncUnsupported)
-                 :backup_durability_unsupported
-               elsif receipt.durable?
-                 :backup_finalize_failed
-               else
-                 :backup_persistence_unconfirmed
-               end
-        super(write_error.message, code: code, host: host, phase: :backup)
-      end
-    end
-
-    module Operations
-      class LocalBackup
-        # 保存执行配置采集的设备对象。
-        def initialize(device) = @device = device
-
-        # 采集配置、识别变更并原子写入私有文件。
-        def call(path:, lock_timeout: 0)
-          host = @device.host if @device.respond_to?(:host)
-          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 = 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 || !SafeFile.same_entry?(destination, previous)
-            write_backup(backup, contents)
-          end
-          backup
-        end
-
-        def write_backup(backup, contents)
-          PrivateFile.write_receipt(backup.path, contents)
-        rescue PrivateFile::WriteError => error
-          raise unless 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
-end