monovm-whois-ruby 1.0.0

data/lib/monovm/whois/parser/record.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "time"
+
+module MonoVM
+  module Whois
+    module Parser
+      # A registration, parsed into typed fields.
+      #
+      # A library that hands back only the raw response leaves every caller that
+      # wants an expiry date writing its own regexp — once per registry format.
+      # This is that work done once.
+      #
+      # {#fields} keeps every key/value the parser saw, so nothing is lost to the
+      # normalisation: if a registry emits something this class has no accessor for,
+      # it is still reachable.
+      class Record
+        # Values registries use to mean "withheld", mostly post-GDPR. Treated as
+        # absent rather than reported as a registrant literally named "REDACTED FOR
+        # PRIVACY", which would otherwise look like real data to a caller.
+        REDACTIONS = [
+          "redacted for privacy", "redacted", "not disclosed", "data protected",
+          "privacy protected", "withheld for privacy", "statutory masking enabled",
+          "gdpr masked", "non-public data", "not available", "n/a", "none"
+        ].freeze
+
+        attr_reader :domain, :registry_id, :registrar, :registrar_whois_server,
+                    :registrar_url, :registrar_iana_id, :registrant, :statuses,
+                    :nameservers, :created_on, :updated_on, :expires_on, :dnssec,
+                    :contacts, :fields, :source
+
+        def initialize(domain: nil, registry_id: nil, registrar: nil, registrar_whois_server: nil,
+                       registrar_url: nil, registrar_iana_id: nil, registrant: nil, statuses: [],
+                       nameservers: [], created_on: nil, updated_on: nil, expires_on: nil,
+                       dnssec: nil, contacts: {}, fields: {}, source: nil)
+          @domain = clean(domain)
+          @registry_id = clean(registry_id)
+          @registrar = clean(registrar)
+          @registrar_whois_server = clean(registrar_whois_server)&.downcase
+          @registrar_url = clean(registrar_url)
+          @registrar_iana_id = clean(registrar_iana_id)
+          @registrant = clean(registrant)
+          @statuses = normalise_list(statuses).freeze
+          @nameservers = normalise_nameservers(nameservers).freeze
+          @created_on = created_on
+          @updated_on = updated_on
+          @expires_on = expires_on
+          @dnssec = dnssec
+          @contacts = contacts.freeze
+          @fields = fields.freeze
+          @source = source
+          freeze
+        end
+
+        # The constructor's arguments, as a Hash. Lets a record be rebuilt with a few
+        # fields changed — which is what merging a registry record with a registrar's
+        # amounts to — without naming all sixteen fields at every call site.
+        #
+        # @return [Hash]
+        def attributes
+          {
+            domain: domain, registry_id: registry_id, registrar: registrar,
+            registrar_whois_server: registrar_whois_server, registrar_url: registrar_url,
+            registrar_iana_id: registrar_iana_id, registrant: registrant,
+            statuses: statuses, nameservers: nameservers, created_on: created_on,
+            updated_on: updated_on, expires_on: expires_on, dnssec: dnssec,
+            contacts: contacts, fields: fields, source: source
+          }
+        end
+
+        # True when the parser found nothing worth reporting. A response can parse
+        # cleanly and still be empty — a not-found reply, for instance.
+        def empty?
+          domain.nil? && registrar.nil? && nameservers.empty? && statuses.empty? &&
+            created_on.nil? && expires_on.nil?
+        end
+
+        def dnssec?
+          return false if dnssec.nil?
+
+          !%w[unsigned unsigned delegation no false 0].include?(dnssec.to_s.downcase.strip)
+        end
+
+        # True when the registry says this name is locked against transfer.
+        def transfer_prohibited?
+          statuses.any? { |status| status.downcase.include?("transferprohibited") }
+        end
+
+        # True for any status meaning the registration is winding down.
+        def expiring?
+          statuses.any? do |status|
+            normalised = status.downcase.delete(" ")
+            normalised.include?("redemption") || normalised.include?("pendingdelete") ||
+              normalised.include?("autorenewperiod")
+          end
+        end
+
+        # Days until expiry, or nil when the record carries no expiry date.
+        # Negative when the date has passed.
+        def days_until_expiry(now: Time.now)
+          return nil if expires_on.nil?
+
+          ((expires_on - now) / 86_400).floor
+        end
+
+        # Look up a raw field by any of its names, case-insensitively.
+        #
+        #   record["Registry Expiry Date"]
+        def [](key)
+          wanted = key.to_s.downcase.strip
+          _, value = fields.find { |name, _| name.to_s.downcase.strip == wanted }
+          value
+        end
+
+        def to_h
+          {
+            domain: domain,
+            registry_id: registry_id,
+            registrar: registrar,
+            registrar_whois_server: registrar_whois_server,
+            registrar_url: registrar_url,
+            registrar_iana_id: registrar_iana_id,
+            registrant: registrant,
+            statuses: statuses,
+            nameservers: nameservers,
+            created_on: created_on&.iso8601,
+            updated_on: updated_on&.iso8601,
+            expires_on: expires_on&.iso8601,
+            dnssec: dnssec,
+            contacts: contacts.empty? ? nil : contacts,
+            source: source
+          }.compact
+        end
+
+        def inspect
+          "#<#{self.class.name} #{domain.inspect} registrar=#{registrar.inspect} " \
+            "expires=#{expires_on&.iso8601.inspect}>"
+        end
+
+        private
+
+        def clean(value)
+          text = value.to_s.strip
+          return nil if text.empty?
+          return nil if REDACTIONS.include?(text.downcase)
+
+          text
+        end
+
+        def normalise_list(values)
+          Array(values).filter_map { |value| clean(value) }.uniq
+        end
+
+        # Registries pad nameservers with an IP address on the same line
+        # (+ns1.example.com 192.0.2.1+) and disagree about case.
+        def normalise_nameservers(values)
+          Array(values).filter_map do |value|
+            host = clean(value)&.split(/[\s,]+/)&.first
+            host&.downcase&.delete_suffix(".")
+          end.uniq
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/parser/selector.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "rdap_json"
+require_relative "icann_rdd"
+require_relative "key_value"
+require_relative "record"
+
+module MonoVM
+  module Whois
+    module Parser
+      # Picks the parser that understands a response.
+      #
+      # Ordered most specific first: RDAP JSON, then the ICANN gTLD format, then the
+      # generic key/value fallback that handles everything else. Each parser decides
+      # for itself whether it applies, so adding support for a registry with a genuinely
+      # odd format means writing one parser and registering it — no changes here.
+      #
+      # Named +Selector+ rather than +Registry+ on purpose: {MonoVM::Whois::Registry}
+      # already means "the TLD server registry", and two different Registry classes in
+      # one library is a trap for whoever reads it next.
+      class Selector
+        def self.default
+          new([RdapJson.new, IcannRdd.new, KeyValue.new])
+        end
+
+        attr_reader :parsers
+
+        def initialize(parsers = [])
+          @parsers = parsers.dup
+        end
+
+        # @param response [Response]
+        # @return [Record] an empty record when nothing understood the response,
+        #   which is normal: a not-found reply has no registration to parse
+        def parse(response)
+          parser = parser_for(response)
+          return Record.new(source: nil) if parser.nil?
+
+          parser.parse(response)
+        rescue StandardError => e
+          # A malformed record must not turn a successful lookup into an exception.
+          # The verdict does not depend on parsing, so a failure here costs the
+          # caller the structured fields and nothing else.
+          Record.new(fields: { "parse_error" => "#{e.class}: #{e.message}" }, source: parser&.name)
+        end
+
+        # @return [Base, nil]
+        def parser_for(response)
+          parsers.find { |parser| parser.applicable?(response) }
+        end
+
+        # Add a parser ahead of the defaults.
+        def prepend(parser)
+          @parsers.unshift(parser)
+          self
+        end
+
+        def append(parser)
+          @parsers.push(parser)
+          self
+        end
+        alias << append
+
+        def names
+          parsers.map(&:name)
+        end
+
+        def inspect
+          "#<#{self.class.name} #{names.join(", ")}>"
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/paths.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module MonoVM
+  module Whois
+    # Locations of the data files shipped inside the gem.
+    module Paths
+      # +lib/monovm/whois/paths.rb+ -> the gem root.
+      ROOT = File.expand_path("../../..", __dir__)
+      DATA_DIR = File.join(ROOT, "data")
+
+      # Curated WHOIS server list: TLD -> port 43 host plus availability markers.
+      WHOIS_SERVERS = File.join(DATA_DIR, "whois_servers.json")
+
+      # Snapshot of the IANA RDAP bootstrap registry (RFC 7484).
+      # Refresh with +rake data:refresh_rdap+.
+      RDAP_BOOTSTRAP = File.join(DATA_DIR, "rdap_bootstrap.json")
+
+      # Environment variable pointing at an override file, so a deployment can
+      # correct a stale registry entry without waiting for a gem release.
+      OVERRIDE_ENV_VAR = "MONOVM_WHOIS_DEFINITIONS"
+
+      class << self
+        # @return [String, nil] the override file path, if one is configured
+        def override
+          path = ENV.fetch(OVERRIDE_ENV_VAR, nil)
+          path.nil? || path.strip.empty? ? nil : path.strip
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/punycode.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module MonoVM
+  module Whois
+    # Punycode (RFC 3492) encoder and decoder.
+    #
+    # Ruby has no Punycode or IDNA support in its standard library, and pulling in
+    # a gem for ~120 lines of well-specified arithmetic would cost this library its
+    # zero-dependency guarantee. So it lives here, transcribed from the reference
+    # pseudocode in RFC 3492 section 6 and checked against the test vectors in
+    # section 7.1.
+    #
+    # This module deals in single labels. Whole-name conversion, the +xn--+ prefix
+    # and validation belong to {DomainName}.
+    module Punycode
+      BASE         = 36
+      TMIN         = 1
+      TMAX         = 26
+      SKEW         = 38
+      DAMP         = 700
+      INITIAL_BIAS = 72
+      INITIAL_N    = 128
+      DELIMITER    = "-"
+
+      # Highest code point that survives a round trip through the bias arithmetic
+      # without overflowing what a DNS label could ever hold.
+      MAX_CODE_POINT = 0x10FFFF
+
+      # Raised when a label is not valid Punycode. Never leaks out of
+      # {DomainName}, which treats an undecodable label as "leave it alone".
+      class Error < MonoVM::Whois::Error; end
+
+      class << self
+        # Encode a Unicode label as Punycode, without the +xn--+ prefix.
+        #
+        #   Punycode.encode("münchen") # => "mnchen-3ya"
+        #
+        # @param input [String] one label, already normalised and downcased
+        # @return [String]
+        def encode(input)
+          code_points = input.codepoints
+          basic = code_points.select { |cp| basic?(cp) }
+
+          output = basic.pack("U*")
+          output += DELIMITER unless basic.empty?
+
+          n = INITIAL_N
+          delta = 0
+          bias = INITIAL_BIAS
+          handled = basic.length
+          basic_length = basic.length
+
+          while handled < code_points.length
+            # The next code point to deal with is the smallest one we have not
+            # reached yet; that ordering is what makes the encoding reversible.
+            m = code_points.select { |cp| cp >= n }.min
+            delta += (m - n) * (handled + 1)
+            n = m
+
+            code_points.each do |cp|
+              delta += 1 if cp < n
+              next unless cp == n
+
+              output += encode_delta(delta, bias)
+              bias = adapt(delta, handled + 1, handled == basic_length)
+              delta = 0
+              handled += 1
+            end
+
+            delta += 1
+            n += 1
+          end
+
+          output
+        end
+
+        # Decode a Punycode label. The +xn--+ prefix must already be stripped.
+        #
+        #   Punycode.decode("mnchen-3ya") # => "münchen"
+        #
+        # @param input [String]
+        # @return [String]
+        # @raise [Error] if the input is not valid Punycode
+        def decode(input)
+          delimiter_at = input.rindex(DELIMITER)
+
+          if delimiter_at
+            basic = input[0...delimiter_at]
+            raise Error, "non-basic code point before the delimiter" unless basic.ascii_only?
+
+            output = basic.codepoints
+            cursor = delimiter_at + 1
+          else
+            output = []
+            cursor = 0
+          end
+
+          n = INITIAL_N
+          i = 0
+          bias = INITIAL_BIAS
+          digits = input.codepoints
+
+          while cursor < digits.length
+            old_i = i
+            weight = 1
+            k = BASE
+
+            loop do
+              raise Error, "truncated punycode sequence" if cursor >= digits.length
+
+              digit = digit_value(digits[cursor])
+              cursor += 1
+
+              i += digit * weight
+              raise Error, "punycode overflow" if i > MAX_CODE_POINT * (output.length + 1)
+
+              t = threshold(k, bias)
+              break if digit < t
+
+              weight *= (BASE - t)
+              k += BASE
+            end
+
+            bias = adapt(i - old_i, output.length + 1, old_i.zero?)
+            n += i / (output.length + 1)
+            i %= (output.length + 1)
+
+            raise Error, "punycode decoded to a basic code point" if basic?(n)
+            raise Error, "punycode decoded outside Unicode" if n > MAX_CODE_POINT
+
+            output.insert(i, n)
+            i += 1
+          end
+
+          output.pack("U*")
+        end
+
+        private
+
+        # Emit the variable-length integer for one delta, generalised
+        # variable-length quantity style (RFC 3492 section 3.3).
+        def encode_delta(delta, bias)
+          out = +""
+          q = delta
+          k = BASE
+
+          loop do
+            t = threshold(k, bias)
+            break if q < t
+
+            out << digit_char(t + ((q - t) % (BASE - t)))
+            q = (q - t) / (BASE - t)
+            k += BASE
+          end
+
+          out << digit_char(q)
+        end
+
+        # t is k - bias clamped to [TMIN, TMAX].
+        def threshold(k, bias)
+          t = k - bias
+          return TMIN if t < TMIN
+          return TMAX if t > TMAX
+
+          t
+        end
+
+        # Bias adaptation, RFC 3492 section 6.1. Keeps later deltas cheap to
+        # encode by tracking how large the previous ones were.
+        def adapt(delta, num_points, first_time)
+          delta = first_time ? delta / DAMP : delta / 2
+          delta += delta / num_points
+
+          k = 0
+          while delta > ((BASE - TMIN) * TMAX) / 2
+            delta /= (BASE - TMIN)
+            k += BASE
+          end
+
+          k + (((BASE - TMIN + 1) * delta) / (delta + SKEW))
+        end
+
+        def basic?(code_point)
+          code_point < INITIAL_N
+        end
+
+        # 0..25 map to a..z, 26..35 to 0..9.
+        def digit_char(digit)
+          raise Error, "digit out of range: #{digit}" unless digit.between?(0, BASE - 1)
+
+          (digit < 26 ? digit + 0x61 : digit - 26 + 0x30).chr
+        end
+
+        def digit_value(code_point)
+          case code_point
+          when 0x41..0x5A then code_point - 0x41       # A-Z
+          when 0x61..0x7A then code_point - 0x61       # a-z
+          when 0x30..0x39 then code_point - 0x30 + 26  # 0-9
+          else
+            raise Error, "not a punycode digit: #{code_point}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/referral/follower.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "../endpoint"
+require_relative "../errors"
+
+module MonoVM
+  module Whois
+    module Referral
+      # Chases a thin registry's pointer to the registrar's own WHOIS server.
+      #
+      # Verisign and the other thin registries hold almost nothing: query +.com+ and
+      # the answer is a domain name, a status, nameservers, and a +Registrar WHOIS
+      # Server+ line pointing at whoever sold it. The registrant, the contact details
+      # and often the accurate expiry date are only on that second server. A client
+      # that stops at the first answer reports the thin record as the whole truth.
+      #
+      # One deliberate constraint: a referral enriches the *record*, never the
+      # verdict. The registry is authoritative about whether a name exists, and a
+      # registrar's server that is down, rate-limiting or simply wrong must not be
+      # able to turn a registered domain into an available one.
+      class Follower
+        # Registrars that answer but say nothing useful, or point in a circle.
+        # Following these costs a round trip and a rate-limit slot for no data.
+        SKIP_HOSTS = [
+          "whois.iana.org",
+          "whois.markmonitor.com",
+          "not.applicable",
+          "none"
+        ].freeze
+
+        attr_reader :transport_factory, :max_hops
+
+        # @param transport_factory [Transport::Factory]
+        # @param max_hops [Integer] referral hops to follow; 1 is almost always right
+        def initialize(transport_factory:, max_hops: 1)
+          @transport_factory = transport_factory
+          @max_hops = max_hops
+        end
+
+        # @param response [Response] the registry's answer
+        # @param record [Parser::Record] parsed from that answer
+        # @param query [String] the name being looked up, in wire form
+        # @return [Response, nil] the registrar's answer, or nil when there is no
+        #   referral to follow or following it failed
+        def follow(response:, record:, query:)
+          return nil unless max_hops.positive?
+          return nil unless response.whois?
+
+          host = referral_host(record, response)
+          return nil if host.nil?
+
+          fetch(Endpoint.parse("socket://#{host}"), query)
+        rescue DefinitionsError
+          # The referral was not a usable host name; keep the registry's answer.
+          nil
+        end
+
+        private
+
+        def referral_host(record, response)
+          host = record.registrar_whois_server
+          host = host_from_text(response) if host.nil?
+          return nil if host.nil?
+
+          host = host.strip.downcase.sub(%r{\Ar?whois://}, "").split("/").first.to_s
+          return nil if host.empty? || SKIP_HOSTS.include?(host)
+          # A server that refers to itself would loop.
+          return nil if host == response.endpoint.host.downcase
+          return nil unless host.include?(".")
+
+          host
+        end
+
+        # Some registries emit the referral without the exact key the parser knows.
+        def host_from_text(response)
+          match = response.text.match(/^\s*(?:Registrar\s+)?WHOIS\s+Server\s*:\s*(\S+)/i)
+          match && match[1]
+        end
+
+        def fetch(endpoint, query)
+          transport_factory.for(endpoint).fetch(query: query, endpoint: endpoint)
+        rescue Error
+          # A failed referral is not an error for the caller: the registry already
+          # answered the question that matters.
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "../endpoint"
+
+module MonoVM
+  module Whois
+    module Registry
+      # Everything known about how to look up one TLD.
+      #
+      # A definition is assembled from several sources: the bundled server list
+      # supplies the port 43 host and the registry's "available" marker, while the
+      # IANA bootstrap supplies the RDAP base URL. {#merge} is what lets those
+      # arrive independently and still end up on one object.
+      class Definition
+        attr_reader :tld, :whois_endpoint, :rdap_endpoint, :available_match,
+                    :premium_match, :comment, :sources
+
+        # @param tld [String] with the leading dot, e.g. +".co.uk"+
+        # @param whois_endpoint [Endpoint, nil] port 43 endpoint
+        # @param rdap_endpoint [Endpoint, nil] RDAP base URL endpoint
+        # @param available_match [String, nil] literal the registry emits for an
+        #   unregistered name; a fast pre-check, not the only signal
+        # @param premium_match [String, nil] literal marking a premium/reserved name
+        # @param available_when_empty [Boolean] registries that answer an
+        #   unregistered name with nothing but their banner. Opt-in per TLD, because
+        #   inferring availability from silence is unsound in general.
+        # @param comment [String, nil] why this entry looks the way it does
+        # @param sources [Array<String>] which sources contributed
+        def initialize(tld:, whois_endpoint: nil, rdap_endpoint: nil, available_match: nil,
+                       premium_match: nil, available_when_empty: false, comment: nil,
+                       sources: [])
+          @tld = tld
+          @whois_endpoint = whois_endpoint
+          @rdap_endpoint = rdap_endpoint
+          @available_match = presence(available_match)
+          @premium_match = presence(premium_match)
+          @available_when_empty = available_when_empty
+          @comment = presence(comment)
+          @sources = sources.freeze
+          freeze
+        end
+
+        def available_when_empty?
+          @available_when_empty
+        end
+
+        def rdap?
+          !rdap_endpoint.nil?
+        end
+
+        def whois?
+          !whois_endpoint.nil?
+        end
+
+        # Endpoints to try, best first.
+        #
+        # RDAP goes first when available: its answer is structured JSON with an
+        # explicit object class or an explicit +errorCode+, so availability is read
+        # rather than guessed. Port 43 free text is the fallback.
+        #
+        # @param prefer [Symbol] +:rdap+ or +:whois+
+        # @return [Array<Endpoint>]
+        def endpoints(prefer: :rdap)
+          ordered = prefer == :whois ? [whois_endpoint, rdap_endpoint] : [rdap_endpoint, whois_endpoint]
+          ordered.compact
+        end
+
+        def usable?
+          rdap? || whois?
+        end
+
+        # Combine with another definition for the same TLD. Values from +other+ win
+        # where it has them, so later sources override earlier ones — that is how a
+        # user's override file beats the bundled list.
+        #
+        # @param other [Definition]
+        # @return [Definition]
+        def merge(other)
+          return self if other.nil?
+
+          self.class.new(
+            tld: tld,
+            whois_endpoint: other.whois_endpoint || whois_endpoint,
+            rdap_endpoint: other.rdap_endpoint || rdap_endpoint,
+            available_match: other.available_match || available_match,
+            premium_match: other.premium_match || premium_match,
+            available_when_empty: other.available_when_empty? || available_when_empty?,
+            comment: other.comment || comment,
+            sources: (sources + other.sources).uniq
+          )
+        end
+
+        def to_h
+          {
+            tld: tld,
+            whois: whois_endpoint&.to_s,
+            rdap: rdap_endpoint&.to_s,
+            available_match: available_match,
+            premium_match: premium_match,
+            available_when_empty: available_when_empty?,
+            sources: sources
+          }.compact
+        end
+
+        def inspect
+          "#<#{self.class.name} #{tld} whois=#{whois_endpoint&.host || "-"} " \
+            "rdap=#{rdap_endpoint ? "yes" : "no"}>"
+        end
+
+        private
+
+        def presence(value)
+          text = value.to_s.strip
+          text.empty? ? nil : text.freeze
+        end
+      end
+    end
+  end
+end