@0x5278/wiretap

wiretap

Low-level Node networking toolkit. Raw TCP and UDP, an HTTP/1.1 client, named instances and structured logging. Zero dependencies, just the Node core (net, tls, dgram, http, zlib).

High-level clients like axios, got and fetch hide the parts of the stack that matter when you care about the wire. wiretap keeps them visible: header order, raw sockets, timeouts you control. SOCKS, Tor and identity management are next; the plan is in docs/ROADMAP.md.

Install

npm install @0x5278/wiretap

Quick start

const wiretap = require('@0x5278/wiretap');

// an instance carries headers and a named log scope
const api = wiretap.wiretap({
  name: 'api',
  headers: { 'x-api-key': 'secret' },
});

const res = await api.get('https://api.example.com/data');
console.log(res.status, res.body.toString());

// stateless client when you do not want instance semantics
const { HttpClient } = wiretap;
const res2 = await new HttpClient().post('https://api.example.com/thing', { a: 1 });

Responses resolve for any status code. Transport failures reject, with code set (ECONNREFUSED, ETIMEDOUT, ABORT_ERR).

Low level

const { TcpSocket, UdpSocket } = require('@0x5278/wiretap');

const sock = new TcpSocket({ host: 'example.com', port: 80, idleTimeout: 30000 });
sock.on('data', (chunk) => console.log(chunk.toString()));
await sock.connect();
sock.write('GET / HTTP/1.1\r\nHost: example.com\r\n\r\n');

TLS sockets work the same way, pass tls options to the constructor for a custom CA, SNI override or stricter verification.

API

HTTP request options: url, method, headers (object or flat [k, v, ...] array to preserve order), body (string, Buffer, stream, or object which becomes JSON), timeout, redirects, decompress, signal (AbortController).

Docs

• docs/ARCHITECTURE.md: layer layout and where modules land
• docs/ROADMAP.md: what ships when
• CONTRIBUTING.md: how to help

License

MIT, see LICENSE.