zabbix_manager 5.1.6 → 6.0.1

data/lib/zabbix_manager/resource.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # 共享资源身份、精确查询和单对象写入行为。
+  # 子类声明 API 前缀、身份和回执字段；原生透传仍由调用方负责授权及版本适配。
+  # 回执校验只确认响应中的 ID，不提供事务、跨进程排他或失败后的自动重放。
+  class Resource
+    # @param client [ZabbixManager::Client] 共享客户端
+    def initialize(client)
+      @client = client
+    end
+
+    # @return [String] Zabbix API 模块名
+    def method_name
+      raise Invalid, "resource API method is not defined"
+    end
+
+    # @return [String] 业务标识字段
+    def identify
+      "name"
+    end
+
+    # @return [String] 对象 ID 字段
+    def key
+      "#{method_name}id"
+    end
+
+    # @return [String] 写入响应的 ID 集合字段
+    def keys
+      "#{key}s"
+    end
+
+    # @return [Hash] 创建默认属性
+    def default_options
+      {}
+    end
+
+    # 合并创建默认属性，不修改调用方输入。
+    # @param data [Hash] 对应资源的原生 API 属性
+    # @return [Integer] 创建对象的 ID
+    # @raise [ProtocolError] 响应没有确认唯一的有效 ID
+    def create(data)
+      response_id(create_raw([default_options.merge(data.deep_symbolize_keys)]))
+    end
+
+    # 删除明确指定的对象 ID。
+    # 此操作不可撤销；批量回执必须确认所有请求 ID。
+    # @param ids [Integer, String, Array<Integer, String>] 一个或多个正整数 ID
+    # @return [Integer] 首个删除对象的 ID
+    def delete(ids)
+      requested = normalized_ids(ids)
+      response_ids(delete_raw(requested), expected: requested).first
+    end
+
+    # 按稳定业务身份创建或更新一个对象。
+    # 通用 CRUD 不提供跨进程原子性；监控业务使用对应的 reconcile/upsert 方法。
+    # @param data [Hash] 包含 identify 字段的原生属性
+    # @return [Integer]
+    def create_or_update(data)
+      attributes = data.deep_symbolize_keys
+      id = get_id(**identity_filter(attributes))
+      id ? update(attributes.merge(key.to_sym => id)) : create(attributes)
+    end
+
+    # 仅在请求属性有变化时更新；无条件写入使用 update_raw。
+    # @param data [Hash] 包含资源 ID 的原生属性，省略字段不参与比较
+    # @return [Integer]
+    # @raise [ProtocolError] 写入回执未确认请求 ID
+    def update(data)
+      attributes = data.deep_symbolize_keys
+      id = attributes[key.to_sym]
+      raise Invalid, "#{key} is required" if id.blank?
+
+      normalized_ids([id])
+
+      current = response_objects(dump_by_id(key.to_sym => id)).find do |item|
+        response_identifier(item[key]) == id.to_i
+      end
+      return id.to_i if current && attributes_match?(current, attributes)
+
+      response_id(update_raw([attributes]), expected: [id])
+    end
+
+    # 按业务标识查询完整对象。
+    # @param data [Hash] 包含 identify 指定的业务标识
+    # @return [Array<Hash>]
+    def get_full_data(data)
+      response_objects(get_raw(filter: identity_filter(data), output: "extend"))
+    end
+
+    # 按对象 ID 查询完整对象。
+    # @param data [Hash] 包含 key 指定的 ID 字段
+    # @return [Array<Hash>]
+    def dump_by_id(data)
+      attributes = data.deep_symbolize_keys
+      id = attributes[key.to_sym]
+      raise Invalid, "#{key} is required" if id.blank?
+
+      response_objects(get_raw(filter: { key.to_sym => id }, output: "extend"))
+    end
+
+    # @return [Hash] 业务标识到原生字符串 ID 的映射
+    # @raise [Conflict] 多个资源具有相同业务标识
+    def all
+      response_objects(get_raw(output: "extend")).each_with_object({}) do |item, result|
+        response_identifier(item[key])
+        raise ProtocolError, "invalid #{method_name} response: #{identify} is missing" unless item.key?(identify)
+
+        name = item.fetch(identify)
+        raise Conflict, "multiple #{method_name} objects share the same identity" if result.key?(name)
+
+        result[name] = item.fetch(key)
+      end
+    end
+
+    # 精确查找唯一资源，空结果返回 nil，多个结果拒绝任意选择。
+    # @param data [Hash] 包含 identify 字段的精确过滤条件
+    # @return [Integer, nil]
+    def get_id(data)
+      attributes = data.deep_symbolize_keys
+      name = attributes[identify.to_sym]
+      raise Invalid, "#{identify} not supplied in call to get_id" if name.nil?
+
+      rows = response_objects(get_raw(filter: attributes, output: [key, identify]))
+      rows.each do |item|
+        response_identifier(item[key])
+        raise ProtocolError, "invalid #{method_name} response: #{identify} is missing" unless item.key?(identify)
+      end
+      matches = rows.select do |item|
+        item[identify].to_s == name.to_s
+      end
+      raise Conflict, "multiple #{method_name} objects match the requested identity" if matches.length > 1
+
+      response_identifier(matches.first[key]) if matches.first
+    end
+
+    # 查找或创建单个对象，不隐含更新已有对象。
+    # @param data [Hash] 创建属性及 identify 指定的业务标识
+    # @return [Integer] 已存在或新创建对象的 ID
+    def get_or_create(data)
+      get_id(**identity_filter(data)) || create(data)
+    end
+
+    # @return [Hash] 精确查询条件，复合身份由资源类覆盖
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      { identify.to_sym => attributes.fetch(identify.to_sym) }
+    end
+
+    # @param data [Hash] 原生 *.get 参数；调用方负责授权和资源边界
+    # @return [Object] 原始查询响应
+    def get_raw(data)
+      @client.api_request(method: "#{method_name}.get", params: data)
+    end
+
+    # @param data [Hash, Array<Hash>] 原生 *.create 参数，不执行高层业务校验
+    # @return [Object] 原始创建响应，调用方负责核对回执
+    def create_raw(data)
+      @client.api_request(method: "#{method_name}.create", params: data)
+    end
+
+    # @param data [Hash, Array<Hash>] 原生 *.update 参数，不执行高层业务校验
+    # @return [Object] 原始更新响应，调用方负责核对回执
+    def update_raw(data)
+      @client.api_request(method: "#{method_name}.update", params: data)
+    end
+
+    # @param data [Array<Integer, String>] 原生 *.delete ID 集合
+    # @return [Object] 原始删除响应，调用方负责核对回执
+    def delete_raw(data)
+      @client.api_request(method: "#{method_name}.delete", params: data)
+    end
+
+    private
+
+    # 高层查询必须区分空结果与损坏的响应；原生 get_raw 保持透传。
+    def response_objects(result)
+      unless result.is_a?(Array) && result.all? { |object| object.is_a?(Hash) }
+        raise ProtocolError, "invalid #{method_name} response: expected an array of objects"
+      end
+
+      result
+    end
+
+    # 单对象查询边界不能接受 ID 集合、布尔值或浮点数。
+    def positive_id_attribute(value, name)
+      id = integer_attribute(value, name)
+      raise Invalid, "#{name} must be a positive integer" unless id.positive?
+
+      id
+    end
+
+    def validate_boolean!(value, name)
+      raise Invalid, "#{name} must be true or false" unless value == true || value == false
+    end
+
+    def integer_attribute(value, name)
+      unless value.is_a?(Integer) || (value.is_a?(String) && value.match?(/\A[+-]?\d+\z/))
+        raise Invalid, "#{name} must be an integer"
+      end
+
+      value.is_a?(Integer) ? value : Integer(value, 10)
+    end
+
+    def normalized_ids(values, allow_empty: false)
+      ids = Array.wrap(values).map do |value|
+        id = integer_attribute(value, keys)
+        raise Invalid, "#{keys} must be positive integers" unless id.positive?
+
+        id.to_s
+      end.uniq
+      raise Invalid, "#{keys} are required" if ids.empty? && !allow_empty
+
+      ids
+    end
+
+    # API 数字字符串可与整数比较，nil 和布尔值保留各自语义。
+    def normalized_attributes(attributes)
+      attributes.deep_symbolize_keys.deep_transform_values do |value|
+        value.is_a?(Numeric) ? value.to_s : value
+      end
+    end
+
+    def attributes_match?(current, desired)
+      actual = normalized_attributes(current)
+      expected = normalized_attributes(desired)
+      actual.slice(*expected.keys) == expected
+    end
+
+    def response_identifier(value, id_field = key)
+      unless value.is_a?(Integer) || (value.is_a?(String) && value.match?(/\A[0-9]+\z/))
+        raise ProtocolError, "invalid #{method_name} response: #{id_field} must be a positive integer"
+      end
+
+      id = value.to_i
+      raise ProtocolError, "invalid #{method_name} response: #{id_field} must be positive" unless id.positive?
+
+      id
+    end
+
+    def response_ids(result, id_field = keys, expected: nil)
+      values = result[id_field] if result.is_a?(Hash)
+      unless values.is_a?(Array) && values.any?
+        raise ProtocolError, "invalid #{method_name} response: #{id_field} must be a nonempty array"
+      end
+
+      ids = values.map { |value| response_identifier(value, id_field) }
+      if ids.uniq != ids || (expected && ids.sort != expected.map { |id| response_identifier(id) }.sort)
+        raise ProtocolError, "invalid #{method_name} response: #{id_field} do not confirm the requested objects"
+      end
+
+      ids
+    end
+
+    def response_id(result, id_field = keys, expected: nil)
+      ids = response_ids(result, id_field, expected: expected)
+      raise ProtocolError, "invalid #{method_name} response: expected one #{key}" unless ids.one?
+
+      ids.first
+    end
+  end
+end

data/lib/zabbix_manager/traffic.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+class ZabbixManager
+  # 通过官方 API 读取有界流量序列；历史样本与小时趋势始终明确区分。
+  class Traffic
+    DEFAULT_LIMIT = 12_000
+    DEFAULT_MAX_POINTS = 720
+    DECIMAL = /\A[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?\z/
+
+    # @param manager [ZabbixManager] 共享连接及资源对象的管理器
+    def initialize(manager)
+      @manager = manager
+    end
+
+    # 返回每个请求监控项的序列，包括不可见、不支持和无数据的状态。
+    # 时段两端均包含；Time 按秒取整。数值保留 Integer 或 BigDecimal 精度。
+    # points 包含 clock/ns/count/value/min/max；压缩后时间指向桶内最后一条记录。
+    # current_value 为已返回记录中最新值（趋势为小时均值）；截断趋势不保证包含最新小时。
+    # @param hostid [Integer, String] 所属主机 ID
+    # @param itemids [Array<Integer, String>] 需要查询的监控项 ID
+    # @param time_from [Time, Integer] 起始时间或 Unix 秒
+    # @param time_till [Time, Integer] 结束时间或 Unix 秒
+    # @param source [Symbol] :history 原始样本，或 :trends 小时统计
+    # @param limit [Integer] 每项最多保留的 API 记录数，额外查询一条用于识别截断
+    # @param max_points [Integer] 每项最多返回的图表点数
+    # @return [Hash] 查询范围、来源及包含状态、统计和 points 的 series 数组
+    # @raise [Invalid] 标识、时间范围或数量无效
+    # @raise [ProtocolError] 响应形状、归属或样本数值无效
+    # @raise [ApiError, TransportError] 官方 API 查询失败；不会转换为空序列
+    def series(hostid:, itemids:, time_from:, time_till:, source: :history,
+               limit: DEFAULT_LIMIT, max_points: DEFAULT_MAX_POINTS)
+      hostid = identifier!(hostid, "hostid")
+      ids = item_ids!(itemids)
+      options = query_options(time_from, time_till, source, limit, max_points)
+      items = items_for_host(hostid, ids)
+      results = ids.map { |id| item_series(id, items[id], options) }
+      { hostid: hostid, **options.slice(:time_from, :time_till, :source), series: results }
+    end
+
+    # 精确发现接口入/出方向的 bps 监控项，再读取相同时间范围的序列。
+    # @param host [String, Array<String>, Hash] 主机候选名或明确的 hostid + host
+    # @param interface_name [String] 接口名称，复用现有方向及单位校验
+    # @param time_from [Time, Integer] 起始时间或 Unix 秒
+    # @param time_till [Time, Integer] 结束时间或 Unix 秒
+    # @param source [Symbol] :history 或 :trends
+    # @param limit [Integer] 每项 API 记录上限
+    # @param max_points [Integer] 每项图表点上限
+    # @return [Hash] series 结果，附带 host、interface_name 和各项 direction
+    # @raise [Invalid, Conflict] 接口输入、bps 语义或主机/监控项身份无法确认
+    # @raise [ApiError, TransportError] 主机、监控项或采样查询失败
+    def for_interface(host:, interface_name:, time_from:, time_till:, source: :history,
+                      limit: DEFAULT_LIMIT, max_points: DEFAULT_MAX_POINTS)
+      Monitoring::Validation.text!(interface_name, "interface_name")
+      query_options(time_from, time_till, source, limit, max_points)
+      resolved = @manager.hosts.resolve(host)
+      candidates = @manager.items.monitored_traffic_candidates(resolved.fetch(:hostid))
+      response_rows!(candidates, "item.get")
+      traffic = Monitoring::TrafficItems.new(candidates).for_interface(interface_name)
+      directions = traffic.to_h { |direction, item| [item.fetch(:itemid).to_s, direction] }
+      result = series(hostid: resolved.fetch(:hostid), itemids: directions.keys,
+                      time_from: time_from, time_till: time_till, source: source, limit: limit, max_points: max_points)
+      result[:series].each do |item|
+        if item[:status] != :unavailable && item[:units] != "bps"
+          raise Conflict, "interface traffic units changed after bps discovery"
+        end
+
+        item[:direction] = directions.fetch(item[:itemid])
+      end
+      result.merge(host: resolved.fetch(:host), interface_name: interface_name)
+    end
+
+    private
+
+    def identifier!(value, name)
+      Monitoring::Validation.positive_id!(value, name).to_s
+    end
+
+    def item_ids!(values)
+      raise Invalid, "itemids must be a nonempty array" unless values.is_a?(Array) && values.any?
+
+      values.map { |value| identifier!(value, "itemid") }.uniq
+    end
+
+    def query_options(time_from, time_till, source, limit, max_points)
+      time_from = epoch!(time_from, "time_from")
+      time_till = epoch!(time_till, "time_till")
+      raise Invalid, "time_till must not precede time_from" if time_till < time_from
+      raise Invalid, "source must be :history or :trends" unless %i[history trends].include?(source)
+
+      { time_from: time_from, time_till: time_till, source: source,
+        limit: positive_integer!(limit, "limit"), max_points: positive_integer!(max_points, "max_points") }
+    end
+
+    def epoch!(value, name)
+      value = value.to_i if value.is_a?(Time)
+      raise Invalid, "#{name} must be Time or nonnegative Unix seconds" unless value.is_a?(Integer) && value >= 0
+
+      value
+    end
+
+    def positive_integer!(value, name)
+      raise Invalid, "#{name} must be a positive integer" unless value.is_a?(Integer) && value.positive?
+
+      value
+    end
+
+    # 显式主机过滤和响应归属检查保证外部 itemid 不能越过查询边界。
+    def items_for_host(hostid, ids)
+      requested_ids = ids.to_h { |id| [id, true] }
+      rows = @manager.query(method: "item.get", params: {
+                              hostids: [hostid], itemids: ids, monitored: true,
+                              output: %w[itemid hostid name units value_type]
+                            })
+      response_rows!(rows, "item.get").each_with_object({}) do |item, result|
+        id = response_integer!(item["itemid"], "itemid", positive: true).to_s
+        owner = response_integer!(item["hostid"], "hostid", positive: true).to_s
+        unless requested_ids.key?(id) && owner == hostid && !result.key?(id)
+          raise ProtocolError, "item.get returned unexpected or duplicate item ownership"
+        end
+        unless item["name"].is_a?(String) && item["units"].is_a?(String)
+          raise ProtocolError, "item.get returned invalid name or units"
+        end
+
+        result[id] = { itemid: id, name: item["name"], units: item["units"],
+                       value_type: response_integer!(item["value_type"], "value_type") }
+      end
+    end
+
+    def item_series(id, metadata, options)
+      result = { itemid: id, name: nil, units: nil, value_type: nil, status: :unavailable,
+                 truncated: false, record_count: 0, sample_count: 0,
+                 current_value: nil, peak_value: nil, points: [] }
+      return result unless metadata
+
+      result.merge!(metadata)
+      return result.merge(status: :unsupported) unless [0, 3].include?(metadata[:value_type])
+
+      points = read_points(metadata, options)
+      truncated = points.length > options[:limit]
+      points = points.sort_by { |point| [point[:clock], point[:ns]] }.last(options[:limit])
+      result.merge(status: points.empty? ? :empty : :ok, truncated: truncated,
+                   record_count: points.length, sample_count: points.sum { |point| point[:count] },
+                   current_value: points.last&.fetch(:value), peak_value: points.map { |point| point[:max] }.max,
+                   points: reduce_points(points, options[:max_points]))
+    end
+
+    def read_points(item, options)
+      history = options[:source] == :history
+      method = history ? "history.get" : "trend.get"
+      params = options.slice(:time_from, :time_till).merge(itemids: [item[:itemid]], limit: options[:limit] + 1)
+      if history
+        params.merge!(history: item[:value_type], output: %w[itemid clock ns value],
+                      sortfield: %w[clock ns], sortorder: "DESC")
+      else
+        # trend.get 没有排序参数；截断的趋势集合不承诺覆盖整段或包含最新小时。
+        params[:output] = %w[itemid clock num value_min value_avg value_max]
+      end
+      rows = response_rows!(@manager.query(method: method, params: params), method)
+      raise ProtocolError, "#{method} exceeded the requested record limit" if rows.length > params[:limit]
+
+      points = rows.map { |row| parse_point(row, item, options) }
+      identities = points.map { |point| [point[:clock], point[:ns]] }
+      raise ProtocolError, "#{method} returned duplicate sample timestamps" unless identities.uniq == identities
+
+      points
+    end
+
+    def parse_point(row, item, options)
+      id = response_integer!(row["itemid"], "itemid", positive: true).to_s
+      clock = response_integer!(row["clock"], "clock")
+      unless id == item[:itemid] && clock.between?(options[:time_from], options[:time_till])
+        raise ProtocolError, "traffic sample is outside the requested item or time range"
+      end
+
+      if options[:source] == :history
+        ns = response_integer!(row["ns"], "ns")
+        raise ProtocolError, "history.get returned invalid nanoseconds" unless ns < 1_000_000_000
+
+        value = item[:value_type] == 3 ? response_integer!(row["value"], "value") : decimal!(row["value"])
+        { clock: clock, ns: ns, count: 1, value: value, min: value, max: value }
+      else
+        count = response_integer!(row["num"], "num", positive: true)
+        minimum, average, maximum = %w[value_min value_avg value_max].map { |field| decimal!(row[field]) }
+        unless minimum <= average && average <= maximum && (item[:value_type] != 3 || minimum >= 0)
+          raise ProtocolError, "trend.get returned inconsistent numeric statistics"
+        end
+
+        { clock: clock, ns: 0, count: count, value: average, min: minimum, max: maximum }
+      end
+    end
+
+    def response_rows!(rows, method)
+      unless rows.is_a?(Array) && rows.all? { |row| row.is_a?(Hash) }
+        raise ProtocolError, "#{method} must return an array of objects"
+      end
+
+      rows
+    end
+
+    def response_integer!(value, field, positive: false)
+      unless value.is_a?(Integer) || (value.is_a?(String) && value.match?(/\A\d+\z/))
+        raise ProtocolError, "traffic response #{field} must be an integer"
+      end
+
+      integer = value.to_i
+      if integer.negative? || (positive && integer.zero?)
+        raise ProtocolError, "traffic response #{field} is outside its valid range"
+      end
+
+      integer
+    end
+
+    def decimal!(value)
+      unless (value.is_a?(String) || value.is_a?(Numeric)) && DECIMAL.match?(value.to_s)
+        raise ProtocolError, "traffic response value must be a finite decimal"
+      end
+
+      number = BigDecimal(value.to_s)
+      raise ProtocolError, "traffic response value must be finite" unless number.finite?
+
+      number
+    end
+
+    # 合并只影响展示密度；保留样本权重和极值，clock/ns 标示桶内最后一条记录。
+    def reduce_points(points, max_points)
+      return points if points.length <= max_points
+
+      size = (points.length.to_f / max_points).ceil
+      points.each_slice(size).map do |bucket|
+        count = bucket.sum { |point| point[:count] }
+        total = bucket.sum { |point| BigDecimal(point[:value].to_s) * point[:count] }
+        { clock: bucket.last[:clock], ns: bucket.last[:ns], count: count, value: total / count,
+          min: bucket.map { |point| point[:min] }.min, max: bucket.map { |point| point[:max] }.max }
+      end
+    end
+  end
+end

data/lib/zabbix_manager/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  VERSION = "5.1.6"
+  VERSION = "6.0.1"
 end