monovm-whois-ruby 1.0.0

data/lib/monovm/whois/registry/resolution.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MonoVM
+  module Whois
+    module Registry
+      # A name split into its registrable parts, with the definition that serves it.
+      #
+      # Produced by {ServerRegistry#resolve}. Exists so the split and the definition
+      # travel together: knowing that +example.co.uk+ has SLD +example+ is only
+      # meaningful alongside the fact that +.co.uk+ is the suffix a registry
+      # actually serves.
+      class Resolution
+        attr_reader :domain, :sld, :tld, :definition
+
+        # @param domain [DomainName] the full name as queried
+        # @param sld [String] the label immediately left of the suffix, ASCII
+        # @param tld [String] the matched suffix, with a leading dot, ASCII — this is
+        #   the key the definitions and the per-TLD pattern tables are indexed by
+        # @param definition [Definition] how to look this suffix up
+        # @param registrable [DomainName, nil] the registrable name in its *Unicode*
+        #   form. Passed in because only the caller that did the splitting still knows
+        #   the Unicode labels; rebuilding it from the ASCII +sld+ and +tld+ would
+        #   lose them, and the registries that insist on Unicode over port 43 would
+        #   silently be sent Punycode.
+        def initialize(domain:, sld:, tld:, definition:, registrable: nil)
+          @domain = domain
+          @sld = sld
+          @tld = tld
+          @definition = definition
+          # Built here, not memoised: the instance is frozen, so a lazy ivar would
+          # raise FrozenError on first use.
+          @registrable = registrable || DomainName.parse("#{sld}#{tld}")
+          freeze
+        end
+
+        # The registrable name — the SLD plus its suffix, with any subdomain
+        # dropped. A lookup for +www.example.co.uk+ must query +example.co.uk+,
+        # because that is the object the registry holds. In Unicode form; call
+        # {#query} for the wire form.
+        attr_reader :registrable
+
+        # The ASCII form to put on the wire.
+        def query
+          registrable.ascii
+        end
+
+        def to_h
+          { domain: domain.to_s, sld: sld, tld: tld, registrable: registrable.to_s }
+        end
+
+        def inspect
+          "#<#{self.class.name} #{sld}|#{tld}>"
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/registry/server_registry.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "definition"
+require_relative "resolution"
+require_relative "sources/base"
+require_relative "sources/json_file"
+require_relative "sources/iana_bootstrap"
+require_relative "../domain_name"
+require_relative "../paths"
+
+module MonoVM
+  module Whois
+    module Registry
+      # Answers two questions: which suffix of a name is its TLD, and how is that
+      # TLD looked up.
+      #
+      # It owns no data of its own — definitions come from an ordered list of
+      # {Sources::Base} objects, later sources overriding earlier ones. The default
+      # order is bundled WHOIS list, then the IANA RDAP bootstrap, then an optional
+      # user override file, so a deployment can correct a stale registry entry
+      # without a gem release.
+      class ServerRegistry
+        attr_reader :sources
+
+        class << self
+          # The registry as most callers want it.
+          #
+          # @param override_path [String, nil] extra definitions, highest priority
+          # @return [ServerRegistry]
+          def default(override_path: Paths.override)
+            sources = [
+              Sources::JsonFile.new(path: Paths::WHOIS_SERVERS, name: "bundled"),
+              Sources::IanaBootstrap.new
+            ]
+
+            if override_path
+              sources << Sources::JsonFile.new(path: override_path, optional: true, name: "override")
+            end
+
+            new(sources: sources)
+          end
+        end
+
+        # @param sources [Array<Sources::Base>] consulted in order; later wins
+        def initialize(sources:)
+          raise ArgumentError, "at least one source is required" if sources.nil? || sources.empty?
+
+          @sources = sources
+          @mutex = Mutex.new
+        end
+
+        # Every TLD this registry can look up, keyed with a leading dot.
+        #
+        # @return [Hash{String => Definition}]
+        def definitions
+          # Bulk checks resolve concurrently, and the first of those threads would
+          # otherwise trigger this build several times over.
+          @definitions || @mutex.synchronize { @definitions ||= build }
+        end
+
+        # @param tld [String, nil] with or without a leading dot
+        # @return [Boolean]
+        def supports?(tld)
+          !definition_for(tld).nil?
+        end
+
+        # @param tld [String, nil]
+        # @return [Definition, nil]
+        def definition_for(tld)
+          return nil if tld.nil?
+
+          key = tld.to_s.strip.downcase
+          key = ".#{key}" unless key.start_with?(".")
+          definitions[key]
+        end
+
+        # @return [Array<String>] sorted, dotted TLDs
+        def supported_tlds
+          definitions.keys.sort
+        end
+
+        def size
+          definitions.size
+        end
+
+        # Split +name+ at its longest known suffix.
+        #
+        # Longest-first is what makes multi-label suffixes and subdomains both land
+        # on the registrable name: +example.co.uk+ resolves against +.co.uk+ rather
+        # than +.uk+, and +www.example.com+ resolves to +example.com+ rather than
+        # being queried as-is.
+        #
+        # @param name [DomainName, String]
+        # @return [Resolution, nil] nil when no suffix of the name is known
+        def resolve(name)
+          domain = name.is_a?(DomainName) ? name : DomainName.parse(name)
+          labels = domain.ascii_labels
+          return nil if labels.length < 2
+
+          # The Unicode labels line up one-for-one with the ASCII ones, so the split
+          # found below can be applied to either form.
+          unicode_labels = domain.labels
+
+          # Start at the longest candidate suffix and shrink, so ".co.uk" is tried
+          # before ".uk".
+          (1...labels.length).each do |index|
+            candidate = ".#{labels[index..].join(".")}"
+            definition = definitions[candidate]
+            next if definition.nil?
+
+            return Resolution.new(
+              domain: domain,
+              sld: labels[index - 1],
+              tld: candidate,
+              definition: definition,
+              registrable: registrable_from(unicode_labels, index)
+            )
+          end
+
+          nil
+        end
+
+        # Drop the memoised definitions so the next call re-reads every source.
+        # Mainly for tests and for long-running processes that refresh a data file.
+        def reload
+          @mutex.synchronize { @definitions = nil }
+          self
+        end
+
+        def inspect
+          "#<#{self.class.name} #{@definitions ? "#{@definitions.size} tlds" : "not loaded"} " \
+            "sources=#{sources.map(&:name).join(",")}>"
+        end
+
+        private
+
+        # Rebuild the registrable name from the Unicode labels, keeping the same split
+        # point the ASCII match found. Returns nil if the two label lists somehow
+        # disagree in length, in which case {Resolution} falls back to the ASCII form.
+        def registrable_from(unicode_labels, index)
+          return nil if index > unicode_labels.length - 1
+
+          DomainName.parse([unicode_labels[index - 1], *unicode_labels[index..]].join("."))
+        end
+
+        def build
+          merged = sources.each_with_object({}) do |source, accumulator|
+            source.load.each do |tld, definition|
+              existing = accumulator[tld]
+              accumulator[tld] = existing ? existing.merge(definition) : definition
+            end
+          end
+
+          if merged.empty?
+            raise DefinitionsError,
+                  "no definitions loaded from #{sources.map(&:name).join(", ")}"
+          end
+
+          merged.select { |_tld, definition| definition.usable? }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/registry/sources/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../definition"
+require_relative "../../errors"
+
+module MonoVM
+  module Whois
+    module Registry
+      module Sources
+        # Interface for anything that can supply TLD definitions.
+        #
+        # {ServerRegistry} depends on this, not on files: that is what lets a host
+        # application feed definitions from a database, an internal HTTP service or
+        # a hard-coded hash in a test, without the registry knowing. A source needs
+        # two methods, {#name} and {#load}.
+        class Base
+          # A short identifier recorded in {Definition#sources}, so a surprising
+          # endpoint can be traced back to whichever source supplied it.
+          #
+          # @return [String]
+          def name
+            self.class.name.to_s.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+          end
+
+          # @return [Hash{String => Definition}] keyed by TLD, with the leading dot
+          def load
+            raise NotImplementedError, "#{self.class} must implement #load"
+          end
+
+          # Sources that cannot be read are usually optional (an override file that
+          # does not exist yet). Returning true here lets {ServerRegistry} skip a
+          # failure instead of aborting every lookup.
+          def optional?
+            false
+          end
+
+          private
+
+          # Normalise +com+, +.COM+ or + .com + to +.com+.
+          def normalise_tld(raw)
+            cleaned = raw.to_s.strip.downcase.sub(/\A\.+/, "").sub(/\.+\z/, "")
+            return nil if cleaned.empty?
+
+            ".#{cleaned}"
+          end
+
+          # A TLD may be internationalised (.рф, .中国); definitions are keyed by the
+          # ASCII form because that is what a resolved name is matched against.
+          def ascii_tld(tld)
+            return nil if tld.nil?
+
+            DomainName.parse(tld.delete_prefix(".")).ascii.then { |ascii| ".#{ascii}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/registry/sources/iana_bootstrap.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+require_relative "../../paths"
+
+module MonoVM
+  module Whois
+    module Registry
+      module Sources
+        # The IANA RDAP bootstrap registry (RFC 7484).
+        #
+        # IANA publishes the authoritative TLD -> RDAP base URL map at
+        # https://data.iana.org/rdap/dns.json. A snapshot ships with the gem, which
+        # is why this library can answer for far more TLDs than a hand-maintained
+        # port 43 list covers, and why those answers are structured JSON instead of
+        # registry prose.
+        #
+        # The file looks like:
+        #
+        #   {
+        #     "version": "1.0",
+        #     "publication": "2026-07-23T02:00:03Z",
+        #     "services": [
+        #       [ ["com", "net"], ["https://rdap.verisign.com/com/v1/"] ]
+        #     ]
+        #   }
+        #
+        # Reading is deliberately offline. Fetching at load time would put a network
+        # round trip in front of every process boot and make the library's own
+        # startup depend on IANA being reachable; +rake data:refresh_rdap+ updates
+        # the snapshot instead.
+        class IanaBootstrap < Base
+          BOOTSTRAP_URL = "https://data.iana.org/rdap/dns.json"
+
+          # RDAP domain lookups live under +{base}/domain/{name}+ (RFC 7482 §3.1.3).
+          DOMAIN_PATH = "domain/"
+
+          attr_reader :path
+
+          def initialize(path: Paths::RDAP_BOOTSTRAP, optional: true)
+            @path = path
+            @optional = optional
+            super()
+          end
+
+          def name
+            "iana-rdap"
+          end
+
+          def optional?
+            @optional
+          end
+
+          # @return [String, nil] the snapshot's publication timestamp
+          def published_at
+            document&.fetch("publication", nil)
+          end
+
+          # @return [Hash{String => Definition}]
+          def load
+            services = document&.fetch("services", nil)
+            return {} unless services.is_a?(Array)
+
+            services.each_with_object({}) do |service, definitions|
+              endpoint = endpoint_for(service)
+              next if endpoint.nil?
+
+              tlds_in(service).each do |tld|
+                definitions[tld] ||= Definition.new(tld: tld, rdap_endpoint: endpoint, sources: [name])
+              end
+            end
+          end
+
+          private
+
+          def document
+            return @document if defined?(@document)
+
+            @document = read_document
+          end
+
+          def read_document
+            raw = read
+            return nil if raw.nil?
+
+            parsed = JSON.parse(raw)
+            parsed.is_a?(Hash) ? parsed : nil
+          rescue JSON::ParserError => e
+            raise DefinitionsError, "#{path} is not valid JSON: #{e.message}" unless optional?
+
+            nil
+          end
+
+          def read
+            return File.read(path, encoding: "UTF-8") if File.file?(path)
+            return nil if optional?
+
+            raise DefinitionsError, "RDAP bootstrap not found at #{path}"
+          rescue SystemCallError => e
+            raise DefinitionsError, "cannot read #{path}: #{e.message}" unless optional?
+
+            nil
+          end
+
+          # A service entry is +[[tld, ...], [url, ...]]+.
+          def tlds_in(service)
+            return [] unless service.is_a?(Array) && service[0].is_a?(Array)
+
+            service[0].filter_map { |tld| ascii_tld(normalise_tld(tld)) }
+          end
+
+          def endpoint_for(service)
+            return nil unless service.is_a?(Array) && service[1].is_a?(Array)
+
+            url = preferred_url(service[1])
+            return nil if url.nil?
+
+            Endpoint.parse("#{url}#{DOMAIN_PATH}")
+          rescue DefinitionsError
+            # One malformed entry must not cost us the other 1,199.
+            nil
+          end
+
+          # HTTPS where a registry offers both: RDAP responses carry registrant
+          # data, and there is no reason to read it off the wire in clear text.
+          def preferred_url(urls)
+            candidates = urls.filter_map do |url|
+              text = url.to_s.strip
+              text.empty? ? nil : text
+            end
+
+            chosen = candidates.find { |url| url.start_with?("https://") } || candidates.first
+            return nil if chosen.nil?
+
+            chosen.end_with?("/") ? chosen : "#{chosen}/"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/registry/sources/json_file.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+
+module MonoVM
+  module Whois
+    module Registry
+      module Sources
+        # Reads the server-list JSON format: an array of entries, each mapping a
+        # comma-separated +extensions+ list to one endpoint.
+        #
+        #   [
+        #     {
+        #       "extensions": ".com,.net",
+        #       "uri": "socket://whois.verisign-grs.com",
+        #       "available": "No match for",
+        #       "premium": "Reserved",
+        #       "rdap": "https://rdap.verisign.com/com/v1/domain/",
+        #       "available_when_empty": false,
+        #       "comment": "why this entry looks like this"
+        #     }
+        #   ]
+        #
+        # Both the bundled list and a user override file use this class — they
+        # differ only in path and in whether a missing file is fatal.
+        class JsonFile < Base
+          attr_reader :path
+
+          # @param path [String]
+          # @param optional [Boolean] when true, a missing or unreadable file
+          #   yields no definitions instead of raising
+          # @param name [String, nil] identifier recorded on each definition
+          def initialize(path:, optional: false, name: nil)
+            @path = path
+            @optional = optional
+            @name = name
+            super()
+          end
+
+          def name
+            @name || (optional? ? "override" : "bundled")
+          end
+
+          def optional?
+            @optional
+          end
+
+          # @return [Hash{String => Definition}]
+          def load
+            raw = read
+            return {} if raw.nil?
+
+            entries = parse(raw)
+            entries.each_with_index.with_object({}) do |(entry, index), definitions|
+              add_entry(definitions, entry, index)
+            end
+          end
+
+          private
+
+          def read
+            return File.read(path, encoding: "UTF-8") if File.file?(path)
+            return nil if optional?
+
+            raise DefinitionsError, "server definitions not found at #{path}"
+          rescue SystemCallError => e
+            raise DefinitionsError, "cannot read #{path}: #{e.message}" unless optional?
+
+            nil
+          end
+
+          def parse(raw)
+            parsed = JSON.parse(raw)
+            unless parsed.is_a?(Array)
+              raise DefinitionsError, "#{path} must hold a JSON array, got #{parsed.class}"
+            end
+
+            parsed
+          rescue JSON::ParserError => e
+            raise DefinitionsError, "#{path} is not valid JSON: #{e.message}"
+          end
+
+          def add_entry(definitions, entry, index)
+            unless entry.is_a?(Hash)
+              raise DefinitionsError, "#{path}: entry #{index} must be an object, got #{entry.class}"
+            end
+
+            whois = build_endpoint(entry["uri"], index)
+            rdap = build_endpoint(entry["rdap"], index)
+            return if whois.nil? && rdap.nil?
+
+            tlds_in(entry).each do |tld|
+              definition = definition_for(tld, entry, whois, rdap)
+              definitions[tld] = definitions.key?(tld) ? definitions[tld].merge(definition) : definition
+            end
+          end
+
+          def tlds_in(entry)
+            entry["extensions"].to_s.split(",").filter_map do |extension|
+              ascii_tld(normalise_tld(extension))
+            end
+          end
+
+          def definition_for(tld, entry, whois, rdap)
+            Definition.new(
+              tld: tld,
+              whois_endpoint: whois,
+              rdap_endpoint: rdap,
+              available_match: entry["available"],
+              premium_match: entry["premium"],
+              available_when_empty: truthy?(entry["available_when_empty"]),
+              comment: entry["comment"],
+              sources: [name]
+            )
+          end
+
+          def build_endpoint(uri, index)
+            return nil if uri.nil? || uri.to_s.strip.empty?
+
+            Endpoint.parse(uri)
+          rescue DefinitionsError => e
+            raise DefinitionsError, "#{path}: entry #{index} has a bad endpoint: #{e.message}"
+          end
+
+          # JSON gives real booleans, but hand-maintained files and environment
+          # overrides tend to carry strings.
+          def truthy?(value)
+            return value if [true, false].include?(value)
+
+            %w[1 true yes on].include?(value.to_s.strip.downcase)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/response.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MonoVM
+  module Whois
+    # One raw answer from one server.
+    #
+    # Transports return this; availability rules and parsers read it. Keeping the
+    # raw body verbatim matters — callers of a WHOIS library legitimately want to
+    # see exactly what the registry said, so nothing here mutates {#body}.
+    class Response
+      attr_reader :body, :endpoint, :query, :status, :elapsed
+
+      # @param body [String] exactly what the server sent
+      # @param endpoint [Endpoint] where it came from
+      # @param query [String] the name that was asked about
+      # @param status [Integer, nil] HTTP status, nil for port 43
+      # @param elapsed [Float, nil] seconds spent on the exchange
+      def initialize(body:, endpoint:, query:, status: nil, elapsed: nil)
+        @body = body.to_s.freeze
+        @endpoint = endpoint
+        @query = query
+        @status = status
+        @elapsed = elapsed
+      end
+
+      # Not frozen as a whole: {#text} and {#json} are memoised, and parsing a large
+      # RDAP document on every rule that asks for it would be wasted work. The body
+      # itself is frozen, so the response is still effectively immutable.
+
+      def rdap?
+        endpoint.kind == :rdap
+      end
+
+      def whois?
+        endpoint.kind == :whois
+      end
+
+      def empty?
+        body.strip.empty?
+      end
+
+      # The body as text, with line endings normalised to \n. Availability rules
+      # match against this so a pattern anchored to a line start behaves the same
+      # whether the registry sent CRLF or LF.
+      def text
+        @text ||= body.encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+                      .gsub(/\r\n?/, "\n")
+                      .freeze
+      end
+
+      # The parsed RDAP document, or nil when the body is not JSON.
+      #
+      # Memoised including the nil case: a non-JSON body is re-checked by several
+      # rules and reparsing it each time is wasted work.
+      def json
+        return @json if defined?(@json)
+
+        @json = begin
+          parsed = JSON.parse(body)
+          parsed.is_a?(Hash) ? parsed : nil
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      def json?
+        !json.nil?
+      end
+
+      def to_h
+        {
+          query: query,
+          endpoint: endpoint.to_s,
+          kind: endpoint.kind,
+          status: status,
+          elapsed: elapsed,
+          length: body.length
+        }
+      end
+
+      def inspect
+        "#<#{self.class.name} query=#{query.inspect} endpoint=#{endpoint} " \
+          "status=#{status.inspect} bytes=#{body.length}>"
+      end
+    end
+  end
+end