net-connector 0.5.0 → 0.7.0

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

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../storage/backup_lock"
+require_relative "../storage/private_file"
+require_relative "../storage/safe_file"
+require_relative "tftp_verification"
+
+module Net
+  module Connector
+    module Netdisco
+      # 设备先上传到服务器根目录，核验后按批次归档；固定文件名不会覆盖历史文件。
+      class TftpArchive
+        BATCH_DIRECTORY_NAME = /\A\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}(?:_\d{2})?\z/
+        private_constant :BATCH_DIRECTORY_NAME
+
+        class Unavailable < Net::Connector::Error
+          def initialize(host: nil)
+            super("a local TFTP root is required to retain a fixed-name upload", code: :tftp_history_unavailable,
+                  host: host, phase: :tftp_backup)
+          end
+        end
+
+        class ArchiveFailed < Net::Connector::Error
+          def initialize(host: nil)
+            super("the uploaded file could not be retained in the batch", code: :tftp_archive_failed,
+                  host: host, phase: :tftp_backup)
+          end
+        end
+
+        def initialize(directory:, root: nil)
+          @report_directory = File.expand_path(directory)
+          @server_root = root && File.realpath(root)
+          @server_archive_directory = create_server_archive_directory if @server_root
+          @remote_suffix = reserve_remote_suffix unless @server_root
+          @verifier = TftpVerification.new(root: @server_root)
+        end
+
+        def upload_filename(device)
+          name = device.tftp_filename
+          return name if @server_root || device.vendor == :palo_alto
+
+          extension = File.extname(name)
+          stem = File.basename(name, extension)
+          suffix = "-#{@remote_suffix}#{extension}"
+          TftpTarget.validate_path!("#{stem.byteslice(0, TftpTarget::MAX_PATH_BYTES - suffix.bytesize)}#{suffix}")
+        end
+
+        def upload_and_archive(device, started_at:)
+          raise Unavailable.new(host: device.host) if device.vendor == :palo_alto && !@server_root
+
+          remote_filename = upload_filename(device)
+          return yield remote_filename unless @server_root
+
+          # The lock spans the upload and copy, including a fixed-name PAN-OS upload.
+          Storage::BackupLock.synchronize(File.join(@server_root, remote_filename), host: device.host, timeout: 240) do
+            archive_existing_file(device, remote_filename)
+            outcome = yield remote_filename
+            receipt = outcome.backup
+            return outcome unless receipt.is_a?(TftpReceipt) && receipt.path
+
+            verified = @verifier.verify_outcome(outcome.with(started_at: started_at))
+            return outcome.success? ? archive_failure(outcome) : outcome unless verified.backup.verification == :server_verified
+
+            archive_uploaded_file(verified)
+          end
+        end
+
+        alias path_for upload_filename
+        alias capture upload_and_archive
+
+        private
+
+        # 首次采用固定远端名时，先保留服务器上原有文件，再允许设备覆盖。
+        def archive_existing_file(device, remote_filename)
+          existing_path = File.join(@server_root, remote_filename)
+          bytes = Storage::SafeFile.open(existing_path, missing: true) { |file, _stat| file.read }
+          return unless bytes
+
+          previous_directory = File.join(@server_archive_directory, "previous")
+          FileUtils.mkdir_p(previous_directory, mode: 0o700)
+          archive_path = File.join(previous_directory, archive_filename(device, File.extname(remote_filename)))
+          Storage::PrivateFile.write(archive_path, bytes)
+        rescue StandardError
+          raise ArchiveFailed.new(host: device.host), cause: nil
+        end
+
+        def create_server_archive_directory
+          parent = File.join(@server_root, "archive")
+          raise ArgumentError, "TFTP archive directory must not be a symlink" if File.symlink?(parent)
+
+          FileUtils.mkdir_p(parent, mode: 0o700)
+          raise ArgumentError, "TFTP archive directory escaped its root" unless File.realpath(parent) == parent
+
+          base = batch_name
+          number = 0
+          loop do
+            candidate = number.zero? ? base : "#{base}_#{format("%02d", number)}"
+            path = File.join(parent, candidate)
+            begin
+              Dir.mkdir(path, 0o700)
+              return path
+            rescue Errno::EEXIST
+              number += 1
+            end
+          end
+        end
+
+        # 同一目录重跑时用原子预留的序号区分运行，不依赖随机数或进程 ID。
+        def reserve_remote_suffix
+          base = batch_name
+          number = 0
+          loop do
+            candidate = number.zero? ? base : "#{base}_#{format("%02d", number)}"
+            marker = File.join(@report_directory, ".tftp-run-#{candidate}")
+            begin
+              File.open(marker, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.write("\n") }
+              return candidate
+            rescue Errno::EEXIST
+              number += 1
+            end
+          end
+        end
+
+        def batch_name
+          name = File.basename(@report_directory)
+          name.match?(BATCH_DIRECTORY_NAME) ? name : Time.now.getlocal("+08:00").strftime("%Y-%m-%d_%H-%M-%S")
+        end
+
+        def archive_uploaded_file(outcome)
+          receipt = outcome.backup
+          saved_batch_path = nil
+          batch_directory = File.join(@report_directory, "tftp")
+          FileUtils.mkdir_p(batch_directory, mode: 0o700)
+          extension = File.extname(receipt.path)
+          filename = archive_filename(outcome.device, extension)
+          batch_archive_path = File.join(batch_directory, filename)
+          server_archive_path = File.join(@server_archive_directory, filename)
+          uploaded_path = receipt.local_path
+          bytes = Storage::SafeFile.open(uploaded_path) do |file, stat|
+            raise ArchiveFailed.new(host: outcome.device.host) unless stat.size == receipt.server_bytes
+
+            file.read
+          end
+          raise ArchiveFailed.new(host: outcome.device.host) unless Digest::SHA256.hexdigest(bytes) == receipt.server_sha256
+
+          Storage::PrivateFile.write(batch_archive_path, bytes)
+          saved_batch_path = batch_archive_path
+          Storage::PrivateFile.write(server_archive_path, bytes)
+          if outcome.success?
+            uploaded_fingerprint = Storage::SafeFile.fingerprint(uploaded_path)
+            raise ArchiveFailed.new(host: outcome.device.host) unless uploaded_fingerprint.sha256 == receipt.server_sha256
+            raise ArchiveFailed.new(host: outcome.device.host) unless Storage::SafeFile.same_entry?(uploaded_path, uploaded_fingerprint)
+
+            File.unlink(uploaded_path)
+          end
+          outcome.with(backup: receipt.with(local_path: batch_archive_path, archive_path: server_archive_path))
+        rescue StandardError
+          retained = outcome.with(backup: receipt.with(local_path: saved_batch_path))
+          outcome.success? ? archive_failure(retained) : retained
+        end
+
+        def archive_failure(outcome)
+          error = ArchiveFailed.new(host: outcome.device.host)
+          outcome.with(status: :reported_with_error, error_code: error.code, error_type: error.class.name,
+                       diagnostic: Diagnostic.from(error, backup: outcome.backup))
+        end
+
+        def archive_filename(device, extension)
+          "#{device.backup_filename(style: :hostname_ip).delete_suffix(".txt")}#{extension}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "tftp_archive"
+
+module Net
+  module Connector
+    module Netdisco
+      # Compatibility with the first batch archive entry point.
+      class TftpHistory < TftpArchive
+        def initialize(server:, **options) # rubocop:disable Lint/UnusedMethodArgument -- Accept the former constructor keyword.
+          super(**options)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../storage/safe_file"
+
+module Net
+  module Connector
+    module Netdisco
+      # 只核验本次设备回执指向的本地服务器文件；远端可读不等于本次上传证据。
+      class TftpVerification
+        def initialize(root: nil)
+          @root = root && File.realpath(root)
+        end
+
+        def call(report)
+          return report unless @root
+
+          outcomes = report.outcomes.map do |outcome|
+            receipt = outcome.backup
+            next outcome unless receipt.is_a?(TftpReceipt) && receipt.path && outcome.started_at
+
+            verify(outcome, receipt)
+          end
+          report.with(outcomes: outcomes.freeze)
+        end
+
+        def verify_outcome(outcome)
+          return outcome unless @root && outcome.started_at && outcome.backup.is_a?(TftpReceipt) && outcome.backup.path
+
+          verify(outcome, outcome.backup)
+        end
+
+        private
+
+        def verify(outcome, receipt)
+          path = File.join(@root, receipt.path)
+          parent = File.realpath(File.dirname(path))
+          return outcome unless parent == @root || parent.start_with?(@root + File::SEPARATOR)
+
+          size = nil
+          fingerprint = Storage::SafeFile.open(path, missing: true) do |file, stat|
+            next unless stat.size.positive? && stat.mtime >= outcome.started_at
+
+            size = stat.size
+            value = Storage::SafeFile.fingerprint_io(path, file, stat)
+            after = file.stat
+            value if [stat.size, stat.mtime, stat.ctime] == [after.size, after.mtime, after.ctime]
+          end
+          return outcome unless fingerprint && Storage::SafeFile.same_entry?(path, fingerprint)
+
+          outcome.with(backup: receipt.with(verification: :server_verified, server_sha256: fingerprint.sha256, server_bytes: size, local_path: path))
+        rescue IOError, SystemCallError, ArgumentError
+          # 核验失败不抹去设备上传回执；要求服务器证据的策略仍判为未完成。
+          outcome
+        end
+      end
+    end
+  end
+end

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

@@ -5,13 +5,18 @@ module Net
     module Netdisco
       # 以固定并发上限执行相互隔离的设备任务。
       class Worker
-        # 校验并保存最大设备并发数。
-        def initialize(concurrency:)
+        # 内部预检与实际执行共用规则，不为校验创建工作线程池对象。
+        def self.validate_concurrency!(concurrency)
           unless concurrency.is_a?(Integer) && (1..Settings::MAX_CONCURRENCY).cover?(concurrency)
             raise ArgumentError, "concurrency must be an Integer in 1..#{Settings::MAX_CONCURRENCY}"
           end
 
-          @concurrency = concurrency
+          concurrency
+        end
+
+        # 校验并保存最大设备并发数。
+        def initialize(concurrency:)
+          @concurrency = Worker.validate_concurrency!(concurrency)
         end
 
         # 按清单顺序收集结果，并隔离设备及回调异常。

data/lib/net/connector/netdisco.rb

@@ -2,6 +2,7 @@
 
 require_relative "../connector"
 require_relative "netdisco/client"
+require_relative "netdisco/database_client"
 require_relative "netdisco/rules"
 require_relative "netdisco/device"
 require_relative "netdisco/config_file"
@@ -11,4 +12,14 @@ require_relative "netdisco/result_store"
 require_relative "netdisco/batch"
 require_relative "netdisco/planner"
 require_relative "netdisco/fleet"
+require_relative "netdisco/progress"
 require_relative "netdisco/cli"
+require_relative "storage/batch_directory"
+require_relative "netdisco/report/text"
+require_relative "netdisco/connection"
+require_relative "netdisco/cli/options"
+require_relative "netdisco/report/files"
+require_relative "netdisco/tftp_verification"
+require_relative "netdisco/tftp_archive"
+require_relative "netdisco/tftp_history"
+require_relative "netdisco/backup_run"

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

@@ -25,7 +25,7 @@ module Net
           File.join(directory, ".net-connector-#{Digest::SHA256.hexdigest(filename)}.lock")
         end
 
-        def self.synchronize(path, **options, &block) = new(path, **options).synchronize(&block)
+        def self.synchronize(path, **options, &) = new(path, **options).synchronize(&)
 
         def initialize(path, timeout: 0, host: nil)
           raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Net
+  module Connector
+    module Storage
+      # 使用本地业务时区命名，原子创建互不覆盖的批次目录。
+      class BatchDirectory
+        # 固定 UTC+8，不依赖运行主机时区；mkdir 原子防止并发任务覆盖。
+        def self.create(root, time: Time.now)
+          FileUtils.mkdir_p(root, mode: 0o700)
+          stamp = time.getlocal("+08:00").strftime("%Y-%m-%d_%H-%M-%S")
+          suffix = 0
+          loop do
+            name = suffix.zero? ? stamp : "#{stamp}_#{format("%02d", suffix)}"
+            path = File.join(root, name)
+            begin
+              Dir.mkdir(path, 0o700)
+              return path
+            rescue Errno::EEXIST
+              suffix += 1
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/storage.rb

@@ -4,6 +4,7 @@ module Net
   module Connector
     # 文件存储不依赖设备连接；备份、离线导出和批量报告共享这些原语。
     module Storage
+      autoload :BatchDirectory, File.expand_path("storage/batch_directory", __dir__)
       autoload :BackupLock, File.expand_path("storage/backup_lock", __dir__)
       autoload :PrivateFile, File.expand_path("storage/private_file", __dir__)
       autoload :SafeFile, File.expand_path("storage/safe_file", __dir__)

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

@@ -38,7 +38,8 @@ module Net
             )
           end
 
-          command_timeout 10
+          # 核心交换机配置采集实测超过 10 秒，保留有界的整条命令预算。
+          command_timeout 60
 
           interactions do
             confirm %r{Are\s+you\s+sure\?\s*\[Y/N\]}i, response: "y\n"

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

@@ -12,9 +12,9 @@ module Net
         # 在连接前拒绝源文件及远端目录；未指定文件名时仍由设备生成。
         def validate_options!(target, source_file:, **)
           raise ArgumentError, "Hillstone TFTP export does not use source_file" unless source_file.nil?
-          if target.explicit_path? && target.path.include?("/")
-            raise ArgumentError, "Hillstone TFTP filename cannot contain a directory"
-          end
+          return unless target.explicit_path? && target.path.include?("/")
+
+          raise ArgumentError, "Hillstone TFTP filename cannot contain a directory"
         end
 
         def receipt_metadata(target, **)

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

@@ -15,9 +15,9 @@ module Net
         def validate_options!(target, source_file:, vrf: nil)
           raise ArgumentError, "PAN-OS does not use source_file" unless source_file.nil?
           raise ArgumentError, "PAN-OS TFTP backup does not use vrf" unless vrf.nil?
-          if target.explicit_path? && target.path != FILENAME
-            raise ArgumentError, "PAN-OS TFTP export uses the fixed filename #{FILENAME}"
-          end
+          return unless target.explicit_path? && target.path != FILENAME
+
+          raise ArgumentError, "PAN-OS TFTP export uses the fixed filename #{FILENAME}"
         end
 
         def receipt_metadata(_target, **)

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../../device/running_config/strategy"
+
+module Net
+  module Connector
+    module Radware
+      class RunningConfig < Net::Connector::RunningConfig::Rendered
+        # /cfg/dump 进入 Configuration 菜单；保留设备前缀，只替换菜单名称。
+        def prompt_text(command)
+          prompt = super
+          return prompt unless command.text == "/cfg/dump"
+
+          prompt.sub(/\A(>>[ \t]+(?:.* - )?)[^\r\n#]+#\z/, '\1Configuration#')
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../device/base"
+require_relative "radware/running_config"
 require_relative "radware/tftp_backup"
 require_relative "radware/topology"
 
@@ -12,7 +13,7 @@ module Net
         vendor :radware
         # 声明菜单式 CLI 的命令、提示、超时、诊断和确认规则。
         profile do
-          running_config_strategy Net::Connector::RunningConfig::Rendered
+          running_config_strategy Net::Connector::Radware::RunningConfig
           tftp_strategy Net::Connector::Radware::TftpBackup
           topology_strategy Net::Connector::Radware::Topology
           commands do
@@ -21,8 +22,8 @@ module Net
           end
 
           prompts do
-            login(/(?:\A|(?<=[\r\n]))(?:>>[^\r\n]*|[^\r\n]+[>#])\s*\z/)
-            command(/(?:\A|(?<=[\r\n]))(?:>>[^\r\n]*|[^\r\n]+#)\s*\z/)
+            login(/(?:\A|(?<=[\r\n]))(?:>>[^\r\n]*#|(?!>>)[^\r\n]+[>#])\s*\z/)
+            command(/(?:\A|(?<=[\r\n]))[^\r\n]+#\s*\z/)
           end
 
           errors do

data/lib/net/connector/version.rb

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

data/lib/net/connector.rb

@@ -34,10 +34,10 @@ module Net
     end
 
     # 在代码块内连接设备并确保会话关闭。
-    def self.open(vendor, **settings)
+    def self.open(vendor, **settings, &)
       raise ArgumentError, "open requires a block" unless block_given?
 
-      vendor_class(vendor).open(**settings) { |device| yield device }
+      vendor_class(vendor).open(**settings, &)
     end
   end
 end