zabbix_manager 5.1.6 → 6.0.0

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

data/lib/zabbix_manager/classes/hosts.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Hosts < Basic
+  # 主机身份解析、状态对账与模板关联；技术名称和显示名称分别处理。
+  class Hosts < Resource
     # 返回主机对应的 Zabbix API 模块名。
     def method_name
       "host"
@@ -22,7 +23,6 @@ class ZabbixManager
 
     # 按主机 ID 查询完整主机及接口、群组和模板。
     def dump_by_id(data)
-      log "[DEBUG] Call dump_by_id with parameters: #{data.inspect}"
       @client.api_request(
         method: "host.get",
         params: {
@@ -35,16 +35,25 @@ class ZabbixManager
       )
     end
 
-    # 从指定主机批量解除模板关联。
-    def unlink_templates(data)
-      result = @client.api_request(
-        method: "host.massRemove",
-        params: {
-          hostids: data[:hosts_id],
-          templateids: data[:templates_id]
-        }
-      )
-      !result.empty?
+    # 向指定主机追加模板关联，保留现有模板。
+    # @return [Array<Integer>] 已更新主机 ID
+    def link_templates(host_ids:, template_ids:)
+      write_templates("massadd", host_ids, template_ids)
+    end
+
+    # 完整替换指定主机的模板关联，空模板集合明确清除全部关联。
+    # @return [Array<Integer>] 已更新主机 ID
+    def replace_templates(host_ids:, template_ids:)
+      write_templates("massupdate", host_ids, template_ids, allow_empty: true)
+    end
+
+    # 从指定主机解除选定模板的关联，保留模板生成的实体。
+    # @return [Array<Integer>] 已更新主机 ID
+    def unlink_templates(host_ids:, template_ids:)
+      ids = normalized_ids(host_ids)
+      templates = normalized_ids(template_ids)
+      result = @client.api_request(method: "host.massremove", params: { hostids: ids, templateids: templates })
+      response_ids(result, expected: ids)
     end
 
     # 使用显式群组和接口创建主机，不注入隐藏凭据。
@@ -52,7 +61,7 @@ class ZabbixManager
       attributes = default_options.merge(data.deep_symbolize_keys)
       validate_create_attributes!(attributes)
       result = @client.api_request(method: "host.create", params: attributes)
-      first_id(result, "hostids")
+      response_id(result)
     end
 
     # 规范化并校验设备定义，不执行远端查询或写入。
@@ -62,7 +71,7 @@ class ZabbixManager
       attributes = data.deep_symbolize_keys
       raise Invalid, "host is required" if attributes[:host].blank?
 
-      hostinterfaces.validate(attributes[:interfaces]) if attributes.key?(:interfaces)
+      host_interfaces.validate(attributes[:interfaces]) if attributes.key?(:interfaces)
       attributes
     end
 
@@ -90,19 +99,19 @@ class ZabbixManager
       attributes = attributes.dup
 
       interfaces = Array.wrap(attributes.delete(:interfaces))
-      hostinterfaces.validate(interfaces)
+      host_interfaces.validate(interfaces)
       update_attributes = attributes.merge(hostid: hostid)
-      @client.api_request(method: "host.update", params: update_attributes)
-      hostinterfaces.reconcile_for_host(hostid: hostid, interfaces: interfaces) if interfaces.any?
-      hostid.to_i
+      host_interfaces.reconcile_for_host(hostid: hostid, interfaces: interfaces) if interfaces.any?
+      result = @client.api_request(method: "host.update", params: update_attributes)
+      response_id(result, expected: [hostid])
     end
 
     # 查询指定主机的全部接口。
     def interfaces_for(hostid)
-      hostinterfaces.for_host(hostid)
+      host_interfaces.for_host(hostid)
     end
 
-    # 返回主机的第一个接口 ID；高频业务应优先使用 hostinterfaces。
+    # 返回主机的第一个接口 ID；高频业务应优先使用 host_interfaces。
     def get_interface_id(hostid)
       interfaces_for(hostid).first&.fetch("interfaceid", nil)
     end
@@ -139,95 +148,132 @@ class ZabbixManager
       find_host_by_filter(hostid: hostid)
     end
 
+    # 解析供流量查询和监控表达式使用的唯一主机；只执行读取。
+    # 显式 ID 与技术名必须同时匹配，候选名称不能分别指向不同主机。
+    # @param reference [String, Array<String>, Hash] 名称/IP/DNS 候选，或同时包含 hostid 和 host 的 Hash
+    # @return [Hash] 符号键主机属性，包含 hostid 和技术名 host
+    # @raise [Invalid] 本地主机引用无效
+    # @raise [ApiError] 主机不存在或当前 API 用户不可见
+    # @raise [Conflict] 候选不唯一，或 ID 与技术名不匹配
+    # @raise [ProtocolError] API 返回无效的主机身份
+    def resolve(reference)
+      if reference.is_a?(Hash)
+        expected = Monitoring::Validation.hash!(reference, "host")
+        Monitoring::Validation.host!(expected)
+        found = find_by_id(expected[:hostid])
+      else
+        candidates = Array.wrap(reference).map do |candidate|
+          Monitoring::Validation.text!(candidate, "host candidate").strip
+        end
+        raise Invalid, "host candidates are required" if candidates.empty?
+
+        found = find_by_candidates(candidates.uniq)
+      end
+      raise ApiError, "Zabbix host was not found for the supplied reference" unless found
+
+      resolved = resolved_host(found)
+      if expected && (resolved[:hostid].to_s != expected[:hostid].to_s || resolved[:host] != expected[:host])
+        raise Conflict, "hostid and technical host name do not refer to the same Zabbix host"
+      end
+
+      resolved
+    end
+
     # 批量启用或停用主机。
     # @return [Array<Integer>]
     def set_status(hostids, enabled:)
-      ids = Array(hostids).filter_map { |value| value.to_s.strip.presence }.uniq
-      raise Invalid, "hostids are required" if ids.empty?
+      validate_boolean!(enabled, "enabled")
+      ids = normalized_ids(hostids)
 
       params = ids.map { |hostid| { hostid: hostid, status: enabled ? 0 : 1 } }
       result = @client.api_request(method: "host.update", params: params)
-      Array(result.fetch("hostids")).map(&:to_i)
-    end
-
-    # 把可见名称对应的主机更新为稳定技术标识。
-    def update_host_to_serial(data)
-      attributes = data.deep_symbolize_keys
-      hostid = get_hostid_by_name(attributes[:name])
-      return nil unless hostid
-
-      attributes.delete(:templates)
-      @client.api_request(method: "host.update", params: attributes.merge(hostid: hostid))
-      hostid.to_i
+      response_ids(result, expected: ids)
     end
 
     private
 
-      # 校验创建主机所需的技术名、群组和接口。
-      def validate_create_attributes!(attributes)
-        raise Invalid, "host is required" if attributes[:host].blank?
-        raise Invalid, "groups are required when creating a host" if Array.wrap(attributes[:groups]).empty?
-        raise Invalid, "interfaces are required when creating a host" if Array.wrap(attributes[:interfaces]).empty?
+    # 远端身份损坏是协议错误，不能当作调用方输入错误或不存在处理。
+    def resolved_host(found)
+      resolved = Monitoring::Validation.hash!(found, "Zabbix host")
+      Monitoring::Validation.host!(resolved)
+      resolved
+    rescue Invalid
+      raise ProtocolError, "invalid host response: hostid and technical host are required", cause: nil
+    end
 
-        attributes[:interfaces] = hostinterfaces.validate_for_create(attributes[:interfaces])
-      end
+    def write_templates(operation, host_ids, template_ids, allow_empty: false)
+      ids = normalized_ids(host_ids)
+      templates = normalized_ids(template_ids, allow_empty: allow_empty)
+      result = @client.api_request(
+        method: "host.#{operation}",
+        params: {
+          hosts: ids.map { |id| { hostid: id } },
+          templates: templates.map { |id| { templateid: id } }
+        }
+      )
+      response_ids(result, expected: ids)
+    end
 
-      # 使用精确过滤查询唯一主机。
-      def find_host_by_filter(filter)
-        result = @client.api_request(
-          method: "host.get",
-          params: {
-            output: %w[hostid host name status],
-            filter: filter,
-            selectInterfaces: %w[interfaceid ip dns]
-          }
-        )
-        raise Conflict, "host lookup is ambiguous for #{filter.inspect}" if result.length > 1
+    # 校验创建主机所需的技术名、群组和接口。
+    def validate_create_attributes!(attributes)
+      raise Invalid, "host is required" if attributes[:host].blank?
+      raise Invalid, "groups are required when creating a host" if Array.wrap(attributes[:groups]).empty?
+      raise Invalid, "interfaces are required when creating a host" if Array.wrap(attributes[:interfaces]).empty?
 
-        result.first
-      end
+      attributes[:interfaces] = host_interfaces.validate_for_create(attributes[:interfaces])
+    end
 
-      # 按 IP 和 DNS 端点查询唯一主机接口。
-      def find_interface_by_endpoint(candidate)
-        matches = []
-        %i[ip dns].each do |field|
-          result = @client.api_request(
-            method: "hostinterface.get",
-            params: { filter: { field => candidate }, output: ["hostid"] }
-          )
-          matches.concat(result)
-        end
-        matches.uniq! { |interface| interface.fetch("hostid") }
-        raise Conflict, "interface endpoint #{candidate} belongs to multiple hosts" if matches.length > 1
+    # 使用精确过滤查询唯一主机。
+    def find_host_by_filter(filter)
+      result = @client.api_request(
+        method: "host.get",
+        params: {
+          output: %w[hostid host name status],
+          filter: filter,
+          selectInterfaces: %w[interfaceid ip dns]
+        }
+      )
+      raise Conflict, "host lookup is ambiguous for #{filter.inspect}" if result.length > 1
 
-        matches.first
-      end
+      response_identifier(result.first["hostid"]) if result.first
+      result.first
+    end
 
-      # 只查询唯一主机 ID。
-      def find_host_id(filter)
+    # 按 IP 和 DNS 端点查询唯一主机接口。
+    def find_interface_by_endpoint(candidate)
+      matches = []
+      %i[ip dns].each do |field|
         result = @client.api_request(
-          method: "host.get",
-          params: {
-            output: ["hostid"],
-            filter: filter
-          }
+          method: "hostinterface.get",
+          params: { filter: { field => candidate }, output: ["hostid"] }
         )
-        raise Conflict, "host lookup is ambiguous for #{filter.inspect}" if result.length > 1
-
-        result.first&.fetch("hostid", nil)
+        matches.concat(result)
       end
+      matches.uniq! { |interface| interface.fetch("hostid") }
+      raise Conflict, "interface endpoint #{candidate} belongs to multiple hosts" if matches.length > 1
 
-      # 从 Zabbix 创建响应中提取首个整数 ID。
-      def first_id(result, key_name)
-        value = result.fetch(key_name).first
-        value && value.to_i
-      end
+      matches.first
+    end
 
-      # 延迟构建接口模块并复用当前客户端。
-      # @return [HostInterfaces]
-      # @api private
-      def hostinterfaces
-        @hostinterfaces ||= HostInterfaces.new(@client)
-      end
+    # 只查询唯一主机 ID。
+    def find_host_id(filter)
+      result = @client.api_request(
+        method: "host.get",
+        params: {
+          output: ["hostid"],
+          filter: filter
+        }
+      )
+      raise Conflict, "host lookup is ambiguous for #{filter.inspect}" if result.length > 1
+
+      response_identifier(result.first["hostid"]).to_s if result.first
+    end
+
+    # 延迟构建接口模块并复用当前客户端。
+    # @return [HostInterfaces]
+    # @api private
+    def host_interfaces
+      @host_interfaces ||= HostInterfaces.new(@client)
+    end
   end
 end

data/lib/zabbix_manager/classes/{httptests.rb → http_tests.rb}

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class HttpTests < Basic
+  # Web 场景以 hostid + name 定位；步骤定义及执行凭据由调用方提供。
+  class HttpTests < Resource
     # 返回 Web 场景对象对应的 Zabbix API 方法前缀。
     #
     # @return [String]
@@ -9,13 +10,6 @@ class ZabbixManager
       "httptest"
     end
 
-    # 返回 Web 场景用于业务识别的字段名。
-    #
-    # @return [String]
-    def identify
-      "name"
-    end
-
     # 返回创建 Web 场景时使用的默认步骤列表。
     #
     # @return [Hash] Web 场景默认属性