monovm-whois-ruby 1.0.0

data/lib/monovm/whois/availability/rule.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "verdict"
+require_relative "patterns"
+
+module MonoVM
+  module Whois
+    module Availability
+      # One link in the detection chain.
+      #
+      # A rule answers a single question about a response and either returns a
+      # {Verdict} — "I recognise this, here is the answer" — or +nil+, meaning
+      # "not mine, ask the next one". That is the whole contract, and it is what
+      # makes the chain extensible: a registry that invents new wording needs one
+      # more small object, not a change to {Analyzer}.
+      #
+      #   class MyRule < Availability::Rule
+      #     def call(context)
+      #       return nil unless context.lower.include?("my special wording")
+      #
+      #       registered(reason: "registry said so")
+      #     end
+      #   end
+      #
+      #   MonoVM::Whois.configure { |c| c.rules.prepend(MyRule.new) }
+      class Rule
+        # Identifier used in {Verdict#rule} and in the analyzer's trace.
+        # +ServerRefusal+ becomes +"server_refusal"+.
+        #
+        # An anonymous class has no +Module#name+, so a rule defined inline — which is
+        # exactly how a host application tries one out — falls back to its inspect
+        # form rather than crashing.
+        def name
+          @name ||= begin
+            base = self.class.name.to_s.split("::").last
+            base = self.class.inspect if base.nil? || base.empty?
+            base.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+          end
+        end
+
+        # @param context [Context]
+        # @return [Verdict, nil]
+        def call(context)
+          raise NotImplementedError, "#{self.class} must implement #call"
+        end
+
+        private
+
+        %i[available registered premium unknown].each do |status|
+          define_method(status) do |reason: nil, evidence: nil|
+            Verdict.public_send(status, rule: name, reason: reason, evidence: evidence)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rule_set.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "rule"
+require_relative "rules/server_refusal"
+require_relative "rules/wrong_registry"
+require_relative "rules/rdap_object"
+require_relative "rules/premium_name"
+require_relative "rules/explicit_unavailability"
+require_relative "rules/registration_fields"
+require_relative "rules/registry_marker"
+require_relative "rules/availability_keywords"
+require_relative "rules/no_match"
+require_relative "rules/tld_specific"
+require_relative "rules/status_field"
+require_relative "rules/recordless"
+
+module MonoVM
+  module Whois
+    module Availability
+      # The ordered chain of detection rules.
+      #
+      # Order is the whole design. Two invariants hold it together:
+      #
+      # 1. Rules that recognise a *non-answer* run first, so nothing that reaches the
+      #    permissive rules could have been a refusal or a wrong-server reply.
+      # 2. Every rule that concludes +:registered+ runs before every rule that
+      #    concludes +:available+, so when two signals conflict the safe one wins.
+      #    Selling a registered domain is a far worse failure than telling a customer
+      #    to check again.
+      #
+      # The set is mutable so a host application can add a rule for a registry that
+      # invents new wording, without forking the gem or waiting for a release.
+      class RuleSet
+        include Enumerable
+
+        # The order shipped with the gem.
+        def self.default
+          new([
+                Rules::ServerRefusal.new,          # non-answers first
+                Rules::WrongRegistry.new,
+                Rules::RdapObject.new,             # structured, authoritative
+                Rules::PremiumName.new,            # premium is not available
+                Rules::ExplicitUnavailability.new, # then everything meaning "registered"
+                Rules::RegistrationFields.new,
+                Rules::RegistryMarker.new,         # then everything meaning "available"
+                Rules::AvailabilityKeywords.new,
+                Rules::NoMatch.new,
+                Rules::TldSpecific.new,
+                Rules::StatusField.new,
+                Rules::Recordless.new              # opt-in per TLD
+              ])
+        end
+
+        def initialize(rules = [])
+          @rules = rules.dup
+        end
+
+        def each(&)
+          @rules.each(&)
+        end
+
+        def to_a
+          @rules.dup
+        end
+
+        def size
+          @rules.size
+        end
+
+        def names
+          @rules.map(&:name)
+        end
+
+        # Add a rule at the very front, ahead of even the refusal checks.
+        def prepend(rule)
+          @rules.unshift(rule)
+          self
+        end
+
+        # Add a rule at the very end, after the shipped fallbacks.
+        def append(rule)
+          @rules.push(rule)
+          self
+        end
+        alias << append
+
+        # Insert +rule+ immediately before the named rule, which is usually what you
+        # want: a registry-specific check belongs next to the generic one it refines.
+        #
+        # @param name [String, Symbol] an existing rule's {Rule#name}
+        # @raise [ArgumentError] when no rule has that name
+        def insert_before(name, rule)
+          @rules.insert(index_of!(name), rule)
+          self
+        end
+
+        def insert_after(name, rule)
+          @rules.insert(index_of!(name) + 1, rule)
+          self
+        end
+
+        # Drop a shipped rule, for a deployment that disagrees with one of them.
+        def remove(name)
+          @rules.delete_at(index_of!(name))
+          self
+        end
+
+        # Swap a rule's implementation, keeping its position.
+        def replace(name, rule)
+          @rules[index_of!(name)] = rule
+          self
+        end
+
+        def include?(name)
+          @rules.any? { |rule| rule.name == name.to_s }
+        end
+
+        def dup
+          self.class.new(@rules)
+        end
+
+        def inspect
+          "#<#{self.class.name} #{names.join(" -> ")}>"
+        end
+
+        private
+
+        def index_of!(name)
+          index = @rules.index { |rule| rule.name == name.to_s }
+          raise ArgumentError, "no rule named #{name.inspect}; have #{names.join(", ")}" if index.nil?
+
+          index
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/availability_keywords.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # Plain-language phrases that state a name is unregistered.
+        #
+        # The list spans several languages, because ccTLD registries answer in their
+        # own: +no se encontro el objeto+, +nicht vergeben+, +is vrij+. Matching is a
+        # substring search over the commentary-stripped response — the stripping is
+        # what keeps a phrase like "not found" in a registry's legal preamble from
+        # being read as an answer.
+        class AvailabilityKeywords < Rule
+          def call(context)
+            return nil if context.empty?
+
+            keyword = context.find_keyword(Patterns::AVAILABILITY_KEYWORDS)
+            return nil if keyword.nil?
+
+            available(
+              reason: "the response states the name is not registered",
+              evidence: keyword
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/explicit_unavailability.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # The response states that the name exists.
+        #
+        # Per-TLD wording is consulted first, because some registries use words that
+        # would be ambiguous elsewhere: DENIC's +Status: invalid+ means the name
+        # cannot be registered as spelled, and Nominet answers a registered +.uk+
+        # name with nothing more definitive than "Registered".
+        #
+        # Matching happens against the response with commentary stripped. Registries
+        # put conditional prose in their preamble ("if the domain is registered,
+        # contact the registrar"), and matching that would mark a free name as taken.
+        class ExplicitUnavailability < Rule
+          def call(context)
+            return nil if context.empty?
+
+            tld_patterns = Patterns::TLD_UNAVAILABILITY[context.tld]
+            if tld_patterns
+              matched = context.find(tld_patterns, source: :significant)
+              if matched
+                return registered(
+                  reason: "#{context.tld} registries report a registration this way",
+                  evidence: matched
+                )
+              end
+            end
+
+            matched = context.find(Patterns::UNAVAILABILITY, source: :significant)
+            return nil if matched.nil?
+
+            registered(reason: "the response states the name is registered", evidence: matched)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/no_match.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # The regexp form of the not-found phrases.
+        #
+        # Overlaps {AvailabilityKeywords} on purpose. That rule does a fast substring
+        # scan, which misses a registry that writes +No  match+ with two spaces or
+        # +not\tfound+ with a tab; these patterns are whitespace-tolerant and catch
+        # the rest. Cheap check first, thorough check second.
+        class NoMatch < Rule
+          def call(context)
+            return nil if context.empty?
+
+            matched = context.find(Patterns::NO_MATCH, source: :significant)
+            return nil if matched.nil?
+
+            available(
+              reason: "the response matched a not-found pattern",
+              evidence: matched
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/premium_name.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # The registry flagged the name as premium, reserved or otherwise withheld.
+        #
+        # A premium name is unregistered but not obtainable at standard price, and a
+        # reserved one is not obtainable at all. Both are distinct from "available",
+        # and a registrar showing an add-to-cart button for either has a support
+        # ticket coming.
+        #
+        # The marker comes from the TLD definition, since the wording is registry
+        # specific. This runs before the availability rules because those registries
+        # tend to phrase a premium answer as a near-miss of "not found".
+        class PremiumName < Rule
+          def call(context)
+            marker = context.definition&.premium_match
+            return nil if marker.nil? || context.empty?
+
+            return nil unless context.lower.include?(marker.downcase)
+
+            premium(
+              reason: "the registry marked this name as premium or reserved",
+              evidence: marker
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/rdap_object.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # Reads an RDAP response, which says outright whether the object exists.
+        #
+        # This is why the library prefers RDAP. Every other rule in the chain infers
+        # a verdict from prose that varies by registry, by year and sometimes by
+        # query. RDAP does not need inference: a registered domain is a JSON object
+        # with an +objectClassName+ of +"domain"+, and an unregistered one is an
+        # error document with +errorCode+ 404 (RFC 7480 §5.3, RFC 9083 §6). Both
+        # answers are definitive, so this rule sits above all the pattern matching.
+        class RdapObject < Rule
+          def call(context)
+            return nil unless context.rdap?
+
+            document = context.json
+
+            # An HTTP 404 is RDAP's "no such domain", whether or not it carried a body.
+            if document.nil?
+              return nil unless Patterns::RDAP_NOT_FOUND_CODES.include?(context.http_status)
+
+              return available(
+                reason: "RDAP answered HTTP 404: no such domain",
+                evidence: "HTTP #{context.http_status}"
+              )
+            end
+
+            verdict_for_error(document, context) || verdict_for_object(document)
+          end
+
+          private
+
+          def verdict_for_error(document, _context)
+            code = document["errorCode"]
+            return nil if code.nil?
+
+            code = code.to_i
+
+            if Patterns::RDAP_NOT_FOUND_CODES.include?(code)
+              return available(
+                reason: "RDAP errorCode 404: no such domain",
+                evidence: error_evidence(document, code)
+              )
+            end
+
+            # Any other error code is the server declining, not an answer: 429 for
+            # rate limiting, 403 for a blocked client, 400 for a query it disliked.
+            unknown(
+              reason: "RDAP returned errorCode #{code}",
+              evidence: error_evidence(document, code)
+            )
+          rescue TypeError
+            nil
+          end
+
+          def verdict_for_object(document)
+            return nil unless describes_domain?(document)
+
+            present = Patterns::RDAP_REGISTRATION_KEYS.count { |key| document.key?(key) }
+
+            # A conformant domain object always carries an ldhName plus at least
+            # something about its state; requiring two keys avoids treating a bare
+            # help or notice document as a registration.
+            return nil unless present >= 2
+
+            registered(
+              reason: "RDAP returned a domain object",
+              evidence: document["ldhName"] || document["handle"]
+            )
+          end
+
+          def describes_domain?(document)
+            object_class = document["objectClassName"].to_s.downcase
+            return true if object_class == "domain"
+
+            # Some registries omit objectClassName but are unmistakably describing a
+            # registration; rdapConformance plus an ldhName is enough.
+            document.key?("ldhName") && document.key?("rdapConformance")
+          end
+
+          def error_evidence(document, code)
+            title = document["title"] || Array(document["description"]).first
+            [code, title].compact.join(" ")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/recordless.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # Last resort: the server answered with its banner and nothing else.
+        #
+        # A few registries — NIC Monaco among them — reply to an unregistered name
+        # with no marker at all, just their header. For those, silence genuinely is
+        # the signal, and no other rule can help.
+        #
+        # Inferring availability from absence is unsound in general, so this rule is
+        # off unless a TLD definition sets +available_when_empty+, and even then it
+        # refuses to answer if the response looks like anything other than a clean
+        # empty reply: no registration fields, no refusal, no error or restriction
+        # notice. Opt-in per TLD rather than a global fallback is the difference
+        # between handling one registry's quirk and reporting every unreadable
+        # response as free to register.
+        class Recordless < Rule
+          # Below two registration fields the response is not a record. At two or more
+          # it is, however terse.
+          MAX_FIELDS = 2
+
+          def call(context)
+            return nil unless context.definition&.available_when_empty?
+            return nil if context.empty?
+            return nil if context.match?(Patterns::ERROR_OR_RESTRICTION, source: :significant)
+
+            fields = context.count(Patterns::REGISTRATION_FIELDS, source: :significant)
+            return nil if fields >= MAX_FIELDS
+
+            available(
+              reason: "#{context.tld} answers unregistered names with no record, " \
+                      "and this response carries none",
+              evidence: context.preview(80)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/registration_fields.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # The response is a record: it carries the fields only a registration has.
+        #
+        # Useful for the many registries that never say "registered" in so many
+        # words — they simply return the record, and the record's existence is the
+        # answer. Counting fields rather than looking for one is deliberate: a
+        # registrar name might appear in a preamble, but a registrar *and* a creation
+        # date *and* nameservers together are a registration.
+        class RegistrationFields < Rule
+          # Three independent fields. Two is reachable by a chatty error notice; four
+          # loses the GDPR-redacted records that only keep domain, registrar and
+          # status.
+          THRESHOLD = 3
+
+          def call(context)
+            return nil if context.empty?
+
+            found = context.count(Patterns::REGISTRATION_INDICATORS, source: :significant)
+            return nil if found < THRESHOLD
+
+            registered(
+              reason: "the response contains #{found} registration fields",
+              evidence: context.find(Patterns::REGISTRATION_INDICATORS, source: :significant)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/registry_marker.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # The exact string this registry emits for an unregistered name, taken from
+        # the TLD definition.
+        #
+        # This is the curated, high-confidence signal — +"No match for"+ for Verisign,
+        # +"Domain not found"+ for PIR — and the obvious design would check it first,
+        # before anything else.
+        #
+        # Here it runs *after* the rules that establish a registration, and that
+        # reordering fixes a real failure mode: when a TLD is mapped to the wrong
+        # server, or a registry starts returning a record that happens to contain the
+        # marker text, checking the marker first turns a registered domain into an
+        # available one. Letting a genuine record win first costs nothing, because a
+        # response cannot both be a record and be the registry's not-found message.
+        class RegistryMarker < Rule
+          def call(context)
+            marker = context.definition&.available_match
+            return nil if marker.nil? || context.empty?
+
+            return nil unless context.significant_lower.include?(marker.downcase)
+
+            available(
+              reason: "matched the not-found marker configured for #{context.tld}",
+              evidence: marker
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/server_refusal.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # The server answered, but declined to say anything about the domain.
+        #
+        # First in the chain, and that position is the point. Rate-limit notices,
+        # "your client is blocked" messages and "port 43 is retired, use RDAP"
+        # banners contain none of the wording that means "registered", so every
+        # later rule passes on them and the response eventually reaches whichever
+        # heuristic is loosest. In a permissive detector that heuristic answers
+        # "available", which means a rate-limited registry reports its entire zone
+        # as free to register.
+        #
+        # Deciding this first, and deciding it +:unknown+, is what makes the rest of
+        # the chain safe to be permissive.
+        class ServerRefusal < Rule
+          def call(context)
+            return nil if context.empty?
+
+            # An RDAP document says "I refuse" structurally — an HTTP 401/403/429,
+            # which the transport turns into an error, or an +errorCode+, which
+            # {RdapObject} reads. Its prose must not be scanned for refusal wording,
+            # because registries embed rate-limit *policy* in the Terms of Service
+            # notice attached to every answer: PIR's .org responses explain that a
+            # client sending "too many queries" will be throttled, and matching that
+            # reported every unregistered .org name as unknown.
+            return nil unless context.json.nil?
+
+            matched = context.find(Patterns::REFUSAL)
+            return nil if matched.nil?
+
+            unknown(
+              reason: "the server refused to answer the query",
+              evidence: matched
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/status_field.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # An explicit status field stating the name is free.
+        #
+        # Some detectors pair this check with a second inference: "fewer than two
+        # registration fields present" also counts as availability. That inference is
+        # unsound and is deliberately not reproduced. Every response that is not a
+        # record has fewer than two registration fields — a rate-limit notice, a
+        # blocked-client message, a legal preamble, a truncated read — so it converts
+        # any non-answer into "free to register".
+        #
+        # Genuine availability always carries a positive signal, and the keyword,
+        # not-found and per-TLD rules already look for it. The one case where silence
+        # really is the only signal is handled by {Recordless}, which requires an
+        # explicit per-TLD opt-in.
+        class StatusField < Rule
+          def call(context)
+            return nil if context.empty?
+
+            # An error or restriction notice can contain a status line while still
+            # describing something that exists.
+            return nil if context.match?(Patterns::ERROR_OR_RESTRICTION, source: :significant)
+
+            matched = context.find(Patterns::STATUS_AVAILABLE, source: :significant)
+            return nil if matched.nil?
+
+            available(
+              reason: "an explicit status field reports the name as available",
+              evidence: matched
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/availability/rules/tld_specific.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # Per-TLD availability wording.
+        #
+        # Runs late because several entries are single words — +.it+ answers a free
+        # name with little more than "available", +.ch+ with "we do not have an entry
+        # in our database matching your query". As a general rule those would be far
+        # too loose; scoped to one registry's output format they are reliable.
+        #
+        # By the time the chain gets here, every rule that could establish a
+        # registration has already declined, so a loose availability pattern can only
+        # fire on a response that carried no registration signal at all.
+        class TldSpecific < Rule
+          def call(context)
+            return nil if context.empty? || context.tld.nil?
+
+            patterns = Patterns::TLD_AVAILABILITY[context.tld]
+            return nil if patterns.nil?
+
+            matched = context.find(patterns, source: :significant)
+            return nil if matched.nil?
+
+            available(
+              reason: "matched an availability pattern specific to #{context.tld}",
+              evidence: matched
+            )
+          end
+        end
+      end
+    end
+  end
+end