netstack 0.1.1 → 0.2.0

data/lib/netstack/wireless/h3c/lldp_parser.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Wireless
+    module H3c
+      class LldpParser
+        def parse(content, ap_name:, terminated: false)
+          ap_name = Values.text(ap_name, name: "LLDP AP name")
+          text = Normalizer.text(content)
+          neighbors = []
+          diagnostics = []
+          current = nil
+          local = nil
+          flush = lambda do
+            if current && current[:remote_chassis_id] && current[:remote_interface]
+              neighbors << Neighbor.new(key: Normalizer.key(ap_name, local, current[:remote_chassis_id], current[:remote_interface]),
+                ap_name: ap_name, local_interface: local, **current)
+            elsif current
+              diagnostics << { code: :incomplete_neighbor }
+            end
+          end
+          text.lines.each_with_index do |line, index|
+            next if line.strip.empty? || /\A\s*[-=]+\s*\z/.match?(line)
+            if (match = /LLDP neighbor-information of port \d+\[(.*?)\]\s*:?/i.match(line))
+              flush.call
+              local = match[1]
+              current = nil
+            elsif /\ALLDP neighbor index\s*:/i.match?(line.strip)
+              flush.call
+              current = {}
+            elsif (match = /\A\s*([^:]+):\s*(.*?)\s*\z/.match(line))
+              label, value = match.captures
+              next if /total|number of neighbors/i.match?(label)
+              unless local
+                diagnostics << { code: :missing_local_interface, line: index + 1 }
+                next
+              end
+              current ||= {}
+              case label.strip.downcase
+              when "chassis id" then current[:remote_chassis_id] = value.downcase
+              when "port id" then current[:remote_interface] = value
+              when "system name" then current[:remote_name] = value
+              when "management address"
+                begin
+                  current[:management_address] = Normalizer.ip(Normalizer.value(value))
+                rescue InputError
+                  diagnostics << { code: :invalid_management_address, line: index + 1 }
+                end
+              when "system description", "port description", "port vlan id", "vlan id", "maximum frame size", "chassis type", "port type", "time to live", "system capabilities supported", "system capabilities enabled"
+                (current[:attributes] ||= {})[label.strip.downcase.tr(" ", "_").to_sym] = value
+              else diagnostics << { code: :unrecognized_field, line: index + 1 }
+              end
+            elsif !/no (?:LLDP )?neighbors|total.*\b0\b/i.match?(line)
+              diagnostics << { code: :unrecognized_line, line: index + 1 }
+            end
+          end
+          flush.call
+          count = /(?:total(?: (?:LLDP )?neighbors)?|number of neighbors)[^\n:]*:\s*(\d+)\s*$/i.match(text)&.[](1)&.to_i
+          diagnostics << { code: :count_mismatch, expected: count, parsed: neighbors.size } if count && count != neighbors.size
+          zero = /no (?:LLDP )?neighbors|(?:total|number of neighbors)[^\n]*:\s*0\s*$/i.match?(text)
+          diagnostics << { code: :missing_completeness_evidence } unless zero || (terminated && !neighbors.empty?)
+          ParseResult.new(records: neighbors, status: diagnostics.empty? ? :complete : neighbors.empty? ? :failed : :partial, diagnostics: diagnostics)
+        rescue InputError => error
+          ParseResult.new(records: [], status: :failed, diagnostics: [{ code: :invalid_output, error: error.code }])
+        end
+      end
+    end
+  end
+end

data/lib/netstack/wireless/h3c/runtime_parser.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Wireless
+    module H3c
+      # CLI grammar adapted from PDK::Inspection::Runtime::H3c::WirelessAp::Parser.
+      class RuntimeParser
+        AP_FIELDS = { "ap id" => :ap_id, "ap group name" => :group_name, "state" => :state, "model" => :model,
+          "mac address" => :mac_address, "ip address" => :ip_address, "client count" => :client_count,
+          "number of clients" => :client_count, "online clients" => :client_count, "online time" => :online_seconds }.freeze
+        RADIO_FIELDS = { "state" => :admin_state, "admin state" => :admin_state, "radio type" => :radio_type,
+          "channel" => :channel, "channel usage(%)" => :channel_usage, "channel usage" => :channel_usage,
+          "noise floor" => :noise_floor }.freeze
+        CLIENT_FIELDS = { "ap name" => :ap_name, "ap id" => :ap_id, "radio id" => :radio_id, "ssid" => :ssid,
+          "bssid" => :bssid, "ipv4 address" => :ip_address, "ip address" => :ip_address, "ipv6 address" => :ipv6_address,
+          "vlan id" => :vlan_id, "rssi" => :rssi, "online time" => :online_seconds }.freeze
+        CLIENT_AUTH = %w[username authentication\ method security\ mode akm\ mode cipher\ suite user\ authentication\ mode wpa3\ status pmf\ status].freeze
+        CLIENT_TERMINAL = %w[sm\ power\ save short\ gi\ for\ 20mhz stbc\ rx\ capability ldpc\ rx\ capability ofdma\ random\ access\ rus twt\ scheduled qos\ mode listen\ interval].freeze
+        CLIENT_ATTRIBUTES = %w[aid channel wireless\ mode channel\ bandwidth roam\ status btm\ mode].freeze
+        BSS_FIELDS = { "ap name" => :ap_name, "ap id" => :ap_id, "radio id" => :radio_id, "ssid" => :ssid,
+          "service template" => :service_template, "service template name" => :service_template,
+          "vlan id" => :vlan_id, "state" => :state, "client count" => :client_count,
+          "number of clients" => :client_count, "online clients" => :client_count }.freeze
+        AUTH_FIELDS = { "username" => :username, "user name" => :username, "access interface" => :interface,
+          "interface" => :interface, "ap name" => :ap_name, "ap id" => :ap_id, "radio id" => :radio_id,
+          "ssid" => :ssid, "bssid" => :bssid, "ip address" => :ip_address, "ipv4 address" => :ip_address,
+          "authentication domain" => :domain, "domain" => :domain, "authentication protocol" => :protocol,
+          "auth protocol" => :protocol, "access protocol" => :protocol, "protocol" => :protocol,
+          "authentication state" => :state, "state" => :state, "status" => :state,
+          "initial vlan" => :initial_vlan_id, "initial vlan id" => :initial_vlan_id,
+          "authorization vlan" => :authorized_vlan_id, "authorization vlan id" => :authorized_vlan_id,
+          "authorized vlan" => :authorized_vlan_id, "authorized vlan id" => :authorized_vlan_id,
+          "online time" => :online_seconds }.freeze
+
+        def parse(dimension, content, terminated: false)
+          text = Normalizer.text(content)
+          case dimension.to_sym
+          when :access_points, :radios then parse_access_points(text, dimension.to_sym, terminated: terminated)
+          when :clients then parse_blocks(text, :clients, /\Amac address\z/, terminated: terminated)
+          when :bsses then parse_blocks(text, :bsses, /\Abssid\z/, terminated: terminated)
+          when :dot1x_connections, :mab_connections
+            parse_blocks(text, dimension.to_sym, /\A(?:user )?mac address\z/, terminated: terminated)
+          when :blocked_clients then parse_blocked_clients(text, terminated: terminated)
+          else raise InputError, "unsupported H3c wireless dimension"
+          end
+        rescue InputError => error
+          ParseResult.new(records: [], status: :failed, diagnostics: [{ code: :invalid_output, error: error.code }])
+        end
+
+        private
+
+        def parse_access_points(text, dimension, terminated:)
+          aps = []
+          radios = []
+          diagnostics = []
+          current = radio = nil
+          each_field(text, diagnostics) do |label, value, line|
+            if label == "ap name"
+              current = { name: value }
+              aps << current
+              radio = nil
+            elsif current && (match = /\Aradio (\d+)\z/.match(label))
+              radio = { ap_name: current[:name], radio_id: match[1].to_i }
+              radios << radio
+            elsif radio && RADIO_FIELDS.key?(label)
+              safely(diagnostics, line) { assign(radio, RADIO_FIELDS.fetch(label), value) }
+            elsif current && AP_FIELDS.key?(label)
+              safely(diagnostics, line) { assign(current, AP_FIELDS.fetch(label), value) }
+            elsif current && label == "capwap data-tunnel status"
+              (current[:configuration] ||= {})[:capwap_data_tunnel_status] = value
+            elsif !summary?(label)
+              diagnostics << { code: :unrecognized_field, line: line }
+            end
+          end
+          records = if dimension == :access_points
+            aps.filter_map do |attributes|
+              next if attributes[:name].nil?
+
+              AccessPoint.new(key: Normalizer.key(attributes[:name]), **attributes)
+            end
+          else
+            radios.map { |attributes| Radio.new(key: Normalizer.key(attributes[:ap_name], attributes[:radio_id]), **attributes) }
+          end
+          total = total_count(text, :access_points)
+          diagnostics << { code: :count_mismatch, expected: total, parsed: aps.size } if total && total != aps.size
+          result(records, diagnostics, total: total, terminated: terminated, recognized: !aps.empty?)
+        end
+
+        def parse_blocks(text, dimension, start, terminated:)
+          blocks = []
+          current = nil
+          diagnostics = []
+          each_field(text, diagnostics) do |label, value, line|
+            if start.match?(label)
+              current = { (dimension == :bsses ? :bssid : :mac_address) => value }
+              blocks << current
+            elsif current
+              current[:fields] ||= []
+              current[:fields] << [label, value, line]
+            elsif !summary?(label)
+              diagnostics << { code: :unrecognized_field, line: line }
+            end
+          end
+          records = blocks.filter_map do |block|
+            safely(diagnostics, nil) do
+              fields = block.delete(:fields) || []
+              identity_field = dimension == :bsses ? :bssid : :mac_address
+              block[identity_field] = Normalizer.mac(block[identity_field])
+              raise InputError, "missing wireless identity" unless block[identity_field]
+
+              fields.each { |label, value, line| safely(diagnostics, line) { block_field(block, dimension, label, value, diagnostics, line) } }
+              build_record(block, dimension)
+            end
+          end
+          total = total_count(text, dimension)
+          diagnostics << { code: :count_mismatch, expected: total, parsed: records.size } if total && total != records.size
+          result(records, diagnostics, total: total, terminated: terminated)
+        end
+
+        def block_field(record, dimension, label, value, diagnostics, line)
+          mapping = dimension == :clients ? CLIENT_FIELDS : dimension == :bsses ? BSS_FIELDS : AUTH_FIELDS
+          if mapping.key?(label)
+            assign(record, mapping.fetch(label), value)
+          elsif dimension == :clients && CLIENT_AUTH.include?(label)
+            (record[:authentication] ||= {})[label.tr(" -", "__").to_sym] = value
+          elsif dimension == :clients && CLIENT_TERMINAL.include?(label)
+            (record[:terminal] ||= {})[label.tr(" -", "__").to_sym] = value
+          elsif dimension == :clients && CLIENT_ATTRIBUTES.include?(label)
+            (record[:attributes] ||= {})[label.tr(" -", "__").to_sym] = value
+          elsif dimension == :clients && ["rx/tx rate", "speed"].include?(label)
+            rates = value && Normalizer.rate_pair(value, default: label == "speed" ? "Kbps" : "Mbps")
+            if label == "speed"
+              (record[:attributes] ||= {})[:throughput_bps] = rates
+            else
+              record[:rx_rate_bps], record[:tx_rate_bps] = rates
+            end
+          elsif dimension == :bsses && ["security mode", "akm mode", "cipher suite", "bss id"].include?(label)
+            (record[:security] ||= {})[label.tr(" ", "_").to_sym] = value
+          elsif dimension != :clients && label == "authentication method"
+            record[:protocol] ||= value
+          else
+            diagnostics << { code: :unrecognized_field, line: line }
+          end
+        end
+
+        def build_record(attributes, dimension)
+          case dimension
+          when :clients
+            rssi = attributes[:rssi]
+            attributes[:rssi] = nil if rssi == 0
+            Client.new(key: Normalizer.key(attributes[:mac_address]), rssi_scale: rssi && rssi < 0 ? :dbm : :relative, **attributes)
+          when :bsses
+            Bss.new(key: Normalizer.key(attributes[:bssid]), **attributes)
+          else
+            kind = dimension == :dot1x_connections ? :dot1x : :mab
+            AuthenticationConnection.new(key: Normalizer.key(kind, attributes[:mac_address], attributes[:interface], attributes[:bssid]), kind: kind, **attributes)
+          end
+        end
+
+        def assign(record, key, value)
+          record[key] = case key
+          when :ap_id, :radio_id, :client_count then Normalizer.integer(value)
+          when :vlan_id, :initial_vlan_id, :authorized_vlan_id then Normalizer.integer(value, max: 4094)
+          when :mac_address, :bssid then Normalizer.mac(value)
+          when :ip_address, :ipv6_address then Normalizer.ip(value)
+          when :online_seconds then Normalizer.duration(value)
+          when :rssi then Normalizer.number(value, unit: "dBm")
+          when :noise_floor then Normalizer.number(value, unit: "dBm")&.then { |number| number.negative? ? number : nil }
+          when :channel_usage
+            number = Normalizer.number(value, unit: "%")
+            raise InputError, "invalid channel usage" if number && !(0..100).cover?(number)
+            number
+          else value
+          end
+          record[:channel_number] = Normalizer.channel(value) if key == :channel
+        end
+
+        def each_field(text, diagnostics)
+          text.lines.each_with_index do |line, index|
+            next if line.strip.empty? || /\A\s*[-=]+\s*\z/.match?(line)
+            match = /\A\s*([^:]+?)\s*:\s*(.*?)\s*\z/.match(line)
+            unless match
+              diagnostics << { code: :unrecognized_line, line: index + 1 }
+              next
+            end
+            yield match[1].strip.downcase.gsub(/\s+/, " "), Normalizer.value(match[2]), index + 1
+          end
+        end
+
+        def total_count(text, dimension)
+          noun = { access_points: "APs", clients: "clients", bsses: "BSSs?", dot1x_connections: "(?:connections|users|online users)", mab_connections: "(?:connections|users|online users)" }.fetch(dimension)
+          match = /(?:Total(?: number of)?\s+(?:#{noun})|Total)\s*:\s*(\d+)\s*$/i.match(text)
+          match && match[1].to_i
+        end
+
+        def summary?(label) = /\A(?:total|number of|connected|remaining|maximum|current number)\b/.match?(label)
+
+        def safely(diagnostics, line)
+          yield
+        rescue InputError
+          diagnostics << { code: :invalid_field, line: line }.compact
+          nil
+        end
+
+        def result(records, diagnostics, total:, terminated:, recognized: !records.empty?)
+          diagnostics << { code: :missing_completeness_evidence } unless total || (terminated && recognized)
+          status = diagnostics.empty? ? :complete : records.empty? ? :failed : :partial
+          ParseResult.new(records: records, status: status, diagnostics: diagnostics)
+        end
+
+        def parse_blocked_clients(text, terminated:)
+          records = []
+          diagnostics = []
+          explicit_zero = false
+          text.lines.each_with_index do |line, index|
+            next if line.strip.empty? || /\A\s*[-=]+\s*\z/.match?(line)
+            if /\A\s*No blocked clients\s*\z/i.match?(line)
+              explicit_zero = true
+              next
+            end
+            if /\A\s*(?:MAC address(?:\s+.*)?|(?:Client )?block list|Blocked clients|Total(?: number of)?(?:\s+\w+)*\s*:\s*\d+)\s*\z/i.match?(line)
+              next
+            end
+            match = /\A\s*((?:[0-9a-f]{4}-){2}[0-9a-f]{4}|(?:[0-9a-f]{2}:){5}[0-9a-f]{2})\s*(.*?)\s*\z/i.match(line)
+            if match
+              mac = Normalizer.mac(match[1])
+              records << { key: Normalizer.key(mac), mac_address: mac, reason: match[2] }
+            else
+              diagnostics << { code: :unrecognized_line, line: index + 1 }
+            end
+          end
+          count = /Total(?: number of)?(?:\s+\w+)*\s*:\s*(\d+)/i.match(text)&.[](1)&.to_i
+          count ||= 0 if explicit_zero
+          diagnostics << { code: :count_mismatch, expected: count, parsed: records.size } if count && count != records.size
+          result(records, diagnostics, total: count, terminated: terminated)
+        end
+      end
+    end
+  end
+end

data/lib/netstack/wireless/huawei/runtime_parser.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Wireless
+    module Huawei
+      # Only the AP and station table formats evidenced by PDK are supported.
+      class RuntimeParser
+        def parse(dimension, content, terminated: false)
+          raise InputError, "unsupported Huawei wireless dimension" unless %i[access_points clients].include?(dimension.to_sym)
+
+          text = Normalizer.text(content)
+          records = []
+          diagnostics = []
+          header = false
+          total = nil
+          text.lines.each_with_index do |line, index|
+            row = line.strip
+            next if row.empty? || /\A[-=]+\z/.match?(row)
+            if (match = /\ATotal\s*:\s*(\d+)\s*\z/i.match(row))
+              total = match[1].to_i
+              next
+            end
+            if dimension.to_sym == :access_points ? /\AID\s+MAC\s+Name\s+Group\s+IP\s+Type\s+State\s+STA\s+Uptime\b/i.match?(row) : /\ASTA MAC\s+AP ID\s+Ap name\s+Rf\/WLAN\b/i.match?(row)
+              header = true
+              next
+            end
+            next if /\ATotal AP information:|\A(?:nor|fault|idle|stdby)\s*:/i.match?(row)
+            unless header
+              diagnostics << { code: :missing_header, line: index + 1 }
+              next
+            end
+            begin
+              records << (dimension.to_sym == :access_points ? access_point(row) : client(row))
+            rescue InputError
+              diagnostics << { code: :invalid_row, line: index + 1 }
+            end
+          end
+          diagnostics << { code: :missing_header } unless header
+          diagnostics << { code: :count_mismatch, expected: total, parsed: records.size } if total && total != records.size
+          diagnostics << { code: :missing_completeness_evidence } unless total || (terminated && header && !records.empty?)
+          ParseResult.new(records: records, status: diagnostics.empty? ? :complete : records.empty? ? :failed : :partial, diagnostics: diagnostics)
+        rescue InputError => error
+          ParseResult.new(records: [], status: :failed, diagnostics: [{ code: :invalid_output, error: error.code }])
+        end
+
+        private
+
+        def access_point(row)
+          columns = row.split(/\s+/)
+          raise InputError, "invalid AP table row" unless columns.size >= 9
+
+          id, mac, name, group, ip, model, state, clients, uptime = columns
+          state = { "nor" => "Normal", "normal" => "Normal", "fault" => "Fault", "idle" => "Idle", "stdby" => "Standby" }.fetch(state.downcase, state)
+          AccessPoint.new(key: Normalizer.key(name), name: name, ap_id: Normalizer.integer(id),
+            mac_address: Normalizer.mac(mac), group_name: group, ip_address: Normalizer.ip(Normalizer.value(ip)),
+            model: model, state: state, client_count: Normalizer.integer(clients), online_seconds: Normalizer.duration(Normalizer.value(uptime)))
+        end
+
+        def client(row)
+          columns = row.split(/\s+/)
+          raise InputError, "invalid station table row" unless columns.size == 15
+
+          mac, ap_id, ap_name, radio_wlan, band, type, rates, rssi, vlan, ipv4, ssid, state, ipv6, ac_id, online = columns
+          raise InputError, "invalid station identity" unless /\A\d+\/\d+\z/.match?(radio_wlan)
+
+          build_client(mac, ap_id, ap_name, radio_wlan, band, type, rates, rssi, vlan, ipv4, ssid, state, ipv6, ac_id, online)
+        end
+
+        def build_client(mac, ap_id, ap_name, radio_wlan, band, type, rates, rssi, vlan, ipv4, ssid, state, ipv6, ac_id, online)
+          address = Normalizer.mac(mac)
+          rx, tx = Normalizer.rate_pair(rates)
+          signal = Normalizer.number(Normalizer.value(rssi), unit: "dBm")
+          signal = nil if signal == 0
+          Client.new(key: Normalizer.key(address), mac_address: address, ap_id: Normalizer.integer(ap_id), ap_name: ap_name,
+            radio_id: Normalizer.integer(radio_wlan.split("/").first), ssid: ssid, vlan_id: Normalizer.integer(vlan, max: 4094),
+            ip_address: Normalizer.ip(Normalizer.value(ipv4)), ipv6_address: Normalizer.ip(Normalizer.value(ipv6)),
+            rssi: signal, rssi_scale: :dbm, online_seconds: Normalizer.duration(Normalizer.value(online)), rx_rate_bps: rx, tx_rate_bps: tx,
+            attributes: { band: band, wireless_mode: type, state: state, wlan_id: radio_wlan.split("/").last.to_i, ac_id: Normalizer.integer(ac_id) })
+        end
+      end
+    end
+  end
+end

data/lib/netstack/wireless/invalid_snapshot.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Wireless
+    class InvalidSnapshot < InputError
+      def initialize(message = "invalid wireless snapshot", **options)
+        super(message, code: :invalid_wireless_snapshot, **options)
+      end
+    end
+  end
+end

data/lib/netstack/wireless/neighbor.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Wireless
+    class Neighbor < Data.define(:key, :ap_name, :local_interface, :remote_chassis_id, :remote_interface, :remote_name, :management_address, :attributes)
+      def initialize(key:, ap_name:, local_interface:, remote_chassis_id:, remote_interface:, remote_name: nil, management_address: nil, attributes: {})
+        key = Values.text(key, name: "wireless record key")
+        super(**Values.copy(key: key, ap_name: ap_name, local_interface: local_interface, remote_chassis_id: remote_chassis_id, remote_interface: remote_interface, remote_name: remote_name, management_address: management_address, attributes: attributes))
+      end
+    end
+  end
+end

data/lib/netstack/wireless/normalizer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Netstack
+  module Wireless
+    module Normalizer
+      module_function
+
+      def text(content)
+        raise InputError, "wireless output must be text" unless content.is_a?(String)
+
+        result = content.dup.force_encoding(Encoding::UTF_8)
+        raise InputError, "invalid wireless output encoding" unless result.valid_encoding? && !result.include?("\0")
+
+        result.gsub(/\r\n?/, "\n")
+      end
+
+      def value(text)
+        normalized = text.strip
+        %w[N/A -- -].include?(normalized) || normalized.empty? ? nil : normalized
+      end
+
+      def mac(value)
+        return nil if value.nil?
+        unless /\A(?:[0-9a-f]{12}|(?:[0-9a-f]{4}[-.]){2}[0-9a-f]{4}|(?:[0-9a-f]{2}:){5}[0-9a-f]{2})\z/i.match?(value)
+          raise InputError, "invalid wireless MAC address"
+        end
+
+        value.delete("-.:").downcase.scan(/../).join(":")
+      end
+
+      def ip(value)
+        return nil if value.nil?
+        raise InputError, "invalid wireless IP address" if value.include?("/") || value.include?("%")
+
+        IPAddr.new(value).to_s
+      rescue IPAddr::InvalidAddressError
+        raise InputError, "invalid wireless IP address"
+      end
+
+      def integer(value, max: nil)
+        return nil if value.nil?
+
+        Values.integer(value, name: "wireless integer", min: 0, max: max)
+      end
+
+      def number(value, unit: nil)
+        return nil if value.nil?
+
+        pattern = unit ? /\A(-?\d+(?:\.\d+)?)\s*(?:#{Regexp.escape(unit)})?\z/i : /\A(-?\d+(?:\.\d+)?)\z/
+        match = pattern.match(value.to_s)
+        raise InputError, "invalid wireless number" unless match
+
+        Float(match[1])
+      end
+
+      def duration(value)
+        return nil if value.nil?
+        return value.split(":").map(&:to_i).zip([86_400, 3600, 60, 1]).sum { |a, b| a * b } if /\A\d+:\d{2}:\d{2}:\d{2}\z/.match?(value)
+
+        parts = value.scan(/(\d+)\s*(days?|hours?|minutes?|seconds?|[dhms])\b/i)
+        rest = value.gsub(/\d+\s*(?:days?|hours?|minutes?|seconds?|[dhms])\b/i, "").delete(" :,")
+        raise InputError, "invalid wireless duration" if parts.empty? || !rest.empty?
+
+        parts.sum { |n, unit| n.to_i * { "d" => 86_400, "h" => 3600, "m" => 60, "s" => 1 }.fetch(unit[0].downcase) }
+      end
+
+      def rate_pair(value, default: "Mbps")
+        match = /\A(\d+(?:\.\d+)?)\s*\/\s*(\d+(?:\.\d+)?)\s*([kmgt]?bps)?\z/i.match(value)
+        raise InputError, "invalid wireless rate" unless match
+
+        multiplier = { "bps" => 1, "kbps" => 1000, "mbps" => 1000_000, "gbps" => 1000_000_000, "tbps" => 1000_000_000_000 }.fetch((match[3] || default).downcase)
+        [match[1], match[2]].map { |number| (Float(number) * multiplier).round }
+      end
+
+      # A length-prefixed composite key cannot collide when names contain punctuation.
+      def key(*parts) = parts.map { |part| text = part.to_s; "#{text.bytesize}:#{text}" }.join("|")
+
+      def channel(value)
+        return nil if value.nil? || /\Aauto\z/i.match?(value)
+
+        match = /\A(\d+)(?:\s*\([^\n]*\))?\z/.match(value)
+        raise InputError, "invalid wireless channel" unless match
+
+        integer(match[1], max: 233)
+      end
+    end
+  end
+end

data/lib/netstack/wireless/parse_result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Wireless
+    class ParseResult < Data.define(:records, :status, :diagnostics)
+      def initialize(records:, status:, diagnostics: [])
+        raise InputError, "invalid parser status" unless %i[complete partial failed].include?(status)
+
+        super(records: Values.copy(records), status: status, diagnostics: Values.copy(diagnostics))
+      end
+    end
+  end
+end

data/lib/netstack/wireless/radio.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Wireless
+    class Radio < Data.define(:key, :ap_name, :radio_id, :admin_state, :radio_type, :channel, :channel_number, :channel_usage, :noise_floor, :configuration)
+      def initialize(key:, ap_name:, radio_id:, admin_state: nil, radio_type: nil, channel: nil, channel_number: nil, channel_usage: nil, noise_floor: nil, configuration: {})
+        key = Values.text(key, name: "wireless record key")
+        super(**Values.copy(key: key, ap_name: ap_name, radio_id: radio_id, admin_state: admin_state, radio_type: radio_type, channel: channel, channel_number: channel_number, channel_usage: channel_usage, noise_floor: noise_floor, configuration: configuration))
+      end
+    end
+  end
+end

data/lib/netstack/wireless/reconciler.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Wireless
+    # 生成新的保留状态而不持久化；部分观察只合并已知字段，
+    # 不能删除缺失身份；时间水位用于拒绝过期输入。
+    class Reconciler
+      def call(previous:, observed:)
+        raise InvalidSnapshot, "wireless observation must be a Snapshot" unless observed.is_a?(Snapshot)
+        previous = State.from_snapshot(previous) if previous.is_a?(Snapshot)
+        previous ||= State.new(target: observed.target)
+        raise InvalidSnapshot, "wireless state must be a State" unless previous.is_a?(State)
+        if previous.target.key != observed.target.key || previous.target.platform != observed.target.platform || previous.target.host != observed.target.host
+          raise InvalidSnapshot, "wireless snapshots belong to different controllers"
+        end
+
+        records = previous.records.dup
+        watermarks = previous.watermarks.dup
+        changes = {}
+        observed.dimensions.each do |dimension|
+          prior = (records[dimension.name] || []).to_h { |record| [key(record), record] }
+          if dimension.status != :not_requested
+            raise InvalidSnapshot, "wireless observation has no collection time" unless dimension.completed_at
+            if watermarks[dimension.name] && dimension.completed_at < watermarks[dimension.name]
+              raise InvalidSnapshot, "stale wireless dimension"
+            end
+            watermarks[dimension.name] = dimension.completed_at
+          end
+          same_time = previous.watermarks[dimension.name] && dimension.completed_at == previous.watermarks[dimension.name]
+          incoming = dimension.records.to_h { |record| [key(record), record] }
+          if dimension.partial?
+            incoming = incoming.transform_values do |record|
+              old = prior[key(record)]
+              old ? merge_record(old, record) : record
+            end
+          end
+          next_records = if dimension.complete?
+            incoming
+          elsif dimension.partial?
+            prior.merge(incoming)
+          else
+            prior
+          end
+          raise InvalidSnapshot, "conflicting wireless observations at the same time" if same_time && next_records != prior
+          changes[dimension.name] = {
+            added: next_records.keys - prior.keys,
+            updated: (next_records.keys & prior.keys).select { |identity| next_records[identity] != prior[identity] },
+            removed: prior.keys - next_records.keys,
+            retained: prior.keys - incoming.keys,
+            status: dimension.status
+          }
+          records[dimension.name] = next_records.values
+        end
+        state = State.new(target: observed.target, records: records, watermarks: watermarks)
+        Reconciliation.new(state: state, changes: changes, observation: observed)
+      end
+
+      private
+
+      def key(record) = record.is_a?(Hash) ? record.fetch(:key) : record.key
+
+      def merge_record(old, current)
+        return old.merge(current.reject { |_, value| value.nil? }) if old.is_a?(Hash)
+        if current.is_a?(Configuration)
+          return Configuration.new(access_points: merge_hash(old.access_points, current.access_points),
+            ap_groups: merge_records(old.ap_groups, current.ap_groups), service_templates: merge_records(old.service_templates, current.service_templates),
+            global_settings: merge_hash(old.global_settings, current.global_settings),
+            blacklist: merge_mac_entries(old.blacklist, current.blacklist),
+            whitelist: merge_mac_entries(old.whitelist, current.whitelist))
+        end
+        current.class.new(**old.to_h.merge(current.to_h) do |_, before, after|
+          if after.nil?
+            before
+          elsif before.is_a?(Hash) && after.is_a?(Hash)
+            merge_hash(before, after)
+          elsif before.is_a?(Array) && after.is_a?(Array)
+            (before + after).uniq
+          else
+            after
+          end
+        end)
+      end
+
+      def merge_records(old, current)
+        values = old.to_h { |record| [record.key, record] }
+        current.each { |record| values[record.key] = values[record.key] ? merge_record(values[record.key], record) : record }
+        values.values
+      end
+
+      # 部分名单按 MAC 更新已观测字段，保留缺失字段和未观测身份，不能授权删除。
+      def merge_mac_entries(old, current)
+        values = old.to_h { |record| [record.fetch(:mac_address), record] }
+        current.each do |record|
+          identity = record.fetch(:mac_address)
+          values[identity] = values[identity] ? merge_record(values[identity], record) : record
+        end
+        values.values
+      end
+
+      def merge_hash(old, current)
+        old.merge(current) do |field, before, after|
+          if field == :service_templates && before.is_a?(Array) && after.is_a?(Array)
+            ServiceTemplateBindings.merge(before, after)
+          elsif before.is_a?(Hash) && after.is_a?(Hash)
+            merge_hash(before, after)
+          elsif before.is_a?(Array) && after.is_a?(Array)
+            (before + after).uniq
+          else
+            after.nil? ? before : after
+          end
+        end
+      end
+    end
+  end
+end

data/lib/netstack/wireless/reconciliation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Wireless
+    class Reconciliation < Data.define(:state, :changes, :observation)
+      def initialize(state:, changes:, observation:)
+        super(state: Values.copy(state), changes: Values.copy(changes), observation: Values.copy(observation))
+      end
+    end
+  end
+end