95 lines
3.3 KiB
Markdown
95 lines
3.3 KiB
Markdown
|
# @push.rocks/smartdns/client
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
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 |
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
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[]`:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
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:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
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
|