ctx_checker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6bd23ca0a7767d79f02f7b0103f0c2f524534ab677d368f995484981d93fbbfb
+  data.tar.gz: 9c324f79c104b917338007d105c2a55405a09a036e66a3c9349ef57e3f9664de
+SHA512:
+  metadata.gz: 15cf93bf62713e215071bc2d5d0081820cdad50d67b38ddbbc3874e6df30b8f256417997b33e2383ea849bc15b879537b7f9013f393f01dd74f9c943db0a9aff
+  data.tar.gz: 0ac66781f4a9795b92bc872704633d72ab12a88a19b26ebe6b3af7e8b8a4239c013bbec61c28c2182e859043fc6b2ee2726eff3f3339e52e648d950769634137

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+Changes to the public contract are recorded here. Versions follow Semantic Versioning.
+
+## 0.1.0 (2026-10-16)
+
+### Added
+
+- Multi-vendor observations, normalized counters, applicability, runtime policies, and health reports.
+- Standalone RubyGems packaging under `ctx_checker` with the `ctx_checker` require path and `CtxChecker` namespace.
+- English and Chinese documentation, an offline example, and standalone RSpec/RuboCop development tasks.
+- Linux/macOS CI, isolated package verification, and automatic RubyGems and GitHub Releases with identical artifacts.
+
+### Changed
+
+- Cross-module dependencies resolve through RubyGems/Bundler instead of relative sibling paths.
+- Motor persistence and application-specific adapters remain in the host application.

data/COUNTER_CONTRACT.md

@@ -0,0 +1,33 @@
+# 接口计数归一契约
+
+接口计数以 `interface + metric` 为身份，保留 `value`、`unit`、`scope`、`source_command`、
+`sampled_at` 和 `discontinuity`。归一化表示同类指标采用一致字段，不表示不同计数可以相加。
+`in_errors`、`out_errors`、`in_discards`、`out_discards` 分别表示接收错误、发送错误、接收丢弃和发送丢弃；
+CRC 及其他错误子项保留独立指标，可能已包含在错误总数中。
+
+| 字段 | 值 | 含义 |
+| --- | --- | --- |
+| `unit` | `packets` | 包计数，可应用接口包计数策略 |
+| | `bytes` | 字节计数，不转换或当作包数 |
+| | `events` | 事件计数，不转换或当作包数 |
+| | `unknown` | 命令未证实单位，保留原值，健康判断未知 |
+| `scope` | `interface` | 接口整体计数 |
+| | `mac` | MAC 层计数 |
+| | `cpu` | CPU 接口计数 |
+| | `logical` | 逻辑接口计数 |
+| | `queue` | 队列计数 |
+| | `unknown` | 无法证实范围，健康判断未知 |
+
+`RuntimeParser` 仅在已声明的接口计数命令投影中补齐 `packets/interface` 默认值；解析器的显式
+`unit/scope` 优先。厂商适配器必须对单位或范围含糊的字段显式标记 `unknown`，不能把模糊字段静默
+交给默认值。`source_command` 始终由命令目录确定，不接受解析器伪造来源。
+直接构造的旧版 `Observation` 仍允许 `unit/scope: nil`，维持旧 API 行为；这不是新来源的语义证据。
+
+判断包计数增量，需要同设备、同接口指标、单位和范围均相同、采样时间递增，以及连续性标识一致。
+新旧样本一方缺少单位或范围时不做跨版本增量。两个样本都缺少这些字段时保留旧 API 行为。
+`bytes/events/unknown` 单位和 `unknown` 范围均不会使用包阈值，零值也不会据此判定正常。
+计数回退、清零或重启后的连续性未知时，不用负差、绝对值或自动溢出修正伪造增量。
+
+同接口同指标的多个命令记录仍属于冲突，不按 `scope` 扩大身份后混合累加。
+来源冲突由 `ObservationMerger` 隔离并报告；若需要同时保留两种范围，应先建立明确的独立业务指标契约。
+设备级 `device_counters` 使用独立的分类和策略，不继承接口包单位限制。

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Song Huang
+Copyright (c) 2026 Gatework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README-zh.md

@@ -0,0 +1,93 @@
+# ctx_checker
+
+[English](README.md) | [源码](https://github.com/gatework/ctx_checker) | [变更记录](CHANGELOG.md)
+
+面向异构网络设备的运行时健康检查。厂商解析器归一化观测指标，策略基于事实判定，缺失证据不会被当作健康。
+
+## 能力
+
+- 接口、归一化 error/drop 计数、聚合成员、光模块、BGP 和 OSPF。
+- CPU、内存、温度、环境、电源、时钟、NTP、活动告警及设备计数。
+- H3C、Cisco IOS/IOS-XE、Cisco NX-OS、Palo Alto、Hillstone 和 Radware Alteon 策略；各平台覆盖范围不同。
+- 命令执行及解析独立隔离、显式适用性判断，以及可选的前次采样比较。
+
+## 安装
+
+要求 **Ruby 4.0.6 或更新版本**。在应用的 `Gemfile` 中添加：
+
+```ruby
+gem "ctx_checker"
+```
+
+然后执行 `bundle install`；也可直接执行 `gem install ctx_checker`。Ruby 加载入口为 `ctx_checker`，公开命名空间为 `CtxChecker`；gem 包名与 Ruby 命名空间分别维护。
+
+模块运行依赖：[`ctx_parser`](https://github.com/gatework/ctx_parser), [`ctx_driver`](https://github.com/gatework/ctx_driver)。 gemspec 的运行依赖不添加版本约束；应用应提交自己的 `Gemfile.lock`，保持部署可复现。使用本库不需要启动 Rails 或配置兄弟模块的本地路径。
+
+发布产物和校验值见 [GitHub Releases](https://github.com/gatework/ctx_checker/releases)，已发布版本以 [RubyGems](https://rubygems.org/gems/ctx_checker) 为准。
+
+## 离线示例
+
+在开发检出目录安装依赖后执行：
+
+```sh
+bundle exec ruby examples/offline.rb
+```
+
+示例使用合成数据，不访问网络。完整代码见 [examples/offline.rb](examples/offline.rb)：
+
+```ruby
+require "ctx_checker"
+
+# 使用合成的 IOS 命令回显，本例不连接设备。
+output = "GigabitEthernet1/0/1 is up, line protocol is up\n"
+parser = CtxChecker::RuntimeParser.new(platform: :cisco_ios)
+observation = parser.parse(:interfaces, output, complete: true)
+snapshot = CtxChecker::Snapshot.new(
+  target: { host: "192.0.2.10", platform: parser.platform },
+  observed_at: Time.utc(2026, 1, 1),
+  observations: { interfaces: observation }
+)
+policy = CtxChecker::Policy.new(required_interfaces: [ "GigabitEthernet1/0/1" ])
+report = CtxChecker::Evaluator.new(policy: policy).call(snapshot)
+puts report.to_text
+# 未请求的维度保持 not_requested，本例不代表整机检查。
+```
+
+## 公开契约与限制
+
+`RuntimeParser.new(platform:, model: nil, software_version: nil)` 提供 `parse`、`parse_many`、`parse_outputs`。以观察结果构建 `Snapshot`，再用 `Evaluator.new(policy: Policy.new).call(snapshot, previous: nil)` 判定；报告提供 `to_text`、`to_h`、`summary` 及覆盖率。
+
+观察完整性 `complete/partial/failed/unsupported/not_requested/not_applicable` 与业务结论 `pass/fail/unknown/not_applicable` 分开。空回显不能独自证明健康或功能未配置。可信配置可证明可选 BGP、OSPF 或聚合检查不适用，必检策略仍优先。
+
+error、CRC、discard 保持独立，不相加；单次累计值不能当作当前错误速率。增量要求身份一致、时间递增及可靠连续性证据。光功率需要设备或策略阈值；已有格式支持不代表所有型号/版本都已验证。
+
+`Collector#collect` 接收负责会话生命周期的 connector；`collect_session` 借用已有会话。本 gem 不包含 Rails、库存数据库、调度或凭据。指标语义见[计数契约](COUNTER_CONTRACT.md)。
+
+详细厂商语义、历史验证记录和 Motor 专用集成说明保留在[架构参考](docs/architecture-zh.md)。其中宿主集成代码需要 Motor，不属于独立 gem API。适配层位于 [Motor 仓库](https://github.com/gatework/motor/tree/main/backend/lib) 的 `backend/lib/baseline`、`backend/lib/vxlan` 和 `backend/lib/wireless`。
+
+生命周期 connector 是宿主适配器，提供 `open { |session| }`，VXLAN 和 Wireless 还要求 `platform`；原生 `Net::Connector::Base` 实例并不提供这一宿主生命周期协议。已连接的原生会话可传入 `CtxDriver::Reader` 或 `CtxChecker::Collector#collect_session`，不会隐式连接或重试。
+
+## 开发与测试
+
+```sh
+bundle install
+bundle exec rake
+bundle exec ruby examples/offline.rb
+bundle exec rake build
+```
+
+`bundle exec rake` 执行 RSpec、RuboCop 及离线示例。测试放在 `spec/`，沿用项目 RSpec 约定；样例采用合成或脱敏证据。新增解析格式时补充成功、不完整、不支持及非法输入回归。离线测试不代表所有设备版本均通过实机验证。
+
+使用声明的最低 Ruby 版本检查兼容性。方法用途统一使用简明中文注释；复杂实现还需说明业务规则、实现思路及关键分支。保持公开返回值与错误契约。真实回显和凭据不可进入示例、fixture、日志或发布包。
+
+## 发布
+
+本目录可独立维护为 [ctx_checker](https://github.com/gatework/ctx_checker) 仓库。更新 `VERSION` 和 `CHANGELOG.md`，运行上述验证与构建命令，检查包内文件，再创建 `vVERSION` 标签。
+
+CI 在 Linux、macOS 上执行测试、lint、示例、构建和隔离安装。`main` 的 CI 通过后推送 `vVERSION` 标签，工作流将已验证的 Linux 产物发布到 RubyGems 和 GitHub Release，附带 `SHA256SUMS` 并回读下载字节。GitHub `release` environment 可配置 `RUBYGEMS_API_KEY` secret；未配置时使用 RubyGems Trusted Publishing，绑定本仓库、`release.yml` 和 `release` environment。失败时重跑失败的发布 job，以复用原 CI 产物；同版本已存在时必须校验字节一致。详见[发布说明](docs/release.md)。
+
+先发布依赖模块。标签、构建成功或工作流文件都不等于已经发布，需单独确认 RubyGems 的实际结果。版本变化见 [CHANGELOG.md](CHANGELOG.md)。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。

data/README.md

@@ -0,0 +1,93 @@
+# ctx_checker
+
+[简体中文](README-zh.md) | [Source](https://github.com/gatework/ctx_checker) | [Changelog](CHANGELOG.md)
+
+Runtime health analysis for heterogeneous network devices. Vendor parsers normalize observed metrics; policies evaluate those facts without treating missing evidence as healthy.
+
+## Features
+
+- Interfaces, normalized error/discard counters, aggregation members, optics, BGP, and OSPF.
+- CPU, memory, temperature, environment, power, clock, NTP, active alarms, and device counters.
+- Profiles for H3C, Cisco IOS/IOS-XE, Cisco NX-OS, Palo Alto, Hillstone, and Radware Alteon; coverage differs by platform.
+- Independent command execution and parsing, explicit applicability, and optional comparison with a prior sample.
+
+## Installation
+
+Requires **Ruby 4.0.6 or newer**. Add this line to your application's `Gemfile`:
+
+```ruby
+gem "ctx_checker"
+```
+
+Then run `bundle install`, or install directly with `gem install ctx_checker`. The require path is `ctx_checker` and the public namespace is `CtxChecker`; package names and Ruby namespaces are intentionally separate.
+
+Internal runtime dependencies: [`ctx_parser`](https://github.com/gatework/ctx_parser), [`ctx_driver`](https://github.com/gatework/ctx_driver). The gemspec declares runtime dependencies without version constraints. Applications should commit their own `Gemfile.lock` to make deployments reproducible. No Rails boot or sibling checkout paths are required.
+
+Release artifacts and checksums are available from [GitHub Releases](https://github.com/gatework/ctx_checker/releases). Check [RubyGems](https://rubygems.org/gems/ctx_checker) for published versions.
+
+## Offline example
+
+From a development checkout after installing dependencies:
+
+```sh
+bundle exec ruby examples/offline.rb
+```
+
+The example uses synthetic data and performs no network access:
+
+```ruby
+require "ctx_checker"
+
+# 使用合成的 IOS 命令回显，本例不连接设备。
+output = "GigabitEthernet1/0/1 is up, line protocol is up\n"
+parser = CtxChecker::RuntimeParser.new(platform: :cisco_ios)
+observation = parser.parse(:interfaces, output, complete: true)
+snapshot = CtxChecker::Snapshot.new(
+  target: { host: "192.0.2.10", platform: parser.platform },
+  observed_at: Time.utc(2026, 1, 1),
+  observations: { interfaces: observation }
+)
+policy = CtxChecker::Policy.new(required_interfaces: [ "GigabitEthernet1/0/1" ])
+report = CtxChecker::Evaluator.new(policy: policy).call(snapshot)
+puts report.to_text
+# 未请求的维度保持 not_requested，本例不代表整机检查。
+```
+
+## Public contract and limits
+
+`RuntimeParser.new(platform:, model: nil, software_version: nil)` exposes `parse`, `parse_many`, and `parse_outputs`. Build `Snapshot` from observations and evaluate it with `Evaluator.new(policy: Policy.new).call(snapshot, previous: nil)`. Reports expose `to_text`, `to_h`, `summary`, and coverage.
+
+Observation completeness (`complete`, `partial`, `failed`, `unsupported`, `not_requested`, `not_applicable`) is separate from findings (`pass`, `fail`, `unknown`, `not_applicable`). Empty output alone cannot prove a healthy or unconfigured feature. Confirmed configuration can establish that optional BGP, OSPF, or aggregation checks do not apply; required policy still takes precedence.
+
+Errors, CRC, and discards are distinct counters and must not be summed. A single cumulative value is not a current error rate. Delta analysis needs matching identities, increasing timestamps, and reliable continuity evidence. Optics need device or policy thresholds; supported command formats do not guarantee every model/version is covered.
+
+`Collector#collect` accepts an injected connector that owns its session lifecycle; `collect_session` borrows an existing session. No Rails, inventory database, scheduler, or credentials are included. See the [counter contract](COUNTER_CONTRACT.md) for metric semantics.
+
+Detailed vendor behavior, historical validation notes, and Motor-only integration are preserved in [the architecture reference](docs/architecture-zh.md). Host integration examples in that reference require Motor; they are not standalone gem APIs. Motor adapters live under `backend/lib/baseline`, `backend/lib/vxlan`, and `backend/lib/wireless` in the [Motor repository](https://github.com/gatework/motor/tree/main/backend/lib).
+
+The lifecycle connector is a host adapter exposing `open { |session| }` (and `platform` for VXLAN and Wireless). It is distinct from a native `Net::Connector::Base` device instance. Borrowed native sessions are accepted by `CtxDriver::Reader` and `CtxChecker::Collector#collect_session`; they are never implicitly connected or retried.
+
+## Development and tests
+
+```sh
+bundle install
+bundle exec rake
+bundle exec ruby examples/offline.rb
+bundle exec rake build
+```
+
+`bundle exec rake` runs RSpec, RuboCop, and the offline examples. Tests live in `spec/`, following the existing project's RSpec convention; fixtures use synthetic or sanitized evidence. Add regression cases for successful, incomplete, unsupported, and malformed inputs when extending a parser. Offline tests do not certify all device versions or replace live integration checks.
+
+Use the declared minimum Ruby version for compatibility checks. Document source methods and non-obvious business logic in concise Chinese, preserve public return/error contracts, and never add raw device captures or credentials to examples, fixtures, logs, or release archives.
+
+## Release
+
+This directory can be maintained as the independent [ctx_checker](https://github.com/gatework/ctx_checker) repository. Update `VERSION` and `CHANGELOG.md`, run the validation and build commands above, and inspect the packaged file list before tagging `vVERSION`.
+
+CI runs tests, lint, examples, build, and an isolated installation on Linux and macOS. After CI passes on `main`, push `vVERSION` to run the release workflow. It publishes the tested Linux artifact to RubyGems and GitHub Releases, attaches `SHA256SUMS`, and verifies downloaded bytes. The GitHub `release` environment accepts a `RUBYGEMS_API_KEY` secret; without it, configure RubyGems Trusted Publishing for this repository, `release.yml`, and the `release` environment. Retry a failed publish job to reuse its CI artifact; an already published version must have identical bytes. See [release details](docs/release.md).
+
+Publish dependency gems first. A Git tag, a successful build, or a workflow file does not establish that the gem has reached RubyGems; confirm the registry result separately. See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+MIT. See [LICENSE](LICENSE).