DNS client module for @push.rocks/smartdns — provides DNS record resolution via system resolver, raw UDP wire-format queries, and DNS-over-HTTPS (RFC 8484), with UDP and DoH powered by a Rust binary for performance.

Import

import { Smartdns, makeNodeProcessUseDnsProvider } from '@push.rocks/smartdns/client';

Architecture

The client routes queries through one of three backends depending on the configured strategy:

System — Uses Node.js dns module (dns.lookup / dns.resolveTxt). Honors /etc/hosts. No external binary.
UDP — Sends raw DNS wire-format queries to upstream resolvers (default: Cloudflare 1.1.1.1) via the rustdns-client Rust binary over IPC.
DoH — Sends RFC 8484 wire-format POST requests to a DoH endpoint (default: https://cloudflare-dns.com/dns-query) via the same Rust binary.

The Rust binary is spawned lazily — only when the first UDP or DoH query is made. The binary stays alive for connection pooling (DoH) and is killed via destroy().

Classes & Functions

`Smartdns`

The main DNS client class. Supports five resolution strategies:

Strategy	Behavior
`prefer-system`	Try OS resolver first, fall back to Rust DoH
`system`	Use only Node.js system resolver
`doh`	Use only Rust DoH (RFC 8484 wire format)
`udp`	Use only Rust UDP to upstream resolver
`prefer-udp`	Try Rust UDP first, fall back to Rust DoH

const dns = new Smartdns({
  strategy: 'prefer-udp',
  allowDohFallback: true,
  timeoutMs: 5000,
});

Key Methods

Method	Description
`getRecordsA(domain)`	Resolve A records (IPv4)
`getRecordsAAAA(domain)`	Resolve AAAA records (IPv6)
`getRecordsTxt(domain)`	Resolve TXT records
`getRecords(domain, type, retries?)`	Generic query — supports A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV
`getNameServers(domain)`	Resolve NS records
`checkUntilAvailable(domain, type, value, cycles?, interval?)`	Poll until a record propagates
`destroy()`	Kill the Rust client binary and free resources

All query methods return IDnsRecord[]:

interface IDnsRecord {
  name: string;
  type: string;
  dnsSecEnabled: boolean; // true if upstream AD flag was set
  value: string;
}

`RustDnsClientBridge`

Low-level IPC bridge to the rustdns-client binary. Used internally by Smartdns — typically not imported directly. Provides:

ensureSpawned() — lazy spawn of the Rust binary
resolve(name, type, protocol, ...) — send a resolve command via IPC
ping() — health check
kill() — terminate the binary

`makeNodeProcessUseDnsProvider(provider)`

Configures the global Node.js DNS resolver to use a specific provider:

makeNodeProcessUseDnsProvider('cloudflare'); // 1.1.1.1
makeNodeProcessUseDnsProvider('google');     // 8.8.8.8

Supported Record Types

A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV

Dependencies

@push.rocks/smartrust — TypeScript-to-Rust IPC bridge
@push.rocks/smartrequest — HTTP client (used by legacy paths)
@push.rocks/smartdelay — delay utility for retry logic
@push.rocks/smartpromise — deferred promise helper
@tsclass/tsclass — DNS record type definitions