Permalink
Newer
Older
100644 213 lines (127 sloc) 8.71 KB
@weppos
Jul 23, 2009
2
@weppos
Dec 22, 2011
3
*Whois* is an intelligent pure Ruby WHOIS client and parser.
@weppos
Dec 22, 2011
5
[![Build Status](https://secure.travis-ci.org/weppos/whois.png)](http://travis-ci.org/weppos/whois)
6
@weppos
Dec 22, 2011
7
*Whois* is a OS-independent library and doesn't require any external binaries or C libraries: it is a 100% Ruby software.
@weppos
Dec 22, 2011
9
This library was developed to power [RoboDomain](https://www.robodomain.com) and, since July 2009, it ran more than thousands requests.
@weppos
Dec 22, 2011
11
An extensive test suite is available to verify the library correctness but you must be aware that registrant might change WHOIS interfaces without notice and at any time causing queries to specific hosts to stop working.
16
* Ability to query registry data for [IPv4, IPv6, TLDs, and domain names](http://www.ruby-whois.org/manual/usage.html#usage-objects)
17
* Ability to [parse WHOIS responses](http://www.ruby-whois.org/manual/parser.html)
18
* Flexible and extensible interface (e.g. You can define [custom servers](http://www.ruby-whois.org/manual/server.html) on the fly)
19
* Object oriented design, featuring 10 different design patterns
20
* Pure Ruby library, without any external dependency other than Ruby itself
21
* Compatible with [Ruby 1.8.7 and greater](http://www.ruby-whois.org/manual/installing.html#installation-requirements), including Ruby 1.9 branch
22
* Successfully tested against several [Ruby implementations](http://www.ruby-whois.org/manual/interpreters.html)
27
* Ruby >= 1.8.7
28
@weppos
Dec 22, 2011
29
*Whois* >= 1.5 requires Ruby 1.8.7 or newer.
30
For older versions of Ruby, see the CHANGELOG.rdoc file.
32
In addition to the standard Ruby interpreter (MRI),
33
Whois has been successfully tested against several
34
[Ruby implementations](http://www.ruby-whois.org/manual/interpreters.html).
@weppos
Dec 24, 2011
39
The best way to install *Whois* is via [RubyGems](https://rubygems.org/).
@weppos
Dec 24, 2011
43
You might need administrator privileges on your system to install the gem.
47
48
Install the newer version via RubyGems.
49
52
Minor and bugfix releases normally won't break backwards-compatibility. You can read the CHANGELOG.md file to learn about the changes in each release.
@weppos
Oct 1, 2011
54
Read the [Upgrading](http://www.ruby-whois.org/manual/upgrading.html) documentation page for detailed information about incompatible changes and further instructions.
@weppos
Oct 1, 2011
57
## Getting Started
@weppos
Oct 1, 2011
59
Note. This section covers only the essentials for getting started with the Whois library. The [documentation](http://www.ruby-whois.org/documentation.html) provides a more accurate explanation including tutorials, more examples and technical details about the client/server/record/parser architecture.
@weppos
Oct 1, 2011
61
### Querying the Server
63
Whois provides the ability to get WHOIS information for TLD, domain names, IPv4 and IPv6 addresses. The client is smart enough to guess the best WHOIS server according to given query, send the request and return the response.
65
Check out the following examples:
@weppos
Oct 1, 2011
67
# Domain WHOIS
68
w = Whois::Client.new
69
w.query("google.com")
70
# => #<Whois::Record>
@weppos
Oct 1, 2011
72
# TLD WHOIS
73
w = Whois::Client.new
74
w.query(".com")
75
# => #<Whois::Record>
@weppos
Oct 1, 2011
77
# IPv4 WHOIS
78
w = Whois::Client.new
79
w.query("74.125.67.100")
80
# => #<Whois::Record>
@weppos
Oct 1, 2011
82
# IPv6 WHOIS
83
w = Whois::Client.new
84
w.query("2001:db8::1428:57ab")
85
# => #<Whois::Record>
86
87
The query method is stateless. For this reason, you can safely re-use the same client instance for multiple queries.
88
@weppos
Oct 1, 2011
89
w = Whois::Client.new
90
w.query("google.com")
91
w.query(".com")
92
w.query("74.125.67.100")
93
w.query("2001:db8::1428:57ab")
94
w.query("google.it")
95
@weppos
Oct 1, 2011
96
If you just need a WHOIS response and you don't care about a full control of the WHOIS client, the {Whois} module provides an all-in-one method called {Whois.whois}. This is the simplest way to send a WHOIS request.
97
98
Whois.whois("google.com")
99
# => #<Whois::Record>
100
101
Did I mention you can even use blocks?
102
103
Whois::Client.new do |w|
104
w.query("google.com")
105
w.query(".com")
106
w.query("74.125.67.100")
107
w.query("2001:db8::1428:57ab")
108
w.query("google.it")
109
end
@weppos
Oct 1, 2011
111
### Consuming the Record
113
Any WHOIS query returns a `Whois::Record`. This object looks like a String, but it's way more powerful.
115
`Whois::Record` encapsulates a WHOIS record and provides the ability to parse the WHOIS response programmatically, by using an object oriented syntax.
@weppos
Oct 1, 2011
117
r = Whois.whois("google.it")
118
# => #<Whois::Record>
@weppos
Oct 1, 2011
120
r.available?
121
# => false
122
r.registered?
123
# => true
@weppos
Oct 1, 2011
125
r.created_on
126
# => Fri Dec 10 00:00:00 +0100 1999
@weppos
Oct 1, 2011
128
t = r.technical_contact
129
# => #<Whois::Record::Contact>
130
t.id
131
# => "TS7016-ITNIC"
132
t.name
133
# => "Technical Services"
@weppos
Oct 1, 2011
135
r.nameservers.each do |nameserver|
136
puts nameserver
137
end
@weppos
Dec 22, 2011
139
This feature is made possible by the *Whois* record parsers. Unfortunately, due to the lack of a global standard, each WHOIS server requires a specific parser. For this reason, the library doesn't support all existing WHOIS servers.
140
141
If you create a new parser, please consider releasing it to the public so that it can be included in a next version.
142
@weppos
Oct 1, 2011
143
### Timeout
145
By default, each query run though the client has a timeout value of 5 seconds. If the execution exceeds timeout limit, the client raises a `Timeout::Error` exception.
@weppos
Oct 1, 2011
147
Off course, you can customize the timeout value setting a different value. If timeout is `nil`, the client will until the response is sent back from the server or the process is killed. Don't disable the timeout unless you really know you are doing!
@weppos
Oct 1, 2011
149
w = Whois::Client.new(:timeout => 10)
150
w.timeout # => 10
151
w.timeout = 5
152
w.timeout # => 5
@weppos
Oct 1, 2011
154
w.query("google.com")
@weppos
Oct 1, 2011
157
## Acknowledgments
@weppos
Dec 22, 2011
159
First of all, I would like to express my most sincere thanks to Cyril Mougel, the author of the first Ruby Whois gem that has been available since 2007. Cyril has been kind enough to yield me the privilege of using the RubyForge Whois project and the Whois package name to publish this library. To express all my gratitude, the release 0.5.0 and all sub sequential versions of the new Whois up to 0.9.x are 100% compatible with Cyril's Whois.
@weppos
Oct 1, 2011
161
Whois is largely inspired by other notable Whois projects, most of all the Debian Whois library written and maintained by Marco D'Itri. Other good ideas and design decisions come from the PERL `Net::DRI` package.
162
163
I would lie if I say I'm completely unaware of the other Ruby Whois projects. Before starting this Ruby Whois library I deeply investigated the available resources and, despite none of them was a good candidate for a refactoring, some of them expose a really cool API.
164
They didn't directly influence this library or any design decision, but they have been a really interesting code-reading.
165
@weppos
Oct 1, 2011
166
The parser architecture has been inspired by the [PHPWhois](http://phpwhois.sourceforge.net/) project. The authors puts lot of effort to create whois-specific parsers normalizing the different responses in a single tree-based structure. So far, this is the only one open source project that offers such this feature in all the programming language ecosystem.
@weppos
Dec 22, 2011
168
Despite I spent weeks reading source code from the available whois libraries, Ruby *Whois* has been built from scratch trying to focus on long-term maintainability and flexibility and cannot be considered a Ruby port of any of other existing Whois libraries.
171
## Credits
173
- [Simone Carletti](http://www.simonecarletti.com/) <weppos@weppos.net> - Author
174
- [Contributors](https://github.com/weppos/whois/contributors)
@weppos
Dec 22, 2011
177
## Contribute
@weppos
Dec 22, 2011
179
Direct questions and discussions to the [mailing list](http://groups.google.com/group/ruby-whois).
@weppos
Dec 22, 2011
181
Pull requests are very welcome! Please include spec and/or feature coverage for every patch, and create a topic branch for every separate change you make.
182
183
Report issues or feature requests to [GitHub Issues](https://github.com/weppos/whois/issues).
186
## Donations
187
188
[Support Whois at Pledgie](http://www.pledgie.com/campaigns/11383).
189
190
<a href='http://www.pledgie.com/campaigns/11383'><img alt='Click here to lend your support to: whois and make a donation at www.pledgie.com !' src='http://www.pledgie.com/campaigns/11383.png?skin_name=chrome' border='0' /></a>
191
192
Whois is free software, but it costs money to write, test, and distribute it. You can support the development by sending a donation. **Any amount, even $5, is greatly appreciated**.
193
194
@weppos
Oct 1, 2011
195
## More
197
- [Homepage](http://www.ruby-whois.org/)
198
- [Repository](https://github.com/weppos/whois)
@weppos
Mar 6, 2012
199
- [Documentation](http://www.ruby-whois.org/documentation.html) - The official documentation, see also the [API Documentation](http://www.ruby-whois.org/api).
200
- [Discussion Group](http://groups.google.com/group/ruby-whois)
@weppos
Oct 1, 2011
203
## Changelog
205
See the [CHANGELOG](CHANGELOG.md) file for details.
@weppos
Oct 1, 2011
208
## License
210
Copyright (c) 2009-2012 Simone Carletti.
211
@weppos
Oct 1, 2011
212
This is Free Software distributed under the MIT license.