zabbix_manager 5.1.5 → 5.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72554dfff6fd4d60ac8be48bc766c9367e4b07f9fa2e3df7500cb21b49a6b033
-  data.tar.gz: 01bea1ff565779f4ce5dab0b9a53d1832e80f9581b58dcc2e9bc943e83da9a46
+  metadata.gz: 37c70888e6fd6b0e27a4945f2672d460243584724c67eed4eadc4d69b88d6ad7
+  data.tar.gz: 6975d3b02322a81fe8923503e58b91f1888de4ec324f30846552305931fe6a59
 SHA512:
-  metadata.gz: 28bfea0b7a7bd6d99d394a0168a3399275af50fe139609141d03a996e6f488f484e8601529a58bf8710c492edd401514d66771e3b1411a53500898a05e8b6974
-  data.tar.gz: a25a5c306cffa53d2b601c6f281e5ab5afbfb72fd8cef106683668f7d4b907b047b5d4ab76fcc2aa1e62b9df979ba5129628443c53601effe0de95facb69dd90
+  metadata.gz: 875b98496cffef36b128f8038f007c8d9a0a9bdb6635c14df0380545ef495903970c73ffca1cb26105a3e382d14e88517308edd81b11b57d5be64e30e0b6f486
+  data.tar.gz: 9d2d60aa041e3e993b4c8aaf9c900570824a997537dca1f0fc34a88dbc7f2dd7286d86adc2ecda40e04b2ac0393fa9279cbbb2a29b65c92dab1a92463984d833

data/CHANGELOG.md

@@ -1,11 +1,27 @@
 # CHANGELOG
 
-## 5.1.1
-* 新增基类查询方法：
-  * get_key_ids_by_identify：基于监控对象索引键(#{identify})查询 { "#{key}": id }；
-  * get_key_ids：基于监控对象索引建"#{identify}"查询 { "#{key}": id }；
-  * get_or_create_keys：批量创建或更新监控对象并返回 [{ "#{key}": id }];
-* 优化 Client 对象实例化逻辑：
-  * 增加入参检查：必须提供 url、user和password，以及 @id 缓存；
-  * 优化 debug 模式，接口请求入参和出参打印，均使用 JSON.pretty_unparse(data) 美化；
-* 完善项目注释，项目注释覆盖率90%；
+## Unreleased
+
+* Add Zabbix 7.x API-token authentication through the Bearer header while retaining the legacy 4.x-6.x authentication body.
+* Reuse a thread-safe persistent `Net::HTTP` session and add explicit `close` lifecycle handling.
+* Add injectable, credential-filtered request logging and stable JSON-RPC error handling.
+* Add idempotent device/interface monitoring workflows with bandwidth, error, and packet-loss hysteresis triggers.
+* Remove experimental `mojo_*` host/trigger methods and unsafe hard-coded SNMP defaults.
+* Remove environment-specific item lookup helpers with hard-coded host data; use `monitoring.reconcile_line` instead.
+* Remove copied Role user-group methods and the hard-coded historical problem-closing workflow.
+* Remove dormant live-Zabbix scripts that were not part of the RSpec test pattern and mutated remote systems by default.
+* Use ActiveSupport for deep key normalization and blank-value semantics.
+* Batch line reconciliation to reuse host/item discovery and reject ambiguous or dimensionally invalid traffic items.
+* Simplify template reference lookup and fix partial final-row sizing in screen creation.
+* Replace the inherited Rails RuboCop profile with project-scoped lint, security, performance, packaging, layout, and safe style gates.
+* Keep HTTPS verification disabled by default for compatibility, with an opt-in `verify_ssl: true` mode.
+* Remove the unused `http` runtime dependency and support the `logger` default gem on modern Ruby.
+* Add two-phase batch reconciliation for devices and lines with full preflight validation, sanitized per-entry errors, and summaries.
+* Add focused host-interface CRUD, item batch/status/delete, trigger status/delete, and current trigger dependency append/replace APIs.
+* Replace legacy exception names with `Invalid`, `Conflict`, `ApiError`, and `TransportError`.
+* Add CI jobs for tests, formatting, Gem packaging, and trusted tag-based RubyGems publishing.
+* Move project metadata to `https://github.com/gatework/zabbix_manager/tree/master`.
+* Scope destructive and dependency operations by host, serialize host/interface reconciliation, and expose uncertain writes as `ResultUnknown`.
+* Validate current Zabbix item/interface create contracts before writes and publish the exact smoke-tested Gem artifact.
+
+### 5.0.7

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 WENWU YAN
+Copyright (c) 2022 WENWU YAN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -4,7 +4,7 @@
 
 [gem]: https://rubygems.org/gems/zabbix_manager
 
-Most of the code in the project is based on rewriting the ZabbixApi
+Most codes borrowed from zabbixapi, but fit for my everyday works well!
 Simple and lightweight ruby module for working with [Zabbix][Zabbix] via the [Zabbix API][Zabbix API]
 
 ## Installation
@@ -13,7 +13,7 @@ Simple and lightweight ruby module for working with [Zabbix][Zabbix] via the [Za
 gem install zabbix_manager
 
 # specific version
-gem install zabbix_manager -v 5.1.1
+gem install zabbix_manager -v 4.2.0
 ```
 
 ## Documentation
@@ -23,15 +23,204 @@ gem install zabbix_manager -v 5.1.1
 
 ## Examples
 
+### API token (Zabbix 7.x)
+
+The token can come from an application settings page or another secret store. Pass it directly to the client; do not copy it into request parameters or logs.
+
+```ruby
+require "zabbix_manager"
+
+zabbix = ZabbixManager.connect(
+  url: "https://zabbix.example.com/api_jsonrpc.php",
+  api_token: ENV.fetch("ZABBIX_API_TOKEN")
+)
+
+hosts = zabbix.hosts.get_raw(output: %w[hostid host])
+zabbix.close
+```
+
+Zabbix 7.x requests use the `Authorization: Bearer` header. Earlier supported servers use the JSON-RPC `auth` property. Supplying `api_token` skips `user.login`, and `logout` only closes the local connection because an API token is not a Zabbix user session. API tokens are rejected on plain HTTP unless `allow_insecure_http: true` is explicitly set.
+
+### Username and password
+
+```ruby
+zabbix = ZabbixManager.connect(
+  url: "https://zabbix.example.com/api_jsonrpc.php",
+  username: ENV.fetch("ZABBIX_USERNAME"),
+  password: ENV.fetch("ZABBIX_PASSWORD")
+)
+
+begin
+  zabbix.query(method: "host.get", params: { output: %w[hostid host] })
+ensure
+  zabbix.logout
+end
+```
+
+A client keeps one persistent `Net::HTTP` session and serializes access to it, so repeated API calls reuse the same TCP/TLS connection. Use one client per process or worker when parallel request throughput matters; a client deliberately permits only one in-flight request. Call `close` when the client is no longer needed. A failed HTTP request closes the connection; the next request establishes a fresh session without automatically replaying the failed JSON-RPC mutation.
+
+### Logging and HTTPS
+
+Pass any Ruby Logger-compatible object to receive connection, request completion, duration, and failure events:
+
+```ruby
+zabbix = ZabbixManager.connect(
+  url: "https://zabbix.example.com/api_jsonrpc.php",
+  api_token: ENV.fetch("ZABBIX_API_TOKEN"),
+  logger: Rails.logger
+)
+```
+
+Passwords, API tokens, authorization values, cookies, and session IDs are filtered. Request parameters and response bodies are not logged; debug events contain only operation metadata.
+
+HTTPS certificate verification is disabled by default as required by this project. Set `verify_ssl: true` (and optionally `ca_file:`) to enable peer verification.
+
+Zabbix 7 API-token requests need the `Authorization` header, so they cannot share that header with HTTP Basic authentication. The client rejects that combination instead of silently overwriting either credential.
+
+Timeouts can be set together with `timeout:` or independently with `open_timeout:`, `read_timeout:`, and `write_timeout:`. `keep_alive_timeout:` controls persistent connection reuse.
+
+### Device and interface monitoring
+
+`monitoring` provides idempotent workflows for frequent device and line updates. Item identity is the stable pair `hostid + key_`; managed triggers use a dedicated `zabbix_manager_id` tag. Missing remote objects are created and existing ones are updated. Omitted objects are never deleted.
+
+For a line inventory that already has interface traffic items discovered by Zabbix, use `reconcile_line`. It accepts the field names from the historical `add_line_monitors.rb` importer, locates the host and the unique inbound/outbound items, then creates or updates one combined trigger. Use a stable, non-secret `line_id` so interface renames update the same trigger.
+
+```ruby
+zabbix.monitoring.reconcile_line(
+  line_id: "line-42",
+  description: "Example upstream circuit",
+  capacity: 200, # Mbps
+  device1: "edge-switch-01",
+  ipaddr1: "192.0.2.10",
+  iface1: "Ten-GigabitEthernet1/0/49",
+  isp: "Example ISP",
+  high_water: 0.90,
+  recovery_water: 0.80,
+  problem_window: "5m",
+  recovery_window: "15m",
+  severity: 4
+)
+```
+
+The lookup accepts full and abbreviated interface names such as `Ten-GigabitEthernet1/0/49` and `Te1/0/49`. It refuses zero or multiple direction matches instead of selecting an item by response order. Existing triggers from the importer can be adopted when their description and `category=line_bandwidth` tag match.
+
+Use `reconcile_lines(lines)` for imports. It reuses host and item discovery results within the batch, avoiding a full `item.get` scan for every line.
+
+For a device-and-line batch, use `reconcile_network`. The whole input is structurally validated before the first device write. Devices are reconciled first, then lines, and the return value contains per-entry results plus a summary. Template linking and low-level discovery are asynchronous in Zabbix: if a new device's traffic items are not available yet, its line result is an error and the same batch can be safely rerun later.
+
+```ruby
+result = zabbix.monitoring.reconcile_network(
+  devices: [
+    {
+      host: "edge-router-01",
+      name: "Example edge router",
+      groups: [{ groupid: 20 }],
+      interfaces: [{
+        type: 2, main: 1, useip: 1, ip: "192.0.2.10", dns: "", port: "161",
+        details: { version: 2, community: ENV.fetch("SNMP_COMMUNITY") }
+      }]
+    }
+  ],
+  lines: [
+    {
+      line_id: "line-42", device: "edge-router-01",
+      interface_name: "Ten-GigabitEthernet1/0/49", capacity_mbps: 200,
+      high_water: 0.90, recovery_water: 0.80
+    }
+  ]
+)
+
+result.fetch(:summary)
+```
+
+```ruby
+hostid = zabbix.monitoring.reconcile_device(
+  host: "router-01",
+  name: "Core router 01",
+  groups: [{ groupid: 20 }],
+  interfaces: [{
+    type: 2,
+    main: 1,
+    useip: 1,
+    ip: "192.0.2.1",
+    dns: "",
+    port: "161",
+    details: { version: 2, community: ENV.fetch("SNMP_COMMUNITY") }
+  }]
+)
+
+zabbix.monitoring.reconcile_interface(
+  host: { hostid: hostid, host: "router-01" },
+  interface: { name: "GigabitEthernet1/0/1", interfaceid: 12 },
+  items: {
+    inbound_bps: {
+      key_: "if.hc.in.bps[1]", name: "WAN inbound", type: 20, value_type: 0,
+      snmp_oid: "get[1.3.6.1.2.1.31.1.1.1.6.1]", delay: "1m", units: "bps",
+      preprocessing: [
+        { type: 10, params: "", error_handler: 0, error_handler_params: "" },
+        { type: 1, params: "8", error_handler: 0, error_handler_params: "" }
+      ]
+    },
+    outbound_bps: {
+      key_: "if.hc.out.bps[1]", name: "WAN outbound", type: 20, value_type: 0,
+      snmp_oid: "get[1.3.6.1.2.1.31.1.1.1.10.1]", delay: "1m", units: "bps",
+      preprocessing: [
+        { type: 10, params: "", error_handler: 0, error_handler_params: "" },
+        { type: 1, params: "8", error_handler: 0, error_handler_params: "" }
+      ]
+    },
+    in_errors: {
+      key_: "if.in.errors.rate[1]", name: "WAN input errors", type: 20, value_type: 0,
+      snmp_oid: "get[1.3.6.1.2.1.2.2.1.14.1]", delay: "1m",
+      preprocessing: [{ type: 10, params: "", error_handler: 0, error_handler_params: "" }]
+    },
+    out_errors: {
+      key_: "if.out.errors.rate[1]", name: "WAN output errors", type: 20, value_type: 0,
+      snmp_oid: "get[1.3.6.1.2.1.2.2.1.20.1]", delay: "1m",
+      preprocessing: [{ type: 10, params: "", error_handler: 0, error_handler_params: "" }]
+    },
+    packet_loss: {
+      key_: "icmppingloss[198.51.100.1]", name: "WAN packet loss",
+      type: 3, value_type: 0, delay: "1m", units: "%"
+    }
+  },
+  thresholds: {
+    bandwidth: { capacity_bps: 1_000_000_000, high_percent: 80, recovery_percent: 70 },
+    errors: { high: 100, recovery: 20, function: "max", window: "5m" },
+    packet_loss: { high: 5, recovery: 2 }
+  }
+)
+```
+
+The library does not guess that SNMP discard/error counters equal packet-loss percentage. Supply an actual packet-loss item key (for example an ICMP loss item) and its item definition. Raw HC-octet traffic items must expose `bps` units and include change-per-second plus multiplier-8 preprocessing; otherwise line reconciliation refuses to build a dimensionally incorrect trigger. Thresholds use separate high and recovery values to avoid alert flapping.
+
+Reconciliation is a sequence of remote API calls, not a transaction. Single-object methods raise immediately; batch methods return a sanitized error for each failed entry unless `fail_fast: true` is passed. A retry safely converges already-created items by stable keys. If a trigger create loses its response and cannot be confirmed by readback, `ResultUnknown` is raised and must not be automatically retried. The readback schedule can be set with `uncertain_write_delays:` (up to 60 seconds total). The trigger upsert is serialized within one client process. For multiple workers, inject a callable `upsert_lock` adapter that runs the block under an application-level distributed lock.
+
+```ruby
+ZabbixManager.connect(
+  url: "https://zabbix.example.com/api_jsonrpc.php",
+  api_token: ENV.fetch("ZABBIX_API_TOKEN"),
+  upsert_lock: ->(key, &work) { MonitoringLock.with(key, &work) }
+)
+```
+
+Invalid caller input raises `ZabbixManager::Invalid`, ambiguous remote ownership raises `ZabbixManager::Conflict`, Zabbix JSON-RPC failures raise `ZabbixManager::ApiError`, HTTP/network failures raise `ZabbixManager::TransportError`, and uncertain remote writes raise `ZabbixManager::ResultUnknown`. Destructive/status/dependency methods require `hostid:` and verify ownership before writing. Dependencies default to the same host; cross-host dependencies require `allow_cross_host_dependencies: true`. Do not pass untrusted page parameters directly to raw `query` calls.
+
+### High-frequency API modules
+
+The focused modules expose explicit current operations instead of compatibility aliases:
+
+* `hosts.reconcile`, `hosts.find_by_id`, `hosts.find_by_candidates`, `hosts.set_status`
+* `hostinterfaces.for_host`, `hostinterfaces.reconcile_for_host`, `hostinterfaces.delete_many`
+* `items.for_host`, `items.upsert_by_key`, `items.upsert_many`, `items.set_status`, `items.delete_many`
+* `triggers.for_host`, `triggers.upsert_for_host`, `triggers.add_dependencies`, `triggers.replace_dependencies`, `triggers.set_status`, `triggers.delete_many`
+
 
 ## Supported Ruby Versions
 This library aims to support and is [tested against][github-ci] the following Ruby
 versions:
 
-* Ruby 2.5
-* Ruby 2.6
-* Ruby 2.7
-* JRuby 9.2.10.0
+* Ruby 2.7 and newer
 
 If something doesn't work on one of these versions, it's a bug.
 
@@ -49,8 +238,9 @@ dropped.
 ## Dependencies
 
 * net/http
+* active_support
 * json
-* activesupport
+* logger
 
 ## Contributing
 
@@ -60,10 +250,14 @@ dropped.
 * Commit, do not mess with rakefile, version.
 * Make a pull request.
 
+## CI and release
+
+Pull requests and pushes to `master` run RSpec, documentation coverage, RuboCop, whitespace checks, and a built-Gem install smoke test. A `v<gem-version>` tag repeats the project gate, validates the tag/version, builds and installs a release candidate, then publishes that exact file through RubyGems Trusted Publishing. Configure the RubyGems trusted publisher for repository `gatework/zabbix_manager`, workflow `release.yml`, and environment `release` before pushing a release tag.
+
 ## Zabbix documentation
 
 * [Zabbix Project Homepage][Zabbix]
 * [Zabbix API docs][Zabbix API]
 
 [Zabbix]: https://www.zabbix.com
-[Zabbix API]: https://www.zabbix.com/documentation/5.2/manual/api
+[Zabbix API]: https://www.zabbix.com/documentation/current/en/manual/api

data/lib/zabbix_manager/basic/basic_alias.rb

@@ -2,19 +2,41 @@
 
 class ZabbixManager
   class Basic
-    # 获取 Zabbix 对象数据
+    # 按标识字段从 Zabbix API 获取对象完整数据。
+    #
+    # @param data [Hash] 包含对象标识字段及其值
+    # @raise [ApiError] Zabbix API 调用失败时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @return [Hash] 对象完整数据
     def get(data)
       get_full_data(data)
     end
 
-    # 新增 Zabbix 对象
+    # 通过 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 对象
+    # 通过 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

@@ -2,83 +2,54 @@
 
 class ZabbixManager
   class Basic
-    # 在调试模式下将日志消息记录到 stdout
+    # 将调试信息交给客户端结构化日志，并移除可能包含请求参数的片段。
+    #
+    # @param message [String] 待记录的调试信息
+    # @return [void]
     def log(message)
-      puts message if @client.options[:debug]
+      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
 
-    # 比较两个哈希是否相等
-    def hash_equals?(hash1, hash2)
-      normalized_hash1 = normalize_hash(hash1)
-      normalized_hash2 = normalize_hash(hash2)
-
-      merged_hash1 = normalized_hash1.merge(normalized_hash2)
-      merged_hash2 = normalized_hash2.merge(normalized_hash1)
-
-      merged_hash1 == merged_hash2
+    # 比较实际哈希是否包含期望哈希中的全部键值。
+    #
+    # @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
 
-    # 将所有哈希/数组键转换为符号
-    # &method(:symbolize_keys) 是 Ruby 中一种将方法转换为可传递给块或其他方法的 Proc 的方式
-    def symbolize_keys(object)
-      case object
-      when Array
-        object.map(&method(:symbolize_keys))
-      when Hash
-        object.transform_keys(&:to_sym).transform_values(&method(:symbolize_keys))
-      else
-        object
-      end
-    end
-
-    # 将所有哈希值规范化为字符串
+    # 将哈希值递归规范为字符串，并忽略 hostid。
+    #
+    # @param hash [Hash] 待规范化的哈希
+    # @return [Hash] 规范化后的副本
     def normalize_hash(hash)
-      result = hash.dup
-
-      # 移除用于日志记录的 TODO 注释。TemplateID 和 HostID 具有不同的 ID
-      result.delete(:hostid)
-
-      result.transform_keys!(&:to_sym)
-      result.transform_values! { |value| value.is_a?(Array) ? normalize_array(value) : value.to_s }
-
-      result
+      hash.deep_symbolize_keys.except(:hostid).deep_transform_values(&:to_s)
     end
 
-    # 将所有数组值规范化为字符串
-    def normalize_array(array)
-      result = []
-
-      array.each do |e|
-        if e.is_a?(Array)
-          result.push(normalize_array(e))
-        elsif e.is_a?(Hash)
-          result.push(normalize_hash(e))
-        else
-          result.push(e.to_s)
-        end
-      end
-
-      result
-    end
-
-    # 解析包含 ID 键或布尔值的数据哈希
+    # 从 API 结果中解析单个对象 ID，或透传布尔结果。
+    #
+    # @param data [Hash, Boolean] API 返回结果
+    # @return [Integer, Boolean, nil] 对象 ID、布尔结果或空值
     def parse_keys(data)
       case data
       when Hash
-        data.empty? ? false : data[keys][0].to_i
+        data.empty? ? nil : data[keys][0].to_i
       when TrueClass
         true
       when FalseClass
         false
-      else
-        false
       end
     end
-
-    # 合并两个哈希为一个新的哈希
-    def merge_hashes(hash1, hash2)
-      new_hash = hash1.dup
-      new_hash.merge(hash2)
-    end
   end
 end

data/lib/zabbix_manager/basic/basic_init.rb

@@ -2,34 +2,49 @@
 
 class ZabbixManager
   class Basic
-    # 使用 ZabbixManager 客户端初始化一个新的 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 ZbxError, "子类需要自行实现 method_name"
+      raise Invalid, "Can't call method_name here"
     end
 
-    # 在派生类中应该重写此方法以提供特定的 ID 字段名
-    def identify
-      raise ZbxError, "子类需要自行实现 identify"
-    end
-
-    # 派生类可以重写此方法以提供特定的默认选项
+    # 返回资源创建时使用的默认选项，子类可按需覆盖。
+    #
+    # @return [Hash] 默认选项
     def default_options
       {}
     end
 
-    # 根据 method_name + id 返回对象的 ID 字段名（identify）
+    # 根据单数 ID 字段名生成 API 返回结果中的复数字段名。
+    #
+    # @return [String] 复数 ID 字段名
+    def keys
+      "#{key}s"
+    end
+
+    # 根据 API 方法名生成对象 ID 字段名。
+    #
+    # @return [String] 对象 ID 字段名
     def key
       "#{method_name}id"
     end
 
-    # 根据 key 返回对象的复数 ID 字段名（identify）
-    def keys
-      "#{key}s"
+    # 定义资源业务标识字段占位，要求子类覆盖。
+    #
+    # @raise [ApiError] 基础类不能直接提供标识字段时抛出
+    # @return [String] 业务标识字段名
+    def identify
+      raise Invalid, "Can't call identify here"
     end
   end
 end