zabbix_manager 5.1.6 → 6.0.1

data/lib/zabbix_manager/configuration.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # 在首次网络访问之前统一校验连接配置。
+  class Configuration
+    ENVIRONMENT_KEYS = {
+      url: "ZABBIX_URL", api_token: "ZABBIX_API_TOKEN",
+      username: "ZABBIX_USERNAME", password: "ZABBIX_PASSWORD"
+    }.freeze
+    CREDENTIALS = %i[api_token username password http_user http_password].freeze
+    BOOLEAN_OPTIONS = %i[verify_ssl allow_insecure_http no_proxy ignore_version].freeze
+    OPTIONS = (CREDENTIALS + BOOLEAN_OPTIONS + %i[
+      url proxy ca_file timeout request_timeout max_response_bytes
+      open_timeout read_timeout write_timeout keep_alive_timeout
+      logger log_level upsert_lock uncertain_write_delays
+    ]).freeze
+    DEFAULT_UNCERTAIN_WRITE_DELAYS = [0, 0.25, 1, 2].freeze
+
+    # 仅从指定环境映射读取连接身份字段。
+    # 显式选项优先于环境值，包含用于清除凭据的 nil。
+    def self.from_env(env, overrides)
+      ENVIRONMENT_KEYS.to_h { |key, name| [key, env[name]] }.merge(overrides)
+    end
+
+    # 返回已校验的配置，不修改调用方持有的值。
+    def self.parse(options)
+      new(options).to_h
+    end
+
+    def initialize(options)
+      raise Invalid, "options must be a Hash" unless options.is_a?(Hash)
+
+      @options = options.symbolize_keys
+      @options.assert_valid_keys(*OPTIONS)
+      @options.transform_values! { |value| value.is_a?(String) ? value.dup.freeze : value }
+      validate_credentials!
+      validate_booleans!
+      validate_delays!
+      validate_collaborators!
+    rescue ArgumentError => error
+      raise Invalid, error.message, cause: nil
+    end
+
+    def to_h
+      @options.freeze
+    end
+
+    def inspect
+      "#<#{self.class}>"
+    end
+
+    private
+
+    def validate_credentials!
+      CREDENTIALS.each do |key|
+        value = @options[key]
+        raise Invalid, "#{key} must be a String" unless value.nil? || value.is_a?(String)
+
+        if key == :api_token && value && !value.empty?
+          unless value.valid_encoding? && value.ascii_only? && value.match?(/\A[!-~]+\z/)
+            raise Invalid, "api_token must contain printable ASCII characters without whitespace"
+          end
+        end
+
+        @options.delete(key) if value.blank?
+      end
+      raise Invalid, "url is required" if @options[:url].blank?
+
+      token = @options[:api_token]
+      username = @options[:username]
+      password = @options[:password]
+      if token && (username || password)
+        raise Invalid, "api_token cannot be combined with username/password"
+      end
+      raise Invalid, "provide api_token or both username and password" unless token || (username && password)
+      return unless @options[:http_password] && !@options[:http_user]
+
+      raise Invalid, "http_password requires http_user"
+    end
+
+    def validate_booleans!
+      BOOLEAN_OPTIONS.each do |key|
+        next unless @options.key?(key)
+        next if [true, false].include?(@options[key])
+
+        raise Invalid, "#{key} must be true or false"
+      end
+    end
+
+    def validate_delays!
+      values = @options.fetch(:uncertain_write_delays, DEFAULT_UNCERTAIN_WRITE_DELAYS)
+      raise Invalid, "uncertain_write_delays must be an Array" unless values.is_a?(Array)
+
+      delays = values.map { |value| Float(value, exception: false) }
+      finite_nonnegative = delays.all? { |value| value && value.finite? && value >= 0 }
+      unless (1..10).cover?(delays.size) && finite_nonnegative && delays.sum <= 60
+        raise Invalid, "uncertain_write_delays must contain 1 to 10 non-negative seconds totaling at most 60"
+      end
+
+      @options[:uncertain_write_delays] = delays.freeze
+    end
+
+    def validate_collaborators!
+      lock = @options[:upsert_lock]
+      raise Invalid, "upsert_lock must respond to call(key, &block)" if lock && !lock.respond_to?(:call)
+
+      logger = @options[:logger]
+      required = %i[debug info warn formatter formatter=]
+      required << :level= if @options.key?(:log_level)
+      return if logger.nil? || required.all? { |method| logger.respond_to?(method) }
+
+      raise Invalid, "logger must support the Ruby Logger interface"
+    end
+  end
+end

data/lib/zabbix_manager/http_transport.rb

@@ -7,9 +7,15 @@ require "timeout"
 require "uri"
 
 class ZabbixManager
+  # 持有串行复用的 Net::HTTP 会话，负责代理、TLS、连接关闭及网络错误转换。
+  # 超时配置作用于连接、读取和写入阶段；传输失败不重放请求。
   class HttpTransport
     DEFAULT_TIMEOUT = 60
     DEFAULT_KEEP_ALIVE_TIMEOUT = 30
+    DEFAULT_MAX_RESPONSE_BYTES = 64 * 1024 * 1024
+    # 仅用于中止单次网络操作，不包裹业务编排或应用层事务。
+    class RequestDeadline < Timeout::Error; end
+    private_constant :RequestDeadline
     NETWORK_ERRORS = [
       Timeout::Error, EOFError, IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError,
       Net::ProtocolError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError
@@ -18,10 +24,19 @@ class ZabbixManager
     attr_reader :uri
 
     # 解析连接、超时和代理配置，并准备持久会话。
+    # @param options [Hash] URL、超时、TLS 和代理设置；不会在初始化时连接
+    # @raise [Invalid] URL、超时或布尔选项无效
     def initialize(options)
-      @options = options
+      @options = options.dup.freeze
+      validate_boolean_options!
       @uri = parse_uri(options.fetch(:url))
       @timeout = positive_number(options.fetch(:timeout, DEFAULT_TIMEOUT), :timeout)
+      @request_timeout = positive_number(options.fetch(:request_timeout, @timeout), :request_timeout)
+      @max_response_bytes = options.fetch(:max_response_bytes, DEFAULT_MAX_RESPONSE_BYTES)
+      unless @max_response_bytes.is_a?(Integer) && @max_response_bytes.positive?
+        raise Invalid, "max_response_bytes must be a positive integer"
+      end
+
       @open_timeout = positive_number(options.fetch(:open_timeout, @timeout), :open_timeout)
       @read_timeout = positive_number(options.fetch(:read_timeout, @timeout), :read_timeout)
       @write_timeout = positive_number(options.fetch(:write_timeout, @timeout), :write_timeout)
@@ -35,20 +50,21 @@ class ZabbixManager
     end
 
     # 串行发送请求，失败时关闭连接但不自动重放写操作。
+    # @param body [String] 已序列化的 JSON-RPC 请求
+    # @param bearer_token [String, nil] 当前请求的 API 认证凭据
+    # @return [String] HTTP 成功响应正文，由 Client 验证 JSON-RPC 协议
+    # @raise [TransportError] HTTP 状态失败、连接中断或超时；写入可能已生效
     def request(body, bearer_token: nil)
+      request = build_request(body, bearer_token)
       @mutex.synchronize do
-        response = active_http.request(build_request(body, bearer_token))
-        unless response.is_a?(Net::HTTPSuccess)
-          raise TransportError, "HTTP Error: #{response.code} on #{safe_url}"
-        end
-
-        response.body
+        # Net::HTTP 原生阶段超时仍生效；额外期限只覆盖连接、发送及读取，不重放 POST。
+        Timeout.timeout(@request_timeout, RequestDeadline) { read_response(request) }
       rescue TransportError
         disconnect
         raise
       rescue *NETWORK_ERRORS => e
         disconnect
-        raise TransportError, "#{e.class}: request failed for #{safe_url}"
+        raise TransportError, "#{e.class}: request failed for #{safe_url}", cause: nil
       rescue StandardError
         disconnect
         raise
@@ -56,12 +72,14 @@ class ZabbixManager
     end
 
     # 显式关闭当前持久连接。
+    # @return [true] 重复关闭也成功，下一次请求按需重新连接
     def close
       @mutex.synchronize { disconnect }
       true
     end
 
     # 返回不包含 URL 凭据和查询串的安全地址。
+    # @return [String]
     def safe_url
       port = @uri.port == @uri.default_port ? nil : ":#{@uri.port}"
       "#{@uri.scheme}://#{@uri.host}#{port}#{@uri.path}"
@@ -76,117 +94,147 @@ class ZabbixManager
 
     private
 
-      # 校验并解析 HTTP 或 HTTPS API 地址。
-      def parse_uri(value)
-        uri = URI.parse(value.to_s)
-        unless %w[http https].include?(uri.scheme) && uri.host && !uri.host.empty?
-          raise Invalid, "url must be an absolute HTTP or HTTPS URL"
+    # 流式累计解压后的响应字节，避免在检查上限之前缓冲整个正文。
+    def read_response(request)
+      body = +""
+      active_http.request(request) do |response|
+        unless response.is_a?(Net::HTTPSuccess)
+          raise TransportError, "HTTP Error: #{response.code} on #{safe_url}"
         end
 
-        uri
-      rescue URI::InvalidURIError
-        raise Invalid, "url must be an absolute HTTP or HTTPS URL"
+        response.read_body do |chunk|
+          if body.bytesize + chunk.bytesize > @max_response_bytes
+            raise TransportError, "HTTP response exceeds max_response_bytes on #{safe_url}"
+          end
+
+          body << chunk
+        end
       end
+      body
+    end
 
-      # 把超时配置转换为正数。
-      def positive_number(value, name)
-        number = Float(value)
-        raise Invalid unless number.positive?
+    # 校验并解析 HTTP 或 HTTPS API 地址。
+    def parse_uri(value)
+      uri = URI.parse(value)
+      unless %w[http https].include?(uri.scheme) && uri.hostname && !uri.hostname.empty? &&
+             (1..65_535).cover?(uri.port)
+        raise Invalid, "url must be an absolute HTTP or HTTPS URL with a valid port"
+      end
+
+      uri.freeze
+    rescue URI::InvalidURIError, TypeError
+      raise Invalid, "url must be an absolute HTTP or HTTPS URL", cause: nil
+    end
 
-        number
-      rescue ArgumentError, TypeError
-        raise Invalid, "#{name} must be greater than zero"
+    # 防止字符串布尔值改变 TLS 校验或代理开关。
+    def validate_boolean_options!
+      %i[verify_ssl no_proxy].each do |name|
+        next unless @options.key?(name)
+        next if [true, false].include?(@options[name])
+
+        raise Invalid, "#{name} must be true or false"
       end
+    end
 
-      # 按显式配置和环境变量顺序解析代理。
-      def proxy_uri(options)
-        return if options[:no_proxy]
+    # 把超时配置转换为有限正数。
+    def positive_number(value, name)
+      number = Float(value)
+      raise ArgumentError unless number.finite? && number.positive?
 
-        value = options[:proxy] || environment_proxy
-        return if value.nil? || value.empty?
+      number
+    rescue ArgumentError, TypeError
+      raise Invalid, "#{name} must be a finite number greater than zero", cause: nil
+    end
 
-        uri = URI.parse(value)
-        unless %w[http https].include?(uri.scheme) && uri.host.present?
-          raise Invalid, "proxy must be an absolute HTTP or HTTPS URL"
-        end
+    # 复用标准库的代理发现与排除规则，并拒绝无法兑现的代理协议。
+    def proxy_uri(options)
+      return if options[:no_proxy]
 
-        uri
-      rescue URI::InvalidURIError
-        raise Invalid, "proxy must be a valid URL"
+      value = options[:proxy]
+      uri = value.nil? ? URI::HTTP.build(host: @uri.hostname, port: @uri.port).find_proxy : URI.parse(value)
+      return unless uri
+      unless uri.is_a?(URI::HTTP) && uri.scheme == "http" && uri.hostname &&
+             (1..65_535).cover?(uri.port) && ["", "/"].include?(uri.path) && !uri.query && !uri.fragment
+        raise Invalid, "proxy must be an absolute HTTP URL without a path, query or fragment"
       end
 
-      # 根据目标协议选择对应的环境代理。
-      def environment_proxy
-        return ENV["http_proxy"] || ENV["HTTP_PROXY"] unless @uri.scheme == "https"
+      uri.freeze
+    rescue URI::InvalidURIError, TypeError
+      raise Invalid, "proxy must be an absolute HTTP URL", cause: nil
+    end
 
-        ENV["https_proxy"] || ENV["HTTPS_PROXY"] || ENV["http_proxy"] || ENV["HTTP_PROXY"]
-      end
+    # 复用已启动连接，并在 fork 后放弃继承套接字。
+    def active_http
+      abandon_inherited_connection if @pid && @pid != Process.pid
+      @http ||= build_http
+      @http.start unless @http.started?
+      @pid = Process.pid
+      @http
+    end
 
-      # 复用已启动连接，并在 fork 后放弃继承套接字。
-      def active_http
-        abandon_inherited_connection if @pid && @pid != Process.pid
-        @http ||= build_http
-        @http.start unless @http.started?
-        @pid = Process.pid
-        @http
-      end
+    # 子进程不能向父进程继承的 TLS 套接字发送 close_notify。
+    def abandon_inherited_connection
+      @http = nil
+      @pid = nil
+    end
 
-      # 子进程不能向父进程继承的 TLS 套接字发送 close_notify。
-      def abandon_inherited_connection
-        @http = nil
-        @pid = nil
-      end
+    # 创建并配置 Net::HTTP 实例。
+    def build_http
+      http = Net::HTTP.new(@uri.hostname, @uri.port, *proxy_arguments)
+
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+      http.write_timeout = @write_timeout
+      http.keep_alive_timeout = @keep_alive_timeout
+      http.max_retries = 0
+      configure_tls(http)
+      http
+    end
 
-      # 创建并配置 Net::HTTP 实例。
-      def build_http
-        http = @proxy_uri ? build_proxy_http : Net::HTTP.new(@uri.host, @uri.port)
+    # 向 Net::HTTP 传入已解析代理，避免二次环境发现；凭据使用 URI 百分号解码。
+    def proxy_arguments
+      return [nil] unless @proxy_uri
 
-        http.open_timeout = @open_timeout
-        http.read_timeout = @read_timeout
-        http.write_timeout = @write_timeout if http.respond_to?(:write_timeout=)
-        http.keep_alive_timeout = @keep_alive_timeout if http.respond_to?(:keep_alive_timeout=)
-        configure_tls(http)
-        http
-      end
+      [
+        @proxy_uri.hostname,
+        @proxy_uri.port,
+        @proxy_uri.user && URI::DEFAULT_PARSER.unescape(@proxy_uri.user),
+        @proxy_uri.password && URI::DEFAULT_PARSER.unescape(@proxy_uri.password)
+      ]
+    end
 
-      # 创建使用显式代理的 Net::HTTP 实例。
-      def build_proxy_http
-        Net::HTTP::Proxy(
-          @proxy_uri.host,
-          @proxy_uri.port,
-          @proxy_uri.user,
-          @proxy_uri.password
-        ).new(@uri.host, @uri.port)
-      end
+    # 配置 HTTPS；证书校验默认关闭，按调用方选项开启。
+    def configure_tls(http)
+      return unless @uri.scheme == "https"
 
-      # 配置 HTTPS；证书校验默认关闭，按调用方选项开启。
-      def configure_tls(http)
-        return unless @uri.scheme == "https"
+      http.use_ssl = true
+      http.verify_mode = @options[:verify_ssl] == true ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      http.ca_file = @options[:ca_file] if @options[:ca_file]
+    end
 
-        http.use_ssl = true
-        http.verify_mode = @options[:verify_ssl] == true ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
-        http.ca_file = @options[:ca_file] if @options[:ca_file]
+    # 构建 JSON-RPC POST，并在需要时写入 Bearer 或 Basic 认证。
+    def build_request(body, bearer_token)
+      if bearer_token && @options[:http_user]
+        raise Invalid, "HTTP Basic authentication cannot be combined with Bearer authentication"
       end
 
-      # 构建 JSON-RPC POST，并在需要时写入 Bearer 或 Basic 认证。
-      def build_request(body, bearer_token)
-        request = Net::HTTP::Post.new(@uri.request_uri)
-        request["Content-Type"] = "application/json-rpc"
-        request["Accept"] = "application/json"
-        request["Authorization"] = "Bearer #{bearer_token}" if bearer_token
-        request.basic_auth(@options[:http_user], @options[:http_password]) if @options[:http_user]
-        request.body = body
-        request
-      end
+      request = Net::HTTP::Post.new(@uri.request_uri)
+      request["Content-Type"] = "application/json-rpc"
+      request["Accept"] = "application/json"
+      request["Authorization"] = "Bearer #{bearer_token}" if bearer_token
+      request.basic_auth(@options[:http_user], @options[:http_password]) if @options[:http_user]
+      request.body = body
+      request
+    end
 
-      # 安全结束连接并清理当前进程的会话状态。
-      def disconnect
-        @http.finish if @http&.started?
-      rescue IOError, SystemCallError
-        nil
-      ensure
-        @http = nil
-        @pid = nil
-      end
+    # 安全结束连接并清理当前进程的会话状态。
+    def disconnect
+      @http.finish if @pid == Process.pid && @http&.started?
+    rescue *NETWORK_ERRORS
+      nil
+    ensure
+      @http = nil
+      @pid = nil
+    end
   end
 end

data/lib/zabbix_manager/log_sanitizer.rb

@@ -1,32 +1,27 @@
 # frozen_string_literal: true
 
 require "uri"
+require "active_support/parameter_filter"
 
 class ZabbixManager
+  # 日志与诊断数据的脱敏边界；过滤已知敏感字段、认证头和 URL 凭据。
+  # 自由文本过滤不能识别任意秘密，因此客户端不记录请求参数或服务端原始错误文本。
   module LogSanitizer
     REDACTED = "[FILTERED]"
     MAX_STRING_LENGTH = 2_000
-    SENSITIVE_KEY_NAMES = "auth|authorization|api_token|community|cookie|http_password|password|passwd|" \
-                          "privatekey|secret|sessionid|snmp_community|snmpv3_authpassphrase|" \
-                          "snmpv3_privpassphrase|tls_psk|tls_psk_identity|token"
-    SENSITIVE_KEYS = /\A(?:#{SENSITIVE_KEY_NAMES})\z/i.freeze
+    SENSITIVE_KEY_NAMES = "auth|authorization|authpassphrase|api_token|community|cookie|" \
+      "http_password|password|passwd|privatekey|privpassphrase|secret|sessionid|snmp_community|snmpv3_authpassphrase|" \
+      "snmpv3_privpassphrase|tls_psk|tls_psk_identity|token"
+    SENSITIVE_KEYS = /\A(?:#{SENSITIVE_KEY_NAMES})\z/i
+    FILTER = ActiveSupport::ParameterFilter.new(
+      [SENSITIVE_KEYS, ->(_key, value) { value.replace(sanitize_string(value)) if value.is_a?(String) }]
+    ).freeze
 
     module_function
 
     # 递归脱敏结构化对象，并限制字符串长度。
     def sanitize(value)
-      case value
-      when Hash
-        value.each_with_object({}) do |(key, child), result|
-          result[key] = sensitive_key?(key) ? REDACTED : sanitize(child)
-        end
-      when Array
-        value.map { |child| sanitize(child) }
-      when String
-        sanitize_string(value)
-      else
-        value
-      end
+      FILTER.filter_param("value", value)
     end
 
     # 移除 URL 中的用户名、密码、查询串和片段。
@@ -38,31 +33,25 @@ class ZabbixManager
       uri.fragment = nil
       uri.to_s
     rescue URI::InvalidURIError
-      sanitize_string(value.to_s)
+      REDACTED
     end
 
     # 清理字符串中的认证头和常见敏感键值。
     def sanitize_string(value)
       sanitized = value.dup
-      sanitized.gsub!(/\b(Bearer|Basic)\s+[^\s,;]+/i, "\\1 #{REDACTED}")
-      sanitized.gsub!(
-        /((?:authorization)["']?\s*(?:=>|:|=)\s*)[^,;}\]]+/i,
-        "\\1#{REDACTED}"
-      )
+      # 先处理完整引号值，避免认证头规则在值内的分隔符处截断秘密。
       sanitized.gsub!(
-        /((?:#{SENSITIVE_KEY_NAMES})["']?\s*(?:=>|:|=)\s*)(["'])(.*?)\2/i,
+        /((?:#{SENSITIVE_KEY_NAMES})["']?\s*(?:=>|:|=)\s*)(["'])((?:\\.|(?!\2)[^\\])*)\2/im,
         "\\1\\2#{REDACTED}\\2"
       )
       sanitized.gsub!(
-        /((?:#{SENSITIVE_KEY_NAMES})["']?\s*(?:=>|:|=)\s*)(?!["'])[^,;}\]]+/i,
+        /((?:#{SENSITIVE_KEY_NAMES})["']?\s*(?:=>|:|=)\s*+)
+         (?!["']|#{Regexp.escape(REDACTED)}(?=[,;}\]]|\z))
+         (?:#{Regexp.escape(REDACTED)}|[^,;}\]])+/ix,
         "\\1#{REDACTED}"
       )
+      sanitized.gsub!(/\b(Bearer|Basic)\s+[^\s,;]+/i, "\\1 #{REDACTED}")
       sanitized.length > MAX_STRING_LENGTH ? "#{sanitized[0, MAX_STRING_LENGTH]}...[TRUNCATED]" : sanitized
     end
-
-    # 判断字段名是否属于敏感配置。
-    def sensitive_key?(key)
-      key.to_s.match?(SENSITIVE_KEYS)
-    end
   end
 end