zabbix_manager 5.1.5 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72554dfff6fd4d60ac8be48bc766c9367e4b07f9fa2e3df7500cb21b49a6b033
-  data.tar.gz: 01bea1ff565779f4ce5dab0b9a53d1832e80f9581b58dcc2e9bc943e83da9a46
+  metadata.gz: b40a4744edcbba667b1c548c576b6451e637dee80bce28755a151f58e02a553b
+  data.tar.gz: 5d5ee350721f10da7ea9f93582bf06fc6c5b6ac4e5a9bbaa445058f43c205a45
 SHA512:
-  metadata.gz: 28bfea0b7a7bd6d99d394a0168a3399275af50fe139609141d03a996e6f488f484e8601529a58bf8710c492edd401514d66771e3b1411a53500898a05e8b6974
-  data.tar.gz: a25a5c306cffa53d2b601c6f281e5ab5afbfb72fd8cef106683668f7d4b907b047b5d4ab76fcc2aa1e62b9df979ba5129628443c53601effe0de95facb69dd90
+  metadata.gz: db558e058564904b417225b8f59df28a741b7f73d787f104180dd878e017899fadfe077d4194b2e2f2b2995639cf9c42ab585abf25f0d06308af9f8a6549eeba
+  data.tar.gz: 5c6a2e519171dec793941f13ba766aad04679a008196dad090b784614fa59882c851c810554c0c8ee479ba8aa7493779c5c2f770bfc1d24c0efb8da4a730da7d

data/CHANGELOG.md

@@ -1,11 +1,57 @@
 # 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%；
+## 6.0.0 (2026-10-01)
+
+* Fix role ID queries and host-scoped value map identities, keeping immutable host fields out of updates.
+* Reject incomplete interface creation and duplicate resolved interface targets before remote writes.
+* Preserve distinct interface names, validate standard 32-bit octet conversion, and check effective numeric item configuration before writing monitoring updates.
+* Bound network request duration and decompressed response size, close failed connections, and never replay uncertain mutations.
+* Complete Chinese module comments and correct public return-type documentation.
+
+* Extract reusable Motor monitoring scenarios through native Zabbix APIs only, without SQL or application persistence.
+* Add `traffic.series` and `traffic.for_interface` for precise history/trend reads with missing-data and truncation states.
+* Add device name resolution, proxy groups, SNMP secret macros and caller-owned membership receipts; preserve unrelated configuration.
+* Add line previews, low-traffic/status/ICMP checks, dependencies, scoped problem reads and managed trigger retirement.
+* Return device receipts and per-kind line `triggerids`; expand public method contracts and executable workflow examples.
+
+* Validate mutation receipts against requested IDs; empty, malformed or mismatched receipts remain unconfirmed outcomes.
+* Require desired trigger state during lost-response recovery and serialize dependency replacement with appends.
+* Replace obsolete template-side host-link helpers with `hosts.link_templates`, `replace_templates`, and `unlink_templates` using current host APIs.
+* Use explicit `user_groups.replace_users` and `replace_host_group_permissions` operations with version-correct server fields.
+* Verify packaged source inventory and isolated authenticated requests, then publish the exact verified artifact; declare IRB for Ruby 4 development consoles.
+
+* Normalize multiword resource classes, files and accessors to Ruby CamelCase/snake_case without compatibility aliases.
+
+* Require Ruby 3.4 or newer; refresh the dependency lockfile and remove development-tool version pins and duplicate declarations.
+* Replace the split `Basic` hierarchy with `Resource`, remove compatibility aliases and parameter logging, and use keyword connection/request options.
+* Use ActiveSupport logger/tagging/parameter filtering; make logging failure independent of API results.
+* Add explicit `from_env` loading for `ZABBIX_URL`, `ZABBIX_API_TOKEN`, `ZABBIX_USERNAME`, and `ZABBIX_PASSWORD` only.
+* Remove `current`, `user`, `debug`, `manager_request`, low-level client request helpers and legacy inventory field aliases; use explicit managers, `username`, `logger`/`log_level` and canonical monitoring fields.
+* Validate JSON-RPC response shapes and IDs, report unconfirmed responses as `ProtocolError`, and prevent server text or exception causes from leaking secrets.
+* Delegate proxy discovery and exclusions to Ruby, validate finite timeouts, and avoid closing an inherited parent TLS session after fork.
+* Validate complete interface/item batches before writes, refuse ambiguous macro ownership, and distinguish missing values from empty strings during updates.
+* Separate monitoring input, threshold and traffic-item rules, reject invalid units/expressions, and retain unknown write outcomes in batch results.
+
+* 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,8 +4,7 @@
 
 [gem]: https://rubygems.org/gems/zabbix_manager
 
-Most of the code in the project is based on rewriting the ZabbixApi
-Simple and lightweight ruby module for working with [Zabbix][Zabbix] via the [Zabbix API][Zabbix API]
+A Ruby client for the [Zabbix API][Zabbix API], with reusable device, interface and circuit monitoring workflows.
 
 ## Installation
 ```sh
@@ -13,7 +12,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,47 +22,265 @@ gem install zabbix_manager -v 5.1.1
 
 ## Examples
 
+### API token (Zabbix 7.x)
 
-## Supported Ruby Versions
-This library aims to support and is [tested against][github-ci] the following Ruby
-versions:
+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.
+
+### Environment configuration
+
+Environment loading is explicit. `connect` uses only its keyword arguments; `from_env` reads exactly four variables:
+
+| Variable | Option |
+| --- | --- |
+| `ZABBIX_URL` | `url` |
+| `ZABBIX_API_TOKEN` | `api_token` |
+| `ZABBIX_USERNAME` | `username` |
+| `ZABBIX_PASSWORD` | `password` |
+
+```ruby
+zabbix = ZabbixManager.from_env(verify_ssl: true)
+```
+
+Explicit keyword arguments override environment values, including `nil` to clear an inherited credential. Set either an API token or a username/password pair. Unknown options and non-boolean flags are rejected before connecting. Timeouts, logging and locking remain ordinary keyword options.
+
+The HTTP transport uses Ruby's standard proxy discovery (`http_proxy`/`HTTP_PROXY`, `no_proxy`/`NO_PROXY`, with CGI protection). `no_proxy: true` disables proxies; `proxy: "http://proxy.example:8080"` selects an explicit HTTP proxy. HTTPS proxy URLs are rejected because this transport does not encrypt the connection to the proxy itself.
+
+### 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 a Ruby Logger or ActiveSupport logger 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
+)
+```
+
+Logging uses `ActiveSupport::Logger` and `ActiveSupport::TaggedLogging`; structured credential filtering uses `ActiveSupport::ParameterFilter`. Pass `log_level: :info` to create a logger on standard error, or inject your application's logger. Logging is disabled unless one of these options is supplied, and logging failures do not change API outcomes.
+
+Passwords, API tokens, authorization values, cookies, and session IDs are filtered. Request parameters and response bodies are not logged. API exceptions expose the server error code and request ID, without remote messages or data that might echo arbitrary secrets. Malformed or mismatched JSON-RPC responses and invalid mutation ID receipts raise `ProtocolError < TransportError`: a write may already have happened, so it must not be blindly replayed.
+
+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. `request_timeout:` bounds the complete network operation, including a continuously progressing response, and defaults to `timeout:`. Waiting for another request on the same client is outside that budget. `max_response_bytes:` limits the decompressed response body (64 MiB by default). Exceeding either limit closes the connection and raises `TransportError`; mutations are never automatically replayed.
+
+### Device and interface monitoring
+
+`monitoring` provides device and line workflows using native Zabbix APIs only. There are no SQL operations, Rails models or persistence dependencies. Item identity is the stable pair `hostid + key_`; managed triggers use a dedicated `zabbix_manager_id` tag. Missing objects are created and existing ones are updated. Optional line checks removed from a definition are disabled after the remaining desired checks succeed; objects are never automatically deleted.
 
-* Ruby 2.5
-* Ruby 2.6
-* Ruby 2.7
-* JRuby 9.2.10.0
+For a line inventory that already has interface traffic items discovered by Zabbix, use `reconcile_line`. It locates the host and unique inbound/outbound items, then creates or updates the selected checks. Use canonical fields `host` (or `host_candidates`), `interface_name`, `capacity_mbps`, and a stable, non-secret endpoint `line_id`. Convert external inventory column names before calling the library.
 
-If something doesn't work on one of these versions, it's a bug.
+The complete workflows and return values are documented in [device monitoring](examples/device_monitoring.md), [line monitoring](examples/line_monitoring.md), and [traffic queries](examples/traffic.md). Public method comments document input, output, failures and remote side effects.
 
-This library may inadvertently work (or seem to work) on other Ruby versions,
-however support will only be provided for the versions listed above.
+```ruby
+zabbix.monitoring.reconcile_line(
+  line_id: "line-42",
+  description: "Example upstream circuit",
+  capacity_mbps: 200,
+  host_candidates: ["edge-switch-01", "192.0.2.10"],
+  interface_name: "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. Trigger ownership comes from the managed identity tag; matching descriptions alone never adopt unrelated triggers.
+
+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: retry discovery after the required items become available. Inspect any `:unknown` write outcome before repeating that entry.
+
+```ruby
+result = zabbix.monitoring.reconcile_network(
+  devices: [
+    {
+      host: "edge-router-01",
+      name: "Example edge router",
+      groups: ["Network devices"],
+      snmp: { ip: "192.0.2.10", community: ENV.fetch("SNMP_COMMUNITY") }
+    }
+  ],
+  lines: [
+    {
+      line_id: "line-42", host: "edge-router-01",
+      interface_name: "Ten-GigabitEthernet1/0/49", capacity_mbps: 200,
+      high_water: 0.90, recovery_water: 0.80
+    }
+  ]
+)
+
+result.fetch(:summary)
+```
+
+```ruby
+receipt = 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") }
+  }]
+)
+hostid = receipt.fetch(:hostid)
+snmp_interface = zabbix.host_interfaces.for_host(hostid).find do |interface|
+  interface["type"] == "2" && interface["main"] == "1"
+end
+
+zabbix.monitoring.reconcile_interface(
+  host: { hostid: hostid, host: "router-01" },
+  interface: { name: "GigabitEthernet1/0/1", interfaceid: snmp_interface.fetch("interfaceid") },
+  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. Line `high_water` and `recovery_water` are ratios greater than zero and at most one; percentages such as `90` are rejected. Interface threshold recovery is inclusive (`<=`), so a zero recovery threshold remains attainable.
+
+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. Batch results distinguish `ok`, `error`, and `unknown`; summaries count each status. Transport failures during device reconciliation are conservatively `unknown`, since that workflow includes both lookup and write calls. Successful earlier remote writes are not rolled back if a later operation fails. After an uncertain outcome has been resolved, a retry can converge already-created items by stable keys. If a trigger create loses its response, readback must confirm both its managed identity and requested attributes. If that cannot be confirmed, `ResultUnknown` is raised and must not be automatically retried. A definite API rejection is propagated. The readback schedule can be set with `uncertain_write_delays:` (up to 60 seconds total). Trigger upserts and dependency read/modify/write operations are 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`. The focused item/interface/trigger deletion, status and dependency helpers require `hostid:` and verify existing ownership before writing. Custom trigger expressions and raw resource methods accept trusted Zabbix definitions; the host lookup context does not replace application authorization. Dependencies default to the same host; cross-host dependencies require `allow_cross_host_dependencies: true`. Do not pass untrusted page parameters directly to `query`, raw resource methods, or custom expressions.
 
-If you would like this library to support another Ruby version or
-implementation, you may volunteer to be a maintainer. Being a maintainer
-entails making sure all tests run and pass on that implementation. When
-something breaks on your implementation, you will be responsible for providing
-patches in a timely fashion. If critical issues for a particular implementation
-exist at the time of a major release, support for that Ruby version may be
-dropped.
+### High-frequency API modules
+
+`traffic.series` reads explicit item IDs; `traffic.for_interface` discovers both interface directions. Both expose missing data and query truncation, preserve numeric precision, and keep raw history separate from hourly trends. They never substitute zero or a stale last value for missing samples.
+
+Multiword resource accessors use Ruby snake_case: `host_groups`, `host_interfaces`, `http_tests`, `media_types`, `proxy_groups`, `user_groups`, `user_macros`, `value_maps`, and `discovery_rules`.
+
+The focused modules expose explicit operations:
+
+* `hosts.reconcile`, `hosts.resolve`, `hosts.find_by_id`, `hosts.find_by_candidates`, `hosts.set_status`
+* `monitoring.reconcile_device`, `monitoring.reconcile_devices`, `monitoring.reconcile_network`
+* `monitoring.plan_line`, `monitoring.reconcile_line`, `monitoring.line_triggers`, `monitoring.line_problems`, `monitoring.disable_line`
+* `hosts.link_templates`, `hosts.replace_templates`, `hosts.unlink_templates`
+* `user_groups.replace_users`, `user_groups.replace_host_group_permissions`
+* `host_interfaces.for_host`, `host_interfaces.reconcile_for_host`, `host_interfaces.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
+The minimum Ruby version is **3.4**. CI runs Ruby 3.4 and 4.0.
 
 ## Dependencies
 
-* net/http
+* net-http
+* active_support
 * json
-* activesupport
+* logger
 
 ## Contributing
 
 * Fork the project.
 * Base your work on the master branch.
 * Make your feature addition or bug fix, write tests, write documentation/examples.
-* Commit, do not mess with rakefile, version.
+* Run `bundle exec rake` and `bundle exec ruby script/verify_package.rb`.
 * Make a pull request.
 
+## CI and release
+
+`script/verify_package.rb` checks the complete library inventory, installs into an isolated gem directory, exercises authentication and a resource request over a local HTTP socket, then saves that exact verified archive under `pkg/`. It also works when invoked outside the checkout.
+
+Development tools are declared once in `Gemfile`, without historical version pins. `Gemfile.lock` records the versions verified together. Runtime dependencies declare only the minimum API version needed by the library; update the lockfile and run the gates when changing dependencies.
+
+
+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
+
+### Upgrading to 6.0
+
+Version 6.0 requires Ruby 3.4 or newer. Use keyword connection and query arguments, snake_case resource accessors, the explicit exception classes, and the current monitoring result shapes shown above. Legacy aliases and the former `Basic` API are removed.

data/lib/zabbix_manager/classes/actions.rb

@@ -1,31 +1,33 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Actions < Basic
-    # 用于与 Zabbix API 交互的方法名称
+  # 告警动作资源；完整读取包含执行、恢复、确认操作及过滤条件。
+  class Actions < Resource
+    # 返回操作对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "action"
     end
 
-    # 用于通过 Zabbix API 标识特定 Action 对象的 id 字段名称
-    def identify
-      "name"
-    end
-
-    # 从 API 获取完整/扩展的 Action 对象数据
+    # 获取操作及其执行、恢复、确认操作和过滤条件的完整数据。
+    #
+    # @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(
-        {
-          filter:                      {
+      @client.api_request(
+        method: "#{method_name}.get",
+        params: {
+          filter: {
             identify.to_sym => data[identify.to_sym]
           },
-          output:                      "extend",
-          selectOperations:            "extend",
-          selectRecoveryOperations:    "extend",
+          output: "extend",
+          selectOperations: "extend",
+          selectRecoveryOperations: "extend",
           selectAcknowledgeOperations: "extend",
-          selectFilter:                "extend"
+          selectFilter: "extend"
         }
       )
     end

data/lib/zabbix_manager/classes/applications.rb

@@ -1,32 +1,21 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Applications < Basic
-    # 用于通过 Zabbix API 与 Applications 交互的方法名称
+  # 应用集以 hostid + name 定位；端点是否可用由目标 Zabbix 版本决定。
+  class Applications < Resource
+    # 返回应用集对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "application"
     end
 
-    # 用于通过 Zabbix API 标识特定 Application 对象的 id 字段名称
-    def identify
-      "name"
-    end
-
-    # 通过 Zabbix API 获取或创建 Application 对象
-    def get_or_create(data)
-      log "[DEBUG] 调用 get_or_create，参数为：#{data.inspect}"
-
-      if (id = get_id(name: data[:name], hostid: data[:hostid]))
-        id
-      else
-        create(data)
-      end
-    end
-
-    # 通过 Zabbix API 创建或更新 Application 对象
-    def create_or_update(data)
-      applicationid = get_id(name: data[:name], hostid: data[:hostid])
-      applicationid ? update(data.merge(applicationid: applicationid)) : create(data)
+    # 生成由应用集名称和所属主机构成的稳定查询条件。
+    # @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
   end
 end

data/lib/zabbix_manager/classes/configurations.rb

@@ -1,28 +1,38 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Configurations < Basic
-    # 用于标识返回结果是否为数组
-    def array_flag
-      true
-    end
-
-    # 用于通过 Zabbix API 与 Configurations 交互的方法名称
+  # 原生配置导入/导出入口；导入可能修改多个远端对象，不提供本地回滚。
+  class Configurations < Resource
+    # 返回配置对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "configuration"
     end
 
-    # 用于通过 Zabbix API 标识特定 Configuration 对象的 id 字段名称
+    # 返回配置对象用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "host"
     end
 
-    # 使用 Zabbix API 导出配置数据
+    # 通过 Zabbix API 导出配置数据。
+    #
+    # @param data [Hash] 配置导出参数
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [String] 服务端按指定格式序列化的配置内容
     def export(data)
       @client.api_request(method: "configuration.export", params: data)
     end
 
-    # 使用 Zabbix API 导入配置数据
+    # 通过 Zabbix API 导入配置数据。
+    #
+    # @param data [Hash] 配置导入参数及内容
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Boolean] 服务端确认的导入结果
     def import(data)
       @client.api_request(method: "configuration.import", params: data)
     end

data/lib/zabbix_manager/classes/discovery_rules.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # 网络发现规则（drule），区别于主机内的低级发现（discoveryrule）。
+  class DiscoveryRules < Resource
+    # 返回网络发现规则对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
+    def method_name
+      "drule"
+    end
+
+    # 返回创建网络发现规则时使用的默认周期和启用状态。
+    #
+    # @return [Hash] 网络发现规则默认属性
+    def default_options
+      {
+        delay: "1h",
+        status: 0
+      }
+    end
+  end
+end

data/lib/zabbix_manager/classes/errors.rb

@@ -1,39 +1,30 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  # BaseError 是 ZabbixManager 模块中处理异常的基类
-  class BaseError < RuntimeError
-    # 用于存储响应对象
-    attr_accessor :response
-    # 用于存储 Zabbix API 错误信息
-    attr_accessor :error
-    # 用于存储格式化后的错误消息
-    attr_accessor :error_message
+  # 表示调用方输入或配置无效。
+  class Invalid < ArgumentError; end
 
-    # 初始化异常对象
-    def initialize(message, response = nil)
+  # 表示 Zabbix JSON-RPC 返回的业务错误或无效响应。
+  class ApiError < StandardError
+    attr_reader :response
+
+    # 保存经过脱敏的远端响应，便于调用方诊断。
+    # @return [ApiError]
+    def initialize(message = nil, response = nil)
       super(message)
       @response = response
-      set_error! if @response
     end
+  end
 
-    private
+  # 表示资源不唯一、身份冲突或无法安全收敛。
+  class Conflict < ApiError; end
 
-    # 从响应中提取 Zabbix API 错误信息
-    def set_error!
-      @error = @response["error"]
-      @error_message = "#{@error["message"]}: #{@error["data"]}"
-    rescue StandardError
-      @error = nil
-      @error_message = nil
-    end
-  end
+  # 表示 HTTP 状态或传输层失败。
+  class TransportError < StandardError; end
 
-  # ZbxError 是 ZabbixManager 模块中处理 Zabbix API 异常的类
-  class ZbxError < BaseError
-  end
+  # 响应无法确认远端操作是否已经完成。
+  class ProtocolError < TransportError; end
 
-  # HttpError 是 ZabbixManager 模块中处理 HTTP 异常的类
-  class HttpError < BaseError
-  end
+  # 表示远端可能已完成写入，调用方不得自动重放。
+  class ResultUnknown < TransportError; end
 end

data/lib/zabbix_manager/classes/events.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Events < Basic
-    # 用于通过 Zabbix API 与 Events 交互的方法名称
+  # 原生事件查询入口；按当前客户端凭据可见范围返回服务端记录。
+  class Events < Resource
+    # 返回事件对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "event"
     end
 
-    # 用于通过 Zabbix API 标识特定 Event 对象的 id 字段名称
+    # 返回事件对象用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "name"
     end