net-connector 0.4.0 → 0.4.2

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

@@ -1,24 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "plan"
+
 module Net
   module Connector
     module Netdisco
-      # 固定一份清单上的选择结果与跳过原因，供预览和执行复用。
-      Plan = Data.define(:mode, :inventory, :ready, :outcomes) do
-        # Data 只冻结对象自身；这里复制并冻结可能由调用方修改的计划容器。
-        def initialize(mode:, inventory:, ready:, outcomes:)
-          unless inventory.is_a?(Array) && ready.is_a?(Array) && outcomes.is_a?(Array)
-            raise ArgumentError, "plan inventory, ready tasks, and outcomes must be Arrays"
-          end
-
-          tasks = ready.map { |task| task.is_a?(Array) ? task.dup.freeze : task }.freeze
-          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze)
-        end
-
-        # 按清单顺序返回选中的设备。
-        def selected = ready.map(&:last)
-      end
-
       # 根据设备就绪状态、厂商采样及远端文件冲突建立备份计划。
       class Planner
         # 保存本次规划使用的清单快照。
@@ -37,22 +23,25 @@ module Net
                      else
                        candidates
                      end
-          # PAN-OS 导出使用固定远端文件名，同批只允许一台设备写入。
-          palo_alto_index = selected.find { |device, _index| device.vendor == :palo_alto }&.last if mode == :tftp
           selected_indices = selected.to_h { |_device, index| [index, true] }
+          filenames = {}
+          if mode == :tftp
+            # 先按采样顺序保留每个目标的首台设备，再按清单顺序输出结果。
+            selected.each { |device, index| filenames[device.tftp_filename] ||= index }
+          end
           outcomes = Array.new(@inventory.size)
           ready = @inventory.each_with_index.filter_map do |device, index|
             if !device.ready?
               outcomes[index] = skipped(device, device.issue)
               nil
-            elsif mode == :tftp && device.vendor == :palo_alto && index != palo_alto_index
+            elsif !selected_indices.key?(index)
+              outcomes[index] = skipped(device, :sample_limit)
+              nil
+            elsif mode == :tftp && filenames.fetch(device.tftp_filename) != index
               outcomes[index] = skipped(device, :remote_filename_collision)
               nil
-            elsif selected_indices.key?(index)
-              [index, device].freeze
             else
-              outcomes[index] = skipped(device, :sample_limit)
-              nil
+              [index, device].freeze
             end
           end
           Plan.new(mode: mode, inventory: @inventory, ready: ready.freeze, outcomes: outcomes.freeze)

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "batch"
+
+module Net
+  module Connector
+    module Netdisco
+      # v2 显式包装旧 Batch；成功策略与清单覆盖分开，默认 Batch JSON 不增加字段。
+      class Report
+        extend Forwardable
+        SUCCESS = %i[backed_up reported_uploaded].freeze
+        ATTEMPTED = [*SUCCESS, :failed, :saved_with_error, :reported_with_error].freeze
+        IGNORABLE = %i[filtered sample_limit].freeze
+        private_constant :SUCCESS, :ATTEMPTED, :IGNORABLE
+
+        attr_reader :batch, :policy, :duration_ms, :report_diagnostic
+        def_delegators :@batch, *Batch.members, :success?, :status, :counts
+
+        # selected 必须使用带策略和覆盖信息的 v2；默认 strict 继续使用旧 schema。
+        def self.options(policy: :strict, schema: nil)
+          raise ArgumentError, "success_policy must be strict or selected" unless %i[strict selected].include?(policy)
+
+          schema = policy == :selected ? 2 : 1 if schema.nil?
+          raise ArgumentError, "report_schema must be 1 or 2" unless schema.is_a?(Integer) && [1, 2].include?(schema)
+          raise ArgumentError, "selected success policy requires report schema 2" if policy == :selected && schema != 2
+
+          { policy: policy, schema: schema }.freeze
+        end
+
+        def initialize(batch, policy: :strict, duration_ms: nil, report_diagnostic: nil)
+          self.class.options(policy: policy, schema: 2)
+          raise ArgumentError, "report requires a Batch" unless batch.instance_of?(Batch)
+          unless duration_ms.nil? || (duration_ms.is_a?(Numeric) && duration_ms.real? && duration_ms.finite? && duration_ms >= 0)
+            raise ArgumentError, "duration_ms must be nonnegative and finite"
+          end
+          unless report_diagnostic.nil? || report_diagnostic.instance_of?(Diagnostic)
+            raise ArgumentError, "report_diagnostic must be a Diagnostic"
+          end
+
+          @batch, @policy, @duration_ms, @report_diagnostic = batch, policy, duration_ms, report_diagnostic
+          freeze
+        end
+
+        # 旧 success?/status 委托给 Batch；新策略绝不把未知状态当作可忽略跳过。
+        def policy_success?
+          return batch.success? if policy == :strict
+          return false unless callback_errors.empty? && report_error.nil?
+
+          outcomes.any? { |item| SUCCESS.include?(item.status) } &&
+            outcomes.all? { |item| SUCCESS.include?(item.status) || IGNORABLE.include?(item.status) }
+        end
+
+        def with(**attributes)
+          self.class.new(batch.with(**attributes), policy: policy, duration_ms: duration_ms,
+                          report_diagnostic: report_diagnostic)
+        end
+
+        def with_report_error(error, location: nil)
+          diagnostic = Diagnostic.from(error, phase: :report)
+          self.class.new(batch.with(report_location: location, report_error: diagnostic.error_type),
+                          policy: policy, duration_ms: duration_ms, report_diagnostic: diagnostic)
+        end
+
+        # 复用旧业务数据，但重新白名单化所有诊断字段，包括手工构造的旧 Batch。
+        def summary
+          legacy = batch.summary
+          legacy.merge(
+            schema_version: 2, policy: policy, policy_success: policy_success?, duration_ms: duration_ms,
+            coverage: { complete: !outcomes.empty? && outcomes.all? { |item| ATTEMPTED.include?(item.status) },
+                        attempted: outcomes.count { |item| ATTEMPTED.include?(item.status) },
+                        skipped: outcomes.count { |item| !ATTEMPTED.include?(item.status) } },
+            devices: device_summaries(legacy.fetch(:devices)),
+            callback_errors: callback_errors.map { |entry| { host: entry[:host], error_type: Diagnostic.type(entry[:error_type]) } },
+            report_location: report_location, report_error: Diagnostic.type(report_error),
+            report_diagnostic: report_diagnostic&.to_h
+          )
+        end
+
+        def inspect = "#<#{self.class} policy=#{policy} status=#{status} policy_success=#{policy_success?}>"
+
+        private
+
+        def device_summaries(entries)
+          entries.zip(outcomes).map do |entry, item|
+            diagnostic = item.diagnostic || Diagnostic.new(error_code: item.error_code, error_type: item.error_type)
+            entry.merge(error_code: diagnostic.error_code, error_type: diagnostic.error_type,
+                        diagnostic: diagnostic.to_h.except(:error_code, :error_type))
+          end
+        end
+      end
+    end
+  end
+end

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
+          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
-          Client.new(**options)
+          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,178 @@ 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)
+
+          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
 
-          raw.transform_keys(&:to_sym)
+        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 credentials_for(device)
+        # 兼容原入口；Fleet 传入本批策略，独立调用则读取当前策略和当前秘密。
+        def credentials_for(device, policy: snapshot(mode: :backup))
+          credentials = device_credentials_for(device)
+          policy.connection_options(device.vendor).merge(credentials) if credentials
+        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