Zonemaster.js

JavaScript interface for Zonemaster JSONRPC API.

Installation & basic usage

$ npm install --save zonemaster-js

import Zonemaster from 'zonemaster-js';

const zm = new Zonemaster('https://backend-url');
// backend needs to live on the same domain or accept CORS requests,
// use --disable-web-security flag for Chrome for easy testing


// using with Promises (ES6/ES2015):

zm.versionInfo().then(version => console.log(version));
// → {'zonemaster_backend': '…', 'zonemaster_engine': '…'}


// using with async/await (ES8/ES2017):

console.log(await zm.versionInfo());
// → {'zonemaster_backend': '…', 'zonemaster_engine': '…'}
console.log(await zm.nameserverIPs('nic.cz'));
// → {'nameservers': ['2001:1488:0:3::2', '217.31.205.50']}

Note: await can be used inside async functions only, as there is no support for "top-level await" in JS (currently?):

• Clarifying question: can await be used in top-level code?
• Top-level await is a footgun
• It's supported in Chrome DevTools Console since Chrome 62 however, might be useful for trying out and debugging: Top-level await operators in the Console

API

Table of Contents

• Zonemaster
  • Parameters
  • Examples
• dataFromParentZone
  • Parameters
  • Examples
• startDomainTest
  • Parameters
  • Examples
• testHistory
  • Parameters
• testProgress
  • Parameters
  • Examples
• testResult
  • Parameters
• validateSyntax
  • Parameters
  • Examples
• validateTestID
  • Parameters
  • Examples
• versionInfo
  • Examples

Zonemaster

Interface to the Zonemaster backend.

Parameters

• backendUrl Zonemaster backend URL, including protocol

Examples

const zm = new Zonemaster('http://localhost:5000/')

dataFromParentZone

Get domain data from it's parent zone. Async method.

API method: https://github.com/dotse/zonemaster-backend/blob/master/docs/API.md#api-method-get_data_from_parent_zone

Parameters

• domain String Domain name.

Examples

zm.dataFromParentZone('nic.cz')
// → {'ns_list': […], 'ds_list': […]}
zm.dataFromParentZone('does-not-exist.cz')
// → {'error': 'Domain does not exist.'}
zm.dataFromParentZone('.cz')
// → {'error': 'Domain name name or label outside allowed length'} -- error message from backend

Returns Object data

Returns Array data.ns_list - See backend docs.

Returns Array data.ds_list - See backend docs.

Returns String data.error - Returns an error message when both ns_list and ds_list are empty or when the backend responds with an error message.

startDomainTest

Start a new domain test. Async method.

API method: https://github.com/dotse/zonemaster-backend/blob/master/docs/API.md#api-method-start_domain_test

Parameters

• config Object A config object with domain and some advanced options
  • config.domain String Domain name, required
  • config.nameservers Object Nameservers to use, optional, see backend docs
  • config.profile String Test profile to use, optional
  • config.ipv4 Boolean Use IPv4, optional
  • config.ipv6 Boolean Use IPv6, optional
  • config.priority Number Test priority, optional
• domain String …or just a a domain name string

Examples

zm.startDomainTest('nic.cz')
zm.startDomainTest({domain: 'nic.cz', nameservers: {…}, ipv6: true})

Returns Object data

Returns String data.id - Test ID

testHistory

Get test history for a domain. Async method.

API method: https://github.com/dotse/zonemaster-backend/blob/master/docs/API.md#api-method-get_test_history

Parameters

• domain String Domain name.

Returns Object data

testProgress

Get test progress percentage. Async method.

API method: https://github.com/dotse/zonemaster-backend/blob/master/docs/API.md#api-method-test_progress

Parameters

• testId
• id String Test ID (as returned from the startDomainTest method)

Examples

zm.testProgress('abdf123456789012')
// → {progress: 80}
zm.testProgress('foo')
// → {error: 'Invalid test ID.'}
zm.testProgress('1234567890123456')
// → {error: 'Test not found.'}

Returns Object data

Returns Number data.progress - Test progress percentage

Returns String data.error - Returns an error message for an invalid ID format or when the test wasn't found.

testResult

Get test result. Async method.

API method: https://github.com/dotse/zonemaster-backend/blob/master/docs/API.md#api-method-get_test_results

Parameters

• testId
• language String (optional) Requested language for the test result messages (optional, default 'en')
• id String Test ID (as returned from the startDomainTest method)

Returns Object data

Returns String data.error - Returns an error message for an invalid ID format or when the test wasn't found.

validateSyntax

Checks the domain name and params for validity. Sync method.

All checks are done localy, since the "validate_syntax" method was removed from backend.

Parameters

• config Object A config object, same structure as in startDomainTest

Examples

zm.validateSyntax('nic.cz')
// → {ok: true, message: 'Syntax ok'}
zm.validateSyntax({domain: 'nic.cz', ipv4: false, ipv6: true})
// → {ok: true, message: 'Syntax ok'}
zm.validateSyntax('_')
// → {ok: false, message: 'Invalid domain.'}
zm.validateSyntax('háčkyčárky.cz')
// → {ok: false, message: 'Domain name contains non-ascii characters and IDN conversion is not installed'}
// (domain is valid, but didn't pass backend validation)

Returns Object data

Returns Boolean data.ok

Returns String data.message - Human readable message from the backend

validateTestID

Validate test ID with a simple regex.

Parameters

• testId String

Examples

zm.validateTestID('abdf123456789012')
// → true
zm.validateTestID('foo')
// → false

Returns Boolean

versionInfo

Get Zonemaster's backend and engine version. Async method.

API method: https://github.com/dotse/zonemaster-backend/blob/master/docs/API.md#api-method-version_info

Examples

zm.versionInfo()
// → {'zonemaster_backend': '…', 'zonemaster_engine': '…'}

Returns Object data

Returns String data.zonemaster_backend

Returns String data.zonemaster_engine

Development

$ git clone https://github.com/helb/zonemaster-js.git && cd zonemaster-js.git
$ npm install

Testing

$ npm test

Set your options in test-config.js. HTTP calls are mocked by default, if you want to use a real backend, set it's URL in the config file and enable it's use:

const config = {
  backendUrl: 'https://url:port/',
  useRealBackend: true,
  …

Generating a test coverage report:

$ npm run coverage

Reports are placed into ./coverage directory and a HTML version should open in your default browser when finished.

Building

$ npm run build

Build output is placed to ./dist directory. Multiple module formats are built, as provided by microbundle (CJS, UMD & ESM).