dns-agent

DNS agent

Table of contents

• Get Started
• API
• Why dns-agent
• Honorable Dependents
• About

Links

• CHANGE LOG
• Homepage

Get Started

// The main entrance of package *dns-agent* is a class.
const DnsAgent = require('dns-agent');

// Create an instance.
const agent = new DnsAgent({
    // Time-To-Live of resolved address (in seconds).
    ttl: 86400,

    // Method to execute name resolving.
    // . "system"   means to use dns.lookup / getaddrinfo(3).
    // . "network"  means to perform a DNS query on the network.
    // . <IP>       DNS server to be used.
    // The default value is "system".
    source: 'system'
});

agent.lookup4('localhost', (err, ipv4) => {
    // ...
});

API

class DnsAgent

The main entrance of dns-agent is a class (named DnsAgent in following code snippets).

• class DnsAgent(object options)
  The only argument may be passed to the constructor is an option object.

  const DnsAgent = require('dns-agent');
  const agent = new DnsAgent({ ttl, source });

  • ttl number DEFAULT 86400 (unit: seconds)
    Time-To-Live of resolved address.

  • source string DEFAULT "system"
    Acceptable values may be "system" | "network" | "<IP_address>".

    When source has a value of "system", dns-agent will use dns.lookup() to find the responding IP address of hostname. It is actually, according to Node.js Documentation, DNS, implemented as a synchronous call to getaddrinfo(3).

    When the value is "network", dns.resolve() will be used. That means to always perform a DNS query on the network. However, if there is some name resolving result not expired, whether or not it is stored in current instance of dns-agent, it will be returned whitout querying the DNS server.

    Else if "<IP_address>" set, dns-agent behaves like what it does on "network" but using the specified DNS server.

• Promise | void agent.lookup4(string hostname [, Function callback ])
  Resolve the hostname into the first found A(IPV4) address. This is a PoC function that will return an instance of Promise if no callback passed, or return void and invoke the passed callback.

  • hostname string
  • callback(Error error, String ipv4) Function OPTIONAL

Examples

Why dns-agent

On designing another package htp, I think it maybe helpful for those developing with htp to be informed how many time an HTTP/HTTPs request spends on each step including (host)name resolving. So, I will try dns.lookup() before really launching the request. It works as expected in unit test. However, when hundreds of, even thousands of requests happen in very short time, repeatedly invoking of dns.lookup() may lead to unexpected exception. Maybe it is regarded as something like DoS attack by system or DNS server. So, I write dns-agent and delegate the actions on dns to it.

Honorable Dependents

Of course, htp is the first dependent.

About

For convenience, this package has following names (alias):

• dns-agent
• dns.agent
• dnsagent