inet 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5372b62775ce7f9a484b88d77115a10e6ffe8ede9f311c683bbb160d6b13b119
-  data.tar.gz: e70a880902a29c15d316e51796818a4f8bd223cc4ca9af5a43aec9e393b69c27
+  metadata.gz: d1b022216eda75fb5d2cf23f4b69b0e225069b7ec53b16400709fd91b7a804b2
+  data.tar.gz: c3d2eb967e3cb4a3abef18ba46e99c3fdbb69d1cf8c8f4dab534f3a3e4b5d25a
 SHA512:
-  metadata.gz: 452788add21b2bcc8993f97e3c5abed49e0f7d82aed975552b268f1bd82bd704768df2efa621d359edb4a619964db0ab5bb292e29037535359f62862b97903ac
-  data.tar.gz: b37bc47a8ad6e9deb3ce78205e7f8a7f426694c697078da9c2cff27d05b8bfd7faa130866f66cb1d05744917302c5e60442367e501fa3c81c1252d4d522449dc
+  metadata.gz: 54fb104ff7fb73fe2291fe583fa1ad11b14bcff967e4d3b591e3993aed508685958bd6b69932065b0e9ec7607650f7f7f3b76b4e831cfc29473afa781f01af7c
+  data.tar.gz: 401fa85bb5d0461dd6646facd4313e539b3a722e7a95aef16054e6e29d05f7306d8e8b13cbbe8a9fce3cbddccb324f70e6643f93e78cdcdf2a73825273bf7f08

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 更新记录
 
+## 0.3.0
+
+1. **域名与 DNS**：从 algosec-rb 迁入 `Inet::DomainName` 和 `Inet::DnsResolver`，提供完整域名校验、左侧通配匹配、A/CNAME 解析与 TTL 缓存。
+2. **通用上下文**：解析器以 `context:` 隔离调用方缓存，默认使用 `Time.now`，不依赖 ActiveSupport；声明所需标准库 gem 依赖。
+
+## 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 校验文件。

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,9 +3,9 @@
 [![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 地址与服务范围运算，域名匹配、带 TTL 缓存的 DNS 解析，以及不可变整数区间集合。加载时不发起网络请求或启动后台任务。
 
-要求 Ruby 3.4 或更高版本，无运行时依赖，采用 MIT 许可证。
+要求 Ruby 3.4 或更高版本，只依赖标准库 gem，采用 MIT 许可证。
 
 ## 安装与使用
 
@@ -16,15 +16,66 @@ gem install inet
 也可以在 Gemfile 中添加：
 
 ```ruby
-gem "inet", "~> 0.1"
+gem "inet", "~> 0.3"
 ```
 
 ```ruby
 require "inet"
 
-puts Inet::VERSION # => "0.1.1"
+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)。
+
+## 域名与 DNS
+
+```ruby
+Inet::DomainName.normalize("WWW.Example.test.") # => "www.example.test"
+Inet::DomainName.exact?("example.test")         # => true
+Inet::DomainName.matches?("*.example.test", "www.example.test") # => true
+
+resolver = Inet::DnsResolver.new(context: { "device_id" => 42 }, servers: ["192.0.2.53"])
+answer = resolver.resolve("www.example.test") # 此时才查询 DNS
+answer.fetch("status")    # => "resolved"、"unresolved" 或 "unsupported"
+answer.fetch("addresses") # => IPv4 地址数组
 ```
 
+域名只接受至少两个 ASCII 标签的完整名称，单个尾点会被移除；不支持 IDNA 转码和搜索域。
+通配仅支持 `*.example.test`，匹配一层或多层子域，不匹配根名称 `example.test`。
+`require "inet/domain_name"` 和 `require "inet/dns_resolver"` 也可独立加载。
+
+解析器只查询 A 记录，跟随最多 8 个 CNAME，使用整条链中最短的 TTL；每次等待为 1 秒。
+`servers:` 最多指定三个 DNS 服务器，省略时使用系统 DNS。`context:` 为字符串键的 JSON 对象，
+由解析器复制并冻结，供调用方隔离租户或设备缓存。返回的 `source` 保留上下文，追加
+`source`（系统 DNS 为 `system`，显式 DNS 为 `device`）和 `servers`，这两个键由解析器管理。
+
+返回值及嵌套内容不可变，包含 `status`、`addresses`、`resolved_at`、`expires_at`、`source`、`error`。
+失败或没有 A 记录返回 `unresolved`，不支持的域名返回 `unsupported`，都缓存 15 秒；不会把失败当成成功的空集合。
+可选 `store:` 接收实现 `read(key)` 与 `write(key, value, expires_in:)` 的缓存，实例内也按 TTL 复用结果。
+`clock:` 默认 `Time.now`；测试可注入 `transport:`（接收域名及显式服务器数组，返回 `[地址数组, TTL秒数]`）
+或 `dns_class:`。加载 gem 不发起 DNS 查询。
+
 ## 开发
 
 ```sh

data/lib/inet/dns_resolver.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "resolv"
+require "digest"
+require "json"
+require "time"
+require_relative "ipaddr"
+require_relative "domain_name"
+
+module Inet
+  # 按调用方上下文和 DNS 视角缓存有期限的证据；不把 DNS 失败解释为空地址。
+  class DnsResolver
+    FAILURE_TTL = 15
+    MAX_CNAME_DEPTH = 8
+    attr_reader :context
+
+    def initialize(context: {}, servers: nil, store: nil, clock: -> { Time.now }, transport: nil, dns_class: Resolv::DNS)
+      servers = Array(servers)
+      raise ArgumentError, "DNS servers must contain at most three IP addresses" if servers.size > 3
+
+      servers.each { |server| ::IPAddr.new(server) }
+      @servers = servers.map { |server| server.to_s.dup.freeze }.freeze
+      @store = store
+      @clock = clock
+      @transport = transport
+      @dns_class = dns_class
+      effective = if @servers.empty?
+                    Resolv::DNS::Config.default_config_hash.fetch(:nameserver).map do |server|
+                      server.dup.freeze
+                    end.freeze
+                  else
+                    @servers
+                  end
+      @context = immutable_answer(context.merge("source" => @servers.empty? ? "system" : "device",
+                                                "servers" => effective))
+      @scope = Digest::SHA256.hexdigest(JSON.generate(@context))
+      @answers = {}
+    end
+
+    # 同次解析只查一次；跨次操作复用 TTL 内缓存，失败缓存不被视作成功。
+    def resolve(domain)
+      name = DomainName.normalize(domain)
+      key = ["inet", "dns-v1", @scope, name]
+      now = @clock.call
+      cached = @answers[name] || @store&.read(key)
+      return @answers[name] ||= immutable_answer(cached) if cached && Time.iso8601(cached.fetch("expires_at")) > now
+
+      answer = lookup(name, now)
+      @store&.write(key, answer, expires_in: [Time.iso8601(answer.fetch("expires_at")) - now, 0].max)
+      @answers[name] = answer
+    end
+
+    private
+
+    # 缓存编码器不保留冻结状态；复制恢复每层 JSON 值，避免调用方改写 DNS 证据。
+    def immutable_answer(value)
+      case value
+      when Hash then value.to_h { |key, item| [key, immutable_answer(item)] }.freeze
+      when Array then value.map { |item| immutable_answer(item) }.freeze
+      else value.dup.freeze
+      end
+    end
+
+    # 仅接受完整域名；通配和单标签主机名不借助本机搜索域猜测。
+    def lookup(name, now)
+      return record("unsupported", [], FAILURE_TTL, now, "Unsupported domain expression") unless DomainName.exact?(name)
+
+      addresses, ttl = @transport ? @transport.call(name, @servers) : query(name)
+      addresses = addresses.map { |ip| Inet::IPAddr.from_i(Inet::IPAddr.to_i(ip)) }.uniq.sort
+      return record("unresolved", [], FAILURE_TTL, now, "No A records") if addresses.empty?
+
+      record("resolved", addresses, Integer(ttl), now)
+    rescue Resolv::ResolvError, Resolv::ResolvTimeout, IOError, SystemCallError, ArgumentError => error
+      record("unresolved", [], FAILURE_TTL, now, error.message)
+    end
+
+    # CNAME 与 A 的 TTL 共同决定有效期，限制跳数和每次等待，防止循环和长时间阻塞。
+    def query(name)
+      servers = context.fetch("servers")
+      @dns_class.open(nameserver: servers, search: [], ndots: 1, raise_timeout_errors: true) do |dns|
+        dns.timeouts = 1
+        visited = []
+        ttls = []
+        MAX_CNAME_DEPTH.times do
+          raise Resolv::ResolvError, "CNAME cycle" if visited.include?(name)
+
+          visited << name
+          aliases = dns.getresources("#{name}.", Resolv::DNS::Resource::IN::CNAME)
+          if aliases.empty?
+            records = dns.getresources("#{name}.", Resolv::DNS::Resource::IN::A)
+            ttls.concat(records.map(&:ttl))
+            return [records.map { |rr| rr.address.to_s }, ttls.min || 0]
+          end
+          ttls.concat(aliases.map(&:ttl))
+          name = aliases.first.name.to_s.downcase.delete_suffix(".")
+        end
+        raise Resolv::ResolvError, "CNAME chain exceeds #{MAX_CNAME_DEPTH}"
+      end
+    end
+
+    # 使用普通 JSON 值保存证据，配置缓存不持有网络连接或解析器对象。
+    def record(status, addresses, ttl, now, error = nil)
+      { "status" => status, "addresses" => addresses.map(&:freeze).freeze, "resolved_at" => now.iso8601(6).freeze,
+        "expires_at" => (now + [ttl, 0].max).iso8601(6).freeze, "source" => context,
+        "error" => error&.dup&.freeze }.freeze
+    end
+  end
+end

data/lib/inet/domain_name.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Inet
+  # 域名表达式只支持完整名称或最左侧标签通配，不使用子串匹配。
+  module DomainName
+    module_function
+
+    def normalize(value)
+      name = value.to_s.downcase
+      # 一个尾点表示根域；多个尾点是空标签，跨层重复归一化也不能把它变成合法名称。
+      name.end_with?("..") ? name : name.delete_suffix(".")
+    end
+
+    def exact?(value)
+      name = normalize(value)
+      name.bytesize <= 253 && name.include?(".") &&
+        name.split(".", -1).all? { |label| /\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\z/.match?(label) }
+    end
+
+    def wildcard?(value)
+      name = normalize(value)
+      name.start_with?("*.") && exact?(name.delete_prefix("*."))
+    end
+
+    def matches?(expression, domain)
+      pattern, name = [expression, domain].map { |value| normalize(value) }
+      return false unless exact?(name)
+
+      wildcard?(pattern) ? name.end_with?(pattern.delete_prefix("*")) : exact?(pattern) && pattern == name
+    end
+  end
+end

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.1"
+  VERSION = "0.3.0"
 end

data/lib/inet.rb

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

metadata

@@ -1,15 +1,86 @@
 --- !ruby/object:Gem::Specification
 name: inet
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - inet contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-07 00:00:00.000000000 Z
-dependencies: []
-description: The initial inet package provides a loadable namespace and version information.
+date: 2026-10-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: digest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ipaddr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: resolv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: time
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Domain matching, cached DNS, IP address ranges, service encoding and
+  immutable interval sets.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -19,6 +90,11 @@ files:
 - README.md
 - docs/releasing.md
 - lib/inet.rb
+- lib/inet/dns_resolver.rb
+- lib/inet/domain_name.rb
+- lib/inet/ipaddr.rb
+- lib/inet/ipv6.rb
+- lib/inet/set.rb
 - lib/inet/version.rb
 homepage: https://github.com/gatework/inet
 licenses:
@@ -45,5 +121,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: Foundation for the inet Ruby library
+summary: IP addresses, domain names, DNS and immutable interval sets
 test_files: []