network-infra-utility 0.5.0 → 0.8.3

data/service/simlab/bin/simctl

@@ -0,0 +1,152 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+# frozen_string_literal: true
+
+# simctl - 路由交换仿真 CLI 工具。
+#
+# 用法：
+#   simctl simulate SCENARIO.yml          # 运行场景
+#   simctl simulate SCENARIO.yml --until 100  # 运行到指定时间
+#   simctl dump --rib R1 SCENARIO.yml    # 导出 RIB
+#   simctl dump --mac S1 SCENARIO.yml    # 导出 MAC 表
+#   simctl trace --from H1 --to 10.0.0.2 SCENARIO.yml  # 路径追踪
+
+require "thor"
+require_relative "../lib/simlab"
+
+module NetworkInfraUtility
+  module SimLab
+    class CLI < Thor
+      desc "simulate SCENARIO", "运行仿真场景"
+      option :until, type: :numeric, default: 100, desc: "运行到指定虚拟时间"
+      option :steps, type: :numeric, desc: "执行指定步数"
+      option :verbose, type: :boolean, default: false, desc: "详细输出"
+
+      def simulate(scenario_file)
+        sim = Simulation.new
+        sim.load(scenario_file)
+        sim.build
+
+        puts "Loading scenario: #{scenario_file}"
+        puts "Devices: #{sim.topology.device_names.join(', ')}"
+        puts "Links: #{sim.topology.links.size}"
+        puts "Running simulation..."
+
+        if options[:steps]
+          sim.run(steps: options[:steps])
+        else
+          sim.run(final_time: options[:until])
+        end
+
+        puts "Simulation completed at t=#{sim.time}"
+
+        if options[:verbose]
+          sim.topology.devices.each_value do |device|
+            if device.is_a?(Device::Router)
+              puts sim.observer.format_rib(device)
+            elsif device.is_a?(Device::Switch)
+              puts sim.observer.format_mac(device)
+            end
+          end
+        end
+      end
+
+      desc "dump SCENARIO", "导出设备表信息"
+      option :rib, type: :string, desc: "导出指定路由器的 RIB"
+      option :mac, type: :string, desc: "导出指定交换机的 MAC 表"
+      option :stp, type: :string, desc: "导出指定交换机的 STP 状态"
+      option :all, type: :boolean, default: false, desc: "导出所有设备"
+
+      def dump(scenario_file)
+        sim = Simulation.new
+        sim.load(scenario_file)
+        sim.build
+        sim.run(final_time: 1)  # 跑一个 tick 让协议初始化
+
+        if options[:rib]
+          device = sim.topology.devices[options[:rib]]
+          if device && device.is_a?(Device::Router)
+            puts sim.observer.format_rib(device)
+          else
+            puts "Device #{options[:rib]} not found or not a router"
+          end
+        end
+
+        if options[:mac]
+          device = sim.topology.devices[options[:mac]]
+          if device && device.is_a?(Device::Switch)
+            puts sim.observer.format_mac(device)
+          else
+            puts "Device #{options[:mac]} not found or not a switch"
+          end
+        end
+
+        if options[:stp]
+          device = sim.topology.devices[options[:stp]]
+          if device && device.is_a?(Device::Switch) && device.stp
+            stp_info = device.stp_dump
+            puts "=== STP: #{options[:stp]} ==="
+            puts "  Bridge ID: #{stp_info[:bridge_id]}"
+            puts "  Root ID: #{stp_info[:root_id]}"
+            puts "  Root Bridge: #{stp_info[:root_bridge]}"
+            stp_info[:ports].each { |port, info| puts "  #{port}: role=#{info[:role]} state=#{info[:state]}" }
+          else
+            puts "Device #{options[:stp]} not found, not a switch, or STP not enabled"
+          end
+        end
+
+        if options[:all]
+          sim.topology.devices.each_value do |device|
+            if device.is_a?(Device::Router)
+              puts sim.observer.format_rib(device)
+            elsif device.is_a?(Device::Switch)
+              puts sim.observer.format_mac(device)
+            end
+          end
+        end
+      end
+
+      desc "trace SCENARIO", "追踪转发路径"
+      option :from, type: :string, required: true, desc: "起始设备"
+      option :to, type: :string, required: true, desc: "目的 IP"
+
+      def trace(scenario_file)
+        sim = Simulation.new
+        sim.load(scenario_file)
+        sim.build
+        sim.run(final_time: 10)
+
+        result = sim.trace(from: options[:from], to: options[:to])
+        puts sim.observer.format_trace(result)
+      end
+
+      desc "list SCENARIO", "列出场景中的设备和链路"
+
+      def list(scenario_file)
+        sim = Simulation.new
+        sim.load(scenario_file)
+
+        puts "=== Devices ==="
+        sim.topology.devices.each_value do |d|
+          type = d.is_a?(Device::Router) ? "Router" : "Switch"
+          puts "  #{d.name} (#{type})"
+          if d.is_a?(Device::Router)
+            d.interfaces.each { |port, info| puts "    #{port}: #{info[:cidr]} (#{info[:status]})" }
+          else
+            puts "    Ports: #{d.ports.keys.join(', ')}"
+          end
+        end
+
+        puts "\n=== Links ==="
+        sim.topology.links.each do |link|
+          puts "  #{link.endpoint_a} <-> #{link.endpoint_b} (#{link.status}, bw=#{link.bandwidth}, delay=#{link.delay})"
+        end
+
+        puts "\n=== Hosts ==="
+        sim.topology.hosts.each { |name, info| puts "  #{name}: #{info[:ip]} gw=#{info[:gateway]}" }
+      end
+    end
+  end
+end
+
+NetworkInfraUtility::SimLab::CLI.start(ARGV)

data/service/simlab/lib/simlab.rb

@@ -0,0 +1,124 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+# SimLab 统一入口模块。
+#
+# 负责加载仿真服务的所有子模块，提供统一接口。
+#
+# 用法：
+#   require_relative "lib/simlab"
+#   simlab = NetworkInfraUtility::SimLab::Simulation.new
+#   simlab.load("scenario.yml")
+#   simlab.run(final_time: 100)
+#   simlab.dump_rib("R1")
+
+require_relative "simlab_topology"
+require_relative "simlab_engine"
+require_relative "simlab_router"
+require_relative "simlab_switch"
+require_relative "simlab_traffic"
+require_relative "simlab_observer"
+require_relative "simlab_scenario"
+
+module NetworkInfraUtility
+  module SimLab
+    class Error < StandardError; end
+
+    class Simulation
+      attr_reader :topology, :engine, :observer, :time
+
+      def initialize
+        @topology = Topology.new
+        @engine   = Engine.new
+        @observer = Observer.new
+        @traffic  = Traffic.new
+        @time     = 0
+      end
+
+      # 加载场景文件（YAML 或 Ruby DSL）。
+      def load(file_path)
+        scenario = Scenario.load(file_path)
+        scenario.apply_to(self)
+        self
+      end
+
+      # 从拓扑构建仿真环境。
+      def build
+        @topology.devices.each_value(&:build)
+        @topology.links.each { |link| link.activate }
+        self
+      end
+
+      # 运行仿真直到指定时间。
+      def run(final_time: nil, steps: nil)
+        if final_time
+          @engine.run_until(final_time) do |time, event|
+            @time = time
+            tick_devices(time)
+            event.call
+          end
+        elsif steps
+          @engine.run_steps(steps) do |time, event|
+            @time = time
+            tick_devices(time)
+            event.call
+          end
+        end
+        self
+      end
+
+      # 单步执行。
+      def step
+        @engine.step do |time, event|
+          @time = time
+          tick_devices(time)
+          event.call
+        end
+        self
+      end
+
+      # 注入流量/事件。
+      def inject(event)
+        @traffic.inject(@engine, event)
+      end
+
+      # 导出 RIB 快照。
+      def dump_rib(device_name)
+        device = @topology.devices[device_name]
+        raise Error, "Device #{device_name} not found" unless device
+
+        @observer.rib_dump(device)
+      end
+
+      # 导出 MAC 表快照。
+      def dump_mac(device_name)
+        device = @topology.devices[device_name]
+        raise Error, "Device #{device_name} not found" unless device
+
+        @observer.mac_dump(device)
+      end
+
+      # 转发路径追踪。
+      def trace(from:, to:)
+        @observer.trace(topology: @topology, from: from, to: to)
+      end
+
+      # 收敛检测。
+      def converged?(ticks: 5)
+        @observer.converged?(topology: @topology, ticks: ticks, engine: @engine)
+      end
+
+      # 快照导出。
+      def snapshot
+        @observer.snapshot(@topology)
+      end
+
+      private
+
+      # 全局时钟推进时，所有设备同步 tick。
+      def tick_devices(now)
+        @topology.devices.each_value { |device| device.tick(now: now) }
+      end
+    end
+  end
+end

data/service/simlab/lib/simlab_engine.rb

@@ -0,0 +1,146 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+# 离散事件仿真核心：全局虚拟时钟 + 事件队列。
+#
+# 设计要点：
+# - 全局虚拟时钟
+# - 事件队列（按时间排序）
+# - 支持延迟事件（链路延迟、计时器、老化）
+# - 收敛检测辅助（统计 N 个 tick 内 RIB/MAC 无变化）
+#
+# support 组件通过 tick(now) 被动推进，不自己计时。
+# device 之间不直接互调方法，由 engine 按链路投递帧/报文（可带延迟）。
+#
+# 用法：
+#   engine = Engine.new
+#   engine.schedule(at: 10) { puts "tick at 10" }
+#   engine.schedule(at: 20, delay: 5) { puts "delayed event" }
+#   engine.run_until(30) { |time, event| event.call }
+
+module NetworkInfraUtility
+  module SimLab
+    # 仿真事件。
+    Event = Data.define(:at, :priority, :id, :block) do
+      include Comparable
+
+      def <=>(other)
+        [at, priority] <=> [other.at, other.priority]
+      end
+    end
+
+    # 投递信封：封装设备间传递的报文。
+    Envelope = Data.define(:at, :src_node, :src_if, :dst_node, :dst_if, :payload)
+
+    class Engine
+      attr_reader :clock, :event_count
+
+      def initialize
+        @clock       = 0     # 虚拟时钟（秒）
+        @queue       = []    # 事件队列（最小堆模拟）
+        @event_count = 0
+        @seq         = 0    # 事件序号（用于稳定排序）
+        @stopped     = false
+      end
+
+      # 调度一个事件在指定时间执行。
+      # at: 执行时间
+      # priority: 优先级（数字小的先执行，默认 0）
+      # 返回事件 ID（可用于取消）。
+      def schedule(at:, priority: 0, &block)
+        @seq += 1
+        event = Event.new(at: at, priority: priority, id: @seq, block: block)
+        @queue << event
+        @queue.sort_by! { |e| [e.at, e.priority, e.id] }
+        @event_count += 1
+        @seq
+      end
+
+      # 调度一个延迟事件。
+      # delay: 从当前时钟起的延迟
+      def schedule_delayed(delay:, priority: 0, &block)
+        schedule(at: @clock + delay, priority: priority, &block)
+      end
+
+      # 投递信封（带链路延迟）。
+      def deliver(envelope, delay: 0)
+        schedule(at: envelope.at + delay) do
+          yield envelope if block_given?
+        end
+      end
+
+      # 取消指定 ID 的事件。
+      def cancel(event_id)
+        @queue.reject! { |e| e.id == event_id }
+      end
+
+      # 运行到指定时间。
+      def run_until(final_time)
+        while !@queue.empty? && !@stopped
+          event = @queue.first
+          break if event.at > final_time
+
+          @queue.shift
+          @clock = event.at
+          yield event.at, event.block if block_given?
+        end
+        @clock = final_time if @clock < final_time
+      end
+
+      # 执行指定步数的事件。
+      def run_steps(steps)
+        steps.times do
+          break if @queue.empty? || @stopped
+
+          event = @queue.shift
+          @clock = event.at
+          yield event.at, event.block if block_given?
+        end
+      end
+
+      # 执行单步。
+      def step
+        return nil if @queue.empty? || @stopped
+
+        event = @queue.shift
+        @clock = event.at
+        yield event.at, event.block if block_given?
+        event
+      end
+
+      # 停止仿真。
+      def stop
+        @stopped = true
+      end
+
+      # 重置。
+      def reset
+        @clock = 0
+        @queue.clear
+        @event_count = 0
+        @seq = 0
+        @stopped = false
+      end
+
+      # 队列中剩余事件数。
+      def pending
+        @queue.size
+      end
+
+      # 是否有空闲（队列空）。
+      def idle?
+        @queue.empty?
+      end
+
+      # 当前时钟。
+      def now
+        @clock
+      end
+
+      # 查看下一个事件时间。
+      def next_event_time
+        @queue.first&.at
+      end
+    end
+  end
+end

data/service/simlab/lib/simlab_observer.rb

@@ -0,0 +1,176 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+# 观测导出：RIB/MAC 快照、转发路径 trace、收敛时间统计。
+#
+# 输出 JSON/文本快照，便于断言和教学演示。
+#
+# 用法：
+#   observer = Observer.new
+#   observer.rib_dump(router)
+#   observer.mac_dump(switch)
+#   observer.trace(topology: topo, from: "H1", to: "10.0.0.2")
+
+require 'json'
+require 'set'
+
+module NetworkInfraUtility
+  module SimLab
+    class Observer
+      # RIB 快照。
+      def rib_dump(device)
+        device.rib_dump
+      end
+
+      # MAC 表快照。
+      def mac_dump(device)
+        device.mac_dump
+      end
+
+      # 转发路径追踪。
+      # 返回 [{device:, port:, decision:}] 的跳转路径。
+      def trace(topology:, from:, to:)
+        path = []
+        visited = Set.new
+        current_device = topology.devices[from]
+
+        return path unless current_device
+
+        while current_device && !visited.include?(current_device.name)
+          visited.add(current_device.name)
+
+          if current_device.is_a?(Device::Router)
+            # 路由器：查 RIB 确定下一跳
+            route = current_device.rib.lookup(parse_ip(to))
+            break unless route
+
+            hop = {
+              device: current_device.name,
+              type: :router,
+              port: route.ifindex,
+              next_hop: route.next_hop,
+              protocol: route.protocol
+            }
+            path << hop
+
+            # 找对端设备
+            adj = topology.peer_of(current_device.name, route.ifindex)
+            break unless adj
+
+            current_device = topology.devices[adj[:peer_device]]
+
+          elsif current_device.is_a?(Device::Switch)
+            # 交换机：查 MAC 表确定出端口
+            mac_entry = current_device.mac_table.lookup(to)
+            port = mac_entry ? mac_entry.port : nil
+
+            hop = {
+              device: current_device.name,
+              type: :switch,
+              port: port || 'flood',
+              decision: mac_entry ? :forward : :flood
+            }
+            path << hop
+
+            if port
+              adj = topology.peer_of(current_device.name, port)
+              break unless adj
+              current_device = topology.devices[adj[:peer_device]]
+            else
+              break
+            end
+          else
+            break
+          end
+        end
+
+        path
+      end
+
+      # 收敛检测：统计 N 个 tick 内 RIB/MAC 是否无变化。
+      def converged?(topology:, ticks:, engine:)
+        # 简化实现：检查是否还有 pending 事件
+        # 真实实现应比较 RIB/MAC 快照
+        snapshots_before = capture_snapshots(topology)
+
+        ticks.times do
+          engine.step do |time, event|
+            topology.devices.each_value { |d| d.tick(now: time) }
+            event.call
+          end
+        end
+
+        snapshots_after = capture_snapshots(topology)
+        snapshots_before == snapshots_after
+      end
+
+      # 全局快照。
+      def snapshot(topology)
+        {
+          devices: topology.devices.transform_values { |d| d.to_h },
+          links: topology.links.map { |l| { a: l.endpoint_a.to_s, b: l.endpoint_b.to_s, status: l.status } },
+          timestamp: engine_now
+        }
+      end
+
+      # 导出为 JSON。
+      def to_json(topology)
+        JSON.pretty_generate(snapshot(topology))
+      end
+
+      # RIB 快照格式化输出。
+      def format_rib(device)
+        rib_data = device.rib_dump
+        lines = ["=== RIB: #{device.name} ==="]
+
+        rib_data.each do |prefix, routes|
+          routes.each do |r|
+            lines << "  #{prefix} via #{r[:next_hop]} (#{r[:protocol]} metric=#{r[:metric]})"
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # MAC 表快照格式化输出。
+      def format_mac(device)
+        mac_data = device.mac_dump
+        lines = ["=== MAC Table: #{device.name} ==="]
+
+        mac_data.each do |mac, info|
+          lines << "  #{mac} -> #{info[:port]}" + (info[:static] ? ' (static)' : '')
+        end
+
+        lines.join("\n")
+      end
+
+      # 路径追踪格式化输出。
+      def format_trace(trace_result)
+        lines = ["=== Trace ==="]
+        trace_result.each do |hop|
+          lines << "  #{hop[:device]} (#{hop[:type]}) -> port #{hop[:port]}" +
+            (hop[:next_hop] ? " next_hop=#{hop[:next_hop]} proto=#{hop[:protocol]}" : '') +
+            (hop[:decision] ? " decision=#{hop[:decision]}" : '')
+        end
+        lines << "  (reached destination)" if trace_result.any?
+        lines.join("\n")
+      end
+
+      private
+
+      def capture_snapshots(topology)
+        topology.devices.transform_values do |d|
+          d.is_a?(Device::Router) ? d.rib_dump : d.mac_dump
+        end
+      end
+
+      def parse_ip(ip_str)
+        ip_str.include?(':') ? IPv6.new(ip_str) : IPv4.new(ip_str)
+      end
+
+      def engine_now
+        Time.now.to_i  # 简化
+      end
+    end
+  end
+end