Skip to content

Latest commit

 

History

History
143 lines (87 loc) · 7.95 KB

4.0-Upgrade.md

File metadata and controls

143 lines (87 loc) · 7.95 KB
Raw

Welcome to Whois 4.0!

Whois 4 is a major upgrade compared to Whois 3. This library is now 7 years old, enough mature to offer pretty much all the features you need to perform WHOIS queries.

In these last 7 years the adoption of this library has grown beyond any expectation. Most of the time was spent updating the definitions to stay up to date with the various registrar changes (thanks ICANN for thew newGLTDs...), updating the registry parsers and polishing up the public interface.

For Whois 4 I decided to take a step back, and rewrite some of the internal components of this library to improve performance and readability. As a result of these changes, there are several compatibility breaks with Whois 4 that I'm going to document here.

-- Simone

What's New

  • The Whois client and the Whois parser are now two separate repositories, and they are also distributed as two separate gems:

    There are several reasons behind this change (see weppos/whois#503).

    First of all, the maintenance of the whois-parser component is the most time consuming task. Updating a parser may require from a few minutes to several hours, depending on how big are the changes. It also requires to generate the appropriate fixtures, and write the necessary tests. In the last years I noticed that more than once client updates were delayed because of pending parser changes. Separating the repositories and the release cycles will likely speedup future released of the client gem.

    Moreover, the parser component takes a lot of space (due to all the files and fixtures). If you just need a Ruby whois client, loading the entire parser component is inefficient and a waste of time/CPU/resources.

    Last but not least, in the last years the Whois client inspired several ports in different languages. Most of these ports were not interested in porting the parser as well. However, the parser was so tightly coupled with the client that it made the client code harder to read.

  • The definition files have been largely redesigned, in particular the TLD file. The definitions are now maintained using a set of CLI tools. The goal is to eventually extract the definition files into a separate, standalone repository that other WHOIS libraries can easily fetch.

Upgrade

When upgrading, here's the most relevant changes to keep an eye on:

  • If you are using the Whois parser, install and require the whois-parser gem. The parser will automatically download the appropriate whois dependency.

    require 'whois-parser'

    If you only need the client and you don't care about the parser, simply continue to require the whois gem directly.

    require 'whois'

  • Whois::Server.definitions no longer return the internal definitions. Definitions are no longer accessible directly, because their internal representation may change at any time. If you need to modify the definitions, use the public API.

    Whois::Server.define(Whois::Server::TYPE_TLD, ...)

    You can still use Whois::Server.definitions, but it will return a copy of the internal definitions, and you have to specify which type of definitions you want to access.

    Whois::Server.definitions(Whois::Server::TYPE_TLD)

  • The parser methods are no longer accessible directly within the response object.

    This is probably one of the most important changes, and it is explained in details at weppos/whois-parser#5.

    In Whois 3, you can invoke a property method on a record object and the record will automatically route the method call to the underlying parser. If the property is not supported or defined in any of the parsers, then the method will return nil.

    However, this behavior is often the cause of confusion and misunderstandings, especially for partially implemented parsers. Without to mention that the code required for this feature to work added an extra layer of complexity to the Whois::Record implementation.

    Starting from Whois 4, the Whois::Record doesn't expose any parsing methods anymore. If you want to parse a record, you have to istantiate a parser manually. Of course, you also need to use the whois-parser library instead of whois.

    Whois 3:

    require 'whois-parser'

record = Whois.whois("example.it")
record.expires_on

    Whois 4:

    require 'whois-parser'

record = Whois.whois("example.it")
parser = Whois::Parser.new(record)
parser.expires_on

    You can still use the convenient helper record.parser to initialize a parser:

    require 'whois-parser'

record = Whois.whois("example.it")
record.parser.expires_on

    Also note that any parser method, such as parser.expires_on, will raise an error if the property is not implemented, as opposite to silently returning nil as it was in Whois 3.

  • Parser extensions

    The Parser features available in Whois 3 has been packaged into several extensions. Some of them are loaded by default in Whois 4 when you require whois-parser, others not anymore. The reason is because although some of them may appear convenient (because it makes you write more code), it turned out that they made some assumptions that were often source of confusion.

    Check the header of the whois/parser.rb file to learn more about the purpose of each extension.

    Requiring all the extensions will essentially force Whois 4 to work pretty much like Whois 3. This is not recommended, and you should not rely on those extensions to be there forever. Instead, you should write the code depending on what you actually need.

    There is also an ENV variable you can set to rollback compatibility to Whois 3.

    ENV["WHOISRB_4EXTENSIONS"] = 1

    Again, this flag exists only as temporary helper, and it should not become a permanent upgrade workaround.

  • SafeRecord

    In the previous point I mentioned that you should write the code you need to customize the Whois::Record and extract information with the Whois::Parser. However, I omitted an important additional recommendation: avoid monkey patching the Whois::Record object, and instead prefer composition via delegation.

    The SafeRecord is an example of a wrapper around a Record object, that expose a Whois 3 alike interface, without injecting the parser methods directly into the Whois::Record itself.

    The advantages are:

    • the code is more maintainable, as it is not tighlty coupled to the Whois::Record
    • you don't monkey patch Whois::Record in your code, which is an object you don't have control of because it is packaged in a third party library (and can change)
    • the library can easily be tested separately

    In these 10 years of writing Ruby code, I've noticed an increasing attitude to monkey patch Ruby classes you don't control, instead of writing your own code and delegate to them. It looks like in several cases Ruby programmers are afraid of writing Ruby code. This results in very fragile code, where methods can easily conflict each other (especially between dependencies).

    The Whois::SafeRecord is an alternative example of how you can restore Whois 3 behavior by using a custom object.

    require 'whois/parser'
require 'whois/safe_record'

record = Whois.whois('example.com')
record.disclaimer
# => Whois::AttributeNotSupported

safe_record = Whois::SafeRecord.new(record)
safe_record.disclaimer
# => nil

    This is preferred over requiring the whois/parser_extensions or enabling v3 compatibility mode.

    Please note that the parser extension is provided as example. It may be removed from future versions therefore, once again, you should write the code you need to access the parsed data.