inet 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 441ae2bd4745812fbc1181d5a430b3eb065225670418c41f252e25907efe4117
-  data.tar.gz: 1831047c063ad8e090b1a184b4bd8dd0e530e1302f711b0ba5abf26627bdf6ee
+  metadata.gz: d1b022216eda75fb5d2cf23f4b69b0e225069b7ec53b16400709fd91b7a804b2
+  data.tar.gz: c3d2eb967e3cb4a3abef18ba46e99c3fdbb69d1cf8c8f4dab534f3a3e4b5d25a
 SHA512:
-  metadata.gz: 2e2f7f9e1f5904cfa0db29842c513e3b7b01a1a987b672b19cea5e91bb6d47e3e15a344c93cde983bc8da2bd447938e0cc674b1823dea27d2cb391ddd734d6e4
-  data.tar.gz: c0d4867be92ee239c51666d27f442b56ca6071469cb36d1810f525acc28f317817ba29edb42dda798ad2881684c70eaaa22d0ce9a16a07f86473887412ee26a7
+  metadata.gz: 54fb104ff7fb73fe2291fe583fa1ad11b14bcff967e4d3b591e3993aed508685958bd6b69932065b0e9ec7607650f7f7f3b76b4e831cfc29473afa781f01af7c
+  data.tar.gz: 401fa85bb5d0461dd6646facd4313e539b3a722e7a95aef16054e6e29d05f7306d8e8b13cbbe8a9fce3cbddccb324f70e6643f93e78cdcdf2a73825273bf7f08

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 更新记录
 
+## 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`。

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` 提供 IPv4、IPv6 地址与服务范围运算，以及不可变整数区间集合。加载时不发起网络请求或启动后台任务。
+`inet` 提供 IPv4、IPv6 地址与服务范围运算，域名匹配、带 TTL 缓存的 DNS 解析，以及不可变整数区间集合。加载时不发起网络请求或启动后台任务。
 
-要求 Ruby 3.4 或更高版本，无运行时依赖，采用 MIT 许可证。
+要求 Ruby 3.4 或更高版本，只依赖标准库 gem，采用 MIT 许可证。
 
 ## 安装与使用
 
@@ -16,7 +16,7 @@ gem install inet
 也可以在 Gemfile 中添加：
 
 ```ruby
-gem "inet", "~> 0.2"
+gem "inet", "~> 0.3"
 ```
 
 ```ruby
@@ -48,6 +48,34 @@ allowed.cardinality # => 5
 
 这三个模块迁自 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/version.rb

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

data/lib/inet.rb

@@ -5,6 +5,9 @@ require_relative "inet/set"
 require_relative "inet/ipaddr"
 require_relative "inet/ipv6"
 
-# IP 地址、服务编码与不可变整数区间集合的公共命名空间。
+require_relative "inet/domain_name"
+require_relative "inet/dns_resolver"
+
+# IP 地址、域名、DNS 解析、服务编码与不可变整数区间集合的公共命名空间。
 module Inet
 end

metadata

@@ -1,16 +1,86 @@
 --- !ruby/object:Gem::Specification
 name: inet
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - inet contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
-dependencies: []
-description: IP address normalization, address ranges, service encoding and immutable
-  integer interval sets.
+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: []
@@ -20,6 +90,8 @@ 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
@@ -49,5 +121,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: IPv4, IPv6 and immutable interval sets
+summary: IP addresses, domain names, DNS and immutable interval sets
 test_files: []