DNS

@push.rocks/smartdns is a TypeScript-first DNS toolkit with Rust binaries behind the wire-level DNS work.

The public surface stays in TypeScript: create a DNS client, choose a resolution strategy, register authoritative server handlers, retrieve ACME certificates, and wire the package into a larger service. Rust handles the parts where DNS is byte-oriented: UDP queries, DNS-over-HTTPS wire-format requests, packet parsing and encoding, async UDP and HTTPS listeners, and DNSSEC signing.

This is the same TypeScript/Rust split beta.news covered in the foss.global bridge architecture dispatch. TypeScript owns product shape and integration. Rust owns the data path. SmartDNS applies that pattern to DNS without turning the package into a general-purpose recursive resolver.

Three entry points

The package ships three import surfaces:

import { Smartdns } from '@push.rocks/smartdns/client';
import { DnsServer } from '@push.rocks/smartdns/server';
import { dnsClientMod, dnsServerMod } from '@push.rocks/smartdns';

The client entry point resolves records. The server entry point runs an authoritative DNS server with TypeScript handlers. The root entry point re-exports both modules.

The current public package version is 7.9.3. The export map points @push.rocks/smartdns/client to dist_ts_client, @push.rocks/smartdns/server to dist_ts_server, and the root package to dist_ts. The build pipeline runs tsbuild tsfolders --web and tsrust, so the TypeScript and Rust outputs ship together.

The major architecture changes landed in the 7.7.x and 7.8.x line. Version 7.7.0 added the Rust server backend and TypeScript bridge. Version 7.8.0 added the Rust DNS client binary for UDP and DoH. Version 7.8.1 removed the synchronous TypeScript packet-processing fallback; current raw packet processing requires the Rust bridge path.

The client: system resolver, Rust UDP, or Rust DoH

Smartdns supports five resolution strategies:

• prefer-system: try the operating system resolver first, then fall back to Rust DoH;
• system: use only Node's DNS module;
• doh: use DNS-over-HTTPS through the Rust client;
• udp: use raw UDP DNS through the Rust client;
• prefer-udp: try Rust UDP first, then fall back to Rust DoH.

The difference is operational. The system resolver path honors local host behavior and does not start Rust. UDP and DoH use rustdns-client, which is spawned lazily on the first query that needs it and can be stopped with destroy().

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

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

const aRecords = await dns.getRecordsA('example.com');
const mxRecords = await dns.getRecords('example.com', 'MX');
const txtRecords = await dns.getRecordsTxt('example.com');

dns.destroy();

The Rust client builds DNS wire-format queries with the recursion desired flag set. It adds EDNS0 with the DNSSEC OK bit, sends UDP queries to an upstream resolver or RFC 8484 DoH POST requests, parses the DNS response, decodes common RDATA types, and reports the upstream AD flag back to TypeScript as dnsSecEnabled.

Type-specific helpers cover A, AAAA, TXT, and NS lookups. Generic queries support A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, and SRV. That makes the client useful for propagation checks, certificate workflows, DNS validation in infrastructure services, and application code that needs predictable DNS behavior without making each consumer parse DNS packets.

The server: authoritative DNS with Rust I/O and TypeScript handlers

The server side is DnsServer. It is an authoritative DNS server, not a recursive resolver. Rust owns UDP socket handling, DNS packet parsing and encoding, DNS-over-HTTPS over Hyper and Rustls, DNSSEC key and signature work, and the IPC management loop. TypeScript owns server lifecycle, handler registration, ACME orchestration, domain authorization, and query events.

import { DnsServer } from '@push.rocks/smartdns/server';

const server = new DnsServer({
  udpPort: 53,
  httpsPort: 443,
  httpsKey: '...pem...',
  httpsCert: '...pem...',
  dnssecZone: 'example.com',
  primaryNameserver: 'ns1.example.com',
});

server.registerHandler('*.example.com', ['A'], (question) => ({
  name: question.name,
  type: 'A',
  class: 'IN',
  ttl: 300,
  data: '10.0.0.1',
}));

await server.start();

When a DNS query arrives, the Rust process emits a dnsQuery event over JSON IPC. TypeScript resolves the question against registered handlers. The answer list goes back to Rust, which assembles the DNS response and signs RRsets when DNSSEC was requested.

Handlers use glob patterns through minimatch, and multiple handlers can contribute records to the same response. That fits dynamic authoritative DNS cases: wildcard service records, generated internal hostnames, tenant-specific answers, ACME DNS-01 challenge records, and dashboard-managed zones.

The 7.9.3 release fixed a real DNS edge case in that handler path. Query names and record types are now normalized before matching, so DNS 0x20 mixed-case randomization still resolves registered records.

DNSSEC is in the Rust layer

DNSSEC is enabled through dnssecZone. The TypeScript server configuration currently sends ECDSA as the default algorithm, and the Rust key implementation covers ECDSA P-256 and ED25519. DNSKEY answers and RRSIG generation are produced in Rust, with RRsets serialized canonically before signing.

That placement is intentional. DNSSEC signing is sensitive to wire format details: canonical ordering, lower-case owner names, TTL handling, record-set boundaries, and the exact RDATA bytes. Those are better handled next to the Rust packet encoder than in an application-level fallback.

DNS-over-HTTPS on both sides

SmartDNS uses DNS-over-HTTPS in both directions.

As a client, rustdns-client sends RFC 8484 application/dns-message requests. Its default DoH endpoint is Cloudflare's https://cloudflare-dns.com/dns-query, and the default UDP upstream is 1.1.1.1:53.

As a server, the Rust backend can expose a DoH listener over HTTPS. The TypeScript options provide HTTPS bind interface, port, certificate, and key. ACME support can retrieve Let's Encrypt certificates through DNS-01 challenge records registered temporarily in the same handler system.

Manual binding and query events

Most deployments can let DnsServer.start() bind UDP and HTTPS directly. The options also support explicit UDP and HTTPS bind interfaces, so the server can be restricted to localhost, a LAN address, or different addresses per protocol.

Manual UDP and HTTPS modes let an outer service own socket placement. In current Rust mode, raw packet processing goes through processRawDnsPacketAsync(); the server must be started