ratchet.dns API Reference

Presently, the DNS system uses dns.c as its backend. This code is included in the ratchet package and is current as of Jan 14, 2011.

Querying

Submitting a query of a specific type (e.g. MX or AAAA) is done using the ratchet.dns.query() function. Submitting multiple query types on the same data is done with ratchet.dns.query_all(), and is useful for resolving IPv6 and IPv4 records in parallel. These functions can be called from any thread; if the full results are not immediately available, the thread will be paused until they are.

local rec = ratchet.dns.query("emailsrvr.com", "mx")
print(rec[10])        -- "mx1.emailsrvr.com."
print(rec[20])        -- "mx2.emailsrvr.com."

local rec = ratchet.dns.query_all("emailsrvr.com", {"aaaa", "a"})
-- rec.a => {[1] = <userdata>}
-- rec.aaaa => nil
-- rec.aaaa_error => "emailsrvr.com has no AAAA record"

IPv4 A Records ("a" Query Type)

Until IPv6 takes over, these will be the most useful queries. It does a simple A record lookup on a hostname to find its associated IP address. This is, for example, what a web browser would do to find out where to connect, given a domain name like "www.google.com". Results are given in a numbered Lua table in the order they are received, as struct in_addr userdata objects.

local rec = ratchet.dns.query("ratchet.icgood.net", "a")

IPv6 AAAA Records ("aaaa" Query Type)

If a hostname has an AAAA record, it will be the associated IPv6 address. During the migration to IPv6, if a AAAA record is not returned the client should call back to A records. Results are given in a numbered Lua table in the order they are received, as struct in6_addr userdata objects.

local rec = ratchet.dns.query("ratchet.icgood.net", "aaaa")

PTR Records ("ptr" Query Type)

Performs a "reverse" lookup of an IPv4/IPv6 string, for an associated hostname. Results are given in a numbered Lua table in the order they are received, as hostname strings.

local rec = ratchet.dns.query("74.205.6.223", "ptr")
-- rec[1] => "emailsrvr.com."

MX Records ("mx" Query Type)

Looks up prioritized mail routing records of a hostname. The results are acceptable next-hops for mail intended for the domain. These records should generally be avoided in favor of a mail server running a configured MTA to deliver mail to the outside world. Results are given as a table keyed on priority number (e.g. 10, 20, ...) with the value being a next-hop address. The address will likely be a hostname that will require an A/AAAA lookup.

The result table for an MX query has a special method get_i() to get a specific hostname from 1 .. n, where n is the total number of hosts returned by all MX priorities. 1 would be the first hostname in the lowest returned priority, and n would be the last hostname in the highest returned priority.

local rec = ratchet.dns.query("ratchet.icgood.net", "mx")

TXT Records ("txt" Query Type)

Looks up a text field associated with a domain name. Often, this field is used for anti-abuse records such as SPF. Results are given as a numbered Lua table in the order they are received, as arbitrary strings.

local rec = ratchet.dns.query("emailsrvr.com", "txt")
-- rec[1] => "v=spf1 ip4:207.97.245.0/24 ip4:207.97.227.208/28 ...etc..."

Errors

In exchange for usually being lightning-fast, DNS queries can and will fail occasionally. For a call to ratchet.dns.query(), the return will be nil followed by an error message. For a call to ratchet.dns.query_all(), the return will always be a table, but the value for the query type that failed will be nil and there will be another key, the concatenation of the query type and "_error", that will contain the specific error message. For example:

local rec = ratchet.dns.query_all("ratchet.icgood.net", {"aaaa", "a"})
-- rec.aaaa => nil
-- rec.aaaa_error => "ratchet.icgood.net has no AAAA record"

If a query does not return from the DNS server, it is tries again at various intervals until finally failing or succeeding. During this time, the requesting thread will remain paused and other activity continues as usual.