vxlan 0.2.3 → 0.3.1

data/lib/vxlan/cli/apply.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require "digest"
+require "ipaddr"
+require "vxlan"
+require_relative "report"
+require_relative "../change_plan"
+
+module Vxlan
+  module CLI
+    # 原生会话适配：读取使用固定查询提示符，写入由连接器识别配置模式提示符。
+    class ApplySession
+      # 借用一次已连接且独占的会话，不重连、不重放。
+      def initialize(native)
+        @native = native
+      end
+
+      # 读回完整配置并交给现有解析器；部分证据不能参与前置检查或验收。
+      def read_configuration
+        [ "terminal length 0", "terminal width 511" ].each { |command| write(command) }
+        capture = CtxDriver::Reader.new(session: @native).read("show running-config")
+        raise IOError, "配置回读失败" unless capture.success?
+        observation = Vxlan::Config.new.parse(capture.body, complete: true)
+        raise ArgumentError, "配置证据不完整" unless observation.complete? && observation.records.one?
+        JSON.parse(JSON.generate(observation.records.first))
+      end
+
+      # 每次只发一条命令；失败立即交还宿主，原始输出不进入终端和日志报告。
+      def write(command)
+        result = @native.execute_command(command.strip, output_sensitive: true)
+        raise IOError, "设备命令未确认" unless result.success? && result.steps.one?
+        true
+      end
+    end
+
+    # 交互式单设备下发：展示、确认、重新读取、记录意图、执行、回读，禁止无人值守确认。
+    class Apply
+      # 注入连接工厂仅用于宿主集成和离线失败测试。
+      def initialize(env: ENV, out: $stdout, error: $stderr, input: $stdin, connector_factory: nil, discovery: {})
+        @env, @out, @error, @input, @factory = env, out, error, input, connector_factory
+        @discovery = discovery
+      end
+
+      # 没有 --yes 或自动回退；零退出码只确认配置回读，不声称业务已验收。
+      def run(argv)
+        @store, @state, @started = nil, nil, false
+        options = { directory: File.join(Dir.pwd, "vxlan-executions"), port: 22 }
+        parser = OptionParser.new do |p|
+          p.banner = "用法：vxlan apply --plan FILE --item ID [--env-file FILE]（必须真实终端明确确认）"
+          p.on("--plan FILE", "批次 plan.json，须有同目录 SHA256 校验文件") { |value| options[:plan] = value }
+          p.on("--item ID", "批次计划中明确选择一个增量，禁止批量执行") { |value| options[:item] = value }
+          p.on("--env-file FILE", "显式凭据文件，进程环境优先") { |value| options[:env_file] = value }
+          p.on("--directory DIR", "私有执行日志目录") { |value| options[:directory] = value }
+          p.on("--port N", Integer, "SSH 端口，默认 22") { |value| options[:port] = value }
+          p.on("-h", "--help", "查看帮助，不连接设备") { options[:help] = true }
+        end
+        rest = parser.parse(argv.dup)
+        return @out.puts(parser) || 0 if options[:help]
+        raise ArgumentError, "必须使用真实交互终端" unless @input.tty? && @out.tty? && @error.tty?
+        raise ArgumentError, "需要单个计划" unless rest.empty? && options[:plan] && options[:port].between?(1, 65_535)
+        body = File.read(options[:plan])
+        hash = Digest::SHA256.hexdigest(body)
+        plan = CtxParser::Immutable.copy(select_plan(JSON.parse(body), options, hash))
+        change = validate_plan(plan)
+        host = plan.fetch("device").fetch("host")
+        @out.puts "目标：#{plan['device']['name']}（#{host}）；#{plan['scope']}；#{plan['title']}"
+        @out.puts "影响：#{plan['impact']}"
+        @out.puts Array(plan["prerequisites"]).map { |value| "条件：#{value}" }
+        @out.puts "计划 SHA256：#{hash}\n拟执行命令：\n#{change.commands.join("\n")}\n条件回退（不自动执行）：\n#{change.rollback.join("\n")}"
+        token = "APPLY #{host} #{hash[0, 12]} #{options[:item]}"
+        @out.print "确认业务策略及维护窗口后输入 #{token}；其他输入取消："
+        @out.flush
+        return @out.puts("已取消，未连接设备。") || 1 unless @input.gets&.strip == token
+        settings = credentials(options)
+        @store = Report.new(options[:directory])
+        @state = { "status" => "confirmed", "device" => plan["device"], "plan_sha256" => hash, "plan_item" => options[:item], "expected_config_sha256" => plan["expected_config_sha256"], "commands" => plan["commands"], "steps" => [] }
+        @store.write_execution(@state)
+        session_opened, verified = false, false
+        with_session(plan["device"], settings) do |session|
+          raise IOError, "会话回调重复，禁止重放" if session_opened
+          session_opened = true
+          before = CtxParser::Immutable.copy(session.read_configuration)
+          unless ChangePlan.fingerprint(before) == plan["expected_config_sha256"] && change.eligible?(before)
+            raise ArgumentError, "配置已变化或增量前提不满足"
+          end
+          change.commands.each_with_index do |command, index|
+            @state["status"] = "executing"
+            @state["pending_command"] = index
+            @store.write_execution(@state)
+            @started = true
+            raise IOError, "设备命令未确认" unless session.write(command) == true
+            @state["steps"] << { "index" => index, "status" => "acknowledged" }
+            @state.delete("pending_command")
+            @store.write_execution(@state)
+          end
+          after = CtxParser::Immutable.copy(session.read_configuration)
+          raise IOError, "配置验收未通过" unless change.satisfied?(after, before: before)
+          @state["observed_config_sha256"] = ChangePlan.fingerprint(after)
+          verified = true
+        end
+        raise IOError, "会话未完成配置验证" unless verified
+        @state["status"] = "configuration_verified"
+        @store.write_execution(@state)
+        @out.puts "配置回读已确认；仍需完成业务验收，未执行保存配置。日志：#{@store.directory}/execution.json"
+        0
+      rescue Interrupt
+        record_failure("interrupted")
+        @error.puts "操作中断；#{@started ? '设备效果可能不完整，请先回读核对，禁止重放。' : '尚未下发业务配置。'}"
+        130
+      rescue StandardError, LoadError => error
+        record_failure(error.class.name)
+        @error.puts "下发停止（#{error.class.name}）；#{@started ? '效果未完整确认，先回读，不自动重放或回退。' : '未下发业务配置；检查终端、计划、凭据及当前配置是否仍匹配。'}"
+        2
+      end
+
+      private
+
+      # 聚合文件必须校验哈希并选中唯一动作；绝不隐式选择第一项或循环执行。
+      def select_plan(document, options, hash)
+        id = options[:item]
+        unless document.is_a?(Hash) && document["schema_version"] == 2 && document["platform"] == "cisco_nxos" && document["changes"].is_a?(Hash) &&
+            id.is_a?(String) && id.match?(/\A[A-Za-z0-9_.-]+\z/) && document["changes"].key?(id)
+          raise ArgumentError, "需要批次计划及有效 --item"
+        end
+        raise ArgumentError, "计划校验失败" unless File.read("#{options[:plan]}.sha256").strip == hash
+        document["changes"].fetch(id)
+      end
+
+      # 不信任文件中的命令，重新从有限动作渲染并逐字核对，拒绝额外命令。
+      def validate_plan(plan)
+        raise ArgumentError, "计划类型不匹配" unless plan.is_a?(Hash) && plan["schema_version"] == 1 && plan["platform"] == "cisco_nxos"
+        host = plan.fetch("device").fetch("host")
+        raise ArgumentError, "目标地址无效" unless host.is_a?(String) && !host.include?("/") && IPAddr.new(host).to_s == host
+        raise ArgumentError, "配置指纹无效" unless plan["expected_config_sha256"].is_a?(String) && plan["expected_config_sha256"].match?(/\A[0-9a-f]{64}\z/)
+        change = ChangePlan.build(plan.fetch("change"))
+        raise ArgumentError, "计划命令被修改" unless change.commands == plan["commands"] && change.rollback == plan["rollback"]
+        change
+      end
+
+      # 共用分层环境加载器，显式文件最高、进程环境优先；凭据不进入计划或日志。
+      def credentials(options)
+        require "net/connector/config"
+        env = Net::Connector::Config.new(name: "vxlan", env: @env, env_file: options[:env_file], **@discovery).load_environment.environment
+        username = env["NC_CISCO_NXOS_USERNAME"] || env["NC_DEVICE_USERNAME"]
+        raise ArgumentError, "缺少设备用户名" unless username.is_a?(String) && !username.strip.empty?
+        { username: username, password: env["NC_CISCO_NXOS_PASSWORD"] || env["NC_DEVICE_PASSWORD"], enable_password: env["NC_ENABLE_PASSWORD"],
+          port: options[:port], host_key_policy: "strict", command_timeout: 60, login_timeout: 15 }
+      end
+
+      # 原生会话只打开一次，读写处于同一操作租约中。
+      def with_session(device, settings, &operation)
+        return @factory.call(device, settings, &operation) if @factory
+        require "net/connector"
+        Net::Connector.open(:cisco_nxos, host: device.fetch("host"), **settings) do |native|
+          native.with_operation(:vxlan_apply) { operation.call(ApplySession.new(native)) }
+        end
+      end
+
+      # 失败记录尽力持久化；记录失败也不允许继续发送任何命令。
+      def record_failure(code)
+        return unless @store && @state
+        @state["status"] = @started ? "uncertain" : "failed"
+        @state["error"] = code
+        @store.write_execution(@state)
+      rescue StandardError, Interrupt
+        @error.puts "执行日志收尾未确认；保留已有检查点，禁止据此重放配置。"
+      end
+    end
+  end
+end

data/lib/vxlan/cli/collect.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "vxlan"
+require_relative "options"
+require_relative "report"
+require_relative "connector"
+
+module Vxlan
+  module CLI
+    # 批量入口拥有配置、清单、并行与报告，不向核心库引入宿主依赖。
+    class Collect
+      # 可注入清单、传输与执行器，离线集成验证不需要任何真实设备。
+      def initialize(env: ENV, out: $stdout, error: $stderr, input: $stdin, connector_factory: nil, executor: nil, **options)
+        @env, @out, @error, @input = env, out, error, input
+        @connector_factory, @executor = connector_factory, executor
+        @defaults = options
+        @lock = Mutex.new
+      end
+
+      # 先预检全部输入和凭据，再创建报告和连接；失败分类不打印原始异常正文。
+      def run(argv)
+        # 每次运行独立持有批次状态；预检失败不能改写上一次报告。
+        @options, @store, @progress, @devices, @results = nil, nil, nil, [], []
+        @options = Options.new(argv, env: @env, out: @out, **@defaults)
+        return 0 if @options.informational?
+        @options.validate_interaction!(input: @input, error: @error)
+        @options.load_environment
+        if @options.flags[:init]
+          @options.initialize_files
+          return 0
+        end
+        return 0 if @options.missing?(input: @input, error: @error)
+        @options.load
+        require "net/connector/collect/progress"
+        @progress = Net::Connector::Collect::Progress.new(io: @error, enabled: !@options.flags[:quiet], verbose: @options.flags[:verbose])
+        @progress.notice("配置：#{@options.config}")
+        return output(@options.public_values.merge("sources" => @options.sources)) if @options.flags[:show_config]
+        @devices = devices = inventory
+        return output(devices) if @options.flags[:inventory_only]
+        if devices.empty?
+          @progress.notice("没有匹配设备，未建立连接")
+          @out.puts JSON.generate(status: :no_devices, total: 0) if @options.flags[:json]
+          return 1
+        end
+        credentials = credentials!
+        load_network unless @connector_factory && @executor
+        unless @connector_factory
+          devices.each { |device| Net::Connector::Configuration.new(host: device.fetch("host"), **credentials).validate_endpoint! }
+        end
+        unless @executor
+          require "net/connector/resources"
+          Net::Connector::Resources.prepare!(parallel: [ devices.size, @options.values.fetch("parallel") ].min)
+        end
+        @store = Report.new(@options.values.fetch("directory"), scripts: @options.flags[:scripts] == true)
+        @progress.plan(devices: devices, total: @inventory_total, parallel: @options.values.fetch("parallel"), label: "VXLAN 只读采集")
+        @progress.with_updates do
+          execute(devices) { |device| collect(device, credentials) }
+        end
+        @store.review_collected_fabric(@options.fabric_policy)
+        summary = finish
+        return 2 unless summary
+        summary[:status] == :complete ? 0 : 1
+      rescue Interrupt
+        finish(interrupted: true) if @store
+        diagnostic "采集已取消，已保存的设备报告保留；未保存结果见报告状态"
+        130
+      rescue SystemCallError, IOError => error
+        finish(report_error: error) if @store
+        diagnostic "VXLAN 参数或报告错误：#{report_diagnostic(error)}"
+        2
+      rescue OptionParser::ParseError, ArgumentError, LoadError => error
+        if @store
+          finish(execution_error: error)
+          diagnostic "VXLAN 执行失败：#{error.class.name}；已采集结果见批次报告"
+        else
+          diagnostic "VXLAN 参数、依赖或报告错误：#{error.message}；使用 --help 查看参数"
+        end
+        2
+      rescue StandardError => error
+        finish(execution_error: error) if @store
+        diagnostic "VXLAN 清单或执行失败：#{CtxDriver::Failure.code(error, :collection_failed)}（#{error.class.name}）"
+        2
+      end
+
+      private
+
+      # 只在需要库存或网络执行时加载可选依赖，帮助和静态预览保持独立。
+      def load_network
+        require "net/connector"
+      rescue LoadError
+        raise LoadError, "联网采集需要 net-connector >= 0.16.0；请在宿主 Gemfile 添加或 gem install net-connector", cause: nil
+      end
+
+      # YAML 静态设备或显式 Netdisco 来源二选一；所有重复地址在连接前拒绝。
+      def inventory
+        values = @options.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
+            { "host" => device.host, "name" => device.name || device.host, "model" => device.model }
+          end
+        else
+          values.fetch("devices")
+        end
+        targets = @options.normalize_devices(rows)
+        @inventory_total = targets.size
+        includes = values.fetch("hosts").map { |v| IPAddr.new(v) }
+        excludes = values.fetch("exclude_hosts").map { |v| IPAddr.new(v) }
+        targets.select do |device|
+          host, name = device.values_at("host", "name")
+          (includes.empty? || includes.any? { |network| network.include?(host) }) &&
+            excludes.none? { |network| network.include?(host) } &&
+            (values.fetch("names").empty? || values.fetch("names").any? { |v| name.downcase.include?(v.downcase) }) &&
+            values.fetch("exclude_names").none? { |v| name.downcase.include?(v.downcase) }
+        end
+      end
+
+      # 缺失用户名时不尝试连接；密码允许省略以支持明确的 SSH key/agent。
+      def credentials!
+        username = secret("NC_CISCO_NXOS_USERNAME") || secret("NC_DEVICE_USERNAME")
+        raise ArgumentError, "请设置 NC_DEVICE_USERNAME 或 NC_CISCO_NXOS_USERNAME；密码可通过环境或 SSH key/agent 提供" unless username
+        @options.values.fetch("ssh").transform_keys(&:to_sym).merge(username: username,
+          password: secret("NC_CISCO_NXOS_PASSWORD") || secret("NC_DEVICE_PASSWORD"), enable_password: secret("NC_ENABLE_PASSWORD"))
+      end
+
+      # 空白环境值视为缺失，不修改或回显凭据。
+      def secret(name)
+        value = @options.environment[name]
+        value unless value.nil? || value.strip.empty?
+      end
+
+      # 每个任务使用独立 Collector 和会话；公共执行器负责有界并发和线程回收。
+      def execute(devices, &block)
+        parallel = @options.values.fetch("parallel")
+        return @executor.call(devices, parallel, &block) if @executor
+        Net::Connector::Parallel::Pool.new(parallel: parallel).map(devices, &block)
+      end
+
+      # 单台失败保留其他设备和已获得维度；报告持久化失败交由批次终止处理。
+      def collect(device, credentials)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        snapshot = nil
+        @progress.start(device)
+        credentials = credentials.merge(on_event: @progress.method(:event))
+        begin
+          connector = @connector_factory ? @connector_factory.call(device, credentials) : Connector.new(device, credentials)
+          snapshot = Vxlan::Collector.new.collect(connector: connector, target: device, fabric_key: @options.values.fetch("fabric"),
+            model: device["model"], dimensions: @options.values.fetch("dimensions").map(&:to_sym))
+          dimensions = snapshot.dimensions.transform_values { |v| { status: v.status, records: v.records.size, issues: v.issues.map { |issue| issue[:code] }.uniq } }
+          status = snapshot.dimensions.fetch(:collection).status
+          result = { device: device, status: status, dimensions: dimensions }
+        rescue StandardError => error
+          result = { device: device, status: :failed, error: CtxDriver::Failure.code(error, :collection_failed), dimensions: {} }
+        end
+        result[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+        result[:report_saved] = false
+        @lock.synchronize { @results << result }
+        @store.write(result, snapshot: snapshot)
+        @lock.synchronize { result[:report_saved] = true }
+        @progress.result(result)
+        result
+      end
+
+      # 调度器已回收线程；摘要失败只交付安全诊断，不覆盖先前的取消事实。
+      def finish(interrupted: false, report_error: nil, execution_error: nil)
+        results = @results.sort_by { |result| result[:device]["host"] }
+        options = { interrupted: interrupted, requested: @devices,
+          report_error: report_error && report_diagnostic(report_error), execution_error: execution_error&.class&.name }
+        summary = @store.finish(results, **options, output_error: @progress.output_error)
+        @progress.finish(summary)
+        # 末尾提示也可能首次失败；只补写输出诊断，不重复设备任务。
+        if @progress.output_error && !summary[:output_error]
+          summary = @store.finish(results, **options, output_error: @progress.output_error)
+        end
+        @out.puts JSON.pretty_generate(summary) if @options.flags[:json]
+        summary
+      rescue SystemCallError, IOError => error
+        diagnostic "VXLAN 摘要报告错误：#{report_diagnostic(error)}"
+        diagnostic "摘要恢复未确认；请依据退出码及报告目录检查，不能将旧摘要视为本次成功。" if @store.recovery_failed?
+        nil
+      end
+
+      # 错误提示失败不能覆盖取消或执行退出码；已失效的进度流不再重试。
+      def diagnostic(message)
+        return if @progress&.output_error
+        @error.puts(message)
+      rescue StandardError
+        nil
+      end
+
+      # 自有发布错误消息不含正文；外部文件异常只显示类型，不打印 message/cause。
+      def report_diagnostic(error)
+        error.instance_of?(Report::Error) ? error.message : error.class.name
+      end
+
+      # 预览默认显示逐设备身份；公开配置由显式开关展示。
+      def output(value)
+        if @options.flags[:json] || value.is_a?(Hash)
+          @out.puts JSON.pretty_generate(value)
+        else
+          value.each { |device| @out.puts "#{device.fetch('host')}\t#{device.fetch('name')}\t#{device['model']}" }
+          @out.puts "设备：#{value.size} 台；未建立设备连接"
+        end
+        value.is_a?(Array) && value.empty? ? 1 : 0
+      end
+    end
+  end
+end

data/lib/vxlan/cli/connector.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Vxlan
+  module CLI
+    # 可选传输适配器；只由联网采集使用，解析库不引用 net-connector。
+    class Connector
+      # 固定设备与接入选项，不在构造时建立会话。
+      def initialize(device, settings)
+        @device, @settings = device, settings
+      end
+
+      # 向 Collector 声明已知平台，不把品牌猜测当作型号识别。
+      def platform = :cisco_nxos
+
+      # 连接器拥有原生会话；CtxDriver 仅借用，不负责关闭或重连。
+      def open
+        Net::Connector.open(:cisco_nxos, host: @device.fetch("host"), **@settings) do |native|
+          native.with_operation(:vxlan) { yield native }
+        end
+      end
+    end
+  end
+end