Architecture Overview

Whois is composed by 3 main objects: Whois::Client, Whois::Server and Whois::Record. Each object is responsible for a specific task in the WHOIS query/response workflow.

  • The Whois::Client is responsible for preparing the WHOIS query and returning the record. It acts as the library controller.
  • The Whois::Server defines a single WHOIS server. It handles the query, select the proper adapter and executes the request.
  • The Whois::Record contains the full WHOIS response. It also handles the calls to the internal response properties, forwarding the methods to the Whois::Record::Parser object.

To know, or not to know: that is the question

If you just need to send a WHOIS request and print out the record, you don't actually need to know how the library works. Whois is designed to makes WHOIS queries a piece of cake. It just works.

# The simplest example

puts Whois.whois("google.com")

But if you want to take advantage of all the features offered by this package, then you need to know how exactly which object is responsible for each task and have an high level understanding of how a WHOIS request works. Don't worry, you don't need to work with socket or manipulate data using regular expression, you just need to play with awesome and flexible Ruby objects.

# An example using an advanced feature of the Whois::Record object

r = Whois.whois("google.com")
r.available? 
# => false

Theory of operation

The following image represents the standard Whois workflow for a WHOIS query.

Workflow

Regardless you are using the shortcut Whois.whois or the extended version, all the requests originates from a Whois::Client instance.

You call the Whois::Client#lookup method passing the query object and Whois::Client tries to guess the object type. On success, the client lookup the server definitions for the current object type and gets an instance of Whois::Server.

The Whois::Server represents the endpoint server for the first WHOIS request. The WHOIS protocol lacks a major standard and each server accepts proprietary requests and respond with a proprietary format. For this reason, a set of Whois::Server::Adapters is available to translate the standard Whois::Client interface into specific endpoint connections.

Assuming the Whois::Server::Adapters supports WHOIS requests, the Whois::Server queries the WHOIS server through the corresponding adapter. Depending on the WHOIS data model, the adapter might decide to run a single query or to follow WHOIS referral. In fact, Whois library supports both Thick and Thin data models.

Workflow Thin and Thick

When the request is successful, the response is converted into a Whois::Record object and sent back to the Whois::Client.

At this point, you can decide to simply print the response object or access the Whois::Record properties using the built-in parser feature. The following image explains the second option.

Whois Record

In this case, all the calls will be handled by the Whois::Record, forwarded to the Whois::Record::Parser which in turn will contact the proper Whois::Record::Parser::Base subclass corresponding to the host which provided the current record part. This is probably the most tricky, advance and powerful part of the library and it's going to be covered in a specific section.