netstack 0.1.1 → 0.2.0

data/lib/netstack/configuration/artifact.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Netstack
+  module Configuration
+    # Content is deliberately absent from inspect, summary and deployment plans.
+    class Artifact
+      PLATFORMS = Values.copy({ "h3c" => %w[h3c], "cisco" => %w[cisco_nxos], "hillstone" => %w[hillstone],
+        "paloalto" => %w[palo_alto], "radware" => %w[radware] })
+      attr_reader :filename, :scenario, :vendor, :created_at, :sha256, :template_sha256, :sections
+
+      def self.script(target:, content:, filename: "configuration.txt", created_at: Time.now.utc)
+        raise InputError, "manual script target must be a Target" unless target.is_a?(Target)
+
+        new(filename: filename, content: content, scenario: "manual", vendor: target.platform, created_at: created_at,
+          template_sha256: nil, target: target)
+      end
+
+      def initialize(filename:, content:, scenario:, vendor:, created_at:, template_sha256:, sections: {}, target: nil)
+        @filename = Values.text(filename, name: "artifact filename")
+        raise InputError, "artifact filename must be a plain filename" unless filename.match?(/\A[a-zA-Z0-9_.-]+\.txt\z/)
+        unless content.is_a?(String) && content.valid_encoding? && !content.empty? && !content.match?(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/)
+          raise InputError, "artifact must contain valid configuration text"
+        end
+        @content = content.dup.freeze
+        @scenario = Values.text(scenario, name: "scenario")
+        @vendor = Values.text(vendor, name: "vendor")
+        @created_at = created_at.getutc.freeze
+        @sha256 = Digest::SHA256.hexdigest(content).freeze
+        @template_sha256 = Values.text(template_sha256, name: "template digest", optional: true)
+        if scenario == "manual"
+          raise InputError, "manual scripts require an explicit target" unless target.is_a?(Target) && target.platform == vendor
+          @target = target
+        elsif target
+          raise InputError, "generated templates cannot override their platform contract"
+        end
+        unless sections.is_a?(Hash) && sections.values.all? { |section| section.is_a?(Artifact) && section.executable? }
+          raise InputError, "artifact sections must be single-target artifacts"
+        end
+        @sections = sections.to_h { |key, value| [Values.text(key, name: "section key"), value] }.freeze
+        freeze
+      end
+
+      def content = @content
+      def executable? = sections.empty?
+      def section(name) = sections.fetch(name.to_s)
+
+      def summary
+        { filename: filename, scenario: scenario, vendor: vendor, created_at: created_at.iso8601,
+          sha256: sha256, template_sha256: template_sha256, bytes: content.bytesize,
+          executable: executable?, sections: sections.keys }.freeze
+      end
+
+      def inspect = "#<#{self.class.name} filename=#{filename.inspect} sha256=#{sha256} bytes=#{content.bytesize}>"
+
+      def plan(target:, artifact_ref:, expected:, request_no: nil, target_id: nil)
+        raise InputError, "select a single-target artifact section before planning" unless executable?
+        raise InputError, "configuration verification expectations are required" unless expected.is_a?(Hash) && !expected.empty?
+        validate_target!(target)
+
+        parameters = { artifact_ref: Values.text(artifact_ref, name: "artifact reference"), sha256: sha256 }
+        parameters[:request_no] = Values.text(request_no, name: "request number") unless request_no.nil?
+        unless target_id.nil?
+          raise InputError, "target id must be text or an integer" unless target_id.is_a?(String) || target_id.is_a?(Integer)
+          parameters[:target_id] = Values.text(target_id.to_s, name: "target id")
+        end
+        Deployment::Plan.new(target: target, steps: [Deployment::Step.new(id: "configuration", action: "configuration",
+          parameters: parameters, expected: expected)], metadata: { scenario: scenario, vendor: vendor, template_sha256: template_sha256 })
+      end
+
+      def validate_target!(target)
+        if @target
+          return if target.is_a?(Target) && target == @target
+
+          raise InputError, "manual script belongs to a different target"
+        end
+        return if target.is_a?(Target) && PLATFORMS.fetch(vendor, []).include?(target.platform)
+        raise InputError, "artifact vendor and target platform do not match"
+
+      end
+    end
+  end
+end

data/lib/netstack/configuration/artifact_resolver.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Configuration
+    # Re-resolve and verify immediately before submission; do not cache mutable host records.
+    class ArtifactResolver
+      def initialize(resolver:)
+        raise InputError, "artifact resolver must be callable" unless resolver.respond_to?(:call)
+
+        @resolver = resolver
+      end
+
+      def resolve(step)
+        raise InputError, "unsupported configuration action" unless step.action == "configuration"
+
+        reference = step.parameters.fetch(:artifact_ref)
+        digest = step.parameters.fetch(:sha256)
+        raise InputError, "invalid artifact reference or digest" unless reference.is_a?(String) && !reference.empty? && digest.is_a?(String) && digest.match?(/\A[0-9a-f]{64}\z/)
+
+        artifact = @resolver.call(reference)
+        unless artifact.is_a?(Artifact) && artifact.executable? && artifact.sha256 == digest
+          raise Error.new("configuration artifact is unavailable or changed", code: :artifact_changed, stage: :preflight)
+        end
+        artifact
+      rescue KeyError
+        raise InputError, "configuration plan requires artifact_ref and sha256"
+      end
+    end
+  end
+end

data/lib/netstack/configuration/bootstrap/payload.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Adapted from Motor Netconf scenario definitions and safe template dialect.
+require_relative "../support"
+
+module Netstack
+  module Configuration
+    module Bootstrap
+      module Payload
+        H3C_STP_PRIORITIES = {
+          "core" => 4096, "aggregation" => 8192, "access" => 32_768
+        }.freeze
+
+        private
+
+        def bootstrap(data)
+          data["access_auth_enabled"] = false unless data.key?("access_auth_enabled")
+          stp_priority = H3C_STP_PRIORITIES[data.fetch("device_role")]
+          data["stp_priority"] = stp_priority if stp_priority
+          cidr = data.fetch("mgmt")
+          range = IPAddr.new(cidr).to_range
+          data.merge!(
+            "mgmt_ip" => cidr.split("/").first,
+            "mgmt_mask" => mask(cidr),
+            "mgmt_gateway" => data["mgmt_gateway"].presence || ipv4(range.last.to_i - 1),
+            "loopback_ip" => data["loopback"]&.split("/")&.first
+          )
+          if data.key?("underlay_enabled")
+            decorate_cisco_fabric!(data)
+          else
+            data["h3c_uplinks"] = data.fetch("uplink_interfaces").map.with_index do |interface, index|
+              { "interface" => interface, "description" => "UPLINK_#{index + 1}" }
+            end
+          end
+          decorate_bootstrap_system!(data.fetch("system"))
+        end
+
+        def decorate_cisco_fabric!(data)
+          overlay = data["overlay_enabled"]
+          role = data.fetch("device_role")
+          data["nve_enabled"] = overlay && %w[leaf border].include?(role)
+          data["route_reflector"] = overlay && role == "spine"
+          data["bgp_neighbors"] = Array(data["overlay_neighbors"]).map { |address| { "address" => address } }
+          data["external_bgp_neighbors"] ||= []
+          data["vtep_secondary_enabled"] = false
+          data["advertise_pip"] = false
+          return unless data["nve_enabled"]
+
+          data["vtep_secondary_enabled"] = data["vtep_secondary"].present?
+          data["advertise_pip"] = data["vpc_enabled"] && data["vtep_secondary_enabled"]
+        end
+
+        def decorate_bootstrap_system!(system)
+          system["tacacs_entries"] = entries(system.fetch("tacacs_servers"))
+          system["radius_entries"] = entries(Array(system["radius_servers"]))
+          system["ssh_acl_entries"] = system.fetch("ssh_acl_cidrs").map.with_index do |cidr, index|
+            { "sequence" => (index + 1) * 10, "wildcard" => wildcard(cidr) }
+          end
+          system["local_users"].each do |user|
+            user["h3c_role"] = user.fetch("role") == "admin" ? "network-admin" : "network-operator"
+            user["cisco_privilege"] = { "admin" => 15, "operator" => 5 }.fetch(user.fetch("role"), 1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/netstack/configuration/bootstrap/validator.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+# Adapted from Motor Netconf scenario definitions and safe template dialect.
+require_relative "../support"
+
+module Netstack
+  module Configuration
+    module Bootstrap
+      module Validator
+        H3C_ROLES = %w[access aggregation core].freeze
+        CISCO_ROLES = %w[leaf spine border].freeze
+
+        private
+
+        def bootstrap_roles
+          @vendor == "cisco" ? CISCO_ROLES : H3C_ROLES
+        end
+
+        def validate_bootstrap_gateway!(result, value)
+          if value.nil? || value == ""
+            if result.fetch("mgmt").split("/").first == last_usable(result.fetch("mgmt"))
+              raise self.class::Error, "mgmt_gateway is required when management address is the last usable address"
+            end
+            return
+          end
+
+          gateway = ipv4!(value, "mgmt_gateway")
+          network = IPAddr.new(result.fetch("mgmt"))
+          range = network.to_range
+          unless network.include?(gateway) && ![ range.first.to_s, range.last.to_s ].include?(gateway)
+            raise self.class::Error, "mgmt_gateway must be a usable host in the management subnet"
+          end
+          if gateway == result.fetch("mgmt").split("/").first
+            raise self.class::Error, "mgmt_gateway must differ from the management address"
+          end
+          result["mgmt_gateway"] = gateway
+        end
+
+        def validate_h3c_bootstrap!(result, common, access_auth_enabled)
+          topology = take!(%w[access_interface_start access_interface_end uplink_interfaces])
+          uplinks = bootstrap_interface_list!(
+            default_if_omitted(topology["uplink_interfaces"], [ "Ten-GigabitEthernet1/0/49", "Ten-GigabitEthernet1/0/50" ]),
+            "uplink_interfaces", max: 8
+          )
+          result.merge!(
+            "access_interface_start" => interface!(default_if_omitted(topology["access_interface_start"], "GigabitEthernet1/0/1"), "access_interface_start"),
+            "access_interface_end" => interface!(default_if_omitted(topology["access_interface_end"], "GigabitEthernet1/0/48"), "access_interface_end"),
+            "uplink_interfaces" => uplinks
+          )
+          access_range = h3c_port_range!(result["access_interface_start"], result["access_interface_end"], "access interfaces")
+          reject_uplink_overlap!(access_range, uplinks)
+          if access_auth_enabled
+            result.merge!(
+              "access_auth_enabled" => true,
+              "access_auth_domain" => identifier!(common["access_auth_domain"], "access_auth_domain"),
+              "access_auth_vlan" => integer!(common["access_auth_vlan"], "access_auth_vlan", 1..4094),
+              "access_auth_interface_start" => interface!(common["access_auth_interface_start"], "access_auth_interface_start"),
+              "access_auth_interface_end" => interface!(common["access_auth_interface_end"], "access_auth_interface_end")
+            )
+            authentication_range = h3c_port_range!(result["access_auth_interface_start"], result["access_auth_interface_end"], "access authentication interfaces")
+            reject_uplink_overlap!(authentication_range, uplinks)
+            unless authentication_range.first == access_range.first && access_range.last.cover?(authentication_range.last)
+              raise self.class::Error, "access authentication range must be inside the access range"
+            end
+          end
+          finish!(result)
+        end
+
+        # H3C 的 to 范围必须属于同一类型、成员和槽位，并按端口号递增。
+        def h3c_port_range!(first, last, name)
+          endpoints = [first, last].map { |value| h3c_port!(value) }
+          unless endpoints.first.first == endpoints.last.first && endpoints.first.last <= endpoints.last.last
+            raise self.class::Error, "#{name} must be ordered ports on one interface path"
+          end
+          [endpoints.first.first, endpoints.first.last..endpoints.last.last]
+        end
+
+        def h3c_port!(value)
+          match = /\A([a-z][a-z-]*[0-9]+\/[0-9]+\/)([0-9]+)\z/i.match(value)
+          raise self.class::Error, "H3C bootstrap requires physical interface paths" unless match
+
+          [match[1].downcase, Integer(match[2], 10)]
+        end
+
+        # 比较范围内所有端口，避免只比较端点而把上联口纳入接入配置。
+        def reject_uplink_overlap!(range, uplinks)
+          return unless uplinks.any? { |value| h3c_port!(value).then { |path, port| path == range.first && range.last.cover?(port) } }
+
+          raise self.class::Error, "uplink interfaces must be outside access ranges"
+        end
+
+        def validate_cisco_bootstrap!(result)
+          fabric = take!(%w[
+            underlay_enabled loopback ospf_process_id ospf_area fabric_mtu fabric_links
+            overlay_enabled local_as remote_as overlay_neighbors vtep_loopback vtep_secondary
+            external_bgp_neighbors vpc_enabled vpc_domain_id vpc_role_priority
+            vpc_peer_keepalive_destination vpc_peer_keepalive_source
+            vpc_virtual_peer_link_destination vpc_virtual_peer_link_source
+            vpc_peer_link_port_channel
+          ])
+          underlay_enabled = fabric["underlay_enabled"].nil? || boolean!(fabric["underlay_enabled"], "underlay_enabled")
+          overlay_enabled = fabric["overlay_enabled"].nil? || boolean!(fabric["overlay_enabled"], "overlay_enabled")
+          vpc_enabled = fabric["vpc_enabled"].nil? ? false : boolean!(fabric["vpc_enabled"], "vpc_enabled")
+          raise self.class::Error, "overlay requires underlay" if overlay_enabled && !underlay_enabled
+          raise self.class::Error, "vPC requires overlay" if vpc_enabled && !overlay_enabled
+          raise self.class::Error, "spine role does not support vPC" if result["device_role"] == "spine" && vpc_enabled
+
+          result.merge!("underlay_enabled" => underlay_enabled, "overlay_enabled" => overlay_enabled, "vpc_enabled" => vpc_enabled)
+          validate_cisco_underlay!(result, fabric) if underlay_enabled
+          validate_cisco_overlay!(result, fabric) if overlay_enabled
+          validate_cisco_vpc!(result, fabric) if vpc_enabled
+          result["vpc_virtual_peer_link_enabled"] ||= false
+          finish!(result)
+        end
+
+        def validate_cisco_underlay!(result, fabric)
+          links = rows!(fabric["fabric_links"], "fabric_links")
+          raise self.class::Error, "fabric_links must contain 1 to 8 rows" if links.size > 8
+          links = links.map.with_index do |link, index|
+            row = exact!(link, %w[interface address description], "fabric_links[#{index}]")
+            {
+              "interface" => interface!(row["interface"], "fabric_links[#{index}].interface"),
+              "address" => cidr!(row["address"], "fabric_links[#{index}].address", host: true),
+              "description" => description!(row["description"], "fabric_links[#{index}].description")
+            }
+          end
+          interfaces = links.pluck("interface").map(&:downcase)
+          addresses = links.pluck("address").map { |value| value.split("/").first }
+          raise self.class::Error, "fabric link interfaces must be unique" unless interfaces.uniq.size == interfaces.size
+          raise self.class::Error, "fabric link addresses must be unique" unless addresses.uniq.size == addresses.size
+
+          loopback = cidr!(fabric["loopback"], "loopback", host: true)
+          raise self.class::Error, "underlay interface addresses must be unique" if addresses.include?(loopback.split("/").first)
+          result.merge!(
+            "loopback" => loopback,
+            "ospf_process_id" => identifier!(default_if_omitted(fabric["ospf_process_id"], "10"), "ospf_process_id"),
+            "ospf_area" => ospf_area!(default_if_omitted(fabric["ospf_area"], "0.0.0.0"), "ospf_area"),
+            "fabric_mtu" => integer!(default_if_omitted(fabric["fabric_mtu"], 9216), "fabric_mtu", 1500..9216),
+            "fabric_links" => links
+          )
+        end
+
+        def validate_cisco_overlay!(result, fabric)
+          neighbors = bootstrap_ipv4_list!(fabric["overlay_neighbors"], "overlay_neighbors", max: self.class::MAX_ROWS)
+          result.merge!(
+            "local_as" => asn!(fabric["local_as"], "local_as"),
+            "remote_as" => asn!(fabric["remote_as"], "remote_as"),
+            "overlay_neighbors" => neighbors
+          )
+          if result["device_role"] == "spine"
+            result["external_bgp_neighbors"] = []
+            return
+          end
+
+          result.merge!(
+            "vtep_loopback" => cidr!(fabric["vtep_loopback"], "vtep_loopback", host: true),
+            "vtep_secondary" => (cidr!(fabric["vtep_secondary"], "vtep_secondary", host: true) if provided?(fabric["vtep_secondary"]))
+          )
+          loopbacks = result.values_at("loopback", "vtep_loopback", "vtep_secondary").compact.map { |value| value.split("/").first }
+          raise self.class::Error, "loopback addresses must be unique" unless loopbacks.uniq.size == loopbacks.size
+          result["external_bgp_neighbors"] = result["device_role"] == "border" ? validate_external_bgp_neighbors!(fabric["external_bgp_neighbors"]) : []
+        end
+
+        def validate_external_bgp_neighbors!(value)
+          return [] if !provided?(value) || value == []
+          rows!(value, "external_bgp_neighbors").map.with_index do |neighbor, index|
+            row = exact!(neighbor, %w[address remote_as description], "external_bgp_neighbors[#{index}]")
+            {
+              "address" => ipv4!(row["address"], "external_bgp_neighbors[#{index}].address"),
+              "remote_as" => asn!(row["remote_as"], "external_bgp_neighbors[#{index}].remote_as"),
+              "description" => optional_description(row["description"], "external_bgp_neighbors[#{index}].description")
+            }.compact
+          end.tap do |neighbors|
+            addresses = neighbors.pluck("address")
+            raise self.class::Error, "external BGP neighbors must be unique" unless addresses.uniq.size == addresses.size
+          end
+        end
+
+        def validate_cisco_vpc!(result, fabric)
+          result.merge!(
+            "vpc_domain_id" => integer!(default_if_omitted(fabric["vpc_domain_id"], 1), "vpc_domain_id", 1..1000),
+            "vpc_role_priority" => integer!(default_if_omitted(fabric["vpc_role_priority"], 100), "vpc_role_priority", 1..65_535),
+            "vpc_peer_keepalive_destination" => ipv4!(fabric["vpc_peer_keepalive_destination"], "vpc_peer_keepalive_destination"),
+            "vpc_peer_keepalive_source" => ipv4!(fabric["vpc_peer_keepalive_source"], "vpc_peer_keepalive_source"),
+            "vpc_peer_link_port_channel" => integer!(default_if_omitted(fabric["vpc_peer_link_port_channel"], 998), "vpc_peer_link_port_channel", 1..4096)
+          )
+          if result["vpc_peer_keepalive_destination"] == result["vpc_peer_keepalive_source"]
+            raise self.class::Error, "vPC keepalive source and destination must be different"
+          end
+          virtual_destination = fabric["vpc_virtual_peer_link_destination"]
+          virtual_source = fabric["vpc_virtual_peer_link_source"]
+          if provided?(virtual_destination) != provided?(virtual_source)
+            raise self.class::Error, "vPC virtual peer-link source and destination must be provided together"
+          end
+          return unless provided?(virtual_destination)
+
+          result.merge!(
+            "vpc_virtual_peer_link_enabled" => true,
+            "vpc_virtual_peer_link_destination" => ipv4!(virtual_destination, "vpc_virtual_peer_link_destination"),
+            "vpc_virtual_peer_link_source" => ipv4!(virtual_source, "vpc_virtual_peer_link_source")
+          )
+        end
+
+        def bootstrap_interface_list!(value, path, max:)
+          unless value.is_a?(Array) && value.size.between?(1, max)
+            raise self.class::Error, "#{path} must contain 1 to #{max} values"
+          end
+          interfaces = value.map.with_index { |item, index| interface!(item, "#{path}[#{index}]") }
+          raise self.class::Error, "#{path} must be unique" unless interfaces.map(&:downcase).uniq.size == interfaces.size
+          interfaces
+        end
+
+        def bootstrap_ipv4_list!(value, path, max:)
+          unless value.is_a?(Array) && value.size.between?(1, max)
+            raise self.class::Error, "#{path} must contain 1 to #{max} values"
+          end
+          addresses = value.map.with_index { |item, index| ipv4!(item, "#{path}[#{index}]") }
+          raise self.class::Error, "#{path} must be unique" unless addresses.uniq.size == addresses.size
+          addresses
+        end
+      end
+    end
+  end
+end

data/lib/netstack/configuration/catalog.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Adapted from Motor Netconf scenario definitions and safe template dialect.
+require_relative "support"
+
+module Netstack
+  module Configuration
+    class Catalog
+      SCENARIOS = Values.copy([
+        { key: "bootstrap", group: "device", default_vendor: "h3c", vendors: %w[h3c cisco], templates: { "h3c" => "h3c-bootstrap.erb", "cisco" => "cisco-bootstrap.erb" } },
+        { key: "h3c-irf", group: "device", default_vendor: "h3c", vendors: %w[h3c], templates: { "h3c" => "h3c-irf.erb" } },
+        { key: "distributed-gateway", group: "network", default_vendor: "cisco", vendors: %w[cisco], templates: { "cisco" => "cisco-distributed-gateway.erb" } },
+        { key: "cisco-n9k-vpc", group: "network", default_vendor: "cisco", vendors: %w[cisco], templates: { "cisco" => "cisco-n9k-vpc.erb" } },
+        { key: "server-port", group: "network", default_vendor: "h3c", vendors: %w[h3c cisco], templates: { "h3c" => "h3c-server-port.erb", "cisco" => "cisco-server-port.erb" } },
+        { key: "hillstone-policy", group: "network", default_vendor: "hillstone", vendors: %w[hillstone], templates: { "hillstone" => "hillstone-policy.erb" } },
+        { key: "load-balancer", group: "application", default_vendor: "radware", vendors: %w[radware], templates: { "radware" => "radware-load-balancer.erb" } },
+        { key: "ipsec-vpn", group: "security", default_vendor: "paloalto", vendors: %w[paloalto hillstone], templates: { "paloalto" => "paloalto-ipsec-vpn.erb", "hillstone" => "hillstone-ipsec-vpn.erb" } }
+      ])
+      VARIABLES = Values.copy({
+        "bootstrap" => %w[
+          hostname device_role stp_priority mgmt mgmt_ip mgmt_mask mgmt_gateway snmp_location system
+          access_interface_start access_interface_end uplink_interfaces h3c_uplinks
+          access_auth_enabled access_auth_domain access_auth_vlan access_auth_interface_start access_auth_interface_end
+          underlay_enabled loopback loopback_ip ospf_process_id ospf_area fabric_mtu fabric_links
+          overlay_enabled local_as remote_as overlay_neighbors bgp_neighbors vtep_loopback vtep_secondary
+          nve_enabled route_reflector external_bgp_neighbors vtep_secondary_enabled advertise_pip
+          vpc_enabled vpc_domain_id vpc_role_priority
+          vpc_peer_keepalive_destination vpc_peer_keepalive_source vpc_virtual_peer_link_enabled
+          vpc_virtual_peer_link_destination vpc_virtual_peer_link_source vpc_peer_link_port_channel
+        ],
+        "h3c-irf" => %w[port1 port2 port3 port4 mad_port1 mad_port2 mad_vlan mad_subnet mad_mask mad_member1_ip mad_member2_ip],
+        "distributed-gateway" => %w[gateways],
+        "cisco-n9k-vpc" => %w[vpc_domain_id primary_role_priority secondary_role_priority primary_keepalive_ip secondary_keepalive_ip primary_virtual_peer_link_ip secondary_virtual_peer_link_ip vpc_peer_link_port_channel infra_vlan fabric_interfaces],
+        "server-port" => %w[stack_mode allocations aggregates],
+        "hillstone-policy" => %w[policies address_objects service_objects service_groups],
+        "load-balancer" => %w[next_hop route_metric services real_servers groups virtuals],
+        "ipsec-vpn" => %w[site_name tunnel local_interface local_address local_ip remote_ip add_route virtual_router route_metric dpd_interval dpd_retry hillstone_sa_index tunnel_zone preshared_key local_subnets remote_subnets ike_version ikev1 ikev2 ike_encryption ike_authentication ike_dh_group ike_lifetime ipsec_encryption ipsec_authentication ipsec_lifetime hillstone_ike_encryption hillstone_ipsec_encryption hillstone_ikev2_encryption hillstone_ipsec_v2_encryption hillstone_ike_hash hillstone_ipsec_hash hillstone_ike_group proxy_ids routes]
+      })
+
+      class << self
+        def all = SCENARIOS.deep_dup
+
+        def fetch(key)
+          SCENARIOS.find { |scenario| scenario.fetch(:key) == key.to_s } || raise(KeyError, "unknown scenario")
+        end
+
+        def template_key(scenario, vendor)
+          fetch(scenario).fetch(:templates).fetch(vendor.to_s) { raise KeyError, "unsupported vendor" }
+        end
+
+        def template_keys = SCENARIOS.flat_map { |scenario| scenario.fetch(:templates).values }.uniq
+
+        def variables_for_template(key)
+          scenario = SCENARIOS.find { |item| item.fetch(:templates).value?(key) } || raise(KeyError, "unknown template")
+          VARIABLES.fetch(scenario.fetch(:key))
+        end
+      end
+    end
+  end
+end

data/lib/netstack/configuration/generator.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+module Netstack
+  # 经过校验的场景输入、受限模板和敏感私有工件。
+  module Configuration
+    # 在本地生成工件；不向设备下发配置。
+    # 初始化批次必须全部校验完成，才渲染任何输出工件。
+    class Generator
+      def self.call(**options) = new.call(**options)
+
+      def initialize(store: TemplateStore.new, clock: -> { Time.now.utc })
+        @store = store
+        @clock = clock
+      end
+
+      # 批量初始化返回可独立引用的工件数组。
+      # 归档、邮件、加密和保留策略由宿主负责。
+      def call(scenario:, vendor:, input:, system_config: {}, settings: {})
+        values = Support.object(input)
+        now = @clock.call
+        if scenario.to_s == "bootstrap" && values.key?("devices")
+          return bootstrap_batch(vendor: vendor, input: values, system_config: system_config, settings: settings, now: now)
+        end
+        normalized = Validator.call(scenario: scenario, vendor: vendor, input: values, system_config: system_config, settings: settings)
+        render(scenario.to_s, vendor.to_s, normalized, now)
+      end
+
+      private
+
+      def bootstrap_batch(vendor:, input:, system_config:, settings:, now:)
+        raise InputError, "unexpected bootstrap batch fields" unless (input.keys - %w[devices system]).empty?
+        devices = input.fetch("devices")
+        unless devices.is_a?(Array) && devices.size.between?(1, Validator::MAX_ROWS)
+          raise InputError, "devices must contain 1 to #{Validator::MAX_ROWS} rows"
+        end
+        normalized = devices.map do |device|
+          row = Support.object(device, name: "bootstrap device")
+          raise InputError, "batch system overrides belong at the batch level" if row.key?("system")
+          row["system"] = input["system"] if input.key?("system")
+          Validator.call(scenario: "bootstrap", vendor: vendor, input: row, system_config: system_config, settings: settings)
+        end
+        hostnames = normalized.map { |row| row.fetch("hostname").downcase }
+        addresses = normalized.map { |row| row.fetch("mgmt").split("/").first }
+        raise InputError, "device hostnames and management addresses must be unique" unless hostnames.uniq.size == hostnames.size && addresses.uniq.size == addresses.size
+
+        normalized.map { |row| render("bootstrap", vendor.to_s, row, now) }.freeze
+      end
+
+      def render(scenario, vendor, normalized, now)
+        key = Catalog.template_key(scenario, vendor)
+        system = normalized.delete("system") || {}
+        data = Payload.call(scenario: scenario, input: normalized, system_config: system, now: now)
+        content = TemplateManager.new(key, data, store: @store).generate
+        prefix = normalized["hostname"] || normalized["site_name"] || "#{vendor}-#{scenario}"
+        filename = "#{prefix}-#{now.strftime("%Y%m%d%H%M%S")}.txt"
+        options = { scenario: scenario, vendor: vendor, created_at: now, template_sha256: @store.metadata(key).fetch(:sha256) }
+        sections = split_sections(scenario, content).to_h do |name, text|
+          [name, Artifact.new(filename: "#{prefix}-#{name}.txt", content: text, **options)]
+        end
+        Artifact.new(filename: filename, content: content, sections: sections, **options)
+      end
+
+      def split_sections(scenario, content)
+        markers = case scenario
+        when "cisco-n9k-vpc" then { "primary" => "! Primary switch", "secondary" => "! Secondary switch" }
+        when "h3c-irf" then { "master" => "# Stage 1 - master", "standby-renumber" => "# Stage 2 - standby renumber",
+          "standby-links" => "# Stage 3 - standby links", "mad" => "# Stage 4 - BFD MAD" }
+        else return {}
+        end
+        positions = markers.map do |name, marker|
+          matches = content.enum_for(:scan, /^#{Regexp.escape(marker)}$/).map { Regexp.last_match.begin(0) }
+          raise InputError, "multi-target template must preserve unique section markers" unless matches.one?
+
+          [name, matches.first]
+        end
+        raise InputError, "configuration sections are out of order" unless positions.map(&:last) == positions.map(&:last).sort
+
+        positions.each_with_index.to_h do |(name, start), index|
+          finish = positions[index + 1]&.last || content.length
+          [name, content[start...finish]]
+        end
+      end
+    end
+  end
+end

data/lib/netstack/configuration/input_contract.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Adapted from Motor Netconf scenario definitions and safe template dialect.
+require_relative "support"
+
+module Netstack
+  module Configuration
+    # Defines the HTTP input shape separately from template output variables.
+    class InputContract
+      EMPTY_FIELDS = [].freeze
+
+      SYSTEM_FIELDS = Values.copy([
+        :domain_name, :timezone, :management_vlan, :snmp_community,
+        :tacacs_secret, :radius_secret, :base_security_enabled,
+        :disable_telnet, :disable_http, :enable_bpdu_protection,
+        :password_min_length, :vty_timeout_minutes,
+        { ntp_servers: [], dns_servers: [], syslog_servers: [],
+          tacacs_servers: [], radius_servers: [], ssh_acl_cidrs: [],
+          local_users: %i[username password role] }
+      ])
+
+      BOOTSTRAP_DEVICE_FIELDS = Values.copy([
+        :hostname, :device_role, :mgmt, :mgmt_gateway, :snmp_location,
+        :access_auth_enabled, :access_auth_domain, :access_auth_vlan,
+        :access_auth_interface_start, :access_auth_interface_end,
+        :access_interface_start, :access_interface_end,
+        :underlay_enabled, :loopback, :ospf_process_id, :ospf_area,
+        :fabric_mtu, :overlay_enabled, :local_as, :remote_as,
+        :vtep_loopback, :vtep_secondary, :vpc_enabled, :vpc_domain_id,
+        :vpc_role_priority, :vpc_peer_keepalive_destination,
+        :vpc_peer_keepalive_source, :vpc_virtual_peer_link_destination,
+        :vpc_virtual_peer_link_source, :vpc_peer_link_port_channel,
+        { uplink_interfaces: [], overlay_neighbors: [],
+          fabric_links: %i[interface address description],
+          external_bgp_neighbors: %i[address remote_as description] }
+      ])
+
+      SCHEMAS = Values.copy({
+        "bootstrap" => [
+          *BOOTSTRAP_DEVICE_FIELDS,
+          { system: SYSTEM_FIELDS, devices: BOOTSTRAP_DEVICE_FIELDS }
+        ],
+        "h3c-irf" => %i[port1 port2 port3 port4 mad_port1 mad_port2 mad_vlan mad_subnet],
+        "distributed-gateway" => [ { gateways: %i[vlan subnet gateway vni name mtu vrf acl] } ],
+        "cisco-n9k-vpc" => [
+          :vpc_domain_id, :primary_role_priority, :secondary_role_priority,
+          :primary_keepalive_ip, :secondary_keepalive_ip,
+          :primary_virtual_peer_link_ip, :secondary_virtual_peer_link_ip,
+          :vpc_peer_link_port_channel, :infra_vlan, { fabric_interfaces: [] }
+        ],
+        "server-port" => [
+          :stack_mode,
+          { allocations: %i[local_iface local_description remote remote_iface vlan port_channel aggregate_id flag] }
+        ],
+        "hillstone-policy" => [
+          { policies: [
+            :description, :src_zone, :dst_zone, :protocol, :action, :log,
+            { src_addresses: [], dst_addresses: [], services: [] }
+          ] }
+        ],
+        "load-balancer" => [
+          { services: [
+            :flag, :virtual_ip, :service_port, :proxy_ip, :app_port,
+            :timeout, :group_name, :service_type, :health_check,
+            :client_ip_persistence, { real_ips: [] }
+          ] }
+        ],
+        "ipsec-vpn" => [
+          :site_name, :tunnel, :local_interface, :local_address, :remote_ip,
+          :add_route, :preshared_key, :ike_version, :ike_encryption,
+          :ike_authentication, :ike_dh_group, :ike_lifetime,
+          :ipsec_encryption, :ipsec_authentication, :ipsec_lifetime,
+          :virtual_router, :route_metric, :dpd_interval, :dpd_retry, :hillstone_sa_index, :tunnel_zone,
+          { local_subnets: [], remote_subnets: [] }
+        ]
+      })
+
+      # Unknown scenarios receive no input fields and are rejected by the catalog.
+      def self.fields_for(scenario) = SCHEMAS.fetch(scenario.to_s, EMPTY_FIELDS)
+    end
+  end
+end