vxlan 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cd74f1778008071770a76681129f64d7fc8d803ca27336fbac450147e33cd01
-  data.tar.gz: d4ba8a592e430b4e8c2a81e2218fe65f70c617d5fce7f60744d893a734a80b53
+  metadata.gz: c114dcb0645a2b10176e8a6cc68cdea2b517edd069c166d20b02046dddaf766a
+  data.tar.gz: edccf86d53afb7ad825c2fd468dcaba21ebda26a7b2330233fc2461840ba220f
 SHA512:
-  metadata.gz: e45e95ed6294d0f1ae0014d60ef13b1f8fad1f60a5832815b46966e1159d35b63159700410afe0f1191cb05155806b0ee5ad73050f27019e76646dfc462a5d63
-  data.tar.gz: 84d292f0dc18f67f949a73cd545293556d5e24722d995a9c161eb5a2889a89bc5cbf4afce379da9660c8bf803741a74b6b5e1ec63d47e9adac2d6214bfc65cfc
+  metadata.gz: 34c6082ad93884802d028f56cb2821cb8ae057537ba4618d7dab6e9edb3d73d27dfaebf8a6e99e502f334aecd9617e5aacc0c579070121e7c2364a5a78e3c185
+  data.tar.gz: 51864b6ddf301c26c41f3eb3fb77b46a2baa32d8047f0f806595a839ef20e32e976c022843bc7bf208794ec54ac12ed31ee2b158f9647cf1e824c191b5bd9fb1

data/CHANGELOG.md

@@ -4,6 +4,10 @@ Changes to the public contract are recorded here. Versions follow Semantic Versi
 
 ## Unreleased
 
+## 0.6.0 (2026-10-29)
+
+- Require RuntimeParser platform at construction and add parse_many. Rename Snapshot Ruby members to observations/observation while retaining dimensions in persisted reports. Use Catalog and shared Credentials in CLI; reject selected duplicate addresses across platforms before connecting.
+
 ## 0.5.1 (2026-10-24)
 
 - Validate EVPN configured-peer totals within each VRF and address-family block, retain administrative shutdown and unknown AS identities, and preserve state-valued prefix totals.

data/README-zh.md

@@ -45,7 +45,7 @@ output = <<~CLI
   Neighbor ID Pri State Up Time Address Interface
   192.0.2.2 1 FULL/ - 1d 192.0.2.3 Eth1/1
 CLI
-observation = Vxlan::RuntimeParser.new.parse(:ospf_neighbors, output, complete: true)
+observation = Vxlan::RuntimeParser.new(platform: :cisco_nxos).parse(:ospf_neighbors, output, complete: true)
 puts "OSPF parse status: #{observation.status}"
 puts "Neighbors: #{observation.records.size}"
 observation.records.each { |record| p record }
@@ -136,3 +136,10 @@ MIT，见 [LICENSE](LICENSE)。
 `vxlan collect` 默认输出逐设备诊断，使用 `--scripts` 可选导出配置建议；`vxlan review --batch DIR` 可离线补生成既有报告的候选配置、条件回退和只读验收命令。导出不会执行变更；独立 `apply --plan FILE --item ID` 必须在真实终端明确确认，配置漂移或失败即停止。详见[修复建议说明](docs/remediation.md)。 业务分层、会话所有权与执行边界见[架构说明](docs/architecture-zh.md)。
 
 报告阅读顺序与 net-connector topology 一致：`summary.txt` → `devices/*.txt` → `scripts/*.cfg`。不生成 Markdown 报告。所有可执行增量汇总于带 SHA256 校验的 `plan.json`，通过 `vxlan apply --plan plan.json --item ID` 选择一项并交互确认。
+
+
+## API 迁移
+
+`RuntimeParser.new(platform:, model: nil)` 固定解析平台；`parse(name, text, complete: false, command: nil)` 与 `parse_many(names, text, complete: false, command: nil)` 返回领域 Observation。`Snapshot.new(observations: ...)`、`#observations`、`#observation(name)` 是统一 Ruby API，旧 `dimensions` 成员及 Wireless `dimension` 入口已移除。已知未请求维度返回 `not_requested`，未知名称抛出 `ArgumentError`；持久化 JSON 仍保留 `dimensions` 字段。
+
+动态清单使用 `Netdisco::Catalog`；选中地址的任何重复记录（包括另一平台）都会阻止连接。范围外冲突只输出安全诊断。平台 `NC_<PLATFORM>_ENABLE_PASSWORD` 优先于 `NC_ENABLE_PASSWORD`。

data/README.md

@@ -45,7 +45,7 @@ output = <<~CLI
   Neighbor ID Pri State Up Time Address Interface
   192.0.2.2 1 FULL/ - 1d 192.0.2.3 Eth1/1
 CLI
-observation = Vxlan::RuntimeParser.new.parse(:ospf_neighbors, output, complete: true)
+observation = Vxlan::RuntimeParser.new(platform: :cisco_nxos).parse(:ospf_neighbors, output, complete: true)
 puts "OSPF parse status: #{observation.status}"
 puts "Neighbors: #{observation.records.size}"
 observation.records.each { |record| p record }
@@ -142,3 +142,10 @@ Review output follows the net-connector topology layout: `summary.txt`, `summary
 Apply returns `2` on failure and `130` on interruption even if stderr cannot accept diagnostics. Existing execution journals retain uncertain device effects; commands are never replayed automatically. Unexpected positional arguments are rejected, including after `--help`.
 
 Offline review requires `snapshot.target.host` to match the canonical device host. Reports without target identity must be collected again; the unbound legacy format is no longer accepted.
+
+
+## API migration
+
+`RuntimeParser.new(platform:, model: nil)` fixes the platform for `parse(name, text, complete: false, command: nil)` and `parse_many(names, text, complete: false, command: nil)`. Snapshots use `observations:` and expose `observations` / `observation(name)`; the old Ruby `dimensions` member and Wireless `dimension` accessor are removed. Known missing dimensions return `not_requested`; unknown names raise `ArgumentError`. Persisted JSON keeps its `dimensions` field.
+
+Dynamic inventory uses `Netdisco::Catalog`. Any duplicate row for a selected address, including another platform, prevents connection; excluded conflicts retain safe diagnostics. `NC_<PLATFORM>_ENABLE_PASSWORD` takes precedence over `NC_ENABLE_PASSWORD`.

data/examples/offline.rb

@@ -9,7 +9,7 @@ output = <<~CLI
   Neighbor ID Pri State Up Time Address Interface
   192.0.2.2 1 FULL/ - 1d 192.0.2.3 Eth1/1
 CLI
-observation = Vxlan::RuntimeParser.new.parse(:ospf_neighbors, output, complete: true)
+observation = Vxlan::RuntimeParser.new(platform: :cisco_nxos).parse(:ospf_neighbors, output, complete: true)
 puts "OSPF parse status: #{observation.status}"
 puts "Neighbors: #{observation.records.size}"
 observation.records.each { |record| p record }

data/lib/vxlan/cli/collect.rb

@@ -34,17 +34,27 @@ module Vxlan
       def load_network
         require "net/connector"
       rescue LoadError
-        raise LoadError, "Online collection requires net-connector >= 0.18.0; add it to the host Gemfile or run gem install net-connector", cause: nil
+        raise LoadError, "Online collection requires net-connector >= 0.19.0; add it to the host Gemfile or run gem install net-connector", cause: nil
       end
 
-      # YAML 静态设备或显式 Netdisco 来源二选一；所有重复地址在连接前拒绝。
+      # YAML 静态设备或显式 Netdisco 来源二选一；选中地址的所有冲突记录在连接前拒绝。
       def inventory(options, progress:)
         values = options.values
+        selection = Net::Connector::Inventory::Filters.selection(values)
         rows = if options.dynamic_inventory?
           progress.reading_inventory
           settings = options.netdisco_settings
-          Net::Connector::Netdisco::Fleet.new(settings: settings).devices.filter_map do |device|
-            next unless device.ready? && device.vendor == :cisco_nxos
+          policy = settings.snapshot(mode: :inventory)
+          devices = Net::Connector::Netdisco::Catalog.new(settings: settings).devices(policy: policy)
+          devices.filter_map(&:issue).tally.each { |code, count| progress.notice("Inventory: #{code}=#{count}") }
+          devices.filter_map do |device|
+            next unless device.vendor == :cisco_nxos
+            platform = "cisco_nxos"
+            if device.issue == :duplicate_host && policy.rules.selected?(device.host, device.vendor, name: device.name, model: device.model) &&
+                selection.selected?(device.host, platform, name: device.name || device.host, model: device.model)
+              raise CtxCli::Collection::Error, "Duplicate management address in selected inventory"
+            end
+            next unless device.ready?
             { "host" => device.host, "name" => device.name || device.host, "model" => device.model }
           end
         else
@@ -52,7 +62,6 @@ module Vxlan
         end
         targets = options.normalize_devices(rows)
         total = targets.size
-        selection = Net::Connector::Inventory::Filters.selection(values)
         selected = targets.select do |device|
           selection.selected?(device.fetch("host"), "cisco_nxos", name: device["name"], model: device["model"])
         end
@@ -86,16 +95,10 @@ module Vxlan
 
       # 缺失用户名时不尝试连接；密码允许省略以支持明确的 SSH key/agent。
       def credentials!(options)
-        username = secret(options, "NC_CISCO_NXOS_USERNAME") || secret(options, "NC_DEVICE_USERNAME")
-        raise CtxCli::Collection::Error, "Set NC_DEVICE_USERNAME or NC_CISCO_NXOS_USERNAME; provide a password through the environment or use an SSH key/agent" unless username
-        options.values.fetch("ssh").transform_keys(&:to_sym).merge(username: username,
-          password: secret(options, "NC_CISCO_NXOS_PASSWORD") || secret(options, "NC_DEVICE_PASSWORD"), enable_password: secret(options, "NC_ENABLE_PASSWORD"))
-      end
-
-      # 空白环境值视为缺失，不修改或回显凭据。
-      def secret(options, name)
-        value = options.environment[name]
-        value unless value.nil? || value.strip.empty?
+        require "net/connector/credentials"
+        credentials = Net::Connector::Credentials.new(env: options.environment).resolve(platform: :cisco_nxos)
+        raise CtxCli::Collection::Error, "Set NC_DEVICE_USERNAME or platform NC_*_USERNAME; provide a password through the environment or use an SSH key/agent" unless credentials
+        options.values.fetch("ssh").transform_keys(&:to_sym).merge(credentials)
       end
 
       # 每个任务使用独立 Collector 和会话；公共执行器负责有界并发和线程回收。
@@ -114,7 +117,7 @@ module Vxlan
         snapshot
       end
 
-      private :load_network, :credentials!, :secret
+      private :load_network, :credentials!
     end
   end
 end

data/lib/vxlan/cli/options.rb

@@ -6,7 +6,7 @@ require "optparse"
 require "ctx_cli/options"
 require "ctx_cli/terminal"
 require "ctx_cli/initializer"
-gem "net-connector", "~> 0.18.0"
+gem "net-connector", "~> 0.19.0"
 require "net/connector/inventory/filters"
 require "yaml"
 require "ipaddr"
@@ -67,7 +67,7 @@ module Vxlan
         @environment = @files.environment
         @config, @env_file = @files.config, @files.env_file
       rescue LoadError
-        raise LoadError, "Collection configuration requires net-connector >= 0.18.0; reading .env also requires dotenv", cause: nil
+        raise LoadError, "Collection configuration requires net-connector >= 0.19.0; reading .env also requires dotenv", cause: nil
       end
 
       # 公共与专用文件先合并，进程值和 CLI 最后覆盖；数组不追加设备。

data/lib/vxlan/cli/parse.rb

@@ -37,7 +37,7 @@ module Vxlan
         observation = if options[:dimension] == :configuration
           Vxlan::Config.new(model: options[:model]).parse(body, complete: options[:complete])
         else
-          Vxlan::RuntimeParser.new(model: options[:model]).parse(options[:dimension], body, complete: options[:complete])
+          Vxlan::RuntimeParser.new(platform: :cisco_nxos, model: options[:model]).parse(options[:dimension], body, complete: options[:complete])
         end
         if options[:json]
           @output.json(observation.to_h)

data/lib/vxlan/collector.rb

@@ -85,7 +85,7 @@ module Vxlan
         :failed
       end
       observations[:collection] ||= Observation.new(name: :collection, status: status, completed_at: @clock.call)
-      Snapshot.new(target: target, fabric_key: fabric_key, dimensions: observations, observed_at: @clock.call)
+      Snapshot.new(target: target, fabric_key: fabric_key, observations: observations, observed_at: @clock.call)
     end
 
     # 采集设备回显前，禁用分页并归一化终端宽度。

data/lib/vxlan/runtime_parser.rb

@@ -7,16 +7,24 @@ module Vxlan
   # 将纯平台解析事实封装为对应 VXLAN 维度观测。
   class RuntimeParser
     # 按请求的平台和型号选择运行解析行为。
-    def initialize(platform: :cisco_nxos, model: nil)
+    def initialize(platform:, model: nil)
       @profile = ParserRegistry.fetch(platform, model: model)
     end
 
     # 拒绝配置维度，仅解析所选 VXLAN 运行查询。
-    def parse(name, text, complete: false)
-      raise ArgumentError, "Unsupported runtime dimension" if name == :configuration || !@profile.commands.key?(name)
+    def parse(name, text, complete: false, command: nil)
+      parse_many([ name ], text, complete: complete, command: command).fetch(name)
+    end
 
-      result = @profile.parse(name, text, complete: complete)
-      Observation.new(name: name, **result.to_h)
+    # 单条正文只允许投影属于同一声明命令的运行维度。
+    def parse_many(names, text, complete: false, command: nil)
+      unless names.is_a?(Array) && names.any? && names.uniq == names &&
+          names.all? { |name| name.is_a?(Symbol) && name != :configuration && @profile.commands.key?(name) }
+        raise ArgumentError, "Unsupported runtime dimensions"
+      end
+      @profile.parse_many(names, text, complete: complete, command: command).to_h do |name, result|
+        [ name, Observation.new(name: name, **result.to_h) ]
+      end
     end
   end
 end

data/lib/vxlan/snapshot.rb

@@ -2,23 +2,35 @@
 
 require "ctx_parser/immutable"
 require_relative "observation"
+require_relative "parser_registry"
 
 module Vxlan
   # 携带单设备 Fabric 身份及观测结果，不管理资产清单。
-  Snapshot = Data.define(:target, :fabric_key, :dimensions, :observed_at) do
+  Snapshot = Data.define(:target, :fabric_key, :observations, :observed_at) do
     # 事实由不可变领域观测持有；仅复制维度选择，不重复复制事实。
-    def initialize(target:, fabric_key:, dimensions:, observed_at:)
-      unless dimensions.is_a?(Hash) && dimensions.all? { |name, value| value.is_a?(Observation) && value.name == name }
+    def initialize(target:, fabric_key:, observations:, observed_at:)
+      unless observations.is_a?(Hash) && observations.all? { |name, value| value.is_a?(Observation) && value.name == name }
         raise ArgumentError, "Dimensions must match their observations"
       end
 
       super(target: CtxParser::Immutable.copy(target), fabric_key: CtxParser::Immutable.copy(fabric_key),
-        dimensions: dimensions.to_h { |name, value| [ name, value ] }.freeze, observed_at: observed_at&.dup&.freeze)
+        observations: observations.to_h { |name, value| [ name, value ] }.freeze, observed_at: observed_at&.dup&.freeze)
     end
 
+    # 未请求的已知维度保留明确状态；未知维度属于调用错误。
+    def observation(name)
+      unless name == :collection || CiscoNxos::Profile::COMMANDS.key?(name)
+        raise ArgumentError, "Unknown VXLAN dimension"
+      end
+      observations.fetch(name) { Observation.new(name: name, status: :not_requested) }
+    end
+
+    # 报告格式独立于 Ruby 成员命名，已有离线证据继续使用 dimensions。
+    def to_h = super.except(:observations).merge(dimensions: observations)
+
     # 判断所有已选事实是否都有完整证据支持。
     def complete?
-      selected = dimensions.values.reject { |dimension| dimension.status == :not_requested }
+      selected = observations.values.reject { |dimension| dimension.status == :not_requested }
       selected.any? && selected.all?(&:complete?)
     end
 

data/lib/vxlan/version.rb

@@ -2,5 +2,5 @@
 
 module Vxlan
   # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vxlan
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Gatework contributors
@@ -29,42 +29,60 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: ctx_parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: ctx_driver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: digest
   requirement: !ruby/object:Gem::Requirement