zabbix_manager 5.1.5 → 6.0.0

data/lib/zabbix_manager/client.rb

@@ -1,190 +1,236 @@
 # frozen_string_literal: true
 
-require "net/http"
 require "json"
-require "openssl"
+require "logger"
+require "active_support"
+require "active_support/logger"
+require "active_support/tagged_logging"
 
 class ZabbixManager
+  # 持有一个已认证连接，管理 JSON-RPC 请求的完整生命周期。
   class Client
-    # 用于读取配置选项
-    attr_reader :options
+    SUPPORTED_MAJOR_VERSIONS = (4..7)
+    UNAUTHENTICATED_METHODS = %w[apiinfo.version user.login].freeze
+    UPSERT_MUTEX_STRIPES = 64
+
+    attr_reader :options, :logger, :api_version
+
+    # 校验配置后立即查询服务器版本并完成认证。
+    # 初始化失败时关闭连接；成功后的客户端生命周期由调用方负责。
+    # @param options [Hash] 显式连接、凭据、日志及锁配置
+    # @raise [Invalid] 连接配置无效或相互冲突
+    # @raise [ApiError, TransportError, ProtocolError] 版本查询或认证失败
+    def initialize(**options)
+      @settings = Configuration.parse(options)
+      @options = sanitized_options.freeze
+      @logger = build_logger
+      @id_mutex = Mutex.new
+      @next_id = 0
+      @upsert_mutexes = Array.new(UPSERT_MUTEX_STRIPES) { Mutex.new }
+      @transport = HttpTransport.new(@settings)
+      validate_token_transport!
+      @api_version = api_request(method: "apiinfo.version")
+      validate_api_version!
+      validate_http_auth_compatibility!
+      @credential_type = @settings[:api_token] ? :api_token : :user_session
+      @auth_token = @settings[:api_token] || login
+      unless @auth_token.is_a?(String) && !@auth_token.empty?
+        raise ProtocolError, "Invalid authentication response"
+      end
 
-    # 生成一个随机的请求标识符
-    def id
-      @id ||= rand 100_00
+      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
 
-    # 获取 Zabbix API 版本
-    def api_version
-      api_request(method: "apiinfo.version", params: {})
+    # 执行一次请求，不重放失败或结果未确认的变更。
+    # @param method [String] 原生 API 方法，例如 "history.get"
+    # @param params [Hash, Array] 原生 Zabbix 参数，不将参数值写入日志
+    # @return [Object] 解码后的 JSON-RPC 结果，保留服务器返回的标量类型
+    # @raise [Invalid] 方法名或参数容器无效
+    # @raise [ApiError] 服务器明确拒绝请求
+    # @raise [TransportError, ProtocolError] 未收到能够确认结果的有效响应
+    def api_request(method:, params: {})
+      validate_request!(method, params)
+      started_at = monotonic_time
+      message = request_message(method, params)
+      log(:debug, "request.started", method: method)
+      body = @transport.request(JSON.generate(message), bearer_token: bearer_token_for(method))
+      result = parse_response(body, message.fetch(:id))
+      log(:info, "request.completed", method: method, duration_ms: elapsed_ms(started_at))
+      result
+    rescue StandardError => error
+      log(:warn, "request.failed", method: method, duration_ms: elapsed_ms(started_at), error: error.class.name)
+      raise
     end
 
-    # 是否启用 debug 模式
-    def debug?
-      !@options || @options[:debug]
+    # 注销密码认证会话；API token 仅需清理本地状态。
+    # 远端注销失败时仍清除本地认证令牌并关闭传输连接。
+    # @return [Boolean] 服务器注销结果；API token 模式返回 true
+    # @raise [ApiError, TransportError] 远端会话注销失败
+    def logout
+      @credential_type == :user_session && @auth_token ? api_request(method: "user.logout", params: []) : true
+    ensure
+      @auth_token = nil
+      close
     end
 
-    # Debug 打印信息
-    def log(message)
-      puts message if debug?
+    # 关闭连接但不撤销凭据；后续请求按需重新连接。
+    # @return [true]
+    def close
+      @transport.close
     end
 
-    # 用户鉴权方法，登录成功即可获取令牌
-    def auth
-      # 发起 "user.login" 方法的 API 请求, 并传递用户信息（用户名和密码）作为参数
-      api_request(
-        method: "user.login",
-        params: {
-          user:     @options[:user],
-          password: @options[:password]
-        }
-      )
-    end
+    # 延迟构造日志元数据；日志失败不能改变远端写入结果。
+    # @param level [Symbol] Ruby Logger 日志级别方法
+    # @param event [String] 稳定的事件名称
+    # @param data [Hash] 序列化之前经过脱敏的元数据
+    # @return [Object, nil] 日志返回值；日志关闭或失败时返回 nil
+    def log(level, event, data = {})
+      return unless @logger
 
-    # HTTP 客户端初始化方法，同时进行用户权限签证
-    def initialize(options = {})
-      # 设置实例变量 @options 以便在整个类中访问
-      @options = options
+      @logger.tagged("zabbix_manager") do
+        @logger.public_send(level) { JSON.generate(LogSanitizer.sanitize(data.merge(event: event))) }
+      end
+    rescue StandardError
+      nil
+    end
 
-      # 检查必要的配置属性是否存在
-      raise ZbxError, "必须正确提供 :url 属性" unless @options.key?(:url)
-      raise ZbxError, "必须正确提供 :user 属性" unless @options.key?(:user)
-      raise ZbxError, "必须正确提供 :password 属性" unless @options.key?(:password)
+    # @return [String] 仅包含脱敏配置的诊断摘要
+    def inspect
+      "#<#{self.class} options=#{@options.inspect}>"
+    end
 
-      # 配置代理信息
-      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
+    # 应用层锁适配器可将本地串行化扩展到多个工作进程。
+    # 锁不可重入；调用方不能在块内再次获取 upsert 锁。
+    # @param key [String] 被保护操作的稳定、非秘密身份
+    # @yield 需要串行执行的读取、修改和写入操作
+    # @return [Object] 块的返回值
+    def with_upsert_lock(key, &block)
+      @upsert_mutexes[key.hash % UPSERT_MUTEX_STRIPES].synchronize do
+        coordinator = @settings[:upsert_lock]
+        coordinator ? coordinator.call(key, &block) : yield
       end
+    end
 
-      # 检查 Zabbix API 版本是否受支持
-      unless api_version.match?(/^[4-7]\.\d+\.\d+$/)
-        message = "Zabbix API版本：#{api_version} 不受此版本的 zabbix_manager 支持"
-        if @options[:ignore_version]
-          log "[WARNING] #{message}"
-        else
-          raise ZbxError, message
+    private
+
+    def sanitized_options
+      LogSanitizer.sanitize(@settings.except(:logger, :upsert_lock)).tap do |safe|
+        safe[:uncertain_write_delays].freeze
+        %i[url proxy].each do |key|
+          safe[key] = LogSanitizer.sanitize_url(@settings[key]) if @settings[key]
         end
       end
-
-      # 进行用户鉴权，获取令牌
-      @auth_hash = auth
-      log "[DEBUG] Auth token: #{@auth_hash}"
     end
 
-    # 定义一个方法，用于将 Ruby 数据结构转换为 JSON 字符串，并根据条件添加令牌
-    def json_payload(body)
-      # 构建基本的 JSON 负载，包括方法名、参数、请求 ID 和 JSON-RPC 版本
-      payload        = {
-        method:  body[:method],
-        params:  body[:params],
-        id:      id,
-        jsonrpc: "2.0"
-      }
+    def build_logger
+      source = @settings[:logger]
+      return if source.nil? && @settings[:log_level].nil?
 
-      # 检查请求方法是否是 "apiinfo.version" 或 "user.login"，如果不是，则添加令牌信息
-      payload[:auth] = @auth_hash unless body[:method] == "apiinfo.version" || body[:method] == "user.login"
-
-      # 将构建好的负载转换为 JSON 字符串并返回
-      JSON(payload)
+      source ||= ActiveSupport::Logger.new($stderr)
+      ActiveSupport::TaggedLogging.new(source).tap do |logger|
+        logger.level = @settings[:log_level] if @settings.key?(:log_level)
+      end
+    rescue ArgumentError, TypeError
+      raise Invalid, "log_level must be a Ruby Logger severity", cause: nil
     end
 
-    # 实例化 Net::HTTP 对象，并发起 API 请求的方法
-    def http_request(body)
-      uri = URI.parse(@options[:url])
-
-      # 设置超时时间，默认为 60 秒
-      timeout = @options[:timeout].nil? ? 60 : @options[:timeout]
-      log "[DEBUG] Timeout for request set to #{timeout} seconds"
-
-      # 创建 Net::HTTP 对象，支持代理设置
-      http =
-        if @proxy_uri
-          Net::HTTP.Proxy(@proxy_host, @proxy_port, @proxy_user, @proxy_pass).new(uri.host, uri.port)
-        else
-          Net::HTTP.new(uri.host, uri.port)
-        end
+    def validate_request!(method, params)
+      unless method.is_a?(String) && method.match?(/\A[a-z][a-z0-9_]*\.[a-z][a-zA-Z0-9_]*\z/)
+        raise Invalid, "method must be a Zabbix API method name"
+      end
+      raise Invalid, "params must be a Hash or Array" unless params.is_a?(Hash) || params.is_a?(Array)
+    end
 
-      # 配置 HTTPS 请求
-      if uri.scheme == "https"
-        http.use_ssl     = true
-        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+    def request_message(method, params)
+      request_id = @id_mutex.synchronize { @next_id += 1 }
+      { method: method, params: params, id: request_id, jsonrpc: "2.0" }.tap do |message|
+        message[:auth] = @auth_token if @auth_token && authenticated_method?(method) && api_major_version < 7
       end
+    end
 
-      # 配置请求超时时间
-      http.open_timeout = timeout
-      http.read_timeout = timeout
+    def parse_response(body, request_id)
+      response = JSON.parse(body)
+      unless response.is_a?(Hash) && response["jsonrpc"] == "2.0" && response["id"] == request_id
+        raise ProtocolError, "Invalid JSON-RPC response envelope or request ID"
+      end
+      unless response.key?("result") ^ response.key?("error")
+        raise ProtocolError, "Invalid JSON-RPC response: expected exactly one result or error"
+      end
 
-      # 创建 POST 请求
-      request = Net::HTTP::Post.new(uri.request_uri)
+      raise_api_error(response) if response.key?("error")
+      response.fetch("result")
+    rescue JSON::ParserError, TypeError
+      raise ProtocolError, "Invalid JSON response", cause: nil
+    end
 
-      # 添加基本身份验证信息（如果提供了用户名和密码）
-      request.basic_auth(@options[:http_user], @options[:http_password]) if @options[:http_user]
+    def raise_api_error(response)
+      error = response["error"]
+      unless error.is_a?(Hash) && error["code"].is_a?(Integer) && error["message"].is_a?(String)
+        raise ProtocolError, "Invalid JSON-RPC error response"
+      end
 
-      # 设置请求头的 Content-Type 为 application/json-rpc
-      request.add_field("Content-Type", "application/json-rpc")
+      # 服务器文本可能回显任意请求值，包括宏及秘密。
+      safe_response = response.slice("jsonrpc", "id").merge("error" => error.slice("code"))
+      raise ApiError.new("Zabbix API error #{error.fetch("code")}", safe_response)
+    end
 
-      # 设置请求体为传入的 JSON 字符串
-      request.body = body
-      log "[DEBUG] HTTP request params: #{pretty_body(request.body)}"
+    def login
+      parameter = api_major_version >= 6 ? :username : :user
+      api_request(method: "user.login", params: { parameter => @settings[:username], password: @settings[:password] })
+    end
 
-      # 发起请求并获取响应
-      response = http.request(request)
+    def validate_api_version!
+      match = @api_version.is_a?(String) && @api_version.match(/\A(\d+)\.(\d+)\.(\d+)\z/)
+      raise ProtocolError, "Invalid API version response" unless match
+      return if SUPPORTED_MAJOR_VERSIONS.cover?(match[1].to_i)
+      raise ApiError, "Zabbix API version is not supported" unless @settings[:ignore_version]
 
-      # 检查响应状态码，如果不是 200，则抛出 HttpError 异常
-      raise HttpError.new("HTTP Error: #{response.code} on #{@options[:url]}", response) unless response.code == "200"
+      log(:warn, "version.unsupported", version: @api_version)
+    end
 
-      log "[DEBUG] HTTP response answer: #{pretty_body(response.body)}"
+    def validate_http_auth_compatibility!
+      return unless api_major_version >= 7 && @settings[:http_user]
 
-      # 返回响应体
-      response.body
+      raise Invalid, "HTTP Basic authentication cannot be combined with Zabbix 7 Bearer authentication"
     end
 
-    # 对 API 响应结果进行解析的方法
-    def _request(body)
-      # 发起 HTTP 请求并解析 JSON 格式的响应
-      result = JSON.parse(http_request(body))
+    def validate_token_transport!
+      return unless insecure_token_transport? && @settings[:allow_insecure_http] != true
 
-      # 如果响应结果中包含错误信息，则抛出 ZbxError 异常
-      if result["error"]
-        # 构建错误消息，包括服务器返回的错误信息和请求的详细信息
-        msg = <<~MOJO
+      raise Invalid, "api_token requires HTTPS unless allow_insecure_http is true"
+    end
 
-          ---------------------------------------------------------------
-          Server answer API error: #{JSON.pretty_unparse(result["error"])}
-            on request: #{pretty_body(body)}
-          ---------------------------------------------------------------
+    def insecure_token_transport?
+      @settings[:api_token] && @transport.uri.scheme == "http"
+    end
 
-        MOJO
+    def insecure_https?
+      @transport.uri.scheme == "https" && @settings[:verify_ssl] != true
+    end
 
-        # 抛出自定义异常 ZbxError，并传递错误消息和完整的响应结果
-        raise ZbxError.new(msg, result)
-      else
-        # 如果没有错误信息，则返回响应结果中的 "result" 部分
-        result["result"]
-      end
+    def api_major_version
+      @api_version.to_s.split(".", 2).first.to_i
     end
 
-    # 将 Ruby 数据结构美化成 JSON 字符串后打印输出的方法
-    def pretty_body(body)
-      # 解析 JSON 字符串
-      data = JSON.parse(body)
+    def bearer_token_for(method)
+      @auth_token if authenticated_method?(method) && api_major_version >= 7
+    end
 
-      # 如果参数中包含密码字段，则将密码字段的值替换为 "***"
-      if data["params"].is_a?(Hash) && data["params"].key?("password")
-        data["params"]["password"] = "***"
-      end
+    def authenticated_method?(method)
+      !UNAUTHENTICATED_METHODS.include?(method)
+    end
 
-      # 将美化后的数据转换为 JSON 字符串并返回
-      JSON.pretty_unparse(data)
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
-    # 通用的 API 调用发起方法
-    def api_request(body)
-      # 调用之前定义的 json_payload 方法，将请求信息转换为 JSON 字符串
-      _request json_payload(body)
+    def elapsed_ms(started_at)
+      ((monotonic_time - started_at) * 1000).round(2) if started_at
     end
   end
 end

data/lib/zabbix_manager/configuration.rb

@@ -0,0 +1,107 @@
+# 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)
+
+        @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]
+      return if logger.nil? || %i[debug info warn formatter formatter=].all? { |method| logger.respond_to?(method) }
+
+      raise Invalid, "logger must support the Ruby Logger interface"
+    end
+  end
+end