zabbix_manager 5.1.5 → 6.0.0

data/lib/zabbix_manager/classes/graphs.rb

@@ -1,23 +1,25 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Graphs < Basic
-    # 用于通过 Zabbix API 与 Graphs 交互的方法名称
+  # 图形以 hostid + name 查询；写入所有者由 gitems 中的监控项确定。
+  class Graphs < Resource
+    # 返回图形对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "graph"
     end
 
-    # 用于通过 Zabbix API 标识特定 Graph 对象的 id 字段名称
-    def identify
-      "name"
-    end
-
-    # 从 Zabbix API 获取完整/扩展的 Graph 数据
+    # 按名称搜索并获取图形的完整数据。
+    #
+    # @param data [Hash] 包含图形识别字段及其值的查询条件
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Array<Hash>] 匹配的图形完整数据
     def get_full_data(data)
-      log "[DEBUG] 使用参数调用 get_full_data: #{data.inspect}"
-
-      get_raw(
-        {
+      @client.api_request(
+        method: "#{method_name}.get",
+        params: {
           search: {
             identify.to_sym => data[identify.to_sym]
           },
@@ -26,10 +28,16 @@ class ZabbixManager
       )
     end
 
-    # 从 Zabbix API 获取主机的 Graph ids
+    # 获取指定主机的图形 ID，并可按名称片段进一步过滤。
+    #
+    # @param data [Hash] 包含 host，且可包含 filter 的查询条件
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Array] 匹配的图形 ID 列表
     def get_ids_by_host(data)
-      result = get_raw(
-        {
+      result = @client.api_request(
+        method: "graph.get",
+        params: {
           filter: {
             host: data[:host]
           },
@@ -38,45 +46,48 @@ class ZabbixManager
       )
 
       result.filter_map do |graph|
-        graphid = graph["graphid"]
-        name    = graph["name"]
-        filter  = data[:filter]
+        num = graph["graphid"]
+        name = graph["name"]
+        filter = data[:filter]
 
-        graphid if filter.nil? || name.match?(/#{filter}/)
+        num if filter.nil? || name.include?(filter.to_s)
       end
     end
 
-    # 通过 Zabbix API 获取 Graph Item 对象
+    # 获取指定图形包含的图形监控项。
+    #
+    # @param data [Hash, String, Integer] 图形 ID
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Array<Hash>] 图形监控项数据
     def get_items(data)
       @client.api_request(
         method: "graphitem.get",
         params: {
           graphids: [data],
-          output:   "extend"
+          output: "extend"
         }
       )
     end
 
-    # 通过 Zabbix API 获取或创建 Graph 对象
-    def get_or_create(data)
-      log "[DEBUG] 使用参数调用 get_or_create: #{data.inspect}"
-
-      unless (id = get_id(name: data[:name], templateid: data[:templateid]))
-        id = create(data)
-      end
-
-      id
+    # 生成由图形名称和所属主机或模板构成的稳定查询条件。
+    # graph.templateid 是继承源图形 ID，不是所属模板 ID。
+    # @param data [Hash] 包含 name 和 hostid 的图形属性
+    # @return [Hash] 图形唯一查询条件
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      { name: attributes.fetch(:name), hostid: attributes.fetch(:hostid) }
     end
 
-    # 通过 Zabbix API 创建或更新 Graph 对象
-    def create_or_update(data)
-      graphid = get_id(name: data[:name], templateid: data[:templateid])
-      graphid ? _update(data.merge(graphid: graphid)) : create(data)
+    # 图形所有者由 gitems 确定，hostid 仅用于调用方的身份查询。
+    # @return [Integer, nil]
+    def create(data)
+      super(data.deep_symbolize_keys.except(:hostid))
     end
 
-    def _update(data)
-      data.delete(:name)
-      update(data)
+    # @return [Integer, nil] 更新的图形 ID
+    def update(data)
+      super(data.deep_symbolize_keys.except(:hostid))
     end
   end
 end

data/lib/zabbix_manager/classes/host_groups.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # 主机群组名称解析与按需创建；批量创建按顺序执行，不是远端事务。
+  class HostGroups < Resource
+    # 返回主机群组对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
+    def method_name
+      "hostgroup"
+    end
+
+    # 返回主机群组的 Zabbix ID 字段名。
+    #
+    # @return [String]
+    def key
+      "groupid"
+    end
+
+    # 批量解析主机群组名称并返回对应的群组 ID。
+    # @param data [Array<String>, String] 待查询的群组名称
+    # @return [Array<Hash>, nil] 群组 ID 列表，未命中时返回 nil
+    def get_hostgroup_ids(data)
+      names = normalized_names(data)
+      return nil if names.empty?
+
+      groups = @client.api_request(
+        method: "hostgroup.get",
+        params: {
+          output: %w[groupid name],
+          filter: { name: names }
+        }
+      )
+
+      groups.empty? ? nil : groups.map { |group| { groupid: group.fetch("groupid") } }
+    end
+
+    # 批量查询并创建缺失的主机群组，避免逐名称重复查询。
+    # @param data [Array<String>, String] 待确保存在的群组名称
+    # @return [Array<Hash>] 群组 ID 列表
+    def get_or_create_host_groups(data)
+      names = normalized_names(data)
+      existing = @client.api_request(
+        method: "hostgroup.get",
+        params: { output: %w[groupid name], filter: { name: names } }
+      ).index_by { |group| group.fetch("name") }
+
+      names.map do |name|
+        group = existing[name]
+        next({ groupid: response_identifier(group["groupid"]).to_s }) if group
+
+        result = @client.api_request(method: "hostgroup.create", params: { name: name })
+        { groupid: response_id(result).to_s }
+      end
+    end
+
+    # 清理、去空并去重主机群组名称。
+    # @param data [Array<String>, String] 原始群组名称
+    # @return [Array<String>] 规范化后的群组名称
+    private def normalized_names(data)
+      Array(data).filter_map { |name| name.to_s.strip.presence }.uniq
+    end
+  end
+end

data/lib/zabbix_manager/classes/host_interfaces.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # 封装高频使用的 Zabbix 主机接口查询与幂等更新。
+  class HostInterfaces < Resource
+    # 返回对应的 Zabbix API 模块名。
+    # @return [String]
+    def method_name
+      "hostinterface"
+    end
+
+    # 返回接口对象的主键字段。
+    # @return [String]
+    def key
+      "interfaceid"
+    end
+
+    # 使用接口 ID 作为通用查询标识。
+    # @return [String]
+    def identify
+      "interfaceid"
+    end
+
+    # 查询指定主机的全部接口，可选择同时返回关联监控项。
+    # @return [Array<Hash>]
+    def for_host(hostid, select_items: nil)
+      raise Invalid, "hostid is required" if hostid.blank?
+
+      params = { hostids: hostid, output: "extend" }
+      params[:selectItems] = select_items if select_items
+      @client.api_request(method: "hostinterface.get", params: params)
+    end
+
+    # 规范化并校验接口定义，不执行远端查询或写入。
+    # @return [Array<Hash>]
+    def validate(interfaces)
+      desired = Array.wrap(interfaces).map { |interface| normalize_definition(interface) }
+      validate_definitions!(desired)
+      desired
+    end
+
+    # 校验 host.create 中全部接口的创建必填合同。
+    # @return [Array<Hash>]
+    def validate_for_create(interfaces)
+      validate(interfaces).each { |attributes| validate_create_definition!(attributes) }
+    end
+
+    # 只读取并校验接口归属和创建必填字段，供多资源编排在首个写入前预检。
+    # @param hostid [Integer, String] 目标主机 ID
+    # @param interfaces [Array<Hash>] 期望接口定义
+    # @return [Array<Hash>] 已验证的接口属性；执行时仍需重新核实远端状态
+    def validate_for_host(hostid:, interfaces:)
+      plan_for_host(hostid: hostid, interfaces: interfaces).map(&:first)
+    end
+
+    # 幂等创建或更新一个主机的接口集合。
+    # @return [Array<Integer>]
+    def reconcile_for_host(hostid:, interfaces:)
+      @client.with_upsert_lock("host-interfaces:#{hostid}") do
+        plan = plan_for_host(hostid: hostid, interfaces: interfaces)
+        apply_plan(hostid: hostid, plan: plan)
+      end
+    end
+
+    # 删除明确指定的主机接口；关联监控项由 Zabbix 按官方规则处理。
+    # @return [Array<Integer>]
+    def delete_many(hostid:, interfaceids:)
+      ids = normalized_ids(interfaceids)
+
+      owned_ids = for_host(hostid).map { |interface| interface.fetch("interfaceid").to_s }
+      foreign_ids = ids - owned_ids
+      raise Conflict, "interfaces do not belong to host #{hostid}: #{foreign_ids.join(", ")}" if foreign_ids.any?
+
+      result = @client.api_request(method: "hostinterface.delete", params: ids)
+      response_ids(result, expected: ids)
+    end
+
+    private
+
+    # 预先校验并生成仅供当前对象执行的接口变更计划。
+    def plan_for_host(hostid:, interfaces:)
+      desired = validate(interfaces)
+      existing = for_host(hostid)
+      plans = desired.map do |attributes|
+        current = matching_interface(existing, attributes)
+        response_identifier(current["interfaceid"]) if current
+        validate_create_definition!(attributes) unless current
+        [attributes, current]
+      end
+      targets = plans.filter_map { |_attributes, current| current && response_identifier(current["interfaceid"]) }
+      raise Invalid, "duplicate resolved interface target" unless targets.uniq == targets
+
+      plans
+    end
+
+    # 执行内部生成的接口变更计划，避免调用方伪造跨主机接口 ID。
+    def apply_plan(hostid:, plan:)
+      plan.map do |attributes, current|
+        current ? update_interface(attributes, current) : create_interface(hostid, attributes)
+      end
+    end
+
+    # 把接口字段递归转换为统一符号键。
+    def normalize_definition(interface)
+      raise Invalid, "interface must be a hash" unless interface.is_a?(Hash)
+
+      attributes = interface.deep_symbolize_keys
+      if attributes.key?(:type)
+        type = integer_attribute(attributes[:type], "interface type")
+        raise Invalid, "interface type must be 1, 2, 3, or 4" unless [1, 2, 3, 4].include?(type)
+      end
+      %i[main useip].each do |field|
+        next unless attributes.key?(field)
+
+        unless [0, 1].include?(integer_attribute(attributes[field], "interface #{field}"))
+          raise Invalid, "interface #{field} must be 0 or 1"
+        end
+      end
+      %i[ip dns].each do |field|
+        if attributes.key?(field) && !attributes[field].is_a?(String)
+          raise Invalid, "interface #{field} must be a string"
+        end
+      end
+      validate_port!(attributes[:port]) if attributes.key?(:port)
+      details = attributes[:details]
+      if attributes.key?(:details) && !details.is_a?(Hash)
+        raise Invalid, "interface details must be a hash"
+      end
+
+      validate_supplied_snmp_details!(details) if details
+      attributes
+    end
+
+    def validate_supplied_snmp_details!(details)
+      validate_snmp_version!(details[:version]) if details.key?(:version)
+      %i[community securityname authpassphrase privpassphrase contextname].each do |field|
+        if details.key?(field) && !details[field].is_a?(String)
+          raise Invalid, "SNMP #{field} must be a string"
+        end
+      end
+      { bulk: [0, 1], securitylevel: [0, 1, 2] }.each do |field, allowed|
+        next unless details.key?(field)
+
+        unless allowed.include?(integer_attribute(details[field], "SNMP #{field}"))
+          raise Invalid, "SNMP #{field} is invalid"
+        end
+      end
+    end
+
+    def validate_port!(value)
+      text = value.to_s
+      numeric = (value.is_a?(String) || value.is_a?(Integer)) && text.match?(/\A[1-9]\d*\z/)
+      macro = value.is_a?(String) && text.match?(/\A\{\$[^{}\r\n]+\}\z/)
+      return if macro || (numeric && value.to_i <= 65_535)
+
+      raise Invalid, "interface port must be between 1 and 65535 or a user macro"
+    end
+
+    # 校验新接口的通用字段及 SNMP 条件字段。
+    def validate_create_definition!(attributes)
+      raise Invalid, "new interfaces cannot reference an existing interfaceid" if attributes.key?(:interfaceid)
+
+      attributes[:ip] = "" unless attributes.key?(:ip)
+      attributes[:dns] = "" unless attributes.key?(:dns)
+      endpoint_identity(attributes)
+      validate_snmp_details!(attributes) if attributes[:type].to_i == 2
+    end
+
+    # 校验 SNMP 版本和 v1/v2c community 必填合同。
+    def validate_snmp_details!(attributes)
+      details = attributes[:details]&.deep_symbolize_keys
+      raise Invalid, "SNMP interface details are required" unless details
+
+      version = validate_snmp_version!(details[:version])
+      if [1, 2].include?(version) && details[:community].blank?
+        raise Invalid, "SNMP v1/v2 interface community is required"
+      end
+
+      attributes[:details] = details
+    end
+
+    def validate_snmp_version!(value)
+      version = integer_attribute(value, "SNMP interface version")
+      raise Invalid, "SNMP interface version must be 1, 2, or 3" unless [1, 2, 3].include?(version)
+
+      version
+    end
+
+    # 校验期望接口是否包含重复身份。
+    # @return [void]
+    # @api private
+    def validate_definitions!(interfaces)
+      identities = interfaces.map { |interface| interface_identity(interface) }
+      duplicate = identities.tally.find { |_identity, count| count > 1 }&.first
+      raise Invalid, "duplicate desired interface identity #{duplicate}" if duplicate
+    end
+
+    # 按显式 ID 或稳定端点身份匹配已有接口。
+    # @return [Hash, nil]
+    # @api private
+    def matching_interface(existing, attributes)
+      if attributes[:interfaceid]
+        match = existing.find { |item| item["interfaceid"].to_s == attributes[:interfaceid].to_s }
+        raise Invalid, "interfaceid #{attributes[:interfaceid]} does not belong to this host" unless match
+
+        return match
+      end
+
+      candidates = existing.select { |item| endpoint_identity(item) == endpoint_identity(attributes) }
+      raise Conflict, "interface identity is ambiguous; provide interfaceid" if candidates.length > 1
+
+      candidates.first
+    end
+
+    # 生成不依赖数组顺序的接口身份。
+    # @return [String]
+    # @api private
+    def interface_identity(attributes)
+      values = attributes.with_indifferent_access
+      return "id:#{values[:interfaceid]}" if values[:interfaceid].present?
+
+      endpoint_identity(values)
+    end
+
+    # 使用类型、端点和端口匹配接口，不把可变的 main 或远端 ID 作为端点身份。
+    def endpoint_identity(attributes)
+      values = attributes.with_indifferent_access
+
+      %i[type main useip port].each do |field|
+        raise Invalid, "interface #{field} is required" if values[field].blank?
+      end
+      endpoint_field = values[:useip].to_i == 1 ? :ip : :dns
+      raise Invalid, "interface #{endpoint_field} is required" if values[endpoint_field].blank?
+
+      "endpoint:#{values[:type]}:#{values[:useip]}:#{values[endpoint_field]}:#{values[:port]}"
+    end
+
+    # 更新已属于目标主机的接口。
+    # @return [Integer]
+    # @api private
+    def update_interface(attributes, current)
+      interfaceid = current.fetch("interfaceid")
+      result = @client.api_request(
+        method: "hostinterface.update",
+        params: attributes.except(:hostid).merge(interfaceid: interfaceid)
+      )
+      response_id(result, expected: [interfaceid])
+    end
+
+    # 为目标主机创建缺失接口。
+    # @return [Integer]
+    # @api private
+    def create_interface(hostid, attributes)
+      result = @client.api_request(
+        method: "hostinterface.create",
+        params: attributes.except(:interfaceid).merge(hostid: hostid)
+      )
+      response_id(result)
+    end
+  end
+end