monovm-whois-ruby 1.0.0

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "base"
+
+module MonoVM
+  module Whois
+    module Transport
+      # WHOIS over TCP port 43 (RFC 3912).
+      #
+      # The protocol is as thin as protocols get: connect, send the query and a
+      # CRLF, read until the server closes. What needs care is everything around
+      # that — a registry that accepts the connection and then never answers, one
+      # that sends half a record and hangs up, one that replies in Latin-1.
+      class WhoisSocket < Base
+        DEFAULT_CONNECT_TIMEOUT = 10.0
+        DEFAULT_READ_TIMEOUT = 15.0
+        CHUNK_SIZE = 16_384
+
+        # Registries that answer in Latin-1. Trying UTF-8 first and falling back
+        # keeps accented registrant names readable rather than replacing them with
+        # U+FFFD.
+        FALLBACK_ENCODING = Encoding::ISO_8859_1
+
+        # IO::TimeoutError only exists from Ruby 3.2. Naming it directly in a rescue
+        # clause would raise NameError on 3.1 at the moment an exception occurred —
+        # turning a timeout into a crash — so the list is built once, here.
+        CONNECT_TIMEOUTS = [
+          Errno::ETIMEDOUT,
+          (IO::TimeoutError if defined?(IO::TimeoutError))
+        ].compact.freeze
+
+        attr_reader :connect_timeout, :read_timeout
+
+        def initialize(connect_timeout: DEFAULT_CONNECT_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+          @connect_timeout = connect_timeout
+          @read_timeout = read_timeout
+          super()
+        end
+
+        def supports?(endpoint)
+          endpoint.socket?
+        end
+
+        # @return [Response]
+        # @raise [ConnectionError, TimeoutError, EmptyResponseError]
+        def fetch(query:, endpoint:)
+          body, elapsed = measure { exchange(query, endpoint) }
+
+          if body.strip.empty?
+            raise EmptyResponseError,
+                  "#{endpoint.host} closed the connection without answering for #{query}"
+          end
+
+          Response.new(body: body, endpoint: endpoint, query: query, elapsed: elapsed)
+        end
+
+        private
+
+        def exchange(query, endpoint)
+          socket = connect(endpoint)
+
+          begin
+            socket.write("#{query}\r\n")
+            read_all(socket, endpoint)
+          ensure
+            begin
+              socket.close
+            rescue IOError, SystemCallError
+              # Already closed by the peer; nothing to salvage.
+            end
+          end
+        end
+
+        def connect(endpoint)
+          Socket.tcp(endpoint.host, endpoint.port, connect_timeout: connect_timeout)
+        rescue *CONNECT_TIMEOUTS => e
+          raise TimeoutError, "timed out connecting to #{endpoint.host}:#{endpoint.port} (#{e.class})"
+        rescue SocketError, SystemCallError => e
+          raise ConnectionError, "cannot reach #{endpoint.host}:#{endpoint.port}: #{e.message}"
+        end
+
+        # Read until the peer closes, bounded by a single deadline for the whole
+        # response rather than per chunk — a server that dribbles one byte per
+        # second should not be able to hold the caller indefinitely.
+        def read_all(socket, endpoint)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + read_timeout
+          chunks = []
+
+          loop do
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            return partial(chunks, endpoint, "read timed out", TimeoutError) if remaining <= 0
+
+            unless socket.wait_readable(remaining)
+              return partial(chunks, endpoint, "read timed out",
+                             TimeoutError)
+            end
+
+            begin
+              chunks << socket.readpartial(CHUNK_SIZE)
+            rescue EOFError
+              break
+            rescue SystemCallError => e
+              return partial(chunks, endpoint, e.message, ConnectionError)
+            end
+          end
+
+          decode(chunks.join)
+        end
+
+        # A truncated record still classifies correctly far more often than not, so
+        # whatever arrived is kept. Nothing at all is a failure, not a verdict.
+        def partial(chunks, endpoint, reason, error_class)
+          raise error_class, "#{endpoint.host}:#{endpoint.port} #{reason}" if chunks.empty?
+
+          decode(chunks.join)
+        end
+
+        def decode(raw)
+          text = raw.dup.force_encoding(Encoding::UTF_8)
+          return text if text.valid_encoding?
+
+          raw.dup.force_encoding(FALLBACK_ENCODING).encode(Encoding::UTF_8)
+        rescue EncodingError
+          raw.dup.force_encoding(Encoding::UTF_8).scrub("")
+        end
+      end
+    end
+  end
+end

data/lib/monovm/whois/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module MonoVM
+  module Whois
+    VERSION = "1.0.0"
+  end
+end

data/lib/monovm/whois/whois_handler.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "client"
+
+module MonoVM
+  module Whois
+    # A single-domain handler that wraps one lookup in an object.
+    #
+    # Exists so that code written against camelCase WHOIS APIs reads the same way
+    # here — the camelCase method names are aliased at the bottom.
+    #
+    #   handler = MonoVM::Whois::WhoisHandler.whois("monovm.com")
+    #   handler.available?     # => false
+    #   handler.whois_message  # => the raw registry response
+    #   handler.record.expires_on
+    #
+    # One deliberate difference from boolean-style WHOIS APIs: there, an
+    # +isAvailable()+ returns false both for a registered domain and for a
+    # lookup that failed, and a permissive detector reports a rate-limited or
+    # unreachable server as *available*. Here {#available?} is true only when availability was
+    # positively established, and {#unknown?} exists to say "we could not find out".
+    # Code that branches on +available?+ alone is safe; code that treats
+    # +!available?+ as "registered" should ask {#registered?} instead.
+    class WhoisHandler
+      attr_reader :domain, :result
+
+      class << self
+        # @param domain [String]
+        # @param options [Hash] anything {Configuration} accepts
+        # @return [WhoisHandler]
+        def whois(domain, **options)
+          new(domain, **options)
+        end
+      end
+
+      def initialize(domain, client: nil, **options)
+        @domain = domain
+        @client = client || build_client(options)
+        @result = @client.lookup(domain)
+      end
+
+      # @return [String] the TLD, with its leading dot, or "" when none was resolved
+      def tld
+        result.tld.to_s
+      end
+
+      # @return [String] the second-level label, or "" when none was resolved
+      def sld
+        result.sld.to_s
+      end
+
+      # True only when the response positively established that the name is free.
+      def available?
+        result.available?
+      end
+
+      # True when the name exists. Distinct from +!available?+, which is also true
+      # when the lookup failed.
+      def registered?
+        result.registered?
+      end
+
+      # True when the registry flagged the name as premium or reserved: unregistered,
+      # but not obtainable at standard price.
+      def premium?
+        result.premium?
+      end
+
+      # True when no verdict could be reached — a refusal, a timeout, an unreadable
+      # response. Ask again later; do not treat as free.
+      def unknown?
+        result.unknown?
+      end
+
+      # True when the domain was well-formed and its TLD is one we can look up.
+      def valid?
+        !result.invalid?
+      end
+
+      # The raw registry response, or the explanatory message when none was obtained.
+      def whois_message
+        result.whois_message
+      end
+
+      # @return [Parser::Record, nil]
+      def record
+        result.record
+      end
+
+      # @return [Symbol] :available, :registered, :premium, :unknown or :invalid
+      def status
+        result.status
+      end
+
+      # Which rule decided, what it matched, and what every other rule said —
+      # the actual decision path rather than a fixed set of boolean flags.
+      #
+      # @return [Hash]
+      def availability_details
+        {
+          domain: result.name,
+          tld: result.tld,
+          sld: result.sld,
+          status: result.status,
+          decided_by: result.verdict&.rule,
+          reason: result.reason,
+          evidence: result.verdict&.evidence,
+          trace: result.verdict&.trace || [],
+          endpoint: result.response&.endpoint&.to_s,
+          response_length: result.response&.body&.length || 0,
+          response_preview: preview
+        }
+      end
+
+      def to_h
+        result.to_h
+      end
+
+      def inspect
+        "#<#{self.class.name} #{result.name.inspect} #{status}>"
+      end
+
+      # ------------------------------------------------------------------
+      # camelCase aliases, for callers coming from camelCase WHOIS APIs
+      # ------------------------------------------------------------------
+
+      alias isAvailable available?
+      alias isPremium premium?
+      alias isValid valid?
+      alias getTld tld
+      alias getSld sld
+      alias getWhoisMessage whois_message
+      alias getAvailabilityDetails availability_details
+
+      private
+
+      def build_client(options)
+        return Client.new if options.empty?
+
+        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
+
+        Client.new(config: config)
+      end
+
+      def preview(limit = 200)
+        text = whois_message.to_s.strip.gsub(/\s+/, " ")
+        text.length > limit ? "#{text[0, limit]}..." : text
+      end
+    end
+  end
+end

data/lib/monovm/whois.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "whois/version"
+require_relative "whois/errors"
+require_relative "whois/paths"
+require_relative "whois/punycode"
+require_relative "whois/domain_name"
+require_relative "whois/endpoint"
+require_relative "whois/response"
+require_relative "whois/availability/verdict"
+require_relative "whois/result"
+require_relative "whois/registry/server_registry"
+require_relative "whois/transport/factory"
+require_relative "whois/availability/analyzer"
+require_relative "whois/parser/selector"
+require_relative "whois/configuration"
+require_relative "whois/referral/follower"
+require_relative "whois/client"
+require_relative "whois/checker"
+require_relative "whois/whois_handler"
+
+module MonoVM
+  # Domain WHOIS and RDAP lookups.
+  #
+  # The short way in:
+  #
+  #   MonoVM::Whois.available?("monovm.com")   # => false
+  #   MonoVM::Whois.lookup("monovm.com")       # => #<Result "monovm.com" registered>
+  #   MonoVM::Whois.whois(["monovm", "bing.com"])
+  #
+  # Settings are global unless overridden per call:
+  #
+  #   MonoVM::Whois.configure do |config|
+  #     config.prefer = :whois          # port 43 before RDAP
+  #     config.throttle_interval = 1.0  # be gentler with registries
+  #     config.instrumentation = ->(event) { Rails.logger.info(event) }
+  #   end
+  module Whois
+    class << self
+      # The global configuration. Mutating it affects the shared {client}.
+      def config
+        @config ||= Configuration.new
+      end
+
+      # Yields {config} for editing, then discards the cached client so the next
+      # lookup picks the changes up.
+      #
+      # @yieldparam config [Configuration]
+      def configure
+        yield config if block_given?
+        reset_client!
+        config
+      end
+
+      # Throw away the global configuration and client. Mainly for tests.
+      def reset!
+        @config = nil
+        reset_client!
+        self
+      end
+
+      # The shared client. Built once, because it owns the definition tables and the
+      # caches and throttle clocks that make repeated lookups cheap and polite.
+      def client
+        @client || mutex.synchronize { @client ||= Client.new(config: config) }
+      end
+
+      # Look one domain up.
+      #
+      # @param domain [String]
+      # @return [Result]
+      def lookup(domain)
+        client.lookup(domain)
+      end
+
+      # @return [Boolean] true only when availability was positively established.
+      #   A refusal, a timeout or an unreadable response is false, not true.
+      def available?(domain)
+        client.available?(domain)
+      end
+
+      # @return [Boolean] true when the name is registered
+      def registered?(domain)
+        lookup(domain).registered?
+      end
+
+      # Check one or many domains, expanding a bare name across popular TLDs.
+      #
+      # @param domains [String, Enumerable<String>]
+      # @param options [Hash]
+      # @return [Hash{String => Symbol}] name => status
+      def whois(domains, options = {})
+        return Checker.new(client: client, config: config).check(domains) if options.empty?
+
+        Checker.whois(domains, options)
+      end
+
+      # Full results rather than statuses.
+      #
+      # @return [Hash{String => Result}]
+      def check(domains, options = {})
+        return Checker.new(client: client, config: config).check_detailed(domains) if options.empty?
+
+        Checker.lookup(domains, options)
+      end
+
+      # A single-domain handler object, camelCase aliases included.
+      #
+      # @return [WhoisHandler]
+      def handler(domain, **options)
+        WhoisHandler.whois(domain, **options)
+      end
+
+      # Why a lookup came out the way it did, including every rule consulted.
+      #
+      # @return [Hash]
+      def explain(domain)
+        client.explain(domain)
+      end
+
+      # @return [Array<String>] every TLD that can be looked up, dotted and sorted
+      def supported_tlds
+        config.server_registry.supported_tlds
+      end
+
+      # @return [Boolean]
+      def supports?(tld)
+        config.server_registry.supports?(tld)
+      end
+
+      private
+
+      def reset_client!
+        mutex.synchronize { @client = nil }
+      end
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+    end
+  end
+end

data/lib/monovm-whois-ruby.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The gem is named +monovm-whois-ruby+, so +require "monovm-whois-ruby"+ has to work.
+# Everything lives under +monovm/whois+ to match the MonoVM::Whois namespace.
+require_relative "monovm/whois"

data/lib/monovm-whois.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Convenience alias so +require "monovm-whois"+ works alongside the canonical
+# +require "monovm-whois-ruby"+.
+require_relative "monovm/whois"

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: monovm-whois-ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- MonoVM
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Look up domain registration data and check availability over RDAP and WHOIS
+  (port 43). Prefers RDAP where a registry offers it, falls back to port 43,
+  follows registrar referrals for thin registries, and parses records into
+  structured objects. Availability detection is a priority-ordered rule chain
+  that reports "unknown" instead of guessing when a server refuses to answer.
+  No runtime dependencies.
+email:
+- dev@monovm.com
+executables:
+- monovm-whois
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- data/rdap_bootstrap.json
+- data/whois_servers.json
+- exe/monovm-whois
+- lib/monovm-whois-ruby.rb
+- lib/monovm-whois.rb
+- lib/monovm/whois.rb
+- lib/monovm/whois/availability/analyzer.rb
+- lib/monovm/whois/availability/context.rb
+- lib/monovm/whois/availability/patterns.rb
+- lib/monovm/whois/availability/rule.rb
+- lib/monovm/whois/availability/rule_set.rb
+- lib/monovm/whois/availability/rules/availability_keywords.rb
+- lib/monovm/whois/availability/rules/explicit_unavailability.rb
+- lib/monovm/whois/availability/rules/no_match.rb
+- lib/monovm/whois/availability/rules/premium_name.rb
+- lib/monovm/whois/availability/rules/rdap_object.rb
+- lib/monovm/whois/availability/rules/recordless.rb
+- lib/monovm/whois/availability/rules/registration_fields.rb
+- lib/monovm/whois/availability/rules/registry_marker.rb
+- lib/monovm/whois/availability/rules/server_refusal.rb
+- lib/monovm/whois/availability/rules/status_field.rb
+- lib/monovm/whois/availability/rules/tld_specific.rb
+- lib/monovm/whois/availability/rules/wrong_registry.rb
+- lib/monovm/whois/availability/verdict.rb
+- lib/monovm/whois/checker.rb
+- lib/monovm/whois/cli.rb
+- lib/monovm/whois/client.rb
+- lib/monovm/whois/configuration.rb
+- lib/monovm/whois/domain_name.rb
+- lib/monovm/whois/endpoint.rb
+- lib/monovm/whois/errors.rb
+- lib/monovm/whois/parser/base.rb
+- lib/monovm/whois/parser/icann_rdd.rb
+- lib/monovm/whois/parser/key_value.rb
+- lib/monovm/whois/parser/rdap_json.rb
+- lib/monovm/whois/parser/record.rb
+- lib/monovm/whois/parser/selector.rb
+- lib/monovm/whois/paths.rb
+- lib/monovm/whois/punycode.rb
+- lib/monovm/whois/referral/follower.rb
+- lib/monovm/whois/registry/definition.rb
+- lib/monovm/whois/registry/resolution.rb
+- lib/monovm/whois/registry/server_registry.rb
+- lib/monovm/whois/registry/sources/base.rb
+- lib/monovm/whois/registry/sources/iana_bootstrap.rb
+- lib/monovm/whois/registry/sources/json_file.rb
+- lib/monovm/whois/response.rb
+- lib/monovm/whois/result.rb
+- lib/monovm/whois/transport/base.rb
+- lib/monovm/whois/transport/factory.rb
+- lib/monovm/whois/transport/middleware/base.rb
+- lib/monovm/whois/transport/middleware/cache.rb
+- lib/monovm/whois/transport/middleware/instrumentation.rb
+- lib/monovm/whois/transport/middleware/retry.rb
+- lib/monovm/whois/transport/middleware/throttle.rb
+- lib/monovm/whois/transport/rdap_http.rb
+- lib/monovm/whois/transport/whois_socket.rb
+- lib/monovm/whois/version.rb
+- lib/monovm/whois/whois_handler.rb
+homepage: https://github.com/monovm/whois-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/monovm/whois-ruby
+  bug_tracker_uri: https://github.com/monovm/whois-ruby/issues
+  changelog_uri: https://github.com/monovm/whois-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/monovm-whois-ruby
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Domain WHOIS and RDAP lookups with reliable availability detection.
+test_files: []