vxlan 0.1.0

data/lib/vxlan/collector.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "parser_registry"
+require "ctx_driver"
+require_relative "observation"
+require_relative "snapshot"
+
+module Vxlan
+  # 单设备单会话顺序采集；各维度独立失败，断链后不重放查询。
+  class Collector
+    COMMANDS = CiscoNxos::Profile::COMMANDS
+    PREPARATION_COMMANDS = [ "terminal length 0", "terminal width 511" ].freeze
+
+    # 注入为顺序命令观测生成时间戳的时钟。
+    def initialize(clock: -> { Time.now.utc })
+      @clock = clock
+    end
+
+    # 通过调用方持有的连接器顺序采集请求维度。
+    def collect(connector:, target:, fabric_key:, model: nil, dimensions: COMMANDS.keys)
+      raise ArgumentError, "Target must be a hash" unless target.is_a?(Hash)
+
+      unless dimensions.is_a?(Array) && dimensions.any? && dimensions.uniq == dimensions && (dimensions - COMMANDS.keys).empty?
+        raise ArgumentError, "Unknown or duplicate VXLAN dimensions"
+      end
+      raise ArgumentError, "VXLAN requires Cisco NX-OS" unless connector.platform.to_s == "cisco_nxos"
+      profile = ParserRegistry.fetch(connector.platform, model: model)
+
+      observations = {}
+      session_finished = false
+      begin
+        connector.open do |session|
+          reader = CtxDriver::Reader.new(session: session, clock: @clock)
+          if (code = prepare(reader))
+            dimensions.each { |name| observations[name] = failure(name, code) }
+            observations[:collection] = failure(:collection, code)
+            next
+          end
+          dimensions.each do |name|
+            config = observations[:configuration]
+            if name == :vpc && !reader.failure && unconfigured?(name, config)
+              observations[name] = Observation.new(name: name, status: :complete, completed_at: @clock.call,
+                issues: [ { code: :vpc_not_configured } ])
+            else
+              observations[name] = read(reader, name, config, profile)
+            end
+          end
+          session_finished = true
+        end
+      rescue StandardError => error
+        raise unless CtxDriver::Failure.connection_error?(error, connector)
+
+        code = CtxDriver::Failure.code(error, :connection_failed)
+        dimensions.each { |name| observations[name] ||= failure(name, code) }
+        observations[:collection] = failure(:collection, session_finished ? :session_close_failed : code)
+      end
+      status = if observations.values.all?(&:complete?)
+        :complete
+      elsif observations.values.any? { |value| %i[complete partial].include?(value.status) }
+        :partial
+      else
+        :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)
+    end
+
+    private
+
+    # 采集设备回显前，禁用分页并归一化终端宽度。
+    def prepare(reader)
+      PREPARATION_COMMANDS.each do |command|
+        capture = reader.read(command)
+        return capture.failure.fetch(:code) unless capture.success?
+      end
+      nil
+    end
+
+    # 解析失败限定在单条查询内；Reader 负责传输与回执校验。
+    def read(reader, name, configuration, profile)
+      command = profile.command(name)
+      capture = reader.read(command)
+      metadata = { started_at: capture.started_at, completed_at: capture.completed_at, evidence: capture.evidence }
+      unless capture.success?
+        return failed_capture(name, capture, command).with(**metadata)
+      end
+      begin
+        body = capture.body
+        parsed = if body.strip.empty? && unconfigured?(name, configuration)
+          code = name == :port_channels ? :port_channels_not_configured : :nve_not_configured
+          Observation.new(name: name, status: :complete, issues: [ { code: code } ])
+        else
+          Observation.new(name: name, **profile.parse(name, body, complete: true).to_h)
+        end
+        parsed.with(**metadata)
+      rescue StandardError => error
+        details = CtxDriver::Failure.details(error, fallback: :command_processing_failed, stage: :parse)
+        failure(name, details.fetch(:code), **details.except(:code), command: command).with(**metadata)
+      end
+    end
+
+    # 保留传输首次不可用原因，并标记从未发送的命令。
+    def failed_capture(name, capture, command)
+      failure(name, capture.failure.fetch(:code), **capture.failure.except(:code), command: command, skipped: capture.skipped?)
+    end
+
+    # 仅当同一会话的完整配置证明功能未启用时，才接受空运行回显。
+    def unconfigured?(name, configuration)
+      return false unless configuration&.complete? && configuration.records.one?
+
+      settings = configuration.records.first
+      case name
+      when :vpc then !settings[:vpc_domain] && !settings.fetch(:features).include?("vpc")
+      when :nve_peers, :nve_vnis then !settings.fetch(:nve)[:interface]
+      when :port_channels
+        settings.fetch(:interfaces).none? { |interface, values| /\Aport-channel\d+\z/i.match?(interface) || values[:channel_group] }
+      else false
+      end
+    end
+
+    # 构建失败观测，不丢弃已成功的同级维度。
+    def failure(name, code, **details)
+      Observation.new(name: name, status: :failed, issues: [ { code: code, **details } ], completed_at: @clock.call)
+    end
+  end
+end

data/lib/vxlan/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "parser_registry"
+require_relative "observation"
+
+module Vxlan
+  # 配置与运行观测使用相同的平台、型号策略。
+  class Configuration
+    # 按当前平台和型号选择 VXLAN 配置策略。
+    def initialize(platform: :cisco_nxos, model: nil)
+      @profile = ParserRegistry.fetch(platform, model: model)
+    end
+
+    # 解析 NX-OS 配置，将事实封装为 VXLAN 配置观测。
+    def parse(text, complete: false)
+      result = @profile.parse(:configuration, text, complete: complete)
+      Observation.new(name: :configuration, **result.to_h)
+    end
+  end
+end

data/lib/vxlan/configuration_review.rb

@@ -0,0 +1,43 @@
+# 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
+
+      members = @configuration.fetch(:nve).fetch(:members, {})
+      vlans = @configuration.fetch(:vlan_vnis).group_by { |_vlan, vni| vni }
+      evpn = @configuration.fetch(:evpn)
+      findings = []
+      vlans.each do |vni, entries|
+        next unless vni && !members.key?(vni)
+
+        findings << { code: :vlan_vni_without_nve, vni: vni, vlan_ids: entries.map(&:first).sort }
+      end
+      members.each do |vni, settings|
+        next if settings[:associate_vrf]
+
+        findings << { code: :nve_l2_without_vlan, vni: vni } unless vlans.key?(vni)
+        if @configuration[:nv_overlay_evpn] && !evpn.key?(vni)
+          findings << { code: :nve_l2_without_evpn, vni: vni }
+        end
+      end
+      evpn.each_key { |vni| findings << { code: :evpn_vni_without_nve, vni: vni } unless members.key?(vni) }
+      @configuration.fetch(:vrfs).each do |name, settings|
+        next unless settings[:vni]
+        member = members[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

data/lib/vxlan/l2route_parser.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "runtime_parser"
+
+module Vxlan
+  # 保留 L2RIB 公共入口，由平台策略选择解析实现。
+  class L2routeParser
+    TYPES = { l2route_macs: :mac, l2route_mac_ips: :mac_ip }.freeze
+
+    # 选择 EVPN 路由维度使用的运行解析器。
+    def initialize(platform: :cisco_nxos, model: nil)
+      @parser = RuntimeParser.new(platform: platform, model: model)
+    end
+
+    # 校验 L2RIB 维度，将 EVPN 路由解析委派给平台策略。
+    def parse(name, text, complete:)
+      TYPES.fetch(name)
+      @parser.parse(name, text, complete: complete)
+    end
+  end
+end

data/lib/vxlan/observation.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "ctx_parser/immutable"
+
+module Vxlan
+  # 保留命令事实与完整性；默认检查不输出原始配置或凭据。
+  Observation = Data.define(:name, :status, :records, :issues, :evidence, :started_at, :completed_at) do
+    # 冻结单个维度的记录、状态及诊断元数据。
+    def initialize(name:, status:, records: [], issues: [], evidence: [], started_at: nil, completed_at: nil)
+      raise ArgumentError, "Invalid observation status" unless %i[complete partial failed unsupported not_requested].include?(status)
+      raise ArgumentError, "Records must be hashes" unless records.is_a?(Array) && records.all? { |row| row.is_a?(Hash) }
+
+      super(name: name, status: status, records: CtxParser::Immutable.copy(records),
+        issues: CtxParser::Immutable.copy(issues), evidence: CtxParser::Immutable.copy(evidence),
+        started_at: started_at&.dup&.freeze, completed_at: completed_at&.dup&.freeze)
+    end
+
+    # 判断所有已选事实是否都有完整证据支持。
+    def complete? = status == :complete
+
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name} name=#{name} status=#{status} records=#{records.size}>"
+  end
+end

data/lib/vxlan/parser_registry.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "ctx_parser/registry"
+require_relative "cisco_nxos/profile"
+
+module Vxlan
+  # VXLAN 在本领域声明平台支持，公共解析库不依赖领域实现。
+  ParserRegistry = CtxParser::Registry.new(profiles: { cisco_nxos: CiscoNxos::Profile })
+end

data/lib/vxlan/prefix_list_references.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "bgp_neighbors"
+
+module Vxlan
+  # 关联命名列表、route-map 选择器及所有支持的路由使用方。
+  class PrefixListReferences
+    # 绑定路由配置，用于解析前缀列表的使用方。
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # 按地址族将前缀列表关联到 route-map 条目和路由使用方。
+    def call(address_family: "ipv4")
+      raise ArgumentError, "Unsupported address family" unless %w[ipv4 ipv6].include?(address_family)
+
+      bindings = route_map_bindings
+      @configuration.fetch(:route_maps).each_with_object({}) do |(name, entries), references|
+        entries.sort_by { |entry| entry.fetch(:sequence) }.each do |entry|
+          matches = entry.fetch(:prefix_list_matches) do
+            [ { address_family: "ipv4", selector: "address", names: entry.fetch(:prefix_lists, []) } ]
+          end
+          matches.select { |match| match[:address_family] == address_family }.each do |match|
+            caller = { type: "route_map", name: name, sequence: entry.fetch(:sequence), action: entry.fetch(:action),
+              bindings: bindings.fetch(name, []).uniq }
+            caller[:selector] = match[:selector] unless match[:selector] == "address"
+            match.fetch(:names).uniq.each do |prefix_list|
+              callers = (references[prefix_list] ||= [])
+              callers << caller unless callers.include?(caller)
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+    # 关联关系保留协议、VRF、地址族及对等体，避免共享策略被混用。
+    def route_map_bindings
+      result = Hash.new { |hash, key| hash[key] = [] }
+      bgp = @configuration.fetch(:bgp)
+      { "default" => bgp }.merge(bgp.fetch(:vrfs, {})).each do |vrf, settings|
+        settings.fetch(:address_families, {}).each do |family, values|
+          context = { protocol: "bgp", process: bgp[:asn].to_s, vrf: vrf, address_family: family }
+          add_redistribution(result, values, context)
+          values.fetch(:networks, []).each do |network|
+            next unless network[:route_map]
+
+            result[network[:route_map]] << context.merge(usage: "network", prefix: network.fetch(:prefix))
+          end
+          retain = values[:retain_route_target]
+          if retain&.start_with?("route-map ")
+            result[retain.delete_prefix("route-map ")] << context.merge(usage: "retain_route_target")
+          end
+        end
+      end
+      BgpNeighbors.new(bgp).each do |vrf, peer, settings|
+        settings.fetch(:address_families, {}).each do |family, values|
+          values.fetch(:route_maps, {}).each do |direction, route_map|
+            result[route_map] << { protocol: "bgp", process: bgp[:asn].to_s, vrf: vrf,
+              address_family: family, usage: "neighbor_route_map", peer: peer, direction: direction.to_s }
+          end
+        end
+      end
+      @configuration.fetch(:ospf).each do |process, settings|
+        { "default" => settings }.merge(settings.fetch(:vrfs, {})).each do |vrf, values|
+          add_redistribution(result, values, protocol: "ospf", process: process, vrf: vrf)
+        end
+      end
+      @configuration.fetch(:vrfs, {}).each do |vrf, settings|
+        settings.fetch(:exports, []).each do |entry|
+          result[entry.fetch(:route_map)] << { protocol: "vrf", vrf: vrf, address_family: entry.fetch(:address_family),
+            usage: "export", target_vrf: entry.fetch(:vrf) }
+        end
+      end
+      result
+    end
+
+    # 将重分发 route-map 关联到其路由使用方。
+    def add_redistribution(result, settings, context)
+      settings.fetch(:redistribute, []).each do |entry|
+        next unless entry[:route_map]
+
+        result[entry[:route_map]] << context.merge(usage: "redistribute", source_protocol: entry.fetch(:protocol),
+          source_process: entry[:process]).compact
+      end
+    end
+  end
+end

data/lib/vxlan/runtime_parser.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "parser_registry"
+require_relative "observation"
+
+module Vxlan
+  # 将纯平台解析事实封装为对应 VXLAN 维度观测。
+  class RuntimeParser
+    # 按请求的平台和型号选择运行解析行为。
+    def initialize(platform: :cisco_nxos, 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)
+
+      result = @profile.parse(name, text, complete: complete)
+      Observation.new(name: name, **result.to_h)
+    end
+  end
+end

data/lib/vxlan/snapshot.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "ctx_parser/immutable"
+
+module Vxlan
+  # 携带单设备 Fabric 身份及观测结果，不管理资产清单。
+  Snapshot = Data.define(:target, :fabric_key, :dimensions, :observed_at) do
+    # 事实由不可变领域观测持有；仅复制维度选择，不重复复制事实。
+    def initialize(target:, fabric_key:, dimensions:, observed_at:)
+      super(target: CtxParser::Immutable.copy(target), fabric_key: CtxParser::Immutable.copy(fabric_key),
+        dimensions: dimensions.dup.freeze, observed_at: observed_at&.dup&.freeze)
+    end
+
+    # 判断所有已选事实是否都有完整证据支持。
+    def complete?
+      selected = dimensions.values.reject { |dimension| dimension.status == :not_requested }
+      selected.any? && selected.all?(&:complete?)
+    end
+
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name} fabric=#{fabric_key.inspect} complete=#{complete?}>"
+  end
+end

data/lib/vxlan/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Vxlan
+  # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
+  VERSION = "0.1.0"
+end

data/lib/vxlan.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "vxlan/version"
+
+module Vxlan
+end
+
+require_relative "vxlan/observation"
+require_relative "vxlan/snapshot"
+require_relative "vxlan/configuration"
+require_relative "vxlan/runtime_parser"
+require_relative "vxlan/l2route_parser"
+require_relative "vxlan/bgp_neighbors"
+require_relative "vxlan/configuration_review"
+require_relative "vxlan/prefix_list_references"
+require_relative "vxlan/collector"

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: vxlan
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gatework contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ctx_parser
+  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: ctx_driver
+  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: digest
+  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: ipaddr
+  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: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README-zh.md
+- README.md
+- docs/architecture-zh.md
+- docs/release.md
+- examples/offline.rb
+- lib/vxlan.rb
+- lib/vxlan/bgp_neighbors.rb
+- lib/vxlan/cisco_nxos/configuration.rb
+- lib/vxlan/cisco_nxos/configuration_document.rb
+- lib/vxlan/cisco_nxos/configuration_parsing/interfaces.rb
+- lib/vxlan/cisco_nxos/configuration_parsing/policies.rb
+- lib/vxlan/cisco_nxos/configuration_parsing/routing.rb
+- lib/vxlan/cisco_nxos/evpn_l2route.rb
+- lib/vxlan/cisco_nxos/parser.rb
+- lib/vxlan/cisco_nxos/parsers/show_bgp_l2vpn_evpn_summary.rb
+- lib/vxlan/cisco_nxos/parsers/show_cdp_neighbors_detail.rb
+- lib/vxlan/cisco_nxos/parsers/show_interface_brief.rb
+- lib/vxlan/cisco_nxos/parsers/show_ip_ospf_neighbors.rb
+- lib/vxlan/cisco_nxos/parsers/show_l2route_evpn_mac_all.rb
+- lib/vxlan/cisco_nxos/parsers/show_l2route_evpn_mac_ip_all.rb
+- lib/vxlan/cisco_nxos/parsers/show_mac_address_table.rb
+- lib/vxlan/cisco_nxos/parsers/show_nve_peers.rb
+- lib/vxlan/cisco_nxos/parsers/show_nve_vni.rb
+- lib/vxlan/cisco_nxos/parsers/show_port_channel_summary.rb
+- lib/vxlan/cisco_nxos/parsers/show_running_config.rb
+- lib/vxlan/cisco_nxos/parsers/show_vpc_brief.rb
+- lib/vxlan/cisco_nxos/profile.rb
+- lib/vxlan/collector.rb
+- lib/vxlan/configuration.rb
+- lib/vxlan/configuration_review.rb
+- lib/vxlan/l2route_parser.rb
+- lib/vxlan/observation.rb
+- lib/vxlan/parser_registry.rb
+- lib/vxlan/prefix_list_references.rb
+- lib/vxlan/runtime_parser.rb
+- lib/vxlan/snapshot.rb
+- lib/vxlan/version.rb
+homepage: https://github.com/gatework/vxlan
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/gatework/vxlan
+  bug_tracker_uri: https://github.com/gatework/vxlan/issues
+  changelog_uri: https://github.com/gatework/vxlan/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/gatework/vxlan#readme
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.6
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Parse and collect Cisco NX-OS VXLAN evidence.
+test_files: []