zabbix_manager 5.1.6 → 6.0.0

data/lib/zabbix_manager/basic/basic_alias.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-class ZabbixManager
-  class Basic
-    # 按标识字段从 Zabbix API 获取对象完整数据。
-    #
-    # @param data [Hash] 包含对象标识字段及其值
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Hash] 对象完整数据
-    def get(data)
-      get_full_data(data)
-    end
-
-    # 通过 Zabbix API 创建对象。
-    #
-    # @param data [Hash] 待创建的对象属性
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Integer] 创建单个对象时返回对象 ID
-    # @return [Boolean] 创建多个对象时返回操作结果
-    def add(data)
-      create(data)
-    end
-
-    # 通过 Zabbix API 删除对象。
-    #
-    # @param data [Hash] 包含对象标识字段及其值
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Integer] 删除单个对象时返回对象 ID
-    # @return [Boolean] 删除多个对象时返回操作结果
-    def destroy(data)
-      delete(data)
-    end
-
-    # 返回子类对应的 Zabbix API 方法名；由具体资源类实现。
-    #
-    # @return [String, nil] API 方法名
-    def method_name; end
-  end
-end

data/lib/zabbix_manager/basic/basic_func.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-class ZabbixManager
-  class Basic
-    # 将调试信息交给客户端结构化日志，并移除可能包含请求参数的片段。
-    #
-    # @param message [String] 待记录的调试信息
-    # @return [void]
-    def log(message)
-      return unless @client.options[:debug]
-
-      raw_message = message.to_s
-      safe_message = if raw_message.start_with?("[DEBUG]")
-                       raw_message[/\A\[DEBUG\]\s+Call\s+[a-z_]+/i] || "[DEBUG] domain operation"
-                     else
-                       raw_message
-                     end
-      @client.log(:debug, "domain.operation", message: safe_message)
-    end
-
-    # 比较实际哈希是否包含期望哈希中的全部键值。
-    #
-    # @param first_hash [Hash] 实际数据
-    # @param second_hash [Hash] 期望数据
-    # @return [Boolean] 是否匹配
-    def hash_equals?(first_hash, second_hash)
-      actual = normalize_hash(first_hash)
-      expected = normalize_hash(second_hash)
-      actual.slice(*expected.keys) == expected
-    end
-
-    # 将哈希值递归规范为字符串，并忽略 hostid。
-    #
-    # @param hash [Hash] 待规范化的哈希
-    # @return [Hash] 规范化后的副本
-    def normalize_hash(hash)
-      hash.deep_symbolize_keys.except(:hostid).deep_transform_values(&:to_s)
-    end
-
-    # 从 API 结果中解析单个对象 ID，或透传布尔结果。
-    #
-    # @param data [Hash, Boolean] API 返回结果
-    # @return [Integer, Boolean, nil] 对象 ID、布尔结果或空值
-    def parse_keys(data)
-      case data
-      when Hash
-        data.empty? ? nil : data[keys][0].to_i
-      when TrueClass
-        true
-      when FalseClass
-        false
-      end
-    end
-  end
-end

data/lib/zabbix_manager/basic/basic_init.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-class ZabbixManager
-  class Basic
-    # 使用 ZabbixManager 客户端初始化基础资源对象。
-    #
-    # @param client [ZabbixManager::Client] API 客户端
-    # @return [ZabbixManager::Basic] 基础资源对象
-    def initialize(client)
-      @client = client
-    end
-
-    # 定义资源对应的 API 方法名占位，要求子类覆盖。
-    #
-    # @raise [ApiError] 基础类不能直接提供方法名时抛出
-    # @return [String] API 方法名
-    def method_name
-      raise Invalid, "Can't call method_name here"
-    end
-
-    # 返回资源创建时使用的默认选项，子类可按需覆盖。
-    #
-    # @return [Hash] 默认选项
-    def default_options
-      {}
-    end
-
-    # 根据单数 ID 字段名生成 API 返回结果中的复数字段名。
-    #
-    # @return [String] 复数 ID 字段名
-    def keys
-      "#{key}s"
-    end
-
-    # 根据 API 方法名生成对象 ID 字段名。
-    #
-    # @return [String] 对象 ID 字段名
-    def key
-      "#{method_name}id"
-    end
-
-    # 定义资源业务标识字段占位，要求子类覆盖。
-    #
-    # @raise [ApiError] 基础类不能直接提供标识字段时抛出
-    # @return [String] 业务标识字段名
-    def identify
-      raise Invalid, "Can't call identify here"
-    end
-  end
-end

data/lib/zabbix_manager/basic/basic_logic.rb

@@ -1,239 +0,0 @@
-# frozen_string_literal: true
-
-class ZabbixManager
-  class Basic
-    # 合并默认选项后通过 Zabbix API 创建对象。
-    #
-    # @param data [Hash] 待创建的对象属性
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Integer] 创建单个对象时返回对象 ID
-    # @return [Boolean] 创建多个对象时返回操作结果
-    def create(data)
-      log "[DEBUG] Call create with parameters: #{data.inspect}"
-
-      # 判断是否绑定默认选项并重新生成配置
-      data_with_default = default_options.empty? ? data : default_options.merge(data)
-      data_create       = [data_with_default]
-
-      # 调用实例方法
-      result = @client.api_request(method: "#{method_name}.create", params: data_create)
-      # 判断是否执行成功并返回结果
-      parse_keys result
-    end
-
-    # 通过 Zabbix API 删除对象。
-    #
-    # @param data [Hash] 包含待删除对象的 ID 字段和值
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Integer] 删除单个对象时返回对象 ID
-    # @return [Boolean] 删除多个对象时返回操作结果
-    def delete(data)
-      log "[DEBUG] Call delete with parameters: #{data.inspect}"
-
-      data_delete = [data]
-      result      = @client.api_request(method: "#{method_name}.delete", params: data_delete)
-      parse_keys result
-    end
-
-    # 按业务标识查找对象，存在则更新，否则创建。
-    #
-    # @param data [Hash] 包含对象业务标识及待写入属性
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Integer] 创建或更新后的对象 ID
-    # @return [Boolean] 批量操作时返回操作结果
-    def create_or_update(data)
-      log "[DEBUG] Call create_or_update with parameters: #{data.inspect}"
-
-      id = get_id(**identity_filter(data))
-      id ? update(data.merge(key.to_sym => id)) : create(data)
-    end
-
-    # 在属性发生变化或强制更新时通过 Zabbix API 更新对象。
-    #
-    # @param data [Hash] 包含对象 ID 及待更新属性
-    # @param force [Boolean] 属性一致时是否仍强制更新
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Integer] 更新后的对象 ID
-    # @return [Boolean] 批量操作时返回操作结果
-    def update(data, force = false)
-      log "[DEBUG] Call update with parameters: #{data.inspect}"
-      dump = {}
-      dump_by_id(key.to_sym => data[key.to_sym]).each do |item|
-        dump = item.deep_symbolize_keys if item[key].to_i == data[key.to_sym].to_i
-      end
-      if hash_equals?(dump, data) && !force
-        log "[DEBUG] Equal keys #{dump} and #{data}, skip update"
-        data[key.to_sym].to_i
-      else
-        data_update = [data]
-        result      = @client.api_request(method: "#{method_name}.update", params: data_update)
-        parse_keys result
-      end
-    end
-
-    # 按业务标识从 Zabbix API 获取对象扩展数据。
-    #
-    # @param data [Hash] 包含对象业务标识字段及其值
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Hash] 对象扩展数据
-    def get_full_data(data)
-      log "[DEBUG] Call get_full_data with parameters: #{data.inspect}"
-
-      @client.api_request(
-        method: "#{method_name}.get",
-        params: {
-          filter: {
-            identify.to_sym => data[identify.to_sym]
-          },
-          output: "extend"
-        }
-      )
-    end
-
-    # 将调用方参数直接传给对应的 Zabbix get 方法。
-    #
-    # @param data [Hash] 原始查询参数
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Hash] API 返回数据
-    def get_raw(data)
-      log "[DEBUG] Call get_raw with parameters: #{data.inspect}"
-
-      @client.api_request(
-        method: "#{method_name}.get",
-        params: data
-      )
-    end
-
-    # 按对象 ID 字段从 Zabbix API 获取扩展数据。
-    #
-    # @param data [Hash] 包含对象 ID 字段及其值
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Hash] 对象扩展数据
-    def dump_by_id(data)
-      log "[DEBUG] Call dump_by_id with parameters: #{data.inspect}"
-
-      @client.api_request(
-        method: "#{method_name}.get",
-        params: {
-          filter: {
-            key.to_sym => data[key.to_sym]
-          },
-          output: "extend"
-        }
-      )
-    end
-
-    # 获取当前资源的全部对象，并返回业务标识到 ID 的映射。
-    #
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Hash] 业务标识到对象 ID 的映射
-    def all
-      result = {}
-      @client.api_request(
-        method: "#{method_name}.get",
-        params: { output: "extend" }
-      ).each do |item|
-        result[item[identify]] = item[key]
-      end
-      result
-    end
-
-    # 按业务标识精确查询对象 ID，并拒绝歧义结果。
-    #
-    # @param data [Hash] 业务标识过滤条件
-    # @raise [ApiError] API 调用失败、缺少标识字段或结果不唯一时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Integer, nil] Zabbix 对象 ID，未找到时返回空值
-    def get_id(data)
-      log "[DEBUG] Call get_id with parameters: #{data.inspect}"
-
-      data = data.deep_symbolize_keys
-      # 缺少业务标识字段时立即终止查询
-      name = data[identify.to_sym]
-      raise Invalid, "#{identify} not supplied in call to get_id" if name.nil?
-
-      result = @client.api_request(
-        method: "#{method_name}.get",
-        params: {
-          filter: data,
-          output: [key, identify]
-        }
-      )
-      matches = result.select { |item| item[identify].to_s == name.to_s }
-      raise Conflict, "multiple #{method_name} objects match #{identify}=#{name}" if matches.length > 1
-
-      matches.first&.fetch(key, nil)&.to_i
-    end
-
-    # 按业务标识获取对象，不存在时创建。
-    #
-    # @param data [Hash] 包含对象业务标识及待创建属性
-    # @raise [ApiError] Zabbix API 调用失败时抛出
-    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
-    # @return [Integer] Zabbix 对象 ID
-    def get_or_create(data)
-      log "[DEBUG] Call get_or_create with parameters: #{data.inspect}"
-
-      unless (id = get_id(**identity_filter(data)))
-        id = create(data)
-      end
-      id
-    end
-
-    # 提取通用获取或写入操作使用的远端业务标识。
-    #
-    # @param data [Hash] 对象属性
-    # @return [Hash] 业务标识过滤条件
-    def identity_filter(data)
-      attributes = data.deep_symbolize_keys
-      { identify.to_sym => attributes.fetch(identify.to_sym) }
-    end
-
-    # 使用原始参数直接创建 Zabbix 对象。
-    #
-    # @param data [Hash, Array] 原始创建参数
-    # @return [Object] API 返回结果
-    def create_raw(data)
-      log "[DEBUG] Call create_raw with parameters: #{data.inspect}"
-      # 请求创建数据
-      @client.api_request(
-        method: "#{method_name}.create",
-        params: data
-      )
-    end
-
-    # 使用原始参数直接更新 Zabbix 对象。
-    #
-    # @param data [Hash, Array] 原始更新参数
-    # @return [Object] API 返回结果
-    def update_raw(data)
-      log "[DEBUG] Call update_raw with parameters: #{data.inspect}"
-      # 请求创建数据
-      @client.api_request(
-        method: "#{method_name}.update",
-        params: data
-      )
-    end
-
-    # 使用原始参数直接删除 Zabbix 对象。
-    #
-    # @param data [Hash, Array] 原始删除参数
-    # @return [Object] API 返回结果
-    def delete_raw(data)
-      log "[DEBUG] Call delete_raw with parameters: #{data.inspect}"
-      # 请求创建数据
-      @client.api_request(
-        method: "#{method_name}.delete",
-        params: data
-      )
-    end
-  end
-end

data/lib/zabbix_manager/classes/hostinterfaces.rb

@@ -1,189 +0,0 @@
-# frozen_string_literal: true
-
-class ZabbixManager
-  # 封装高频使用的 Zabbix 主机接口查询与幂等更新。
-  class HostInterfaces < Basic
-    # 返回对应的 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
-
-    # 幂等创建或更新一个主机的接口集合。
-    # @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 = Array(interfaceids).filter_map { |value| value.to_s.strip.presence }.uniq
-      raise Invalid, "interfaceids are required" if ids.empty?
-
-      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)
-      Array(result.fetch("interfaceids")).map(&:to_i)
-    end
-
-    private
-
-      # 预先校验并生成仅供当前对象执行的接口变更计划。
-      def plan_for_host(hostid:, interfaces:)
-        desired = validate(interfaces)
-        existing = for_host(hostid)
-        desired.map { |attributes| [attributes, matching_interface(existing, attributes)] }
-      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)
-        interface.deep_symbolize_keys
-      end
-
-      # 校验新接口的通用字段及 SNMP 条件字段。
-      def validate_create_definition!(attributes)
-        attributes[:ip] = "" unless attributes.key?(:ip)
-        attributes[:dns] = "" unless attributes.key?(:dns)
-        interface_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 = Integer(details[:version])
-        raise Invalid, "SNMP interface version must be 1, 2, or 3" unless [1, 2, 3].include?(version)
-        if [1, 2].include?(version) && details[:community].blank?
-          raise Invalid, "SNMP v1/v2 interface community is required"
-        end
-
-        attributes[:details] = details
-      rescue ArgumentError, TypeError
-        raise Invalid, "SNMP interface version must be 1, 2, or 3"
-      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")
-        @client.api_request(
-          method: "hostinterface.update",
-          params: attributes.except(:hostid).merge(interfaceid: interfaceid)
-        )
-        interfaceid.to_i
-      end
-
-      # 为目标主机创建缺失接口。
-      # @return [Integer]
-      # @api private
-      def create_interface(hostid, attributes)
-        validate_create_definition!(attributes)
-        result = @client.api_request(
-          method: "hostinterface.create",
-          params: attributes.except(:interfaceid).merge(hostid: hostid)
-        )
-        result.fetch("interfaceids").first.to_i
-      end
-  end
-end

data/lib/zabbix_manager/classes/usergroups.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-class ZabbixManager
-  class Usergroups < Basic
-    # 返回 Zabbix API 中用户组对象的方法名前缀。
-    #
-    # @return [String] 用户组对象的方法名前缀
-    def method_name
-      "usergroup"
-    end
-
-    # 返回用户组对象的主键字段名。
-    #
-    # @return [String] 用户组对象的主键字段名
-    def key
-      "usrgrpid"
-    end
-
-    # 返回用于唯一识别用户组的业务字段名。
-    #
-    # @return [String] 用户组对象的业务标识字段名
-    def identify
-      "name"
-    end
-
-    # 更新用户组对主机组的访问权限。
-    #
-    # @param data [Hash] 包含 usrgrpid、hostgroupids 及可选 permission
-    # @raise [ApiError] Zabbix API 返回业务错误时抛出
-    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
-    # @return [Integer, nil] 已更新用户组的 ID
-    def permissions(data)
-      permission = data[:permission] || 2
-      result = @client.api_request(
-        method: "usergroup.update",
-        params: {
-          usrgrpid: data[:usrgrpid],
-          rights: data[:hostgroupids].map { |t| { permission: permission, id: t } }
-        }
-      )
-      result ? result["usrgrpids"][0].to_i : nil
-    end
-
-    # 将用户加入用户组；兼容旧调用并委托给 update_users。
-    #
-    # @deprecated Zabbix 已移除 massAdd，请使用 update_users。
-    # @param data [Hash] 包含 userids 和 usrgrpids
-    # @raise [ApiError] Zabbix API 返回业务错误时抛出
-    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
-    # @return [Integer, nil] 已更新用户组的 ID
-    def add_user(data)
-      update_users(data)
-    end
-
-    # 批量替换指定用户组中的用户列表。
-    #
-    # @param data [Hash] 包含 userids 和 usrgrpids
-    # @raise [ApiError] Zabbix API 返回业务错误时抛出
-    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
-    # @return [Integer, nil] 首个已更新用户组的 ID
-    def update_users(data)
-      user_groups = data[:usrgrpids].map do |t|
-        {
-          usrgrpid: t,
-          userids: data[:userids]
-        }
-      end
-      result = @client.api_request(
-        method: "usergroup.update",
-        params: user_groups
-      )
-      result ? result["usrgrpids"][0].to_i : nil
-    end
-  end
-end