dnslink-std/js

The reference implementation for DNSLink resolver in JavaScript. Tested in Node.js and in the Browser.

@dnslink/js

The reference implementation for DNSLink resolver in JavaScript. Tested in Node.js and in the Browser.

Usage

You can use dnslink both as a CLI tool or a library.

JavaScript API

Getting started with DNSLink resolution in a jiffy:

import { resolve, DNSRcodeError } from '@dnslink/js'

// assumes top-level await
let result
try {
  result = await resolve('dnslink.dev/abcd?foo=bar', {
    endpoints: ['dns.google'], // required! see more below.
    /* (optional) */
    signal, // AbortSignal that you can use to abort the request
    timeout: 1000, // timeout for the operation
    retries: 3 // retries in case of transport error
  })
} catch (err) {
  // Errors provided by DNS server
  if (err instanceof DNSRcodeError) {
    err.rcode // Error code number following - https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
    err.error // Error code name following (same list)
    err.code // `RCODE_${err.code}
    err.domain // Domain lookup that resulted in the error
    if (err.rcode === 3) {
      // NXDomain = Domain not found; most relevant error
    }
  } else {
    // A variety other errors may be thrown as well. Possible causes include, but are not limited to:
    // - Invalid input
    // - Timeouts / aborts
    // - Networking errors
    // - Incompatible dns packets provided by server
  }
}
const { links, log, txtEntries } = result

// `links` is an object containing given links for the different namespaces
// Each names contains an identifier and a ttl.
links.ipfs === [{ identifier: 'QmTg....yomU', ttl: 60 }]

// The `log` is always an Array and contains a list of log entries
// that were should help to trace back how the linked data was resolved.
Array.isArray(log)

// The `txtEntries` are a reduced form of the links that contains the namespace 
// as part of the value
txtEntries === [{ value: '/ipfs/QmTg....yomU', ttl: 60 }]

Endpoints

You need to specify endpoints to be used with the API. You can specify them the same way as you would in dns-query.

Possible log statements

The log statements follow the DNSLink specification.

Command Line

To use dnslink in the command line you will need Node.js installed.

Install it permanently using npm i -g @dnslink/js or run in on-the-fly using npx @dnslink/js.

You can get detailed help for the app by passing a --help option at the end:

$ npx @dnslink/js --help

License

Published under dual-license: MIT OR Apache-2.0

js's Issues

Load domain and fallback domain in parallel

Currently the code is written to value formal correctness and brevity over performance. This meant a neglect of performance in particular for loading the _dnslink.<fqdn> and <fqdn> domains. Those requests should be done in parallel, preferably cancelling the <fqdn> request if _dnslink.<fqdn> was successful.

Remove eth support?

Following up on our conversation in https://github.com/ipfs/community/discussions/560: Should .eth support be removed from this implementation?

Add support for multiple responses

Aligning with dnslink-std/test#11

Remove built-in doh endpoints

Lib allows passing 'pet names' for DoH endpoints from https://github.com/martinheidegger/doh-query/blob/main/endpoints.md

Concern

Maintenance costs, eventual rot of the list.

Ask

• Remove DoH list from the lib.
• Require full URL of DoH endpoint to be explicitly provided

Change CLI argument to redirect by default

Currently, in the spirit of resolve and resolveN, the -r flag of the command line tool is optional, making redirects optional. In standard operation I would guess however that redirects are desired. It would be better to have a --no-redirect flag instead assuming redirect as standard.

Align API with @dnslink-std/go

In the go implementation following API seems to be useful here too:

const resolver = new dnslink.Resolver({
   async lookupTXT(domain) {
      // implementation
   }
})
resolver.resolveN("dnslink.dev")

Chaining not getting resolved properly

What we did

I assume the extension is using this lib under the hood. IPFS Browser extension 0.11.0. The URL in browser (Brave) is ipns://wiki.polkadot.network , and I was able to reproduce the error using a HTTP gateway (https://ipfs.w3f.community/ipns/wiki.polkadot.network).

Error:

ipfs resolve -r /ipns/wiki.polkadot.network: could not resolve name: "wiki.polkadot.network" is missing a DNSLink record (https://docs.ipfs.io/concepts/dnslink/)

Expected resolving

browser -> _dnslink.wiki.polkadot.network -> _dnslink.polkadot-wiki.w3f.services -> resolve the wiki's hash

DNS TXT values

❯ dig +short TXT _dnslink.wiki.polkadot.network
"dnslink=/dnslink/polkadot-wiki.w3f.services"
                                                                                      
❯ dig +short TXT _dnslink.polkadot-wiki.w3f.services    
"dnslink=/ipfs/QmdncfsVm2h5Kqq9hPmU7oAVX2zTSVP3L869tgTbPYnsha"

Any clear misconfigurations on our part? Pretty sure we're doing it exactly how its described here.

Add support for TTL

Following outstanding tests in dnslink-std/test#7 the library should support ttl output.