net-connector 0.4.1 → 0.5.0

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

@@ -12,20 +12,33 @@ module Net
                        host_overrides: {}, mappings: [])
           @include_hosts = string_list(include_hosts)
           @exclude_hosts = string_list(exclude_hosts)
+          @include_vendors = vendor_list(include_vendors)
+          @vendor_overrides = vendor_mapping(vendor_overrides)
+          @host_overrides = host_mapping(host_overrides)
+          @mappings = device_mappings(mappings)
+        end
+
+        # 校验允许使用的厂商列表。
+        def vendor_list(include_vendors)
           raise ArgumentError, "include_vendors must be an Array" unless include_vendors.is_a?(Array)
 
-          @include_vendors = include_vendors.map do |vendor|
+          vendors = include_vendors.map do |vendor|
             raise ArgumentError, "include_vendors contains an invalid value" unless vendor.is_a?(String) || vendor.is_a?(Symbol)
 
             vendor.to_sym
           end.freeze
-          unless @include_vendors.all? { |vendor| Net::Connector.vendors.include?(vendor) }
+          unless vendors.all? { |vendor| Net::Connector.vendors.include?(vendor) }
             raise ArgumentError, "include_vendors contains an unsupported connector"
           end
+          vendors
+        end
+
+        # 将清单厂商标签映射为受支持的连接器。
+        def vendor_mapping(vendor_overrides)
           unless vendor_overrides.is_a?(Hash)
             raise ArgumentError, "vendor_overrides must be a Hash"
           end
-          @vendor_overrides = vendor_overrides.to_h do |label, vendor|
+          vendor_overrides.to_h do |label, vendor|
             unless label.is_a?(String) && vendor.is_a?(String) && !label.empty?
               raise ArgumentError, "vendor_overrides must map labels to connector names"
             end
@@ -35,9 +48,13 @@ module Net
 
             [key, value]
           end.freeze
+        end
+
+        # 按规范化管理地址覆盖厂商，拒绝网段和无效地址。
+        def host_mapping(host_overrides)
           raise ArgumentError, "host_overrides must be a Hash" unless host_overrides.is_a?(Hash)
 
-          @host_overrides = host_overrides.to_h do |host, vendor|
+          host_overrides.to_h do |host, vendor|
             unless host.is_a?(String) && !host.include?("/") && vendor.is_a?(String)
               raise ArgumentError, "host_overrides must map IP addresses to connector names"
             end
@@ -51,9 +68,13 @@ module Net
 
             [address, connector]
           end.freeze
+        end
+
+        # 型号映射仅接受已声明字段，并冻结每条规则。
+        def device_mappings(mappings)
           raise ArgumentError, "mappings must be an Array" unless mappings.is_a?(Array)
 
-          @mappings = mappings.map do |rule|
+          mappings.map do |rule|
             unless rule.is_a?(Hash) && rule["vendor"].is_a?(String) && !rule["vendor"].empty? &&
                    rule["connector"].is_a?(String) &&
                    (rule.keys - %w[vendor os model_prefix connector]).empty? &&
@@ -68,6 +89,8 @@ module Net
           end.freeze
         end
 
+        private :vendor_list, :vendor_mapping, :host_mapping, :device_mappings
+
         # 根据地址、显式规则和厂商信息识别连接器。
         def resolve(row)
           begin

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

@@ -1,41 +1,95 @@
 # frozen_string_literal: true
 
 require "json"
-require "uri"
 
 module Net
   module Connector
     module Netdisco
-      # 使用时从环境中读取配置，并提供明确的默认值。
+      # 活的凭据来源与不可变的批次策略分开保存；只有明确列出的非敏感字段进入快照。
       class Settings
         DEFAULT_BACKUP_DIRECTORY = "backups"
         DEFAULT_CONCURRENCY = 4
         MAX_CONCURRENCY = 50
-        DEFAULT_PAGE_SIZE = 500
+        DEFAULT_PAGE_SIZE = Client::DEFAULTS.fetch(:page_size)
+        UNSET = Object.new.freeze
+        private_constant :UNSET
 
-        # 加载 YAML 配置，并使环境变量覆盖文件配置。
         def self.from_file(path, env: ENV)
-          new(env: ConfigFile.load(path).merge(env.to_h))
+          new(env: env, defaults: ConfigFile.load(path))
         end
 
-        # 保存当前批次读取配置所用的环境映射。
-        def initialize(env: ENV)
-          @env = env
+        def initialize(env: ENV, defaults: {}, overrides: {}, policy: nil, fixed: false)
+          @env, @defaults, @overrides = env, defaults, overrides
+          @policy, @fixed = policy, fixed
         end
 
-        # 使用 Netdisco 地址和认证信息创建客户端。
-        def client
-          options = { url: required("NETDISCO_URL"), page_size: integer("NETDISCO_PAGE_SIZE", DEFAULT_PAGE_SIZE) }
-          if present?(@env["NETDISCO_API_KEY"])
-            options[:api_key] = @env["NETDISCO_API_KEY"]
-          else
-            options[:username] = required("NETDISCO_USERNAME")
-            options[:password] = required("NETDISCO_PASSWORD")
+        # 快照自身不保留 ENV、凭据 resolver 或原 Settings 的引用，不能携带秘密进入摘要。
+        def snapshot(mode: :backup)
+          return @policy.validate!(mode: mode) if @policy
+          return validate!(mode: mode) if @fixed
+
+          keys = mode == :export ? ["NET_CONNECTOR_BACKUP_DIRECTORY"] : non_secret_keys
+          values = keys.each_with_object({}) do |key, result|
+            item = raw(key, UNSET)
+            result[key.freeze] = item.is_a?(String) ? item.dup.freeze : item unless item.equal?(UNSET)
           end
-          Client.new(**options)
+          self.class.new(env: values.freeze, fixed: true).validate!(mode: mode).freeze
+        end
+
+        # CLI 的一次预览/执行使用同一策略；凭据仍指向原环境映射，允许逐设备轮换。
+        def for_run(mode: :backup)
+          self.class.new(env: @env, defaults: @defaults, overrides: @overrides, policy: snapshot(mode: mode))
+        end
+
+        def validate!(mode:)
+          unless %i[backup tftp inventory show_config export].include?(mode)
+            raise ArgumentError, "unknown settings validation mode"
+          end
+          backup_directory
+          return self if mode == :export
+
+          client_options
+          rules
+          concurrency
+          limit_per_vendor
+          log_directory
+          connection_options
+          Net::Connector.vendors.each { |vendor| connection_options(vendor) }
+          tftp_source_files.each_value { |source| TftpTarget.validate_source_file!(source) }
+          tftp_vrfs
+          TftpTarget.new(host: tftp_server, path: "preflight.cfg") if tftp_server
+          self
+        end
+
+        def client(policy: snapshot(mode: :inventory))
+          options = policy.client_options
+          raise ArgumentError, "NETDISCO_URL is required" unless options.fetch(:url)
+
+          authentication = if (token = secret_value("NETDISCO_API_KEY"))
+                             { api_key: token }
+                           else
+                             { username: required_secret("NETDISCO_USERNAME"), password: required_secret("NETDISCO_PASSWORD") }
+                           end
+          Client.new(**options, **authentication)
+        end
+
+        # 原生客户端和 --show-config 共享同一预算、地址与 HTTP 策略校验。
+        def client_options
+          options = Client::DEFAULTS.to_h do |name, default|
+            key = "NETDISCO_#{name.to_s.upcase}"
+            parsed = case name
+                     when :inventory_timeout then number(key, default)
+                     when :allow_insecure_http then boolean(key, default)
+                     else integer(key, default)
+                     end
+            [name, parsed]
+          end
+          options = Client.options(**options)
+          url = value("NETDISCO_URL")
+          Client.validate_url!(url, allow_insecure_http: options.fetch(:allow_insecure_http)) if url
+          options.merge(url: url).freeze
         end
 
-        # 读取清单筛选和厂商映射规则。
         def rules
           Rules.new(include_hosts: list("NET_CONNECTOR_INCLUDE_HOSTS"),
                     exclude_hosts: list("NET_CONNECTOR_EXCLUDE_HOSTS"),
@@ -45,15 +99,13 @@ module Net
                     mappings: json("NET_CONNECTOR_DEVICE_RULES", []))
         end
 
-        # 读取并展开本地备份目录。
         def backup_directory
-          path = @env.fetch("NET_CONNECTOR_BACKUP_DIRECTORY", DEFAULT_BACKUP_DIRECTORY)
+          path = raw("NET_CONNECTOR_BACKUP_DIRECTORY", DEFAULT_BACKUP_DIRECTORY)
           raise ArgumentError, "NET_CONNECTOR_BACKUP_DIRECTORY must be nonempty" unless present?(path)
 
           File.expand_path(path)
         end
 
-        # 读取并限制设备任务并发数。
         def concurrency
           count = integer("NET_CONNECTOR_CONCURRENCY", DEFAULT_CONCURRENCY)
           raise ArgumentError, "NET_CONNECTOR_CONCURRENCY must be at most #{MAX_CONCURRENCY}" if count > MAX_CONCURRENCY
@@ -61,121 +113,172 @@ module Net
           count
         end
 
-        # 确定厂商采样数量：本地默认全量，TFTP 默认每厂商五台。
         def limit_per_vendor(tftp: false)
-          return integer("NET_CONNECTOR_SAMPLE_PER_VENDOR", 5) if @env.key?("NET_CONNECTOR_SAMPLE_PER_VENDOR")
-
-          5 if tftp
+          count = if configured?("NET_CONNECTOR_SAMPLE_PER_VENDOR")
+                    integer("NET_CONNECTOR_SAMPLE_PER_VENDOR", 5) unless raw("NET_CONNECTOR_SAMPLE_PER_VENDOR").nil?
+                  elsif tftp
+                    5
+                  end
+          Planner.validate_limit!(count)
+          count
         end
 
-        # 读取厂商的 TFTP 源文件配置，并提供华为启动配置默认路径。
         def tftp_source_files
-          files = { huawei: @env.fetch("NET_CONNECTOR_HUAWEI_TFTP_SOURCE_FILE", "flash:/startup.cfg") }
+          files = { huawei: raw("NET_CONNECTOR_HUAWEI_TFTP_SOURCE_FILE", "flash:/startup.cfg") }
           %i[h3c h3c_wireless].each do |vendor|
             key = "NET_CONNECTOR_#{vendor.to_s.upcase}_TFTP_SOURCE_FILE"
-            files[vendor] = @env.fetch(key) if @env.key?(key)
+            files[vendor] = raw(key) if configured?(key)
           end
           files
         end
 
-        # 读取各厂商 TFTP 出口 VRF 的名称映射。
         def tftp_vrfs
-          raw = json("NET_CONNECTOR_TFTP_VRFS", {})
-          raise ArgumentError, "NET_CONNECTOR_TFTP_VRFS must be a JSON object" unless raw.is_a?(Hash)
+          mapping = json("NET_CONNECTOR_TFTP_VRFS", {})
+          raise ArgumentError, "NET_CONNECTOR_TFTP_VRFS must be a JSON object" unless mapping.is_a?(Hash)
 
-          raw.transform_keys(&:to_sym)
+          self.class.validate_vrfs!(mapping.transform_keys(&:to_sym))
+        end
+
+        def self.validate_vrfs!(vrfs)
+          unless vrfs.is_a?(Hash) && vrfs.all? { |vendor, name|
+            %i[cisco_nxos hillstone].include?(vendor) && name.is_a?(String) &&
+              name.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/)
+          }
+            raise ArgumentError, "vrfs must map supported vendor names to safe VRF names"
+          end
+          vrfs
         end
 
-        # 每台设备执行时读取凭据，使新批次可使用轮换后的环境变量。
-        # 按厂商优先级读取设备账号与密码。
-        def credentials_for(device)
+        def tftp_server = value("TFTP_HOST")
+
+        def connection_options(vendor = nil)
+          prefix = "NET_CONNECTOR_#{vendor.to_s.upcase}_"
+          configuration = Configuration.new(
+            protocol: (vendor && value(prefix + "PROTOCOL")) || value("NET_CONNECTOR_PROTOCOL") || "ssh",
+            log_level: value("NET_CONNECTOR_LOG_LEVEL") || "info", known_hosts: value("NET_CONNECTOR_KNOWN_HOSTS"),
+            host_key_policy: value("NET_CONNECTOR_HOST_KEY_POLICY") || "strict",
+            max_script_output_bytes: optional_integer("NET_CONNECTOR_MAX_SCRIPT_OUTPUT_BYTES")
+          )
+          options = %i[protocol log_level known_hosts host_key_policy].to_h { |key| [key, configuration.public_send(key)] }
+          options[:max_script_output_bytes] = configuration.max_script_output_bytes if configuration.max_script_output_bytes
+          options.freeze
+        end
+
+        def device_credentials_for(device)
           prefix = "NET_CONNECTOR_#{device.vendor.to_s.upcase}_"
-          username = value(prefix + "USERNAME") || value("NET_CONNECTOR_DEVICE_USERNAME")
+          username = secret_value(prefix + "USERNAME") || secret_value("NET_CONNECTOR_DEVICE_USERNAME")
           return nil unless username
 
-          {
-            username: username,
-            password: value(prefix + "PASSWORD") || value("NET_CONNECTOR_DEVICE_PASSWORD"),
-            enable_password: value(prefix + "ENABLE_PASSWORD") || value("NET_CONNECTOR_ENABLE_PASSWORD"),
-            protocol: (value(prefix + "PROTOCOL") || value("NET_CONNECTOR_PROTOCOL") || "ssh").to_sym,
-            log_level: (value("NET_CONNECTOR_LOG_LEVEL") || "info").to_sym,
-            known_hosts: value("NET_CONNECTOR_KNOWN_HOSTS"),
-            host_key_policy: (value("NET_CONNECTOR_HOST_KEY_POLICY") || "strict").to_sym
-          }
+          { username: username,
+            password: secret_value(prefix + "PASSWORD") || secret_value("NET_CONNECTOR_DEVICE_PASSWORD"),
+            enable_password: secret_value(prefix + "ENABLE_PASSWORD") || secret_value("NET_CONNECTOR_ENABLE_PASSWORD") }
         end
 
-        # 读取并展开设备日志目录。
         def log_directory
           path = value("NET_CONNECTOR_LOG_DIRECTORY")
           File.expand_path(path) if path
         end
 
-        # 仅展示非敏感配置，不输出设备凭据或 API 密钥。
-        # 生成不包含凭据的可展示配置。
         def public_config
-          rules
-          url = value("NETDISCO_URL")
-          if url
-            uri = URI.parse(url)
-            unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
-              raise ArgumentError, "NETDISCO_URL must be a base URL without credentials or query"
-            end
-          end
+          snapshot(mode: :show_config).send(:config_hash)
+        end
+
+        def inspect = "#<#{self.class}>"
+
+        private
+
+        def config_hash
           {
-            netdisco: { url: url, page_size: integer("NETDISCO_PAGE_SIZE", DEFAULT_PAGE_SIZE) },
-            backup: { directory: backup_directory, concurrency: concurrency,
-                      limit_per_vendor: limit_per_vendor },
+            netdisco: client_options,
+            backup: { directory: backup_directory, concurrency: concurrency, limit_per_vendor: limit_per_vendor },
             inventory: { include_hosts: list("NET_CONNECTOR_INCLUDE_HOSTS"),
                          exclude_hosts: list("NET_CONNECTOR_EXCLUDE_HOSTS"),
                          include_vendors: list("NET_CONNECTOR_INCLUDE_VENDORS"),
                          vendor_overrides: json("NET_CONNECTOR_VENDOR_OVERRIDES", {}),
                          host_overrides: json("NET_CONNECTOR_HOST_OVERRIDES", {}),
                          device_rules: json("NET_CONNECTOR_DEVICE_RULES", []) },
-            ssh: { protocol: value("NET_CONNECTOR_PROTOCOL") || "ssh",
-                   known_hosts: value("NET_CONNECTOR_KNOWN_HOSTS"),
-                   host_key_policy: value("NET_CONNECTOR_HOST_KEY_POLICY") || "strict",
-                   log_directory: log_directory,
-                   log_level: value("NET_CONNECTOR_LOG_LEVEL") || "info" },
-            tftp: { server: value("TFTP_HOST"), vrfs: tftp_vrfs.transform_keys(&:to_s) }
+            ssh: connection_options.transform_values { |item| item.is_a?(Symbol) ? item.to_s : item }.merge(
+              log_directory: log_directory,
+              vendor_protocols: Net::Connector.vendors.filter_map do |vendor|
+                protocol = value("NET_CONNECTOR_#{vendor.to_s.upcase}_PROTOCOL")
+                [vendor, protocol] if protocol
+              end.to_h
+            ),
+            tftp: { server: tftp_server, vrfs: tftp_vrfs.transform_keys(&:to_s), source_files: tftp_source_files }
           }
-        rescue URI::InvalidURIError
-          raise ArgumentError, "NETDISCO_URL is invalid"
         end
 
-        private
+        def non_secret_keys
+          keys = ConfigFile::FIELDS.values.flat_map { |section| section.values.map(&:first) }
+          keys + Net::Connector.vendors.map { |vendor| "NET_CONNECTOR_#{vendor.to_s.upcase}_PROTOCOL" }
+        end
+
+        def raw(key, default = nil)
+          return @policy.send(:raw, key, default) if @policy
+          return @overrides.fetch(key) if @overrides.key?(key)
+          return @env.fetch(key) if @env.key?(key)
+
+          @defaults.fetch(key, default)
+        end
+
+        def configured?(key) = !raw(key, UNSET).equal?(UNSET)
 
-        # 解析指定环境变量中的 JSON 配置。
         def json(key, default)
-          raw = value(key)
-          raw ? JSON.parse(raw) : default
+          text = value(key)
+          text ? JSON.parse(text) : default
         rescue JSON::ParserError
-          raise ArgumentError, "#{key} must be valid JSON"
+          raise ArgumentError, "#{key} must be valid JSON", cause: nil
         end
 
-        # 解析逗号分隔的环境变量列表。
-        def list(key) = @env.fetch(key, "").split(",").map(&:strip).reject(&:empty?)
+        def list(key) = (value(key) || "").split(",").map(&:strip).reject(&:empty?)
 
-        # 读取正整数配置并统一错误信息。
         def integer(key, default)
-          raw = @env.fetch(key, default)
-          value = Integer(raw.to_s, 10)
-          raise ArgumentError, "#{key} must be a positive integer" unless value.positive?
+          result = Integer(raw(key, default).to_s, 10)
+          raise ArgumentError unless result.positive?
 
-          value
+          result
         rescue ArgumentError, TypeError
-          raise ArgumentError, "#{key} must be a positive integer"
+          raise ArgumentError, "#{key} must be a positive integer", cause: nil
+        end
+
+        def optional_integer(key)
+          integer(key, nil) unless raw(key).nil?
+        end
+
+        def number(key, default)
+          input = raw(key, default)
+          result = input.is_a?(String) ? Float(input) : input
+          unless result.is_a?(Numeric) && result.real? && result.finite? && result.positive? && result.to_f.finite?
+            raise ArgumentError
+          end
+          result
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "#{key} must be a positive finite number", cause: nil
+        end
+
+        def boolean(key, default)
+          result = raw(key, default)
+          return true if result == true || result == "true"
+          return false if result == false || result == "false"
+
+          raise ArgumentError, "#{key} must be true or false"
         end
 
-        # 读取非空字符串配置。
         def value(key)
-          result = @env[key]
+          result = raw(key)
+          raise ArgumentError, "#{key} must be a String" unless result.nil? || result.is_a?(String)
+
           result if present?(result)
         end
 
-        # 读取必填环境变量。
-        def required(key) = value(key) || (raise ArgumentError, "#{key} is required")
+        def secret_value(key)
+          result = @env[key]
+          raise ArgumentError, "#{key} must be a String" unless result.nil? || result.is_a?(String)
+
+          result.dup.freeze if present?(result)
+        end
 
-        # 判断环境变量是否为非空字符串。
+        def required_secret(key) = secret_value(key) || (raise ArgumentError, "#{key} is required")
         def present?(value) = value.is_a?(String) && !value.strip.empty?
       end
     end

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

@@ -31,25 +31,10 @@ module Net
                 Thread.current.report_on_exception = false
                 while (task = queue.pop)
                   index, device = task
-                  started_at = Time.now.utc
-                  begin
-                    on_start&.call(device)
-                  rescue StandardError => error
-                    callback_errors << { host: device.host, error_type: error.class.name }.freeze
-                  end
-                  result = begin
-                             yield device
-                           rescue StandardError => error
-                             on_error.call(device, error)
-                           end
-                  result = result.with(started_at: started_at, finished_at: Time.now.utc)
+                  result = run_task(device, on_error, on_start, callback_errors) { yield device }
                   outcomes[index] = result
                   Array(on_result).each do |callback|
-                    begin
-                      callback.call(result)
-                    rescue StandardError => error
-                      callback_errors << { host: device.host, error_type: error.class.name }.freeze
-                    end
+                    notify(callback, result, host: device.host, errors: callback_errors)
                   end
                 end
               ensure
@@ -76,6 +61,30 @@ module Net
           end
           Array.new(callback_errors.size) { callback_errors.pop }.freeze
         end
+
+        private
+
+        # 普通设备故障转换为结果，中断仍交给批次统一停止其余线程。
+        def run_task(device, on_error, on_start, callback_errors)
+          started_at = Time.now.utc
+          started = monotonic
+          notify(on_start, device, host: device.host, errors: callback_errors) unless on_start.nil?
+          result = begin
+                     yield
+                   rescue StandardError => error
+                     on_error.call(device, error)
+                   end
+          result.with(started_at: started_at, finished_at: Time.now.utc, duration_ms: ((monotonic - started) * 1000).round)
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        # 回调故障不覆盖设备结果，也不把异常消息中的凭据写入报告。
+        def notify(callback, value, host:, errors:)
+          callback.call(value)
+        rescue StandardError => error
+          errors << { host: host, error_type: error.class.name }.freeze
+        end
       end
     end
   end

data/lib/net/connector/storage/backup_lock.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../engine/errors"
+
+module Net
+  module Connector
+    class BackupBusy < Error; end
+
+    module Storage
+      # 路径锁在设备采集之前取得；锁文件长期保留，避免等待者落在已经删除的 inode 上。
+      class BackupLock
+        STORAGE_KEY = :net_connector_backup_delegation
+        private_constant :STORAGE_KEY
+
+        attr_reader :path
+
+        def self.lock_path(path)
+          destination = File.expand_path(path)
+          directory = File.realpath(File.dirname(destination))
+          # 锁名先折叠 Unicode 与大小写，避免大小写不敏感文件系统上的别名绕过互斥。
+          # 在区分大小写的文件系统上可能保守地合并两个锁，但不会改写目标文件名。
+          filename = File.basename(destination).b.force_encoding(Encoding::UTF_8)
+          filename = filename.valid_encoding? ? filename.unicode_normalize(:nfc).downcase(:fold).unicode_normalize(:nfc) : filename.b.downcase
+          File.join(directory, ".net-connector-#{Digest::SHA256.hexdigest(filename)}.lock")
+        end
+
+        def self.synchronize(path, **options, &block) = new(path, **options).synchronize(&block)
+
+        def initialize(path, timeout: 0, host: nil)
+          raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?
+          unless timeout.is_a?(Numeric) && timeout.real? && timeout.finite? && timeout >= 0 && timeout.to_f.finite?
+            raise ArgumentError, "lock_timeout must be a nonnegative finite number"
+          end
+
+          @path = File.expand_path(path).freeze
+          @lock_path = self.class.lock_path(@path).freeze
+          @timeout, @host = timeout.to_f, host
+        end
+
+        def synchronize
+          # Fleet 只向下层备份借用一次；消费后清除，采集回调中的递归备份仍须竞争锁。
+          # Thread#[] 是 Fiber 局部存储；fork 后不能消费父进程的借用记录。
+          if Thread.current[STORAGE_KEY] == [@lock_path, Process.pid]
+            Thread.current[STORAGE_KEY] = nil
+            return yield self
+          end
+
+          file = nil
+          begin
+            file = open_lock
+            verify_lock!(file)
+            acquire(file)
+            verify_lock!(file)
+            @owner = [Process.pid, Fiber.current]
+            yield self
+          ensure
+            @owner = nil
+            file&.close
+          end
+        end
+
+        # 仅持有实际 flock 的同一 Fiber 可授权一次内层采集，避免把路径锁变成任意可重入锁。
+        def with_delegated_lock
+          raise ThreadError, "backup path delegation requires lock ownership" unless @owner == [Process.pid, Fiber.current]
+
+          previous = Thread.current[STORAGE_KEY]
+          begin
+            Thread.current[STORAGE_KEY] = [@lock_path, Process.pid]
+            yield
+          ensure
+            Thread.current[STORAGE_KEY] = previous
+          end
+        end
+
+        private
+
+        def open_lock
+          File.open(@lock_path, File::RDWR | File::CREAT | File::NOFOLLOW | File::NONBLOCK, 0o600)
+        rescue Errno::ELOOP, Errno::EISDIR, Errno::ENXIO
+          raise ArgumentError, "backup lock must be a private regular file", cause: nil
+        end
+
+        def verify_lock!(file)
+          stat = file.stat
+          unless stat.file? && stat.uid == Process.euid && stat.nlink == 1 && (stat.mode & 0o7777) == 0o600
+            raise ArgumentError, "backup lock must be an owned regular file with mode 0600 and one link"
+          end
+          current = File.lstat(@lock_path)
+          unless current.file? && current.dev == stat.dev && current.ino == stat.ino
+            raise ArgumentError, "backup lock path changed while acquiring ownership"
+          end
+        rescue Errno::ENOENT
+          raise ArgumentError, "backup lock path changed while acquiring ownership", cause: nil
+        end
+
+        def acquire(file)
+          deadline = monotonic + @timeout
+          loop do
+            acquired = file.flock(File::LOCK_EX | File::LOCK_NB)
+            return if acquired && (@timeout.zero? || monotonic < deadline)
+
+            remaining = deadline - monotonic
+            if remaining <= 0
+              raise BackupBusy.new("backup path already belongs to another operation", host: @host, phase: :backup), cause: nil
+            end
+            wait([remaining, 0.05].min)
+          end
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        def wait(seconds) = sleep(seconds)
+      end
+    end
+  end
+end