@push.rocks/smartdns 7.0.2 → 7.4.0

package/readme.md

@@ -1,392 +1,813 @@
 # @push.rocks/smartdns
 
-A TypeScript library for smart DNS methods, supporting various DNS records and providers.
+A robust TypeScript library providing advanced DNS management and resolution capabilities including support for DNSSEC, custom DNS servers, and integration with various DNS providers.
 
 ## Install
 
-To install `@push.rocks/smartdns`, use the following command with npm:
+To install `@push.rocks/smartdns`, use the following command with pnpm:
 
 ```bash
-npm install @push.rocks/smartdns --save
+pnpm install @push.rocks/smartdns --save
 ```
 
-Or with `yarn`:
+Or with npm:
 
 ```bash
-yarn add @push.rocks/smartdns
+npm install @push.rocks/smartdns --save
 ```
 
 Make sure you have a TypeScript environment set up to utilize the library effectively.
 
 ## Usage
 
-`@push.rocks/smartdns` is a comprehensive library aimed at facilitating smart DNS operations, leveraging TypeScript for enhanced development experience. This section aims to cover several real-world scenarios demonstrating the library's capabilities, from basic DNS lookups to more advanced DNS management tasks.
+`@push.rocks/smartdns` is a comprehensive library that provides both DNS client and server capabilities, leveraging TypeScript for enhanced development experience. The library is organized into three modules:
+
+- **Client Module** (`@push.rocks/smartdns/client`): DNS resolution and record queries
+- **Server Module** (`@push.rocks/smartdns/server`): Full DNS server implementation with DNSSEC
+- **Main Module** (`@push.rocks/smartdns`): Convenience exports for both client and server
 
 ### Getting Started
 
-First, ensure you import the module into your TypeScript project:
+You can import the modules based on your needs:
 
 ```typescript
-import { Smartdns } from '@push.rocks/smartdns';
+// For DNS client operations
+import { Smartdns } from '@push.rocks/smartdns/client';
+
+// For DNS server operations
+import { DnsServer } from '@push.rocks/smartdns/server';
+
+// Or import from the main module (note the different syntax)
+import { dnsClientMod, dnsServerMod } from '@push.rocks/smartdns';
+const dnsClient = new dnsClientMod.Smartdns({});
+const dnsServer = new dnsServerMod.DnsServer({ /* options */ });
 ```
 
-### Basic DNS Record Lookup
+### DNS Client Operations
 
-Often, the need arises to fetch various DNS records for a domain. `@push.rocks/smartdns` simplifies this by providing intuitive methods. A DNS record is essentially a map from a domain name to information about that domain, such as its IP address, mail exchange server, etc.
+The DNS client (`Smartdns` class) provides methods to query various DNS record types using DNS-over-HTTPS (DoH) with Cloudflare as the primary provider, with fallback to Node.js DNS resolver.
 
 #### Fetching A Records
 
-To fetch an "A" record for a domain, which resolves the domain to an IPv4 address, use the following approach:
+To fetch "A" records (IPv4 addresses) for a domain:
 
 ```typescript
-import { Smartdns } from '@push.rocks/smartdns';
+import { Smartdns } from '@push.rocks/smartdns/client';
 
-const dnsManager = new Smartdns({});
-const aRecords = await dnsManager.getRecordsA('example.com');
+const dnsClient = new Smartdns({});
+const aRecords = await dnsClient.getRecordsA('example.com');
 console.log(aRecords);
+// Output: [{ name: 'example.com', type: 'A', dnsSecEnabled: false, value: '93.184.215.14' }]
 ```
 
-This will return an array of records that include the IPv4 addresses mapped to the domain `example.com`.
-
 #### Fetching AAAA Records
 
-For resolving a domain to an IPv6 address, you can fetch "AAAA" records in a similar manner:
+For resolving a domain to IPv6 addresses:
 
 ```typescript
-const aaaaRecords = await dnsManager.getRecordsAAAA('example.com');
+const aaaaRecords = await dnsClient.getRecordsAAAA('example.com');
 console.log(aaaaRecords);
+// Output: [{ name: 'example.com', type: 'AAAA', dnsSecEnabled: false, value: '2606:2800:21f:cb07:6820:80da:af6b:8b2c' }]
 ```
 
-These queries are quite common where IPv6 addresses have been prevalent due to the scarcity of IPv4 addresses.
-
 #### Fetching TXT Records
 
-TXT records store arbitrary text data associated with a domain. They are often used to hold information such as SPF records for email validation or Google site verification token.
+TXT records store text data, commonly used for domain verification, SPF records, and other metadata:
 
 ```typescript
-const txtRecords = await dnsManager.getRecordsTxt('example.com');
+const txtRecords = await dnsClient.getRecordsTxt('example.com');
 console.log(txtRecords);
+// Output: [{ name: 'example.com', type: 'TXT', dnsSecEnabled: false, value: 'v=spf1 -all' }]
 ```
 
-TXT records have increasingly become significant with the growth of security features and integrations that require domain verification.
+#### Other Record Types
 
-### Advanced DNS Management
+The client supports various other DNS record types:
 
-The `@push.rocks/smartdns` doesn't just stop at querying— it offers more advanced DNS management utilities, which are crucial for real-world applications involving DNS operations.
+```typescript
+// MX records for mail servers
+const mxRecords = await dnsClient.getRecords('example.com', 'MX');
+
+// NS records for nameservers
+const nsRecords = await dnsClient.getNameServers('example.com');
+
+// Generic query method with retry support
+const records = await dnsClient.getRecords('example.com', 'CNAME', { retryCount: 3 });
+```
+
+### Advanced DNS Features
 
 #### Checking DNS Propagation
 
-When changing DNS records, ensuring that the new records have propagated fully is crucial. `@push.rocks/smartdns` facilitates this with a method to check if a DNS record is available globally. This can be critical for ensuring that users worldwide are able to access your updated records in a consistent manner.
+The client provides a powerful method to verify DNS propagation globally, essential when making DNS changes:
 
 ```typescript
-const recordType = 'TXT'; // Record type: A, AAAA, CNAME, TXT etc.
-const expectedValue = 'your_expected_value';
-const isAvailable = await dnsManager.checkUntilAvailable('example.com', recordType, expectedValue);
+// Check if a specific DNS record has propagated
+const recordType = 'TXT';
+const expectedValue = 'verification=abc123';
+
+const isAvailable = await dnsClient.checkUntilAvailable(
+  'example.com',
+  recordType,
+  expectedValue,
+  50,    // Number of check cycles (default: 50)
+  500    // Interval between checks in ms (default: 500)
+);
 
 if (isAvailable) {
-  console.log('Record propagated successfully.');
+  console.log('DNS record has propagated successfully!');
 } else {
-  console.log('Record propagation failed or timed out.');
+  console.log('DNS propagation timeout - record not found.');
 }
 ```
 
-This method repeatedly queries DNS servers until the expected DNS record appears, making sure that the changes made are visible globally.
+#### Configuring System DNS Provider
 
-### Leveraging DNS for Application Logic
+You can configure Node.js to use a specific DNS provider for all DNS queries:
 
-DNS records can function beyond their typical usage of domain-to-IP resolution. They can be extremely useful in application logic such as feature flagging or environment-specific configurations.
+```typescript
+// Import the standalone function
+import { makeNodeProcessUseDnsProvider } from '@push.rocks/smartdns/client';
+
+// Use Cloudflare DNS for all Node.js DNS operations
+makeNodeProcessUseDnsProvider('cloudflare');
 
-#### Example: Feature Flagging via TXT Records
+// Or use Google DNS
+makeNodeProcessUseDnsProvider('google');
+```
 
-One such advanced use case is using TXT records for enabling or disabling features dynamically without needing to redeploy or change the actual application code:
+### Real-World Use Cases
+
+#### DNS-Based Feature Flagging
+
+Use TXT records for dynamic feature toggles without redeployment:
 
 ```typescript
-const txtRecords = await dnsManager.getRecordsTxt('features.example.com');
-const featureFlags = txtRecords.reduce((acc, record) => {
-  const [flag, isEnabled] = record.value.split('=');
-  acc[flag] = isEnabled === 'true';
-  return acc;
-}, {});
-
-if (featureFlags['NewFeature']) {
-  // Logic to enable the new feature
-  console.log('New Feature enabled');
+const txtRecords = await dnsClient.getRecordsTxt('features.example.com');
+const featureFlags = {};
+
+txtRecords.forEach(record => {
+  // Parse TXT records like "feature-dark-mode=true"
+  const [feature, enabled] = record.value.split('=');
+  featureFlags[feature] = enabled === 'true';
+});
+
+if (featureFlags['feature-dark-mode']) {
+  console.log('Dark mode is enabled!');
 }
 ```
 
-This approach enables applications to be more flexible and responsive to business needs as feature toggles can be managed through DNS.
+#### Service Discovery
+
+Use DNS for service endpoint discovery:
+
+```typescript
+// Discover API endpoints via TXT records
+const serviceRecords = await dnsClient.getRecordsTxt('_services.example.com');
+
+// Discover mail servers
+const mxRecords = await dnsClient.getRecords('example.com', 'MX');
+const primaryMailServer = mxRecords
+  .sort((a, b) => a.priority - b.priority)[0]?.exchange;
+```
 
 ### DNS Server Implementation
 
-`@push.rocks/smartdns` includes powerful features that allow you to implement your very own DNS server, complete with UDP and HTTPS protocols support and DNSSEC compliance.
+The `DnsServer` class provides a full-featured DNS server with support for UDP, DNS-over-HTTPS (DoH), DNSSEC, and automatic SSL certificate management via Let's Encrypt.
 
-#### Basic DNS Server Example
+#### Basic DNS Server Setup
 
-Implementing a DNS server involves setting it up to respond to various DNS queries. Here's how you can set up a basic DNS server using UDP and HTTPS protocols:
+Create a simple DNS server that responds to queries:
 
 ```typescript
-import { DnsServer } from '@push.rocks/smartdns';
+import { DnsServer } from '@push.rocks/smartdns/server';
 
 const dnsServer = new DnsServer({
+  udpPort: 5333,      // UDP port for DNS queries
+  httpsPort: 8443,    // HTTPS port for DNS-over-HTTPS
+  httpsKey: 'path/to/key.pem',   // Required for HTTPS
+  httpsCert: 'path/to/cert.pem', // Required for HTTPS
+  dnssecZone: 'example.com'      // Optional: enable DNSSEC for this zone
+});
+
+// For enhanced security, bind to specific interfaces
+const secureServer = new DnsServer({
+  udpPort: 53,
+  httpsPort: 443,
   httpsKey: 'path/to/key.pem',
   httpsCert: 'path/to/cert.pem',
-  httpsPort: 443,
-  udpPort: 53,
   dnssecZone: 'example.com',
+  udpBindInterface: '127.0.0.1',    // Bind UDP to localhost only
+  httpsBindInterface: '127.0.0.1'   // Bind HTTPS to localhost only
 });
 
+// Register a handler for all subdomains of example.com
 dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
   name: question.name,
   type: 'A',
   class: 'IN',
   ttl: 300,
-  data: '127.0.0.1',
+  data: '192.168.1.100',
 }));
 
-dnsServer.start().then(() => console.log('DNS Server started'));
-```
+// Register a handler for TXT records
+dnsServer.registerHandler('example.com', ['TXT'], (question) => ({
+  name: question.name,
+  type: 'TXT',
+  class: 'IN',
+  ttl: 300,
+  data: 'v=spf1 include:_spf.example.com ~all',
+}));
 
-This sets up a basic DNS server responding to A records for the domain `example.com` and mirrors the common structure used in production applications.
+// Start the server
+await dnsServer.start();
+console.log('DNS Server started!');
+```
 
 ### DNSSEC Support
 
-DNS Security Extensions (DNSSEC) adds an additional layer of security to DNS, protecting against various types of attacks. With `@push.rocks/smartdns`, setting up a DNS server with DNSSEC is straightforward.
-
-#### DNSSEC Configuration
-
-To configure DNSSEC for your DNS server, you’ll need to establish DNSSEC parameters including zone signatures and enabling key management. This setup ensures that DNS records are signed and can be verified for authenticity.
+The DNS server includes comprehensive DNSSEC support with automatic key generation and record signing:
 
 ```typescript
-import { DnsServer } from '@push.rocks/smartdns';
+import { DnsServer } from '@push.rocks/smartdns/server';
 
 const dnsServer = new DnsServer({
-  httpsKey: 'path/to/key.pem',
-  httpsCert: 'path/to/cert.pem',
-  httpsPort: 443,
   udpPort: 53,
-  dnssecZone: 'example.com',
+  httpsPort: 443,
+  dnssecZone: 'secure.example.com',  // Enable DNSSEC for this zone
 });
 
-dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
+// The server automatically:
+// 1. Generates DNSKEY records with ECDSA (algorithm 13)
+// 2. Creates DS records for parent zone delegation
+// 3. Signs all responses with RRSIG records
+// 4. Provides NSEC records for authenticated denial of existence
+
+// Register your handlers as normal - DNSSEC signing is automatic
+dnsServer.registerHandler('secure.example.com', ['A'], (question) => ({
   name: question.name,
   type: 'A',
   class: 'IN',
   ttl: 300,
-  data: '127.0.0.1',
+  data: '192.168.1.1',
 }));
 
-dnsServer.start().then(() => console.log('DNS Server with DNSSEC started'));
+await dnsServer.start();
+
+// Query for DNSSEC records
+import { Smartdns } from '@push.rocks/smartdns/client';
+const client = new Smartdns({});
+const dnskeyRecords = await client.getRecords('secure.example.com', 'DNSKEY');
+const dsRecords = await client.getRecords('secure.example.com', 'DS');
 ```
 
-### Handling DNS Queries Over Different Protocols
+#### Supported DNSSEC Algorithms
 
-The library supports handling DNS queries over UDP and HTTPS. This functionality allows for the flexible use and management of DNS inquiries and resolves, accommodating various protocol needs.
+The server supports multiple DNSSEC algorithms:
+- **ECDSAP256SHA256** (Algorithm 13) - Default, using P-256 curve
+- **ED25519** (Algorithm 15) - Modern elliptic curve algorithm
+- **RSASHA256** (Algorithm 8) - RSA-based signatures
 
-#### Handling UDP Queries
+### Let's Encrypt Integration
 
-UDP is the traditional DNS protocol used for quick, non-persistent queries. Here’s how you can set up a DNS server to respond to UDP queries:
+The DNS server includes built-in Let's Encrypt support for automatic SSL certificate management:
 
 ```typescript
-import { DnsServer } from '@push.rocks/smartdns';
-import dgram from 'dgram';
+import { DnsServer } from '@push.rocks/smartdns/server';
 
 const dnsServer = new DnsServer({
   udpPort: 53,
   httpsPort: 443,
+  httpsKey: '/path/to/letsencrypt/key.pem',   // Will be auto-generated
+  httpsCert: '/path/to/letsencrypt/cert.pem', // Will be auto-generated
 });
 
-dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
-  name: question.name,
-  type: 'A',
-  class: 'IN',
-  ttl: 300,
-  data: '127.0.0.1',
-}));
+// Retrieve Let's Encrypt certificate for your domain
+const result = await dnsServer.retrieveSslCertificate(
+  ['secure.example.com', 'www.secure.example.com'],
+  {
+    email: 'admin@example.com',
+    staging: false,  // Use production Let's Encrypt
+    certDir: './certs'
+  }
+);
 
-dnsServer.start().then(() => {
-  console.log('UDP DNS Server started on port', dnsServer.getOptions().udpPort);
+if (result.success) {
+  console.log('Certificate retrieved successfully!');
+}
+
+// The server automatically:
+// 1. Handles ACME DNS-01 challenges
+// 2. Creates temporary TXT records for domain validation  
+// 3. Retrieves and installs the certificate
+// 4. Restarts the HTTPS server with the new certificate
+
+await dnsServer.start();
+console.log('DNS Server with Let\'s Encrypt SSL started!');
+```
+
+### Manual Socket Handling
+
+The DNS server supports manual socket handling for advanced use cases like clustering, load balancing, and custom transport implementations. You can control UDP and HTTPS socket handling independently.
+
+#### Configuration Options
+
+```typescript
+export interface IDnsServerOptions {
+  // ... standard options ...
+  manualUdpMode?: boolean;    // Handle UDP sockets manually
+  manualHttpsMode?: boolean;  // Handle HTTPS sockets manually
+}
+```
+
+#### Basic Manual Socket Usage
+
+```typescript
+import { DnsServer } from '@push.rocks/smartdns/server';
+import * as dgram from 'dgram';
+import * as net from 'net';
+
+// Create server with manual UDP mode
+const dnsServer = new DnsServer({
+  httpsKey: '...',
+  httpsCert: '...',
+  httpsPort: 853,
+  udpPort: 53,
+  dnssecZone: 'example.com',
+  manualUdpMode: true  // UDP manual, HTTPS automatic
+});
+
+await dnsServer.start(); // HTTPS binds, UDP doesn't
+
+// Create your own UDP socket
+const udpSocket = dgram.createSocket('udp4');
+
+// Handle incoming UDP messages
+udpSocket.on('message', (msg, rinfo) => {
+  dnsServer.handleUdpMessage(msg, rinfo, (response, responseRinfo) => {
+    // Send response using your socket
+    udpSocket.send(response, responseRinfo.port, responseRinfo.address);
+  });
+});
+
+// Bind to custom port or multiple interfaces
+udpSocket.bind(5353, '0.0.0.0');
+```
+
+#### Manual HTTPS Socket Handling
+
+```typescript
+// Create server with manual HTTPS mode
+const dnsServer = new DnsServer({
+  httpsKey: '...',
+  httpsCert: '...',
+  httpsPort: 853,
+  udpPort: 53,
+  dnssecZone: 'example.com',
+  manualHttpsMode: true  // HTTPS manual, UDP automatic
+});
+
+await dnsServer.start(); // UDP binds, HTTPS doesn't
+
+// Create your own TCP server
+const tcpServer = net.createServer((socket) => {
+  // Pass TCP sockets to DNS server
+  dnsServer.handleHttpsSocket(socket);
 });
 
-const client = dgram.createSocket('udp4');
+tcpServer.listen(8853, '0.0.0.0');
+```
+
+#### Full Manual Mode
 
-client.on('message', (msg, rinfo) => {
-  console.log(`Received ${msg} from ${rinfo.address}:${rinfo.port}`);
+Control both protocols manually for complete flexibility:
+
+```typescript
+const dnsServer = new DnsServer({
+  httpsKey: '...',
+  httpsCert: '...',
+  httpsPort: 853,
+  udpPort: 53,
+  dnssecZone: 'example.com',
+  manualUdpMode: true,
+  manualHttpsMode: true
 });
 
-client.send(Buffer.from('example DNS query'), dnsServer.getOptions().udpPort, 'localhost');
+await dnsServer.start(); // Neither protocol binds
+
+// Set up your own socket handling for both protocols
+// Perfect for custom routing, load balancing, or clustering
+```
+
+#### Advanced Use Cases
+
+##### Load Balancing Across Multiple UDP Sockets
+
+```typescript
+// Create multiple UDP sockets for different CPU cores
+const sockets = [];
+const numCPUs = require('os').cpus().length;
+
+for (let i = 0; i < numCPUs; i++) {
+  const socket = dgram.createSocket({ 
+    type: 'udp4', 
+    reuseAddr: true  // Allow multiple sockets on same port
+  });
+  
+  socket.on('message', (msg, rinfo) => {
+    dnsServer.handleUdpMessage(msg, rinfo, (response, rinfo) => {
+      socket.send(response, rinfo.port, rinfo.address);
+    });
+  });
+  
+  socket.bind(53);
+  sockets.push(socket);
+}
 ```
 
-This segment of code creates a UDP server that listens for incoming DNS requests and responds accordingly.
+##### Clustering with Worker Processes
 
-#### Handling HTTPS Queries
+```typescript
+import cluster from 'cluster';
+import { DnsServer } from '@push.rocks/smartdns/server';
+
+if (cluster.isPrimary) {
+  // Master process accepts connections
+  const server = net.createServer({ pauseOnConnect: true });
+  
+  // Distribute connections to workers
+  server.on('connection', (socket) => {
+    const worker = getNextWorker(); // Round-robin or custom logic
+    worker.send('socket', socket);
+  });
+  
+  server.listen(853);
+} else {
+  // Worker process handles DNS
+  const dnsServer = new DnsServer({
+    httpsKey: '...',
+    httpsCert: '...',
+    httpsPort: 853,
+    udpPort: 53,
+    dnssecZone: 'example.com',
+    manualHttpsMode: true
+  });
+  
+  process.on('message', (msg, socket) => {
+    if (msg === 'socket') {
+      dnsServer.handleHttpsSocket(socket);
+    }
+  });
+  
+  await dnsServer.start();
+}
+```
 
-DNS over HTTPS (DoH) offers a heightened level of privacy and security, where DNS queries are transmitted over HTTPS to prevent eavesdropping and man-in-the-middle attacks.
+##### Custom Transport Protocol
 
 ```typescript
-import { DnsServer } from '@push.rocks/smartdns';
-import https from 'https';
-import fs from 'fs';
+// Use DNS server with custom transport (e.g., WebSocket)
+import WebSocket from 'ws';
 
+const wss = new WebSocket.Server({ port: 8080 });
 const dnsServer = new DnsServer({
-  httpsKey: fs.readFileSync('path/to/key.pem'),
-  httpsCert: fs.readFileSync('path/to/cert.pem'),
-  httpsPort: 443,
+  httpsKey: '...',
+  httpsCert: '...',
+  httpsPort: 853,
   udpPort: 53,
   dnssecZone: 'example.com',
+  manualUdpMode: true,
+  manualHttpsMode: true
 });
 
-dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
+await dnsServer.start();
+
+wss.on('connection', (ws) => {
+  ws.on('message', (data) => {
+    // Process DNS query from WebSocket
+    const response = dnsServer.processRawDnsPacket(Buffer.from(data));
+    ws.send(response);
+  });
+});
+```
+
+##### Multi-Interface Binding
+
+```typescript
+// Bind to multiple network interfaces manually
+const interfaces = [
+  { address: '192.168.1.100', type: 'udp4' },
+  { address: '10.0.0.50', type: 'udp4' },
+  { address: '::1', type: 'udp6' }
+];
+
+interfaces.forEach(({ address, type }) => {
+  const socket = dgram.createSocket(type);
+  
+  socket.on('message', (msg, rinfo) => {
+    console.log(`Query received on ${address}`);
+    dnsServer.handleUdpMessage(msg, rinfo, (response, rinfo) => {
+      socket.send(response, rinfo.port, rinfo.address);
+    });
+  });
+  
+  socket.bind(53, address);
+});
+```
+
+### Handling Different Protocols
+
+#### UDP DNS Server
+
+Traditional DNS queries over UDP (port 53):
+
+```typescript
+import { DnsServer } from '@push.rocks/smartdns/server';
+import * as plugins from '@push.rocks/smartdns/server/plugins';
+
+const dnsServer = new DnsServer({
+  udpPort: 5353,  // Using alternate port for testing
+  httpsPort: 8443,
+  httpsKey: fs.readFileSync('/path/to/key.pem', 'utf8'),
+  httpsCert: fs.readFileSync('/path/to/cert.pem', 'utf8'),
+  dnssecZone: 'test.local' // Optional
+});
+
+// The UDP server automatically handles DNS packet parsing and encoding
+dnsServer.registerHandler('test.local', ['A'], (question) => ({
   name: question.name,
-  type: 'A',
+  type: 'A', 
   class: 'IN',
-  ttl: 300,
+  ttl: 60,
   data: '127.0.0.1',
 }));
 
-dnsServer.start().then(() => console.log('HTTPS DNS Server started'));
+await dnsServer.start();
 
-const client = https.request({
-  hostname: 'localhost',
-  port: 443,
-  path: '/dns-query',
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/dns-message'
-  }
-}, (res) => {
-  res.on('data', (d) => {
-    process.stdout.write(d);
-  });
-});
+// Test with dig or nslookup:
+// dig @localhost -p 5353 test.local
+```
+
+#### DNS-over-HTTPS (DoH) Server
+
+Provide encrypted DNS queries over HTTPS:
+
+```typescript
+import { DnsServer } from '@push.rocks/smartdns/server';
+import * as fs from 'fs';
 
-client.on('error', (e) => {
-  console.error(e);
+const dnsServer = new DnsServer({
+  httpsPort: 8443,
+  httpsKey: fs.readFileSync('/path/to/key.pem', 'utf8'),
+  httpsCert: fs.readFileSync('/path/to/cert.pem', 'utf8'),
 });
 
-client.write(Buffer.from('example DNS query'));
-client.end();
-```
+// The HTTPS server automatically handles:
+// - DNS wire format in POST body
+// - Proper Content-Type headers (application/dns-message)
+// - Base64url encoding for GET requests
+
+dnsServer.registerHandler('secure.local', ['A'], (question) => ({
+  name: question.name,
+  type: 'A',
+  class: 'IN', 
+  ttl: 300,
+  data: '10.0.0.1',
+}));
 
-This ensures that DNS requests can be securely transmitted over the web, maintaining privacy for the clients querying the DNS server.
+await dnsServer.start();
 
-### Testing
+// Test with curl:
+// curl -H "Content-Type: application/dns-message" \
+//      --data-binary @query.bin \
+//      https://localhost:8443/dns-query
+```
 
-Like any crucial application component, DNS servers require thorough testing to ensure reliability and correctness in different scenarios. Here we use TAP (Test Anything Protocol) to test various functionalities.
+### Interface Binding
 
-#### DNS Server Tests
+For enhanced security and network isolation, you can bind the DNS server to specific network interfaces instead of all available interfaces.
 
-`@push.rocks/smartdns` integrates seamlessly with TAP, allowing for comprehensive testing of server functionalities.
+#### Localhost-Only Binding
 
-Here's an example of how you might set up tests for your DNS server:
+Bind to localhost for development or local-only DNS services:
 
 ```typescript
-import { expect, tap } from '@push.rocks/tapbundle';
+const localServer = new DnsServer({
+  udpPort: 5353,
+  httpsPort: 8443,
+  httpsKey: cert.key,
+  httpsCert: cert.cert,
+  dnssecZone: 'local.test',
+  udpBindInterface: '127.0.0.1',     // IPv4 localhost
+  httpsBindInterface: '127.0.0.1'
+});
 
-import { DnsServer } from '@push.rocks/smartdns';
+// Or use IPv6 localhost
+const ipv6LocalServer = new DnsServer({
+  // ... other options
+  udpBindInterface: '::1',           // IPv6 localhost
+  httpsBindInterface: '::1'
+});
+```
 
-let dnsServer: DnsServer;
+#### Specific Interface Binding
 
-tap.test('should create an instance of DnsServer', async () => {
-  dnsServer = new DnsServer({
-    httpsKey: 'path/to/key.pem',
-    httpsCert: 'path/to/cert.pem',
-    httpsPort: 443,
-    udpPort: 53,
-    dnssecZone: 'example.com',
-  });
-  expect(dnsServer).toBeInstanceOf(DnsServer);
-});
+Bind to a specific network interface in multi-homed servers:
 
-tap.test('should start the server', async () => {
-  await dnsServer.start();
-  expect(dnsServer.isRunning()).toBeTrue();
+```typescript
+const interfaceServer = new DnsServer({
+  udpPort: 53,
+  httpsPort: 443,
+  httpsKey: cert.key,
+  httpsCert: cert.cert,
+  dnssecZone: 'example.com',
+  udpBindInterface: '192.168.1.100',  // Specific internal interface
+  httpsBindInterface: '10.0.0.50'    // Different interface for HTTPS
 });
+```
+
+#### Security Considerations
+
+- **Default Behavior**: If not specified, servers bind to all interfaces (`0.0.0.0`)
+- **Localhost Binding**: Use `127.0.0.1` or `::1` for development and testing
+- **Production**: Consider binding to specific internal interfaces for security
+- **Validation**: Invalid IP addresses will throw an error during server startup
 
-tap.test('should add a DNS handler', async () => {
-  dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
+### Advanced Handler Patterns
+
+#### Pattern-Based Routing
+
+Use glob patterns for flexible domain matching:
+
+```typescript
+// Match all subdomains
+dnsServer.registerHandler('*.example.com', ['A'], (question) => {
+  // Extract subdomain
+  const subdomain = question.name.replace('.example.com', '');
+  
+  // Dynamic response based on subdomain
+  return {
     name: question.name,
     type: 'A',
     class: 'IN',
     ttl: 300,
-    data: '127.0.0.1',
-  }));
-
-  const response = dnsServer.processDnsRequest({
-    type: 'query',
-    id: 1,
-    flags: 0,
-    questions: [
-      {
-        name: 'test.example.com',
-        type: 'A',
-        class: 'IN',
-      },
-    ],
-    answers: [],
-  });
+    data: subdomain === 'api' ? '10.0.0.10' : '10.0.0.1',
+  };
+});
 
-  expect(response.answers[0]).toEqual({
-    name: 'test.example.com',
+// Match specific patterns
+dnsServer.registerHandler('db-*.service.local', ['A'], (question) => {
+  const instanceId = question.name.match(/db-(\d+)/)?.[1];
+  return {
+    name: question.name,
     type: 'A',
     class: 'IN',
-    ttl: 300,
-    data: '127.0.0.1',
-  });
+    ttl: 60,
+    data: `10.0.1.${instanceId}`,
+  };
 });
 
-tap.test('should query the server over HTTP', async () => {
-  const query = dnsPacket.encode({
-    type: 'query',
-    id: 2,
-    flags: dnsPacket.RECURSION_DESIRED,
-    questions: [
-      {
-        name: 'test.example.com',
-        type: 'A',
-        class: 'IN',
-      },
-    ],
-  });
+// Catch-all handler
+dnsServer.registerHandler('*', ['A'], (question) => ({
+  name: question.name,
+  type: 'A', 
+  class: 'IN',
+  ttl: 300,
+  data: '127.0.0.1',
+}));
+```
 
-  const response = await fetch('https://localhost:443/dns-query', {
-    method: 'POST',
-    body: query,
-    headers: {
-      'Content-Type': 'application/dns-message',
-    }
-  });
+### Testing
+
+The library uses `@git.zone/tstest` for testing. Here's an example of comprehensive tests:
+
+```typescript
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { Smartdns } from '@push.rocks/smartdns/client';
+import { DnsServer } from '@push.rocks/smartdns/server';
+
+// Test DNS Client
+tap.test('DNS Client - Query Records', async () => {
+  const dnsClient = new Smartdns({});
+  
+  // Test A record query
+  const aRecords = await dnsClient.getRecordsA('google.com');
+  expect(aRecords).toBeArray();
+  expect(aRecords[0]).toHaveProperty('type', 'A');
+  expect(aRecords[0].data).toMatch(/^\d+\.\d+\.\d+\.\d+$/);
+  
+  // Test TXT record query
+  const txtRecords = await dnsClient.getRecordsTxt('google.com');
+  expect(txtRecords).toBeArray();
+  expect(txtRecords[0]).toHaveProperty('type', 'TXT');
+});
 
-  expect(response.status).toEqual(200);
+// Test DNS Server
+let dnsServer: DnsServer;
 
-  const responseData = await response.arrayBuffer();
-  const dnsResponse = dnsPacket.decode(Buffer.from(responseData));
+tap.test('DNS Server - Setup and Start', async () => {
+  dnsServer = new DnsServer({
+    udpPort: 5353,
+    httpsPort: 8443,
+    httpsKey: 'test-key',   // Use test certificates
+    httpsCert: 'test-cert',
+    dnssecZone: 'test.local'
+  });
+  
+  expect(dnsServer).toBeInstanceOf(DnsServer);
+  await dnsServer.start();
+});
 
-  expect(dnsResponse.answers[0]).toEqual({
-    name: 'test.example.com',
+tap.test('DNS Server - Register Handlers', async () => {
+  // Register multiple handlers
+  dnsServer.registerHandler('test.local', ['A'], () => ({
+    name: 'test.local',
     type: 'A',
     class: 'IN',
     ttl: 300,
     data: '127.0.0.1',
+  }));
+  
+  dnsServer.registerHandler('*.test.local', ['A'], (question) => ({
+    name: question.name,
+    type: 'A', 
+    class: 'IN',
+    ttl: 60,
+    data: '127.0.0.2',
+  }));
+});
+
+tap.test('DNS Server - Query via UDP', async (tools) => {
+  const dnsPacket = (await import('dns-packet')).default;
+  const dgram = await import('dgram');
+  
+  const query = dnsPacket.encode({
+    type: 'query',
+    id: 1234,
+    questions: [{
+      type: 'A',
+      class: 'IN', 
+      name: 'test.local',
+    }],
   });
+  
+  const client = dgram.createSocket('udp4');
+  const done = tools.defer();
+  
+  client.on('message', (msg) => {
+    const response = dnsPacket.decode(msg);
+    expect(response.answers[0].data).toEqual('127.0.0.1');
+    client.close();
+    done.resolve();
+  });
+  
+  client.send(query, 5353, 'localhost'); // Use the port specified during server creation
+  await done.promise;
 });
 
-tap.test('should stop the server', async () => {
+tap.test('DNS Server - Cleanup', async () => {
   await dnsServer.stop();
-  expect(dnsServer.isRunning()).toBeFalse();
 });
 
+// Run tests
 await tap.start();
 ```
 
-The above tests ensure that the DNS server setup, query handling, and proper stopping of the server are all functioning as intended.
+### Best Practices
+
+1. **Port Selection**: Use non-privileged ports (>1024) during development
+2. **Handler Organization**: Group related handlers together
+3. **Error Handling**: Always handle DNS query errors gracefully
+4. **DNSSEC**: Enable DNSSEC for production deployments
+5. **Monitoring**: Log DNS queries for debugging and analytics
+6. **Rate Limiting**: Implement rate limiting for public DNS servers
+7. **Caching**: Respect TTL values and implement proper caching
+8. **Manual Sockets**: Use manual socket handling for clustering and load balancing
+
+### Performance Considerations
+
+- The DNS client uses HTTP keep-alive for connection reuse
+- The DNS server handles concurrent UDP and HTTPS requests efficiently
+- DNSSEC signatures are generated on-demand to reduce memory usage
+- Pattern matching uses caching for improved performance
+- Manual socket handling enables horizontal scaling across CPU cores
+
+### Security Considerations
 
-In a realistic production environment, additional tests would include edge cases such as malformed requests, large queries, concurrent access handling, and integration tests with various DNS resolvers. These tests ensure robustness and reliability of DNS services provided by the server.
+- Always use DNSSEC for authenticated responses
+- Enable DoH for encrypted DNS queries
+- Validate and sanitize all DNS inputs
+- Implement access controls for DNS server handlers
+- Use Let's Encrypt for automatic SSL certificate management
+- Never expose internal network information through DNS
+- Bind to specific interfaces in production environments
+- Use manual socket handling for custom security layers
 
-This comprehensive guide demonstrates how to implement, manage, and test a DNS server using `@push.rocks/smartdns`, making it an ideal tool for developers tasked with handling DNS management and setup in TypeScript projects. The library supports the full scope of DNS operations needed for modern applications, from basic record query to full-scale DNS server operations with advanced security extensions.
+This comprehensive library provides everything needed for both DNS client operations and running production-grade DNS servers with modern security features in TypeScript.
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license.md) file within this repository. 
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
@@ -401,4 +822,4 @@ Registered at District court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
 
-By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.