monovm-whois-ruby 1.0.0

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module MonoVM
+  module Whois
+    module Availability
+      module Rules
+        # The server we reached does not serve this TLD.
+        #
+        # Two shapes of this exist. A WHOIS server may say so outright ("TLD not
+        # supported"), or — more dangerously — a TLD may be mapped to an address
+        # registry by mistake. RIPE, APNIC, ARIN and friends answer any domain query
+        # with +%ERROR:101: no entries found+, which reads as "no entries found" to a
+        # keyword scan and therefore as availability for every name under that TLD.
+        #
+        # Either way the response describes the server's capabilities, not the
+        # domain, so the only honest verdict is +:unknown+.
+        class WrongRegistry < Rule
+          def call(context)
+            return nil if context.empty?
+
+            # As with {ServerRefusal}: an RDAP document reports this structurally, and
+            # its Terms of Service prose is not evidence about the server's coverage.
+            return nil unless context.json.nil?
+
+            matched = context.find(Patterns::UNSUPPORTED)
+            if matched
+              return unknown(
+                reason: "the server does not serve #{context.tld || "this TLD"}",
+                evidence: matched
+              )
+            end
+
+            banner = context.find(Patterns::WRONG_REGISTRY_BANNERS)
+            return nil if banner.nil?
+
+            unknown(
+              reason: "reached an address registry, not the domain registry for " \
+                      "#{context.tld || "this TLD"}",
+              evidence: banner
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module MonoVM
+  module Whois
+    module Availability
+      # The outcome of analysing one response.
+      #
+      # This is the central design decision. With a boolean-only
+      # +isAvailable()+, "this domain is registered" and "the
+      # server would not tell me" collapse into the same +false+ — and, worse, a
+      # response that carries no verdict at all falls through the detector's
+      # heuristics and comes back +true+. A rate-limited registry then reports
+      # every registered domain as free to register.
+      #
+      # Here {#status} has four values and +:unknown+ is a real answer that is
+      # never promoted to +:available+. {#rule} and {#trace} record *why*, which
+      # is what makes a surprising classification debuggable.
+      class Verdict
+        STATUSES = %i[available registered premium unknown].freeze
+
+        attr_reader :status, :rule, :reason, :evidence, :trace
+
+        class << self
+          STATUSES.each do |status|
+            define_method(status) do |rule: nil, reason: nil, evidence: nil, trace: nil|
+              new(status: status, rule: rule, reason: reason, evidence: evidence, trace: trace)
+            end
+          end
+        end
+
+        # @param status [Symbol] one of {STATUSES}
+        # @param rule [String, nil] name of the rule that decided it
+        # @param reason [String, nil] human-readable justification
+        # @param evidence [String, nil] the matched text, trimmed for display
+        # @param trace [Array<Hash>, nil] every rule consulted, in order
+        def initialize(status:, rule: nil, reason: nil, evidence: nil, trace: nil)
+          raise ArgumentError, "unknown verdict status #{status.inspect}" unless STATUSES.include?(status)
+
+          @status = status
+          @rule = rule
+          @reason = reason
+          @evidence = evidence
+          @trace = (trace || []).freeze
+          freeze
+        end
+
+        def available?
+          status == :available
+        end
+
+        def registered?
+          status == :registered
+        end
+
+        def premium?
+          status == :premium
+        end
+
+        # True when no rule could reach a conclusion, or when the server refused
+        # to answer. Callers must treat this as "ask again later", never as free.
+        def unknown?
+          status == :unknown
+        end
+
+        # True when the verdict says something actionable about the domain.
+        def conclusive?
+          !unknown?
+        end
+
+        # Return a copy carrying +trace+. Rules build verdicts without knowing the
+        # trace; the analyzer attaches it once the chain finishes.
+        def with_trace(trace)
+          self.class.new(status: status, rule: rule, reason: reason, evidence: evidence, trace: trace)
+        end
+
+        def to_h
+          {
+            status: status,
+            rule: rule,
+            reason: reason,
+            evidence: evidence
+          }
+        end
+
+        def ==(other)
+          other.is_a?(Verdict) && other.status == status && other.rule == rule
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, status, rule].hash
+        end
+
+        def inspect
+          "#<#{self.class.name} #{status}#{" by #{rule}" if rule}>"
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/checker.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require_relative "client"
+require_relative "configuration"
+require_relative "domain_name"
+
+module MonoVM
+  module Whois
+    # Checks many domains, and expands a bare name across popular TLDs.
+    #
+    # Two jobs the single-domain {Client} deliberately does not do. Given +"monovm"+
+    # with no TLD it tries +.com+, +.net+, +.org+ and +.info+; given a list it works
+    # through it concurrently.
+    #
+    # Concurrency here is safe only because {Transport::Middleware::Throttle} sits
+    # underneath it: eight threads against a list of +.com+ names would otherwise send
+    # eight simultaneous queries to one Verisign host and get the caller's IP
+    # rate-limited, after which every remaining answer is a refusal. The throttle is
+    # per host, so a batch spanning many registries still runs genuinely in parallel.
+    #
+    #   MonoVM::Whois::Checker.whois("monovm.com")
+    #   # => {"monovm.com" => :registered}
+    #
+    #   MonoVM::Whois::Checker.whois(["monovm", "google.com"])
+    #   # => {"monovm.com" => :registered, "monovm.net" => :registered, ...}
+    class Checker
+      class << self
+        # @param domains [String, Enumerable<String>]
+        # @param options [Hash] +:popular_tlds+ (or +:popularTLDs+), +:concurrency+,
+        #   plus anything {Configuration} accepts
+        # @return [Hash{String => Symbol}] name => status
+        def whois(domains, options = {})
+          new(**build_options(options)).check(domains)
+        end
+
+        # As {.whois} but each value is the full {Result}.
+        #
+        # @return [Hash{String => Result}]
+        def lookup(domains, options = {})
+          new(**build_options(options)).check_detailed(domains)
+        end
+
+        private
+
+        # Accept the camelCase alias key alongside the Ruby one, and route
+        # everything else at the configuration.
+        def build_options(options)
+          options = options.to_h.dup
+          popular = options.delete(:popular_tlds) || options.delete(:popularTLDs)
+          concurrency = options.delete(:concurrency)
+
+          config = Configuration.new
+          options.each do |key, value|
+            setter = "#{key}="
+            raise ArgumentError, "unknown option #{key.inspect}" unless config.respond_to?(setter)
+
+            config.public_send(setter, value)
+          end
+
+          { config: config, popular_tlds: popular, concurrency: concurrency }.compact
+        end
+      end
+
+      attr_reader :client, :popular_tlds, :concurrency
+
+      def initialize(client: nil, config: nil, popular_tlds: nil, concurrency: nil)
+        @config = config || Configuration.new
+        @client = client || Client.new(config: @config)
+        @popular_tlds = normalise_tlds(popular_tlds || @config.popular_tlds)
+        @concurrency = (concurrency || @config.concurrency).to_i.clamp(1, 64)
+      end
+
+      # @return [Hash{String => Symbol}]
+      def check(domains)
+        check_detailed(domains).transform_values(&:status)
+      end
+
+      # @return [Hash{String => Result}]
+      def check_detailed(domains)
+        targets = expand(domains)
+        return {} if targets.empty?
+
+        results = run(targets)
+
+        # Return in the order asked, which is what a caller rendering a table needs.
+        targets.to_h { |name| [name.to_s, results[name.to_s]] }
+      end
+
+      private
+
+      def normalise_tlds(tlds)
+        list = tlds.is_a?(String) ? tlds.split(",") : Array(tlds)
+        normalised = list.filter_map do |tld|
+          cleaned = tld.to_s.strip.downcase.delete_prefix(".")
+          cleaned.empty? ? nil : ".#{cleaned}"
+        end
+
+        raise ArgumentError, "popular_tlds must not be empty" if normalised.empty?
+
+        normalised
+      end
+
+      # One input may become several names, and duplicates are looked up once.
+      def expand(domains)
+        inputs = domains.is_a?(String) ? [domains] : Array(domains)
+
+        inputs.flat_map { |input| candidates_for(input) }.uniq(&:to_s)
+      end
+
+      def candidates_for(input)
+        raise ArgumentError, "every domain must be a String, got #{input.class}" unless input.is_a?(String)
+
+        name = DomainName.parse(input)
+
+        # An unusable name is passed through untouched so the caller sees it reported
+        # as :invalid under the string they supplied. Expanding it across the popular
+        # TLDs first would turn one bad entry into four confusing ones.
+        return [name] unless name.valid?
+        return [name] unless name.bare?
+
+        popular_tlds.map { |tld| name.join(tld) }
+      end
+
+      def run(targets)
+        return sequential(targets) if concurrency == 1 || targets.length == 1
+
+        queue = Queue.new
+        targets.each { |name| queue << name }
+
+        results = {}
+        mutex = Mutex.new
+
+        workers = Array.new([concurrency, targets.length].min) do
+          Thread.new do
+            while (name = pop(queue))
+              result = safely(name) { client.lookup(name) }
+              mutex.synchronize { results[name.to_s] = result }
+            end
+          end
+        end
+
+        workers.each(&:join)
+        results
+      end
+
+      def sequential(targets)
+        targets.to_h { |name| [name.to_s, safely(name) { client.lookup(name) }] }
+      end
+
+      def pop(queue)
+        queue.pop(true)
+      rescue ThreadError
+        nil
+      end
+
+      # One unexpected failure must not lose the other 499 answers in a batch, and it
+      # must not be reported as availability either.
+      def safely(name)
+        yield
+      rescue StandardError => e
+        Result.unknown(name, reason: "lookup raised #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/monovm/whois/cli.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../whois"
+
+module MonoVM
+  module Whois
+    # The +monovm-whois+ command.
+    #
+    # Kept as a class taking explicit +stdout+/+stderr+ and returning an exit code
+    # rather than calling +exit+ itself, so the specs can run it in-process and assert
+    # on its output.
+    #
+    # Exit codes: 0 when every name got a real answer, 1 when any came back unknown or
+    # invalid, 2 for a usage error.
+    class CLI
+      EXIT_OK = 0
+      EXIT_INCONCLUSIVE = 1
+      EXIT_USAGE = 2
+
+      # Terminal colours, skipped when output is redirected.
+      COLOURS = {
+        available: "\e[32m",  # green
+        registered: "\e[31m", # red
+        premium: "\e[33m",    # yellow
+        unknown: "\e[35m",    # magenta
+        invalid: "\e[90m"     # grey
+      }.freeze
+      RESET = "\e[0m"
+
+      def self.run(argv, stdout: $stdout, stderr: $stderr)
+        new(stdout: stdout, stderr: stderr).run(argv)
+      end
+
+      def initialize(stdout: $stdout, stderr: $stderr)
+        @stdout = stdout
+        @stderr = stderr
+        @options = default_options
+      end
+
+      def run(argv)
+        domains = parser.parse(argv)
+
+        return print_help if @options[:help]
+        return print_version if @options[:version]
+        return print_tld_count if @options[:tld_count]
+        return usage_error("give at least one domain name") if domains.empty?
+
+        results = check(domains)
+        render(results)
+        exit_code(results)
+      rescue OptionParser::ParseError => e
+        usage_error(e.message)
+      rescue Error => e
+        @stderr.puts "monovm-whois: #{e.message}"
+        EXIT_INCONCLUSIVE
+      rescue Interrupt
+        @stderr.puts "monovm-whois: interrupted"
+        EXIT_INCONCLUSIVE
+      end
+
+      private
+
+      def default_options
+        {
+          format: :text,
+          details: false,
+          raw: false,
+          prefer: :rdap,
+          cache: true,
+          concurrency: nil,
+          timeout: nil,
+          popular_tlds: nil,
+          colour: nil
+        }
+      end
+
+      # Memoised: the option handlers close over @options, and building a second
+      # parser to print usage would be wasteful and easy to let drift.
+      def parser
+        @parser ||= OptionParser.new do |opts|
+          opts.banner = "Usage: monovm-whois DOMAIN [DOMAIN...] [options]"
+          opts.separator ""
+          opts.separator "Checks domain availability over RDAP and WHOIS."
+          opts.separator ""
+
+          opts.on("-j", "--json", "Emit JSON instead of a table") { @options[:format] = :json }
+          opts.on("-d", "--details", "Show which rule decided, and why") { @options[:details] = true }
+          opts.on("-r", "--raw", "Print the raw registry response") { @options[:raw] = true }
+
+          opts.on("--prefer PROTOCOL", %w[rdap whois],
+                  "Try rdap or whois first (default: rdap)") do |value|
+            @options[:prefer] = value.to_sym
+          end
+
+          opts.on("-t", "--timeout SECONDS", Float, "Per-request timeout") do |value|
+            @options[:timeout] = value
+          end
+
+          opts.on("-c", "--concurrency N", Integer, "Parallel lookups (default: 8)") do |value|
+            @options[:concurrency] = value
+          end
+
+          opts.on("--tlds LIST", "TLDs to try for a name with no TLD",
+                  "(default: .com,.net,.org,.info)") do |value|
+            @options[:popular_tlds] = value.split(",")
+          end
+
+          opts.on("--[no-]cache", "Cache responses in-process (default: on)") do |value|
+            @options[:cache] = value
+          end
+
+          opts.on("--[no-]color", "--[no-]colour", "Colourise the status column") do |value|
+            @options[:colour] = value
+          end
+
+          opts.on("--tld-count", "Print how many TLDs are supported, then exit") do
+            @options[:tld_count] = true
+          end
+
+          opts.on("-v", "--version", "Print the version, then exit") do
+            @options[:version] = true
+          end
+
+          opts.on("-h", "--help", "Print this message") { @options[:help] = true }
+        end
+      end
+
+      def print_help
+        @stdout.puts parser
+        EXIT_OK
+      end
+
+      def print_version
+        @stdout.puts "monovm-whois #{MonoVM::Whois::VERSION}"
+        EXIT_OK
+      end
+
+      def print_tld_count
+        registry = Configuration.new.server_registry
+        @stdout.puts "#{registry.size} TLDs supported"
+        EXIT_OK
+      end
+
+      def check(domains)
+        Checker.new(
+          config: build_config,
+          popular_tlds: @options[:popular_tlds],
+          concurrency: @options[:concurrency]
+        ).check_detailed(domains)
+      end
+
+      def build_config
+        config = Configuration.new
+        config.prefer = @options[:prefer]
+        config.cache = @options[:cache]
+
+        if @options[:timeout]
+          timeout = @options[:timeout]
+          config.socket_connect_timeout = timeout
+          config.socket_read_timeout = timeout
+          config.http_open_timeout = timeout
+          config.http_read_timeout = timeout
+        end
+
+        config
+      end
+
+      def render(results)
+        case @options[:format]
+        when :json then render_json(results)
+        else render_text(results)
+        end
+      end
+
+      def render_json(results)
+        payload = results.transform_values do |result|
+          entry = result.to_h
+          entry[:trace] = result.verdict&.trace if @options[:details]
+          entry[:raw] = result.whois_message if @options[:raw]
+          entry
+        end
+
+        @stdout.puts JSON.pretty_generate(payload)
+      end
+
+      def render_text(results)
+        width = results.keys.map(&:length).max.to_i
+
+        results.each do |name, result|
+          @stdout.puts "#{name.ljust(width)}  #{colourise(result.status)}"
+          next unless @options[:details]
+
+          @stdout.puts "#{" " * width}  decided by: #{result.verdict&.rule || "-"}"
+          @stdout.puts "#{" " * width}  reason:     #{result.reason}"
+          @stdout.puts "#{" " * width}  endpoint:   #{result.response&.endpoint || "-"}"
+          render_record(result, width)
+        end
+
+        render_raw(results) if @options[:raw]
+      end
+
+      def render_record(result, width)
+        record = result.record
+        return if record.nil? || record.empty?
+
+        pad = " " * width
+        @stdout.puts "#{pad}  registrar:  #{record.registrar}" if record.registrar
+        @stdout.puts "#{pad}  created:    #{record.created_on&.iso8601}" if record.created_on
+        @stdout.puts "#{pad}  expires:    #{record.expires_on&.iso8601}" if record.expires_on
+        return if record.nameservers.empty?
+
+        @stdout.puts "#{pad}  nameservers: #{record.nameservers.join(", ")}"
+      end
+
+      def render_raw(results)
+        results.each do |name, result|
+          @stdout.puts
+          @stdout.puts "=== #{name} ==="
+          @stdout.puts result.whois_message
+        end
+      end
+
+      def colourise(status)
+        return status.to_s unless colour?
+
+        "#{COLOURS.fetch(status, "")}#{status}#{RESET}"
+      end
+
+      def colour?
+        return @options[:colour] unless @options[:colour].nil?
+
+        @stdout.respond_to?(:tty?) && @stdout.tty?
+      end
+
+      # Anything not conclusively answered is worth a non-zero exit, so a shell script
+      # can tell "definitely free" from "could not find out".
+      def exit_code(results)
+        results.each_value.all?(&:conclusive?) ? EXIT_OK : EXIT_INCONCLUSIVE
+      end
+
+      def usage_error(message)
+        @stderr.puts "monovm-whois: #{message}"
+        @stderr.puts parser
+        EXIT_USAGE
+      end
+    end
+  end
+end