zabbix_manager 5.1.4 → 5.1.6

data/lib/zabbix_manager/client.rb

@@ -1,189 +1,365 @@
 # frozen_string_literal: true
 
-require "net/http"
 require "json"
-require "openssl"
+require "logger"
 
 class ZabbixManager
   class Client
-    # 用于读取配置选项
-    attr_reader :options
+    SUPPORTED_MAJOR_VERSIONS = (4..7).freeze
+    UNAUTHENTICATED_METHODS = %w[apiinfo.version user.login].freeze
+    BLANK_NORMALIZED_OPTIONS = %i[api_token username user password http_user http_password].freeze
+    UPSERT_MUTEX_STRIPES = 64
+    DEFAULT_UNCERTAIN_WRITE_DELAYS = [0, 0.25, 1, 2].freeze
 
-    # 生成一个随机的请求标识符
-    def id
-      @id ||= rand 100_00
-    end
+    attr_reader :options, :sanitized_options, :logger
 
-    # 获取 Zabbix API 版本
-    def api_version
-      api_request(method: "apiinfo.version", params: {})
+    # 构建按服务端版本选择认证方式并复用 HTTP 会话的客户端。
+    # @return [Client]
+    # @api public
+    def initialize(options = {})
+      @raw_options = normalize_options(options)
+      validate_credentials!
+      validate_uncertain_write_delays!
+      @sanitized_options = sanitize_options(@raw_options).freeze
+      @options = @sanitized_options
+      @logger = build_logger
+      @id_mutex = Mutex.new
+      @next_id = 0
+      @upsert_mutexes = Array.new(UPSERT_MUTEX_STRIPES) { Mutex.new }
+      validate_upsert_lock!
+      @transport = HttpTransport.new(@raw_options)
+      validate_token_transport!
+      @api_version = api_version
+      validate_api_version!
+      validate_http_auth_compatibility!
+      @credential_type = @raw_options[:api_token] ? :api_token : :user_session
+      @auth_token = @raw_options[:api_token] || auth
+      log(:info, "client.connected", version: @api_version, credential_type: @credential_type)
+      log(:warn, "tls.verification_disabled", url: @transport.safe_url) if insecure_https?
+      log(:warn, "token.sent_over_http", url: @transport.safe_url) if insecure_token_transport?
+    rescue StandardError
+      @transport&.close
+      raise
     end
 
-    # 是否启用 debug 模式
-    def debug?
-      !@options || @options[:debug]
+    # 分配线程安全的 JSON-RPC 请求编号。
+    # @return [Integer]
+    # @api semipublic
+    def id
+      @id_mutex.synchronize { @next_id += 1 }
     end
 
-    # Debug 打印信息
-    def log(message)
-      puts message if debug?
+    # 返回首次查询后缓存的远端 Zabbix API 版本。
+    # @return [String]
+    # @api public
+    def api_version
+      @api_version ||= api_request(method: "apiinfo.version", params: {})
     end
 
-    # 用户鉴权方法，登录成功即可获取令牌
+    # 使用用户名和密码创建 Zabbix 会话。
+    # @return [String] Zabbix session token
+    # @api semipublic
     def auth
-      # 发起 "user.login" 方法的 API 请求, 并传递用户信息（用户名和密码）作为参数
       api_request(
         method: "user.login",
         params: {
-          user:     @options[:user],
-          password: @options[:password]
+          login_parameter => username,
+          password: @raw_options[:password]
         }
       )
     end
 
-    # HTTP 客户端初始化方法，同时进行用户权限签证
-    def initialize(options = {})
-      # 设置实例变量 @options 以便在整个类中访问
-      @options = options
-
-      # 检查必要的配置属性是否存在
-      raise ZbxError, "必须正确提供 :url 属性" unless @options.key?(:url)
-      raise ZbxError, "必须正确提供 :user 属性" unless @options.key?(:user)
-      raise ZbxError, "必须正确提供 :password 属性" unless @options.key?(:password)
-
-      # 配置代理信息
-      if !ENV["http_proxy"].nil? && options[:no_proxy] != true
-        @proxy_uri               = URI.parse(ENV["http_proxy"])
-        @proxy_host              = @proxy_uri.host
-        @proxy_port              = @proxy_uri.port
-        @proxy_user, @proxy_pass = @proxy_uri.userinfo&.split(/:/) if @proxy_uri.userinfo
-      end
-
-      # 检查 Zabbix API 版本是否受支持
-      unless api_version.match?(/^(234567)\.\d+\.\d+$/)
-        message = "Zabbix API版本：#{api_version} 不受此版本的 zabbix_manager 支持"
-        if @options[:ignore_version]
-          log "[WARNING] #{message}"
-        else
-          raise ZbxError, message
-        end
-      end
-
-      # 进行用户鉴权，获取令牌
-      @auth_hash = auth
-      log "[DEBUG] Auth token: #{@auth_hash}"
+    # 判断是否启用调试日志。
+    # @return [Boolean]
+    # @api semipublic
+    def debug?
+      @raw_options[:debug] == true
     end
 
-    # 定义一个方法，用于将 Ruby 数据结构转换为 JSON 字符串，并根据条件添加令牌
-    def json_payload(body)
-      # 构建基本的 JSON 负载，包括方法名、参数、请求 ID 和 JSON-RPC 版本
-      payload        = {
-        method:  body[:method],
-        params:  body[:params],
-        id:      id,
+    # 序列化 JSON-RPC 请求并按版本加入请求体认证。
+    # @return [String]
+    # @api semipublic
+    def message_json(body)
+      method = fetch_body_value(body, :method)
+      message = {
+        method: method,
+        params: fetch_body_value(body, :params) || {},
+        id: id,
         jsonrpc: "2.0"
       }
+      message[:auth] = @auth_token if @auth_token && body_authentication?(method)
+      JSON.generate(message)
+    end
+
+    # 通过持久连接发送请求，并按版本加入 Bearer 令牌。
+    # @return [String] raw response body
+    # @api semipublic
+    def http_request(body)
+      method = JSON.parse(body).fetch("method")
+      @transport.request(body, bearer_token: bearer_token_for(method))
+    end
 
-      # 检查请求方法是否是 "apiinfo.version" 或 "user.login"，如果不是，则添加令牌信息
-      payload[:auth] = @auth_hash unless body[:method] == "apiinfo.version" || body[:method] == "user.login"
+    # 解析 JSON-RPC 响应并统一转换协议错误。
+    # @return [Object]
+    # @api semipublic
+    def _request(body)
+      parsed = JSON.parse(http_request(body))
+      raise_api_error(parsed, body) if parsed["error"]
+      unless parsed.key?("result")
+        raise ApiError.new("Invalid JSON-RPC response: missing result", LogSanitizer.sanitize(parsed))
+      end
 
-      # 将构建好的负载转换为 JSON 字符串并返回
-      JSON(payload)
+      parsed["result"]
+    rescue JSON::ParserError => e
+      raise ApiError, "Invalid JSON response: #{e.message}"
     end
 
-    # 实例化 Net::HTTP 对象，并发起 API 请求的方法
-    def http_request(body)
-      uri = URI.parse(@options[:url])
+    # 格式化请求摘要并隐藏全部参数值。
+    # @return [String]
+    # @api semipublic
+    def pretty_body(body)
+      parsed = JSON.parse(body)
+      parsed["params"] = LogSanitizer::REDACTED if parsed.key?("params")
+      JSON.pretty_generate(LogSanitizer.sanitize(parsed))
+    end
+
+    # 执行 Zabbix JSON-RPC 方法并记录脱敏耗时日志。
+    # @return [Object] decoded result value
+    # @api public
+    def api_request(body)
+      method = fetch_body_value(body, :method)
+      started_at = monotonic_time
+      log(:debug, "request.started", method: method)
+      result = _request(message_json(body))
+      log(:info, "request.completed", method: method, duration_ms: elapsed_ms(started_at))
+      result
+    rescue StandardError => e
+      log(:warn, "request.failed", method: method, duration_ms: elapsed_ms(started_at), error: e.class.name)
+      raise
+    end
+    alias manager_request api_request
+
+    # 注销用户名会话并关闭持久连接；API 令牌无需远端注销。
+    # @return [Object] logout result
+    # @api public
+    def logout
+      result = @credential_type == :user_session && @auth_token ? api_request(method: "user.logout", params: []) : true
+      result
+    ensure
+      @auth_token = nil
+      close
+    end
+
+    # 关闭持久 HTTP 连接。
+    # @return [Object]
+    # @api public
+    def close
+      @transport.close
+    end
+
+    # 输出结构化且已脱敏的客户端事件。
+    # @return [void]
+    # @api semipublic
+    def log(level, event, data = {})
+      return unless @logger
+
+      sanitized = LogSanitizer.sanitize(data)
+      details = sanitized.map { |key, value| "#{key}=#{value.inspect}" }.join(" ")
+      @logger.public_send(level, ["[zabbix_manager]", event, details].reject(&:empty?).join(" "))
+    end
+
+    # 返回不包含凭据的客户端摘要，避免对象检查时泄漏配置
+    # @return [String]
+    # @api public
+    def inspect
+      "#<#{self.class} options=#{@sanitized_options.inspect}>"
+    end
+
+    # 以业务键串行执行幂等写入，并可接入跨进程锁实现
+    # @return [Object] 代码块结果
+    # @api semipublic
+    def with_upsert_lock(key, &block)
+      mutex = @upsert_mutexes[key.hash % UPSERT_MUTEX_STRIPES]
+      mutex.synchronize do
+        coordinator = @raw_options[:upsert_lock]
+        coordinator ? coordinator.call(key, &block) : yield
+      end
+    end
+
+    private
+
+      # 统一配置键并把页面提交的空凭据归一化为 nil
+      # @return [Hash]
+      # @api private
+      def normalize_options(options)
+        unless options.respond_to?(:each_pair)
+          raise Invalid, "options must be a hash-like object"
+        end
 
-      # 设置超时时间，默认为 60 秒
-      timeout = @options[:timeout].nil? ? 60 : @options[:timeout]
-      log "[DEBUG] Timeout for request set to #{timeout} seconds"
+        normalized = options.to_h.transform_keys(&:to_sym)
+        BLANK_NORMALIZED_OPTIONS.each do |key|
+          value = normalized[key].presence
+          value ? normalized[key] = value : normalized.delete(key)
+        end
+        normalized
+      end
+
+      # 脱敏普通凭据，并清理 URL 和代理地址中的 userinfo 与查询串。
+      def sanitize_options(options)
+        sanitized = LogSanitizer.sanitize(options)
+        %i[url proxy].each do |key|
+          sanitized[key] = LogSanitizer.sanitize_url(options[key]) if options[key]
+        end
+        sanitized
+      end
+
+      # 校验页面配置只能选择 API 令牌或用户名密码之一。
+      # @return [void]
+      # @api private
+      def validate_credentials!
+        raise Invalid, "url is required" if @raw_options[:url].nil? || @raw_options[:url].to_s.empty?
+
+        token_present = @raw_options[:api_token].present?
+        username_present = username.present?
+        password_present = @raw_options[:password].present?
+        if token_present && (username_present || password_present)
+          raise Invalid, "api_token cannot be combined with username/password"
+        end
+        return if token_present || (username_present && password_present)
+
+        raise Invalid, "provide api_token or both username and password"
+      end
+
+      # 校验传输结果不确定时的只读回查退避窗口。
+      def validate_uncertain_write_delays!
+        values = @raw_options.fetch(:uncertain_write_delays, DEFAULT_UNCERTAIN_WRITE_DELAYS)
+        delays = Array(values).map { |value| Float(value) }
+        unless delays.any? && delays.length <= 10 && delays.all? { |delay| delay >= 0 } && delays.sum <= 60
+          raise Invalid, "uncertain_write_delays must contain 1 to 10 non-negative seconds totaling at most 60"
+        end
+
+        @raw_options[:uncertain_write_delays] = delays.freeze
+      rescue ArgumentError, TypeError
+        raise Invalid, "uncertain_write_delays must contain numeric seconds"
+      end
+
+      # 校验可选的跨进程幂等锁适配器。
+      # @return [void]
+      # @api private
+      def validate_upsert_lock!
+        lock = @raw_options[:upsert_lock]
+        return if lock.nil? || lock.respond_to?(:call)
+
+        raise Invalid, "upsert_lock must respond to call(key, &block)"
+      end
 
-      # 创建 Net::HTTP 对象，支持代理设置
-      http =
-        if @proxy_uri
-          Net::HTTP.Proxy(@proxy_host, @proxy_port, @proxy_user, @proxy_pass).new(uri.host, uri.port)
+      # 校验服务端版本格式及支持范围。
+      # @return [void]
+      # @api private
+      def validate_api_version!
+        match = @api_version.to_s.match(/\A(\d+)\.(\d+)\.(\d+)\z/)
+        supported = match && SUPPORTED_MAJOR_VERSIONS.cover?(match[1].to_i)
+        return if supported
+
+        message = "Zabbix API version #{@api_version.inspect} is not supported"
+        if @raw_options[:ignore_version]
+          log(:warn, "version.unsupported", version: @api_version)
         else
-          Net::HTTP.new(uri.host, uri.port)
+          raise ApiError, message
         end
+      end
+
+      # 拒绝 Zabbix 7 Bearer 认证与 HTTP Basic 复用同一认证头。
+      # @return [void]
+      # @api private
+      def validate_http_auth_compatibility!
+        return unless api_major_version >= 7 && @raw_options[:http_user].present?
 
-      # 配置 HTTPS 请求
-      if uri.scheme == "https"
-        http.use_ssl     = true
-        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        raise Invalid, "HTTP Basic authentication cannot be combined with Zabbix 7 Bearer authentication"
       end
 
-      # 配置请求超时时间
-      http.open_timeout = timeout
-      http.read_timeout = timeout
+      # 默认阻止 API 令牌通过明文 HTTP 发送
+      # @return [void]
+      # @api private
+      def validate_token_transport!
+        return unless @raw_options[:api_token] && insecure_token_transport?
+        return if @raw_options[:allow_insecure_http] == true
 
-      # 创建 POST 请求
-      request = Net::HTTP::Post.new(uri.request_uri)
+        raise Invalid, "api_token requires HTTPS unless allow_insecure_http is true"
+      end
 
-      # 添加基本身份验证信息（如果提供了用户名和密码）
-      request.basic_auth(@options[:http_user], @options[:http_password]) if @options[:http_user]
+      # 判断当前令牌连接是否使用明文 HTTP
+      # @return [Boolean]
+      # @api private
+      def insecure_token_transport?
+        @raw_options[:api_token].present? && @transport.uri.scheme == "http"
+      end
 
-      # 设置请求头的 Content-Type 为 application/json-rpc
-      request.add_field("Content-Type", "application/json-rpc")
+      # 提取已缓存 API 版本的主版本号。
+      def api_major_version
+        @api_version.to_s.split(".", 2).first.to_i
+      end
 
-      # 设置请求体为传入的 JSON 字符串
-      request.body = body
-      log "[DEBUG] HTTP request params: #{pretty_body(request.body)}"
+      # 根据服务端版本选择登录用户名字段。
+      def login_parameter
+        api_major_version >= 6 ? :username : :user
+      end
 
-      # 发起请求并获取响应
-      response = http.request(request)
+      # 返回统一后的登录用户名。
+      def username
+        @raw_options[:username] || @raw_options[:user]
+      end
 
-      # 检查响应状态码，如果不是 200，则抛出 HttpError 异常
-      raise HttpError.new("HTTP Error: #{response.code} on #{@options[:url]}", response) unless response.code == "200"
+      # 判断当前方法是否应在 JSON-RPC 请求体中携带认证值。
+      def body_authentication?(method)
+        authenticated_method?(method) && api_major_version < 7
+      end
 
-      log "[DEBUG] HTTP response answer: #{pretty_body(response.body)}"
+      # 判断当前方法是否应使用 Bearer 认证头。
+      def bearer_token_for(method)
+        @auth_token if authenticated_method?(method) && api_major_version >= 7
+      end
 
-      # 返回响应体
-      response.body
-    end
+      # 排除版本查询和登录方法，判断请求是否需要认证。
+      def authenticated_method?(method)
+        !UNAUTHENTICATED_METHODS.include?(method.to_s)
+      end
 
-    # 对 API 响应结果进行解析的方法
-    def _request(body)
-      # 发起 HTTP 请求并解析 JSON 格式的响应
-      result = JSON.parse(http_request(body))
-
-      # 如果响应结果中包含错误信息，则抛出 ZbxError 异常
-      if result["error"]
-        # 构建错误消息，包括服务器返回的错误信息和请求的详细信息
-        msg = <<~MOJO
-          ---------------------------------------------------------------
-          Server answer API error: #{JSON.pretty_unparse(result["error"])}
-            on request: #{pretty_body(body)}
-          ---------------------------------------------------------------
-        MOJO
-
-        # 抛出自定义异常 ZbxError，并传递错误消息和完整的响应结果
-        raise ZbxError.new(msg, result)
-      else
-        # 如果没有错误信息，则返回响应结果中的 "result" 部分
-        result["result"]
+      # 同时读取符号键和字符串键的请求字段。
+      def fetch_body_value(body, key)
+        body[key] || body[key.to_s]
       end
-    end
 
-    # 将 Ruby 数据结构美化成 JSON 字符串后打印输出的方法
-    def pretty_body(body)
-      # 解析 JSON 字符串
-      data = JSON.parse(body)
+      # 使用脱敏响应和请求摘要构造 API 异常。
+      def raise_api_error(parsed, request_body)
+        safe_response = LogSanitizer.sanitize(parsed)
+        error = safe_response["error"]
+        message = "Zabbix API error #{error["code"]}: #{error["message"]}"
+        message = "#{message} (#{error["data"]})" if error["data"]
+        raise ApiError.new("#{message}\nRequest:\n#{pretty_body(request_body)}", safe_response)
+      end
+
+      # 优先使用调用方日志器，调试模式下才创建默认日志器。
+      def build_logger
+        return @raw_options[:logger] if @raw_options[:logger]
+        return unless debug?
 
-      # 如果参数中包含密码字段，则将密码字段的值替换为 "***"
-      if data["params"].is_a?(Hash) && data["params"].key?("password")
-        data["params"]["password"] = "***"
+        Logger.new($stdout).tap { |value| value.level = Logger::DEBUG }
       end
 
-      # 将美化后的数据转换为 JSON 字符串并返回
-      JSON.pretty_unparse(data)
-    end
+      # 判断 HTTPS 是否按项目要求关闭证书校验。
+      def insecure_https?
+        @transport.uri.scheme == "https" && @raw_options[:verify_ssl] != true
+      end
 
-    # 通用的 API 调用发起方法
-    def api_request(body)
-      # 调用之前定义的 json_payload 方法，将请求信息转换为 JSON 字符串
-      # 然后调用之前定义的 _request 方法，发起 API 请求并解析响应结果
-      _request json_payload(body)
-    end
+      # 读取不受系统时间校准影响的单调时钟。
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # 计算并格式化请求耗时毫秒数。
+      def elapsed_ms(started_at)
+        ((monotonic_time - started_at) * 1_000).round(1)
+      end
   end
 end