dnsts

A TypeScript DNS server library.

Features

- Full DNS protocol implementation (RFC 1035)
- UDP and TCP server support
- Flexible request handler with type-specific routing
- Support for common record types: A, AAAA, CNAME, MX, TXT, NS, SOA, SRV, PTR

Installation

``bash
npm install
`

Quick Start

`typescript
import {
UdpServer,
RequestHandler,
RecordType,
RecordClass,
ResourceRecord,
createARecord,
ResponseCode,
} from 'dnsts';

// Create a request handler
const handler = new RequestHandler();

// Handle A record queries
handler.onA((question) => {
if (question.name === 'example.com') {
const answer: ResourceRecord = {
name: question.name,
type: RecordType.A,
class: RecordClass.IN,
ttl: 300,
rdata: createARecord('93.184.216.34'),
};
return { answers: [answer] };
}
return { rcode: ResponseCode.NXDOMAIN };
});

// Create and start the server
const server = new UdpServer({
port: 53,
handler,
});

server.start();
`

Running the Example

`bash


Start the example server

npm run example

In another terminal, test with dig

dig @127.0.0.1 -p 5353 example.com A
dig @127.0.0.1 -p 5353 hello.local TXT
`

API

$3

The RequestHandler class routes DNS queries to appropriate handlers:

`typescript
const handler = new RequestHandler();

// Type-specific handlers
handler.onA(callback); // A records
handler.onAAAA(callback); // AAAA records
handler.onCNAME(callback); // CNAME records
handler.onMX(callback); // MX records
handler.onTXT(callback); // TXT records
handler.onNS(callback); // NS records
handler.onANY(callback); // ANY queries

// Generic handlers
handler.on(RecordType.SOA, callback); // Any record type
handler.onDefault(callback); // Fallback handler
handler.onAll(callback); // Wildcard (receives all queries)
`

$3

`typescript
type QueryHandler = (
question: Question,
message: Message,
clientInfo: ClientInfo
) => Promise | HandlerResult;

interface HandlerResult {
answers?: ResourceRecord[];
authorities?: ResourceRecord[];
additionals?: ResourceRecord[];
rcode?: ResponseCode;
}
`

$3

Helper functions to create record data:

`typescript
import {
createARecord,
createAAAARecord,
createNameRecord, // For CNAME, NS, PTR
createMXRecord,
createTXTRecord,
} from 'dnsts';

createARecord('192.168.1.1');
createAAAARecord('2001:db8::1');
createNameRecord('ns1.example.com');
createMXRecord(10, 'mail.example.com');
createTXTRecord(['v=spf1 include:example.com ~all']);
`

Project Structure

`
src/
├── protocol/ # DNS protocol implementation
│ ├── types.ts # Type definitions
│ ├── name.ts # Domain name encoding/decoding
│ ├── header.ts # DNS header parsing
│ ├── question.ts # Question section
│ ├── record.ts # Resource records
│ └── message.ts # Complete DNS messages
├── server/ # Server implementations
│ ├── udp.ts # UDP server
│ ├── tcp.ts # TCP server
│ └── handler.ts # Request routing
└── index.ts # Main exports
``

License

MIT