inet 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd1407cb6b63aedfbf3e934ab952f7a89e74b19660aabb97d13eaa2ca63365d9
-  data.tar.gz: 8a47da2e0262b952cc8b085b1551c057585a1ff8f2e48039dd16e71fccc038b4
+  metadata.gz: 441ae2bd4745812fbc1181d5a430b3eb065225670418c41f252e25907efe4117
+  data.tar.gz: 1831047c063ad8e090b1a184b4bd8dd0e530e1302f711b0ba5abf26627bdf6ee
 SHA512:
-  metadata.gz: 22881dab447cf39c8468b8ef3053fb5276b373f35034c0a95dcb115c72f47d777448793e55007f9bc572979196e1a7aa1531e784c969aa8fb401a87dd766df79
-  data.tar.gz: 1de282eccadcf51c4ebd15929f3eee88e90f0aec16617df644e900894461eb0157ce4de807b4de0a87251cbb6720c8699d36de91bab9f4a8bf7fee21650480de
+  metadata.gz: 2e2f7f9e1f5904cfa0db29842c513e3b7b01a1a987b672b19cea5e91bb6d47e3e15a344c93cde983bc8da2bd447938e0cc674b1823dea27d2cb391ddd734d6e4
+  data.tar.gz: c0d4867be92ee239c51666d27f442b56ca6071469cb36d1810f525acc28f317817ba29edb42dda798ad2881684c70eaaa22d0ce9a16a07f86473887412ee26a7

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 更新记录
 
+## 0.2.0
+
+1. **地址与服务运算**：从 algosec-rb 迁入 IPv4、IPv6 地址规范化、范围解析、CIDR 拆分、端口及协议服务编码，公共入口为 `Inet::IPAddr`、`Inet::IPv6`。
+2. **区间集合**：提供不可变 `Inet::Set`，支持合并、交集、差集、包含、重叠、关系判断和 Marshal 持久化；无需 ActiveSupport 或其他运行时依赖。
+3. **验证**：补充边界、非法输入、集合运算对照测试和真实 gem 隔离安装验证。
+
+## 0.1.1
+
+1. **自动发布**：接通 RubyGems Trusted Publishing，由 GitHub Actions 发布通过全部检查的同一份 gem，并提供对应的 GitHub Release 和 SHA256 校验文件。
+
 ## 0.1.0
 
 1. **基础骨架**：提供可安装的 `inet` gem、`Inet` 命名空间和版本信息，要求 Ruby 3.4 及以上版本。

data/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 inet contributors
+Copyright (c) 2026 Gatework contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -3,7 +3,7 @@
 [![Release](https://github.com/gatework/inet/actions/workflows/release.yml/badge.svg)](https://github.com/gatework/inet/actions/workflows/release.yml)
 [![Gem Version](https://badge.fury.io/rb/inet.svg)](https://rubygems.org/gems/inet)
 
-`inet` 的 Ruby gem 基础骨架。当前仅提供 `Inet` 命名空间和版本信息，尚未实现网络功能。
+`inet` 提供 IPv4、IPv6 地址与服务范围运算，以及不可变整数区间集合。加载时不发起网络请求或启动后台任务。
 
 要求 Ruby 3.4 或更高版本，无运行时依赖，采用 MIT 许可证。
 
@@ -16,15 +16,38 @@ gem install inet
 也可以在 Gemfile 中添加：
 
 ```ruby
-gem "inet", "~> 0.1"
+gem "inet", "~> 0.2"
 ```
 
 ```ruby
 require "inet"
 
-puts Inet::VERSION # => "0.1.0"
+Inet::IPAddr.host_cidr("192.0.2.9/24")    # => "192.0.2.9/24"
+Inet::IPAddr.network_cidr("192.0.2.9/24") # => "192.0.2.0/24"
+Inet::IPAddr.cidrs(Inet::IPAddr.parse("192.0.2.0/24")) # => [["192.0.2.0", 24]]
+Inet::IPv6.canonical("2001:0db8::9/64")   # => "2001:db8::/64"
+Inet::IPv6.canonical("2001:db8::9/64", host: true) # => "2001:db8::9/64"
+
+allowed = Inet::Set.new(1..10) - Inet::Set.new(3..7)
+allowed.ranges      # => [1..2, 8..10]
+allowed.cardinality # => 5
 ```
 
+## 接口约定
+
+- `Inet::IPAddr` 继承标准库 `IPAddr`，只接受 IPv4 字符串或整数；设备格式中的前导零按十进制处理，`any` 表示 `0.0.0.0`，全部 IPv4 地址使用 `any/0`。
+- `host_cidr` 保留主机位，`network_cidr` 归一化网络地址；可传第二个参数指定前缀长度或连续网络掩码。`host` 返回主机文本，`to_i` / `from_i` 转换整数，`prefix_length` / `netmask` / `wildcard_mask` 转换掩码。
+- `parse` 接受主机、CIDR、点分掩码或 `起点-终点`，返回 `Inet::Set`。IPv4 的范围端点自动排序；`between` 接受两个端点，`subnet` / `network` 接受地址及掩码。`cidrs` 接受合法 IPv4 整数集合并返回 `[地址, 前缀]` 数组；`format_range` 接受合法闭区间并返回单个 CIDR 或端点表达式。
+- `ports` 接受端口整数、区间、单个端口文本或以连字符/空格分隔的范围，限制为 `0..65535`。`protocol_number` 接受名称、符号或 `0..255` 的编号；`icmp?` 判断 ICMP/ICMPv6。`service("tcp/80-90")` 返回服务整数集合，高八位为协议号，低十六位为端口；省略端口使用零，`any` 或协议 `0` 表示整个 24 位服务空间。
+- `Inet::IPv6.address` 返回标准库 `IPAddr`；`canonical` 规范化主机或 CIDR，`parse` 返回整数集合，`normalize` 输出规范文本。范围必须按从小到大排列且不带前缀；拒绝带区域标识 `%` 的地址。`from_i` 转换 128 位非负整数，`ranges` 把合法 IPv6 整数集合转换为地址文本端点对。
+- `Inet::Set.new(*ranges)` 接受非负整数区间，自动合并重叠及相邻区间；半开区间转换为闭区间，拒绝空或逆序区间。`each` 遍历区间，`size` 是区间段数，`cardinality` 是整数元素总数。空集合的 `min` / `max` 返回 `nil`。
+- 集合支持 `|`、`&`、`-`、`include?(整数)`、`cover?(整数或集合)`、`subset?`、`overlap?`、`relation`。关系返回 `:equal`、`:contains`、`:within` 或 `:other`。集合和值数组冻结，`to_a` 返回数组副本；相等性、哈希和 Marshal 恢复保持值语义。
+
+非法地址、超范围值和不支持的类型抛出 `ArgumentError`（包括标准库 `IPAddr` 的对应子类）。集合自身不区分 IPv4、IPv6、端口或服务，调用方须保持同一数值空间，避免跨类型混算。
+可分别 `require "inet/ipaddr"`、`require "inet/ipv6"` 或 `require "inet/set"`。
+
+这三个模块迁自 Gatework 的 algosec-rb，保留其公共方法与运算行为；最低 Ruby 版本自带的 `Range#overlap?` 替代原 ActiveSupport 加载。源代码采用 MIT 许可证，版权声明见 [LICENSE](LICENSE)。
+
 ## 开发
 
 ```sh

data/docs/releasing.md

@@ -36,7 +36,8 @@
 4. 上传该 gem，回读 RubyGems 版本信息和下载内容，确认 SHA256 一致。
 5. 创建对应标签和 GitHub Release，上传同一份 gem 与 `SHA256SUMS`，下载比对后公开发布。
 
-首次推送 `main` 会发布 `0.1.0`。同版本的后续提交会跳过发布；后续更改需要提升版本号。
+`0.1.0` 的首次上传使用了本地构建包；从 `0.1.1` 开始使用上述自动发布流程。
+同版本的后续提交会跳过发布；后续更改需要提升版本号。
 发布只在 `main` 上运行，标签由工作流自动创建。
 
 ## 失败恢复
@@ -49,4 +50,4 @@ RubyGems 上传结果不明时，先查看版本页面和 SHA256，等待索引
 同版本存在不同 SHA256 时停止发布，需要检查冲突并使用新版本。
 
 `script/release.rb` 是 Actions 内部入口，要求 `gatework/inet` 的 `main`、干净工作区和对应的触发提交。
-本地可以运行 `bundle exec ruby script/verify_package.rb pkg/inet-0.1.0.gem` 验证已有构件。
+本地可以运行 `bundle exec ruby script/verify_package.rb pkg/inet-0.1.1.gem` 验证已有构件。

data/lib/inet/ipaddr.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require_relative "set"
+
+module Inet
+  # 在标准 IPAddr 能力上补充防火墙所需的 IPv4 和服务范围运算。
+  class IPAddr < ::IPAddr
+    IPV4_MAX = ::IPAddr::IN4MASK
+    PORT_MAX = (1 << 16) - 1
+    SERVICE_MAX = (1 << 24) - 1
+    # 服务编码中反复使用的协议号集中命名，避免上层散落裸数字。
+    ANY_PROTOCOL = 0
+    ICMP = 1
+    ICMPV6 = 58
+    TCP = 6
+    UDP = 17
+    PROTOCOL_NUMBERS = { "tcp" => TCP, "udp" => UDP, "icmp" => ICMP, "icmpv6" => ICMPV6,
+                         "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, "Firewall IP helpers require IPv4"
+      end
+
+      if address.is_a?(String)
+        address = address.sub(%r{\Aany(?=/|\z)}i, "0.0.0.0")
+        unless %r{\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, "Firewall IP helpers require IPv4" unless ipv4?
+
+      range = to_range
+      Set.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
+        Set.new(low..high)
+      end
+
+      # 将地址范围精确拆成 CIDR，供持久化与命令生成共用。
+      def cidrs(set)
+        set.flat_map do |range|
+          cursor = range.begin
+          last = range.end
+          blocks = []
+          while cursor <= last
+            size = 1
+            size *= 2 while (cursor % (size * 2)).zero? && cursor + (size * 2) - 1 <= last
+            blocks << [IPAddr.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.nobits?(size - 1) && (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 = Set.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
+        Set.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
+
+      # 两种 ICMP 都以消息类型和代码匹配，不把类型限制当作普通目的端口。
+      def icmp?(protocol) = [ICMP, ICMPV6].include?(protocol_number(protocol))
+
+      # 服务编码的高八位保存协议，低十六位保存目标端口；省略端口时使用零。
+      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 Set.new(0..SERVICE_MAX) if protocol.casecmp?(ANY_PROTOCOL.to_s) || protocol.casecmp?("any")
+
+        base = protocol_number(protocol) << 16
+        Set.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/inet/ipv6.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require_relative "set"
+
+module Inet
+  # IPv6 范围独立于 IPv4；JSON 端点使用地址文本，避免客户端整数精度丢失。
+  module IPv6
+    module_function
+
+    def address(value)
+      validate_text!(value)
+      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)
+      validate_text!(value)
+      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 }
+        Set.new(first..last)
+      else
+        ip = address(value)
+        Set.new(ip.to_range.begin.to_i..ip.to_range.end.to_i)
+      end
+    end
+
+    def normalize(value)
+      validate_text!(value)
+      return canonical(value) unless value.include?("-")
+
+      range = parse(value).ranges.first
+      "#{from_i(range.begin)}-#{from_i(range.end)}"
+    end
+
+    def from_i(value)
+      unless value.is_a?(Integer) && value.between?(0, ::IPAddr::IN6MASK)
+        raise ArgumentError, "IPv6 integer must be in 0..#{::IPAddr::IN6MASK}"
+      end
+
+      ::IPAddr.new(value, Socket::AF_INET6).to_s
+    end
+
+    def ranges(set) = set.map { |range| [from_i(range.begin), from_i(range.end)] }
+
+    def validate_text!(value)
+      return if value.is_a?(String) && value == value.strip && !value.include?("%")
+
+      raise ArgumentError, "Invalid IPv6 address"
+    end
+    private_class_method :validate_text!
+  end
+end

data/lib/inet/set.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Inet
+  # 不变量是区间有序、互不相交且已合并；遍历区间而不是逐个枚举主机。
+  class Set
+    include Enumerable
+
+    attr_reader :ranges, :hash
+
+    # 校验、排序并合并区间，然后冻结集合以保证值语义。
+    def initialize(*ranges)
+      ordered = ranges.map { |range| interval_endpoints(range) }.sort_by(&:first)
+      merged = []
+      ordered.each do |first, last|
+        if !merged.empty? && first <= merged.last[1] + 1
+          merged.last[1] = [merged.last[1], last].max
+        else
+          merged << [first, last]
+        end
+      end
+      @ranges = merged.map { |first, last| first..last }.freeze
+      @hash = @ranges.hash
+      freeze
+    end
+
+    # 遍历规范化后的区间；没有代码块时返回枚举器。
+    def each(&block)
+      return enum_for(__method__) unless block
+
+      ranges.each(&block)
+      self
+    end
+
+    # 判断集合是否没有区间。
+    def empty? = ranges.empty?
+
+    # 返回区间段数量，而不是地址或端口总数。
+    def size = ranges.size
+
+    # 返回最小端点；空集合返回 nil。
+    def min = ranges.first&.begin
+
+    # 返回最大端点；空集合返回 nil。
+    def max = ranges.last&.end
+
+    # 计算所有闭区间包含的元素总数。
+    def cardinality = sum { |range| range.end - range.begin + 1 }
+
+    # 仅按规范化后的区间比较集合内容。
+    def ==(other) = other.is_a?(Set) && ranges == other.ranges
+
+    alias eql? ==
+
+    # 计算并集；两个集合为空或相同对象时直接复用已有值。
+    def |(other)
+      validate_operand!(other)
+      return self if other.empty? || equal?(other)
+      return other if empty?
+
+      self.class.new(*ranges, *other.ranges)
+    end
+
+    # 用双指针扫描两个有序集合，计算交集。
+    def &(other)
+      validate_operand!(other)
+      return self if equal?(other) || empty?
+      return other if other.empty?
+
+      result = []
+      left = right = 0
+      while left < size && right < other.size
+        a = ranges[left]
+        b = other.ranges[right]
+        first = [a.begin, b.begin].max
+        last = [a.end, b.end].min
+        result << (first..last) if first <= last
+        left += 1 if a.end <= b.end
+        right += 1 if b.end <= a.end
+      end
+      self.class.new(*result)
+    end
+
+    # 从当前集合中减去另一个集合，逐段截去重叠部分。
+    def -(other)
+      validate_operand!(other)
+      return self if empty? || other.empty?
+      return self.class.new if equal?(other)
+
+      result = []
+      right = 0
+      each do |range|
+        cursor = range.begin
+        right += 1 while right < other.size && other.ranges[right].end < cursor
+        result.concat(subtract_interval(range, other.ranges, right))
+      end
+      self.class.new(*result)
+    end
+
+    # 判断整数是否落在任一规范化区间内。
+    def include?(number)
+      raise ArgumentError, "Membership requires an integer" unless number.is_a?(Integer)
+
+      candidate = ranges.bsearch { |range| range.end >= number }
+      candidate ? candidate.begin <= number : false
+    end
+
+    # 判断集合是否被当前集合覆盖；空集合始终被覆盖。
+    def cover?(other)
+      return include?(other) if other.is_a?(Integer)
+
+      validate_operand!(other)
+      return covers_interval?(other.ranges.first) if other.size == 1
+
+      index = 0
+      other.each do |range|
+        index += 1 while index < size && ranges[index].end < range.begin
+        return false if index == size || ranges[index].begin > range.begin || ranges[index].end < range.end
+      end
+      true
+    end
+
+    # 判断当前集合是否是另一个集合的子集。
+    def subset?(other)
+      validate_operand!(other)
+      other.cover?(self)
+    end
+
+    # 判断两个有序集合是否存在重叠区间。
+    def overlap?(other)
+      validate_operand!(other)
+      left = right = 0
+      while left < size && right < other.size
+        a = ranges[left]
+        b = other.ranges[right]
+        return true if a.overlap?(b)
+
+        a.end < b.end ? left += 1 : right += 1
+      end
+      false
+    end
+
+    # 返回相等、包含、被包含或互不相同四种关系之一。
+    def relation(other)
+      validate_operand!(other)
+      return :equal if self == other
+      return :contains if cover?(other)
+      return :within if subset?(other)
+
+      :other
+    end
+
+    # 返回区间数组的浅副本，避免调用方修改内部数组。
+    def to_a = ranges.dup
+
+    # 哈希值只在当前进程有效；持久化区间，并在读取进程中重新建立冻结集合。
+    def marshal_dump = ranges
+
+    # 从持久化区间恢复集合的不变量和冻结状态。
+    def marshal_load(ranges)
+      initialize(*ranges)
+    end
+
+    private
+
+    # 把合法区间统一为闭区间端点。
+    def interval_endpoints(range)
+      unless range.is_a?(Range) && range.begin.is_a?(Integer) && range.end.is_a?(Integer)
+        raise ArgumentError, "Intervals must have integer endpoints"
+      end
+
+      first = range.begin
+      last = range.end - (range.exclude_end? ? 1 : 0)
+      raise ArgumentError, "Intervals must be nonnegative and ordered" if first.negative? || first > last
+
+      [first, last]
+    end
+
+    # 对单个区间做差，调用方复用已找到的右侧起点。
+    def subtract_interval(range, removed_ranges, scan)
+      result = []
+      cursor = range.begin
+      while scan < removed_ranges.size && removed_ranges[scan].begin <= range.end
+        removed = removed_ranges[scan]
+        result << (cursor..(removed.begin - 1)) if removed.begin > cursor
+        cursor = [cursor, removed.end + 1].max
+        break if cursor > range.end
+
+        scan += 1
+      end
+      result << (cursor..range.end) if cursor <= range.end
+      result
+    end
+
+    # 单区间包含检查使用二分查找。
+    def covers_interval?(target)
+      candidate = ranges.bsearch { |range| range.end >= target.end }
+      candidate ? candidate.begin <= target.begin : false
+    end
+
+    # 统一校验集合运算的右值类型。
+    def validate_operand!(other)
+      raise ArgumentError, "Expected a Set" unless other.is_a?(Set)
+    end
+  end
+end

data/lib/inet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Inet
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/inet.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "inet/version"
+require_relative "inet/set"
+require_relative "inet/ipaddr"
+require_relative "inet/ipv6"
 
-# inet 的公共命名空间；首版只提供加载入口与版本信息。
+# IP 地址、服务编码与不可变整数区间集合的公共命名空间。
 module Inet
 end

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: inet
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - inet contributors
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies: []
-description: The initial inet package provides a loadable namespace and version information.
+description: IP address normalization, address ranges, service encoding and immutable
+  integer interval sets.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -19,6 +20,9 @@ files:
 - README.md
 - docs/releasing.md
 - lib/inet.rb
+- lib/inet/ipaddr.rb
+- lib/inet/ipv6.rb
+- lib/inet/set.rb
 - lib/inet/version.rb
 homepage: https://github.com/gatework/inet
 licenses:
@@ -43,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Foundation for the inet Ruby library
+summary: IPv4, IPv6 and immutable interval sets
 test_files: []