net-connector 0.4.1 → 0.5.0

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "interface_name"
+
+module Net
+  module Connector
+    class Topology
+      # 描述文本与常见接口视图命令的纯构造方法，不连接或修改设备。
+      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
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Topology
+      # 接口身份匹配与描述展示共用名称规则；展示简称不能直接用作下发命令。
+      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
+end

data/lib/net/connector/device/topology/strategy.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "interface_description"
+
+module Net
+  module Connector
+    class Topology
+      # 厂商拓扑规则；默认不提供任何设备能力。
+      class Strategy
+        # 保存设备供厂商规则查询档案和会话状态。
+        def initialize(device)
+          @device = device
+        end
+
+        # 声明策略类支持的拓扑能力，默认全部关闭。
+        def self.supports?(_capability) = false
+
+        # 将实例级能力查询交给策略类声明。
+        def supports?(capability) = self.class.supports?(capability)
+
+        # 返回读取邻居的命令，未定义时不支持发现。
+        def neighbor_command = nil
+
+        # 根据原始输出选择邻居解析模板。
+        def neighbor_template(_output) = nil
+
+        # 返回当前接口描述所用的解析模板。
+        def description_template = nil
+
+        # 返回输出中应解析出的邻居数量，供完整性校验使用。
+        def expected_neighbor_count(_output, _template) = 0
+
+        # 只有明确的空表证据才允许返回空邻居列表。
+        def empty_neighbor_output?(_output) = false
+
+        # 返回进入设备配置视图的命令。
+        def enter_configuration_command = nil
+
+        # 只读策略不提供变更阶段；可写策略必须分别声明退出、验证和保存命令。
+        def leave_configuration_commands = nil
+        def verification_commands = nil
+        def persistence_commands = nil
+        def persistence_confirmed?(_result) = false
+        def change_error_code = :description_unsupported
+
+        # 只读策略可以没有完整性扩展；立即生效的接口块模型会进一步校验解析数量。
+        def validate_descriptions!(_config, _rows) end
+
+        # 为一条接口描述变更生成厂商命令。
+        def change_commands(_change) = []
+
+        # 标明邻居发现使用的协议。
+        def protocol = :lldp
+
+        # 在下发前允许厂商调整命令对象及超时。
+        def script_command(command) = command
+
+        # 将发现接口名归一为查找当前配置所用的键。
+        def interface_key(name) = InterfaceName.key(name)
+
+        # 将发现协议常用的接口简称展开为配置视图可识别的名称。
+        def configuration_interface(name) = InterfaceName.configuration(name)
+
+        # 还原 PAN-OS set 配置或 Alteon dump 中的引号描述。
+        def decode_description(value)
+          value = value.strip
+          value.start_with?('"') ? Shellwords.split(value).join(" ") : value
+        rescue ArgumentError
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require_relative "topology/strategy"
+
+module Net
+  module Connector
+    # 从 CDP/LLDP 回显生成链路邻居，并规划接口描述变更。
+    class Topology
+      # 设备入口与功能实现共置，Base 只组合能力，不重复业务流程。
+      module Capability
+        # 执行 CDP 或 LLDP 查询并返回统一的链路邻居记录。
+        def neighbors = Topology.new(self).neighbors
+
+        # 读取运行配置中的接口描述或端口名称。
+        def interface_descriptions = Topology.new(self).interface_descriptions
+
+        # 以邻居和现有配置为证据，生成待确认的接口描述变更计划。
+        def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+          Topology.new(self).plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+        end
+
+        # 明确确认且现场证据未变化时执行接口描述计划。
+        def apply_interface_descriptions(plan, confirmed: false)
+          Topology.new(self).apply_interface_descriptions(plan, confirmed: confirmed)
+        end
+      end
+
+      Neighbor = Data.define(:local_interface, :neighbor_name, :neighbor_interface, :chassis_id, :protocol)
+      Change = Data.define(:interface, :old_description, :new_description, :neighbor)
+      Plan = Data.define(:host, :vendor, :evidence, :changes, :commands)
+
+      # 保存设备及其独立的 TextFSM 解析入口。
+      def initialize(device, template_dir: nil)
+        require_relative "../textfsm"
+
+        @device = device
+        @parser = TextFSM.new(template_dir: template_dir)
+        @strategy = (device.profile.topology_strategy || Strategy).new(device)
+      end
+
+      # 执行厂商 CDP/LLDP 命令，返回统一的邻居记录。
+      def neighbors
+        command = @strategy.neighbor_command
+        unless @strategy.supports?(:neighbors) && command
+          raise UnsupportedOperation.new("this device cannot discover LLDP neighbors",
+                                         code: :neighbor_discovery_unsupported, host: @device.host, phase: :discover)
+        end
+
+        output = TerminalText.utf8(@device.execute_command(command).value!, host: @device.host)
+        template = @strategy.neighbor_template(output)
+        rows = @parser.call(output, template: template, vendor: @device.vendor, command: command, host: @device.host)
+        if rows.size != @strategy.expected_neighbor_count(output, template) || (rows.empty? && !@strategy.empty_neighbor_output?(output))
+          raise ParsingError.new("neighbor output was not recognized", code: :unrecognized_output,
+                                 host: @device.host, phase: :discover)
+        end
+
+        rows.map do |row|
+          Neighbor.new(local_interface: row.fetch("LOCAL_INTERFACE").strip.freeze,
+                       neighbor_name: row.fetch("NEIGHBOR_NAME", "").strip.freeze,
+                       neighbor_interface: row.fetch("NEIGHBOR_INTERFACE").strip.freeze,
+                       chassis_id: row.fetch("CHASSIS_ID", "").strip.freeze,
+                       protocol: @strategy.protocol).freeze
+        end
+      end
+
+      # 从运行配置读取已设置的接口描述或端口名称。
+      def interface_descriptions = read_interface_descriptions
+
+      # 内部读取先交付执行步骤，再处理解析；解析失败也不能抹去已经完成的采集命令。
+      def read_interface_descriptions
+        template = @strategy.description_template
+        unless @strategy.supports?(:interface_descriptions) && template
+          raise UnsupportedOperation.new("interface descriptions are unsupported for this vendor",
+                                         code: :description_unsupported, host: @device.host, phase: :discover)
+        end
+        result = @device.running_config
+        yield result if block_given?
+        config = result.value!
+        rows = @parser.call(config, template: template, host: @device.host)
+        @strategy.validate_descriptions!(config, rows)
+        rows.each_with_object({}) do |row, found|
+          interface = @strategy.interface_key(row.fetch("INTERFACE"))
+          description = @strategy.decode_description(row.fetch("DESCRIPTION", ""))
+          previous = found[interface]
+          if previous && !previous.empty? && !description.empty? && previous != description
+            raise ParsingError.new("interface has conflicting descriptions", code: :ambiguous_description,
+                                   host: @device.host, phase: :parse)
+          end
+          found[interface] = description unless description.empty? && previous
+        end
+      end
+
+      private :read_interface_descriptions
+
+      # 比对邻居和现有描述，生成包含确切命令的只读变更计划。
+      def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+        validate_change_support!(:plan) if @strategy.supports?(:neighbors)
+        discovered = neighbors
+        current = interface_descriptions
+        current.each_value(&:freeze)
+        evidence = evidence_for(discovered, current)
+        changes = discovered.filter_map do |neighbor|
+          old = current.fetch(@strategy.interface_key(neighbor.local_interface))
+          proposed = if formatter
+                       formatter.call(neighbor)
+                     else
+                       InterfaceDescription.format(neighbor, abbreviate: abbreviate, lowercase: lowercase)
+                     end
+          InterfaceDescription.validate!(proposed)
+          next if old == proposed
+
+          Change.new(interface: @strategy.configuration_interface(neighbor.local_interface).freeze, old_description: old.freeze,
+                     new_description: proposed.freeze, neighbor: neighbor).freeze
+        end.freeze
+        commands = if changes.empty?
+                     []
+                   else
+                     stage_scripts(changes).values.flat_map { |script| script.map(&:text) }
+                   end
+        commands.each(&:freeze)
+        Plan.new(host: @device.host.dup.freeze, vendor: @device.vendor, evidence: evidence,
+                 changes: changes, commands: commands.freeze).freeze
+      end
+
+      # 只有明确确认且邻居和旧描述未变化时，才下发计划中的命令。
+      def apply_interface_descriptions(plan, confirmed: false)
+        unless confirmed == true
+          raise UnsupportedOperation.new("description plan requires confirmation", code: :confirmation_required,
+                                         host: @device.host, phase: :apply)
+        end
+        raise ArgumentError, "plan must be a topology plan for this device" unless plan.is_a?(Plan) &&
+                                                                                   plan.host == @device.host &&
+                                                                                   plan.vendor == @device.vendor
+        if plan.changes.empty?
+          raise ArgumentError, "empty topology plan cannot contain commands" unless plan.commands.empty?
+
+          return Result.new
+        end
+
+        @strategy.supports?(:neighbors) ? validate_change_support!(:apply) : neighbors
+        @device.with_operation(:apply) { apply_plan(plan) }
+      end
+
+      private
+
+      # 同一租约覆盖重验、修改、读回与保存；有完成步骤后发生的错误必须带回这些步骤。
+      def apply_plan(plan)
+        stages = stage_scripts(plan.changes)
+        unless stages.values.flat_map { |script| script.map(&:text) } == plan.commands
+          raise ArgumentError, "plan commands were modified or use an older execution sequence; regenerate the plan"
+        end
+        revalidate_plan!(plan)
+        steps = []
+        result = execute_stage(stages.fetch(:change), steps)
+        return Result.new(steps: steps, error: result.error) if result.failure?
+
+        verify_descriptions!(plan.changes, stages.fetch(:verify), steps)
+        persisting = true
+        result = execute_stage(stages.fetch(:persist), steps)
+        if result.failure? || !@strategy.persistence_confirmed?(result)
+          return Result.new(steps: steps, error: build_persistence_error(result.error))
+        end
+        Result.new(steps: steps)
+      rescue Error => error
+        raise unless steps
+
+        Result.new(steps: steps, error: persisting ? build_persistence_error(error) : error)
+      end
+
+      # 读回命令与审批一致，并且每个目标描述均得到确认，才允许进入保存阶段。
+      def verify_descriptions!(changes, script, steps)
+        unless Script.new(@device.config_commands).map(&:text) == script.map(&:text)
+          raise DeviceError.new("configuration readback commands changed after approval",
+                                code: :verification_plan_changed, host: @device.host, phase: :verify)
+        end
+        updated = read_interface_descriptions do |readback|
+          steps.concat(readback.steps)
+          if readback.success? && readback.steps.map { |step| step.command.text } != script.map(&:text)
+            raise DeviceError.new("configuration readback did not execute the approved commands",
+                                  code: :verification_plan_changed, host: @device.host, phase: :verify)
+          end
+        end
+        unless changes.all? { |change| updated[@strategy.interface_key(change.interface)] == change.new_description }
+          raise DeviceError.new("interface descriptions were not confirmed by readback",
+                                code: :description_unconfirmed, host: @device.host, phase: :verify)
+        end
+      end
+
+      # 重验失败仍在写入前直接抛异常，保持 stale_plan 的既有契约。
+      def revalidate_plan!(plan)
+        discovered = neighbors
+        evidence = evidence_for(discovered, interface_descriptions)
+        current_neighbors = discovered.to_h { |neighbor| [@strategy.interface_key(neighbor.local_interface), neighbor] }
+        same_neighbors = plan.changes.all? do |change|
+          current_neighbors[@strategy.interface_key(change.interface)] == change.neighbor
+        end
+        unless evidence == plan.evidence && same_neighbors
+          raise DeviceError.new("neighbors or interface descriptions changed after planning",
+                                code: :stale_plan, host: @device.host, phase: :apply)
+        end
+
+        plan.changes.each do |change|
+          InterfaceDescription.validate!(change.new_description)
+          unless evidence.fetch(@strategy.interface_key(change.interface)) ==
+                 [change.neighbor.neighbor_name, change.neighbor.neighbor_interface, change.old_description]
+            raise ArgumentError, "plan changes do not match its discovery evidence"
+          end
+        end
+      end
+
+      # 审批列表保留真正执行的读回命令，使旧版“先保存后读回”计划无法静默复用。
+      def stage_scripts(changes)
+        phases = %i[leave_configuration_commands verification_commands persistence_commands].map do |method|
+          @strategy.public_send(method)
+        end
+        unless phases.all? { |commands| commands.is_a?(Array) && !commands.empty? }
+          raise UnsupportedOperation.new("topology strategy must declare separate readback and persistence stages",
+                                         code: :description_stages_unsupported, host: @device.host, phase: :plan)
+        end
+        leave, verify, persist = phases
+        sequences = {
+          change: [@strategy.enter_configuration_command] + changes.flat_map { |change| change_commands(change) } + leave,
+          verify: verify, persist: persist
+        }
+        sequences.transform_values do |commands|
+          Script.new(commands.map { |command| @strategy.script_command(command) }, name: "interface descriptions")
+        end
+      end
+
+      def execute_stage(script, steps)
+        result = @device.execute_script(script)
+        steps.concat(result.steps)
+        result
+      end
+
+      # 保存可能已执行，超时、失败或缺少完成行均不自动重放；诊断不附带回显正文。
+      def build_persistence_error(error = nil)
+        underlying = UnderlyingError.new(error, nil, sensitive: true) if error
+        DeviceError.new("interface descriptions were verified; persistence was not confirmed",
+                        code: :persistence_unconfirmed, host: @device.host, phase: :persist, underlying: underlying)
+      end
+
+      # 下发描述前确认厂商提供配置能力，避免把只读发现当成可写能力。
+      def validate_change_support!(phase)
+        return if @strategy.supports?(:interface_description_changes)
+
+        raise UnsupportedOperation.new("automatic interface description changes are unavailable; use a verified manual workflow",
+                                       code: @strategy.change_error_code, host: @device.host, phase: phase)
+      end
+
+      # 汇总邻居身份和当前描述，并要求每个目标接口都有配置证据。
+      def evidence_for(discovered, current)
+        interfaces = discovered.group_by { |neighbor| @strategy.interface_key(neighbor.local_interface) }
+        if interfaces.any? { |_interface, peers| peers.size != 1 || peers.first.neighbor_name.empty? ||
+          peers.first.neighbor_interface.empty? }
+          raise ParsingError.new("neighbor identity is incomplete or ambiguous", code: :ambiguous_neighbor,
+                                 host: @device.host, phase: :plan)
+        end
+        unless interfaces.keys.all? { |interface| current.key?(interface) }
+          raise ParsingError.new("neighbor interface was not found in running configuration",
+                                 code: :interface_missing, host: @device.host, phase: :plan)
+        end
+
+        interfaces.transform_values do |peers|
+          peer = peers.fetch(0)
+          [peer.neighbor_name, peer.neighbor_interface, current.fetch(@strategy.interface_key(peer.local_interface))].freeze
+        end.freeze
+      end
+
+      # 设备标识来自解析证据，仍需在生成命令前验证其安全性。
+      def change_commands(change)
+        InterfaceDescription.validate_interface!(change.interface)
+        @strategy.change_commands(change)
+      end
+    end
+  end
+end

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

@@ -61,7 +61,7 @@ module Net
       def login_interactions
         host_key = Interaction.new(SSH_CONFIRMATION, lambda { |_prompt|
           if @config.host_key_policy == :strict
-            raise @session.error(ConnectionError, "host key confirmation rejected",
+            raise @session.build_error(ConnectionError, "host key confirmation rejected",
                                  phase: :login, code: :host_key_untrusted), cause: nil
           end
           "yes\n"

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

@@ -11,7 +11,8 @@ module Net
       attr_reader :text, :timeout, :interactions, :prompt, :source, :line
 
       # 在任何输入输出前校验命令、提示、交互和敏感标记，并冻结命令。
-      def initialize(text, timeout: nil, interactions: [], prompt: nil, sensitive: false, source: nil, line: nil)
+      def initialize(text, timeout: nil, interactions: [], prompt: nil, sensitive: false, output_sensitive: false,
+                     source: nil, line: nil)
         unless text.is_a?(String) && !text.strip.empty? && !text.match?(/[\r\n\x00]/)
           raise ScriptError.new("a command must contain exactly one nonempty CLI line", phase: :parse,
                                 source: source, line: line)
@@ -24,12 +25,14 @@ module Net
           raise ArgumentError, "prompt must be a nonempty Regexp or nil"
         end
         raise ArgumentError, "sensitive must be true or false" unless [true, false].include?(sensitive)
+        raise ArgumentError, "output_sensitive must be true or false" unless [true, false].include?(output_sensitive)
 
         @text = text.dup.freeze
         @timeout = Expect.duration(timeout)
         @interactions = interactions.dup.freeze
         @prompt = prompt
         @sensitive = sensitive
+        @output_sensitive = output_sensitive
         @source = source&.dup&.freeze
         @line = line
         freeze
@@ -38,10 +41,19 @@ module Net
       # 判断命令文本是否需要脱敏。
       def sensitive? = @sensitive
 
+      # 响应正文可能包含尚未登记的秘密，与命令文本是否敏感无关。
+      def output_sensitive? = @output_sensitive
+
       # 复制命令元数据，只替换命令文本。
       def with_text(text)
         self.class.new(text, timeout: timeout, interactions: interactions, prompt: prompt,
-                       sensitive: sensitive?, source: source, line: line)
+                       sensitive: sensitive?, output_sensitive: output_sensitive?, source: source, line: line)
+      end
+
+      # 配置采集保留调用方的全部命令元数据，只收紧输出的诊断边界。
+      def with_output_sensitive
+        self.class.new(text, timeout: timeout, interactions: interactions, prompt: prompt,
+                       sensitive: sensitive?, output_sensitive: true, source: source, line: line)
       end
 
       # 返回命令来源摘要，不展开命令内容。

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

@@ -8,13 +8,13 @@ module Net
     # 显式且不可变的连接设置；环境变量读取由调用库的可执行程序负责。
     class Configuration
       attr_reader :host, :username, :password, :enable_password, :protocol, :port, :login_timeout,
-                  :command_timeout, :write_timeout, :max_output_bytes, :log_file, :log_format, :log_level,
+                  :command_timeout, :write_timeout, :max_output_bytes, :max_script_output_bytes, :log_file, :log_format, :log_level,
                   :known_hosts, :host_key_policy, :challenges, :logger
 
       # 校验端点、凭据、超时、日志、主机密钥和挑战配置，然后冻结设置。
       def initialize(host: nil, username: nil, password: nil, enable_password: nil, protocol: :ssh, port: nil,
                      login_timeout: 10, command_timeout: nil, write_timeout: 10,
-                     max_output_bytes: 32 * 1024 * 1024, log_file: nil, logger: nil,
+                     max_output_bytes: 32 * 1024 * 1024, max_script_output_bytes: nil, log_file: nil, logger: nil,
                      log_format: :text, log_level: :info,
                      known_hosts: nil, host_key_policy: :strict, telnet_fallback: false, legacy_ssh: false,
                      challenges: [])
@@ -32,15 +32,12 @@ module Net
         @login_timeout = timeout_seconds(login_timeout, :login_timeout)
         @command_timeout = command_timeout.nil? ? nil : timeout_seconds(command_timeout, :command_timeout)
         @write_timeout = timeout_seconds(write_timeout, :write_timeout)
-        unless max_output_bytes.is_a?(Integer) && max_output_bytes.positive?
-          raise ArgumentError, "max_output_bytes must be a positive Integer"
-        end
-
-        @max_output_bytes = max_output_bytes
+        @max_output_bytes = positive_integer(max_output_bytes, :max_output_bytes)
+        @max_script_output_bytes = positive_integer(max_script_output_bytes, :max_script_output_bytes) unless max_script_output_bytes.nil?
         @log_file = absolute_path(log_file)
         if logger && (!logger.respond_to?(:debug) || !logger.respond_to?(:info) ||
           !logger.respond_to?(:warn) || !logger.respond_to?(:error) ||
-          !logger.respond_to?(:formatter) || !logger.respond_to?(:level))
+          !logger.respond_to?(:level))
           raise ArgumentError, "logger must be Logger-compatible"
         end
         raise ArgumentError, "logger and log_file cannot be combined" if logger && @log_file
@@ -86,6 +83,12 @@ module Net
 
       private
 
+      def positive_integer(value, name)
+        raise ArgumentError, "#{name} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+
+        value
+      end
+
       # 将可选值校验为字符串副本。
       def frozen_string(value)
         return nil if value.nil?