@gajanan_107/dns3 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,427 @@
+# @gajanan_107/dns3
+
+A DNS framework for Node.js that puts you in control of every step of DNS resolution.
+
+Most DNS packages resolve queries for you behind the scenes — you hand them a domain and they hand you an IP. **dns3 does not do that.** Instead, it gives you the raw tools to handle each step yourself: receive the packet, parse it, check your own database, check your own cache, forward to upstream if needed, parse the response, and send bytes back to the client.
+
+This means you will actually understand what happens when someone types `google.com` in their browser.
+
+---
+
+## Why dns3
+
+When you use a regular DNS library, you never see the packet. You never see the `id`, the `flags`, the `questions` section. You never understand why a response has to carry the same `id` as the request. You never see that what travels over the wire is just raw bytes — not JSON, not objects.
+
+dns3 exposes all of that. Every step is explicit. You write each step yourself. Your cache is yours. Your database is yours. dns3 only gives you the functions to move between raw bytes and structured data.
+
+---
+
+## Install
+
+```bash
+npm install @gajanan_107/dns3
+```
+
+---
+
+## How DNS actually works
+
+Before looking at code, understand what happens when a DNS query arrives:
+
+1. A client (browser, OS) sends a **raw UDP packet** to your server. That packet is just bytes.
+2. Inside those bytes is a **question**: *"What is the IP address of `google.com`?"*
+3. Your server checks if it already knows the answer — from a local database or a cache.
+4. If it does not know, it forwards the **original raw bytes** to an upstream DNS server like `8.8.8.8`.
+5. The upstream server sends back **raw bytes** containing the answer.
+6. Your server parses those bytes to read the answer, optionally stores it in cache, then sends bytes back to the original client.
+
+dns3 maps directly to these steps. Nothing is hidden.
+
+---
+
+## Quick start
+
+```js
+const dns3 = require('@gajanan_107/dns3');
+const { parseRequest, parseResponse, createResponseFromRequest, upstreamResponse } = dns3;
+
+const server = dns3.createServer();
+
+// Your own storage — use MongoDB, Redis, a plain object, anything
+const localdb = {
+    'myapp.local': { 'A': '192.168.1.10' },
+};
+const cache = {};
+
+server.handle('onmessage', async (msg, send) => {
+
+    // Step 1 — msg is raw bytes, parse it to see what's inside
+    const request = parseRequest(msg);
+    const { name, type } = request.questions[0];
+
+    // Step 2 — check your local database first
+    if (localdb[name]?.[type]) {
+        const response = createResponseFromRequest(request);
+        response.answers.push(localdb[name][type]);
+        return send(response);
+    }
+
+    // Step 3 — check your cache
+    if (cache[`${name}:${type}`]) {
+        const response = createResponseFromRequest(request);
+        response.answers.push(cache[`${name}:${type}`]);
+        return send(response);
+    }
+
+    // Step 4 — not found anywhere, forward the original raw bytes upstream
+    const rawUpstream = await upstreamResponse(msg);
+
+    // Step 5 — upstream replied with raw bytes, parse them to read the answers
+    const parsed = parseResponse(rawUpstream);
+    for (const record of parsed.answers) {
+        cache[`${name}:${type}`] = record;   // store in your cache for next time
+    }
+
+    // Step 6 — send the raw upstream bytes directly back to the client
+    send(rawUpstream);
+});
+
+server.handle('onerror', (err) => {
+    console.error('DNS error:', err.message);
+});
+
+server.listen(5353);
+```
+
+Test it:
+
+```bash
+dig @127.0.0.1 -p5353 myapp.local
+dig @127.0.0.1 -p5353 google.com
+```
+
+---
+
+## The request object
+
+When `parseRequest(msg)` is called, the raw bytes are parsed into a structured object that reflects the actual DNS packet format:
+
+```js
+{
+    id: 1432,               // unique ID — the response must carry this same ID
+    flags: {
+        raw:    256,        // the 2-byte flags field as it arrived on the wire
+        qr:     0,          // 0 = this is a query, 1 = this is a response
+        opcode: 0,          // 0 = standard query
+        aa:     0,          // authoritative answer
+        tc:     0,          // truncated (message was cut short)
+        rd:     1,          // recursion desired — client wants full resolution
+        ra:     0,          // recursion available — server supports recursion
+        z:      0,          // reserved, always 0
+        rcode:  0,          // response code — 0 = no error, 3 = NXDOMAIN
+    },
+    questions: [
+        { name: 'google.com', type: 'A', class: 1 }
+    ],
+    answers:    [],         // empty in a query, filled in a response
+    authority:  [],         // authoritative nameserver records
+    additional: [],         // additional records the sender included
+}
+```
+
+The `id` is the most important field to understand. When a client sends a DNS query, it assigns a random `id` to it. When your server sends a response back, that response **must carry the same `id`** — otherwise the client will discard it. This is exactly why `createResponseFromRequest` exists: it copies the `id` automatically.
+
+---
+
+## The response object
+
+`createResponseFromRequest(request)` returns a response shell that already has the correct `id` and `questions` copied from the request. You only need to fill in the `answers`:
+
+```js
+{
+    id: 1432,               // copied from request — do not change this
+    flags: {
+        qr:     1,          // 1 = this is a response
+        opcode: 0,          // copied from request
+        aa:     0,          // set to 1 if you are authoritative for this domain
+        tc:     0,          // set to 1 if the response was truncated
+        rd:     1,          // copied from request
+        ra:     1,          // 1 = this server supports recursion
+        z:      0,
+        rcode:  0,          // 0 = success, 3 = NXDOMAIN (domain does not exist)
+    },
+    questions: [...],       // copied from request
+    answers:   [],          // push your answer here
+}
+```
+
+You can change any `flags` field before calling `send`. For example to tell the client a domain does not exist:
+
+```js
+const response = createResponseFromRequest(request);
+response.flags.rcode = 3;   // 3 = NXDOMAIN
+send(response);
+```
+
+---
+
+## Pushing answers
+
+dns3 accepts two formats when pushing into `response.answers`.
+
+**Format 1 — just the data value.** dns3 fills in the rest from the question context:
+
+```js
+response.answers.push('192.168.1.10');              // A record
+response.answers.push('::1');                       // AAAA record
+response.answers.push('mail.myapp.local');          // CNAME or MX exchange
+```
+
+**Format 2 — a full record object.** Use this when pushing a record that came from `parseResponse` (it already has the full shape), or when you want to control `ttl`:
+
+```js
+response.answers.push({
+    name:  'google.com',
+    type:  'A',
+    class: 1,
+    ttl:   300,
+    data:  '142.250.64.100',
+});
+```
+
+When records come back from `parseResponse().answers`, they are already in Format 2 — so you can push them directly into `response.answers` or store them in your cache and push them later. Either way works.
+
+---
+
+## Supported record types
+
+| Type  | What it maps                          | Example data value                                      |
+|-------|---------------------------------------|---------------------------------------------------------|
+| A     | Domain → IPv4 address                 | `'192.168.1.10'`                                        |
+| AAAA  | Domain → IPv6 address                 | `'::1'`                                                 |
+| CNAME | Domain → another domain (alias)       | `'app.myapp.local'`                                     |
+| NS    | Domain → nameserver                   | `'ns1.myapp.local'`                                     |
+| MX    | Domain → mail server                  | `{ priority: 10, exchange: 'mail.myapp.local' }`        |
+| TXT   | Domain → text string(s)               | `'v=spf1 ~all'` or `['string1', 'string2']`             |
+| PTR   | Reverse IP → domain (reverse lookup)  | `'myhost.local'`                                        |
+| SOA   | Start of authority record             | `{ mname, rname, serial, refresh, retry, expire, minimum }` |
+
+The `type` field in `questions[0].type` will always be one of these strings — never a number. So your database keys can be readable strings like `'A'`, `'MX'`, `'TXT'` directly.
+
+---
+
+## Using with MongoDB
+
+```js
+server.handle('onmessage', async (msg, send) => {
+    const request = parseRequest(msg);
+    const { name, type } = request.questions[0];
+
+    // check MongoDB
+    const record = await db.collection('records').findOne({ name, type });
+    if (record) {
+        const response = createResponseFromRequest(request);
+        response.answers.push(record.data);
+        return send(response);
+    }
+
+    // forward upstream and cache in MongoDB
+    const rawUpstream = await upstreamResponse(msg);
+    const parsed = parseResponse(rawUpstream);
+    for (const answer of parsed.answers) {
+        await db.collection('cache').insertOne({
+            name:      answer.name,
+            type:      answer.type,
+            data:      answer.data,
+            expiresAt: new Date(Date.now() + answer.ttl * 1000),
+        });
+    }
+
+    send(rawUpstream);
+});
+```
+
+---
+
+## Using with Redis
+
+```js
+server.handle('onmessage', async (msg, send) => {
+    const request = parseRequest(msg);
+    const { name, type } = request.questions[0];
+
+    // check Redis
+    const cached = await redis.get(`${name}:${type}`);
+    if (cached) {
+        const response = createResponseFromRequest(request);
+        response.answers.push(JSON.parse(cached));
+        return send(response);
+    }
+
+    // forward upstream and cache in Redis
+    const rawUpstream = await upstreamResponse(msg);
+    const parsed = parseResponse(rawUpstream);
+    for (const answer of parsed.answers) {
+        await redis.set(
+            `${answer.name}:${answer.type}`,
+            JSON.stringify(answer),
+            { EX: answer.ttl }
+        );
+    }
+
+    send(rawUpstream);
+});
+```
+
+---
+
+## Forwarding upstream
+
+`upstreamResponse(msg)` takes the **original raw bytes** from the `onmessage` handler and sends them to an upstream DNS server. It returns raw bytes:
+
+```js
+// default upstream is 8.8.8.8 (Google)
+const rawUpstream = await upstreamResponse(msg);
+
+// use a different upstream
+const rawUpstream = await upstreamResponse(msg, '1.1.1.1');
+
+// custom port and timeout
+const rawUpstream = await upstreamResponse(msg, '1.1.1.1', 53, 3000);
+```
+
+The reason you pass `msg` (the raw bytes) and not the parsed request is important: the upstream server expects a DNS packet on the wire, not a JavaScript object. The raw bytes *are* that packet. Parsing and re-encoding would be unnecessary work — just forward the original bytes.
+
+---
+
+## Parsing upstream responses
+
+`parseResponse(rawUpstream)` parses what came back from upstream. It gives the same structure as `parseRequest`, but with `answers` filled in:
+
+```js
+const parsed = parseResponse(rawUpstream);
+
+console.log(parsed.answers);
+// [
+//   { name: 'google.com', type: 'A', class: 1, ttl: 300, data: '142.250.64.100' },
+//   { name: 'google.com', type: 'A', class: 1, ttl: 300, data: '142.250.64.102' },
+// ]
+```
+
+This is how you read what the upstream server found, so you can store it in your cache with the correct TTL before sending the response.
+
+---
+
+## API reference
+
+### `dns3.createServer()`
+
+Creates a DNS server. Returns a server object with `handle()` and `listen()`.
+
+### `server.handle(event, fn)`
+
+Registers a handler for a server event.
+
+- `'onmessage'` — fires for every incoming DNS query. Receives `(msg, send)`:
+  - `msg` — the raw incoming bytes (`Buffer`)
+  - `send(response)` — call this to reply. Accepts either a response object or a raw `Buffer`
+- `'onerror'` — fires when an error occurs. Receives `(err)`
+
+### `server.listen(port)`
+
+Binds the server to a UDP port and starts listening.
+
+### `parseRequest(msg)`
+
+Parses a raw incoming DNS query buffer. Returns a structured object with `id`, `flags`, `questions`, `answers`, `authority`, `additional`.
+
+### `parseResponse(buffer)`
+
+Parses a raw DNS response buffer — either from upstream or your own encoded response. Same structure as `parseRequest` but with `answers` filled in.
+
+### `createResponseFromRequest(request)`
+
+Creates a response shell from a parsed request. Copies `id`, `flags`, and `questions`. Sets response flags (`qr: 1`, `ra: 1`). Returns an object with an empty `answers` array ready to fill.
+
+### `upstreamResponse(msg, upstream, port, timeout)`
+
+Forwards raw bytes to an upstream DNS server and returns raw bytes.
+
+| Argument  | Default     | Description                    |
+|-----------|-------------|--------------------------------|
+| msg       | required    | Raw query Buffer               |
+| upstream  | `'8.8.8.8'` | Upstream server IP             |
+| port      | `53`        | Upstream server port           |
+| timeout   | `2000`      | Timeout in milliseconds        |
+
+### `getRecord(type)`
+
+Looks up a record type handler by name (`'A'`, `'MX'`, etc.) or numeric code. Returns `{ typeCode, typeName, encode, decode }` or `null`.
+
+### `registerRecord(handler)`
+
+Registers a custom record type handler. The handler must have `{ typeCode, typeName, encode, decode }`.
+
+```js
+const { registerRecord } = require('@gajanan_107/dns3');
+
+registerRecord({
+    typeCode: 99,
+    typeName: 'MY',
+    encode(data) { return Buffer.from(data); },
+    decode(buf, offset, rdlength) { return buf.toString('ascii', offset, offset + rdlength); },
+});
+```
+
+---
+
+## Project structure
+
+```
+dns3/
+├── index.js                    ← single entry point, all exports
+├── packet/
+│   ├── parser.js               ← parseRequest, parseResponse
+│   ├── encoder.js              ← encodeResponse (used internally by send)
+│   ├── header.js               ← 12-byte DNS header read/write
+│   ├── nameCodec.js            ← DNS wire-format name encoding/decoding
+│   └── records/
+│       └── index.js            ← A, AAAA, CNAME, NS, MX, TXT, PTR, SOA handlers
+├── resolver/
+│   ├── index.js                ← createResponseFromRequest
+│   └── forwarder.js            ← upstreamResponse
+└── server/
+    └── udpServer.js            ← createServer, handle, listen
+```
+
+---
+
+## DNS flags reference
+
+Every DNS packet carries a 16-bit flags field. dns3 breaks it into individual named bits so you can read or change each one:
+
+| Flag     | Bits | Meaning                                                              |
+|----------|------|----------------------------------------------------------------------|
+| `qr`     | 1    | `0` = query (request), `1` = response                               |
+| `opcode` | 4    | `0` = standard query. Other values are rare.                        |
+| `aa`     | 1    | Authoritative Answer — `1` if your server owns this domain          |
+| `tc`     | 1    | Truncated — `1` if the response was cut short (too large for UDP)   |
+| `rd`     | 1    | Recursion Desired — set by the client, copied to your response      |
+| `ra`     | 1    | Recursion Available — set to `1` to tell the client you can recurse |
+| `z`      | 1    | Reserved, always `0`                                                |
+| `rcode`  | 4    | `0` = success, `3` = NXDOMAIN (domain does not exist)              |
+
+---
+
+## RFC references
+
+This package implements the core DNS wire format as defined in:
+
+- [RFC 1034 — Domain Names: Concepts and Facilities](https://tools.ietf.org/html/rfc1034)
+- [RFC 1035 — Domain Names: Implementation and Specification](https://tools.ietf.org/html/rfc1035)
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gajanan_107/dns3",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "",
   "main": "index.js",
   "scripts": {