vxlan 0.2.3 → 0.3.0

data/lib/vxlan/service/catalog.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Vxlan
+  module Service
+    # L2 业务由 VLAN、NVE、EVPN 的联合事实识别；缺一个环节仍是已开始部署。
+    class Catalog
+      # 配置完整性由调用方保证，目录本身不读取设备或推断部署意图。
+      def initialize(configs)
+        @configs = configs
+      end
+
+      # 一个 VNI 可有多个本地 VLAN 事实，交给审查明确报告歧义。
+      def services
+        result = Hash.new { |hash, vni| hash[vni] = [] }
+        @configs.each do |host, config|
+          mappings = config.fetch("vlan_vnis", {})
+          nve = config.fetch("nve", {}).fetch("members", {})
+          evpn = config.fetch("evpn", {})
+          l3 = config.fetch("vrfs", {}).values.filter_map { |vrf| vrf["vni"] }
+          l2 = evpn.filter_map { |vni, member| Integer(vni) if member["type"] == "l2" }
+          l2.concat(nve.filter_map { |vni, member| Integer(vni) unless member["associate_vrf"] })
+          l3.concat(nve.filter_map { |vni, member| Integer(vni) if member["associate_vrf"] })
+          l3.concat(evpn.filter_map { |vni, member| Integer(vni) if member["type"] == "l3" })
+          vnis = (mappings.values.compact - l3 + l2).uniq
+          mappings_by_vni = mappings.group_by { |_vlan, vni| vni }
+          vnis.sort.each do |vni|
+            vlans = mappings_by_vni.fetch(vni, []).map(&:first)
+            (vlans.empty? ? [ nil ] : vlans).each do |vlan|
+              member, control = nve[vni.to_s], evpn[vni.to_s]
+              missing = []
+              missing << "VLAN" unless vlan
+              missing << "NVE" unless member
+              missing << "NVE L2" if member && member["associate_vrf"]
+              missing << "EVPN" if config["nv_overlay_evpn"] && !control
+              missing << "EVPN L2" if control && control["type"] != "l2"
+              result[vni] << { host: host, config: config, vlan: vlan, svi: vlan && config.fetch("interfaces", {})["Vlan#{vlan}"],
+                nve: member, evpn: control, missing: missing }
+            end
+          end
+        end
+        result
+      end
+
+      # 成员未指定复制方式时继承全局组播；显式 BGP/成员组播优先。
+      def self.nve_member(config, member)
+        return nil unless member
+        inherited = config.dig("nve", "multicast_group")
+        if inherited && !member["replication"] && !member["multicast_group"] && !member["associate_vrf"]
+          member.merge("multicast_group" => inherited)
+        else
+          member
+        end
+      end
+
+      # 两字节 AS 的 auto RT 为 AS:VNI；其他 AS 形式保留声明，不猜测版本相关派生行为。
+      def self.route_targets(entries, asn:, vni:)
+        Array(entries).flat_map do |entry|
+          directions = entry["direction"] == "both" ? %w[import export] : [ entry["direction"] ]
+          directions.map do |direction|
+            target = entry["target"]
+            target = asn.is_a?(Integer) && asn.between?(1, 65_535) ? "#{asn}:#{vni}" : [ "auto", asn, vni ] if target == "auto"
+            [ entry["address_family"], entry.fetch("evpn", false), direction, target ]
+          end
+        end.uniq.sort_by { |entry| JSON.generate(entry) }
+      end
+
+      # 租户出口细节可以因 Border 职责不同而不同，此投影只比较 VNI 与导入导出声明。
+      def self.tenant(config, name)
+        vrf = config.fetch("vrfs", {})[name]
+        return nil unless vrf
+        { "vrf" => name, "vni" => vrf["vni"], "route_targets" => route_targets(vrf["route_targets"], asn: config.dig("bgp", "asn"), vni: vrf["vni"]) }
+      end
+    end
+  end
+end

data/lib/vxlan/service/mapping.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../change_plan"
+require_relative "../acl_policy"
+require_relative "catalog"
+
+module Vxlan
+  module Service
+    # 由完整同业务对端证明关联关系，而不是通过 VNI 数字编码猜测 VLAN。
+    class Mapping
+      # 只接受同 Fabric、同角色业务行，返回已校验的业务增量对象或未知。
+      def self.infer(vni, row, peers)
+        return nil unless peers.map { |peer| peer[:host] }.uniq.size == peers.size
+        donors = peers.reject { |peer| peer[:host] == row[:host] }
+        return nil unless donors.any? && donors.all? { |peer| peer[:missing].empty? && peer[:svi] }
+        signatures = donors.map { |peer| signature(peer[:config], peer[:svi]) }.uniq
+        return nil unless signatures.one? && signatures.first
+        expected = signatures.first
+        return nil unless transport_matches?(vni, row, donors)
+        matches = row[:config].fetch("vlan_vnis", {}).filter_map do |vlan, mapped|
+          next unless mapped.nil?
+          svi = row[:config].fetch("interfaces", {})["Vlan#{vlan}"]
+          vlan if svi && signature(row[:config], svi) == expected
+        end
+        return nil unless matches.one?
+        change = { "kind" => "vlan_vni_add", "vlan" => Integer(matches.first), "vni" => vni, "vrf" => expected["vrf"], "address" => expected["addresses"].first }
+        ChangePlan.candidate(change, config: row[:config])
+      end
+
+      # 网关、租户、ACL 及其依赖一起界定业务；缺失 Anycast 身份不能当成一致。
+      def self.signature(config, svi)
+        return nil unless svi["anycast"] && svi["vrf"] && svi.fetch("addresses", []).one? && config["anycast_mac"]
+        policies = svi.fetch("acl_bindings", {}).to_h do |direction, name|
+          policy = AclPolicy.resolve(config, config.fetch("acls", {})[name])
+          return nil unless policy
+          [ direction, policy.to_h ]
+        end
+        svi.slice("addresses", "vrf", "anycast", "shutdown", "mtu").merge("anycast_mac" => config["anycast_mac"], "policies" => policies)
+      end
+
+      # 本机已有 NVE/EVPN 与对端语义一致才允许连接 VLAN；路由冲突不能靠补绑定解决。
+      def self.transport_matches?(vni, row, donors)
+        values = [ row, *donors ].map do |peer|
+          next nil unless peer[:nve] && peer[:evpn]
+          config = peer[:config]
+          vrf = peer[:svi]&.dig("vrf") || donors.first[:svi]["vrf"]
+          [ Catalog.nve_member(config, peer[:nve]), peer[:evpn]["type"], Catalog.route_targets(peer[:evpn]["route_targets"], asn: config.dig("bgp", "asn"), vni: vni), Catalog.tenant(config, vrf) ]
+        end
+        values.none?(&:nil?) && values.uniq.one?
+      end
+    end
+  end
+end

data/lib/vxlan/snapshot.rb

@@ -25,5 +25,8 @@ module Vxlan
     # 展示对象身份与状态，避免泄露原始回显或凭据。
     def inspect = "#<#{self.class.name} fabric=#{fabric_key.inspect} complete=#{complete?}>"
     alias to_s inspect
+
+    # PP 默认展开 Data 成员，显式沿用脱敏展示。
+    def pretty_print(printer) = printer.text(inspect)
   end
 end

data/lib/vxlan/subnet_index.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "ctx_parser/immutable"
+
+module Vxlan
+  # 单设备 SVI 网段索引；按 VRF 和地址族查重叠，保留接口顺序和重复来源。
+  class SubnetIndex
+    Entry = Data.define(:interface, :vni, :address, :position, :first, :prefix)
+    private_constant :Entry
+
+    # 仅保存查询所需的独立事实；未解析地址不能作为无重叠证据。
+    def initialize(config)
+      groups, invalid = {}, {}
+      position = 0
+      config.fetch("interfaces", {}).each do |name, svi|
+        next unless name.match?(/\AVlan\d+\z/)
+        vni = config.fetch("vlan_vnis", {})[name.delete_prefix("Vlan")]
+        svi.fetch("addresses", []).each do |address|
+          fields = CtxParser::Immutable.copy([ name, vni, address ])
+          network = parse_network(address)
+          entry = Entry.new(*fields, position, network&.to_i, network&.prefix)
+          position += 1
+          if network
+            ((groups[svi["vrf"]] ||= {})[network.ipv4?] ||= []) << entry
+          else
+            (invalid[svi["vrf"]] ||= []) << entry
+          end
+        end
+      end
+      @groups = groups.transform_values do |families|
+        families.transform_values do |entries|
+          prefixes = entries.group_by(&:prefix).transform_values { |rows| rows.group_by(&:first).transform_values(&:freeze).freeze }
+          { ordered: entries.sort_by(&:first).freeze, prefixes: prefixes.freeze }.freeze
+        end.freeze
+      end.freeze
+      @invalid = invalid.transform_values(&:freeze).freeze
+      freeze
+    end
+
+    # 同业务 VNI 和明确排除的本机接口不构成冲突；其他匹配范围保留完整地址证据。
+    def conflicts(address:, vrf:, vni:, except_interface: nil)
+      network = IPAddr.new(address)
+      @invalid.fetch(vrf, []).each do |entry|
+        IPAddr.new(entry.address) if relevant?(entry, vni, except_interface)
+      end
+      group = @groups.dig(vrf, network.ipv4?)
+      return [] unless group
+
+      entries = overlapping(group, network).select { |entry| relevant?(entry, vni, except_interface) }
+      entries.sort_by!(&:position)
+      entries.group_by(&:interface).map do |name, rows|
+        { interface: name, vni: rows.first.vni, value: rows.map(&:address) }
+      end
+    end
+
+    private
+
+    # 非法地址只在相关查询中重新拒绝，不能让另一 VRF 的未使用事实改变原有边界。
+    def parse_network(address)
+      IPAddr.new(address)
+    rescue ArgumentError
+      nil
+    end
+
+    # 区间起点命中的子网配合有限个祖先前缀，覆盖相等、包含和被包含的网段。
+    def overlapping(group, network)
+      first, last = network.to_i, network.to_range.last.to_i
+      ordered = group.fetch(:ordered)
+      left = ordered.bsearch_index { |entry| entry.first >= first } || ordered.size
+      right = ordered.bsearch_index { |entry| entry.first > last } || ordered.size
+      entries = ordered[left...right]
+      width = network.ipv4? ? 32 : 128
+      group.fetch(:prefixes).each do |prefix, subnets|
+        next unless prefix < network.prefix
+        shift = width - prefix
+        ancestor = (first >> shift) << shift
+        entries.concat(subnets.fetch(ancestor, [])) unless ancestor == first
+      end
+      entries
+    end
+
+    # 相同 VNI 与排除接口的事实保留在索引中，只在本次查询中排除。
+    def relevant?(entry, vni, except_interface)
+      entry.vni != vni && entry.interface != except_interface
+    end
+  end
+end

data/lib/vxlan/version.rb

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

data/lib/vxlan.rb

@@ -7,9 +7,11 @@ end
 
 require_relative "vxlan/observation"
 require_relative "vxlan/snapshot"
-require_relative "vxlan/configuration"
+require_relative "vxlan/config"
 require_relative "vxlan/runtime_parser"
 require_relative "vxlan/bgp_neighbors"
-require_relative "vxlan/configuration_review"
+require_relative "vxlan/config/review"
 require_relative "vxlan/prefix_list_references"
 require_relative "vxlan/collector"
+require_relative "vxlan/recommendations"
+require_relative "vxlan/fabric/review"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vxlan
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Gatework contributors
@@ -29,14 +29,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '0.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '0.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.4
 - !ruby/object:Gem::Dependency
   name: digest
   requirement: !ruby/object:Gem::Requirement
@@ -65,9 +71,94 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: optparse
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yaml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fileutils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tempfile
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: time
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Independent configuration and runtime parsers for VXLAN fabrics, with
   immutable snapshots and injected collection sessions.
-executables: []
+executables:
+- vxlan
 extensions: []
 extra_rdoc_files: []
 files:
@@ -75,12 +166,32 @@ files:
 - LICENSE
 - README-zh.md
 - README.md
+- bin/README.md
+- bin/vxlan
 - docs/architecture-zh.md
+- docs/evidence-contracts.md
 - docs/release.md
+- docs/remediation.md
+- docs/review-2026-10-19.md
+- docs/superpowers/plans/2026-10-19-command-line.md
+- docs/superpowers/plans/2026-10-19-connector-integration.md
+- docs/superpowers/plans/2026-10-19-evidence-contracts.md
+- docs/superpowers/plans/2026-10-19-vxlan-examples.md
+- docs/superpowers/plans/2026-10-20-fabric-consistency.md
+- docs/superpowers/specs/2026-10-19-command-line-design.md
+- docs/superpowers/specs/2026-10-19-connector-integration-design.md
+- docs/superpowers/specs/2026-10-19-evidence-contracts.md
+- examples/README.md
+- examples/collect.rb
 - examples/offline.rb
+- examples/parse.rb
 - lib/vxlan.rb
+- lib/vxlan/acl_policy.rb
 - lib/vxlan/bgp_neighbors.rb
-- lib/vxlan/cisco_nxos/configuration.rb
+- lib/vxlan/change_plan.rb
+- lib/vxlan/change_plan/svi_acl.rb
+- lib/vxlan/change_plan/svi_gateway.rb
+- lib/vxlan/change_plan/vlan_vni.rb
 - lib/vxlan/cisco_nxos/configuration_state.rb
 - lib/vxlan/cisco_nxos/document.rb
 - lib/vxlan/cisco_nxos/evpn_l2route.rb
@@ -102,14 +213,33 @@ files:
 - lib/vxlan/cisco_nxos/syntax/policies.rb
 - lib/vxlan/cisco_nxos/syntax/routing.rb
 - lib/vxlan/cisco_nxos/terminal.rb
+- lib/vxlan/cli.rb
+- lib/vxlan/cli/apply.rb
+- lib/vxlan/cli/collect.rb
+- lib/vxlan/cli/connector.rb
+- lib/vxlan/cli/options.rb
+- lib/vxlan/cli/parse.rb
+- lib/vxlan/cli/report.rb
+- lib/vxlan/cli/review.rb
+- lib/vxlan/cli/review/fabric.rb
+- lib/vxlan/cli/review/report.rb
+- lib/vxlan/cli/templates/env.example
+- lib/vxlan/cli/templates/vxlan.yml
 - lib/vxlan/collector.rb
-- lib/vxlan/configuration.rb
-- lib/vxlan/configuration_review.rb
+- lib/vxlan/config.rb
+- lib/vxlan/config/evidence.rb
+- lib/vxlan/config/review.rb
+- lib/vxlan/fabric/review.rb
+- lib/vxlan/fabric/scope.rb
 - lib/vxlan/observation.rb
 - lib/vxlan/parser_registry.rb
 - lib/vxlan/prefix_list_references.rb
+- lib/vxlan/recommendations.rb
 - lib/vxlan/runtime_parser.rb
+- lib/vxlan/service/catalog.rb
+- lib/vxlan/service/mapping.rb
 - lib/vxlan/snapshot.rb
+- lib/vxlan/subnet_index.rb
 - lib/vxlan/version.rb
 homepage: https://github.com/gatework/vxlan
 licenses:

data/lib/vxlan/cisco_nxos/configuration.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "configuration_state"
-
-module Vxlan
-  module CiscoNxos
-    # 兼容既有加载路径；配置解析状态由 ConfigurationState 表达。
-    Configuration = ConfigurationState
-  end
-end

data/lib/vxlan/configuration_review.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module Vxlan
-  # 配置关联审查独立于语法解析及运行健康检查。
-  class ConfigurationReview
-    # 绑定归一化配置，用于交叉引用一致性检查。
-    def initialize(configuration)
-      @configuration = configuration
-    end
-
-    # 检查完整配置中的关联缺失或引用矛盾。
-    def call(complete: false)
-      raise ArgumentError, "Completeness must be boolean" unless [ true, false ].include?(complete)
-      return [] unless complete
-
-      nve_members_by_vni = @configuration.fetch(:nve).fetch(:members, {})
-      vlan_mappings_by_vni = @configuration.fetch(:vlan_vnis).group_by { |_vlan, vni| vni }
-      vrf_vnis = @configuration.fetch(:vrfs).values.filter_map { |settings| settings[:vni] }.to_set
-      evpn_vnis = @configuration.fetch(:evpn)
-      findings = []
-      vlan_mappings_by_vni.each do |vni, entries|
-        next unless vni && !nve_members_by_vni.key?(vni)
-
-        findings << { code: :vlan_vni_without_nve, vni: vni, vlan_ids: entries.map(&:first).sort }
-      end
-      nve_members_by_vni.each do |vni, settings|
-        if settings[:associate_vrf]
-          findings << { code: :nve_l3_without_vrf, vni: vni } unless vrf_vnis.include?(vni)
-          next
-        end
-
-        findings << { code: :nve_l2_without_vlan, vni: vni } unless vlan_mappings_by_vni.key?(vni)
-        if @configuration[:nv_overlay_evpn] && !evpn_vnis.key?(vni)
-          findings << { code: :nve_l2_without_evpn, vni: vni }
-        end
-      end
-      evpn_vnis.each do |vni, settings|
-        member = nve_members_by_vni[vni]
-        if !member
-          findings << { code: :evpn_vni_without_nve, vni: vni }
-        elsif (settings[:type] == "l3") != member[:associate_vrf]
-          findings << { code: :vni_layer_conflict, vni: vni, evpn_type: settings[:type] }
-        end
-      end
-      @configuration.fetch(:vrfs).each do |name, settings|
-        next unless settings[:vni]
-        member = nve_members_by_vni[settings[:vni]]
-        code = member ? (!member[:associate_vrf] ? :vni_layer_conflict : nil) : :l3_vni_without_nve
-        findings << { code: code, vni: settings[:vni], vrf: name } if code
-      end
-      findings.sort_by { |finding| [ finding[:vni], finding[:code].to_s ] }
-    end
-  end
-end