zabbix_manager 5.1.6 → 6.0.1

data/lib/zabbix_manager/classes/value_maps.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # 原生值映射资源；所属范围与映射规则由调用方提供。
+  class ValueMaps < Resource
+    # 返回 Zabbix API 中值映射对象的方法名前缀。
+    #
+    # @return [String] 值映射对象的方法名前缀
+    def method_name
+      "valuemap"
+    end
+
+    # 返回用于唯一识别值映射的业务字段名。
+    #
+    # @return [String] 值映射对象的业务标识字段名
+    def identify
+      "name"
+    end
+
+    # 5.4 起值映射属于主机或模板；旧版仍按全局名称定位。
+    # @return [Hash] 带版本边界的精确身份条件
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      identity = super(attributes)
+      if host_scoped?
+        raise Invalid, "hostid is required for a host-scoped value map" unless attributes.key?(:hostid)
+
+        identity[:hostid] = normalized_ids([attributes[:hostid]]).first
+      end
+      identity
+    end
+
+    # 名称查询始终经过完整身份检查，避免跨主机合法重名造成误选。
+    # @return [Integer, nil] 唯一值映射 ID
+    def get_id(data)
+      super(identity_filter(data))
+    end
+
+    # hostid 用于身份查询和创建，不能用于移动已有值映射。
+    # @return [Integer] 已确认的值映射 ID
+    def update(data)
+      attributes = data.deep_symbolize_keys
+      super(host_scoped? ? attributes.except(:hostid) : attributes)
+    end
+
+    private
+
+    def host_scoped?
+      Gem::Version.new(@client.api_version) >= Gem::Version.new("5.4")
+    end
+  end
+end

data/lib/zabbix_manager/client.rb

@@ -2,38 +2,45 @@
 
 require "json"
 require "logger"
+require "active_support"
+require "active_support/logger"
+require "active_support/tagged_logging"
 
 class ZabbixManager
+  # 持有一个已认证连接，管理 JSON-RPC 请求的完整生命周期。
   class Client
-    SUPPORTED_MAJOR_VERSIONS = (4..7).freeze
+    SUPPORTED_MAJOR_VERSIONS = (4..7)
     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
-
-    attr_reader :options, :sanitized_options, :logger
-
-    # 构建按服务端版本选择认证方式并复用 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
+    LOG_LEVELS = { debug: Logger::DEBUG, info: Logger::INFO, warn: Logger::WARN,
+                   error: Logger::ERROR, fatal: Logger::FATAL, unknown: Logger::UNKNOWN }.freeze
+    private_constant :LOG_LEVELS
+
+    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 }
-      validate_upsert_lock!
-      @transport = HttpTransport.new(@raw_options)
+      @transport = HttpTransport.new(@settings)
       validate_token_transport!
-      @api_version = api_version
+      @api_version = api_request(method: "apiinfo.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
+      @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
+
       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?
@@ -42,324 +49,200 @@ class ZabbixManager
       raise
     end
 
-    # 分配线程安全的 JSON-RPC 请求编号。
-    # @return [Integer]
-    # @api semipublic
-    def id
-      @id_mutex.synchronize { @next_id += 1 }
-    end
-
-    # 返回首次查询后缓存的远端 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
-      api_request(
-        method: "user.login",
-        params: {
-          login_parameter => username,
-          password: @raw_options[:password]
-        }
-      )
-    end
-
-    # 判断是否启用调试日志。
-    # @return [Boolean]
-    # @api semipublic
-    def debug?
-      @raw_options[:debug] == true
-    end
-
-    # 序列化 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
-
-    # 解析 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
-
-      parsed["result"]
-    rescue JSON::ParserError => e
-      raise ApiError, "Invalid JSON response: #{e.message}"
-    end
-
-    # 格式化请求摘要并隐藏全部参数值。
-    # @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)
+    # 执行一次请求，不重放失败或结果未确认的变更。
+    # @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: {})
+      method = method.dup.freeze if method.is_a?(String)
+      validate_request!(method, params)
       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))
+      message = request_message(method, params)
+      log(:debug, "request.started", method: method, request_id: message[:id])
+      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, request_id: message[:id], 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)
+    rescue StandardError => error
+      if started_at
+        log(:warn, "request.failed", method: method, request_id: message&.fetch(:id),
+                                     duration_ms: elapsed_ms(started_at), error: error.class.name)
+      end
       raise
     end
-    alias manager_request api_request
 
-    # 注销用户名会话并关闭持久连接；API 令牌无需远端注销。
-    # @return [Object] logout result
-    # @api public
+    # 注销密码认证会话；API token 仅需清理本地状态。
+    # 远端注销失败时仍清除本地认证令牌并关闭传输连接。
+    # @return [Boolean] 服务器注销结果；API token 模式返回 true
+    # @raise [ApiError, TransportError] 远端会话注销失败
     def logout
-      result = @credential_type == :user_session && @auth_token ? api_request(method: "user.logout", params: []) : true
-      result
+      @credential_type == :user_session && @auth_token ? api_request(method: "user.logout", params: []) : true
     ensure
       @auth_token = nil
       close
     end
 
-    # 关闭持久 HTTP 连接。
-    # @return [Object]
-    # @api public
+    # 关闭连接但不撤销凭据；后续请求按需重新连接。
+    # @return [true]
     def close
       @transport.close
     end
 
-    # 输出结构化且已脱敏的客户端事件。
-    # @return [void]
-    # @api semipublic
+    # 延迟构造日志元数据；日志失败不能改变远端写入结果。
+    # @param level [Symbol] Ruby Logger 日志级别方法
+    # @param event [String] 稳定的事件名称
+    # @param data [Hash] 序列化之前经过脱敏的元数据
+    # @return [Object, nil] 日志返回值；日志关闭或失败时返回 nil
     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(" "))
+      severity = LOG_LEVELS[level]
+      return if severity && @logger.respond_to?(:level) && @logger.level > severity
+
+      @logger.tagged("zabbix_manager") do
+        @logger.public_send(level) { JSON.generate(LogSanitizer.sanitize(data.merge(event: event))) }
+      end
+    rescue StandardError
+      nil
     end
 
-    # 返回不包含凭据的客户端摘要，避免对象检查时泄漏配置
-    # @return [String]
-    # @api public
+    # @return [String] 仅包含脱敏配置的诊断摘要
     def inspect
-      "#<#{self.class} options=#{@sanitized_options.inspect}>"
+      "#<#{self.class} options=#{@options.inspect}>"
     end
 
-    # 以业务键串行执行幂等写入，并可接入跨进程锁实现
-    # @return [Object] 代码块结果
-    # @api semipublic
+    # 应用层锁适配器可将本地串行化扩展到多个工作进程。
+    # 锁不可重入；调用方不能在块内再次获取 upsert 锁。
+    # @param key [String] 被保护操作的稳定、非秘密身份
+    # @yield 需要串行执行的读取、修改和写入操作
+    # @return [Object] 块的返回值
     def with_upsert_lock(key, &block)
-      mutex = @upsert_mutexes[key.hash % UPSERT_MUTEX_STRIPES]
-      mutex.synchronize do
-        coordinator = @raw_options[:upsert_lock]
+      @upsert_mutexes[key.hash % UPSERT_MUTEX_STRIPES].synchronize do
+        coordinator = @settings[: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
-
-        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)
+    def sanitized_options
+      LogSanitizer.sanitize(@settings.except(:logger, :upsert_lock)).tap do |safe|
+        safe[:uncertain_write_delays].freeze
         %i[url proxy].each do |key|
-          sanitized[key] = LogSanitizer.sanitize_url(options[key]) if options[key]
+          safe[key] = LogSanitizer.sanitize_url(@settings[key]) if @settings[key]
         end
-        sanitized
       end
+    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)
+    def build_logger
+      source = @settings[:logger]
+      return if source.nil? && @settings[:log_level].nil?
 
-        raise Invalid, "provide api_token or both username and password"
+      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
 
-      # 校验传输结果不确定时的只读回查退避窗口。
-      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"
+    def validate_request!(method, params)
+      valid_method = method.is_a?(String) && method.valid_encoding? && method.ascii_only? &&
+                     method.match?(/\A[a-z][a-z0-9_]*\.[a-z][a-zA-Z0-9_]*\z/)
+      unless valid_method
+        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
 
-      # 校验可选的跨进程幂等锁适配器。
-      # @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)"
+    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
 
-      # 校验服务端版本格式及支持范围。
-      # @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
-          raise ApiError, message
-        end
+    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
-
-      # 拒绝 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?
-
-        raise Invalid, "HTTP Basic authentication cannot be combined with Zabbix 7 Bearer authentication"
+      unless response.key?("result") ^ response.key?("error")
+        raise ProtocolError, "Invalid JSON-RPC response: expected exactly one result or error"
       end
 
-      # 默认阻止 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
+      raise_api_error(response) if response.key?("error")
+      response.fetch("result")
+    rescue JSON::ParserError, TypeError
+      raise ProtocolError, "Invalid JSON response", cause: nil
+    end
 
-        raise Invalid, "api_token requires HTTPS unless allow_insecure_http is true"
+    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
 
-      # 判断当前令牌连接是否使用明文 HTTP
-      # @return [Boolean]
-      # @api private
-      def insecure_token_transport?
-        @raw_options[:api_token].present? && @transport.uri.scheme == "http"
-      end
+      # 服务器文本可能回显任意请求值，包括宏及秘密。
+      safe_response = response.slice("jsonrpc", "id").merge("error" => error.slice("code"))
+      raise ApiError.new("Zabbix API error #{error.fetch("code")}", safe_response)
+    end
 
-      # 提取已缓存 API 版本的主版本号。
-      def api_major_version
-        @api_version.to_s.split(".", 2).first.to_i
-      end
+    def login
+      parameter = api_major_version >= 6 ? :username : :user
+      api_request(method: "user.login", params: { parameter => @settings[:username], password: @settings[:password] })
+    end
 
-      # 根据服务端版本选择登录用户名字段。
-      def login_parameter
-        api_major_version >= 6 ? :username : :user
-      end
+    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]
 
-      # 返回统一后的登录用户名。
-      def username
-        @raw_options[:username] || @raw_options[:user]
-      end
+      log(:warn, "version.unsupported", version: @api_version)
+    end
 
-      # 判断当前方法是否应在 JSON-RPC 请求体中携带认证值。
-      def body_authentication?(method)
-        authenticated_method?(method) && api_major_version < 7
-      end
+    def validate_http_auth_compatibility!
+      return unless api_major_version >= 7 && @settings[:http_user]
 
-      # 判断当前方法是否应使用 Bearer 认证头。
-      def bearer_token_for(method)
-        @auth_token if authenticated_method?(method) && api_major_version >= 7
-      end
+      raise Invalid, "HTTP Basic authentication cannot be combined with Zabbix 7 Bearer authentication"
+    end
 
-      # 排除版本查询和登录方法，判断请求是否需要认证。
-      def authenticated_method?(method)
-        !UNAUTHENTICATED_METHODS.include?(method.to_s)
-      end
+    def validate_token_transport!
+      return unless insecure_token_transport? && @settings[:allow_insecure_http] != true
 
-      # 同时读取符号键和字符串键的请求字段。
-      def fetch_body_value(body, key)
-        body[key] || body[key.to_s]
-      end
+      raise Invalid, "api_token requires HTTPS unless allow_insecure_http is true"
+    end
 
-      # 使用脱敏响应和请求摘要构造 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 insecure_token_transport?
+      @settings[:api_token] && @transport.uri.scheme == "http"
+    end
 
-      # 优先使用调用方日志器，调试模式下才创建默认日志器。
-      def build_logger
-        return @raw_options[:logger] if @raw_options[:logger]
-        return unless debug?
+    def insecure_https?
+      @transport.uri.scheme == "https" && @settings[:verify_ssl] != true
+    end
 
-        Logger.new($stdout).tap { |value| value.level = Logger::DEBUG }
-      end
+    def api_major_version
+      @api_version.to_s.split(".", 2).first.to_i
+    end
 
-      # 判断 HTTPS 是否按项目要求关闭证书校验。
-      def insecure_https?
-        @transport.uri.scheme == "https" && @raw_options[:verify_ssl] != true
-      end
+    def bearer_token_for(method)
+      @auth_token if authenticated_method?(method) && api_major_version >= 7
+    end
 
-      # 读取不受系统时间校准影响的单调时钟。
-      def monotonic_time
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
+    def authenticated_method?(method)
+      !UNAUTHENTICATED_METHODS.include?(method)
+    end
 
-      # 计算并格式化请求耗时毫秒数。
-      def elapsed_ms(started_at)
-        ((monotonic_time - started_at) * 1_000).round(1)
-      end
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def elapsed_ms(started_at)
+      ((monotonic_time - started_at) * 1000).round(2) if started_at
+    end
   end
 end