monovm-whois-ruby 1.0.0

data/lib/monovm/whois/errors.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module MonoVM
+  module Whois
+    # Base class for every error this gem raises.
+    #
+    # A library that raises bare exceptions leaves callers rescuing everything
+    # or nothing. Here the taxonomy is meaningful: callers who
+    # just want "did it blow up" rescue {Error}, while callers that retry on a
+    # busy registry but give up on a bad domain can discriminate.
+    class Error < StandardError; end
+
+    # The input is not a usable domain name.
+    class InvalidDomainError < Error
+      attr_reader :domain
+
+      def initialize(domain, message = nil)
+        @domain = domain
+        super(message || "not a usable domain name: #{domain.inspect}")
+      end
+    end
+
+    # No WHOIS or RDAP endpoint is known for this TLD.
+    class UnsupportedTldError < Error
+      attr_reader :tld
+
+      def initialize(tld, message = nil)
+        @tld = tld
+        super(message || "no whois server known for #{tld.nil? ? "a name without a TLD" : tld}")
+      end
+    end
+
+    # A server definition file is missing, unreadable or malformed.
+    class DefinitionsError < Error; end
+
+    # Raised when the transport could not reach the server at all.
+    class ConnectionError < Error; end
+
+    # The connection succeeded but the exchange exceeded the configured timeout.
+    class TimeoutError < ConnectionError; end
+
+    # The server answered, but refused to give a verdict: rate limiting, a
+    # blocked client, a retired port 43 endpoint, or an HTTP status that is not
+    # an answer (401/403/405/406/429/5xx).
+    #
+    # This is deliberately distinct from "the domain is registered". Conflating
+    # the two is how a permissive detector ends up reporting registered domains
+    # as free.
+    class ServerRefusedError < Error
+      attr_reader :endpoint
+
+      def initialize(message, endpoint: nil)
+        @endpoint = endpoint
+        super(message)
+      end
+    end
+
+    # The server closed the connection without sending anything. An empty record
+    # is not evidence that a domain is unregistered, so this is an error rather
+    # than a verdict.
+    class EmptyResponseError < Error; end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "record"
+
+module MonoVM
+  module Whois
+    module Parser
+      # Shared scaffolding for record parsers.
+      #
+      # Subclasses say which responses they understand ({#applicable?}) and how to
+      # turn one into a {Record} ({#parse}). Date parsing lives here because it is
+      # the one job every registry does differently and none of them do well: the
+      # same field arrives as +2026-08-13T04:00:00Z+, +13-Aug-2026+, +2026.08.13+ or
+      # +13/08/2026+, and getting it wrong by a month is worse than returning nil.
+      class Base
+        # @param response [Response]
+        # @return [Boolean]
+        def applicable?(response)
+          raise NotImplementedError, "#{self.class} must implement #applicable?"
+        end
+
+        # @param response [Response]
+        # @return [Record]
+        def parse(response)
+          raise NotImplementedError, "#{self.class} must implement #parse"
+        end
+
+        def name
+          @name ||= Base.snake_case(self.class)
+        end
+
+        # +IcannRdd+ becomes +"icann_rdd"+. Handles an anonymous class, whose
+        # +Module#name+ is nil — which a spec or a host application defining a parser
+        # inline would otherwise crash on.
+        def self.snake_case(klass)
+          base = klass.name.to_s.split("::").last
+          base = klass.inspect if base.nil? || base.empty?
+          base.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+        end
+
+        # Explicit formats, tried in order, before falling back to Ruby's parser.
+        #
+        # Ordering matters for the ambiguous ones: +13/08/2026+ is day-first
+        # everywhere that writes it with slashes in a WHOIS record, so that pattern
+        # comes before the month-first reading Time.parse would pick.
+        DATE_FORMATS = [
+          "%Y-%m-%dT%H:%M:%S%z",
+          "%Y-%m-%dT%H:%M:%SZ",
+          "%Y-%m-%dT%H:%M:%S.%L%z",
+          "%Y-%m-%d %H:%M:%S%z",
+          "%Y-%m-%d %H:%M:%S",
+          "%Y-%m-%d",
+          "%Y.%m.%d %H:%M:%S",
+          "%Y.%m.%d",
+          "%Y/%m/%d",
+          "%d-%b-%Y %H:%M:%S",
+          "%d-%b-%Y",
+          "%d.%m.%Y %H:%M:%S",
+          "%d.%m.%Y",
+          "%d/%m/%Y %H:%M:%S",
+          "%d/%m/%Y",
+          "%b %d %Y",
+          "%d %b %Y",
+          "%Y%m%d"
+        ].freeze
+
+        # Registration dates are never before the DNS existed and never centuries
+        # away. The range is what makes the ambiguous formats safe to try in order:
+        # "%Y.%m.%d" happily parses "12.5.2015" as year 12, month 5, day 2015 —
+        # rolling over into May of year 12 — and without this guard that nonsense wins
+        # before "%d.%m.%Y" is ever tried, silently misdating every European record.
+        PLAUSIBLE_YEARS = (1980..2200)
+
+        private
+
+        # @return [Time, nil]
+        def parse_time(value)
+          text = value.to_s.strip
+          return nil if text.empty?
+
+          # Registries append notes to dates: "2026-08-13 (registry lock)".
+          text = text.sub(/\s*\(.*\)\s*\z/, "").strip
+          # A trailing timezone name after an offset confuses every strptime format.
+          text = text.sub(/\s+\((?:UTC|GMT)[^)]*\)\z/i, "").strip
+          return nil if text.empty?
+
+          from_formats(text) || from_fallback(text)
+        end
+
+        def from_formats(text)
+          DATE_FORMATS.each do |format|
+            parsed = begin
+              Time.strptime(text, format)
+            rescue ArgumentError, RangeError
+              nil
+            end
+
+            next if parsed.nil?
+            next unless PLAUSIBLE_YEARS.cover?(parsed.year)
+            # strptime also parses "2026" with "%Y%m%d" and calls it January 1st;
+            # requiring the year to appear in the input rejects that kind of match.
+            next unless text.include?(parsed.year.to_s)
+
+            return parsed
+          end
+
+          nil
+        end
+
+        def from_fallback(text)
+          Time.parse(text)
+        rescue ArgumentError, RangeError, TypeError
+          nil
+        end
+
+        # Registries answer with a literal for "no data"; those must not become
+        # strings that look like values.
+        def blank?(value)
+          text = value.to_s.strip
+          text.empty? || Record::REDACTIONS.include?(text.downcase)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "key_value"
+
+module MonoVM
+  module Whois
+    module Parser
+      # The ICANN Registrar Data Directory format used by gTLD registries.
+      #
+      # Structurally it is {KeyValue}, so almost everything is inherited. What earns a
+      # subclass is that this format carries the same fact twice and the two copies
+      # disagree: a +.com+ record holds both a +Registry Expiry Date+ and a
+      # +Registrar Registration Expiration Date+, and the registrar's copy is
+      # frequently stale. The registry is authoritative, so it wins here explicitly
+      # rather than by luck of alias ordering.
+      #
+      # It also drops the +>>> Last update of WHOIS database+ trailer, which is a
+      # timestamp for the database rather than for the domain and otherwise lands in
+      # {Record#updated_on}.
+      class IcannRdd < KeyValue
+        # Keys that only this format uses; two of them together is a confident match.
+        SIGNATURE_KEYS = [
+          "registry domain id",
+          "registrar whois server",
+          "registrar iana id",
+          "registry expiry date"
+        ].freeze
+
+        TRAILER = />>>\s*Last update of (?:the )?WHOIS database.*$/i
+
+        def applicable?(response)
+          return false if response.json?
+
+          text = response.text.downcase
+          SIGNATURE_KEYS.count { |key| text.include?("#{key}:") } >= 2
+        end
+
+        def parse(response)
+          record = super
+
+          # The registry's expiry date is authoritative; only fall back to the
+          # registrar's if the registry did not supply one.
+          expires = parse_time(record["registry expiry date"]) || record.expires_on
+
+          Record.new(
+            domain: record.domain,
+            registry_id: record.registry_id,
+            registrar: record.registrar,
+            registrar_whois_server: record.registrar_whois_server,
+            registrar_url: record.registrar_url,
+            registrar_iana_id: record.registrar_iana_id,
+            registrant: record.registrant,
+            statuses: record.statuses.map { |status| strip_epp_url(status) },
+            nameservers: record.nameservers,
+            created_on: record.created_on,
+            updated_on: record.updated_on,
+            expires_on: expires,
+            dnssec: record.dnssec,
+            contacts: record.contacts,
+            fields: record.fields,
+            source: name
+          )
+        end
+
+        private
+
+        def extract_pairs(text)
+          super(text.sub(TRAILER, ""))
+        end
+
+        # Statuses arrive as "clientTransferProhibited https://icann.org/epp#..." —
+        # the URL is documentation, not part of the status.
+        def strip_epp_url(status)
+          status.split(/\s+/).first
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../availability/patterns"
+
+module MonoVM
+  module Whois
+    module Parser
+      # Parses the +Key: value+ shape that nearly every port 43 registry speaks.
+      #
+      # There is no standard for this format, only a strong convention, so the work
+      # is in the disagreements: keys padded with dots to align values, the same field
+      # called +Creation Date+, +created+, +registered on+ or +paid-till+, and fields
+      # that legitimately repeat (a domain has several nameservers and several EPP
+      # statuses). {ALIASES} is where that variation is absorbed; everything else here
+      # is mechanical.
+      class KeyValue < Base
+        # +Key: value+, tolerating padded keys and values that contain colons.
+        LINE = /\A(?<key>[^:]{1,64}?)[\s._·-]*:[ \t]*(?<value>.*)\z/
+
+        # Canonical field name => the key spellings that mean it, most preferred
+        # first. Order matters where a record carries two candidates: a gTLD record
+        # has both a registry expiry date and the registrar's copy of it, and the
+        # registry is authoritative.
+        ALIASES = {
+          domain: ["domain name", "domain", "ascii", "domain-name", "the domain"],
+          registry_id: ["registry domain id"],
+          registrar: ["registrar", "sponsoring registrar", "registrar name", "registrar organization"],
+          registrar_whois_server: ["registrar whois server", "whois server"],
+          registrar_url: ["registrar url", "referral url", "registrar web"],
+          registrar_iana_id: ["registrar iana id"],
+          registrant: [
+            "registrant name", "registrant organization", "registrant organisation",
+            "registrant", "holder", "holder name", "organisation", "organization", "org"
+          ],
+          created_on: [
+            "creation date", "created", "created on", "created date", "registered on",
+            "registration date", "registered", "domain registration date", "record created",
+            "activation date"
+          ],
+          updated_on: [
+            "updated date", "last updated", "last update", "changed", "modified",
+            "last modified", "record last updated", "update date"
+          ],
+          expires_on: [
+            "registry expiry date", "expiry date", "expiration date", "expires",
+            "expires on", "expire date", "paid-till", "renewal date", "record expires",
+            "registrar registration expiration date", "valid until", "expiry"
+          ],
+          dnssec: ["dnssec", "dnssec signed", "signed"]
+        }.freeze
+
+        # Fields that may appear many times; every occurrence is kept.
+        MULTI = {
+          statuses: ["domain status", "status", "state", "eppstatus"],
+          nameservers: ["name server", "nameserver", "nserver", "ns", "dns", "name servers"]
+        }.freeze
+
+        # Contact blocks, addressed by key prefix: +Admin Email:+, +Tech Name:+.
+        CONTACT_ROLES = {
+          registrant: %w[registrant],
+          admin: ["admin", "administrative contact", "admin contact"],
+          tech: ["tech", "technical contact", "tech contact"],
+          billing: ["billing", "billing contact"]
+        }.freeze
+
+        CONTACT_ATTRIBUTES = {
+          name: "name",
+          organization: "organization",
+          email: "email",
+          phone: "phone",
+          country: "country",
+          city: "city",
+          state: "state/province"
+        }.freeze
+
+        def applicable?(response)
+          return false if response.json?
+
+          # LINE is anchored, so it has to be matched a line at a time — testing it
+          # against the whole response fails on anything multi-line, which is every
+          # real record.
+          response.text.each_line.any? { |line| LINE.match?(line.strip) }
+        end
+
+        def parse(response)
+          pairs = extract_pairs(response.text)
+
+          Record.new(**attributes_from(pairs), fields: flatten(pairs), source: name)
+        end
+
+        private
+
+        # {ALIASES}'s keys are deliberately {Record}'s keyword names, so resolving the
+        # single-valued fields is one transform rather than a line each.
+        def attributes_from(pairs)
+          resolved = ALIASES.transform_values { |keys| first(pairs, keys) }
+
+          resolved.merge(
+            statuses: all(pairs, MULTI[:statuses]),
+            nameservers: all(pairs, MULTI[:nameservers]),
+            created_on: parse_time(resolved[:created_on]),
+            updated_on: parse_time(resolved[:updated_on]),
+            expires_on: parse_time(resolved[:expires_on]),
+            contacts: extract_contacts(pairs)
+          )
+        end
+
+        # @return [Hash{String => Array<String>}] normalised key => every value seen
+        def extract_pairs(text)
+          text.split("\n").each_with_object({}) do |raw_line, pairs|
+            line = raw_line.strip
+            next if line.empty? || comment?(line)
+
+            match = LINE.match(line)
+            next if match.nil?
+
+            key = normalise_key(match[:key])
+            value = match[:value].strip
+            next if key.empty? || blank?(value)
+
+            (pairs[key] ||= []) << value
+          end
+        end
+
+        def comment?(line)
+          Availability::Patterns::COMMENT_PREFIXES.any? { |prefix| line.start_with?(prefix) }
+        end
+
+        # Strip alignment padding, collapse inner whitespace, downcase.
+        def normalise_key(key)
+          key.strip.sub(/[\s.·]+\z/, "").gsub(/\s+/, " ").downcase
+        end
+
+        def first(pairs, keys)
+          keys.each do |key|
+            values = pairs[key]
+            return values.first if values && !values.empty?
+          end
+
+          nil
+        end
+
+        def all(pairs, keys)
+          keys.flat_map { |key| pairs[key] || [] }
+        end
+
+        def flatten(pairs)
+          pairs.transform_values { |values| values.length == 1 ? values.first : values }
+        end
+
+        def extract_contacts(pairs)
+          CONTACT_ROLES.each_with_object({}) do |(role, prefixes), contacts|
+            details = contact_details(pairs, prefixes)
+            contacts[role] = details unless details.empty?
+          end
+        end
+
+        def contact_details(pairs, prefixes)
+          CONTACT_ATTRIBUTES.each_with_object({}) do |(attribute, suffix), details|
+            keys = prefixes.map { |prefix| "#{prefix} #{suffix}" }
+            value = first(pairs, keys)
+            details[attribute] = value unless value.nil?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module MonoVM
+  module Whois
+    module Parser
+      # Parses an RDAP domain object (RFC 9083).
+      #
+      # RDAP is where structured data was the point, so this parser reads fields
+      # instead of guessing at prose. Two parts of the format still need translating:
+      # dates live in an +events+ array keyed by +eventAction+ rather than in named
+      # fields, and contacts are jCard/vCard arrays (RFC 7095) — a nested array of
+      # +[name, params, type, value]+ tuples that has to be walked to find an email.
+      class RdapJson < Base
+        # eventAction values mapped to the record fields they populate.
+        EVENTS = {
+          "registration" => :created_on,
+          "last changed" => :updated_on,
+          "last update of rdap database" => nil, # about the database, not the domain
+          "expiration" => :expires_on
+        }.freeze
+
+        ROLES = {
+          "registrant" => :registrant,
+          "administrative" => :admin,
+          "technical" => :tech,
+          "billing" => :billing,
+          "registrar" => :registrar
+        }.freeze
+
+        # jCard property name => the record field it populates. +adr+ is absent because
+        # its value is a structured array rather than a plain string.
+        VCARD_FIELDS = { "fn" => :fn, "org" => :org, "email" => :email, "tel" => :tel }.freeze
+
+        def applicable?(response)
+          document = response.json
+          return false if document.nil?
+
+          document.key?("objectClassName") || document.key?("ldhName") ||
+            document.key?("rdapConformance")
+        end
+
+        def parse(response)
+          document = response.json || {}
+          events = extract_events(document)
+          entities = extract_entities(document)
+          registrar = entities[:registrar] || {}
+
+          Record.new(
+            domain: document["unicodeName"] || document["ldhName"],
+            registry_id: document["handle"],
+            registrar: registrar[:organization] || registrar[:name],
+            registrar_iana_id: registrar[:iana_id],
+            registrant: entities.dig(:registrant, :organization) || entities.dig(:registrant, :name),
+            statuses: Array(document["status"]),
+            nameservers: extract_nameservers(document),
+            created_on: events[:created_on],
+            updated_on: events[:updated_on],
+            expires_on: events[:expires_on],
+            dnssec: extract_dnssec(document),
+            contacts: entities.except(:registrar),
+            fields: document,
+            source: name
+          )
+        end
+
+        private
+
+        def extract_events(document)
+          Array(document["events"]).each_with_object({}) do |event, dates|
+            next unless event.is_a?(Hash)
+
+            field = EVENTS[event["eventAction"].to_s.downcase]
+            next if field.nil?
+
+            dates[field] ||= parse_time(event["eventDate"])
+          end
+        end
+
+        def extract_nameservers(document)
+          Array(document["nameservers"]).filter_map do |nameserver|
+            next unless nameserver.is_a?(Hash)
+
+            nameserver["unicodeName"] || nameserver["ldhName"]
+          end
+        end
+
+        # +secureDNS.delegationSigned+ is the authoritative flag; report it in the
+        # same vocabulary the WHOIS parsers use so callers need not special-case RDAP.
+        def extract_dnssec(document)
+          secure = document["secureDNS"]
+          return nil unless secure.is_a?(Hash)
+
+          signed = secure["delegationSigned"]
+          return nil if signed.nil?
+
+          signed ? "signedDelegation" : "unsigned"
+        end
+
+        def extract_entities(document)
+          Array(document["entities"]).each_with_object({}) do |entity, contacts|
+            next unless entity.is_a?(Hash)
+
+            Array(entity["roles"]).each do |raw_role|
+              role = ROLES[raw_role.to_s.downcase]
+              next if role.nil?
+
+              contacts[role] ||= entity_details(entity)
+            end
+          end
+        end
+
+        def entity_details(entity)
+          card = parse_vcard(entity["vcardArray"])
+
+          {
+            handle: entity["handle"],
+            name: card[:fn],
+            organization: card[:org],
+            email: card[:email],
+            phone: card[:tel],
+            country: card[:country],
+            iana_id: public_id(entity, "IANA Registrar ID")
+          }.compact
+        end
+
+        # A jCard is +["vcard", [[name, params, type, value], ...]]+ (RFC 7095).
+        # Addresses carry a structured value whose seventh element is the country.
+        def parse_vcard(vcard_array)
+          entries = vcard_array.is_a?(Array) ? vcard_array[1] : nil
+          return {} unless entries.is_a?(Array)
+
+          entries.each_with_object({}) do |entry, card|
+            next unless entry.is_a?(Array) && entry.length >= 4
+
+            key = entry[0].to_s.downcase
+            field = VCARD_FIELDS[key]
+
+            if field
+              card[field] ||= field == :org ? flatten_value(entry[3]) : entry[3].to_s
+            elsif key == "adr"
+              card[:country] ||= country_from(entry[3])
+            end
+          end
+        end
+
+        def flatten_value(value)
+          value.is_a?(Array) ? value.flatten.compact.reject(&:empty?).first.to_s : value.to_s
+        end
+
+        def country_from(value)
+          return nil unless value.is_a?(Array)
+
+          country = value[6]
+          country.to_s.strip.empty? ? nil : country.to_s.strip
+        end
+
+        def public_id(entity, type)
+          Array(entity["publicIds"]).each do |public_id|
+            next unless public_id.is_a?(Hash)
+            return public_id["identifier"].to_s if public_id["type"].to_s.casecmp?(type)
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end