TCP, UDP & DNS

import net from 'node:net';
import readline from 'node:readline';
import { once } from 'node:events';

const catalog = new Map([
  ['9781098145187', 'Efficient Node.js'],
  ['9781098173135', 'Node.js Projects'],
]);

const server = net.createServer({ keepAlive: true, noDelay: true }, (socket) => {
  socket.setEncoding('utf8');
  socket.setTimeout(5_000, () => socket.destroy()); // idle timeout: we must end it ourselves
  socket.on('error', (err) => console.error('socket error:', err.code));

  // TCP is a byte stream: one write can arrive as many chunks, many writes as one.
  // readline re-assembles the stream into lines.
  const lines = readline.createInterface({ input: socket });
  lines.on('line', (isbn) => {
    socket.write(`${catalog.get(isbn.trim()) ?? 'not found'}\n`);
  });
});
server.maxConnections = 100; // beyond this, new connections are dropped and 'drop' is emitted
server.on('drop', ({ remoteAddress }) => console.warn('dropped', remoteAddress));

server.listen({ port: 0, host: '127.0.0.1' }); // port 0: the OS picks a free port
await once(server, 'listening');
const { port } = server.address();
console.log('listening on', server.address());

const client = net.createConnection({ port, host: '127.0.0.1' });
client.setEncoding('utf8');
client.write('978109814'); // a request split across two writes ...
client.write('5187\n9999999999999\n'); // ... and two requests in one write
const answers = [];
client.on('data', (chunk) => answers.push(chunk));
await new Promise((resolve) => setTimeout(resolve, 200));
console.log(JSON.stringify(answers.join('').split('\n').filter(Boolean)));

client.end();
await once(client, 'close');
await server[Symbol.asyncDispose](); // server.close() as a promise (stable since v24.2.0)

listening on { address: '127.0.0.1', family: 'IPv4', port: 63110 }
["Efficient Node.js","not found"]

import net from 'node:net';
import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import { once } from 'node:events';

// A private directory keeps the socket file away from other local users.
const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'bookshelf-'));
const endpoint = process.platform === 'win32'
  ? String.raw`\\.\pipe\bookshelf-control` // Windows: a named pipe in the flat pipe namespace
  : path.join(dir, 'control.sock'); // Unix: a Unix domain socket (a file system entry)

const server = net.createServer((socket) => {
  socket.end('{"status":"ok"}\n');
});
server.listen({ path: endpoint }); // readableAll/writableAll stay false: owner-only access
await once(server, 'listening');
console.log('listening on a', typeof server.address(), '->', path.basename(server.address()));

const client = net.createConnection({ path: endpoint });
client.setEncoding('utf8');
let reply = '';
for await (const chunk of client) reply += chunk;
console.log('reply:', reply.trim());

await server[Symbol.asyncDispose](); // close() unlinks the socket file it created
console.log('socket file still there?', await fs.access(endpoint).then(() => true, () => false));
await fs.rm(dir, { recursive: true });

listening on a string -> control.sock
reply: {"status":"ok"}
socket file still there? false

import net from 'node:net';
import { once } from 'node:events';

const deny = new net.BlockList();
deny.addAddress('203.0.113.7'); // one address
deny.addRange('198.51.100.10', '198.51.100.20'); // an inclusive range
deny.addSubnet('2001:db8::', 32, 'ipv6'); // a subnet (prefix length)

console.log(deny.check('198.51.100.15')); // true
console.log(deny.check('8.8.8.8')); // false
console.log(deny.check('2001:db8::1', 'ipv6')); // true: the family must be given for IPv6
console.log(deny.rules); // human-readable rule list

// Rules survive a round trip through JSON (Release candidate).
const copy = new net.BlockList();
copy.fromJSON(deny.toJSON());
console.log(copy.check('203.0.113.7'));

// Inbound: the server refuses matching peers before 'connection' fires.
const server = net.createServer({ blockList: deny }, (socket) => socket.end('hello\n'));
server.listen(0, '127.0.0.1');
await once(server, 'listening');

// Outbound: the client refuses to dial matching addresses (SSRF guard).
const loopbackDeny = new net.BlockList();
loopbackDeny.addSubnet('127.0.0.0', 8);
const blocked = net.connect({ port: server.address().port, host: '127.0.0.1', blockList: loopbackDeny });
const [err] = await once(blocked, 'error');
console.log(err.code); // ERR_IP_BLOCKED

await server[Symbol.asyncDispose]();

true
false
true
[
  'Address: IPv4 203.0.113.7',
  'Subnet: IPv6 2001:db8::/32',
  'Range: IPv4 198.51.100.10-198.51.100.20'
]
true
ERR_IP_BLOCKED

import net from 'node:net';

// Added in v26.8.0: a ready-made list of non-routable ranges.
const privateOnly = new net.BlockList();
privateOnly.addCIDRs(net.BlockList.PRIVATE_RANGES);
console.log(privateOnly.size);
console.log(privateOnly.check('10.1.2.3'), privateOnly.check('169.254.169.254'), privateOnly.check('93.184.216.34'));

8
true true false

import net from 'node:net';
import { once } from 'node:events';

console.log(net.getDefaultAutoSelectFamily(), net.getDefaultAutoSelectFamilyAttemptTimeout());

// Only IPv4 is listening; the IPv6 loopback address has nothing behind it.
const server = net.createServer((socket) => socket.end('hi\n'));
server.listen(0, '127.0.0.1');
await once(server, 'listening');

// A custom lookup stands in for a host name with an AAAA and an A record (all: true).
const lookup = (host, options, callback) =>
  setImmediate(callback, null, [{ address: '::1', family: 6 }, { address: '127.0.0.1', family: 4 }]);

const socket = net.connect({
  host: 'bookshelf.test', port: server.address().port,
  lookup,
  autoSelectFamily: true, // default since v20.0.0 / v18.18.0
  autoSelectFamilyAttemptTimeout: 250,
});
socket.on('connectionAttempt', (ip, port, family) => console.log('trying  ', ip, 'IPv' + family));
socket.on('connectionAttemptFailed', (ip, port, family, err) => console.log('failed  ', ip, err.code));
socket.on('connectionAttemptTimeout', (ip) => console.log('timeout ', ip));
socket.on('connect', () => console.log('connected to', socket.remoteAddress));
socket.resume();
await once(socket, 'close');

// With every attempt failing, a single AggregateError carries all the errors.
const dead = net.connect({ host: 'bookshelf.test', port: 1, lookup }); // port 1: nothing listens
const [err] = await once(dead, 'error');
console.log(err.constructor.name, err.errors.map((e) => `${e.address}:${e.code}`));
await server[Symbol.asyncDispose]();

true 500
trying   ::1 IPv6
failed   ::1 ECONNREFUSED
trying   127.0.0.1 IPv4
connected to 127.0.0.1
AggregateError [ '::1:ECONNREFUSED', '127.0.0.1:ECONNREFUSED' ]

import dgram from 'node:dgram';
import { once } from 'node:events';

// A tiny "metrics collector": fire-and-forget datagrams, no connection, no delivery guarantee.
const collector = dgram.createSocket('udp4');
collector.on('message', (msg, rinfo) => {
  // One datagram = one whole message; there is no framing problem as on TCP.
  console.log(`got ${JSON.stringify(msg.toString())} from ${rinfo.address} (${rinfo.size} bytes)`);
  collector.send('ack', rinfo.port, rinfo.address); // reply to the sender
});
collector.bind(0, '127.0.0.1'); // port 0: any free port
await once(collector, 'listening');
const { port } = collector.address();

const client = dgram.createSocket('udp4');
client.connect(port, '127.0.0.1'); // optional: fixes the peer, so send() needs no address
await once(client, 'connect');
client.send('books.opened:1|c'); // callback optional; errors surface as 'error' events
const [ack] = await once(client, 'message');
console.log('reply:', ack.toString());

// Datagrams larger than the path MTU may be fragmented or silently dropped:
// keep payloads small (the docs give 65,507 bytes as the hard IPv4 ceiling).
console.log('recv buffer bytes:', client.getRecvBufferSize() > 0);

await client[Symbol.asyncDispose]();
await collector[Symbol.asyncDispose]();

got "books.opened:1|c" from 127.0.0.1 (16 bytes)
reply: ack
recv buffer bytes: true

import dgram from 'node:dgram';

const socket = dgram.createSocket('udp4');
const addr = socket.bindSync({ address: '127.0.0.1', port: 0 }); // v26.4.0+: numeric IP only
console.log(addr.family, typeof addr.port);
socket.connectSync(addr.port, '127.0.0.1');
console.log(socket.remoteAddress().address);
await socket[Symbol.asyncDispose]();

IPv4 number
127.0.0.1

import dgram from 'node:dgram';
import net from 'node:net';
import { once } from 'node:events';

const deny = new net.BlockList();
deny.addSubnet('127.0.0.0', 8);
const rx = dgram.createSocket({ type: 'udp4', receiveBlockList: deny });
rx.on('message', () => console.log('received (should not)'));
rx.bind(0, '127.0.0.1');
await once(rx, 'listening');
const tx = dgram.createSocket('udp4');
tx.send('hi', rx.address().port, '127.0.0.1', () => console.log('sent'));
await new Promise((r) => setTimeout(r, 200));
await tx[Symbol.asyncDispose](); await rx[Symbol.asyncDispose]();

sent

import dgram from 'node:dgram';
import dns from 'node:dns/promises';
import { once } from 'node:events';

// A throw-away DNS server (answers every A query with 192.0.2.1) so the demo needs no internet.
const stub = dgram.createSocket('udp4');
stub.on('message', (query, rinfo) => {
  let end = 12; // the header is 12 bytes; the question follows
  while (query[end] !== 0) end += query[end] + 1; // walk the labels of the name
  end += 5; // root label + QTYPE + QCLASS
  const answer = Buffer.from([0xc0, 0x0c, 0, 1, 0, 1, 0, 0, 0, 60, 0, 4, 192, 0, 2, 1]);
  const header = Buffer.from(query.subarray(0, 12));
  header[2] = 0x81; header[3] = 0x80; // QR=1 (response), RD+RA
  header[6] = 0; header[7] = 1; // ANCOUNT = 1
  stub.send(Buffer.concat([header, query.subarray(12, end), answer]), rinfo.port, rinfo.address);
});
stub.bind(0, '127.0.0.1');
await once(stub, 'listening');

// lookup(): getaddrinfo(3) on the libuv thread pool; honours /etc/hosts, nsswitch.conf...
console.log('lookup  :', await dns.lookup('localhost'));

// resolve*(): a real DNS query over the network, never /etc/hosts, no thread pool.
const resolver = new dns.Resolver({ timeout: 1000, tries: 1 });
resolver.setServers([`127.0.0.1:${stub.address().port}`]); // this resolver only
console.log('resolve4:', await resolver.resolve4('localhost')); // the stub answers, not /etc/hosts
console.log('servers :', resolver.getServers());

stub.close();

lookup  : { address: '::1', family: 6 }
resolve4: [ '192.0.2.1' ]
servers : [ '127.0.0.1:51603' ]