Whois Client

The Whois::Client class is the library controller. It is responsible for receiving the WHOIS query request, invoking the Whois::Server and returning the Whois::Record.

Basics

In order to send a WHOIS query, first you need to create a WHOIS client as follows.

# Example:  Creating a Whois client

c = Whois::Client.new

Now, call the #lookup method to perform a WHOIS query passing the object you want to query as parameter.

# Example:  Sending a WHOIS query for google.com domain

c = Whois::Client.new
puts c.lookup("google.com")

The object can be any supported object, including TLDs, domain names, IPv4 and IPv6 addresses.

# Example:  Supported Object Types

c = Whois::Client.new

puts c.lookup("google.com")            # Domain
puts c.lookup(".com")                  # TLD
puts c.lookup("209.85.129.104")        # IPv4
puts c.lookup("2a00:1450:8006::63")    # IPv6

The Whois::Client is idempotent. You can use the same client to perform as many query as you want without any side effect.

# Example:  Executing multiple calls with the same Whois::Client

c = Whois::Client.new

puts c.lookup("google.com")
puts c.lookup("google.it")
puts c.lookup("google.org")
puts c.lookup("209.85.129.104")

Whois::Client#new also supports blocks.

# Example:  Executing multiple calls with the same Whois::Client using the block.

c = Whois::Client.new do |c|
  puts c.lookup("google.com")
  puts c.lookup("google.it")
  puts c.lookup("google.org")
  puts c.lookup("209.85.129.104")
end

Whois::Client.lookup always returns a Whois::Record on success or raises an error on failure.

Options

Timeout

By default, each query run though the Whois::Client has a timeout value of 10 seconds. If the execution exceeds timeout limit, the client raises a Timeout::Error exception.

You can customize the timeout value using the :timeout option or calling the #timeout method. If timeout is nil, the client will wait until the response is sent back from the server or the process is killed.

WARNING: Don't disable the timeout unless you really know what you are doing.

# Example:  Changing the timeout value for a WHOIS query

c = Whois::Client.new(timeout: 20)
c.timeout # => 20
c.timeout = 5
c.timeout # => 5

c.lookup("google.com")

Local Address and Port Binding

If :bind_host and/or :bind_port options are passed, the client associates given settings to the socket connection. Otherwise, the client will use default socket settings.

# Example:  Changing the bind address

c = Whois::Client.new(bind_host: "192.168.1.100")

c.lookup("google.com")

Shortcuts

The most essential Whois features are also available as a convenient module functions in the Whois module.

Whois.whois
Whois.available?
Whois.registered?

Whois.whois is equal to invoking the #lookup method on a Whois::Client instance.

# Example:  Sending a WHOIS query using an explicit or implicit WHOIS::Client

# WHOIS request with an explicit Whois::Client
c = Whois::Client.new
c.lookup("google.com")

# WHOIS request with an implicit Whois::Client
c = Whois.whois("google.com")

Whois.available? and Whois.registered? are equal to performing a WHOIS request for given object and invoking the corresponding available? and registered? on the returned Whois::Record.

# Example:  Sending a WHOIS query and checking for domain availability
#           using an explicit or implicit WHOIS::Client

# With an explicit Whois::Client
c = Whois::Client.new
c.lookup("google.com").available?
c.lookup("google.com").registered?

# With an implicit Whois::Client
Whois.available?("google.com")
Whois.registered?("google.com")