Caution

This project is currently under development

unbound-control-ts

A TypeScript library for configuration and control of Unbound DNS.

Samples

Important

This is an unofficial project, not affiliated with the official Unbound or its maintainers.

Table of Contents

1. About The Project
2. Key Features
3. Usage
   1. Prerequisites
   2. Install
   3. Example Usage
4. Development
   1. Develop Prerequisites
   2. Develop Setup
5. License

About The Project

Unbound is a powerful and versatile DNS resolver that is widely used for enhancing network privacy, security, and performance.

This project provides a TypeScript library designed to simplify interaction with Unbound's unbound-control utility, enabling developers to manage and configure Unbound DNS programmatically with ease.

Key Features

• Seamless Integration: Interact with Unbound directly from your TypeScript or JavaScript projects.
• User-Friendly API: A clean and intuitive API for common Unbound operations like querying statistics, reloading configurations, or managing zones.
• Cross-Platform Compatibility: Works across various platforms where unbound-control is available.
• Open Source: Built with community contributions and extensibility in mind.

Here's a suggestion for the "Usage" section, including installation instructions:

Usage

Prerequisites

1. Ensure that unbound-control is installed and configured on your system.
2. Make sure the process running the script has appropriate permissions to access the Unbound control socket.

For more examples and advanced usage, refer to the Unbound docs.

Install

To get started, install the library using your preferred package manager:

Using npm:

npm install unbound-control-ts

Using yarn:

yarn add unbound-control-ts

Example Usage

Here's a basic example to demonstrate how to use the library:

Use domain socket:

import { UnixUnboundClient } from 'unbound-control-ts';

const client = new UnixUnboundClient('/path/to/unbound-control.sock');

(async () => {
  try {
    const response = await client.status();
    console.log(response);
  } catch (error) {
    if (error instanceof UnboundError) {
      console.error(error.message);
    } else {
      console.error(error);
    }
  }
})();

Use tcp socket:

import { TcpUnboundClient } from 'unbound-control-ts';

const client = new TcpUnboundClient('localhost', 8953);

(async () => {
  try {
    const response = await client.status();
    console.log(response);
  } catch (error) {
    if (error instanceof UnboundError) {
      console.error(error.message);
    } else {
      console.error(error);
    }
  }
})();

output:

{
  "json": {
    "modules": [
      "subnetcache",
      "validator",
      "iterator",
    ],
    "options": [
      "reuseport",
      "control(namedpipe)",
    ],
    "pid": 1,
    "status": "running",
    "threads": 1,
    "uptime": 292,
    "verbosity": 1,
    "version": "1.22.0",
  },
  "raw": "version: 1.22.0\nverbosity: 1\nthreads: 1\nmodules: 3 [ subnetcache validator iterator ]\nuptime: 292 seconds\noptions: reuseport control(namedpipe)\nunbound (pid 1) is running...\n",
}

Development

Develop Prerequisites

Before you begin, ensure you have the following tools installed on your system:

• Node.js: Version 16 or later. Download Node.js
• npm: Comes with Node.js, or install it separately if needed.
• Unbound: Ensure that unbound-control is installed and properly configured. Follow the Unbound installation guide for details.

Develop Setup

Follow these steps to set up the project for local development:

1. Clone the Repository

   git clone https://github.com/your-username/unbound-control-ts.git
   cd unbound-control-ts

2. Install Dependencies Use your preferred package manager to install dependencies:

   npm install

   or

   yarn install

3. Build the Project Compile the TypeScript source code into JavaScript:

   npm run build

4. Run Tests Verify the project by running tests:

   npm test

5. Code Linting and Formatting Use the following commands to ensure code quality:

   • Lint the code:

     npm run lint

   • Format the code:

     npm run format

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)