getsocket-dns

socket-dns

Socket-specific fork of datprotocol/dat-dns, originally written by pfrazee

Issue DNS lookups for Dat archives using HTTPS requests to the target host. Keeps an in-memory cache of recent lookups.

API

var socketDns = require('socket-dns')()
 
// resolve a name: pass the hostname by itself
socketDns.resolveName('foo.com', function (err, key) { ... })
socketDns.resolveName('foo.com').then(key => ...)
 
// dont use cached 'misses'
socketDns.resolveName('foo.com', {ignoreCachedMiss: true})
 
// dont use the cache at all
socketDns.resolveName('foo.com', {ignoreCache: true})
 
// dont use dns-over-https
socketDns.resolveName('foo.com', {noDnsOverHttps: true})
 
// dont use .well-known/socket
socketDns.resolveName('foo.com', {noWellknownDat: true})
 
// list all entries in the cache
socketDns.listCache()
 
// clear the cache
socketDns.flushCache()
 
// configure the DNS-over-HTTPS host used
var socketDns = require('socket-dns')({
  dnsHost: 'dns.google.com',
  dnsPath: '/resolve'
})
 
// use a persistent fallback cache
// (this is handy for persistent dns data when offline)
var socketDns = require('socket-dns')({
  persistentCache: {
    read: async (name, err) => {
      // try lookup
      // if failed, you can throw the original error:
      throw err
    },
    write: async (name, key, ttl) => {
      // write to your cache
    }
  }
})
 
// emits some events, mainly useful for logging/debugging
socketDns.on('resolved', ({method, name, key}) => {...})
socketDns.on('failed', ({method, name, err}) => {...})
socketDns.on('cache-flushed', () => {...})

Spec

In detail.

Option 1 (DNS-over-HTTPS). Create a DNS TXT record witht he following schema:

socketkey={key}

Option 2 (.well-known/socket). Place a file at /.well-known/socket with the following schema:

{socket-url}
TTL={time in seconds}

TTL is optional and will default to 3600 (one hour). If set to 0, the entry is not cached.