wasmnet

Browser client for wasmnet — a networking proxy that bridges WASI socket APIs to real TCP/UDP/TLS via WebSocket.

Install

npm install wasmnet

Usage

import { WasmnetClient } from 'wasmnet';

const client = new WasmnetClient('ws://localhost:9000');
await client.ready();

// TCP
const id = await client.connect('example.com', 80);
client.onData(id, (data) => console.log(new TextDecoder().decode(data)));
client.send(id, 'GET / HTTP/1.1\r\nHost: example.com\r\n\r\n');

// TLS (server handles handshake)
const tls = await client.connectTls('api.example.com', 443);
client.onData(tls, (data) => console.log('tls:', data));

// UDP
const udp = await client.connectUdp('8.8.8.8', 53);
client.onDataFrom(udp.id, (data, addr, port) => console.log(data));
client.send(udp.id, packet);
client.sendTo(udp.id, '8.8.4.4', 53, packet); // different target

// DNS resolve
const ips = await client.resolve('example.com');

// Inbound TCP
const listener = await client.bind('0.0.0.0', 3000);
client.onAccept(listener.id, (connId, remote) => {
  client.onData(connId, (data) => client.send(connId, data));
});

// Cleanup
client.close(id);
client.disconnect();

Binary framing

Pass { binary: true } to skip JSON + base64 overhead on data frames. Raw bytes are sent directly in WebSocket binary messages.

const client = new WasmnetClient('ws://localhost:9000', { binary: true });

WebTransport

Pass { transport: 'webtransport' } to run the protocol over HTTP/3 / QUIC instead of WebSocket. The same API is used — only the transport changes. WebTransport is always binary-framed. The server must be started with --webtransport-port (see the server README).

const client = new WasmnetClient('https://localhost:9001', {
  transport: 'webtransport',
});
await client.ready();

Against a CA-trusted certificate this is all that's needed. For a self-signed dev certificate, pass the SHA-256 hash the server logs at startup so the browser will accept it:

const client = new WasmnetClient('https://localhost:9001', {
  transport: 'webtransport',
  serverCertificateHashes: [{ algorithm: 'sha-256', value: hashBytes }],
});

hashBytes is the 32-byte digest as a Uint8Array / ArrayBuffer (the server prints it as colon-separated hex).

API

new WasmnetClient(url: string, options?: ClientOptions)

Creates a client connecting to the wasmnet server. Options:

• binary?: boolean — use binary framing instead of JSON (WebSocket only; WebTransport is always binary).
• transport?: 'websocket' | 'webtransport' — defaults to 'websocket'.
• serverCertificateHashes?: { algorithm: 'sha-256', value: BufferSource }[] — for WebTransport against a self-signed certificate.

ready(): Promise<void>

Resolves when the underlying connection (WebSocket or WebTransport) is open. Always await this before issuing requests.

connect(addr: string, port: number): Promise<number>

Opens an outbound TCP connection. Returns the socket ID.

connectTls(addr: string, port: number): Promise<number>

Opens an outbound TCP connection with TLS. The wasmnet server handles the TLS handshake (using system CA roots). Returns the socket ID. Data sent/received through this socket is plaintext — encryption is handled transparently.

connectUdp(addr: string, port: number): Promise<{ id: number, port: number }>

Creates a UDP socket connected to the given address. Returns the socket ID and local port. Use send() to send to the connected address, or sendTo() for arbitrary targets.

bind(addr: string, port: number): Promise<{ id: number, port: number }>

Binds a TCP listener. Returns the listener ID and actual bound port.

listen(id: number, backlog?: number): void

Starts accepting connections on a bound listener.

send(id: number, data: string | Uint8Array | ArrayBuffer): void

Sends data on a TCP, TLS, or connected UDP socket.

sendTo(id: number, addr: string, port: number, data: string | Uint8Array | ArrayBuffer): void

Sends a UDP datagram to a specific target address, regardless of the socket's connected address.

resolve(name: string): Promise<string[]>

Resolves a hostname to an array of IP address strings (both IPv4 and IPv6).

close(id: number): void

Closes a socket or listener.

onData(id: number, callback: (data: Uint8Array) => void): void

Registers a data handler for TCP/TLS sockets. Any data buffered before the handler was set is flushed immediately.

onDataFrom(id: number, callback: (data: Uint8Array, addr: string, port: number) => void): void

Registers a data handler for UDP sockets. Each callback includes the source address and port.

onClose(id: number, callback: () => void): void

Registers a close handler.

onAccept(id: number, callback: (connId: number, remote: string) => void): void

Registers an accept handler for a TCP listener. connId is the new socket ID for the accepted connection.

disconnect(): void

Closes the underlying connection and all sockets.

License

MIT