monovm-whois-ruby 1.0.0

data/lib/monovm/whois/result.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module MonoVM
+  module Whois
+    # What a lookup produced: the verdict, the parsed record, and the raw response
+    # that backs both.
+    #
+    # {#status} adds +:invalid+ to the four {Availability::Verdict} statuses, for
+    # names that never reached a server — malformed input, or a TLD with no known
+    # endpoint. That distinction matters to a caller building a UI: +:invalid+ is
+    # the user's problem to fix, +:unknown+ is ours to retry.
+    class Result
+      STATUSES = %i[available registered premium unknown invalid].freeze
+
+      attr_reader :domain, :sld, :tld, :status, :verdict, :record, :response, :error
+
+      class << self
+        # A name that could not be looked up at all.
+        def invalid(domain, reason:, sld: nil, tld: nil)
+          new(domain: domain, status: :invalid, sld: sld, tld: tld, error: reason)
+        end
+
+        # A lookup that reached a server but produced no verdict.
+        def unknown(domain, reason:, sld: nil, tld: nil, response: nil)
+          new(
+            domain: domain,
+            status: :unknown,
+            sld: sld,
+            tld: tld,
+            response: response,
+            error: reason,
+            verdict: Availability::Verdict.unknown(reason: reason)
+          )
+        end
+      end
+
+      def initialize(domain:, status:, sld: nil, tld: nil, verdict: nil, record: nil,
+                     response: nil, error: nil)
+        raise ArgumentError, "unknown result status #{status.inspect}" unless STATUSES.include?(status)
+
+        @domain = domain
+        @status = status
+        @sld = sld
+        @tld = tld
+        @verdict = verdict
+        @record = record
+        @response = response
+        @error = error
+        freeze
+      end
+
+      def available?
+        status == :available
+      end
+
+      def registered?
+        status == :registered
+      end
+
+      def premium?
+        status == :premium
+      end
+
+      def unknown?
+        status == :unknown
+      end
+
+      def invalid?
+        status == :invalid
+      end
+
+      # True when the lookup produced an actionable answer about the domain.
+      def conclusive?
+        available? || registered? || premium?
+      end
+
+      # The name as a string, in its Unicode form.
+      def name
+        domain.to_s
+      end
+
+      # The raw text the registry sent, or the explanatory message when no server
+      # was reached. Also aliased as +getWhoisMessage+ on {WhoisHandler}.
+      def whois_message
+        return response.text if response
+
+        error.to_s
+      end
+      alias message whois_message
+
+      # Why the verdict came out this way, for logging and bug reports.
+      def reason
+        verdict&.reason || error
+      end
+
+      def to_h
+        {
+          domain: name,
+          sld: sld,
+          tld: tld,
+          status: status,
+          reason: reason,
+          rule: verdict&.rule,
+          record: record&.to_h,
+          response: response&.to_h
+        }.compact
+      end
+
+      def inspect
+        "#<#{self.class.name} #{name.inspect} #{status}>"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../response"
+require_relative "../errors"
+
+module MonoVM
+  module Whois
+    module Transport
+      # The one interface every transport and every middleware implements.
+      #
+      #   fetch(query:, endpoint:) -> Response
+      #
+      # Two implementations exist for two protocols ({WhoisSocket}, {RdapHttp}), and
+      # the middlewares in {Middleware} implement the same method so they can wrap
+      # either one. Because the whole surface is a single method, the specs inject a
+      # lambda-backed fake and the entire suite runs without a network.
+      #
+      # A transport decides nothing about availability. It returns what the server
+      # said, or raises: {ConnectionError} when the server was unreachable,
+      # {TimeoutError} when it was too slow, {ServerRefusedError} when it answered
+      # but declined to give a verdict, {EmptyResponseError} when it said nothing.
+      # That separation is what stops a network failure from being mistaken for an
+      # unregistered domain.
+      class Base
+        # @param query [String] the name to ask about, already in wire form
+        # @param endpoint [Endpoint] where to ask
+        # @return [Response]
+        def fetch(query:, endpoint:)
+          raise NotImplementedError, "#{self.class} must implement #fetch"
+        end
+
+        # True when this transport can serve +endpoint+.
+        #
+        # @param endpoint [Endpoint]
+        def supports?(endpoint)
+          raise NotImplementedError, "#{self.class} must implement #supports?"
+        end
+
+        private
+
+        # Wall-clock seconds for one exchange, recorded on the {Response} so callers
+        # can see which registry is slow without instrumenting the caller.
+        def measure
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = yield
+          [result, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started]
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/transport/factory.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "whois_socket"
+require_relative "rdap_http"
+
+module MonoVM
+  module Whois
+    module Transport
+      # Chooses a transport for an endpoint.
+      #
+      # {Client} asks for "something that can fetch this endpoint" and gets it, so
+      # adding a protocol means registering a transport here and nowhere else. The
+      # factory also owns the middleware wrapping, which is why every transport it
+      # hands out already caches, throttles and retries consistently — those are
+      # decisions about the whole system, not about one protocol.
+      class Factory
+        attr_reader :transports, :middleware
+
+        # @param transports [Array<Base>] candidates, asked in order via #supports?
+        # @param middleware [Array<#call>] each receives a transport and returns a
+        #   wrapped transport. Applied outermost-last, so the array reads in the
+        #   order requests travel through it.
+        def initialize(transports: nil, middleware: [])
+          @transports = transports || [WhoisSocket.new, RdapHttp.new]
+          @middleware = middleware
+          @wrapped = {}
+          @mutex = Mutex.new
+        end
+
+        # @param endpoint [Endpoint]
+        # @return [Base] a transport that can serve +endpoint+, already wrapped
+        # @raise [Error] when nothing registered can serve it
+        def for(endpoint)
+          transport = transports.find { |candidate| candidate.supports?(endpoint) }
+          raise Error, "no transport can serve #{endpoint}" if transport.nil?
+
+          # Middleware holds per-host state (throttle clocks, cache entries), so each
+          # transport must be wrapped exactly once and shared, not re-wrapped per call.
+          @wrapped[transport] || @mutex.synchronize { @wrapped[transport] ||= wrap(transport) }
+        end
+
+        private
+
+        def wrap(transport)
+          middleware.reverse.reduce(transport) { |inner, layer| layer.call(inner) }
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/transport/middleware/base.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module MonoVM
+  module Whois
+    module Transport
+      # Cross-cutting behaviour, wrapped around a transport rather than built into it.
+      #
+      # Caching, throttling and retrying are decisions about how a whole system
+      # talks to registries, not about how RDAP or port 43 works. Keeping them here
+      # means {WhoisSocket} and {RdapHttp} stay small enough to read, and a caller
+      # who wants a bare transport for one call can have one.
+      module Middleware
+        # Wraps another transport and forwards to it. Because it implements the same
+        # {Transport::Base} interface, layers compose in any order and nothing
+        # downstream can tell it is talking to a decorator.
+        class Base < Transport::Base
+          attr_reader :app
+
+          class << self
+            # A lambda suitable for {Factory}'s +middleware:+ list.
+            #
+            #   Factory.new(middleware: [Middleware::Cache.builder(ttl: 300)])
+            def builder(**options)
+              ->(app) { new(app, **options) }
+            end
+          end
+
+          def initialize(app)
+            @app = app
+            super()
+          end
+
+          def fetch(query:, endpoint:)
+            app.fetch(query: query, endpoint: endpoint)
+          end
+
+          def supports?(endpoint)
+            app.supports?(endpoint)
+          end
+
+          # Reach the real transport through any stack of decorators.
+          def unwrap
+            app.is_a?(Base) ? app.unwrap : app
+          end
+
+          def inspect
+            "#<#{self.class.name} -> #{app.inspect}>"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/transport/middleware/cache.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module MonoVM
+  module Whois
+    module Transport
+      module Middleware
+        # Remembers responses for a short while.
+        #
+        # Registries rate-limit, and a bulk check of a list that happens to contain
+        # the same name twice should not pay for it twice. The TTL is deliberately
+        # short by default: registration data changes, and a stale "available" is
+        # the expensive kind of wrong.
+        #
+        # Only successful responses are cached. A failure is never remembered — a
+        # transient timeout would otherwise poison every later lookup of that name.
+        class Cache < Middleware::Base
+          DEFAULT_TTL = 300.0
+          DEFAULT_MAX_ENTRIES = 1_000
+
+          attr_reader :ttl, :max_entries
+
+          # @param ttl [Float] seconds an entry stays fresh
+          # @param max_entries [Integer] cap on retained entries; oldest evicted first
+          # @param clock [#call] monotonic seconds, injectable so specs need no sleeps
+          def initialize(app, ttl: DEFAULT_TTL, max_entries: DEFAULT_MAX_ENTRIES, clock: nil)
+            @ttl = ttl
+            @max_entries = max_entries
+            @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+            @entries = {}
+            @mutex = Mutex.new
+            super(app)
+          end
+
+          def fetch(query:, endpoint:)
+            key = [endpoint.uri, query]
+
+            cached = read(key)
+            return cached if cached
+
+            response = app.fetch(query: query, endpoint: endpoint)
+            write(key, response)
+            response
+          end
+
+          # @return [Integer] how many fresh entries are held
+          def size
+            @mutex.synchronize { @entries.size }
+          end
+
+          def clear
+            @mutex.synchronize { @entries.clear }
+            self
+          end
+
+          private
+
+          def read(key)
+            @mutex.synchronize do
+              entry = @entries[key]
+              next nil if entry.nil?
+
+              if expired?(entry)
+                @entries.delete(key)
+                next nil
+              end
+
+              # Ruby hashes keep insertion order, so re-inserting makes this the
+              # newest entry and keeps eviction least-recently-used.
+              @entries.delete(key)
+              @entries[key] = entry
+              entry[:response]
+            end
+          end
+
+          def write(key, response)
+            @mutex.synchronize do
+              @entries.delete(key)
+              @entries[key] = { response: response, stored_at: @clock.call }
+              @entries.shift while @entries.size > max_entries
+            end
+          end
+
+          def expired?(entry)
+            @clock.call - entry[:stored_at] > ttl
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/transport/middleware/instrumentation.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module MonoVM
+  module Whois
+    module Transport
+      module Middleware
+        # Reports every exchange to a subscriber.
+        #
+        # A registrar running this at volume needs to know which registries are slow
+        # and which are refusing, and that is the host application's concern, not
+        # this library's. So nothing is logged here — an event is handed to whatever
+        # was injected, and the caller decides whether it becomes a log line, a
+        # StatsD counter or nothing at all.
+        class Instrumentation < Middleware::Base
+          # @param subscriber [#call] receives one Hash per exchange
+          def initialize(app, subscriber:)
+            @subscriber = subscriber
+            super(app)
+          end
+
+          def fetch(query:, endpoint:)
+            started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+            begin
+              response = app.fetch(query: query, endpoint: endpoint)
+            rescue StandardError => e
+              publish(
+                query: query,
+                endpoint: endpoint,
+                outcome: :error,
+                error: e.class.name,
+                message: e.message,
+                elapsed: Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+              )
+              raise
+            end
+
+            publish(
+              query: query,
+              endpoint: endpoint,
+              outcome: :ok,
+              status: response.status,
+              bytes: response.body.length,
+              elapsed: Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+            )
+            response
+          end
+
+          private
+
+          def publish(event)
+            @subscriber.call(event.merge(endpoint: event[:endpoint].to_s, host: event[:endpoint].host))
+          rescue StandardError
+            # A broken metrics pipeline must never take a lookup down with it.
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/transport/middleware/retry.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../../errors"
+
+module MonoVM
+  module Whois
+    module Transport
+      module Middleware
+        # Retries failures that are plausibly transient.
+        #
+        # Only {ConnectionError} and {TimeoutError} qualify: a dropped TCP
+        # connection or a slow registry is worth one more attempt. A
+        # {ServerRefusedError} is not retried, and that restraint is the point — a
+        # refusal usually *is* a rate limit, so hammering it makes the block worse
+        # and delays every other lookup in the batch behind the backoff.
+        class Retry < Middleware::Base
+          DEFAULT_ATTEMPTS = 2
+          DEFAULT_BACKOFF = 0.5
+
+          RETRIABLE = [ConnectionError, TimeoutError].freeze
+
+          attr_reader :attempts, :backoff
+
+          # @param attempts [Integer] total tries, so 2 means one retry
+          # @param backoff [Float] seconds before the first retry, doubling after
+          # @param sleeper [#call] injectable so specs do not actually wait
+          def initialize(app, attempts: DEFAULT_ATTEMPTS, backoff: DEFAULT_BACKOFF, sleeper: nil)
+            @attempts = [attempts.to_i, 1].max
+            @backoff = backoff
+            @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+            super(app)
+          end
+
+          def fetch(query:, endpoint:)
+            attempt = 0
+            delay = backoff
+
+            loop do
+              attempt += 1
+
+              begin
+                return app.fetch(query: query, endpoint: endpoint)
+              rescue *RETRIABLE
+                raise if attempt >= attempts
+
+                @sleeper.call(delay)
+                delay *= 2
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/transport/middleware/throttle.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module MonoVM
+  module Whois
+    module Transport
+      module Middleware
+        # Keeps a minimum gap between consecutive queries to the same host.
+        #
+        # This is the politeness layer, and it is what makes concurrent bulk checks
+        # safe. Registries publish query-rate limits and enforce them by blocking
+        # clients; without a throttle, pointing eight threads at a list of +.com+
+        # names sends eight simultaneous queries to one Verisign host and gets the
+        # caller's IP throttled — after which every response is a refusal and no
+        # domain can be checked at all.
+        #
+        # The gap is per host, not global, so a batch spanning many TLDs still runs
+        # in parallel across them.
+        class Throttle < Middleware::Base
+          DEFAULT_INTERVAL = 0.5
+
+          attr_reader :interval
+
+          # @param interval [Float] minimum seconds between queries to one host
+          # @param clock [#call] monotonic seconds, injectable for specs
+          # @param sleeper [#call] receives seconds to wait, injectable for specs
+          def initialize(app, interval: DEFAULT_INTERVAL, clock: nil, sleeper: nil)
+            @interval = interval
+            @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+            @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+            @last_seen = {}
+            @mutex = Mutex.new
+            super(app)
+          end
+
+          def fetch(query:, endpoint:)
+            wait_for(endpoint.host)
+            app.fetch(query: query, endpoint: endpoint)
+          end
+
+          private
+
+          # Reserve this host's next slot while holding the lock, then sleep outside
+          # it. Sleeping under the mutex would serialise every host behind whichever
+          # one happened to be waiting.
+          def wait_for(host)
+            delay = @mutex.synchronize do
+              now = @clock.call
+              earliest = @last_seen[host]
+              slot = earliest.nil? ? now : [now, earliest + interval].max
+              @last_seen[host] = slot
+              slot - now
+            end
+
+            @sleeper.call(delay) if delay.positive?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/transport/rdap_http.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+require_relative "base"
+require_relative "../version"
+
+module MonoVM
+  module Whois
+    module Transport
+      # RDAP over HTTPS (RFC 7480-7483).
+      #
+      # RDAP is the reason this library can be confident where a WHOIS-only one has
+      # to guess. A registered domain comes back as JSON with an +objectClassName+;
+      # an unregistered one comes back as HTTP 404 with an +errorCode+ of 404. Both
+      # are answers, so both are returned as a {Response} for the rules to read.
+      #
+      # What is *not* an answer gets raised instead: 401/403/405/406/429 mean the
+      # server refused us, and 5xx means it broke. Handing those bodies back would
+      # let an error page be pattern-matched into "available".
+      class RdapHttp < Base
+        DEFAULT_OPEN_TIMEOUT = 10.0
+        DEFAULT_READ_TIMEOUT = 30.0
+        MAX_REDIRECTS = 3
+
+        # 404 carries the "no such domain" answer, so it is deliberately absent.
+        REFUSAL_STATUSES = [401, 403, 405, 406, 429].freeze
+
+        ACCEPT = "application/rdap+json, application/json;q=0.9, */*;q=0.1"
+
+        attr_reader :open_timeout, :read_timeout, :verify_ssl, :user_agent
+
+        # @param verify_ssl [Boolean] verify TLS certificates. Defaults to true.
+        #   A handful of registry endpoints do serve broken chains; those
+        #   deployments can opt out explicitly rather than everyone losing the
+        #   guarantee silently.
+        def initialize(open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
+                       verify_ssl: true, user_agent: nil)
+          @open_timeout = open_timeout
+          @read_timeout = read_timeout
+          @verify_ssl = verify_ssl
+          @user_agent = user_agent ||
+                        "monovm-whois-ruby/#{MonoVM::Whois::VERSION} (+https://github.com/monovm/whois-ruby)"
+          super()
+        end
+
+        def supports?(endpoint)
+          endpoint.http?
+        end
+
+        # @return [Response]
+        # @raise [ConnectionError, TimeoutError, ServerRefusedError, EmptyResponseError]
+        def fetch(query:, endpoint:)
+          url = URI.parse(endpoint.url_for(query))
+          (response, elapsed) = measure { request(url, endpoint) }
+
+          Response.new(
+            body: response.body.to_s,
+            endpoint: endpoint,
+            query: query,
+            status: Integer(response.code),
+            elapsed: elapsed
+          )
+        rescue URI::InvalidURIError => e
+          raise ConnectionError, "cannot build an RDAP URL for #{query}: #{e.message}"
+        end
+
+        private
+
+        def request(url, endpoint, redirects_left = MAX_REDIRECTS)
+          response = perform(url, endpoint)
+
+          # RDAP registries do redirect: a registry may hand a name off to the
+          # registrar's own server, and the answer is at the new location.
+          if redirect?(response) && redirects_left.positive?
+            location = response["location"]
+            return request(URI.join(url, location), endpoint, redirects_left - 1) if location
+          end
+
+          verify_answerable!(response, endpoint)
+          response
+        end
+
+        def perform(url, endpoint)
+          http = build_http(url)
+          request = Net::HTTP::Get.new(url)
+          request["Accept"] = ACCEPT
+          request["User-Agent"] = user_agent
+
+          http.start { |connection| connection.request(request) }
+        rescue Net::OpenTimeout, Net::ReadTimeout => e
+          raise TimeoutError, "#{endpoint.host} timed out after #{timeout_for(e)}s (#{e.class})"
+        rescue OpenSSL::SSL::SSLError => e
+          raise ConnectionError, "TLS handshake with #{endpoint.host} failed: #{e.message}"
+        rescue SocketError, SystemCallError, Net::HTTPBadResponse, Net::ProtocolError, IOError => e
+          raise ConnectionError, "cannot reach #{endpoint.host}: #{e.message}"
+        end
+
+        def build_http(url)
+          http = Net::HTTP.new(url.host, url.port)
+          http.use_ssl = url.scheme == "https"
+          http.open_timeout = open_timeout
+          http.read_timeout = read_timeout
+
+          http.verify_mode = OpenSSL::SSL::VERIFY_NONE unless verify_ssl
+
+          http
+        end
+
+        def redirect?(response)
+          response.is_a?(Net::HTTPRedirection)
+        end
+
+        # Separate "the server answered the question" from "the server declined".
+        def verify_answerable!(response, endpoint)
+          status = Integer(response.code)
+
+          if REFUSAL_STATUSES.include?(status)
+            raise ServerRefusedError.new(
+              "#{endpoint.host} refused the query with HTTP #{status} #{response.message}",
+              endpoint: endpoint
+            )
+          end
+
+          if status >= 500
+            raise ServerRefusedError.new(
+              "#{endpoint.host} failed with HTTP #{status} #{response.message}",
+              endpoint: endpoint
+            )
+          end
+
+          # A 404 with no body is still an answer in RDAP terms, but an empty 200 is
+          # not: there is nothing in it to classify either way.
+          return unless status == 200 && response.body.to_s.strip.empty?
+
+          raise EmptyResponseError, "#{endpoint.host} returned an empty 200 for the query"
+        end
+
+        def timeout_for(error)
+          error.is_a?(Net::OpenTimeout) ? open_timeout : read_timeout
+        end
+      end
+    end
+  end
+end