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

npm install

Quick Start

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

# 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

RequestHandler

The RequestHandler class routes DNS queries to appropriate handlers:

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)

Handler Callback

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

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

RDATA Builders

Helper functions to create record data:

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