net-connector 0.19.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe3f1f3bc71cf02e0007ec892699ea03fb13f30b697f5e318ca256159e77a466
-  data.tar.gz: 7f2ed60b91541c0eb362b1dc1c063661f5f22eac07719f1ed9d56f552a7d175b
+  metadata.gz: 7e379dbe5598c3f170fdcfbc123103c4eb178941508e8fa0df12e2b8043fdf93
+  data.tar.gz: 3ad7934b5aa811031ea1a1283c67743494795472a0361207869d6b16d03cfda0
 SHA512:
-  metadata.gz: 03ea333dc6fdc10956b58478de7b67d8e3061345b3d96af8601a847dd393b158cd0bdbd7e4ca3ebc69c7cdca03d58ced76e34964b0370d9b2b0dad27c4d1f9dc
-  data.tar.gz: 38784dee207a4b5161add61183ebb49cf7b4a7a843171a29da2effe393105cd9c4bd00f2a0d3780ab296c430149a43792c85b9054375cb1c97269e89b1ad7f96
+  metadata.gz: 07e68bd1ebd341839e6c45db6e821e76f8371c7b5d2e135a064925be5ca6f0d06189cf22be97fd2d8ea676fc542216dc67bfeff88fd06043b310fe72e642b67b
+  data.tar.gz: 96400e19508ca207d0e4aeccb0dc5aad7529bafebb0e2a4723a10e9d3907e07c5ba9f722afaabf5d78f257184f2b7f27aab82da91c7e64f60ca005188d1aa445

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.21.0 - 2026-10-30
+
+- Rename neighbor fields to `remote_name`, `remote_interface` and `remote_chassis_id`, retaining `local_interface`. Collection progress reads schema 4 `target`; require ctx_cli 0.5. No legacy accessor aliases.
+
+## 0.20.0 - 2026-10-29
+
+- Require the latest stable TextFSM 0.5.1, align the minimum dependency matrix, and verify JSON 3 with its original published package instead of a source metadata patch.
+
+- Recheck streamed archive content on the pinned descriptor so same-timestamp overwrites cannot receive a successful copy or delivery receipt.
+
+- Bound compatible ctx_cli and expect-pty dependencies to the contract versions tested with this release (ctx_cli 0.4.x and expect-pty 0.9.6 through 0.9.x).
+
 ## 0.19.0 - 2026-10-29
 
 - Extract `Netdisco::Catalog#devices(policy:)` for immutable inventory without credentials or operations; Fleet delegates inventory access. Add live, injected `Credentials#resolve(platform:)` with platform-specific username/password/enable-password precedence and independent secret snapshots.

data/README.md

@@ -4,7 +4,7 @@
 
 Ruby sessions for network device CLIs over SSH or Telnet. Collect configurations, save private backups, run interactive scripts, parse output with TextFSM, and back up fleets from Netdisco inventories.
 
-Requires Ruby 3.4+, expect-pty 0.9.4+ and a POSIX system. SSH uses local OpenSSH; Telnet requires a local `telnet` executable and explicit configuration.
+Requires Ruby 3.4+, expect-pty 0.9.6+, ctx_cli 0.4.x, TextFSM 0.5.1+ and a POSIX system. SSH uses local OpenSSH; Telnet requires a local `telnet` executable and explicit configuration.
 
 ## Install
 
@@ -85,3 +85,7 @@ credentials = Net::Connector::Credentials.new(env: ENV).resolve(platform: :cisco
 Catalog owns inventory reading, normalization, duplicate marking and cache status (`#status`). It does not resolve device credentials, log into devices or create operation reports. Pass one policy snapshot throughout a run. Fleet delegates to Catalog and retains operation orchestration.
 
 Credentials reads the injected environment on every `resolve`; it returns an independent frozen hash, or nil when no username is available. Platform-specific `NC_<PLATFORM>_USERNAME`, `_PASSWORD`, and `_ENABLE_PASSWORD` override `NC_DEVICE_USERNAME`, `NC_DEVICE_PASSWORD`, and `NC_ENABLE_PASSWORD` respectively. Blank values fall back. Secrets are never cached or included in object inspection.
+
+## Domain contract migration (2026-10-30)
+
+Rename neighbor fields to `remote_name`, `remote_interface` and `remote_chassis_id`, retaining `local_interface`. Collection progress reads schema 4 `target`; require ctx_cli 0.5. No legacy accessor aliases. See the [schema 4 migration and module contracts](https://github.com/gatework/ctx_runner/blob/main/docs/contracts-2026-10-30.md). Regenerate old collection reports and change plans; changing only their version number is not supported.

data/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 通过 SSH 或 Telnet 操作网络设备的 Ruby 库。支持配置采集、私有备份、交互脚本、TextFSM 解析，以及基于 Netdisco 清单的批量备份。
 
-需要 Ruby 3.4+、expect-pty 0.9.4+ 和 POSIX 系统。SSH 使用本机 OpenSSH；Telnet 需要本机安装 `telnet` 并显式配置。
+需要 Ruby 3.4+、expect-pty 0.9.6+、ctx_cli 0.4.x、TextFSM 0.5.1+ 和 POSIX 系统。SSH 使用本机 OpenSSH；Telnet 需要本机安装 `telnet` 并显式配置。
 
 ## 安装
 

data/docs/VERIFICATION.md

@@ -155,7 +155,7 @@ SHA-256，首次使用时从官方 GitHub Release 下载，缓存到 `tmp/tools/
 
 运行依赖写在 `net-connector.gemspec`，包括直接使用的、可能从 Ruby 默认
 安装中拆出的标准库 gem。开发工具只写在 Gemfile，不进入运行依赖。
-PTY 与共享脱敏直接依赖 expect-pty 0.9.4+ 的公开 `Session`、`buffer_bytesize` 和 `Expect::Redactor` 接口。
+PTY 与共享脱敏直接依赖 expect-pty 0.9.6+ 的公开 `Session`、`buffer_bytesize` 和 `Expect::Redactor` 接口。
 开发用 `parallel` 保持 1.x。升级 expect-pty 时先验证源码集成，再用本次构建的 gem 验证隔离安装；
 新依赖版本发布前不得将本地构建验证记成已发布版本验收，也不能退回旧接口掩盖依赖缺失。
 
@@ -163,7 +163,7 @@ PTY 与共享脱敏直接依赖 expect-pty 0.9.4+ 的公开 `Session`、`buffer_
 分别解析兼容依赖。应用使用者应在自己的应用中提交 lockfile。测试和打包
 脚本通过隔离安装检查运行依赖，避免依赖开发环境里偶然存在的 gem。
 
-`gemfiles/minimum.gemfile` 固定受支持的依赖下界 expect-pty 0.9.4、textfsm 0.2.0；
+`gemfiles/minimum.gemfile` 固定受支持的依赖下界 expect-pty 0.9.6、ctx_cli 0.4.0、textfsm 0.5.1；
 标准库和开发工具仍按主 Gemfile 的兼容范围解析。普通矩阵检查允许版本的正常解析，
 另在 Ubuntu / Ruby 3.4、4.0 检查这组版本的全量测试与隔离安装。本地复现：
 
@@ -206,17 +206,16 @@ Gitleaks 默认规则之外，还检查网络设备密码/SNMP community 配置
 扫描工具不会自动改写 Git 历史或真实设备备份。规则用于拦截常见泄露，
 发布前仍需人工确认设备名称、拓扑和业务配置等上下文信息是否适合公开。
 
-## JSON 2 发布依赖与 JSON 3 源码兼容分开验证
+## 使用已发布 TextFSM 分别验证 JSON 2 与 JSON 3
 
-默认及最低依赖任务验证实际发布依赖。TextFSM 0.2.0 的公开声明仍为 `json ~> 2.0`；
-本地同版本 gem 的修订不能证明普通消费者能安装 JSON 3。
+运行依赖要求 TextFSM 0.5.1 或更新版本；0.5.1 的公开 JSON 声明为 `>= 2.0`，
+允许普通消费者选择 JSON 2 或 JSON 3。最低依赖任务固定 TextFSM 0.5.1 与 JSON 2。
 
-CI 的 `json3-source-compatibility` 在 Ruby 3.4 / 4.0 检出固定 TextFSM commit
-`733340de378f2d7fbe530b48f2cf1dd6c30c69b0`，应用仓库内
-`script/compatibility/textfsm-json3.patch`，只放宽依赖声明，再执行完整测试和真实打包隔离安装。
-该任务明确代表尚未发布依赖声明下的源码兼容性；不自动发布、替换正式依赖或修改用户的全局 gem。
+CI 的 `json3-compatibility` 在 Ruby 3.4 / 4.0 使用已发布 TextFSM 0.5.1 与 JSON 3，
+执行完整测试和真实打包隔离安装。脚本核对原始 gem 的 JSON 依赖声明，再将发布包缓存
+交给隔离消费者；不再检出旧源码、修改 metadata 或重建同版本 TextFSM。
 
-复现时，在 `tmp/json3/textfsm` 准备该源码并应用补丁，然后运行：
+本地复现：
 
 ```sh
 BUNDLE_GEMFILE=gemfiles/json3.gemfile bundle install

data/docs/usage.md

@@ -165,6 +165,6 @@ Per-command prompts use `interactions: [Net::Connector::Interaction.new(/Token:\
 
 ## Dependencies and extensions
 
-Load device APIs with `require "net/connector"`; Netdisco has a separate entrypoint. Vendor implementations and TextFSM load on demand. The gemspec requires expect-pty 0.9.4+; the host application's lockfile selects concrete dependency versions. The minimum dependency matrix uses TextFSM 0.2.0 and JSON 2, with a separate fixed-source TextFSM patch matrix for JSON 3.
+Load device APIs with `require "net/connector"`; Netdisco has a separate entrypoint. Vendor implementations and TextFSM load on demand. The gemspec requires expect-pty 0.9.6+, ctx_cli 0.4.x and TextFSM 0.5.1+; the host application's lockfile selects concrete dependency versions. The minimum dependency matrix uses TextFSM 0.5.1 and JSON 2. A separate JSON 3 matrix uses the same published TextFSM package without modifying its dependency metadata.
 
 CLI entry points share layered configuration and `.env` loading; dotenv is a declared runtime dependency. Core library calls do not discover host files. Follow the [loading and migration reference](architecture.md#加载入口与厂商策略) (Chinese) for custom profiles, strategies, and protected hooks.

data/docs/usage.zh-CN.md

@@ -2,11 +2,11 @@
 
 [English](usage.md) | [返回首页](../README.zh-CN.md) | [Netdisco 批量备份](netdisco.zh-CN.md)
 
-支持 Ruby 3.4 及以上版本和 POSIX 系统。SSH 调用本机 OpenSSH，Telnet 需要本机安装 `telnet` 并显式选择。要求 [`expect-pty`](https://rubygems.org/gems/expect-pty) 0.9.4 及以上；[`textfsm`](https://rubygems.org/gems/textfsm) 由宿主选择版本，最低依赖测试覆盖 0.2.0。
+支持 Ruby 3.4 及以上版本和 POSIX 系统。SSH 调用本机 OpenSSH，Telnet 需要本机安装 `telnet` 并显式选择。要求 [`expect-pty`](https://rubygems.org/gems/expect-pty) 0.9.6 及以上、ctx_cli 0.4.x 和 [`textfsm`](https://rubygems.org/gems/textfsm) 0.5.1 及以上；具体版本由宿主锁定。
 
 脱敏直接复用 expect-pty 的公开 `Expect::Redactor` 接口；连接器只管理秘密作用域和配置输出的隐私策略。
 
-gemspec 声明 expect-pty 的接口版本下界；宿主应用通过自己的 Gemfile 和锁文件固定具体依赖版本。最低依赖组合使用 textfsm 0.2.0 与 JSON 2；JSON 3 另有固定 TextFSM 源码及显式依赖声明补丁的验证通道。开发工具及测试矩阵的版本约束不进入 gem 的运行依赖。
+gemspec 声明所需接口的版本下界；宿主应用通过自己的 Gemfile 和锁文件固定具体依赖版本。最低依赖组合使用 textfsm 0.5.1 与 JSON 2；JSON 3 矩阵也使用同一已发布 TextFSM 包，无需源码或 metadata 补丁。开发工具及测试矩阵的版本约束不进入 gem 的运行依赖。
 
 CLI 与示例入口共用分层配置和 `.env` 加载，dotenv 已声明为运行时依赖；核心库调用不自动发现宿主文件。
 

data/lib/net/connector/collect/progress.rb

@@ -27,7 +27,7 @@ module Net
                     when "partial" then "Partially complete (#{code})"
                     else "Incomplete (#{code})"
                     end
-          super(host: result.fetch("device").fetch("host"), success: status == "complete",
+          super(host: result.fetch("target").fetch("host"), success: status == "complete",
                 duration_ms: result.fetch("duration_ms"), message: message, error_code: code&.to_sym)
         end
 

data/lib/net/connector/device/interfaces/audit.rb

@@ -64,7 +64,7 @@ module Net
         def inspect_interface(interface, peers)
           peer = peers.first
           current = @descriptions[interface]
-          row = { interface: peer.local_interface, neighbor: peer.neighbor_name, port: peer.neighbor_interface,
+          row = { interface: peer.local_interface, neighbor: peer.remote_name, port: peer.remote_interface,
                   current: current, expected: nil, status: :unverified }
           @comparisons << row
           if peers.size != 1
@@ -78,7 +78,7 @@ module Net
           local = @strategy.configuration_interface(peer.local_interface)
           Description.validate_interface!(local)
           row.merge!(expected: proposed, status: compare_status(current, proposed, peer))
-          @evidence[interface] = [peer.neighbor_name, peer.neighbor_interface, current]
+          @evidence[interface] = [peer.remote_name, peer.remote_interface, current]
           return if row[:status] == :matches
 
           @changes << Change.new(interface: local, old_description: current, new_description: proposed, neighbor: peer)

data/lib/net/connector/device/interfaces/description.rb

@@ -10,11 +10,11 @@ module Net
         # 将邻居名称和接口拼成默认描述；统一邻居接口简称，原始发现记录保持不变。
         def self.format(neighbor, abbreviate: true, lowercase: false)
           port = if abbreviate
-                   Name.short(neighbor.neighbor_interface, lowercase: lowercase)
+                   Name.short(neighbor.remote_interface, lowercase: lowercase)
                  else
-                   lowercase ? neighbor.neighbor_interface.downcase : neighbor.neighbor_interface
+                   lowercase ? neighbor.remote_interface.downcase : neighbor.remote_interface
                  end
-          validate!("To_#{neighbor.neighbor_name.tr(" ", "_")}_#{port.tr(" ", "_")}")
+          validate!("To_#{neighbor.remote_name.tr(" ", "_")}_#{port.tr(" ", "_")}")
         end
 
         # 保留语义相同的旧描述；只归一末尾已知接口别名和大小写，不模糊匹配名称或端口编号。

data/lib/net/connector/device/interfaces/neighbor.rb

@@ -4,11 +4,11 @@ module Net
   module Connector
     class Interfaces
       # 邻居身份拥有独立字符串，格式化回调不能改写发现证据。
-      Neighbor = Data.define(:local_interface, :neighbor_name, :neighbor_interface, :chassis_id, :protocol) do
+      Neighbor = Data.define(:local_interface, :remote_name, :remote_interface, :remote_chassis_id, :protocol) do
         # 复制并冻结本地端口、邻居名称、远端端口及发现协议。
-        def initialize(local_interface:, neighbor_name:, neighbor_interface:, chassis_id:, protocol:)
-          fields = { local_interface: local_interface, neighbor_name: neighbor_name,
-                     neighbor_interface: neighbor_interface, chassis_id: chassis_id }
+        def initialize(local_interface:, remote_name:, remote_interface:, remote_chassis_id:, protocol:)
+          fields = { local_interface: local_interface, remote_name: remote_name,
+                     remote_interface: remote_interface, remote_chassis_id: remote_chassis_id }
           raise ArgumentError, "neighbor fields must be Strings" unless fields.values.all?(String)
           raise ArgumentError, "neighbor protocol must be a Symbol" unless protocol.is_a?(Symbol)
 
@@ -18,8 +18,8 @@ module Net
         # 原始发现数据保留占位符；规划与下发重验共用身份校验，不能把未知名称写入描述。
         # MAC 是合法的 LLDP Port ID，不凭地址形状猜测设备角色，也不拿 chassis ID 补造名称。
         def identity_issue
-          return :unknown_neighbor_name if unknown_identity?(neighbor_name)
-          return :unknown_neighbor_interface if unknown_identity?(neighbor_interface)
+          return :unknown_neighbor_name if unknown_identity?(remote_name)
+          return :unknown_neighbor_interface if unknown_identity?(remote_interface)
 
           nil
         end

data/lib/net/connector/device/interfaces.rb

@@ -88,9 +88,9 @@ module Net
 
         rows.map do |row|
           Neighbor.new(local_interface: row.fetch("LOCAL_INTERFACE").strip.freeze,
-                       neighbor_name: row.fetch("NEIGHBOR_NAME", "").strip.freeze,
-                       neighbor_interface: row.fetch("NEIGHBOR_INTERFACE").strip.freeze,
-                       chassis_id: row.fetch("CHASSIS_ID", "").strip.freeze,
+                       remote_name: row.fetch("NEIGHBOR_NAME", "").strip.freeze,
+                       remote_interface: row.fetch("NEIGHBOR_INTERFACE").strip.freeze,
+                       remote_chassis_id: row.fetch("CHASSIS_ID", "").strip.freeze,
                        protocol: @strategy.protocol).freeze
         end
       end
@@ -272,7 +272,7 @@ module Net
         plan.changes.each do |change|
           Description.validate!(change.new_description)
           unless evidence.fetch(@strategy.interface_key(change.interface)) ==
-                 [change.neighbor.neighbor_name, change.neighbor.neighbor_interface, change.old_description]
+                 [change.neighbor.remote_name, change.neighbor.remote_interface, change.old_description]
             raise ArgumentError, "plan changes do not match its discovery evidence"
           end
         end
@@ -319,7 +319,7 @@ module Net
 
         interfaces.transform_values do |peers|
           peer = peers.fetch(0)
-          [peer.neighbor_name, peer.neighbor_interface, current.fetch(@strategy.interface_key(peer.local_interface))].freeze
+          [peer.remote_name, peer.remote_interface, current.fetch(@strategy.interface_key(peer.local_interface))].freeze
         end.freeze
       end
 

data/lib/net/connector/netdisco/ssh/archive/worker.py

@@ -130,6 +130,21 @@ def read_file(parent, name, missing=False, consume=None):
             digest.update(chunk)
             if consume is not None and consume(chunk) != len(chunk):
                 raise IOError("incomplete file write")
+        # 同一时钟粒度内的覆写可能不改变 stat 时间；投递后重读摘要核对已发送字节。
+        if consume is not None:
+            f.seek(0)
+            verified = hashlib.sha256()
+            verified_size = 0
+            while True:
+                chunk = f.read(CHUNK_BYTES)
+                if not chunk:
+                    break
+                verified_size += len(chunk)
+                if verified_size > MAX_BYTES:
+                    raise ValueError("oversized file")
+                verified.update(chunk)
+            if verified_size != size or verified.digest() != digest.digest():
+                raise ValueError("file changed while delivering")
         after = os.fstat(f.fileno())
         if size != after.st_size or fingerprint(before) != fingerprint(after):
             raise ValueError("file changed while reading")

data/lib/net/connector/netdisco/topology/options.rb

@@ -51,10 +51,10 @@ module Net
 
           # 使用当前模板和端口展示策略生成缺失或确需修正的目标描述。
           def description_for(neighbor)
-            port = neighbor.neighbor_interface
+            port = neighbor.remote_interface
             port = Net::Connector::Interfaces::Name.short(port) if abbreviate_ports
             port = port.downcase if lowercase_ports
-            format(neighbor: neighbor.neighbor_name, port: port)
+            format(neighbor: neighbor.remote_name, port: port)
           end
 
           # 仅显式声明的旧名称前缀可保留；不把未知名称、包含匹配或不同编号当作同一邻居。
@@ -63,7 +63,7 @@ module Net
             return true if comparison.equivalent?(current, expected)
 
             neighbor_name_prefixes.any? do |prefix|
-              variant = neighbor.with(neighbor_name: prefix + neighbor.neighbor_name)
+              variant = neighbor.with(remote_name: prefix + neighbor.remote_name)
               comparison.equivalent?(current, description_for(variant))
             end
           end

data/lib/net/connector/version.rb

@@ -3,6 +3,6 @@
 module Net
   module Connector
     # gemspec、CLI 与发布工具共用此版本，运行时读取不触发设备依赖加载。
-    VERSION = "0.19.0"
+    VERSION = "0.21.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.21.0
 platform: ruby
 authors:
 - net-connector contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-29 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ctx_cli
@@ -15,42 +15,54 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.5.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.5.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: expect-pty
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.6
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.6
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: textfsm
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.5.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.5.1
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement