netstack 0.1.1 → 0.2.0

data/lib/netstack/inventory/collector.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Netstack
+  # 按来源和范围组织观察结果与变更建议；持久化由宿主负责。
+  module Inventory
+    # 管理代码块内的设备连接，只读取已请求且受支持的维度。
+    # 单个维度失败不会使其他已完成的观察失效。
+    class Collector
+      DIMENSIONS = %i[device interfaces transceivers neighbors].freeze
+
+      def initialize(connector: Connector, parser: CliParser.new, clock: -> { Time.now.utc })
+        @connector = connector
+        @parser = parser
+        @clock = clock
+      end
+
+      def collect(target:, dimensions: %i[device interfaces neighbors], connection_options: {}, scope: {})
+        raise InputError, "collection target must be a Target" unless target.is_a?(Target)
+        unless dimensions.is_a?(Array) && dimensions.all? { |name| DIMENSIONS.include?(name) } && dimensions.uniq == dimensions
+          raise InputError, "unknown or duplicate inventory dimensions"
+        end
+        unless connection_options.is_a?(Hash) && !connection_options.key?(:host) && !connection_options.key?("host")
+          raise InputError, "connection options cannot override the target host"
+        end
+        result = DIMENSIONS.to_h { |name| [name, Dimension.new(name: name, status: :not_requested)] }
+        scope = Snapshot.new(target: target, source: "cli", dimensions: result, scope: scope).scope
+        dimensions.each { |name| result[name] = Dimension.new(name: name, status: :unsupported) }
+        supported = dimensions.select { |name| name == :neighbors || (name != :transceivers && @parser.supports?(target.platform)) }
+        return Snapshot.new(target: target, source: "cli", dimensions: result, scope: scope) if supported.empty?
+
+        begin
+          @connector.open(target.platform, host: target.host, **connection_options) do |device|
+            configuration = nil
+            configuration_error = nil
+            configuration_started = @clock.call
+            if (supported & %i[device interfaces]).any?
+              begin
+                configuration = device.running_config.value!
+              rescue StandardError => error
+                configuration_error = error
+              end
+            end
+            supported.each do |name|
+              next if name == :neighbors && !device.supports?(:neighbors)
+
+              started = name == :neighbors ? @clock.call : configuration_started
+              begin
+                raise configuration_error if configuration_error && name != :neighbors
+
+                records = collect_dimension(name, device, target, configuration)
+                if scope.key?(name)
+                  keys = scope.fetch(name)
+                  records = records.select { |record| keys.include?(record.key) }
+                end
+                evidence = name == :neighbors ? [] : [{ kind: :configuration, sha256: Digest::SHA256.hexdigest(configuration) }]
+                result[name] = Dimension.new(name: name, status: :complete, records: records, started_at: started,
+                  completed_at: @clock.call, evidence: evidence)
+              rescue StandardError => error
+                result[name] = failure(name, error, started)
+              end
+            end
+          end
+        rescue StandardError => error
+          supported.each do |name|
+            result[name] = failure(name, error, @clock.call) unless result[name].complete?
+          end
+        end
+        Snapshot.new(target: target, source: "cli", dimensions: result, scope: scope)
+      end
+
+      private
+
+      def collect_dimension(name, device, target, configuration)
+        case name
+        when :device
+          command = target.platform.start_with?("cisco") ? "show version" : "display version"
+          version = device.execute_command(command).value!
+          [@parser.device(configuration: configuration, version: version, target: target)]
+        when :interfaces
+          @parser.interfaces(configuration: configuration, platform: target.platform)
+        when :neighbors
+          device.neighbors.map do |neighbor|
+            Neighbor.new(local_interface: neighbor.local_interface, remote_name: neighbor.neighbor_name,
+              remote_interface: neighbor.neighbor_interface, chassis_id: neighbor.chassis_id,
+              attributes: { protocol: neighbor.protocol })
+          end
+        end
+      end
+
+      def failure(name, error, started)
+        code = error.respond_to?(:code) ? error.code : :collection_failed
+        Dimension.new(name: name, status: :failed, started_at: started, completed_at: @clock.call,
+          diagnostics: [{ code: code }])
+      end
+    end
+  end
+end

data/lib/netstack/inventory/device.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Inventory
+    class Device < Data.define(:key, :name, :serial, :model, :vendor, :os_version, :attributes)
+      def initialize(key:, name: nil, serial: nil, model: nil, vendor: nil, os_version: nil, attributes: {})
+        super(key: Values.text(key, name: "device key"), name: Values.text(name, name: "device name", optional: true),
+          serial: Values.text(serial, name: "serial", optional: true), model: Values.text(model, name: "model", optional: true),
+          vendor: Values.text(vendor, name: "vendor", optional: true), os_version: Values.text(os_version, name: "OS version", optional: true),
+          attributes: Values.copy(attributes))
+      end
+    end
+  end
+end

data/lib/netstack/inventory/interface.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Inventory
+    class Interface < Data.define(:name, :description, :admin_status, :oper_status, :addresses, :attributes)
+      def initialize(name:, description: nil, admin_status: :unknown, oper_status: :unknown, addresses: [], attributes: {})
+        statuses = [admin_status, oper_status].map do |status|
+          status = status.to_sym if status.is_a?(String)
+          raise InputError, "invalid interface status" unless %i[up down unknown].include?(status)
+
+          status
+        end
+        unless addresses.is_a?(Array) && addresses.all? { |address| address.is_a?(Address) }
+          raise InputError, "interface addresses must be Address values"
+        end
+        raise InputError, "description must be text or nil" unless description.nil? || description.is_a?(String)
+
+        super(name: Values.text(name, name: "interface name"), description: Values.copy(description),
+          admin_status: statuses[0], oper_status: statuses[1], addresses: addresses.dup.freeze, attributes: Values.copy(attributes))
+      end
+
+      def key = name.downcase
+    end
+  end
+end

data/lib/netstack/inventory/neighbor.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Inventory
+    class Neighbor < Data.define(:local_interface, :remote_name, :remote_interface, :chassis_id, :attributes)
+      def initialize(local_interface:, remote_name:, remote_interface:, chassis_id: nil, attributes: {})
+        super(local_interface: Values.text(local_interface, name: "local interface"), remote_name: Values.text(remote_name, name: "remote name"),
+          remote_interface: Values.text(remote_interface, name: "remote interface"),
+          chassis_id: Values.text(chassis_id, name: "chassis id", optional: true), attributes: Values.copy(attributes))
+      end
+
+      def key = [local_interface.downcase, chassis_id || remote_name.downcase, remote_interface.downcase].freeze
+    end
+  end
+end

data/lib/netstack/inventory/reconciler.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Inventory
+    # 只计算变更，不写入宿主记录；仅完整维度可以提出删除，
+    # 并且删除必须限定在采集来源与明确的身份范围内。
+    class Reconciler
+      # current contains host records keyed by dimension. Fields owned by people stay with the host.
+      # A row has :key, :attributes, :managed_fields and :source; collection never guesses ownership.
+      def call(current:, snapshot:, target:)
+        unless snapshot.is_a?(Snapshot) && target.is_a?(Target) &&
+            target == snapshot.target
+          raise InputError, "snapshot target has changed"
+        end
+        raise InputError, "current inventory must be a Hash" unless current.is_a?(Hash)
+
+        changes = {}
+        skipped = {}
+        snapshot.dimensions.each do |name, dimension|
+          unless dimension.complete?
+            skipped[name] = dimension.status
+            next
+          end
+          rows = current.fetch(name, [])
+          validate_rows!(rows)
+          indexed = rows.to_h { |row| [identity(name, row.fetch(:key)), row] }
+          raise InputError, "duplicate current inventory identity" unless indexed.size == rows.size
+
+          updates = []
+          creates = []
+          observed = {}
+          dimension.records.each do |record|
+            key = identity(name, record.key)
+            existing = indexed[key]
+            attributes = record.to_h.reject { |field, _| field == :key }
+            if existing && existing[:source] == snapshot.source
+              fields = existing.fetch(:managed_fields)
+              desired = existing.fetch(:attributes).merge(attributes.select { |field, _| fields.include?(field) })
+              # Host record identity and display spelling remain stable for interface references.
+              desired[:name] = existing[:attributes][:name] if name == :interfaces && existing[:attributes].key?(:name)
+              updates << { key: existing[:key], attributes: desired } if desired != existing[:attributes]
+            elsif !existing
+              creates << { key: record.key, attributes: attributes, source: snapshot.source }
+            end
+            observed[key] = true
+          end
+          scope = snapshot.scope[name]&.to_h { |key| [key, true] }
+          removals = rows.filter_map do |row|
+            key = identity(name, row[:key])
+            in_scope = scope.nil? || scope.key?(key)
+            row[:key] if in_scope && row[:source] == snapshot.source && !observed.key?(key)
+          end
+          changes[name] = { create: creates, update: updates, remove: removals }
+        end
+        Changes.new(target: target, source: snapshot.source, dimensions: changes, skipped: skipped)
+      end
+
+      private
+
+      def identity(name, key)
+        Snapshot.identity(name, key)
+      end
+
+      def validate_rows!(rows)
+        unless rows.is_a?(Array) && rows.all? do |row|
+          row.is_a?(Hash) && row.key?(:key) && row[:attributes].is_a?(Hash) &&
+            row[:managed_fields].is_a?(Array) && row[:managed_fields].all? { |field| field.is_a?(Symbol) } && row[:source].is_a?(String)
+        end
+          raise InputError, "invalid current inventory records"
+        end
+      end
+    end
+  end
+end

data/lib/netstack/inventory/snapshot.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Inventory
+    # 同时校验记录身份、目标归属和采集范围。
+    # 未提供范围表示整个维度；空范围表示不包含任何身份。
+    class Snapshot < Data.define(:target, :source, :dimensions, :scope)
+      RECORD_TYPES = { device: Device, interfaces: Interface, transceivers: Transceiver, neighbors: Neighbor }.freeze
+
+      def initialize(target:, source:, dimensions:, scope: {})
+        raise InputError, "snapshot target must be a Target" unless target.is_a?(Target)
+        raise InputError, "snapshot dimensions must be a Hash" unless dimensions.is_a?(Hash)
+        raise InputError, "snapshot scope must be a Hash" unless scope.is_a?(Hash)
+
+        normalized_scope = scope.each_with_object({}) do |(name, keys), result|
+          name = name.to_sym if name.is_a?(String)
+          unless RECORD_TYPES.key?(name) && keys.is_a?(Array) && !result.key?(name)
+            raise InputError, "scope must contain dimension identity arrays"
+          end
+          result[name] = keys.map { |key| self.class.identity(name, key) }
+          raise InputError, "duplicate inventory scope identity" unless result[name].uniq.size == result[name].size
+        end
+
+        normalized = {}
+        dimensions.each do |name, dimension|
+          name = name.to_sym if name.is_a?(String)
+          unless RECORD_TYPES.key?(name) && dimension.is_a?(Dimension) && dimension.name == name && !normalized.key?(name)
+            raise InputError, "invalid snapshot dimension"
+          end
+          unless dimension.records.all? { |record| record.is_a?(RECORD_TYPES.fetch(name)) }
+            raise InputError, "invalid inventory record type"
+          end
+          identities = dimension.records.map(&:key)
+          raise InputError, "duplicate inventory identity" unless identities.uniq.size == identities.size
+          if name == :device && dimension.records.any? { |record| record.key != target.key }
+            raise InputError, "device record does not belong to target"
+          end
+          if name == :device && dimension.complete? && dimension.records.size != 1
+            raise InputError, "a complete device dimension must identify the target"
+          end
+          if normalized_scope.key?(name) && (identities - normalized_scope[name]).any?
+            raise InputError, "inventory contains records outside the collected scope"
+          end
+
+          normalized[name] = dimension
+        end
+        super(target: target, source: Values.text(source, name: "snapshot source"), dimensions: normalized.freeze, scope: Values.copy(normalized_scope))
+      end
+
+      def self.identity(name, key)
+        case name
+        when :device then Values.text(key, name: "device identity")
+        when :interfaces then Values.text(key, name: "interface identity").downcase.freeze
+        when :transceivers then Values.integer(key, name: "transceiver identity", min: 1)
+        when :neighbors
+          raise InputError, "neighbor identity must contain three text components" unless key.is_a?(Array) && key.size == 3
+          key.each { |part| Values.text(part, name: "neighbor identity") }
+          [key[0].strip.downcase, key[1].strip, key[2].strip.downcase].map(&:freeze).freeze
+        else raise InputError, "unknown inventory identity dimension"
+        end
+      end
+
+      def complete?
+        requested = dimensions.values.reject { |dimension| dimension.status == :not_requested }
+        !requested.empty? && requested.all?(&:complete?)
+      end
+    end
+  end
+end

data/lib/netstack/inventory/transceiver.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Inventory
+    class Transceiver < Data.define(:interface_index, :interface_name, :vendor, :model, :serial, :measurements)
+      def initialize(interface_index:, interface_name:, vendor: nil, model: nil, serial: nil, measurements: {})
+        raise InputError, "transceiver measurements must be a Hash" unless measurements.is_a?(Hash)
+
+        measurements.each_value do |value|
+          unless value.nil? || (value.is_a?(Numeric) && value.real? && value.finite?)
+            raise InputError, "measurements must be finite numbers or nil"
+          end
+        end
+        super(interface_index: Values.integer(interface_index, name: "interface index", min: 1),
+          interface_name: Values.text(interface_name, name: "interface name"), vendor: Values.text(vendor, name: "vendor", optional: true),
+          model: Values.text(model, name: "model", optional: true), serial: Values.text(serial, name: "serial", optional: true),
+          measurements: Values.copy(measurements))
+      end
+
+      def key = interface_index
+    end
+  end
+end

data/lib/netstack/ipv4.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require_relative "range_set"
+
+module Netstack
+  # 在标准 IPAddr 能力上补充防火墙所需的 IPv4 和服务范围运算。
+  class IPv4 < ::IPAddr
+    IPV4_MAX = ::IPAddr::IN4MASK
+    PORT_MAX = (1 << 16) - 1
+    SERVICE_MAX = (1 << 24) - 1
+    # 服务编码中反复使用的协议号集中命名，避免上层散落裸数字。
+    ANY_PROTOCOL = 0
+    ICMP = 1
+    TCP = 6
+    UDP = 17
+    PROTOCOL_NUMBERS = { "tcp" => TCP, "udp" => UDP, "icmp" => ICMP,
+                         "ms-rpc-tcp" => TCP, "ms-rpc-udp" => UDP }.freeze
+
+    # 规范化 IPv4 输入，并拒绝 IPv6、非法前缀及非十进制设备写法。
+    def initialize(address = "0.0.0.0", family = Socket::AF_INET)
+      unless [ Socket::AF_INET, Socket::AF_UNSPEC ].include?(family)
+        raise ArgumentError, "IPv4 helpers require IPv4"
+      end
+      if address.is_a?(String)
+        address = address.sub(/\Aany\z/i, "0.0.0.0/0").sub(/\Aany(?=\/)/i, "0.0.0.0")
+        unless /\A[0-9]+(?:\.[0-9]+){3}(?:\/(?:[0-9]+|[0-9]+(?:\.[0-9]+){3}))?\z/.match?(address)
+          raise ArgumentError, "Invalid IPv4 expression: #{address.inspect}"
+        end
+        # 设备格式把带前导零的八位组和前缀都按十进制解释。
+        address = address.gsub(/\b0+(?=[0-9])/, "")
+      elsif !address.is_a?(Integer)
+        raise ArgumentError, "IPv4 input must be a string or integer"
+      end
+      super(address, Socket::AF_INET)
+    end
+
+    # 把地址转换成包含首尾整数的标准集合，供范围运算复用。
+    def to_set
+      raise ArgumentError, "IPv4 helpers require IPv4" unless ipv4?
+      range = to_range
+      RangeSet.new(range.begin.to_i..range.end.to_i)
+    end
+
+    class << self
+      # 接口地址保留主机位；不能直接用 IPAddr.new("host/prefix").to_s。
+      def host_cidr(expression, mask = nil)
+        host, prefix = string(expression, label: "Interface address").split("/", 2)
+        "#{from_i(to_i(host))}/#{prefix_length(mask || prefix || 32)}"
+      end
+
+      # 路由目的统一归一化为网络地址和前缀。
+      def network_cidr(expression, mask = nil)
+        address = new(host_cidr(expression, mask))
+        "#{address}/#{address.prefix}"
+      end
+
+      # 取接口 CIDR 中的主机地址，供 NAT 出口使用。
+      def host(expression) = host_cidr(expression).split("/", 2).first
+
+      # 把不带前缀的 IPv4 文本转换为整数。
+      def to_i(address)
+        unless address.is_a?(String) && !address.include?("/")
+          raise ArgumentError, "Invalid IPv4 address: #{address.inspect}"
+        end
+        new(address).to_i
+      end
+
+      # 把 IPv4 整数转换为点分十进制文本。
+      def from_i(number)
+        value = integer(number, max: IPV4_MAX, label: "IPv4 integer")
+        new(value).to_s
+      end
+
+      # 把前缀长度或掩码转换为规范前缀长度。
+      def prefix_length(mask)
+        mask = integer(mask, max: 32, label: "Prefix length") unless mask.is_a?(String)
+        new("0.0.0.0/#{mask}").prefix
+      end
+
+      # 根据前缀长度生成点分十进制网络掩码。
+      def netmask(mask) = new(IPV4_MAX).mask(prefix_length(mask)).to_s
+
+      # 把通配符掩码转换为网络掩码。
+      def wildcard_mask(wildcard)
+        unless wildcard.is_a?(String) && /\A[0-9]+(?:\.[0-9]+){3}\z/.match?(wildcard)
+          raise ArgumentError, "Invalid IPv4 wildcard"
+        end
+        (~new(wildcard)).to_s
+      end
+
+      # 根据地址和掩码计算覆盖的整数地址集合。
+      def subnet(address, mask = 32)
+        new(to_i(address)).mask(prefix_length(mask.nil? ? 32 : mask)).to_set
+      end
+
+      # 返回子网的网络地址文本。
+      def network(address, mask = 32) = from_i(subnet(address, mask).min)
+
+      # 解析主机、CIDR 或网络掩码表达式，也支持两个 IPv4 端点。
+      def parse(expression)
+        text = string(expression, label: "IPv4 expression")
+        parts = text.split("-", -1)
+        return between(*parts) if parts.size == 2
+        raise ArgumentError, "Invalid IPv4 expression: #{text}" unless parts.size == 1
+        new(text).to_set
+      end
+
+      # 用两个端点创建有序的闭区间。
+      def between(first, last)
+        low, high = [ to_i(first), to_i(last) ].minmax
+        RangeSet.new(low..high)
+      end
+
+      # 将地址范围精确拆成 CIDR，供持久化与命令生成共用。
+      def cidrs(set)
+        unless set.is_a?(RangeSet) && (set.empty? || set.max <= IPV4_MAX)
+          raise ArgumentError, "Expected IPv4 integer ranges"
+        end
+        set.flat_map do |range|
+          cursor, last = range.begin, range.end
+          blocks = []
+          while cursor <= last
+            size = 1
+            size *= 2 while (cursor % (size * 2)).zero? && (cursor + (size * 2) - 1) <= last
+            blocks << [ IPv4.from_i(cursor), 32 - (size.bit_length - 1) ]
+            cursor += size
+          end
+          blocks
+        end
+      end
+
+      # 把整数区间压缩成最短的单个网段或端点表达式。
+      def format_range(range)
+        unless range.is_a?(Range) && !range.exclude_end? && range.begin.is_a?(Integer) && range.end.is_a?(Integer)
+          raise ArgumentError, "IPv4 notation requires a closed integer range"
+        end
+        integer(range.begin, max: IPV4_MAX, label: "IPv4 lower bound")
+        integer(range.end, max: IPV4_MAX, label: "IPv4 upper bound")
+        raise ArgumentError, "IPv4 range is reversed" if range.begin > range.end
+        size = range.end - range.begin + 1
+        first = from_i(range.begin)
+        if (size & (size - 1)).zero? && (range.begin % size).zero?
+          "#{first}/#{32 - (size.bit_length - 1)}"
+        else
+          "#{first}-#{from_i(range.end)}"
+        end
+      end
+
+      # 解析单个端口或端口范围，并限制在 16 位端口空间内。
+      def ports(expression)
+        if expression.is_a?(Range)
+          result = RangeSet.new(expression)
+          raise ArgumentError, "Port must be in 0..#{PORT_MAX}" if result.max > PORT_MAX
+          return result
+        end
+        text = expression.is_a?(Integer) ? expression.to_s : string(expression, label: "Port")
+        match = /\A\s*([0-9]+)(?:(?:\s*-\s*|\s+)([0-9]+))?\s*\z/.match(text)
+        raise ArgumentError, "Invalid port expression: #{text}" unless match
+        first, last = [ match[1], match[2] || match[1] ].map do |endpoint|
+          integer(endpoint, max: PORT_MAX, label: "Port")
+        end.minmax
+        RangeSet.new(first..last)
+      end
+
+      # 把协议名称或编号转换成服务编码使用的协议编号。
+      def protocol_number(protocol)
+        protocol = protocol.to_s if protocol.is_a?(Integer) || protocol.is_a?(Symbol)
+        name = string(protocol, label: "Protocol").downcase
+        return ANY_PROTOCOL if name == "any"
+        PROTOCOL_NUMBERS.fetch(name) { integer(name, max: 255, label: "Protocol number") }
+      end
+
+      # 服务编码的高八位保存协议，低十六位保存目标端口；省略端口时使用零。
+      def service(expression)
+        text = string(expression, label: "Service expression")
+        protocol, port, *unexpected_parts = text.split("/", -1)
+        raise ArgumentError, "Invalid service expression: #{text}" unless protocol && unexpected_parts.empty?
+        ranges = ports(port || 0)
+        return RangeSet.new(0..SERVICE_MAX) if protocol.casecmp?(ANY_PROTOCOL.to_s) || protocol.casecmp?("any")
+        base = protocol_number(protocol) << 16
+        RangeSet.new(*ranges.map { |range| (base + range.begin)..(base + range.end) })
+      end
+
+      private
+
+      # 校验并转换整数输入，同时限制其数值范围。
+      def integer(value, max:, label:)
+        unless value.is_a?(Integer) || (value.is_a?(String) && /\A[0-9]+\z/.match?(value))
+          raise ArgumentError, "#{label} must be an integer in 0..#{max}"
+        end
+        number = value.is_a?(Integer) ? value : Integer(value, 10)
+        raise ArgumentError, "#{label} must be in 0..#{max}" unless number.between?(0, max)
+        number
+      end
+
+      # 校验文本输入并保留原字符串，便于上层继续解析原始表达式。
+      def string(value, label:)
+        raise ArgumentError, "#{label} must be a string" unless value.is_a?(String)
+        value
+      end
+    end
+  end
+end

data/lib/netstack/ipv6.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Netstack
+  # IPv6 ranges remain separate from IPv4. Serialize endpoints as address text.
+  module IPv6
+    MAX = (1 << 128) - 1
+    module_function
+
+    def address(value)
+      unless value.is_a?(String) && value == value.strip && !value.include?("%")
+        raise ArgumentError, "Invalid IPv6 address"
+      end
+
+      result = ::IPAddr.new(value)
+      raise ArgumentError, "Expected IPv6" unless result.ipv6?
+
+      result
+    end
+
+    def canonical(value, host: false)
+      ip = address(value)
+      return "#{address(value.split("/").first)}/#{ip.prefix}" if host
+
+      value.include?("/") ? "#{ip}/#{ip.prefix}" : ip.to_s
+    end
+
+    def parse(value)
+      raise ArgumentError, "IPv6 expression must be text" unless value.is_a?(String)
+
+      if value.include?("-")
+        parts = value.split("-", -1)
+        unless parts.size == 2 && parts.none? { |part| part.include?("/") }
+          raise ArgumentError, "IPv6 range needs two hosts"
+        end
+
+        first, last = parts.map { |part| address(part).to_i }
+        RangeSet.new(first..last)
+      else
+        ip = address(value)
+        RangeSet.new(ip.to_range.begin.to_i..ip.to_range.end.to_i)
+      end
+    end
+
+    def normalize(value)
+      raise ArgumentError, "IPv6 expression must be text" unless value.is_a?(String)
+      return canonical(value) unless value.include?("-")
+
+      range = parse(value).ranges.fetch(0)
+      "#{from_i(range.begin)}-#{from_i(range.end)}"
+    end
+
+    def from_i(value)
+      raise ArgumentError, "IPv6 integer is out of range" unless value.is_a?(Integer) && value.between?(0, MAX)
+
+      ::IPAddr.new(value, Socket::AF_INET6).to_s
+    end
+
+    def ranges(set)
+      validate_set!(set)
+      set.map { |range| [from_i(range.begin), from_i(range.end)] }
+    end
+
+    def cidrs(set)
+      validate_set!(set)
+      set.flat_map do |range|
+        cursor = range.begin
+        blocks = []
+        while cursor <= range.end
+          remaining_bits = (range.end - cursor + 1).bit_length - 1
+          aligned_bits = cursor.zero? ? 128 : (cursor & -cursor).bit_length - 1
+          bits = [remaining_bits, aligned_bits].min
+          blocks << [from_i(cursor), 128 - bits]
+          cursor += 1 << bits
+        end
+        blocks
+      end
+    end
+
+    def validate_set!(set)
+      return if set.is_a?(RangeSet) && (set.empty? || set.max <= MAX)
+
+      raise ArgumentError, "Expected IPv6 integer ranges"
+    end
+    private_class_method :validate_set!
+  end
+end