# @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